S32 SDK
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 
52 
60 /*******************************************************************************
61  * Enumerations.
62  ******************************************************************************/
63 
65 /* Size of the master command queue. Worst case: 5 commands in High-Speed receive with 10-bit address:
66  START + master code, REP START + addr_1 + tx, addr_2, REP START + addr_1 + rx, receive command */
67 #define LPI2C_MASTER_CMD_QUEUE_SIZE 5U
68 
73 typedef enum
74 {
76  LPI2C_FAST_MODE = 0x1U,
77 #if(LPI2C_HAS_FAST_PLUS_MODE)
78  LPI2C_FASTPLUS_MODE = 0x2U,
79 #endif
80 #if(LPI2C_HAS_HIGH_SPEED_MODE)
81  LPI2C_HIGHSPEED_MODE = 0x3U,
82 #endif
83 #if(LPI2C_HAS_ULTRA_FAST_MODE)
84  LPI2C_ULTRAFAST_MODE = 0x4U
85 #endif
86 } lpi2c_mode_t;
87 
91 typedef enum
92 {
99 
103 typedef enum
104 {
111 
115 typedef enum
116 {
120 
121 /*******************************************************************************
122 * Definitions
123 ******************************************************************************/
124 
138 typedef void (*lpi2c_master_callback_t)(uint32_t instance, lpi2c_master_event_t masterEvent, void *userData);
139 
147 typedef void (*lpi2c_slave_callback_t)(uint32_t instance, lpi2c_slave_event_t slaveEvent, void *userData);
148 
155 typedef struct
156 {
157  uint16_t slaveAddress;
158  bool is10bitAddr;
160  uint32_t baudRate;
161 #if(LPI2C_HAS_HIGH_SPEED_MODE)
162  uint32_t baudRateHS;
163  uint8_t masterCode;
164 #endif
166  uint8_t dmaChannel;
173 
180 typedef struct
181 {
182  uint16_t slaveAddress;
183  bool is10bitAddr;
187  uint8_t dmaChannel;
195 
202 typedef struct
203 {
204  uint32_t baudRate;
205 #if(LPI2C_HAS_HIGH_SPEED_MODE)
206  uint32_t baudRateHS;
207 #endif
209 
211 /* LPI2C master commands */
212 typedef enum
213 {
214  LPI2C_MASTER_COMMAND_TRANSMIT = 0U,
215  LPI2C_MASTER_COMMAND_RECEIVE = 1U,
216  LPI2C_MASTER_COMMAND_STOP = 2U,
217  LPI2C_MASTER_COMMAND_RECEIVE_DISCARD = 3U,
218  LPI2C_MASTER_COMMAND_START = 4U,
219  LPI2C_MASTER_COMMAND_START_NACK = 5U,
220  LPI2C_MASTER_COMMAND_START_HS = 6U,
221  LPI2C_MASTER_COMMAND_START_NACK_HS = 7U,
222 } lpi2c_master_command_t;
226 /* Master software command queue */
227 typedef struct
228 {
229  lpi2c_master_command_t cmd[LPI2C_MASTER_CMD_QUEUE_SIZE];
230  uint8_t data[LPI2C_MASTER_CMD_QUEUE_SIZE];
231  uint8_t writeIdx;
232  uint8_t readIdx;
233 } lpi2c_master_cmd_queue_t;
244 typedef struct
245 {
247  lpi2c_master_cmd_queue_t cmdQueue; /* Software queue for commands, when LPI2C FIFO is not big enough */
248  uint8_t * rxBuff; /* Pointer to receive data buffer */
249  uint32_t rxSize; /* Size of receive data buffer */
250  const uint8_t * txBuff; /* Pointer to transmit data buffer */
251  uint32_t txSize; /* Size of transmit data buffer */
252  volatile status_t status; /* Status of last driver operation */
253  lpi2c_mode_t operatingMode; /* I2C Operating mode */
254  uint16_t slaveAddress; /* Slave address */
255  volatile bool i2cIdle; /* Idle/busy state of the driver */
256 #if(LPI2C_HAS_HIGH_SPEED_MODE)
257  uint8_t masterCode; /* Master code for High-speed mode */
258  bool highSpeedInProgress; /* High-speed communication is in progress */
259 #endif
260  bool sendStop; /* Specifies if STOP condition must be generated after current transfer */
261  bool is10bitAddr; /* Selects 7-bit or 10-bit slave address */
262  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
263  bool blocking; /* Specifies if the current transfer is blocking */
264  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
265  uint8_t dmaChannel; /* Channel number for DMA rx channel */
266  lpi2c_master_callback_t masterCallback; /* Master callback function */
267  void *callbackParam; /* Parameter for the master callback function */
270 
279 typedef struct
280 {
282  status_t status; /* The I2C slave status */
283  volatile bool isTransferInProgress; /* Slave is busy because of an ongoing transfer */
284  uint32_t txSize; /* Size of the TX buffer*/
285  uint32_t rxSize; /* Size of the RX buffer*/
286  const uint8_t * txBuff; /* Pointer to Tx Buffer*/
287  uint8_t * rxBuff; /* Pointer to Rx Buffer*/
288  lpi2c_mode_t operatingMode; /* I2C Operating mode */
289  bool slaveListening; /* Slave mode (always listening or on demand only) */
290  bool txUnderrunWarning; /* Possible slave tx underrun */
291  semaphore_t idleSemaphore; /* Semaphore used by blocking functions */
292  bool blocking; /* Specifies if the current transfer is blocking */
293  lpi2c_transfer_type_t transferType; /* Type of LPI2C transfer */
294  uint8_t dmaChannel; /* Channel number for DMA channel */ /* Channel number for DMA tx channel */
295  lpi2c_slave_callback_t slaveCallback; /* Slave callback function */
296  void *callbackParam; /* Parameter for the slave callback function */
299 
300 /*******************************************************************************
301  * API
302  ******************************************************************************/
308 #if defined(__cplusplus)
309 extern "C" {
310 #endif
311 
312 
329 status_t LPI2C_DRV_MasterInit(uint32_t instance,
330  const lpi2c_master_user_config_t * userConfigPtr,
331  lpi2c_master_state_t * master);
332 
333 
344 status_t LPI2C_DRV_MasterDeinit(uint32_t instance);
345 
346 
357 void LPI2C_DRV_MasterGetBaudRate(uint32_t instance, lpi2c_baud_rate_params_t *baudRate);
358 
359 
378 void LPI2C_DRV_MasterSetBaudRate(uint32_t instance,
379  const lpi2c_mode_t operatingMode,
380  const lpi2c_baud_rate_params_t baudRate);
381 
382 
393 void LPI2C_DRV_MasterSetSlaveAddr(uint32_t instance, const uint16_t address, const bool is10bitAddr);
394 
395 
410 status_t LPI2C_DRV_MasterSendData(uint32_t instance,
411  const uint8_t * txBuff,
412  uint32_t txSize,
413  bool sendStop);
414 
415 
430  const uint8_t * txBuff,
431  uint32_t txSize,
432  bool sendStop,
433  uint32_t timeout);
434 
435 
443 
444 
459 status_t LPI2C_DRV_MasterReceiveData(uint32_t instance,
460  uint8_t * rxBuff,
461  uint32_t rxSize,
462  bool sendStop);
463 
464 
479  uint8_t * rxBuff,
480  uint32_t rxSize,
481  bool sendStop,
482  uint32_t timeout);
483 
484 
495 status_t LPI2C_DRV_MasterGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining);
496 
497 
506 void LPI2C_DRV_MasterIRQHandler(uint32_t instance);
507 
508 
523 status_t LPI2C_DRV_SlaveInit(uint32_t instance,
524  const lpi2c_slave_user_config_t * userConfigPtr,
525  lpi2c_slave_state_t * slave);
526 
527 
538 status_t LPI2C_DRV_SlaveDeinit(uint32_t instance);
539 
540 
554 status_t LPI2C_DRV_SlaveSetTxBuffer(uint32_t instance,
555  const uint8_t * txBuff,
556  uint32_t txSize);
557 
558 
572 status_t LPI2C_DRV_SlaveSetRxBuffer(uint32_t instance,
573  uint8_t * rxBuff,
574  uint32_t rxSize);
575 
576 
591 status_t LPI2C_DRV_SlaveSendData(uint32_t instance,
592  const uint8_t * txBuff,
593  uint32_t txSize);
594 
595 
610 status_t LPI2C_DRV_SlaveSendDataBlocking(uint32_t instance,
611  const uint8_t * txBuff,
612  uint32_t txSize,
613  uint32_t timeout);
614 
615 
630 status_t LPI2C_DRV_SlaveReceiveData(uint32_t instance,
631  uint8_t * rxBuff,
632  uint32_t rxSize);
633 
634 
650  uint8_t * rxBuff,
651  uint32_t rxSize,
652  uint32_t timeout);
653 
654 
666  uint32_t *bytesRemaining);
667 
668 
675 status_t LPI2C_DRV_SlaveAbortTransferData(uint32_t instance);
676 
677 
687 void LPI2C_DRV_SlaveIRQHandler(uint32_t instance);
688 
689 
691 #if defined(__cplusplus)
692 }
693 #endif
694 
697 #endif /* LPI2C_DRIVER_H */
698 /*******************************************************************************
699  * EOF
700  ******************************************************************************/
status_t LPI2C_DRV_SlaveGetTransferStatus(uint32_t instance, uint32_t *bytesRemaining)
Return the current status of the I2C slave transfer.
void(* lpi2c_slave_callback_t)(uint32_t instance, lpi2c_slave_event_t slaveEvent, void *userData)
LPI2C slave callback function.
Definition: lpi2c_driver.h:147
lpi2c_slave_callback_t slaveCallback
Definition: lpi2c_driver.h:188
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:103
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:165
lpi2c_master_callback_t masterCallback
Definition: lpi2c_driver.h:167
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:186
lpi2c_mode_t
I2C operating modes Implements : lpi2c_mode_t_Class.
Definition: lpi2c_driver.h:73
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_master_callback_t)(uint32_t instance, lpi2c_master_event_t masterEvent, void *userData)
Defines the example structure.
Definition: lpi2c_driver.h:138
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:180
Slave internal context structure.
Definition: lpi2c_driver.h:279
Baud rate structure.
Definition: lpi2c_driver.h:202
lpi2c_transfer_type_t
Type of LPI2C transfer (based on interrupts or DMA). Implements : lpi2c_transfer_type_t_Class.
Definition: lpi2c_driver.h:115
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.
Master configuration structure.
Definition: lpi2c_driver.h:155
status_t LPI2C_DRV_SlaveDeinit(uint32_t instance)
De-initialize the I2C slave mode driver.
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:244
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.
lpi2c_master_event_t
LPI2C master events Implements : lpi2c_master_event_t_Class.
Definition: lpi2c_driver.h:91