S32 SDK
lpi2c_driver.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2014 - 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016 NXP
4  * All rights reserved.
5  *
6  * THIS SOFTWARE IS PROVIDED BY NXP "AS IS" AND ANY EXPRESSED OR
7  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
8  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
9  * IN NO EVENT SHALL NXP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
10  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
11  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
12  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
13  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
14  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
15  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
16  * THE POSSIBILITY OF SUCH DAMAGE.
17  */
18 
19 #if !defined(LPI2C_DRIVER_H)
20 #define LPI2C_DRIVER_H
21 
22 #include <stddef.h>
23 #include <stdbool.h>
24 #include "device_registers.h"
25 #include "status.h"
26 #include "lpi2c_hal.h"
27 #include "edma_driver.h"
28 #include "osif.h"
29 
37 /*******************************************************************************
38  * Enumerations.
39  ******************************************************************************/
40 
42 /* Size of the master command queue. Worst case: 5 commands in High-Speed receive with 10-bit address:
43  START + master code, REP START + addr_1 + tx, addr_2, REP START + addr_1 + rx, receive command */
44 #define LPI2C_MASTER_CMD_QUEUE_SIZE 5U
45 
50 typedef enum
51 {
53  LPI2C_FAST_MODE = 0x1U,
54 #if(LPI2C_HAS_FAST_PLUS_MODE)
55  LPI2C_FASTPLUS_MODE = 0x2U,
56 #endif
57 #if(LPI2C_HAS_HIGH_SPEED_MODE)
58  LPI2C_HIGHSPEED_MODE = 0x3U,
59 #endif
60 #if(LPI2C_HAS_ULTRA_FAST_MODE)
61  LPI2C_ULTRAFAST_MODE = 0x4U
62 #endif
63 } lpi2c_mode_t;
64 
68 typedef enum
69 {
76 
80 typedef enum
81 {
88 
92 typedef enum
93 {
97 
98 /*******************************************************************************
99 * Definitions
100 ******************************************************************************/
101 
115 typedef void (*lpi2c_master_callback_t)(uint8_t instance, lpi2c_master_event_t masterEvent, void *userData);
116 
124 typedef void (*lpi2c_slave_callback_t)(uint8_t instance, lpi2c_slave_event_t slaveEvent, void *userData);
125 
132 typedef struct
133 {
134  uint16_t slaveAddress;
135  bool is10bitAddr;
137  uint32_t baudRate;
138 #if(LPI2C_HAS_HIGH_SPEED_MODE)
139  uint32_t baudRateHS;
140  uint8_t masterCode;
141 #endif
143  uint8_t dmaChannel;
150 
157 typedef struct
158 {
159  uint16_t slaveAddress;
160  bool is10bitAddr;
164  uint8_t dmaChannel;
172 
179 typedef struct
180 {
181  uint32_t baudRate;
182 #if(LPI2C_HAS_HIGH_SPEED_MODE)
183  uint32_t baudRateHS;
184 #endif
186 
188 /* Master software command queue */
189 typedef struct
190 {
191  lpi2c_master_command_t cmd[LPI2C_MASTER_CMD_QUEUE_SIZE];
192  uint8_t data[LPI2C_MASTER_CMD_QUEUE_SIZE];
193  uint8_t writeIdx;
194  uint8_t readIdx;
195 } lpi2c_master_cmd_queue_t;
206 typedef struct
207 {
209  lpi2c_master_cmd_queue_t cmdQueue; /* Software queue for commands, when LPI2C FIFO is not big enough */
210  uint8_t * rxBuff; /* Pointer to receive data buffer */
211  uint32_t rxSize; /* Size of receive data buffer */
212  const uint8_t * txBuff; /* Pointer to transmit data buffer */
213  uint32_t txSize; /* Size of transmit data buffer */
214  volatile status_t status; /* Status of last driver operation */
215  lpi2c_mode_t operatingMode; /* I2C Operating mode */
216  uint16_t slaveAddress; /* Slave address */
217  volatile bool i2cIdle; /* Idle/busy state of the driver */
218 #if(LPI2C_HAS_HIGH_SPEED_MODE)
219  uint8_t masterCode; /* Master code for High-speed mode */
220  bool highSpeedInProgress; /* High-speed communication is in progress */
221 #endif
222  bool sendStop; /* Specifies if STOP condition must be generated after current transfer */
223  bool is10bitAddr; /* Selects 7-bit or 10-bit slave address */
224  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
225  bool blocking; /* Specifies if the current transfer is blocking */
226  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
227  uint8_t dmaChannel; /* Channel number for DMA rx channel */
228  lpi2c_master_callback_t masterCallback; /* Master callback function */
229  void *callbackParam; /* Parameter for the master callback function */
232 
241 typedef struct
242 {
244  status_t status; /* The I2C slave status */
245  volatile bool isTransferInProgress; /* Slave is busy because of an ongoing transfer */
246  uint32_t txSize; /* Size of the TX buffer*/
247  uint32_t rxSize; /* Size of the RX buffer*/
248  const uint8_t * txBuff; /* Pointer to Tx Buffer*/
249  uint8_t * rxBuff; /* Pointer to Rx Buffer*/
250  lpi2c_mode_t operatingMode; /* I2C Operating mode */
251  bool slaveListening; /* Slave mode (always listening or on demand only) */
252  bool txUnderrunWarning; /* Possible slave tx underrun */
253  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
254  bool blocking; /* Specifies if the current transfer is blocking */
255  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
256  uint8_t dmaChannel; /* Channel number for DMA channel */ /* Channel number for DMA tx channel */
257  lpi2c_slave_callback_t slaveCallback; /* Slave callback function */
258  void *callbackParam; /* Parameter for the slave callback function */
261 
262 /*******************************************************************************
263  * API
264  ******************************************************************************/
270 #if defined(__cplusplus)
271 extern "C" {
272 #endif
273 
274 
291 status_t LPI2C_DRV_MasterInit(uint32_t instance,
292  const lpi2c_master_user_config_t * userConfigPtr,
293  lpi2c_master_state_t * master);
294 
295 
306 status_t LPI2C_DRV_MasterDeinit(uint32_t instance);
307 
308 
319 void LPI2C_DRV_MasterGetBaudRate(uint32_t instance, lpi2c_baud_rate_params_t *baudRate);
320 
321 
340 void LPI2C_DRV_MasterSetBaudRate(uint32_t instance,
341  const lpi2c_mode_t operatingMode,
342  const lpi2c_baud_rate_params_t baudRate);
343 
344 
355 void LPI2C_DRV_MasterSetSlaveAddr(uint32_t instance, const uint16_t address, const bool is10bitAddr);
356 
357 
372 status_t LPI2C_DRV_MasterSendData(uint32_t instance,
373  const uint8_t * txBuff,
374  uint32_t txSize,
375  bool sendStop);
376 
377 
392  const uint8_t * txBuff,
393  uint32_t txSize,
394  bool sendStop,
395  uint32_t timeout);
396 
397 
405 
406 
421 status_t LPI2C_DRV_MasterReceiveData(uint32_t instance,
422  uint8_t * rxBuff,
423  uint32_t rxSize,
424  bool sendStop);
425 
426 
441  uint8_t * rxBuff,
442  uint32_t rxSize,
443  bool sendStop,
444  uint32_t timeout);
445 
446 
457 status_t LPI2C_DRV_MasterGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining);
458 
459 
468 void LPI2C_DRV_MasterIRQHandler(uint32_t instance);
469 
470 
485 status_t LPI2C_DRV_SlaveInit(uint32_t instance,
486  const lpi2c_slave_user_config_t * userConfigPtr,
487  lpi2c_slave_state_t * slave);
488 
489 
500 status_t LPI2C_DRV_SlaveDeinit(uint32_t instance);
501 
502 
516 status_t LPI2C_DRV_SlaveSetTxBuffer(uint32_t instance,
517  const uint8_t * txBuff,
518  uint32_t txSize);
519 
520 
534 status_t LPI2C_DRV_SlaveSetRxBuffer(uint32_t instance,
535  uint8_t * rxBuff,
536  uint32_t rxSize);
537 
538 
553 status_t LPI2C_DRV_SlaveSendData(uint32_t instance,
554  const uint8_t * txBuff,
555  uint32_t txSize);
556 
557 
572 status_t LPI2C_DRV_SlaveSendDataBlocking(uint32_t instance,
573  const uint8_t * txBuff,
574  uint32_t txSize,
575  uint32_t timeout);
576 
577 
592 status_t LPI2C_DRV_SlaveReceiveData(uint32_t instance,
593  uint8_t * rxBuff,
594  uint32_t rxSize);
595 
596 
612  uint8_t * rxBuff,
613  uint32_t rxSize,
614  uint32_t timeout);
615 
616 
628  uint32_t *bytesRemaining);
629 
630 
637 status_t LPI2C_DRV_SlaveAbortTransferData(uint32_t instance);
638 
639 
649 void LPI2C_DRV_SlaveIRQHandler(uint32_t instance);
650 
651 
653 #if defined(__cplusplus)
654 }
655 #endif
656 
659 #endif /* LPI2C_DRIVER_H */
660 /*******************************************************************************
661  * EOF
662  ******************************************************************************/
status_t LPI2C_DRV_SlaveGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining)
Return the current status of the I2C slave transfer.
lpi2c_slave_callback_t slaveCallback
Definition: lpi2c_driver.h:165
status_t LPI2C_DRV_MasterGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining)
Return the current status of the I2C master transfer.
lpi2c_slave_event_t
LPI2C slave events Implements : lpi2c_slave_event_t_Class.
Definition: lpi2c_driver.h:80
status_t LPI2C_DRV_MasterAbortTransferData(uint32_t instance)
Abort a non-blocking I2C Master transmission or reception.
void(* lpi2c_master_callback_t)(uint8_t instance, lpi2c_master_event_t masterEvent, void *userData)
Defines the example structure.
Definition: lpi2c_driver.h:115
lpi2c_transfer_type_t transferType
Definition: lpi2c_driver.h:142
lpi2c_master_callback_t masterCallback
Definition: lpi2c_driver.h:144
status_t LPI2C_DRV_SlaveReceiveData(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
Perform a non-blocking receive transaction on the I2C bus.
status_t LPI2C_DRV_SlaveSendDataBlocking(uint32_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
Perform a blocking send transaction on the I2C bus.
lpi2c_transfer_type_t transferType
Definition: lpi2c_driver.h:163
lpi2c_mode_t
I2C operating modes Implements : lpi2c_mode_t_Class.
Definition: lpi2c_driver.h:50
void LPI2C_DRV_MasterSetSlaveAddr(uint32_t instance, const uint16_t address, const bool is10bitAddr)
Set the slave address for any subsequent I2C communication.
status_t LPI2C_DRV_SlaveSetRxBuffer(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
Provide a buffer for receiving data.
void LPI2C_DRV_MasterGetBaudRate(uint32_t instance, lpi2c_baud_rate_params_t *baudRate)
Get the currently configured baud rate.
status_t LPI2C_DRV_MasterReceiveDataBlocking(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop, uint32_t timeout)
Perform a blocking receive transaction on the I2C bus.
status_t LPI2C_DRV_MasterSendData(uint32_t instance, const uint8_t *txBuff, uint32_t txSize, bool sendStop)
Perform a non-blocking send transaction on the I2C bus.
status_t LPI2C_DRV_SlaveSetTxBuffer(uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
Provide a buffer for transmitting data.
Slave configuration structure.
Definition: lpi2c_driver.h:157
Slave internal context structure.
Definition: lpi2c_driver.h:241
Baud rate structure.
Definition: lpi2c_driver.h:179
lpi2c_transfer_type_t
Type of LPI2C transfer (based on interrupts or DMA). Implements : lpi2c_transfer_type_t_Class.
Definition: lpi2c_driver.h:92
status_t LPI2C_DRV_SlaveSendData(uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
Perform a non-blocking send transaction on the I2C bus.
status_t LPI2C_DRV_SlaveAbortTransferData(uint32_t instance)
Abort a non-blocking I2C Master transmission or reception.
void LPI2C_DRV_MasterIRQHandler(uint32_t instance)
Handle master operation when I2C interrupt occurs.
status_t
Status return codes. Common error codes will be a unified enumeration (C enum) that will contain all ...
Definition: status.h:31
status_t LPI2C_DRV_MasterInit(uint32_t instance, const lpi2c_master_user_config_t *userConfigPtr, lpi2c_master_state_t *master)
Initialize the LPI2C master mode driver.
status_t LPI2C_DRV_MasterDeinit(uint32_t instance)
De-initialize the LPI2C master mode driver.
void LPI2C_DRV_SlaveIRQHandler(uint32_t instance)
Handle slave operation when I2C interrupt occurs.
Master configuration structure.
Definition: lpi2c_driver.h:132
status_t LPI2C_DRV_SlaveDeinit(uint32_t instance)
De-initialize the I2C slave mode driver.
lpi2c_master_command_t
LPI2C master commands Implements : lpi2c_master_command_t_Class.
Definition: lpi2c_hal.h:208
void LPI2C_DRV_MasterSetBaudRate(uint32_t instance, const lpi2c_mode_t operatingMode, const lpi2c_baud_rate_params_t baudRate)
Set the baud rate for any subsequent I2C communication.
Master internal context structure.
Definition: lpi2c_driver.h:206
status_t LPI2C_DRV_MasterReceiveData(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, bool sendStop)
Perform a non-blocking receive transaction on the I2C bus.
status_t LPI2C_DRV_SlaveReceiveDataBlocking(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
Perform a blocking receive transaction on the I2C bus.
status_t LPI2C_DRV_SlaveInit(uint32_t instance, const lpi2c_slave_user_config_t *userConfigPtr, lpi2c_slave_state_t *slave)
Initialize the I2C slave mode driver.
status_t LPI2C_DRV_MasterSendDataBlocking(uint32_t instance, const uint8_t *txBuff, uint32_t txSize, bool sendStop, uint32_t timeout)
Perform a blocking send transaction on the I2C bus.
void(* lpi2c_slave_callback_t)(uint8_t instance, lpi2c_slave_event_t slaveEvent, void *userData)
LPI2C slave callback function.
Definition: lpi2c_driver.h:124
lpi2c_master_event_t
LPI2C master events Implements : lpi2c_master_event_t_Class.
Definition: lpi2c_driver.h:68