lpi2c_driver.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2014 - 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016 - 2017 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  */
42 #if !defined(LPI2C_DRIVER_H)
43 #define LPI2C_DRIVER_H
44 
45 #include <stddef.h>
46 #include <stdbool.h>
47 #include "device_registers.h"
48 #include "status.h"
49 #include "edma_driver.h"
50 #include "osif.h"
51 #include "callbacks.h"
52 
53 
61 /*******************************************************************************
62  * Enumerations.
63  ******************************************************************************/
64 
66 /* Size of the master command queue. Worst case: 5 commands in High-Speed receive with 10-bit address:
67  START + master code, REP START + addr_1 + tx, addr_2, REP START + addr_1 + rx, receive command */
68 #define LPI2C_MASTER_CMD_QUEUE_SIZE 5U
69 
74 typedef enum
75 {
77  LPI2C_FAST_MODE = 0x1U,
78 #if(LPI2C_HAS_FAST_PLUS_MODE)
79  LPI2C_FASTPLUS_MODE = 0x2U,
80 #endif
81 #if(LPI2C_HAS_HIGH_SPEED_MODE)
82  LPI2C_HIGHSPEED_MODE = 0x3U,
83 #endif
84 #if(LPI2C_HAS_ULTRA_FAST_MODE)
85  LPI2C_ULTRAFAST_MODE = 0x4U
86 #endif
87 } lpi2c_mode_t;
88 
92 typedef enum
93 {
97 
98 /*******************************************************************************
99 * Definitions
100 ******************************************************************************/
101 
114 typedef struct
115 {
116  uint16_t slaveAddress;
117  bool is10bitAddr;
119  uint32_t baudRate;
120 #if(LPI2C_HAS_HIGH_SPEED_MODE)
121  uint32_t baudRateHS;
122  uint8_t masterCode;
123 #endif
125  uint8_t dmaChannel;
132 
139 typedef struct
140 {
141  uint16_t slaveAddress;
142  bool is10bitAddr;
146  uint8_t dmaChannel;
154 
161 typedef struct
162 {
163  uint32_t baudRate;
164 #if(LPI2C_HAS_HIGH_SPEED_MODE)
165  uint32_t baudRateHS;
166 #endif
168 
170 /* LPI2C master commands */
171 typedef enum
172 {
173  LPI2C_MASTER_COMMAND_TRANSMIT = 0U,
174  LPI2C_MASTER_COMMAND_RECEIVE = 1U,
175  LPI2C_MASTER_COMMAND_STOP = 2U,
176  LPI2C_MASTER_COMMAND_RECEIVE_DISCARD = 3U,
177  LPI2C_MASTER_COMMAND_START = 4U,
178  LPI2C_MASTER_COMMAND_START_NACK = 5U,
179  LPI2C_MASTER_COMMAND_START_HS = 6U,
180  LPI2C_MASTER_COMMAND_START_NACK_HS = 7U,
181 } lpi2c_master_command_t;
185 /* Master software command queue */
186 typedef struct
187 {
188  lpi2c_master_command_t cmd[LPI2C_MASTER_CMD_QUEUE_SIZE];
189  uint8_t data[LPI2C_MASTER_CMD_QUEUE_SIZE];
190  uint8_t writeIdx;
191  uint8_t readIdx;
192 } lpi2c_master_cmd_queue_t;
203 typedef struct
204 {
206  lpi2c_master_cmd_queue_t cmdQueue; /* Software queue for commands, when LPI2C FIFO is not big enough */
207  uint8_t * rxBuff; /* Pointer to receive data buffer */
208  uint32_t rxSize; /* Size of receive data buffer */
209  const uint8_t * txBuff; /* Pointer to transmit data buffer */
210  uint32_t txSize; /* Size of transmit data buffer */
211  volatile status_t status; /* Status of last driver operation */
212  lpi2c_mode_t operatingMode; /* I2C Operating mode */
213  uint16_t slaveAddress; /* Slave address */
214  volatile bool i2cIdle; /* Idle/busy state of the driver */
215 #if(LPI2C_HAS_HIGH_SPEED_MODE)
216  uint8_t masterCode; /* Master code for High-speed mode */
217  bool highSpeedInProgress; /* High-speed communication is in progress */
218 #endif
219  bool sendStop; /* Specifies if STOP condition must be generated after current transfer */
220  bool is10bitAddr; /* Selects 7-bit or 10-bit slave address */
221  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
222  bool blocking; /* Specifies if the current transfer is blocking */
223  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
224  uint8_t dmaChannel; /* Channel number for DMA rx channel */
225  i2c_master_callback_t masterCallback; /* Master callback function */
226  void *callbackParam; /* Parameter for the master callback function */
229 
238 typedef struct
239 {
241  status_t status; /* The I2C slave status */
242  volatile bool isTransferInProgress; /* Slave is busy because of an ongoing transfer */
243  uint32_t txSize; /* Size of the TX buffer*/
244  uint32_t rxSize; /* Size of the RX buffer*/
245  const uint8_t * txBuff; /* Pointer to Tx Buffer*/
246  uint8_t * rxBuff; /* Pointer to Rx Buffer*/
247  lpi2c_mode_t operatingMode; /* I2C Operating mode */
248  bool slaveListening; /* Slave mode (always listening or on demand only) */
249  bool is10bitAddress; /* Specifies if 10-bit or 7-bit address */
250  uint8_t repeatedStarts; /* Specifies the number of repeated starts */
251  bool txUnderrunWarning; /* Possible slave tx underrun */
252  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
253  bool blocking; /* Specifies if the current transfer is blocking */
254  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
255  uint8_t dmaChannel; /* Channel number for DMA channel */ /* Channel number for DMA tx channel */
256  i2c_slave_callback_t slaveCallback; /* Slave callback function */
257  void *callbackParam; /* Parameter for the slave callback function */
260 
261 /*******************************************************************************
262  * API
263  ******************************************************************************/
269 #if defined(__cplusplus)
270 extern "C" {
271 #endif
272 
273 
290 status_t LPI2C_DRV_MasterInit(uint32_t instance,
291  const lpi2c_master_user_config_t * userConfigPtr,
292  lpi2c_master_state_t * master);
293 
294 
305 status_t LPI2C_DRV_MasterDeinit(uint32_t instance);
306 
307 
318 void LPI2C_DRV_MasterGetBaudRate(uint32_t instance, lpi2c_baud_rate_params_t *baudRate);
319 
320 
339 void LPI2C_DRV_MasterSetBaudRate(uint32_t instance,
340  const lpi2c_mode_t operatingMode,
341  const lpi2c_baud_rate_params_t baudRate);
342 
343 
354 void LPI2C_DRV_MasterSetSlaveAddr(uint32_t instance, const uint16_t address, const bool is10bitAddr);
355 
356 
371 status_t LPI2C_DRV_MasterSendData(uint32_t instance,
372  const uint8_t * txBuff,
373  uint32_t txSize,
374  bool sendStop);
375 
376 
391  const uint8_t * txBuff,
392  uint32_t txSize,
393  bool sendStop,
394  uint32_t timeout);
395 
396 
404 
405 
420 status_t LPI2C_DRV_MasterReceiveData(uint32_t instance,
421  uint8_t * rxBuff,
422  uint32_t rxSize,
423  bool sendStop);
424 
425 
440  uint8_t * rxBuff,
441  uint32_t rxSize,
442  bool sendStop,
443  uint32_t timeout);
444 
445 
456 status_t LPI2C_DRV_MasterGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining);
457 
458 
467 void LPI2C_DRV_MasterIRQHandler(uint32_t instance);
468 
469 
484 status_t LPI2C_DRV_SlaveInit(uint32_t instance,
485  const lpi2c_slave_user_config_t * userConfigPtr,
486  lpi2c_slave_state_t * slave);
487 
488 
499 status_t LPI2C_DRV_SlaveDeinit(uint32_t instance);
500 
501 
515 status_t LPI2C_DRV_SlaveSetTxBuffer(uint32_t instance,
516  const uint8_t * txBuff,
517  uint32_t txSize);
518 
519 
533 status_t LPI2C_DRV_SlaveSetRxBuffer(uint32_t instance,
534  uint8_t * rxBuff,
535  uint32_t rxSize);
536 
537 
552 status_t LPI2C_DRV_SlaveSendData(uint32_t instance,
553  const uint8_t * txBuff,
554  uint32_t txSize);
555 
556 
571 status_t LPI2C_DRV_SlaveSendDataBlocking(uint32_t instance,
572  const uint8_t * txBuff,
573  uint32_t txSize,
574  uint32_t timeout);
575 
576 
591 status_t LPI2C_DRV_SlaveReceiveData(uint32_t instance,
592  uint8_t * rxBuff,
593  uint32_t rxSize);
594 
595 
611  uint8_t * rxBuff,
612  uint32_t rxSize,
613  uint32_t timeout);
614 
615 
627  uint32_t *bytesRemaining);
628 
629 
636 status_t LPI2C_DRV_SlaveAbortTransferData(uint32_t instance);
637 
638 
648 void LPI2C_DRV_SlaveIRQHandler(uint32_t instance);
649 
650 #if defined(S32K11x_SERIES)
651 
660 void LPI2C_DRV_ModuleIRQHandler(uint32_t instance);
661 #endif
662 
664 #if defined(__cplusplus)
665 }
666 #endif
667 
670 #endif /* LPI2C_DRIVER_H */
671 /*******************************************************************************
672  * EOF
673  ******************************************************************************/
status_t LPI2C_DRV_SlaveGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining)
Return the current status of the I2C slave transfer.
status_t LPI2C_DRV_MasterGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining)
Return the current status of the I2C master transfer.
status_t LPI2C_DRV_MasterAbortTransferData(uint32_t instance)
Abort a non-blocking I2C Master transmission or reception.
lpi2c_transfer_type_t transferType
Definition: lpi2c_driver.h:124
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.
i2c_master_callback_t masterCallback
Definition: lpi2c_driver.h:126
lpi2c_transfer_type_t transferType
Definition: lpi2c_driver.h:145
lpi2c_mode_t
I2C operating modes Implements : lpi2c_mode_t_Class.
Definition: lpi2c_driver.h:74
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:139
Slave internal context structure.
Definition: lpi2c_driver.h:238
Baud rate structure.
Definition: lpi2c_driver.h:161
void(* i2c_master_callback_t)(i2c_master_event_t event, void *userData)
Definition: callbacks.h:70
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:44
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.
Defines the example structure.
Definition: lpi2c_driver.h:114
status_t LPI2C_DRV_SlaveDeinit(uint32_t instance)
De-initialize the I2C slave mode driver.
void(* i2c_slave_callback_t)(i2c_slave_event_t event, void *userData)
Definition: callbacks.h:67
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:203
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.
i2c_slave_callback_t slaveCallback
Definition: lpi2c_driver.h:147
void LPI2C_DRV_ModuleIRQHandler(uint32_t instance)
Handler for both slave and master operation when I2C interrupt occurs.