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_I2C_H_
9 #define FSL_I2C_H_
10
11 #include "fsl_common.h"
12
13 /*!
14 * @addtogroup i2c_driver
15 * @{
16 */
17
18 /*******************************************************************************
19 * Definitions
20 ******************************************************************************/
21
22 /*! @name Driver version */
23 /*! @{ */
24 /*! @brief I2C driver version. */
25 #define FSL_I2C_DRIVER_VERSION (MAKE_VERSION(2, 0, 9))
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 Mater Fast ack control, control if master needs to manually write ack, this is used to
34 low the speed of transfer for SoCs with feature FSL_FEATURE_I2C_HAS_DOUBLE_BUFFERING */
35 #ifndef I2C_MASTER_FACK_CONTROL
36 #define I2C_MASTER_FACK_CONTROL 0U /* Default defines to zero means master will send ack automatically. */
37 #endif
38
39 #if (defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT || \
40 defined(FSL_FEATURE_I2C_HAS_STOP_DETECT) && FSL_FEATURE_I2C_HAS_STOP_DETECT)
41 #define I2C_HAS_STOP_DETECT
42 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT / FSL_FEATURE_I2C_HAS_STOP_DETECT */
43
44 /*! @brief I2C status return codes. */
45 enum
46 {
47 kStatus_I2C_Busy = MAKE_STATUS(kStatusGroup_I2C, 0), /*!< I2C is busy with current transfer. */
48 kStatus_I2C_Idle = MAKE_STATUS(kStatusGroup_I2C, 1), /*!< Bus is Idle. */
49 kStatus_I2C_Nak = MAKE_STATUS(kStatusGroup_I2C, 2), /*!< NAK received during transfer. */
50 kStatus_I2C_ArbitrationLost = MAKE_STATUS(kStatusGroup_I2C, 3), /*!< Arbitration lost during transfer. */
51 kStatus_I2C_Timeout = MAKE_STATUS(kStatusGroup_I2C, 4), /*!< Timeout polling status flags. */
52 kStatus_I2C_Addr_Nak = MAKE_STATUS(kStatusGroup_I2C, 5), /*!< NAK received during the address probe. */
53 };
54
55 /*!
56 * @brief I2C peripheral flags
57 *
58 * @note These enumerations are meant to be OR'd together to form a bit mask.
59 *
60 */
61 enum _i2c_flags
62 {
63 kI2C_ReceiveNakFlag = I2C_S_RXAK_MASK, /*!< I2C receive NAK flag. */
64 kI2C_IntPendingFlag = I2C_S_IICIF_MASK, /*!< I2C interrupt pending flag. This flag can be cleared. */
65 kI2C_TransferDirectionFlag = I2C_S_SRW_MASK, /*!< I2C transfer direction flag. */
66 kI2C_RangeAddressMatchFlag = I2C_S_RAM_MASK, /*!< I2C range address match flag. */
67 kI2C_ArbitrationLostFlag = I2C_S_ARBL_MASK, /*!< I2C arbitration lost flag. This flag can be cleared. */
68 kI2C_BusBusyFlag = I2C_S_BUSY_MASK, /*!< I2C bus busy flag. */
69 kI2C_AddressMatchFlag = I2C_S_IAAS_MASK, /*!< I2C address match flag. */
70 kI2C_TransferCompleteFlag = I2C_S_TCF_MASK, /*!< I2C transfer complete flag. */
71 #ifdef I2C_HAS_STOP_DETECT
72 kI2C_StopDetectFlag = I2C_FLT_STOPF_MASK << 8, /*!< I2C stop detect flag. This flag can be cleared. */
73 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT / FSL_FEATURE_I2C_HAS_STOP_DETECT */
74
75 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
76 kI2C_StartDetectFlag = I2C_FLT_STARTF_MASK << 8, /*!< I2C start detect flag. This flag can be cleared. */
77 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT */
78 };
79
80 /*! @brief I2C feature interrupt source. */
81 enum _i2c_interrupt_enable
82 {
83 kI2C_GlobalInterruptEnable = I2C_C1_IICIE_MASK, /*!< I2C global interrupt. */
84
85 #if defined(FSL_FEATURE_I2C_HAS_STOP_DETECT) && FSL_FEATURE_I2C_HAS_STOP_DETECT
86 kI2C_StopDetectInterruptEnable = I2C_FLT_STOPIE_MASK, /*!< I2C stop detect interrupt. */
87 #endif /* FSL_FEATURE_I2C_HAS_STOP_DETECT */
88
89 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
90 kI2C_StartStopDetectInterruptEnable = I2C_FLT_SSIE_MASK, /*!< I2C start&stop detect interrupt. */
91 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT */
92 };
93
94 /*! @brief The direction of master and slave transfers. */
95 typedef enum _i2c_direction
96 {
97 kI2C_Write = 0x0U, /*!< Master transmits to the slave. */
98 kI2C_Read = 0x1U, /*!< Master receives from the slave. */
99 } i2c_direction_t;
100
101 /*! @brief Addressing mode. */
102 typedef enum _i2c_slave_address_mode
103 {
104 kI2C_Address7bit = 0x0U, /*!< 7-bit addressing mode. */
105 kI2C_RangeMatch = 0X2U, /*!< Range address match addressing mode. */
106 } i2c_slave_address_mode_t;
107
108 /*! @brief I2C transfer control flag. */
109 enum _i2c_master_transfer_flags
110 {
111 kI2C_TransferDefaultFlag = 0x0U, /*!< A transfer starts with a start signal, stops with a stop signal. */
112 kI2C_TransferNoStartFlag = 0x1U, /*!< A transfer starts without a start signal, only support write only or
113 write+read with no start flag, do not support read only with no start flag. */
114 kI2C_TransferRepeatedStartFlag = 0x2U, /*!< A transfer starts with a repeated start signal. */
115 kI2C_TransferNoStopFlag = 0x4U, /*!< A transfer ends without a stop signal. */
116 };
117
118 /*!
119 * @brief Set of events sent to the callback for nonblocking slave transfers.
120 *
121 * These event enumerations are used for two related purposes. First, a bit mask created by OR'ing together
122 * events is passed to I2C_SlaveTransferNonBlocking() to specify which events to enable.
123 * Then, when the slave callback is invoked, it is passed the current event through its @a transfer
124 * parameter.
125 *
126 * @note These enumerations are meant to be OR'd together to form a bit mask of events.
127 */
128 typedef enum _i2c_slave_transfer_event
129 {
130 kI2C_SlaveAddressMatchEvent = 0x01U, /*!< Received the slave address after a start or repeated start. */
131 kI2C_SlaveTransmitEvent = 0x02U, /*!< A callback is requested to provide data to transmit
132 (slave-transmitter role). */
133 kI2C_SlaveReceiveEvent = 0x04U, /*!< A callback is requested to provide a buffer in which to place received
134 data (slave-receiver role). */
135 kI2C_SlaveTransmitAckEvent = 0x08U, /*!< A callback needs to either transmit an ACK or NACK. */
136 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
137 kI2C_SlaveStartEvent = 0x10U, /*!< A start/repeated start was detected. */
138 #endif
139 kI2C_SlaveCompletionEvent = 0x20U, /*!< A stop was detected or finished transfer, completing the transfer. */
140 kI2C_SlaveGenaralcallEvent = 0x40U, /*!< Received the general call address after a start or repeated start. */
141
142 /*! A bit mask of all available events. */
143 kI2C_SlaveAllEvents = kI2C_SlaveAddressMatchEvent | kI2C_SlaveTransmitEvent | kI2C_SlaveReceiveEvent |
144 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
145 kI2C_SlaveStartEvent |
146 #endif
147 kI2C_SlaveCompletionEvent | kI2C_SlaveGenaralcallEvent,
148 } i2c_slave_transfer_event_t;
149
150 /*! @brief Common sets of flags used by the driver. */
151 enum
152 {
153 /*! All flags which are cleared by the driver upon starting a transfer. */
154 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
155 kClearFlags = kI2C_ArbitrationLostFlag | kI2C_IntPendingFlag | kI2C_StartDetectFlag | kI2C_StopDetectFlag,
156 kIrqFlags = kI2C_GlobalInterruptEnable | kI2C_StartStopDetectInterruptEnable,
157 #elif defined(FSL_FEATURE_I2C_HAS_STOP_DETECT) && FSL_FEATURE_I2C_HAS_STOP_DETECT
158 kClearFlags = kI2C_ArbitrationLostFlag | kI2C_IntPendingFlag | kI2C_StopDetectFlag,
159 kIrqFlags = kI2C_GlobalInterruptEnable | kI2C_StopDetectInterruptEnable,
160 #else
161 kClearFlags = kI2C_ArbitrationLostFlag | kI2C_IntPendingFlag,
162 kIrqFlags = kI2C_GlobalInterruptEnable,
163 #endif
164 };
165
166 /*! @brief I2C master user configuration. */
167 typedef struct _i2c_master_config
168 {
169 bool enableMaster; /*!< Enables the I2C peripheral at initialization time. */
170 #if defined(FSL_FEATURE_I2C_HAS_STOP_HOLD_OFF) && FSL_FEATURE_I2C_HAS_STOP_HOLD_OFF
171 bool enableStopHold; /*!< Controls the stop hold enable. */
172 #endif
173 #if defined(FSL_FEATURE_I2C_HAS_DOUBLE_BUFFER_ENABLE) && FSL_FEATURE_I2C_HAS_DOUBLE_BUFFER_ENABLE
174 bool enableDoubleBuffering; /*!< Controls double buffer enable; notice that
175 enabling the double buffer disables the clock stretch. */
176 #endif
177 uint32_t baudRate_Bps; /*!< Baud rate configuration of I2C peripheral. */
178 uint8_t glitchFilterWidth; /*!< Controls the width of the glitch. */
179 } i2c_master_config_t;
180
181 /*! @brief I2C slave user configuration. */
182 typedef struct _i2c_slave_config
183 {
184 bool enableSlave; /*!< Enables the I2C peripheral at initialization time. */
185 bool enableGeneralCall; /*!< Enables the general call addressing mode. */
186 bool enableWakeUp; /*!< Enables/disables waking up MCU from low-power mode. */
187 #if defined(FSL_FEATURE_I2C_HAS_DOUBLE_BUFFER_ENABLE) && FSL_FEATURE_I2C_HAS_DOUBLE_BUFFER_ENABLE
188 bool enableDoubleBuffering; /*!< Controls a double buffer enable; notice that
189 enabling the double buffer disables the clock stretch. */
190 #endif
191 bool enableBaudRateCtl; /*!< Enables/disables independent slave baud rate on SCL in very fast I2C modes. */
192 uint16_t slaveAddress; /*!< A slave address configuration. */
193 uint16_t upperAddress; /*!< A maximum boundary slave address used in a range matching mode. */
194 i2c_slave_address_mode_t
195 addressingMode; /*!< An addressing mode configuration of i2c_slave_address_mode_config_t. */
196 uint32_t sclStopHoldTime_ns; /*!< the delay from the rising edge of SCL (I2C clock) to the rising edge of SDA (I2C
197 data) while SCL is high (stop condition), SDA hold time and SCL start hold time
198 are also configured according to the SCL stop hold time. */
199 } i2c_slave_config_t;
200
201 /*! @brief I2C master handle typedef. */
202 typedef struct _i2c_master_handle i2c_master_handle_t;
203
204 /*! @brief I2C master transfer callback typedef. */
205 typedef void (*i2c_master_transfer_callback_t)(I2C_Type *base,
206 i2c_master_handle_t *handle,
207 status_t status,
208 void *userData);
209
210 /*! @brief I2C slave handle typedef. */
211 typedef struct _i2c_slave_handle i2c_slave_handle_t;
212
213 /*! @brief I2C master transfer structure. */
214 typedef struct _i2c_master_transfer
215 {
216 uint32_t flags; /*!< A transfer flag which controls the transfer. */
217 uint8_t slaveAddress; /*!< 7-bit slave address. */
218 i2c_direction_t direction; /*!< A transfer direction, read or write. */
219 uint32_t subaddress; /*!< A sub address. Transferred MSB first. */
220 uint8_t subaddressSize; /*!< A size of the command buffer. */
221 uint8_t *volatile data; /*!< A transfer buffer. */
222 volatile size_t dataSize; /*!< A transfer size. */
223 } i2c_master_transfer_t;
224
225 /*! @brief I2C master handle structure. */
226 struct _i2c_master_handle
227 {
228 i2c_master_transfer_t transfer; /*!< I2C master transfer copy. */
229 size_t transferSize; /*!< Total bytes to be transferred. */
230 uint8_t state; /*!< A transfer state maintained during transfer. */
231 i2c_master_transfer_callback_t completionCallback; /*!< A callback function called when the transfer is finished. */
232 void *userData; /*!< A callback parameter passed to the callback function. */
233 };
234
235 /*! @brief I2C slave transfer structure. */
236 typedef struct _i2c_slave_transfer
237 {
238 i2c_slave_transfer_event_t event; /*!< A reason that the callback is invoked. */
239 uint8_t *volatile data; /*!< A transfer buffer. */
240 volatile size_t dataSize; /*!< A transfer size. */
241 status_t completionStatus; /*!< Success or error code describing how the transfer completed. Only applies for
242 #kI2C_SlaveCompletionEvent. */
243 size_t transferredCount; /*!< A number of bytes actually transferred since the start or since the last repeated
244 start. */
245 } i2c_slave_transfer_t;
246
247 /*! @brief I2C slave transfer callback typedef. */
248 typedef void (*i2c_slave_transfer_callback_t)(I2C_Type *base, i2c_slave_transfer_t *xfer, void *userData);
249
250 /*! @brief I2C slave handle structure. */
251 struct _i2c_slave_handle
252 {
253 volatile bool isBusy; /*!< Indicates whether a transfer is busy. */
254 i2c_slave_transfer_t transfer; /*!< I2C slave transfer copy. */
255 uint32_t eventMask; /*!< A mask of enabled events. */
256 i2c_slave_transfer_callback_t callback; /*!< A callback function called at the transfer event. */
257 void *userData; /*!< A callback parameter passed to the callback. */
258 };
259
260 /*******************************************************************************
261 * API
262 ******************************************************************************/
263
264 #if defined(__cplusplus)
265 extern "C" {
266 #endif /*_cplusplus. */
267
268 /*!
269 * @name Initialization and deinitialization
270 * @{
271 */
272
273 /*!
274 * @brief Initializes the I2C peripheral. Call this API to ungate the I2C clock
275 * and configure the I2C with master configuration.
276 *
277 * @note This API should be called at the beginning of the application.
278 * Otherwise, any operation to the I2C module can cause a hard fault
279 * because the clock is not enabled. The configuration structure can be custom filled
280 * or it can be set with default values by using the I2C_MasterGetDefaultConfig().
281 * After calling this API, the master is ready to transfer.
282 * This is an example.
283 * @code
284 * i2c_master_config_t config = {
285 * .enableMaster = true,
286 * .enableStopHold = false,
287 * .highDrive = false,
288 * .baudRate_Bps = 100000,
289 * .glitchFilterWidth = 0
290 * };
291 * I2C_MasterInit(I2C0, &config, 12000000U);
292 * @endcode
293 *
294 * @param base I2C base pointer
295 * @param masterConfig A pointer to the master configuration structure
296 * @param srcClock_Hz I2C peripheral clock frequency in Hz
297 */
298 void I2C_MasterInit(I2C_Type *base, const i2c_master_config_t *masterConfig, uint32_t srcClock_Hz);
299
300 /*!
301 * @brief Initializes the I2C peripheral. Call this API to ungate the I2C clock
302 * and initialize the I2C with the slave configuration.
303 *
304 * @note This API should be called at the beginning of the application.
305 * Otherwise, any operation to the I2C module can cause a hard fault
306 * because the clock is not enabled. The configuration structure can partly be set
307 * with default values by I2C_SlaveGetDefaultConfig() or it can be custom filled by the user.
308 * This is an example.
309 * @code
310 * i2c_slave_config_t config = {
311 * .enableSlave = true,
312 * .enableGeneralCall = false,
313 * .addressingMode = kI2C_Address7bit,
314 * .slaveAddress = 0x1DU,
315 * .enableWakeUp = false,
316 * .enablehighDrive = false,
317 * .enableBaudRateCtl = false,
318 * .sclStopHoldTime_ns = 4000
319 * };
320 * I2C_SlaveInit(I2C0, &config, 12000000U);
321 * @endcode
322 *
323 * @param base I2C base pointer
324 * @param slaveConfig A pointer to the slave configuration structure
325 * @param srcClock_Hz I2C peripheral clock frequency in Hz
326 */
327 void I2C_SlaveInit(I2C_Type *base, const i2c_slave_config_t *slaveConfig, uint32_t srcClock_Hz);
328
329 /*!
330 * @brief De-initializes the I2C master peripheral. Call this API to gate the I2C clock.
331 * The I2C master module can't work unless the I2C_MasterInit is called.
332 * @param base I2C base pointer
333 */
334 void I2C_MasterDeinit(I2C_Type *base);
335
336 /*!
337 * @brief De-initializes the I2C slave peripheral. Calling this API gates the I2C clock.
338 * The I2C slave module can't work unless the I2C_SlaveInit is called to enable the clock.
339 * @param base I2C base pointer
340 */
341 void I2C_SlaveDeinit(I2C_Type *base);
342
343 /*!
344 * @brief Get instance number for I2C module.
345 *
346 * @param base I2C peripheral base address.
347 */
348 uint32_t I2C_GetInstance(I2C_Type *base);
349
350 /*!
351 * @brief Sets the I2C master configuration structure to default values.
352 *
353 * The purpose of this API is to get the configuration structure initialized for use in the I2C_MasterConfigure().
354 * Use the initialized structure unchanged in the I2C_MasterConfigure() or modify
355 * the structure before calling the I2C_MasterConfigure().
356 * This is an example.
357 * @code
358 * i2c_master_config_t config;
359 * I2C_MasterGetDefaultConfig(&config);
360 * @endcode
361 * @param masterConfig A pointer to the master configuration structure.
362 */
363 void I2C_MasterGetDefaultConfig(i2c_master_config_t *masterConfig);
364
365 /*!
366 * @brief Sets the I2C slave configuration structure to default values.
367 *
368 * The purpose of this API is to get the configuration structure initialized for use in the I2C_SlaveConfigure().
369 * Modify fields of the structure before calling the I2C_SlaveConfigure().
370 * This is an example.
371 * @code
372 * i2c_slave_config_t config;
373 * I2C_SlaveGetDefaultConfig(&config);
374 * @endcode
375 * @param slaveConfig A pointer to the slave configuration structure.
376 */
377 void I2C_SlaveGetDefaultConfig(i2c_slave_config_t *slaveConfig);
378
379 /*!
380 * @brief Enables or disables the I2C peripheral operation.
381 *
382 * @param base I2C base pointer
383 * @param enable Pass true to enable and false to disable the module.
384 */
I2C_Enable(I2C_Type * base,bool enable)385 static inline void I2C_Enable(I2C_Type *base, bool enable)
386 {
387 if (enable)
388 {
389 base->C1 |= I2C_C1_IICEN_MASK;
390 }
391 else
392 {
393 base->C1 &= ~(uint8_t)I2C_C1_IICEN_MASK;
394 }
395 }
396
397 /*! @} */
398
399 /*!
400 * @name Status
401 * @{
402 */
403
404 /*!
405 * @brief Gets the I2C status flags.
406 *
407 * @param base I2C base pointer
408 * @return status flag, use status flag to AND #_i2c_flags to get the related status.
409 */
410 uint32_t I2C_MasterGetStatusFlags(I2C_Type *base);
411
412 /*!
413 * @brief Gets the I2C status flags.
414 *
415 * @param base I2C base pointer
416 * @return status flag, use status flag to AND #_i2c_flags to get the related status.
417 */
I2C_SlaveGetStatusFlags(I2C_Type * base)418 static inline uint32_t I2C_SlaveGetStatusFlags(I2C_Type *base)
419 {
420 return I2C_MasterGetStatusFlags(base);
421 }
422
423 /*!
424 * @brief Clears the I2C status flag state.
425 *
426 * The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag.
427 *
428 * @param base I2C base pointer
429 * @param statusMask The status flag mask, defined in type i2c_status_flag_t.
430 * The parameter can be any combination of the following values:
431 * @arg kI2C_StartDetectFlag (if available)
432 * @arg kI2C_StopDetectFlag (if available)
433 * @arg kI2C_ArbitrationLostFlag
434 * @arg kI2C_IntPendingFlagFlag
435 */
I2C_MasterClearStatusFlags(I2C_Type * base,uint32_t statusMask)436 static inline void I2C_MasterClearStatusFlags(I2C_Type *base, uint32_t statusMask)
437 {
438 /* Must clear the STARTF / STOPF bits prior to clearing IICIF */
439 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
440 if ((uint32_t)kI2C_StartDetectFlag == (statusMask & (uint32_t)kI2C_StartDetectFlag))
441 {
442 /* Shift the odd-ball flags back into place. */
443 base->FLT |= (uint8_t)(statusMask >> 8U);
444 }
445 #endif
446
447 #ifdef I2C_HAS_STOP_DETECT
448 if ((uint32_t)kI2C_StopDetectFlag == (statusMask & (uint32_t)kI2C_StopDetectFlag))
449 {
450 /* Shift the odd-ball flags back into place. */
451 base->FLT |= (uint8_t)(statusMask >> 8U);
452 }
453 #endif
454
455 base->S = (uint8_t)statusMask;
456 }
457
458 /*!
459 * @brief Clears the I2C status flag state.
460 *
461 * The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag
462 *
463 * @param base I2C base pointer
464 * @param statusMask The status flag mask, defined in type i2c_status_flag_t.
465 * The parameter can be any combination of the following values:
466 * @arg kI2C_StartDetectFlag (if available)
467 * @arg kI2C_StopDetectFlag (if available)
468 * @arg kI2C_ArbitrationLostFlag
469 * @arg kI2C_IntPendingFlagFlag
470 */
I2C_SlaveClearStatusFlags(I2C_Type * base,uint32_t statusMask)471 static inline void I2C_SlaveClearStatusFlags(I2C_Type *base, uint32_t statusMask)
472 {
473 I2C_MasterClearStatusFlags(base, statusMask);
474 }
475
476 /*! @} */
477
478 /*!
479 * @name Interrupts
480 * @{
481 */
482
483 /*!
484 * @brief Enables I2C interrupt requests.
485 *
486 * @param base I2C base pointer
487 * @param mask interrupt source
488 * The parameter can be combination of the following source if defined:
489 * @arg kI2C_GlobalInterruptEnable
490 * @arg kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable
491 * @arg kI2C_SdaTimeoutInterruptEnable
492 */
493 void I2C_EnableInterrupts(I2C_Type *base, uint32_t mask);
494
495 /*!
496 * @brief Disables I2C interrupt requests.
497 *
498 * @param base I2C base pointer
499 * @param mask interrupt source
500 * The parameter can be combination of the following source if defined:
501 * @arg kI2C_GlobalInterruptEnable
502 * @arg kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable
503 * @arg kI2C_SdaTimeoutInterruptEnable
504 */
505 void I2C_DisableInterrupts(I2C_Type *base, uint32_t mask);
506 /*! @} */
507
508 /*!
509 * @name DMA Control
510 * @{
511 */
512 #if defined(FSL_FEATURE_I2C_HAS_DMA_SUPPORT) && FSL_FEATURE_I2C_HAS_DMA_SUPPORT
513 /*!
514 * @brief Enables/disables the I2C DMA interrupt.
515 *
516 * @param base I2C base pointer
517 * @param enable true to enable, false to disable
518 */
I2C_EnableDMA(I2C_Type * base,bool enable)519 static inline void I2C_EnableDMA(I2C_Type *base, bool enable)
520 {
521 if (enable)
522 {
523 base->C1 |= I2C_C1_DMAEN_MASK;
524 }
525 else
526 {
527 base->C1 &= ~(uint8_t)I2C_C1_DMAEN_MASK;
528 }
529 }
530
531 #endif /* FSL_FEATURE_I2C_HAS_DMA_SUPPORT */
532
533 /*!
534 * @brief Gets the I2C tx/rx data register address. This API is used to provide a transfer address
535 * for I2C DMA transfer configuration.
536 *
537 * @param base I2C base pointer
538 * @return data register address
539 */
I2C_GetDataRegAddr(I2C_Type * base)540 static inline uint32_t I2C_GetDataRegAddr(I2C_Type *base)
541 {
542 return (uint32_t)(&(base->D));
543 }
544
545 /*! @} */
546
547 /*!
548 * @name Bus Operations
549 * @{
550 */
551
552 /*!
553 * @brief Sets the I2C master transfer baud rate.
554 *
555 * @param base I2C base pointer
556 * @param baudRate_Bps the baud rate value in bps
557 * @param srcClock_Hz Source clock
558 */
559 void I2C_MasterSetBaudRate(I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz);
560
561 /*!
562 * @brief Sends a START on the I2C bus.
563 *
564 * This function is used to initiate a new master mode transfer by sending the START signal.
565 * The slave address is sent following the I2C START signal.
566 *
567 * @param base I2C peripheral base pointer
568 * @param address 7-bit slave device address.
569 * @param direction Master transfer directions(transmit/receive).
570 * @retval kStatus_Success Successfully send the start signal.
571 * @retval kStatus_I2C_Busy Current bus is busy.
572 */
573 status_t I2C_MasterStart(I2C_Type *base, uint8_t address, i2c_direction_t direction);
574
575 /*!
576 * @brief Sends a STOP signal on the I2C bus.
577 *
578 * @retval kStatus_Success Successfully send the stop signal.
579 * @retval kStatus_I2C_Timeout Send stop signal failed, timeout.
580 */
581 status_t I2C_MasterStop(I2C_Type *base);
582
583 /*!
584 * @brief Sends a REPEATED START on the I2C bus.
585 *
586 * @param base I2C peripheral base pointer
587 * @param address 7-bit slave device address.
588 * @param direction Master transfer directions(transmit/receive).
589 * @retval kStatus_Success Successfully send the start signal.
590 * @retval kStatus_I2C_Busy Current bus is busy but not occupied by current I2C master.
591 */
592 status_t I2C_MasterRepeatedStart(I2C_Type *base, uint8_t address, i2c_direction_t direction);
593
594 /*!
595 * @brief Performs a polling send transaction on the I2C bus.
596 *
597 * @param base The I2C peripheral base pointer.
598 * @param txBuff The pointer to the data to be transferred.
599 * @param txSize The length in bytes of the data to be transferred.
600 * @param flags Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag
601 * to issue a stop and kI2C_TransferNoStop to not send a stop.
602 * @retval kStatus_Success Successfully complete the data transmission.
603 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
604 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
605 */
606 status_t I2C_MasterWriteBlocking(I2C_Type *base, const uint8_t *txBuff, size_t txSize, uint32_t flags);
607
608 /*!
609 * @brief Performs a polling receive transaction on the I2C bus.
610 *
611 * @note The I2C_MasterReadBlocking function stops the bus before reading the final byte.
612 * Without stopping the bus prior for the final read, the bus issues another read, resulting
613 * in garbage data being read into the data register.
614 *
615 * @param base I2C peripheral base pointer.
616 * @param rxBuff The pointer to the data to store the received data.
617 * @param rxSize The length in bytes of the data to be received.
618 * @param flags Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag
619 * to issue a stop and kI2C_TransferNoStop to not send a stop.
620 * @retval kStatus_Success Successfully complete the data transmission.
621 * @retval kStatus_I2C_Timeout Send stop signal failed, timeout.
622 */
623 status_t I2C_MasterReadBlocking(I2C_Type *base, uint8_t *rxBuff, size_t rxSize, uint32_t flags);
624
625 /*!
626 * @brief Performs a polling send transaction on the I2C bus.
627 *
628 * @param base The I2C peripheral base pointer.
629 * @param txBuff The pointer to the data to be transferred.
630 * @param txSize The length in bytes of the data to be transferred.
631 * @retval kStatus_Success Successfully complete the data transmission.
632 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
633 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
634 */
635 status_t I2C_SlaveWriteBlocking(I2C_Type *base, const uint8_t *txBuff, size_t txSize);
636
637 /*!
638 * @brief Performs a polling receive transaction on the I2C bus.
639 *
640 * @param base I2C peripheral base pointer.
641 * @param rxBuff The pointer to the data to store the received data.
642 * @param rxSize The length in bytes of the data to be received.
643 * @retval kStatus_Success Successfully complete data receive.
644 * @retval kStatus_I2C_Timeout Wait status flag timeout.
645 */
646 status_t I2C_SlaveReadBlocking(I2C_Type *base, uint8_t *rxBuff, size_t rxSize);
647
648 /*!
649 * @brief Performs a master polling transfer on the I2C bus.
650 *
651 * @note The API does not return until the transfer succeeds or fails due
652 * to arbitration lost or receiving a NAK.
653 *
654 * @param base I2C peripheral base address.
655 * @param xfer Pointer to the transfer structure.
656 * @retval kStatus_Success Successfully complete the data transmission.
657 * @retval kStatus_I2C_Busy Previous transmission still not finished.
658 * @retval kStatus_I2C_Timeout Transfer error, wait signal timeout.
659 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
660 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
661 */
662 status_t I2C_MasterTransferBlocking(I2C_Type *base, i2c_master_transfer_t *xfer);
663
664 /*! @} */
665
666 /*!
667 * @name Transactional
668 * @{
669 */
670
671 /*!
672 * @brief Initializes the I2C handle which is used in transactional functions.
673 *
674 * @param base I2C base pointer.
675 * @param handle pointer to i2c_master_handle_t structure to store the transfer state.
676 * @param callback pointer to user callback function.
677 * @param userData user parameter passed to the callback function.
678 */
679 void I2C_MasterTransferCreateHandle(I2C_Type *base,
680 i2c_master_handle_t *handle,
681 i2c_master_transfer_callback_t callback,
682 void *userData);
683
684 /*!
685 * @brief Performs a master interrupt non-blocking transfer on the I2C bus.
686 *
687 * @note Calling the API returns immediately after transfer initiates. The user needs
688 * to call I2C_MasterGetTransferCount to poll the transfer status to check whether
689 * the transfer is finished. If the return status is not kStatus_I2C_Busy, the transfer
690 * is finished.
691 *
692 * @param base I2C base pointer.
693 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state.
694 * @param xfer pointer to i2c_master_transfer_t structure.
695 * @retval kStatus_Success Successfully start the data transmission.
696 * @retval kStatus_I2C_Busy Previous transmission still not finished.
697 * @retval kStatus_I2C_Timeout Transfer error, wait signal timeout.
698 */
699 status_t I2C_MasterTransferNonBlocking(I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_t *xfer);
700
701 /*!
702 * @brief Gets the master transfer status during a interrupt non-blocking transfer.
703 *
704 * @param base I2C base pointer.
705 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state.
706 * @param count Number of bytes transferred so far by the non-blocking transaction.
707 * @retval kStatus_InvalidArgument count is Invalid.
708 * @retval kStatus_Success Successfully return the count.
709 */
710 status_t I2C_MasterTransferGetCount(I2C_Type *base, i2c_master_handle_t *handle, size_t *count);
711
712 /*!
713 * @brief Aborts an interrupt non-blocking transfer early.
714 *
715 * @note This API can be called at any time when an interrupt non-blocking transfer initiates
716 * to abort the transfer early.
717 *
718 * @param base I2C base pointer.
719 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state
720 * @retval kStatus_I2C_Timeout Timeout during polling flag.
721 * @retval kStatus_Success Successfully abort the transfer.
722 */
723 status_t I2C_MasterTransferAbort(I2C_Type *base, i2c_master_handle_t *handle);
724
725 /*!
726 * @brief Master interrupt handler.
727 *
728 * @param base I2C base pointer.
729 * @param i2cHandle pointer to i2c_master_handle_t structure.
730 */
731 void I2C_MasterTransferHandleIRQ(I2C_Type *base, void *i2cHandle);
732
733 /*!
734 * @brief Initializes the I2C handle which is used in transactional functions.
735 *
736 * @param base I2C base pointer.
737 * @param handle pointer to i2c_slave_handle_t structure to store the transfer state.
738 * @param callback pointer to user callback function.
739 * @param userData user parameter passed to the callback function.
740 */
741 void I2C_SlaveTransferCreateHandle(I2C_Type *base,
742 i2c_slave_handle_t *handle,
743 i2c_slave_transfer_callback_t callback,
744 void *userData);
745
746 /*!
747 * @brief Starts accepting slave transfers.
748 *
749 * Call this API after calling the I2C_SlaveInit() and I2C_SlaveTransferCreateHandle() to start processing
750 * transactions driven by an I2C master. The slave monitors the I2C bus and passes events to the
751 * callback that was passed into the call to I2C_SlaveTransferCreateHandle(). The callback is always invoked
752 * from the interrupt context.
753 *
754 * The set of events received by the callback is customizable. To do so, set the @a eventMask parameter to
755 * the OR'd combination of #i2c_slave_transfer_event_t enumerators for the events you wish to receive.
756 * The kI2C_SlaveTransmitEvent and kLPI2C_SlaveReceiveEvent events are always enabled and do not need
757 * to be included in the mask. Alternatively, pass 0 to get a default set of only the transmit and
758 * receive events that are always enabled. In addition, the #kI2C_SlaveAllEvents constant is provided as
759 * a convenient way to enable all events.
760 *
761 * @param base The I2C peripheral base address.
762 * @param handle Pointer to i2c_slave_handle_t structure which stores the transfer state.
763 * @param eventMask Bit mask formed by OR'ing together #i2c_slave_transfer_event_t enumerators to specify
764 * which events to send to the callback. Other accepted values are 0 to get a default set of
765 * only the transmit and receive events, and #kI2C_SlaveAllEvents to enable all events.
766 *
767 * @retval kStatus_Success Slave transfers were successfully started.
768 * @retval kStatus_I2C_Busy Slave transfers have already been started on this handle.
769 */
770 status_t I2C_SlaveTransferNonBlocking(I2C_Type *base, i2c_slave_handle_t *handle, uint32_t eventMask);
771
772 /*!
773 * @brief Aborts the slave transfer.
774 *
775 * @note This API can be called at any time to stop slave for handling the bus events.
776 *
777 * @param base I2C base pointer.
778 * @param handle pointer to i2c_slave_handle_t structure which stores the transfer state.
779 */
780 void I2C_SlaveTransferAbort(I2C_Type *base, i2c_slave_handle_t *handle);
781
782 /*!
783 * @brief Gets the slave transfer remaining bytes during a interrupt non-blocking transfer.
784 *
785 * @param base I2C base pointer.
786 * @param handle pointer to i2c_slave_handle_t structure.
787 * @param count Number of bytes transferred so far by the non-blocking transaction.
788 * @retval kStatus_InvalidArgument count is Invalid.
789 * @retval kStatus_Success Successfully return the count.
790 */
791 status_t I2C_SlaveTransferGetCount(I2C_Type *base, i2c_slave_handle_t *handle, size_t *count);
792
793 /*!
794 * @brief Slave interrupt handler.
795 *
796 * @param base I2C base pointer.
797 * @param i2cHandle pointer to i2c_slave_handle_t structure which stores the transfer state
798 */
799 void I2C_SlaveTransferHandleIRQ(I2C_Type *base, void *i2cHandle);
800
801 /*! @} */
802 #if defined(__cplusplus)
803 }
804 #endif /*_cplusplus. */
805 /*! @} */
806
807 #endif /* FSL_I2C_H_*/
808
