1 /*
2 * Copyright (c) 2015, Freescale Semiconductor, Inc.
3 * Copyright 2016-2017 NXP
4 *
5 * Redistribution and use in source and binary forms, with or without modification,
6 * are permitted provided that the following conditions are met:
7 *
8 * o Redistributions of source code must retain the above copyright notice, this list
9 * of conditions and the following disclaimer.
10 *
11 * o Redistributions in binary form must reproduce the above copyright notice, this
12 * list of conditions and the following disclaimer in the documentation and/or
13 * other materials provided with the distribution.
14 *
15 * o Neither the name of the copyright holder nor the names of its
16 * contributors may be used to endorse or promote products derived from this
17 * software without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
23 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
26 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
28 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 #ifndef _FSL_I2C_H_
31 #define _FSL_I2C_H_
32
33 #include "fsl_common.h"
34
35 /*!
36 * @addtogroup i2c_driver
37 * @{
38 */
39
40 /*******************************************************************************
41 * Definitions
42 ******************************************************************************/
43
44 /*! @name Driver version */
45 /*@{*/
46 /*! @brief I2C driver version 2.0.3. */
47 #define FSL_I2C_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))
48 /*@}*/
49
50 #if (defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT || \
51 defined(FSL_FEATURE_I2C_HAS_STOP_DETECT) && FSL_FEATURE_I2C_HAS_STOP_DETECT)
52 #define I2C_HAS_STOP_DETECT
53 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT / FSL_FEATURE_I2C_HAS_STOP_DETECT */
54
55 /*! @brief I2C status return codes. */
56 enum _i2c_status
57 {
58 kStatus_I2C_Busy = MAKE_STATUS(kStatusGroup_I2C, 0), /*!< I2C is busy with current transfer. */
59 kStatus_I2C_Idle = MAKE_STATUS(kStatusGroup_I2C, 1), /*!< Bus is Idle. */
60 kStatus_I2C_Nak = MAKE_STATUS(kStatusGroup_I2C, 2), /*!< NAK received during transfer. */
61 kStatus_I2C_ArbitrationLost = MAKE_STATUS(kStatusGroup_I2C, 3), /*!< Arbitration lost during transfer. */
62 kStatus_I2C_Timeout = MAKE_STATUS(kStatusGroup_I2C, 4), /*!< Wait event timeout. */
63 kStatus_I2C_Addr_Nak = MAKE_STATUS(kStatusGroup_I2C, 5), /*!< NAK received during the address probe. */
64 };
65
66 /*!
67 * @brief I2C peripheral flags
68 *
69 * The following status register flags can be cleared:
70 * - #kI2C_ArbitrationLostFlag
71 * - #kI2C_IntPendingFlag
72 * - #kI2C_StartDetectFlag
73 * - #kI2C_StopDetectFlag
74 *
75 * @note These enumerations are meant to be OR'd together to form a bit mask.
76 *
77 */
78 enum _i2c_flags
79 {
80 kI2C_ReceiveNakFlag = I2C_S_RXAK_MASK, /*!< I2C receive NAK flag. */
81 kI2C_IntPendingFlag = I2C_S_IICIF_MASK, /*!< I2C interrupt pending flag. */
82 kI2C_TransferDirectionFlag = I2C_S_SRW_MASK, /*!< I2C transfer direction flag. */
83 kI2C_RangeAddressMatchFlag = I2C_S_RAM_MASK, /*!< I2C range address match flag. */
84 kI2C_ArbitrationLostFlag = I2C_S_ARBL_MASK, /*!< I2C arbitration lost flag. */
85 kI2C_BusBusyFlag = I2C_S_BUSY_MASK, /*!< I2C bus busy flag. */
86 kI2C_AddressMatchFlag = I2C_S_IAAS_MASK, /*!< I2C address match flag. */
87 kI2C_TransferCompleteFlag = I2C_S_TCF_MASK, /*!< I2C transfer complete flag. */
88 #ifdef I2C_HAS_STOP_DETECT
89 kI2C_StopDetectFlag = I2C_FLT_STOPF_MASK << 8, /*!< I2C stop detect flag. */
90 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT / FSL_FEATURE_I2C_HAS_STOP_DETECT */
91
92 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
93 kI2C_StartDetectFlag = I2C_FLT_STARTF_MASK << 8, /*!< I2C start detect flag. */
94 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT */
95 };
96
97 /*! @brief I2C feature interrupt source. */
98 enum _i2c_interrupt_enable
99 {
100 kI2C_GlobalInterruptEnable = I2C_C1_IICIE_MASK, /*!< I2C global interrupt. */
101
102 #if defined(FSL_FEATURE_I2C_HAS_STOP_DETECT) && FSL_FEATURE_I2C_HAS_STOP_DETECT
103 kI2C_StopDetectInterruptEnable = I2C_FLT_STOPIE_MASK, /*!< I2C stop detect interrupt. */
104 #endif /* FSL_FEATURE_I2C_HAS_STOP_DETECT */
105
106 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
107 kI2C_StartStopDetectInterruptEnable = I2C_FLT_SSIE_MASK, /*!< I2C start&stop detect interrupt. */
108 #endif /* FSL_FEATURE_I2C_HAS_START_STOP_DETECT */
109 };
110
111 /*! @brief The direction of master and slave transfers. */
112 typedef enum _i2c_direction
113 {
114 kI2C_Write = 0x0U, /*!< Master transmits to the slave. */
115 kI2C_Read = 0x1U, /*!< Master receives from the slave. */
116 } i2c_direction_t;
117
118 /*! @brief Addressing mode. */
119 typedef enum _i2c_slave_address_mode
120 {
121 kI2C_Address7bit = 0x0U, /*!< 7-bit addressing mode. */
122 kI2C_RangeMatch = 0X2U, /*!< Range address match addressing mode. */
123 } i2c_slave_address_mode_t;
124
125 /*! @brief I2C transfer control flag. */
126 enum _i2c_master_transfer_flags
127 {
128 kI2C_TransferDefaultFlag = 0x0U, /*!< A transfer starts with a start signal, stops with a stop signal. */
129 kI2C_TransferNoStartFlag = 0x1U, /*!< A transfer starts without a start signal. */
130 kI2C_TransferRepeatedStartFlag = 0x2U, /*!< A transfer starts with a repeated start signal. */
131 kI2C_TransferNoStopFlag = 0x4U, /*!< A transfer ends without a stop signal. */
132 };
133
134 /*!
135 * @brief Set of events sent to the callback for nonblocking slave transfers.
136 *
137 * These event enumerations are used for two related purposes. First, a bit mask created by OR'ing together
138 * events is passed to I2C_SlaveTransferNonBlocking() to specify which events to enable.
139 * Then, when the slave callback is invoked, it is passed the current event through its @a transfer
140 * parameter.
141 *
142 * @note These enumerations are meant to be OR'd together to form a bit mask of events.
143 */
144 typedef enum _i2c_slave_transfer_event
145 {
146 kI2C_SlaveAddressMatchEvent = 0x01U, /*!< Received the slave address after a start or repeated start. */
147 kI2C_SlaveTransmitEvent = 0x02U, /*!< A callback is requested to provide data to transmit
148 (slave-transmitter role). */
149 kI2C_SlaveReceiveEvent = 0x04U, /*!< A callback is requested to provide a buffer in which to place received
150 data (slave-receiver role). */
151 kI2C_SlaveTransmitAckEvent = 0x08U, /*!< A callback needs to either transmit an ACK or NACK. */
152 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
153 kI2C_SlaveStartEvent = 0x10U, /*!< A start/repeated start was detected. */
154 #endif
155 kI2C_SlaveCompletionEvent = 0x20U, /*!< A stop was detected or finished transfer, completing the transfer. */
156 kI2C_SlaveGenaralcallEvent = 0x40U, /*!< Received the general call address after a start or repeated start. */
157
158 /*! A bit mask of all available events. */
159 kI2C_SlaveAllEvents = kI2C_SlaveAddressMatchEvent | kI2C_SlaveTransmitEvent | kI2C_SlaveReceiveEvent |
160 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
161 kI2C_SlaveStartEvent |
162 #endif
163 kI2C_SlaveCompletionEvent | kI2C_SlaveGenaralcallEvent,
164 } i2c_slave_transfer_event_t;
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 Sets the I2C master configuration structure to default values.
345 *
346 * The purpose of this API is to get the configuration structure initialized for use in the I2C_MasterConfigure().
347 * Use the initialized structure unchanged in the I2C_MasterConfigure() or modify
348 * the structure before calling the I2C_MasterConfigure().
349 * This is an example.
350 * @code
351 * i2c_master_config_t config;
352 * I2C_MasterGetDefaultConfig(&config);
353 * @endcode
354 * @param masterConfig A pointer to the master configuration structure.
355 */
356 void I2C_MasterGetDefaultConfig(i2c_master_config_t *masterConfig);
357
358 /*!
359 * @brief Sets the I2C slave configuration structure to default values.
360 *
361 * The purpose of this API is to get the configuration structure initialized for use in the I2C_SlaveConfigure().
362 * Modify fields of the structure before calling the I2C_SlaveConfigure().
363 * This is an example.
364 * @code
365 * i2c_slave_config_t config;
366 * I2C_SlaveGetDefaultConfig(&config);
367 * @endcode
368 * @param slaveConfig A pointer to the slave configuration structure.
369 */
370 void I2C_SlaveGetDefaultConfig(i2c_slave_config_t *slaveConfig);
371
372 /*!
373 * @brief Enables or disabless the I2C peripheral operation.
374 *
375 * @param base I2C base pointer
376 * @param enable Pass true to enable and false to disable the module.
377 */
I2C_Enable(I2C_Type * base,bool enable)378 static inline void I2C_Enable(I2C_Type *base, bool enable)
379 {
380 if (enable)
381 {
382 base->C1 |= I2C_C1_IICEN_MASK;
383 }
384 else
385 {
386 base->C1 &= ~I2C_C1_IICEN_MASK;
387 }
388 }
389
390 /* @} */
391
392 /*!
393 * @name Status
394 * @{
395 */
396
397 /*!
398 * @brief Gets the I2C status flags.
399 *
400 * @param base I2C base pointer
401 * @return status flag, use status flag to AND #_i2c_flags to get the related status.
402 */
403 uint32_t I2C_MasterGetStatusFlags(I2C_Type *base);
404
405 /*!
406 * @brief Gets the I2C status flags.
407 *
408 * @param base I2C base pointer
409 * @return status flag, use status flag to AND #_i2c_flags to get the related status.
410 */
I2C_SlaveGetStatusFlags(I2C_Type * base)411 static inline uint32_t I2C_SlaveGetStatusFlags(I2C_Type *base)
412 {
413 return I2C_MasterGetStatusFlags(base);
414 }
415
416 /*!
417 * @brief Clears the I2C status flag state.
418 *
419 * The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag.
420 *
421 * @param base I2C base pointer
422 * @param statusMask The status flag mask, defined in type i2c_status_flag_t.
423 * The parameter can be any combination of the following values:
424 * @arg kI2C_StartDetectFlag (if available)
425 * @arg kI2C_StopDetectFlag (if available)
426 * @arg kI2C_ArbitrationLostFlag
427 * @arg kI2C_IntPendingFlagFlag
428 */
I2C_MasterClearStatusFlags(I2C_Type * base,uint32_t statusMask)429 static inline void I2C_MasterClearStatusFlags(I2C_Type *base, uint32_t statusMask)
430 {
431 /* Must clear the STARTF / STOPF bits prior to clearing IICIF */
432 #if defined(FSL_FEATURE_I2C_HAS_START_STOP_DETECT) && FSL_FEATURE_I2C_HAS_START_STOP_DETECT
433 if (statusMask & kI2C_StartDetectFlag)
434 {
435 /* Shift the odd-ball flags back into place. */
436 base->FLT |= (uint8_t)(statusMask >> 8U);
437 }
438 #endif
439
440 #ifdef I2C_HAS_STOP_DETECT
441 if (statusMask & kI2C_StopDetectFlag)
442 {
443 /* Shift the odd-ball flags back into place. */
444 base->FLT |= (uint8_t)(statusMask >> 8U);
445 }
446 #endif
447
448 base->S = (uint8_t)statusMask;
449 }
450
451 /*!
452 * @brief Clears the I2C status flag state.
453 *
454 * The following status register flags can be cleared kI2C_ArbitrationLostFlag and kI2C_IntPendingFlag
455 *
456 * @param base I2C base pointer
457 * @param statusMask The status flag mask, defined in type i2c_status_flag_t.
458 * The parameter can be any combination of the following values:
459 * @arg kI2C_StartDetectFlag (if available)
460 * @arg kI2C_StopDetectFlag (if available)
461 * @arg kI2C_ArbitrationLostFlag
462 * @arg kI2C_IntPendingFlagFlag
463 */
I2C_SlaveClearStatusFlags(I2C_Type * base,uint32_t statusMask)464 static inline void I2C_SlaveClearStatusFlags(I2C_Type *base, uint32_t statusMask)
465 {
466 I2C_MasterClearStatusFlags(base, statusMask);
467 }
468
469 /* @} */
470
471 /*!
472 * @name Interrupts
473 * @{
474 */
475
476 /*!
477 * @brief Enables I2C interrupt requests.
478 *
479 * @param base I2C base pointer
480 * @param mask interrupt source
481 * The parameter can be combination of the following source if defined:
482 * @arg kI2C_GlobalInterruptEnable
483 * @arg kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable
484 * @arg kI2C_SdaTimeoutInterruptEnable
485 */
486 void I2C_EnableInterrupts(I2C_Type *base, uint32_t mask);
487
488 /*!
489 * @brief Disables I2C interrupt requests.
490 *
491 * @param base I2C base pointer
492 * @param mask interrupt source
493 * The parameter can be combination of the following source if defined:
494 * @arg kI2C_GlobalInterruptEnable
495 * @arg kI2C_StopDetectInterruptEnable/kI2C_StartDetectInterruptEnable
496 * @arg kI2C_SdaTimeoutInterruptEnable
497 */
498 void I2C_DisableInterrupts(I2C_Type *base, uint32_t mask);
499
500 /*!
501 * @name DMA Control
502 * @{
503 */
504 #if defined(FSL_FEATURE_I2C_HAS_DMA_SUPPORT) && FSL_FEATURE_I2C_HAS_DMA_SUPPORT
505 /*!
506 * @brief Enables/disables the I2C DMA interrupt.
507 *
508 * @param base I2C base pointer
509 * @param enable true to enable, false to disable
510 */
I2C_EnableDMA(I2C_Type * base,bool enable)511 static inline void I2C_EnableDMA(I2C_Type *base, bool enable)
512 {
513 if (enable)
514 {
515 base->C1 |= I2C_C1_DMAEN_MASK;
516 }
517 else
518 {
519 base->C1 &= ~I2C_C1_DMAEN_MASK;
520 }
521 }
522
523 #endif /* FSL_FEATURE_I2C_HAS_DMA_SUPPORT */
524
525 /*!
526 * @brief Gets the I2C tx/rx data register address. This API is used to provide a transfer address
527 * for I2C DMA transfer configuration.
528 *
529 * @param base I2C base pointer
530 * @return data register address
531 */
I2C_GetDataRegAddr(I2C_Type * base)532 static inline uint32_t I2C_GetDataRegAddr(I2C_Type *base)
533 {
534 return (uint32_t)(&(base->D));
535 }
536
537 /* @} */
538 /*!
539 * @name Bus Operations
540 * @{
541 */
542
543 /*!
544 * @brief Sets the I2C master transfer baud rate.
545 *
546 * @param base I2C base pointer
547 * @param baudRate_Bps the baud rate value in bps
548 * @param srcClock_Hz Source clock
549 */
550 void I2C_MasterSetBaudRate(I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz);
551
552 /*!
553 * @brief Sends a START on the I2C bus.
554 *
555 * This function is used to initiate a new master mode transfer by sending the START signal.
556 * The slave address is sent following the I2C START signal.
557 *
558 * @param base I2C peripheral base pointer
559 * @param address 7-bit slave device address.
560 * @param direction Master transfer directions(transmit/receive).
561 * @retval kStatus_Success Successfully send the start signal.
562 * @retval kStatus_I2C_Busy Current bus is busy.
563 */
564 status_t I2C_MasterStart(I2C_Type *base, uint8_t address, i2c_direction_t direction);
565
566 /*!
567 * @brief Sends a STOP signal on the I2C bus.
568 *
569 * @retval kStatus_Success Successfully send the stop signal.
570 * @retval kStatus_I2C_Timeout Send stop signal failed, timeout.
571 */
572 status_t I2C_MasterStop(I2C_Type *base);
573
574 /*!
575 * @brief Sends a REPEATED START on the I2C bus.
576 *
577 * @param base I2C peripheral base pointer
578 * @param address 7-bit slave device address.
579 * @param direction Master transfer directions(transmit/receive).
580 * @retval kStatus_Success Successfully send the start signal.
581 * @retval kStatus_I2C_Busy Current bus is busy but not occupied by current I2C master.
582 */
583 status_t I2C_MasterRepeatedStart(I2C_Type *base, uint8_t address, i2c_direction_t direction);
584
585 /*!
586 * @brief Performs a polling send transaction on the I2C bus.
587 *
588 * @param base The I2C peripheral base pointer.
589 * @param txBuff The pointer to the data to be transferred.
590 * @param txSize The length in bytes of the data to be transferred.
591 * @param flags Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag
592 * to issue a stop and kI2C_TransferNoStop to not send a stop.
593 * @retval kStatus_Success Successfully complete the data transmission.
594 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
595 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
596 */
597 status_t I2C_MasterWriteBlocking(I2C_Type *base, const uint8_t *txBuff, size_t txSize, uint32_t flags);
598
599 /*!
600 * @brief Performs a polling receive transaction on the I2C bus.
601 *
602 * @note The I2C_MasterReadBlocking function stops the bus before reading the final byte.
603 * Without stopping the bus prior for the final read, the bus issues another read, resulting
604 * in garbage data being read into the data register.
605 *
606 * @param base I2C peripheral base pointer.
607 * @param rxBuff The pointer to the data to store the received data.
608 * @param rxSize The length in bytes of the data to be received.
609 * @param flags Transfer control flag to decide whether need to send a stop, use kI2C_TransferDefaultFlag
610 * to issue a stop and kI2C_TransferNoStop to not send a stop.
611 * @retval kStatus_Success Successfully complete the data transmission.
612 * @retval kStatus_I2C_Timeout Send stop signal failed, timeout.
613 */
614 status_t I2C_MasterReadBlocking(I2C_Type *base, uint8_t *rxBuff, size_t rxSize, uint32_t flags);
615
616 /*!
617 * @brief Performs a polling send transaction on the I2C bus.
618 *
619 * @param base The I2C peripheral base pointer.
620 * @param txBuff The pointer to the data to be transferred.
621 * @param txSize The length in bytes of the data to be transferred.
622 * @retval kStatus_Success Successfully complete the data transmission.
623 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
624 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
625 */
626 status_t I2C_SlaveWriteBlocking(I2C_Type *base, const uint8_t *txBuff, size_t txSize);
627
628 /*!
629 * @brief Performs a polling receive transaction on the I2C bus.
630 *
631 * @param base I2C peripheral base pointer.
632 * @param rxBuff The pointer to the data to store the received data.
633 * @param rxSize The length in bytes of the data to be received.
634 */
635 void I2C_SlaveReadBlocking(I2C_Type *base, uint8_t *rxBuff, size_t rxSize);
636
637 /*!
638 * @brief Performs a master polling transfer on the I2C bus.
639 *
640 * @note The API does not return until the transfer succeeds or fails due
641 * to arbitration lost or receiving a NAK.
642 *
643 * @param base I2C peripheral base address.
644 * @param xfer Pointer to the transfer structure.
645 * @retval kStatus_Success Successfully complete the data transmission.
646 * @retval kStatus_I2C_Busy Previous transmission still not finished.
647 * @retval kStatus_I2C_Timeout Transfer error, wait signal timeout.
648 * @retval kStatus_I2C_ArbitrationLost Transfer error, arbitration lost.
649 * @retval kStataus_I2C_Nak Transfer error, receive NAK during transfer.
650 */
651 status_t I2C_MasterTransferBlocking(I2C_Type *base, i2c_master_transfer_t *xfer);
652
653 /* @} */
654
655 /*!
656 * @name Transactional
657 * @{
658 */
659
660 /*!
661 * @brief Initializes the I2C handle which is used in transactional functions.
662 *
663 * @param base I2C base pointer.
664 * @param handle pointer to i2c_master_handle_t structure to store the transfer state.
665 * @param callback pointer to user callback function.
666 * @param userData user parameter passed to the callback function.
667 */
668 void I2C_MasterTransferCreateHandle(I2C_Type *base,
669 i2c_master_handle_t *handle,
670 i2c_master_transfer_callback_t callback,
671 void *userData);
672
673 /*!
674 * @brief Performs a master interrupt non-blocking transfer on the I2C bus.
675 *
676 * @note Calling the API returns immediately after transfer initiates. The user needs
677 * to call I2C_MasterGetTransferCount to poll the transfer status to check whether
678 * the transfer is finished. If the return status is not kStatus_I2C_Busy, the transfer
679 * is finished.
680 *
681 * @param base I2C base pointer.
682 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state.
683 * @param xfer pointer to i2c_master_transfer_t structure.
684 * @retval kStatus_Success Successfully start the data transmission.
685 * @retval kStatus_I2C_Busy Previous transmission still not finished.
686 * @retval kStatus_I2C_Timeout Transfer error, wait signal timeout.
687 */
688 status_t I2C_MasterTransferNonBlocking(I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_t *xfer);
689
690 /*!
691 * @brief Gets the master transfer status during a interrupt non-blocking transfer.
692 *
693 * @param base I2C base pointer.
694 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state.
695 * @param count Number of bytes transferred so far by the non-blocking transaction.
696 * @retval kStatus_InvalidArgument count is Invalid.
697 * @retval kStatus_Success Successfully return the count.
698 */
699 status_t I2C_MasterTransferGetCount(I2C_Type *base, i2c_master_handle_t *handle, size_t *count);
700
701 /*!
702 * @brief Aborts an interrupt non-blocking transfer early.
703 *
704 * @note This API can be called at any time when an interrupt non-blocking transfer initiates
705 * to abort the transfer early.
706 *
707 * @param base I2C base pointer.
708 * @param handle pointer to i2c_master_handle_t structure which stores the transfer state
709 */
710 void I2C_MasterTransferAbort(I2C_Type *base, i2c_master_handle_t *handle);
711
712 /*!
713 * @brief Master interrupt handler.
714 *
715 * @param base I2C base pointer.
716 * @param i2cHandle pointer to i2c_master_handle_t structure.
717 */
718 void I2C_MasterTransferHandleIRQ(I2C_Type *base, void *i2cHandle);
719
720 /*!
721 * @brief Initializes the I2C handle which is used in transactional functions.
722 *
723 * @param base I2C base pointer.
724 * @param handle pointer to i2c_slave_handle_t structure to store the transfer state.
725 * @param callback pointer to user callback function.
726 * @param userData user parameter passed to the callback function.
727 */
728 void I2C_SlaveTransferCreateHandle(I2C_Type *base,
729 i2c_slave_handle_t *handle,
730 i2c_slave_transfer_callback_t callback,
731 void *userData);
732
733 /*!
734 * @brief Starts accepting slave transfers.
735 *
736 * Call this API after calling the I2C_SlaveInit() and I2C_SlaveTransferCreateHandle() to start processing
737 * transactions driven by an I2C master. The slave monitors the I2C bus and passes events to the
738 * callback that was passed into the call to I2C_SlaveTransferCreateHandle(). The callback is always invoked
739 * from the interrupt context.
740 *
741 * The set of events received by the callback is customizable. To do so, set the @a eventMask parameter to
742 * the OR'd combination of #i2c_slave_transfer_event_t enumerators for the events you wish to receive.
743 * The #kI2C_SlaveTransmitEvent and #kLPI2C_SlaveReceiveEvent events are always enabled and do not need
744 * to be included in the mask. Alternatively, pass 0 to get a default set of only the transmit and
745 * receive events that are always enabled. In addition, the #kI2C_SlaveAllEvents constant is provided as
746 * a convenient way to enable all events.
747 *
748 * @param base The I2C peripheral base address.
749 * @param handle Pointer to #i2c_slave_handle_t structure which stores the transfer state.
750 * @param eventMask Bit mask formed by OR'ing together #i2c_slave_transfer_event_t enumerators to specify
751 * which events to send to the callback. Other accepted values are 0 to get a default set of
752 * only the transmit and receive events, and #kI2C_SlaveAllEvents to enable all events.
753 *
754 * @retval #kStatus_Success Slave transfers were successfully started.
755 * @retval #kStatus_I2C_Busy Slave transfers have already been started on this handle.
756 */
757 status_t I2C_SlaveTransferNonBlocking(I2C_Type *base, i2c_slave_handle_t *handle, uint32_t eventMask);
758
759 /*!
760 * @brief Aborts the slave transfer.
761 *
762 * @note This API can be called at any time to stop slave for handling the bus events.
763 *
764 * @param base I2C base pointer.
765 * @param handle pointer to i2c_slave_handle_t structure which stores the transfer state.
766 */
767 void I2C_SlaveTransferAbort(I2C_Type *base, i2c_slave_handle_t *handle);
768
769 /*!
770 * @brief Gets the slave transfer remaining bytes during a interrupt non-blocking transfer.
771 *
772 * @param base I2C base pointer.
773 * @param handle pointer to i2c_slave_handle_t structure.
774 * @param count Number of bytes transferred so far by the non-blocking transaction.
775 * @retval kStatus_InvalidArgument count is Invalid.
776 * @retval kStatus_Success Successfully return the count.
777 */
778 status_t I2C_SlaveTransferGetCount(I2C_Type *base, i2c_slave_handle_t *handle, size_t *count);
779
780 /*!
781 * @brief Slave interrupt handler.
782 *
783 * @param base I2C base pointer.
784 * @param i2cHandle pointer to i2c_slave_handle_t structure which stores the transfer state
785 */
786 void I2C_SlaveTransferHandleIRQ(I2C_Type *base, void *i2cHandle);
787
788 /* @} */
789 #if defined(__cplusplus)
790 }
791 #endif /*_cplusplus. */
792 /*@}*/
793
794 #endif /* _FSL_I2C_H_*/
795