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