2 * Copyright (c) 2015-2016, Texas Instruments Incorporated
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 /*!*****************************************************************************
35 * @brief I2C driver interface
37 * The I2C driver interface provides device independent APIs, data types,
38 * and macros. The I2C header file should be included in an application as
41 * #include <ti/drivers/I2C.h>
45 * This section assumes that you have background knowledge and understanding
46 * about how the I2C protocol operates. For the full I2C specifications and
47 * user manual (UM10204), see the NXP Semiconductors website.
49 * The I2C driver has been designed to operate as a single I2C master by
50 * performing I2C transactions between the target and I2C slave peripherals.
51 * The I2C driver does not support I2C slave mode.
52 * I2C is a communication protocol - the specifications define how data
53 * transactions are to occur via the I2C bus. The specifications do not
54 * define how data is to be formatted or handled, allowing for flexible
55 * implementations across different peripheral vendors. As a result, the
56 * I2C handles only the exchange of data (or transactions) between master
57 * and slaves. It is the left to the application to interpret and
58 * manipulate the contents of each specific I2C peripheral.
60 * The I2C driver has been designed to operate in an RTOS environment. It
61 * protects its transactions with OS primitives supplied by the underlying
66 * The I2C driver includes the following APIs:
67 * - I2C_init(): Initialize the I2C driver.
68 * - I2C_Params_init(): Initialize an #I2C_Params structure with default
70 * - I2C_open(): Open an instance of the I2C driver.
71 * - I2C_control(): Performs implemenation-specific features on a given
73 * - I2C_transfer(): Transfer the data.
74 * - I2C_close(): De-initialize the I2C instance.
77 * ### I2C Driver Configuration #
79 * In order to use the I2C APIs, the application is required
80 * to provide device-specific I2C configuration in the Board.c file.
81 * The I2C driver interface defines a configuration data structure:
84 * typedef struct I2C_Config_ {
85 * I2C_FxnTable const *fxnTablePtr;
87 * void const *hwAttrs;
91 * The application must declare an array of I2C_Config elements, named
92 * I2C_config[]. Each element of I2C_config[] must be populated with
93 * pointers to a device specific I2C driver implementation's function
94 * table, driver object, and hardware attributes. The hardware attributes
95 * define properties such as the I2C peripheral's base address and
96 * pins. Each element in I2C_config[] corresponds to
97 * an I2C instance, and none of the elements should have NULL pointers.
98 * There is no correlation between the index and the
99 * peripheral designation (such as I2C0 or I2C1). For example, it is
100 * possible to use I2C_config[0] for I2C1.
102 * Because the I2C configuration is very device dependent, you will need to
103 * check the doxygen for the device specific I2C implementation. There you
104 * will find a description of the I2C hardware attributes. Please also
105 * refer to the Board.c file of any of your examples to see the I2C
108 * ### Initializing the I2C Driver #
110 * I2C_init() must be called before any other I2C APIs. This function
111 * iterates through the elements of the I2C_config[] array, calling
112 * the element's device implementation I2C initialization function.
116 * The #I2C_Params structure is passed to the I2C_open() call. If NULL
117 * is passed for the parameters, I2C_open() uses default parameters.
118 * An #I2C_Params structure is initialized with default values by passing
119 * it to I2C_Params_init().
120 * Some of the I2C parameters are described below. To see brief descriptions
121 * of all the parameters, see #I2C_Params.
123 * #### I2C Transfer Mode
124 * The I2C driver supports two transfer modes of operation: blocking and
126 * - #I2C_MODE_BLOCKING: The call to I2C_transfer() blocks until the
127 * transfer completes.
128 * - #I2C_MODE_CALLBACK: The call to I2C_transfer() returns immediately.
129 * When the transfer completes, the I2C driver will call a user-
130 * specified callback function.
132 * The transfer mode is determined by the #I2C_Params.transferMode parameter
133 * passed to I2C_open(). The I2C driver defaults to blocking mode, if the
134 * application does not set it.
136 * In blocking mode, a task calling I2C_transfer() is blocked until the
137 * transaction completes. Other tasks requesting I2C transactions while
138 * a transaction is currently taking place, are also placed into a
141 * In callback mode, an I2C_transfer() functions asynchronously, which
142 * means that it does not block a calling task's execution. In this
143 * mode, the user must set #I2C_Params.transferCallbackFxn to a user-
144 * provided callback function. After an I2C transaction has completed,
145 * the I2C driver calls the user- provided callback function.
146 * If another I2C transaction is requested, the transaction is queued up.
147 * As each transfer completes, the I2C driver will call the user-specified
148 * callback function. The user callback will be called from either hardware
149 * or software interrupt context, depending upon the device implementation.
151 * Once an I2C driver instance is opened, the
152 * only way to change the transfer mode is to close and re-open the I2C
153 * instance with the new transfer mode.
155 * #### Specifying an I2C Bus Frequency
156 * The I2C controller's bus frequency is determined by #I2C_Params.bitRate
157 * passed to I2C_open(). The standard I2C bus frequencies are 100 kHz and
158 * 400 kHz, with 100 kHz being the default.
160 * ### Opening the I2C Driver #
161 * After initializing the I2C driver by calling I2C_init(), the application
162 * can open an I2C instance by calling I2C_open(). This function
163 * takes an index into the I2C_config[] array and an I2C parameters data
164 * structure. The I2C instance is specified by the index of the I2C in
165 * I2C_config[]. Only one I2C index can be used at a time;
166 * calling I2C_open() a second time with the same index previosly
167 * passed to I2C_open() will result in an error. You can,
168 * though, re-use the index if the instance is closed via I2C_close().
170 * If no I2C_Params structure is passed to I2C_open(), default values are
171 * used. If the open call is successful, it returns a non-NULL value.
173 * Example opening an I2C driver instance in blocking mode:
177 * // NULL params are used, so default to blocking mode, 100 KHz
178 * i2c = I2C_open(Board_I2C0, NULL);
181 * // Error opening the I2C
185 * Example opening an I2C driver instance in callback mode and 400KHz bit rate:
191 * I2C_Params_init(¶ms);
192 * params.transferMode = I2C_MODE_CALLBACK;
193 * params.transferCallbackFxn = myCallbackFunction;
194 * params.bitRate = I2C_400kHz;
196 * handle = I2C_open(Board_I2C0, ¶ms);
198 * // Error opening I2C
202 * ### Transferring data #
203 * An I2C transaction with an I2C peripheral is started by calling
204 * I2C_transfer(). Three types of transactions are supported: Write, Read,
205 * or Write/Read. Each transfer is completed before another transfer is
208 * For Write/Read transactions, the specified data is first written to the
209 * peripheral, then a repeated start is sent by the driver, which initiates
210 * the read operation. This type of transfer is useful if an I2C peripheral
211 * has a pointer register that needs to be adjusted prior to reading from
212 * the referenced data register.
214 * The details of each transaction are specified with an #I2C_Transaction data
215 * structure. This structure defines the slave I2C address, pointers
216 * to write and read buffers, and their associated byte counts. If
217 * no data needs to be written or read, the corresponding byte counts should
220 * If an I2C transaction is requested while a transaction is currently
221 * taking place, the new transaction is placed onto a queue to be processed
222 * in the order in which it was received.
224 * The below example shows sending three bytes of data to a slave peripheral
225 * at address 0x50, in blocking mode:
228 * unsigned char writeBuffer[3];
229 * I2C_Transaction i2cTransaction;
231 * i2cTransaction.slaveAddress = 0x50;
232 * i2cTransaction.writeBuf = writeBuffer;
233 * i2cTransaction.writeCount = 3;
234 * i2cTransaction.readBuf = NULL;
235 * i2cTransaction.readCount = 0;
237 * status = I2C_transfer(i2c, &i2cTransaction);
239 * // Unsuccessful I2C transfer
243 * The next example shows reading of five bytes of data from the I2C
244 * peripheral, also in blocking mode:
247 * unsigned char readBuffer[5];
248 * I2C_Transaction i2cTransaction;
250 * i2cTransaction.slaveAddress = 0x50;
251 * i2cTransaction.writeBuf = NULL;
252 * i2cTransaction.writeCount = 0;
253 * i2cTransaction.readBuf = readBuffer;
254 * i2cTransaction.readCount = 5;
256 * status = I2C_transfer(i2c, &i2cTransaction);
258 * // Unsuccessful I2C transfer
262 * This example shows writing of two bytes and reading of four bytes in a
263 * single transaction.
266 * unsigned char readBuffer[4];
267 * unsigned char writeBuffer[2];
268 * I2C_Transaction i2cTransaction;
270 * i2cTransaction.slaveAddress = 0x50;
271 * i2cTransaction.writeBuf = writeBuffer;
272 * i2cTransaction.writeCount = 2;
273 * i2cTransaction.readBuf = readBuffer;
274 * i2cTransaction.readCount = 4;
276 * status = I2C_transfer(i2c, &i2cTransaction);
278 * // Unsuccessful I2C transfer
282 * This final example shows usage of asynchronous callback mode, with queuing
283 * of multiple transactions. Because multiple transactions are simultaneously
284 * queued, separate I2C_Transaction structures must be used. (This is a
285 * general rule, that I2C_Transaction structures cannot be reused until
286 * it is known that the previous transaction has completed.)
288 * First, for the callback function (that is specified in the I2C_open() call)
289 * the "arg" in the I2C_Transaction structure is a SemaphoreP_Handle; when
290 * this value is non-NULL, SemaphoreP_post() is called in the callback using
291 * the specified handle, to signal completion to the task that queued the
295 * Void callbackFxn(I2C_Handle handle, I2C_Transaction *msg, Bool transfer) {
296 * if (msg->arg != NULL) {
297 * SemaphoreP_post((SemaphoreP_Handle)(msg->arg));
302 * Snippets of the task code that initiates the transactions are shown below.
303 * Note the use of multiple I2C_Transaction structures, and passing of the
304 * handle of the semaphore to be posted via i2cTransaction2.arg.
305 * I2C_transfer() is called three times to initiate each transaction.
306 * Since callback mode is used, these functions return immediately. After
307 * the transactions have been queued, other work can be done, and then
308 * eventually SemaphoreP_pend() is called to wait for the last I2C
309 * transaction to complete. Once the callback posts the semaphore, the task
310 * will be moved to the ready state, so the task can resume execution, after
311 * the SemaphoreP_pend() call.
314 * Void taskfxn(arg0, arg1) {
316 * I2C_Transaction i2cTransaction0;
317 * I2C_Transaction i2cTransaction1;
318 * I2C_Transaction i2cTransaction2;
321 * i2cTransaction0.arg = NULL;
322 * i2cTransaction1.arg = NULL;
323 * i2cTransaction2.arg = semaphoreHandle;
326 * I2C_transfer(i2c, &i2cTransaction0);
327 * I2C_transfer(i2c, &i2cTransaction1);
328 * I2C_transfer(i2c, &i2cTransaction2);
332 * SemaphoreP_pend(semaphoreHandle);
340 * This top-level I2C module serves as the main interface for RTOS
341 * applications. Its purpose is to redirect the module's APIs to specific
342 * peripheral implementations which are specified using a pointer to an
345 * The I2C driver interface module is joined (at link time) to an
346 * array of I2C_Config data structures named *I2C_config*.
347 * *I2C_config* is typically defined in the Board.c file used for the
348 * application. If there are multiple instances of I2C peripherals on the
349 * device, there will typically be multiple I2C_Config structures defined in
350 * the board file. Each entry in *I2C_config* contains a:
351 * - (I2C_FxnTable *) to a set of functions that implement a I2C peripheral
352 * - (void *) data object that is associated with the I2C_FxnTable
353 * - (void *) hardware attributes that are associated to the I2C_FxnTable
355 *******************************************************************************
358 #ifndef ti_drivers_I2C__include
359 #define ti_drivers_I2C__include
370 * @defgroup I2C_CONTROL I2C_control command and status codes
371 * These I2C macros are reservations for I2C.h
376 * Common I2C_control command code reservation offset.
377 * I2C driver implementations should offset command codes with I2C_CMD_RESERVED
380 * Example implementation specific command codes:
382 * #define I2CXYZ_CMD_COMMAND0 I2C_CMD_RESERVED + 0
383 * #define I2CXYZ_CMD_COMMAND1 I2C_CMD_RESERVED + 1
386 #define I2C_CMD_RESERVED (32)
389 * Common I2C_control status code reservation offset.
390 * I2C driver implementations should offset status codes with
391 * I2C_STATUS_RESERVED growing negatively.
393 * Example implementation specific status codes:
395 * #define I2CXYZ_STATUS_ERROR0 I2C_STATUS_RESERVED - 0
396 * #define I2CXYZ_STATUS_ERROR1 I2C_STATUS_RESERVED - 1
397 * #define I2CXYZ_STATUS_ERROR2 I2C_STATUS_RESERVED - 2
400 #define I2C_STATUS_RESERVED (-32)
403 * @defgroup I2C_STATUS Status Codes
404 * I2C_STATUS_* macros are general status codes returned by I2C_control()
406 * @ingroup I2C_CONTROL
410 * @brief Successful status code returned by I2C_control().
412 * I2C_control() returns I2C_STATUS_SUCCESS if the control code was executed
415 #define I2C_STATUS_SUCCESS (0)
418 * @brief Generic error status code returned by I2C_control().
420 * I2C_control() returns I2C_STATUS_ERROR if the control code was not executed
423 #define I2C_STATUS_ERROR (-1)
426 * @brief An error status code returned by I2C_control() for undefined
429 * I2C_control() returns I2C_STATUS_UNDEFINEDCMD if the control code is not
430 * recognized by the driver implementation.
432 #define I2C_STATUS_UNDEFINEDCMD (-2)
436 * @defgroup I2C_CMD Command Codes
437 * I2C_CMD_* macros are general command codes for I2C_control(). Not all I2C
438 * driver implementations support these command codes.
440 * @ingroup I2C_CONTROL
443 /* Add I2C_CMD_<commands> here */
450 * @brief A handle that is returned from an I2C_open() call.
452 typedef struct I2C_Config_ *I2C_Handle;
455 * @brief I2C transaction
457 * This structure defines an I2C transaction. It specifies the buffer(s) and
458 * buffer size(s) to be written to and/or read from an I2C slave peripheral.
459 * arg is an optional user-supplied argument that will be passed
460 * to the user-supplied callback function when the I2C driver is in
462 * nextPtr is a pointer used internally by the driver for queuing of multiple
463 * transactions; this value must never be modified by the user application.
465 typedef struct I2C_Transaction_ {
466 void *writeBuf; /*!< Buffer containing data to be written */
467 size_t writeCount; /*!< Number of bytes to be written to the slave */
469 void *readBuf; /*!< Buffer to which data is to be read into */
470 size_t readCount; /*!< Number of bytes to be read from the slave */
472 uint_least8_t slaveAddress; /*!< Address of the I2C slave peripheral */
474 void *arg; /*!< Argument to be passed to the callback function */
475 void *nextPtr; /*!< Used for queuing in I2C_MODE_CALLBACK mode */
479 * @brief I2C transfer mode
481 * I2C_MODE_BLOCKING blocks task execution while an I2C transfer is in
483 * I2C_MODE_CALLBACK does not block task execution, but calls a callback
484 * function when the I2C transfer has completed.
486 typedef enum I2C_TransferMode_ {
487 I2C_MODE_BLOCKING, /*!< I2C_transfer() blocks execution */
488 I2C_MODE_CALLBACK /*!< I2C_transfer() does not block */
492 * @brief I2C callback function
494 * User-definable callback function prototype. The I2C driver will call this
495 * callback upon transfer completion, specifying the I2C handle for the
496 * transfer (as returned from I2C_open()), the pointer to the I2C_Transaction
497 * that just completed, and the return value of I2C_transfer(). Note that
498 * this return value will be the same as if the transfer were performed in
501 * @param I2C_Handle I2C_Handle
503 * @param I2C_Transaction* Address of the I2C_Transaction
505 * @param bool Result of the I2C transfer
507 typedef void (*I2C_CallbackFxn)(I2C_Handle handle, I2C_Transaction *transaction,
508 bool transferStatus);
513 * Specifies one of the standard I2C bus bit rates for I2C communications.
514 * The default is I2C_100kHz.
516 typedef enum I2C_BitRate_ {
522 * @brief I2C Parameters
524 * I2C parameters are used with the I2C_open() call. Default values for
525 * these parameters are set using I2C_Params_init().
527 * If I2C_TransferMode is set to I2C_MODE_BLOCKING, I2C_transfer() function
528 * calls will block thread execution until the transaction has completed. In
529 * this case, the transferCallbackFxn parameter will be ignored.
531 * If I2C_TransferMode is set to I2C_MODE_CALLBACK, I2C_transfer() will not
532 * block thread execution, but it will call the function specified by
533 * transferCallbackFxn upon transfer completion. Sequential calls to
534 * I2C_transfer() in I2C_MODE_CALLBACK will put the I2C_Transaction structures
535 * onto an internal queue that automatically starts queued transactions after
536 * the previous transaction has completed. This queuing occurs regardless of
537 * any error state from previous transactions.
539 * I2C_BitRate specifies the I2C bus rate used for I2C communications.
541 * @sa I2C_Params_init()
543 typedef struct I2C_Params_ {
544 I2C_TransferMode transferMode; /*!< Blocking or Callback mode */
545 I2C_CallbackFxn transferCallbackFxn; /*!< Callback function pointer */
546 I2C_BitRate bitRate; /*!< I2C bus bit rate */
547 void *custom; /*!< Custom argument used by driver
552 * @brief A function pointer to a driver-specific implementation of
555 typedef void (*I2C_CancelFxn) (I2C_Handle handle);
558 * @brief A function pointer to a driver-specific implementation of
561 typedef void (*I2C_CloseFxn) (I2C_Handle handle);
564 * @brief A function pointer to a driver-specific implementation of
567 typedef int_fast16_t (*I2C_ControlFxn) (I2C_Handle handle, uint_fast16_t cmd,
571 * @brief A function pointer to a driver-specific implementation of
574 typedef void (*I2C_InitFxn) (I2C_Handle handle);
577 * @brief A function pointer to a driver-specific implementation of
580 typedef I2C_Handle (*I2C_OpenFxn) (I2C_Handle handle, I2C_Params *params);
583 * @brief A function pointer to a driver-specific implementation of
586 typedef bool (*I2C_TransferFxn) (I2C_Handle handle,
587 I2C_Transaction *transaction);
590 * @brief The definition of an I2C function table that contains the
591 * required set of functions to control a specific I2C driver
594 typedef struct I2C_FxnTable_ {
595 /*! Cancel all I2C data transfers */
596 I2C_CancelFxn cancelFxn;
598 /*! Close the specified peripheral */
599 I2C_CloseFxn closeFxn;
601 /*! Implementation-specific control function */
602 I2C_ControlFxn controlFxn;
604 /*! Initialize the given data object */
607 /*! Open the specified peripheral */
610 /*! Initiate an I2C data transfer */
611 I2C_TransferFxn transferFxn;
615 * @brief I2C global configuration
617 * The I2C_Config structure contains a set of pointers used to characterize
618 * the I2C driver implementation.
620 * This structure needs to be defined before calling I2C_init() and it must
621 * not be changed thereafter.
625 typedef struct I2C_Config_ {
626 /*! Pointer to a table of driver-specific implementations of I2C APIs */
627 I2C_FxnTable const *fxnTablePtr;
629 /*! Pointer to a driver-specific data object */
632 /*! Pointer to a driver-specific hardware attributes structure */
637 * @brief Cancel all I2C transfers
639 * This function will cancel asynchronous I2C_transfer() operations, and is
640 * applicable only for I2C_MODE_CALLBACK. An in progress transfer, as well
641 * as any queued transfers will be canceled. The individual callback functions
642 * for each transfer will be called from the context that I2C_cancel() is
645 * @pre I2C_Transfer() has been called.
647 * @param handle An I2C_Handle returned from I2C_open()
649 * @note Different I2C slave devices will behave differently when an
650 * in-progress transfer fails and needs to be canceled. The slave
651 * may need to be reset, or there may be other slave-specific
652 * steps that can be used to successfully resume communication.
656 extern void I2C_cancel(I2C_Handle handle);
659 * @brief Close an I2C peripheral specified by an I2C_Handle
661 * @pre I2C_open() has been called.
663 * @param handle An I2C_Handle returned from I2C_open()
667 extern void I2C_close(I2C_Handle handle);
670 * @brief Perform implementation-specific features on a given
673 * Commands for I2C_control() can originate from I2C.h or from implementation
674 * specific I2C*.h (I2CCC26XX.h_, I2CMSP432.h_, etc.) files.
675 * While commands from I2C.h are API portable across driver implementations,
676 * not all implementations may support all these commands.
677 * Conversely, commands from driver implementation specific I2C*.h files add
678 * unique driver capabilities but are not API portable across all I2C driver
681 * Commands supported by I2C.h follow a I2C_CMD_\<cmd\> naming
683 * Commands supported by I2C*.h follow a I2C*_CMD_\<cmd\> naming
685 * Each control command defines @b arg differently. The types of @b arg are
686 * documented with each command.
688 * See @ref I2C_CMD "I2C_control command codes" for command codes.
690 * See @ref I2C_STATUS "I2C_control return status codes" for status codes.
692 * @pre I2C_open() has to be called first.
694 * @param handle An I2C_Handle returned from I2C_open()
696 * @param cmd I2C.h or I2C*.h command.
698 * @param controlArg An optional R/W (read/write) command argument
699 * accompanied with cmd
701 * @return Implementation-specific return codes. Negative values indicate
702 * unsuccessful operations.
706 extern int_fast16_t I2C_control(I2C_Handle handle, uint_fast16_t cmd,
710 * @brief Initializes the I2C module
712 * @pre The I2C_config structure must exist and be persistent before this
713 * function can be called. This function must also be called before
714 * any other I2C driver APIs. This function call does not modify any
715 * peripheral registers.
717 extern void I2C_init(void);
720 * @brief Initialize a given I2C peripheral as identified by an index value.
721 * The I2C_Params structure defines the operating mode, and any
724 * @pre The I2C controller has been initialized, via a previous call to
727 * @param index Logical peripheral number for the I2C indexed into
728 * the I2C_config table
730 * @param params Pointer to a parameter block. Default values will be
731 * used if NULL is specified for params. All the fields
732 * in this structure are are considered RO (read-only).
734 * @return An I2C_Handle on success, or NULL on an error, or if the peripheral
740 extern I2C_Handle I2C_open(uint_least8_t index, I2C_Params *params);
743 * @brief Initialize an I2C_Params struct to its defaults
745 * @param params A pointer to I2C_Params structure for
748 * Defaults values are:
749 * transferMode = I2C_MODE_BLOCKING
750 * transferCallbackFxn = NULL
751 * bitRate = I2C_100kHz
753 extern void I2C_Params_init(I2C_Params *params);
756 * @brief Perform an I2C transaction with an I2C slave peripheral.
758 * This function will perform an I2C transfer, as specified by an
759 * I2C_Transaction structure.
761 * An I2C transaction may write data to a peripheral, or read data from a
762 * peripheral, or both write and read data, in a single transaction. If there
763 * is any data to be written, it will always be sent before any data is read
764 * from the peripheral.
766 * The data written to the peripheral is preceded with the peripheral's 7-bit
767 * I2C slave address (with the Write bit set).
768 * After all the data has been transmitted, the driver will evaluate if any
769 * data needs to be read from the device.
770 * If yes, another START bit is sent, along with the same 7-bit I2C slave
771 * address (with the Read bit). After the specified number of bytes have been
772 * read, the transfer is ended with a NACK and a STOP bit. Otherwise, if
773 * no data is to be read, the transfer is concluded with a STOP bit.
775 * In I2C_MODE_BLOCKING, I2C_transfer() will block thread execution until the
776 * transaction completes. Therefore, this function must only be called from an
777 * appropriate thread context (e.g., Task context for the TI-RTOS kernel).
779 * In I2C_MODE_CALLBACK, the I2C_transfer() call does not block thread
780 * execution. Instead, a callback function (specified during I2C_open(), via
781 * the transferCallbackFxn field in the I2C_Params structure) is called when
782 * the transfer completes. Success or failure of the transaction is reported
783 * via the callback function's bool argument. If a transfer is already in
784 * progress, the new transaction is put on an internal queue. The driver
785 * services the queue in a first come first served basis.
787 * @param handle An I2C_Handle
789 * @param transaction A pointer to an I2C_Transaction. All of the fields
790 * within the transaction structure should be considered
791 * write only, unless otherwise noted in the driver
794 * @note The I2C_Transaction structure must persist unmodified until the
795 * corresponding call to I2C_transfer() has completed.
797 * @return In I2C_MODE_BLOCKING: true for a successful transfer; false for an
798 * error (for example, an I2C bus fault (NACK)).
800 * In I2C_MODE_CALLBACK: always true. The transferCallbackFxn's bool
801 * argument will be true to indicate success, and false to indicate
806 extern bool I2C_transfer(I2C_Handle handle, I2C_Transaction *transaction);
812 #endif /* ti_drivers_I2C__include */