1 /*
2  * Copyright (c) 2015, Freescale Semiconductor, Inc.
3  * Copyright 2016-2020 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef _FSL_FLEXIO_I2C_MASTER_H_
9 #define _FSL_FLEXIO_I2C_MASTER_H_
10 
11 #include "fsl_common.h"
12 #include "fsl_flexio.h"
13 
14 /*!
15  * @addtogroup flexio_i2c_master
16  * @{
17  */
18 
19 /*******************************************************************************
20  * Definitions
21  ******************************************************************************/
22 
23 /*! @name Driver version */
24 /*@{*/
25 #define FSL_FLEXIO_I2C_MASTER_DRIVER_VERSION (MAKE_VERSION(2, 4, 0))
26 /*@}*/
27 
28 /*! @brief Retry times for waiting flag. */
29 #ifndef I2C_RETRY_TIMES
30 #define I2C_RETRY_TIMES 0U /* Define to zero means keep waiting until the flag is assert/deassert. */
31 #endif
32 
33 /*! @brief FlexIO I2C transfer status*/
34 enum
35 {
36     kStatus_FLEXIO_I2C_Busy    = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 0), /*!< I2C is busy doing transfer. */
37     kStatus_FLEXIO_I2C_Idle    = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 1), /*!< I2C is busy doing transfer. */
38     kStatus_FLEXIO_I2C_Nak     = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 2), /*!< NAK received during transfer. */
39     kStatus_FLEXIO_I2C_Timeout = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 3), /*!< Timeout polling status flags. */
40 };
41 
42 /*! @brief Define FlexIO I2C master interrupt mask. */
43 enum _flexio_i2c_master_interrupt
44 {
45     kFLEXIO_I2C_TxEmptyInterruptEnable = 0x1U, /*!< Tx buffer empty interrupt enable. */
46     kFLEXIO_I2C_RxFullInterruptEnable  = 0x2U, /*!< Rx buffer full interrupt enable. */
47 };
48 
49 /*! @brief Define FlexIO I2C master status mask. */
50 enum _flexio_i2c_master_status_flags
51 {
52     kFLEXIO_I2C_TxEmptyFlag    = 0x1U, /*!< Tx shifter empty flag. */
53     kFLEXIO_I2C_RxFullFlag     = 0x2U, /*!< Rx shifter full/Transfer complete flag. */
54     kFLEXIO_I2C_ReceiveNakFlag = 0x4U, /*!< Receive NAK flag. */
55 };
56 
57 /*! @brief Direction of master transfer.*/
58 typedef enum _flexio_i2c_direction
59 {
60     kFLEXIO_I2C_Write = 0x0U, /*!< Master send to slave. */
61     kFLEXIO_I2C_Read  = 0x1U, /*!< Master receive from slave. */
62 } flexio_i2c_direction_t;
63 
64 /*! @brief Define FlexIO I2C master access structure typedef. */
65 typedef struct _flexio_i2c_type
66 {
67     FLEXIO_Type *flexioBase; /*!< FlexIO base pointer. */
68     uint8_t SDAPinIndex;     /*!< Pin select for I2C SDA. */
69     uint8_t SCLPinIndex;     /*!< Pin select for I2C SCL. */
70     uint8_t shifterIndex[2]; /*!< Shifter index used in FlexIO I2C. */
71     uint8_t timerIndex[3];   /*!< Timer index used in FlexIO I2C. */
72     uint32_t baudrate;       /*!< Master transfer baudrate, used to calculate delay time. */
73 } FLEXIO_I2C_Type;
74 
75 /*! @brief Define FlexIO I2C master user configuration structure. */
76 typedef struct _flexio_i2c_master_config
77 {
78     bool enableMaster;     /*!< Enables the FlexIO I2C peripheral at initialization time. */
79     bool enableInDoze;     /*!< Enable/disable FlexIO operation in doze mode. */
80     bool enableInDebug;    /*!< Enable/disable FlexIO operation in debug mode. */
81     bool enableFastAccess; /*!< Enable/disable fast access to FlexIO registers, fast access requires
82                            the FlexIO clock to be at least twice the frequency of the bus clock. */
83     uint32_t baudRate_Bps; /*!< Baud rate in Bps. */
84 } flexio_i2c_master_config_t;
85 
86 /*! @brief Define FlexIO I2C master transfer structure. */
87 typedef struct _flexio_i2c_master_transfer
88 {
89     uint32_t flags;                   /*!< Transfer flag which controls the transfer, reserved for FlexIO I2C. */
90     uint8_t slaveAddress;             /*!< 7-bit slave address. */
91     flexio_i2c_direction_t direction; /*!< Transfer direction, read or write. */
92     uint32_t subaddress;              /*!< Sub address. Transferred MSB first. */
93     uint8_t subaddressSize;           /*!< Size of command buffer. */
94     uint8_t volatile *data;           /*!< Transfer buffer. */
95     volatile size_t dataSize;         /*!< Transfer size. */
96 } flexio_i2c_master_transfer_t;
97 
98 /*! @brief FlexIO I2C master handle typedef. */
99 typedef struct _flexio_i2c_master_handle flexio_i2c_master_handle_t;
100 
101 /*! @brief FlexIO I2C master transfer callback typedef. */
102 typedef void (*flexio_i2c_master_transfer_callback_t)(FLEXIO_I2C_Type *base,
103                                                       flexio_i2c_master_handle_t *handle,
104                                                       status_t status,
105                                                       void *userData);
106 
107 /*! @brief Define FlexIO I2C master handle structure. */
108 struct _flexio_i2c_master_handle
109 {
110     flexio_i2c_master_transfer_t transfer;                    /*!< FlexIO I2C master transfer copy. */
111     size_t transferSize;                                      /*!< Total bytes to be transferred. */
112     uint8_t state;                                            /*!< Transfer state maintained during transfer. */
113     flexio_i2c_master_transfer_callback_t completionCallback; /*!< Callback function called at transfer event. */
114                                                               /*!< Callback function called at transfer event. */
115     void *userData;                                           /*!< Callback parameter passed to callback function. */
116     bool needRestart;                                         /*!< Whether master needs to send re-start signal. */
117 };
118 
119 /*******************************************************************************
120  * API
121  ******************************************************************************/
122 
123 #if defined(__cplusplus)
124 extern "C" {
125 #endif /*_cplusplus*/
126 
127 /*!
128  * @name Initialization and deinitialization
129  * @{
130  */
131 
132 #if defined(FSL_FEATURE_FLEXIO_HAS_PIN_STATUS) && FSL_FEATURE_FLEXIO_HAS_PIN_STATUS
133 /*!
134  * @brief Make sure the bus isn't already pulled down.
135  *
136  * Check the FLEXIO pin status to see whether either of SDA and SCL pin is pulled down.
137  *
138  * @param base Pointer to FLEXIO_I2C_Type structure..
139  * @retval kStatus_Success
140  * @retval kStatus_FLEXIO_I2C_Busy
141  */
142 status_t FLEXIO_I2C_CheckForBusyBus(FLEXIO_I2C_Type *base);
143 #endif /*FSL_FEATURE_FLEXIO_HAS_PIN_STATUS*/
144 
145 /*!
146  * @brief Ungates the FlexIO clock, resets the FlexIO module, and configures the FlexIO I2C
147  * hardware configuration.
148  *
149  * Example
150    @code
151    FLEXIO_I2C_Type base = {
152    .flexioBase = FLEXIO,
153    .SDAPinIndex = 0,
154    .SCLPinIndex = 1,
155    .shifterIndex = {0,1},
156    .timerIndex = {0,1}
157    };
158    flexio_i2c_master_config_t config = {
159    .enableInDoze = false,
160    .enableInDebug = true,
161    .enableFastAccess = false,
162    .baudRate_Bps = 100000
163    };
164    FLEXIO_I2C_MasterInit(base, &config, srcClock_Hz);
165    @endcode
166  *
167  * @param base Pointer to FLEXIO_I2C_Type structure.
168  * @param masterConfig Pointer to flexio_i2c_master_config_t structure.
169  * @param srcClock_Hz FlexIO source clock in Hz.
170  * @retval kStatus_Success Initialization successful
171  * @retval kStatus_InvalidArgument The source clock exceed upper range limitation
172 */
173 status_t FLEXIO_I2C_MasterInit(FLEXIO_I2C_Type *base, flexio_i2c_master_config_t *masterConfig, uint32_t srcClock_Hz);
174 
175 /*!
176  * @brief De-initializes the FlexIO I2C master peripheral. Calling this API Resets the FlexIO I2C master
177  * shifer and timer config, module can't work unless the FLEXIO_I2C_MasterInit is called.
178  *
179  * @param base pointer to FLEXIO_I2C_Type structure.
180  */
181 void FLEXIO_I2C_MasterDeinit(FLEXIO_I2C_Type *base);
182 
183 /*!
184  * @brief Gets the default configuration to configure the FlexIO module. The configuration
185  * can be used directly for calling the FLEXIO_I2C_MasterInit().
186  *
187  * Example:
188    @code
189    flexio_i2c_master_config_t config;
190    FLEXIO_I2C_MasterGetDefaultConfig(&config);
191    @endcode
192  * @param masterConfig Pointer to flexio_i2c_master_config_t structure.
193 */
194 void FLEXIO_I2C_MasterGetDefaultConfig(flexio_i2c_master_config_t *masterConfig);
195 
196 /*!
197  * @brief Enables/disables the FlexIO module operation.
198  *
199  * @param base Pointer to FLEXIO_I2C_Type structure.
200  * @param enable Pass true to enable module, false does not have any effect.
201  */
FLEXIO_I2C_MasterEnable(FLEXIO_I2C_Type * base,bool enable)202 static inline void FLEXIO_I2C_MasterEnable(FLEXIO_I2C_Type *base, bool enable)
203 {
204     if (enable)
205     {
206         base->flexioBase->CTRL |= FLEXIO_CTRL_FLEXEN_MASK;
207     }
208 }
209 
210 /* @} */
211 
212 /*!
213  * @name Status
214  * @{
215  */
216 
217 /*!
218  * @brief Gets the FlexIO I2C master status flags.
219  *
220  * @param base Pointer to FLEXIO_I2C_Type structure
221  * @return Status flag, use status flag to AND #_flexio_i2c_master_status_flags can get the related status.
222  */
223 
224 uint32_t FLEXIO_I2C_MasterGetStatusFlags(FLEXIO_I2C_Type *base);
225 
226 /*!
227  * @brief Clears the FlexIO I2C master status flags.
228  *
229  * @param base Pointer to FLEXIO_I2C_Type structure.
230  * @param mask Status flag.
231  *      The parameter can be any combination of the following values:
232  *          @arg kFLEXIO_I2C_RxFullFlag
233  *          @arg kFLEXIO_I2C_ReceiveNakFlag
234  */
235 
236 void FLEXIO_I2C_MasterClearStatusFlags(FLEXIO_I2C_Type *base, uint32_t mask);
237 
238 /*@}*/
239 
240 /*!
241  * @name Interrupts
242  * @{
243  */
244 
245 /*!
246  * @brief Enables the FlexIO i2c master interrupt requests.
247  *
248  * @param base Pointer to FLEXIO_I2C_Type structure.
249  * @param mask Interrupt source.
250  *     Currently only one interrupt request source:
251  *     @arg kFLEXIO_I2C_TransferCompleteInterruptEnable
252  */
253 void FLEXIO_I2C_MasterEnableInterrupts(FLEXIO_I2C_Type *base, uint32_t mask);
254 
255 /*!
256  * @brief Disables the FlexIO I2C master interrupt requests.
257  *
258  * @param base Pointer to FLEXIO_I2C_Type structure.
259  * @param mask Interrupt source.
260  */
261 void FLEXIO_I2C_MasterDisableInterrupts(FLEXIO_I2C_Type *base, uint32_t mask);
262 
263 /*@}*/
264 
265 /*!
266  * @name Bus Operations
267  * @{
268  */
269 
270 /*!
271  * @brief Sets the FlexIO I2C master transfer baudrate.
272  *
273  * @param base Pointer to FLEXIO_I2C_Type structure
274  * @param baudRate_Bps the baud rate value in HZ
275  * @param srcClock_Hz source clock in HZ
276  */
277 void FLEXIO_I2C_MasterSetBaudRate(FLEXIO_I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz);
278 
279 /*!
280  * @brief Sends START + 7-bit address to the bus.
281  *
282  * @note This API should be called when the transfer configuration is ready to send a START signal
283  * and 7-bit address to the bus. This is a non-blocking API, which returns directly after the address
284  * is put into the data register but the address transfer is not finished on the bus. Ensure that
285  * the kFLEXIO_I2C_RxFullFlag status is asserted before calling this API.
286  * @param base Pointer to FLEXIO_I2C_Type structure.
287  * @param address 7-bit address.
288  * @param direction transfer direction.
289  *     This parameter is one of the values in flexio_i2c_direction_t:
290  *        @arg kFLEXIO_I2C_Write: Transmit
291  *        @arg kFLEXIO_I2C_Read:  Receive
292  */
293 
294 void FLEXIO_I2C_MasterStart(FLEXIO_I2C_Type *base, uint8_t address, flexio_i2c_direction_t direction);
295 
296 /*!
297  * @brief Sends the stop signal on the bus.
298  *
299  * @param base Pointer to FLEXIO_I2C_Type structure.
300  */
301 void FLEXIO_I2C_MasterStop(FLEXIO_I2C_Type *base);
302 
303 /*!
304  * @brief Sends the repeated start signal on the bus.
305  *
306  * @param base Pointer to FLEXIO_I2C_Type structure.
307  */
308 void FLEXIO_I2C_MasterRepeatedStart(FLEXIO_I2C_Type *base);
309 
310 /*!
311  * @brief Sends the stop signal when transfer is still on-going.
312  *
313  * @param base Pointer to FLEXIO_I2C_Type structure.
314  */
315 void FLEXIO_I2C_MasterAbortStop(FLEXIO_I2C_Type *base);
316 
317 /*!
318  * @brief Configures the sent ACK/NAK for the following byte.
319  *
320  * @param base Pointer to FLEXIO_I2C_Type structure.
321  * @param enable True to configure send ACK, false configure to send NAK.
322  */
323 void FLEXIO_I2C_MasterEnableAck(FLEXIO_I2C_Type *base, bool enable);
324 
325 /*!
326  * @brief Sets the number of bytes to be transferred from a start signal to a stop signal.
327  *
328  * @note Call this API before a transfer begins because the timer generates a number of clocks according
329  * to the number of bytes that need to be transferred.
330  *
331  * @param base Pointer to FLEXIO_I2C_Type structure.
332  * @param count Number of bytes need to be transferred from a start signal to a re-start/stop signal
333  * @retval kStatus_Success Successfully configured the count.
334  * @retval kStatus_InvalidArgument Input argument is invalid.
335  */
336 status_t FLEXIO_I2C_MasterSetTransferCount(FLEXIO_I2C_Type *base, uint16_t count);
337 
338 /*!
339  * @brief Writes one byte of data to the I2C bus.
340  *
341  * @note This is a non-blocking API, which returns directly after the data is put into the
342  * data register but the data transfer is not finished on the bus. Ensure that
343  * the TxEmptyFlag is asserted before calling this API.
344  *
345  * @param base Pointer to FLEXIO_I2C_Type structure.
346  * @param data a byte of data.
347  */
FLEXIO_I2C_MasterWriteByte(FLEXIO_I2C_Type * base,uint32_t data)348 static inline void FLEXIO_I2C_MasterWriteByte(FLEXIO_I2C_Type *base, uint32_t data)
349 {
350     base->flexioBase->SHIFTBUFBBS[base->shifterIndex[0]] = data;
351 }
352 
353 /*!
354  * @brief Reads one byte of data from the I2C bus.
355  *
356  * @note This is a non-blocking API, which returns directly after the data is read from the
357  * data register. Ensure that the data is ready in the register.
358  *
359  * @param base Pointer to FLEXIO_I2C_Type structure.
360  * @return data byte read.
361  */
FLEXIO_I2C_MasterReadByte(FLEXIO_I2C_Type * base)362 static inline uint8_t FLEXIO_I2C_MasterReadByte(FLEXIO_I2C_Type *base)
363 {
364     return (uint8_t)(base->flexioBase->SHIFTBUFBIS[base->shifterIndex[1]]);
365 }
366 
367 /*!
368  * @brief Sends a buffer of data in bytes.
369  *
370  * @note This function blocks via polling until all bytes have been sent.
371  *
372  * @param base Pointer to FLEXIO_I2C_Type structure.
373  * @param txBuff The data bytes to send.
374  * @param txSize The number of data bytes to send.
375  * @retval kStatus_Success Successfully write data.
376  * @retval kStatus_FLEXIO_I2C_Nak Receive NAK during writing data.
377  * @retval kStatus_FLEXIO_I2C_Timeout Timeout polling status flags.
378  */
379 status_t FLEXIO_I2C_MasterWriteBlocking(FLEXIO_I2C_Type *base, const uint8_t *txBuff, uint8_t txSize);
380 
381 /*!
382  * @brief Receives a buffer of bytes.
383  *
384  * @note This function blocks via polling until all bytes have been received.
385  *
386  * @param base Pointer to FLEXIO_I2C_Type structure.
387  * @param rxBuff The buffer to store the received bytes.
388  * @param rxSize The number of data bytes to be received.
389  * @retval kStatus_Success Successfully read data.
390  * @retval kStatus_FLEXIO_I2C_Timeout Timeout polling status flags.
391  */
392 status_t FLEXIO_I2C_MasterReadBlocking(FLEXIO_I2C_Type *base, uint8_t *rxBuff, uint8_t rxSize);
393 
394 /*!
395  * @brief Performs a master polling transfer on the I2C bus.
396  *
397  * @note The API does not return until the transfer succeeds or fails due
398  * to receiving NAK.
399  *
400  * @param base pointer to FLEXIO_I2C_Type structure.
401  * @param xfer pointer to flexio_i2c_master_transfer_t structure.
402  * @return status of status_t.
403  */
404 status_t FLEXIO_I2C_MasterTransferBlocking(FLEXIO_I2C_Type *base, flexio_i2c_master_transfer_t *xfer);
405 /*@}*/
406 
407 /*Transactional APIs*/
408 
409 /*!
410  * @name Transactional
411  * @{
412  */
413 
414 /*!
415  * @brief Initializes the I2C handle which is used in transactional functions.
416  *
417  * @param base Pointer to FLEXIO_I2C_Type structure.
418  * @param handle Pointer to flexio_i2c_master_handle_t structure to store the transfer state.
419  * @param callback Pointer to user callback function.
420  * @param userData User param passed to the callback function.
421  * @retval kStatus_Success Successfully create the handle.
422  * @retval kStatus_OutOfRange The FlexIO type/handle/isr table out of range.
423  */
424 status_t FLEXIO_I2C_MasterTransferCreateHandle(FLEXIO_I2C_Type *base,
425                                                flexio_i2c_master_handle_t *handle,
426                                                flexio_i2c_master_transfer_callback_t callback,
427                                                void *userData);
428 
429 /*!
430  * @brief Performs a master interrupt non-blocking transfer on the I2C bus.
431  *
432  * @note The API returns immediately after the transfer initiates.
433  * Call FLEXIO_I2C_MasterTransferGetCount to poll the transfer status to check whether
434  * the transfer is finished. If the return status is not kStatus_FLEXIO_I2C_Busy, the transfer
435  * is finished.
436  *
437  * @param base Pointer to FLEXIO_I2C_Type structure
438  * @param handle Pointer to flexio_i2c_master_handle_t structure which stores the transfer state
439  * @param xfer pointer to flexio_i2c_master_transfer_t structure
440  * @retval kStatus_Success Successfully start a transfer.
441  * @retval kStatus_FLEXIO_I2C_Busy FlexIO I2C is not idle, is running another transfer.
442  */
443 status_t FLEXIO_I2C_MasterTransferNonBlocking(FLEXIO_I2C_Type *base,
444                                               flexio_i2c_master_handle_t *handle,
445                                               flexio_i2c_master_transfer_t *xfer);
446 
447 /*!
448  * @brief Gets the master transfer status during a interrupt non-blocking transfer.
449  *
450  * @param base Pointer to FLEXIO_I2C_Type structure.
451  * @param handle Pointer to flexio_i2c_master_handle_t structure which stores the transfer state.
452  * @param count Number of bytes transferred so far by the non-blocking transaction.
453  * @retval kStatus_InvalidArgument count is Invalid.
454  * @retval kStatus_NoTransferInProgress There is not a non-blocking transaction currently in progress.
455  * @retval kStatus_Success Successfully return the count.
456  */
457 status_t FLEXIO_I2C_MasterTransferGetCount(FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, size_t *count);
458 
459 /*!
460  * @brief Aborts an interrupt non-blocking transfer early.
461  *
462  * @note This API can be called at any time when an interrupt non-blocking transfer initiates
463  * to abort the transfer early.
464  *
465  * @param base Pointer to FLEXIO_I2C_Type structure
466  * @param handle Pointer to flexio_i2c_master_handle_t structure which stores the transfer state
467  */
468 void FLEXIO_I2C_MasterTransferAbort(FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle);
469 
470 /*!
471  * @brief Master interrupt handler.
472  *
473  * @param i2cType Pointer to FLEXIO_I2C_Type structure
474  * @param i2cHandle Pointer to flexio_i2c_master_transfer_t structure
475  */
476 void FLEXIO_I2C_MasterTransferHandleIRQ(void *i2cType, void *i2cHandle);
477 
478 /*@}*/
479 
480 #if defined(__cplusplus)
481 }
482 #endif /*_cplusplus*/
483 /*@}*/
484 
485 #endif /*_FSL_FLEXIO_I2C_MASTER_H_*/
486