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, 5, 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
