ADuCM302x Device Drivers API Reference Manual  Release 3.1.2.0
I2C Driver

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
 

Enumerations

enum  ADI_I2C_RESULT {
  ADI_I2C_SUCCESS = 0,
  ADI_I2C_BAD_BITRATE,
  ADI_I2C_BAD_DEVICE_HANDLE,
  ADI_I2C_BAD_DEVICE_NUMBER,
  ADI_I2C_BAD_SYS_CLOCK,
  ADI_I2C_DEVICE_IN_USE,
  ADI_I2C_DEVICE_NOT_OPEN,
  ADI_I2C_FAILURE,
  ADI_I2C_HW_ERROR_DETECTED,
  ADI_I2C_INSUFFICIENT_MEMORY,
  ADI_I2C_INVALID_PARAMETER,
  ADI_I2C_INVALID_SLAVE_ADDRESS,
  ADI_I2C_INVALID_SUBMIT_API,
  ADI_I2C_SEMAPHORE_FAILED
}
 
enum  ADI_I2C_HW_ERRORS {
  ADI_I2C_HW_ERROR_NONE = 0,
  ADI_I2C_HW_ERROR_NACK_ADDR = 0x0001,
  ADI_I2C_HW_ERROR_NACK_DATA = 0x0002,
  ADI_I2C_HW_ERROR_ARBITRATION_LOST = 0x0004,
  ADI_I2C_HW_ERROR_UNEXPECTED_ERROR = 0x0008
}
 

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...
 

Detailed Description

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.

Note
The application must include drivers/i2c/adi_i2c.h to use this driver
This documentation presented here is API documentation only. The device drive user's guide, located in the Documents folder, explains how to use these APIs in an application.

Macro Definition Documentation

◆ ADI_I2C_MEMORY_SIZE

#define ADI_I2C_MEMORY_SIZE   (44u + ADI_SEM_SIZE)

Use macro "ADI_I2C_MEMORY_SIZE" to know how much memory to provide the i2c driver during the "adi_i2c_Open()" driver initialization call. This memory is used to store internal driver state data. Use map file to verify.

Definition at line 134 of file adi_i2c.h.

◆ ADI_I2C_MAX_RATE

#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 Documentation

◆ ADI_I2C_HANDLE

typedef struct __ADI_I2C_DEV_DATA_TYPE* ADI_I2C_HANDLE

A device handle used in all API functions to identify the I2C device.

Definition at line 127 of file adi_i2c.h.

Enumeration Type Documentation

◆ 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.

Definition at line 86 of file adi_i2c.h.

◆ 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.

Enumerator
ADI_I2C_HW_ERROR_NONE 

No hardware error.

ADI_I2C_HW_ERROR_NACK_ADDR 

A no-acknowledgement occurred for the address.

ADI_I2C_HW_ERROR_NACK_DATA 

A no-acknowledgement occurred for the data.

ADI_I2C_HW_ERROR_ARBITRATION_LOST 

I2C bus arbitration was Lost.

ADI_I2C_HW_ERROR_UNEXPECTED_ERROR 

An unexpected error occurred.

Definition at line 115 of file adi_i2c.h.

Function Documentation

◆ adi_i2c_Open()

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.

Parameters
[in]DeviceNumZero-based device index designating the I2C device to initialize.
[in]pMemoryPointer to a 32-bit aligned buffer of size ADI_I2C_MEMORY_SIZE required by the driver for the operation of specified I2C device.
[in]MemorySizeSize of the buffer to which "pMemory" points.
[out]phDeviceThe caller's device handle pointer for storing the initialized device instance data pointer.
Returns
Status

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.

Note
Currently, only a singular I2C physical device instance (device ID "0") exists.
See also
adi_spi_Close().

Definition at line 181 of file adi_i2c.c.

◆ adi_i2c_Close()

ADI_I2C_RESULT adi_i2c_Close ( ADI_I2C_HANDLE const  hDevice)

Uninitialize and deallocate an I2C device.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
Returns
Status

Uninitialize and release an allocated I2C device, and memory associated with it for other use.

Note
The user memory is released from use by the I2C driver, but is not freed.
See also
adi_spi_Open().

Definition at line 278 of file adi_i2c.c.

◆ adi_i2c_ReadWrite()

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.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[in]pTransactionPointer to I2C transaction data struct.
[out]pHwErrorsPointer to hardware error return variable.
Returns
Status

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.

Note
Application must check the return code to verify if any I2C Bus errors occurred. Hardware errors (I2C Protocol errors) are indicated with the ADI_I2C_HW_ERROR_DETECTED return code, and the set of hardware errors (enum ADI_I2C_HW_ERRORS) that occurred (there may be multiple) are indicated in the value set to user variable pointed to by pHwErrors.
See also
adi_i2c_SetSlaveAddress().
adi_i2c_SubmitBuffer().
adi_i2c_IsBufferAvailable().
adi_i2c_GetBuffer().
ADI_I2C_TRANSACTION.
ADI_I2C_HW_ERRORS.

Definition at line 355 of file adi_i2c.c.

Referenced by adi_i2c_IssueGeneralCall().

◆ adi_i2c_SubmitBuffer()

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.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[in]pTransactionPointer to I2C transaction data struct.
Returns
Status

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.

Note
The non-blocking adi_i2c_SubmitBuffer() call REQUIRES a matching adi_i2c_GetBuffer() call to obtain the final transaction result code and to inform the driver that the application wants to regain ownership of the buffers. The application should be prepared to wait for this ownership until the current transaction completes. The matching adi_i2c_GetBuffer() call is required even if the transaction may have already completed. The adi_i2c_GetBuffer() call allows the driver to block on completion or error events and then synchronize its internal blocking object. The intermediate adi_i2c_IsBufferAvailable() API is optional.

The adi_i2c_SubmitBuffer() API is singular, i.e., only a single transaction may be submitted at a time. Simultaneous submits (e.g., ping-pong mode) are not supported by the I2C driver.
See also
adi_i2c_ReadWrite().
adi_i2c_SetSlaveAddress().
adi_i2c_IsBufferAvailable().
adi_i2c_GetBuffer().
ADI_I2C_TRANSACTION.

Definition at line 450 of file adi_i2c.c.

◆ adi_i2c_IsBufferAvailable()

ADI_I2C_RESULT adi_i2c_IsBufferAvailable ( ADI_I2C_HANDLE const  hDevice,
bool *const  pbCompletionState 
)

Query if a non-blocking I2C transfer is complete.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[out]pbCompletionStatePointer to Boolean into which the I2C bus state is written.
Returns
Status

Sets the application-provided Boolean variable pointed to by pbCompletionState either:

  • true, when the non-blocking transactions is complete, or
  • false, while the non-blocking transactions is still underway.

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.

Note
This API is inappropriate in context of blocking calls to adi_i2c_ReadWrite().
See also
adi_i2c_ReadWrite().
adi_i2c_SubmitBuffer().
adi_i2c_GetBuffer().
ADI_I2C_TRANSACTION.

Definition at line 511 of file adi_i2c.c.

◆ adi_i2c_GetBuffer()

ADI_I2C_RESULT adi_i2c_GetBuffer ( ADI_I2C_HANDLE const  hDevice,
uint32_t *const  pHwErrors 
)

Request ownership of a submitted buffer.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[out]pHwErrorsPointer to hardware error return variable.
Returns
Status

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.

Note
Application must check the return code to verify if any I2C Bus errors occurred. Hardware errors (I2C Protocol errors) are indicated with the ADI_I2C_HW_ERROR_DETECTED return code, and the set of hardware errors (enum ADI_I2C_HW_ERRORS) that occurred (there may be multiple) are indicated in the value set to user variable pointed to by pHwErrors.
See also
adi_i2c_ReadWrite().
adi_i2c_SubmitBuffer().
adi_i2c_IsBufferAvailable().
ADI_I2C_TRANSACTION.
ADI_I2C_HW_ERRORS.

Definition at line 570 of file adi_i2c.c.

◆ adi_i2c_Reset()

ADI_I2C_RESULT adi_i2c_Reset ( ADI_I2C_HANDLE const  hDevice)

Reset an I2C device and driver instance.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
Returns
Status

Reset the I2C physical controller and device driver internals.

Definition at line 613 of file adi_i2c.c.

◆ adi_i2c_SetBitRate()

ADI_I2C_RESULT adi_i2c_SetBitRate ( ADI_I2C_HANDLE const  hDevice,
uint32_t const  requestedBitRate32 
)

Set the I2C serial bus speed.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[in]requestedBitRate32Requested I2C bus clock rate (in Hz).
Returns
Status

Sets the I2C bus clock speed to the requested user parameter, requestedBitRate.

Note
Any I2C Bus clock rate may be requested up to and including the "FAST" mode I2C clock rate (400 kHz), including the "STANDARD" mode (100 kHz). Faster clock rates beyond "FAST" mode (e.g., "FAST+" or "HIGH-SPEED" modes) are not supported by the hardware. Slower clock rates below approximately 55 kHz (assuming a 26 MHz system clock) are physically unrealizable due to the fixed 8-bit field-width of the 8-bit I2C clock rate divide register.

Default clock rate may be specified statically in the default user configuration file, "adi_i2c_config.h".

Definition at line 656 of file adi_i2c.c.

◆ adi_i2c_SetSlaveAddress()

ADI_I2C_RESULT adi_i2c_SetSlaveAddress ( ADI_I2C_HANDLE const  hDevice,
uint16_t const  SlaveAddress 
)

Set the I2C serial bus slave address.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[in]SlaveAddressNew 7-bit address for targeting a slave device.
Returns
Status

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.

Note
This driver does not support the I2C 10-bit extended addressing scheme.

Default slave address may be specified statically in the default user configuration file, "adi_i2c_config.h".

Definition at line 735 of file adi_i2c.c.

◆ adi_i2c_IssueGeneralCall()

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.

Parameters
[in]hDeviceDevice handle obtained from adi_spi_Open().
[in]pDataPointer to data buffer to transmit.
[in]nDataSizeSize of data buffer to transmit.
[out]pHwErrorsPointer to hardware error return variable.
Returns
Status

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.

Note
The currently active slave address is saved and restored when transmitting GC commands to the reserved GC address (address zero).

Definition at line 789 of file adi_i2c.c.