ADuCM302x Device Drivers API Reference Manual
Release 3.1.2.0
|
Inter-Integrated Circuit (I2C) Driver. More...
Modules | |
Static Configuration | |
Data Structures | |
struct | ADI_I2C_TRANSACTION |
Macros | |
#define | ADI_I2C_MEMORY_SIZE (44u + ADI_SEM_SIZE) |
#define | ADI_I2C_MAX_RATE (400000u) |
Typedefs | |
typedef struct __ADI_I2C_DEV_DATA_TYPE * | ADI_I2C_HANDLE |
Functions | |
ADI_I2C_RESULT | adi_i2c_Open (uint32_t const DeviceNum, void *const pMemory, uint32_t const MemorySize, ADI_I2C_HANDLE *const phDevice) |
Initialize and allocate an I2C device for use in Master Mode. More... | |
ADI_I2C_RESULT | adi_i2c_Close (ADI_I2C_HANDLE const hDevice) |
Uninitialize and deallocate an I2C device. More... | |
ADI_I2C_RESULT | adi_i2c_ReadWrite (ADI_I2C_HANDLE const hDevice, ADI_I2C_TRANSACTION *const pTransaction, uint32_t *const pHwErrors) |
Blocking I2C Master-Mode data read/write API. More... | |
ADI_I2C_RESULT | adi_i2c_SubmitBuffer (ADI_I2C_HANDLE const hDevice, ADI_I2C_TRANSACTION *const pTransaction) |
Non-Blocking I2C Master-Mode data read or data write API. More... | |
ADI_I2C_RESULT | adi_i2c_IsBufferAvailable (ADI_I2C_HANDLE const hDevice, bool *const pbCompletionState) |
Query if a non-blocking I2C transfer is complete. More... | |
ADI_I2C_RESULT | adi_i2c_GetBuffer (ADI_I2C_HANDLE const hDevice, uint32_t *const pHwErrors) |
Request ownership of a submitted buffer. More... | |
ADI_I2C_RESULT | adi_i2c_Reset (ADI_I2C_HANDLE const hDevice) |
Reset an I2C device and driver instance. More... | |
ADI_I2C_RESULT | adi_i2c_SetBitRate (ADI_I2C_HANDLE const hDevice, uint32_t const requestedBitRate32) |
Set the I2C serial bus speed. More... | |
ADI_I2C_RESULT | adi_i2c_SetSlaveAddress (ADI_I2C_HANDLE const hDevice, uint16_t const SlaveAddress) |
Set the I2C serial bus slave address. More... | |
ADI_I2C_RESULT | adi_i2c_IssueGeneralCall (ADI_I2C_HANDLE const hDevice, uint8_t *const pData, uint8_t const nDataSize, uint32_t *const pHwErrors) |
Transmit a General Call command to all slave devices on the I2C bus. More... | |
Inter-Integrated Circuit (I2C) Driver.
The I2C Master device driver manages the on-chip I2C hardware to control the external two-wire I2C Bus interface, allowing communication with multiple I2C slave devices through the I2C slave device addressing scheme.
#define ADI_I2C_MEMORY_SIZE (44u + ADI_SEM_SIZE) |
#define ADI_I2C_MAX_RATE (400000u) |
Maximum supported bitrate is "FAST" mode (400 kHz).
Definition at line 210 of file adi_i2c.h.
Referenced by adi_i2c_SetBitRate().
typedef struct __ADI_I2C_DEV_DATA_TYPE* ADI_I2C_HANDLE |
enum ADI_I2C_RESULT |
I2C Device Error Codes. ADI_I2C_SUCCESS is always zero The return value of all I2C APIs returning ADI_I2C_RESULT should always be tested at the application level for success or failure. Specific I2C bus error conditions are returned as elements of ADI_I2C_RESULT.
Enumerator | |
---|---|
ADI_I2C_SUCCESS | The API call succeeded. |
ADI_I2C_BAD_BITRATE | The bit rate is invalid. |
ADI_I2C_BAD_DEVICE_HANDLE | The device handle is invalid. |
ADI_I2C_BAD_DEVICE_NUMBER | The device number is invalid. |
ADI_I2C_BAD_SYS_CLOCK | Unable to obtain system clock rate. |
ADI_I2C_DEVICE_IN_USE | The device is in use. |
ADI_I2C_DEVICE_NOT_OPEN | The device is not open. |
ADI_I2C_FAILURE | Generic API failure code. |
ADI_I2C_HW_ERROR_DETECTED | An I2C hardware error occurred. See ADI_I2C_HW_ERRORS. |
ADI_I2C_INSUFFICIENT_MEMORY | The application supplied memory size is insufficient. |
ADI_I2C_INVALID_PARAMETER | An invalid parameter is passed to the function. |
ADI_I2C_INVALID_SLAVE_ADDRESS | The application supplied slave address is too wide. |
ADI_I2C_INVALID_SUBMIT_API | Unmatched read/write vs. submit/get API call. |
ADI_I2C_SEMAPHORE_FAILED | Semaphore operation failed. |
enum ADI_I2C_HW_ERRORS |
I2C Device Hardware Error Codes. Contains one or more hardware (I2C protocol) errors. Use this enum to decode hardware errors when the main ADI_I2C_RESULT return result value is ADI_I2C_HW_ERROR_DETECTED.
ADI_I2C_RESULT adi_i2c_Open | ( | uint32_t const | DeviceNum, |
void *const | pMemory, | ||
uint32_t const | MemorySize, | ||
ADI_I2C_HANDLE *const | phDevice | ||
) |
Initialize and allocate an I2C device for use in Master Mode.
[in] | DeviceNum | Zero-based device index designating the I2C device to initialize. |
[in] | pMemory | Pointer to a 32-bit aligned buffer of size ADI_I2C_MEMORY_SIZE required by the driver for the operation of specified I2C device. |
[in] | MemorySize | Size of the buffer to which "pMemory" points. |
[out] | phDevice | The caller's device handle pointer for storing the initialized device instance data pointer. |
Initialize an I2C device using default user configuration settings (from adi_i2c_config.h) and allocate the device for use. Device is opened in Master mode only.
No other I2C APIs may be called until the device open function is called. The returned device handle is required to be passed to all subsequent I2C API calls to identify the physical device instance to use. The user device handle (pointed to by phDevice) is set to NULL on failure.
ADI_I2C_RESULT adi_i2c_Close | ( | ADI_I2C_HANDLE const | hDevice | ) |
Uninitialize and deallocate an I2C device.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
Uninitialize and release an allocated I2C device, and memory associated with it for other use.
ADI_I2C_RESULT adi_i2c_ReadWrite | ( | ADI_I2C_HANDLE const | hDevice, |
ADI_I2C_TRANSACTION *const | pTransaction, | ||
uint32_t *const | pHwErrors | ||
) |
Blocking I2C Master-Mode data read/write API.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pTransaction | Pointer to I2C transaction data struct. |
[out] | pHwErrors | Pointer to hardware error return variable. |
Request a blocking I2C data transfer (read or write, not both as I2C is unidirectional bus) with or without preceding prologue transmitted. Control is not returned to the calling application until the transfer is complete. Buffer allocations are made by the calling code (the application).
The optional prologue (if present) and MANDATORY transaction data pointers are used to read or write data over the I2C serial bus according to the prologue and data pointers and corresponding size information contained in the pTransaction parameter block. The most recently set slave target address (set statically with user configuration settings contained in adi_i2c_config.h file or set dynamically (at run-time) via the adi_i2c_SetSlaveAddress() API) is used to address the specific destination slave device on the I2C bus.
If present, the prologue (typically, an addressing phase conveying a memory/register address or slave device command) is transmitted prior to the data read or write phase, with or without an intervening I2C STOP condition. The prologue data is entirely slave device dependent.
In the case of a prologue followed by a data read operation, the I2C bus direction must be reversed following the prologue transmit. In this case, The usual I2C STOP condition following the prologue (if present) transmit may be suppressed by setting the bRepeatStart transaction parameter "true". In this case, a second (repeat) START condition is "transmitted" between the addressing phase (prologue transmit) and the data phase of the read sequence... without an intervening STOP condition. This is commonly referred to as the "combined format" in which the I2C bus direction is reversed halfway through the transaction without releasing control of the I2C bus arbitration. The REPEAT-START condition is a common I2C bus protocol required by many I2C slave devices.
In the case of a prologue followed by a data write operation, there is no need to turn the bus around and so the bRepeatStart parameter is ignored.
Definition at line 355 of file adi_i2c.c.
Referenced by adi_i2c_IssueGeneralCall().
ADI_I2C_RESULT adi_i2c_SubmitBuffer | ( | ADI_I2C_HANDLE const | hDevice, |
ADI_I2C_TRANSACTION *const | pTransaction | ||
) |
Non-Blocking I2C Master-Mode data read or data write API.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pTransaction | Pointer to I2C transaction data struct. |
Request a non-blocking I2C data transfer (read or write) with or without preceding prologue transmitted. Control is returned to the calling application immediately, allowing the application process other tasks. The transaction result code is retrieved by adi_i2c_GetBuffer().
The application may optionally poll the I2C driver via the adi_i2c_IsBufferAvailable() API while the transaction is underway to determine if and when the submitted transaction is complete. Eventually, the application MUST call the MANDATORY adi_i2c_GetBuffer() API to obtain the transaction result and complete the transaction. Buffer allocations are made by the calling code (the application).
The adi_i2c_GetBuffer() API may be called at any time, even if the transaction is incomplete; the adi_i2c_GetBuffer() call will simply block in incomplete transactions until the transaction does complete... at which point adi_i2c_GetBuffer() returns control with the transaction result code. Submitting background transactions is useful if the application has housekeeping chores to perform when the I2C transaction is started, but later the application decides to just block until the transaction is complete.
The prologue and data buffers are handled as they are in the blocking adi_i2c_ReadWrite() call, it's just that the adi_i2c_SubmitBuffer() API does not block on the data phase.
ADI_I2C_RESULT adi_i2c_IsBufferAvailable | ( | ADI_I2C_HANDLE const | hDevice, |
bool *const | pbCompletionState | ||
) |
Query if a non-blocking I2C transfer is complete.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[out] | pbCompletionState | Pointer to Boolean into which the I2C bus state is written. |
Sets the application-provided Boolean variable pointed to by pbCompletionState either:
This API is used in conjunction with a non-blocking adi_i2c_SubmitBuffer() transfer to determine when the transaction is complete. Typically, non-blocking calls are used when the calling application has other work to do while I2C controller serializes data over the I2C bus, which is an interrupt-driven process. The transaction is submitted as a non-blocking call and the submitting API returns immediately, allowing the calling application to perform its other tasks. The I2C driver services the interrupts to transfer data while the application performs its other tasks.
Non-blocking calls can be polled with this API for completion, or if the application has completed its other tasks and wants to just wait on the I2C completion without further polling, it may call the associated adi_i2c_GetBuffer() API to convert the currently unblocked transaction to a blocking one.
ADI_I2C_RESULT adi_i2c_GetBuffer | ( | ADI_I2C_HANDLE const | hDevice, |
uint32_t *const | pHwErrors | ||
) |
Request ownership of a submitted buffer.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[out] | pHwErrors | Pointer to hardware error return variable. |
This is a potentially blocking MANDATORY call that the application MUST use to reclaim ownership of any "submitted" transaction (submitted via a previous adi_i2c_SubmitBuffer() call) and obtain the transaction success/failure result code. This API blocks until the transaction is complete and returns the transaction result code. If the transaction is already complete, the blocking is trivial and control is returned immediately.
Non-blocking calls can also be (optionally) polled with the non-blocking adi_i2c_IsBufferAvailable() API to see if and when the transaction is complete.
The adi_i2c_GetBuffer() call is a MANDATORY compliment to adi_i2c_SubmitBuffer() and allows the I2C driver to synchronize its internal blocking object.
ADI_I2C_RESULT adi_i2c_Reset | ( | ADI_I2C_HANDLE const | hDevice | ) |
Reset an I2C device and driver instance.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
Reset the I2C physical controller and device driver internals.
ADI_I2C_RESULT adi_i2c_SetBitRate | ( | ADI_I2C_HANDLE const | hDevice, |
uint32_t const | requestedBitRate32 | ||
) |
Set the I2C serial bus speed.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | requestedBitRate32 | Requested I2C bus clock rate (in Hz). |
Sets the I2C bus clock speed to the requested user parameter, requestedBitRate.
ADI_I2C_RESULT adi_i2c_SetSlaveAddress | ( | ADI_I2C_HANDLE const | hDevice, |
uint16_t const | SlaveAddress | ||
) |
Set the I2C serial bus slave address.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | SlaveAddress | New 7-bit address for targeting a slave device. |
Sets the 7-bit (unformatted) slave address for which all subsequent I2C bus traffic is directed. Read/write address formatting is performed by the driver, depending on bus direction.
ADI_I2C_RESULT adi_i2c_IssueGeneralCall | ( | ADI_I2C_HANDLE const | hDevice, |
uint8_t *const | pData, | ||
uint8_t const | nDataSize, | ||
uint32_t *const | pHwErrors | ||
) |
Transmit a General Call command to all slave devices on the I2C bus.
[in] | hDevice | Device handle obtained from adi_spi_Open(). |
[in] | pData | Pointer to data buffer to transmit. |
[in] | nDataSize | Size of data buffer to transmit. |
[out] | pHwErrors | Pointer to hardware error return variable. |
Broadcasts the given command buffer across the I2C bus to reserved General Call (GC) address (address zero). All, some, or none of the slave devices on the I2C bus will respond, depending on their capabilities. All responding slave devices will process the GC command according to their capabilities.
The GC command is a blocking transaction.
The application is responsible for formatting the GC command into the data buffer according to various Philips Semiconductor (now, NXP) documents, such as the 2014 Revision 6 document: "UM10204 I2C-Bus Specification and User Manual" (see www.nxp.com/documents/user_manual/UM10204.pdf).
No prologue precedes the GC command data; the GC command data is transmitted verbatim.