![]() |
CMSIS-Driver
Version 2.02
Peripheral Interface for Middleware and Application Code
|
Driver API for I2C Bus Peripheral (Driver_I2C.h) More...
Content | |
I2C Events | |
The I2C driver generates call back events that are notified via the function ARM_I2C_SignalEvent. | |
I2C Control Codes | |
Many parameters of the I2C driver are configured using the ARM_I2C_Control function. | |
I2C Address Flags | |
Specify address flags. | |
Data Structures | |
struct | ARM_DRIVER_I2C |
Access structure of the I2C Driver. More... | |
struct | ARM_I2C_CAPABILITIES |
I2C Driver Capabilities. More... | |
struct | ARM_I2C_STATUS |
I2C Status. More... | |
Typedefs | |
typedef void(* | ARM_I2C_SignalEvent_t )(uint32_t event) |
Pointer to ARM_I2C_SignalEvent : Signal I2C Event. | |
Functions | |
ARM_DRIVER_VERSION | ARM_I2C_GetVersion (void) |
Get driver version. | |
ARM_I2C_CAPABILITIES | ARM_I2C_GetCapabilities (void) |
Get driver capabilities. | |
int32_t | ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event) |
Initialize I2C Interface. | |
int32_t | ARM_I2C_Uninitialize (void) |
De-initialize I2C Interface. | |
int32_t | ARM_I2C_PowerControl (ARM_POWER_STATE state) |
Control I2C Interface Power. | |
int32_t | ARM_I2C_MasterTransmit (uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending) |
Start transmitting data as I2C Master. | |
int32_t | ARM_I2C_MasterReceive (uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) |
Start receiving data as I2C Master. | |
int32_t | ARM_I2C_SlaveTransmit (const uint8_t *data, uint32_t num) |
Start transmitting data as I2C Slave. | |
int32_t | ARM_I2C_SlaveReceive (uint8_t *data, uint32_t num) |
Start receiving data as I2C Slave. | |
int32_t | ARM_I2C_GetDataCount (void) |
Get transferred data count. | |
int32_t | ARM_I2C_Control (uint32_t control, uint32_t arg) |
Control I2C Interface. | |
ARM_I2C_STATUS | ARM_I2C_GetStatus (void) |
Get I2C status. | |
void | ARM_I2C_SignalEvent (uint32_t event) |
Signal I2C Events. | |
Driver API for I2C Bus Peripheral (Driver_I2C.h)
I2C (Inter-Integrated Circuit, referred to as I-squared-C, I-two-C, or IIC) is a multimaster serial single-ended bus used for attaching low-speed peripherals to a motherboard, embedded system, cellphone, or other electronic device. I2C is used mostly on single boards, but can also to connect components which are linked via cable.
Most significant features of the I2C bus include:
Wikipedia offers more information about the I2C.
I2C API
The following header files define the Application Programming Interface (API) for the I2C interface:
The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.
Driver Functions
The driver functions are published in the access struct as explained in Driver Functions
Example Code
The following example code shows the usage of the I2C interface.
struct ARM_DRIVER_I2C |
Access structure of the I2C Driver.
The functions of the I2C interface are accessed by function pointers exposed by this structure. Refer to Driver Functions for overview information.
Each instance of an I2C provides such an access structure. The instance is indicated by a postfix in the symbol name of the access structure, for example:
A configuration setting in the middleware allows connecting the middleware to a specific driver instance Driver_I2Cn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRIVER_VERSION(* | GetVersion )(void) |
Pointer to ARM_I2C_GetVersion : Get driver version. | |
ARM_I2C_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_I2C_GetCapabilities : Get driver capabilities. | |
int32_t(* | Initialize )(ARM_I2C_SignalEvent_t cb_event) |
Pointer to ARM_I2C_Initialize : Initialize I2C Interface. | |
int32_t(* | Uninitialize )(void) |
Pointer to ARM_I2C_Uninitialize : De-initialize I2C Interface. | |
int32_t(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_I2C_PowerControl : Control I2C Interface Power. | |
int32_t(* | MasterTransmit )(uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending) |
Pointer to ARM_I2C_MasterTransmit : Start transmitting data as I2C Master. | |
int32_t(* | MasterReceive )(uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) |
Pointer to ARM_I2C_MasterReceive : Start receiving data as I2C Master. | |
int32_t(* | SlaveTransmit )(const uint8_t *data, uint32_t num) |
Pointer to ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave. | |
int32_t(* | SlaveReceive )(uint8_t *data, uint32_t num) |
Pointer to ARM_I2C_SlaveReceive : Start receiving data as I2C Slave. | |
int32_t(* | GetDataCount )(void) |
Pointer to ARM_I2C_GetDataCount : Get transferred data count. | |
int32_t(* | Control )(uint32_t control, uint32_t arg) |
Pointer to ARM_I2C_Control : Control I2C Interface. | |
ARM_I2C_STATUS(* | GetStatus )(void) |
Pointer to ARM_I2C_GetStatus : Get I2C status. | |
int32_t(* Control)(uint32_t control, uint32_t arg) |
Pointer to ARM_I2C_Control : Control I2C Interface.
ARM_I2C_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_I2C_GetCapabilities : Get driver capabilities.
int32_t(* GetDataCount)(void) |
Pointer to ARM_I2C_GetDataCount : Get transferred data count.
ARM_I2C_STATUS(* GetStatus)(void) |
Pointer to ARM_I2C_GetStatus : Get I2C status.
ARM_DRIVER_VERSION(* GetVersion)(void) |
Pointer to ARM_I2C_GetVersion : Get driver version.
int32_t(* Initialize)(ARM_I2C_SignalEvent_t cb_event) |
Pointer to ARM_I2C_Initialize : Initialize I2C Interface.
int32_t(* MasterReceive)(uint32_t addr, uint8_t *data, uint32_t num, bool xfer_pending) |
Pointer to ARM_I2C_MasterReceive : Start receiving data as I2C Master.
int32_t(* MasterTransmit)(uint32_t addr, const uint8_t *data, uint32_t num, bool xfer_pending) |
Pointer to ARM_I2C_MasterTransmit : Start transmitting data as I2C Master.
int32_t(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_I2C_PowerControl : Control I2C Interface Power.
int32_t(* SlaveReceive)(uint8_t *data, uint32_t num) |
Pointer to ARM_I2C_SlaveReceive : Start receiving data as I2C Slave.
int32_t(* SlaveTransmit)(const uint8_t *data, uint32_t num) |
Pointer to ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave.
int32_t(* Uninitialize)(void) |
Pointer to ARM_I2C_Uninitialize : De-initialize I2C Interface.
struct ARM_I2C_CAPABILITIES |
I2C Driver Capabilities.
An I2C driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.
The element address_10_bit indicates that the driver is able to handle 10-bit addressing natively. User can still emulate the 10-bit addressing in software if the driver does not support it.
Returned by:
Data Fields | ||
---|---|---|
uint32_t | address_10_bit: 1 | supports 10-bit addressing |
struct ARM_I2C_STATUS |
I2C Status.
Structure with information about the status of the I2C.
The flag busy indicates that the driver is busy executing Master/Slave Transmit/Receive operation.
It is set:
It is cleared when Master/Slave operation has finished.
The flag mode indicates the current mode which is Master when Master Transmit/Receive is active or Slave otherwise.
The flag direction indicates either Transmitter or Receiver mode. It is updated during Master/Slave operation when the Slave is addressed by a Master.
The flag general_call indicates a General call (address 0) when in Slave mode.
The flag arbitration_lost indicates that the Master has lost arbitration. The current Master operation is aborted.
The flag bus_error indicates that a bus error has been detected. The current Master/Slave operation is aborted.
Returned by:
ARM_I2C_SignalEvent_t |
Pointer to ARM_I2C_SignalEvent : Signal I2C Event.
Provides the typedef for the callback function ARM_I2C_SignalEvent.
Parameter for:
int32_t ARM_I2C_Control | ( | uint32_t | control, |
uint32_t | arg | ||
) |
Control I2C Interface.
[in] | control | Operation |
[in] | arg | Argument of operation (optional) |
Controls the I2C interface settings and executes various operations.
The function ARM_I2C_Control controls the I2C interface settings and executes various operations. It is registered by the function ARM_I2C_Initialize.
The parameter control specifies various parameters with the ARM_I2C_xxx values (see table below). Depending on the control value, the parameter arg provides additional information.
Control Bits | Description |
---|---|
ARM_I2C_OWN_ADDRESS | Set Own Slave Address; arg = slave own address |
ARM_I2C_BUS_SPEED | Set the Bus Speed; arg = bus speed |
ARM_I2C_BUS_CLEAR | Clear the bus by sending nine clock pulses |
ARM_I2C_ABORT_TRANSFER | Aborts the data transfer between Master and Slave for Transmit or Receive |
The function ARM_I2C_Control with control = ARM_I2C_OWN_ADDRESS specifies the slave own address with arg. Using the value 0 disables the slave. ARM_I2C_ADDRESS_10BIT is used to indicate that it is a 10-bit address. ARM_I2C_ADDRESS_GC is used to indicate that the slave responds to a General Call.
The function ARM_I2C_Control with control = ARM_I2C_BUS_SPEED specifies the bus speed of the I2C interface with arg using the following values.
Bus Speed | Description |
---|---|
ARM_I2C_BUS_SPEED_STANDARD | Standard Speed to (100 kHz) |
ARM_I2C_BUS_SPEED_FAST | Fast Speed (400kHz) |
ARM_I2C_BUS_SPEED_FAST_PLUS | Fast+ Speed (1MHz) |
ARM_I2C_BUS_SPEED_HIGH | High Speed (3.4MHz) |
ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities | ( | void | ) |
Get driver capabilities.
Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_I2C_CAPABILITIES encode various capabilities.
Example:
int32_t ARM_I2C_GetDataCount | ( | void | ) |
Get transferred data count.
Returns the number of currently transferred data bytes during and after:
When the Slave is not yet addressed by the Master then -1 is returned.
ARM_I2C_STATUS ARM_I2C_GetStatus | ( | void | ) |
ARM_DRIVER_VERSION ARM_I2C_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t ARM_I2C_Initialize | ( | ARM_I2C_SignalEvent_t | cb_event | ) |
Initialize I2C Interface.
[in] | cb_event | Pointer to ARM_I2C_SignalEvent |
The function initializes the I2C interface. It is called when the middleware component starts operation.
The function performs the following operations:
The parameter cb_event is a pointer to the ARM_I2C_SignalEvent callback function; use a NULL pointer when no callback signals are required.
Example:
int32_t ARM_I2C_MasterReceive | ( | uint32_t | addr, |
uint8_t * | data, | ||
uint32_t | num, | ||
bool | xfer_pending | ||
) |
Start receiving data as I2C Master.
[in] | addr | Slave address (7-bit or 10-bit) |
[out] | data | Pointer to buffer for data to receive from I2C Slave |
[in] | num | Number of data bytes to receive |
[in] | xfer_pending | Transfer operation is pending - Stop condition will not be generated |
This function is used to receive data as Master from the selected Slave.
The operation consists of:
The parameter addr is the address of the slave to receive the data from. The value can be ORed with ARM_I2C_ADDRESS_10BIT to identify a 10-bit address value.
The parameter data and num specify the address of a data buffer and the number of bytes to receive.
Set the parameter xfer_pending to 'true' if another transfer operation follows. With xfer_pending set to 'false' a STOP condition is generated.
The function is non-blocking and returns as soon as the driver has started the operation. During the operation it is not allowed to call any Master function again. Also the data buffer must stay allocated. When receive operation has finished the ARM_I2C_EVENT_TRANSFER_DONE event is generated. When not all the data is transferred then the ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
Number of data bytes received is returned by the function ARM_I2C_GetDataCount during and after the operation has finished.
The operation is aborted in the following cases (ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.
Receive operation can be aborted also by calling ARM_I2C_Control with ARM_I2C_ABORT_TRANSFER as the control parameter.
int32_t ARM_I2C_MasterTransmit | ( | uint32_t | addr, |
const uint8_t * | data, | ||
uint32_t | num, | ||
bool | xfer_pending | ||
) |
Start transmitting data as I2C Master.
[in] | addr | Slave address (7-bit or 10-bit) |
[in] | data | Pointer to buffer with data to transmit to I2C Slave |
[in] | num | Number of data bytes to transmit |
[in] | xfer_pending | Transfer operation is pending - Stop condition will not be generated |
This function is used to transmit data as Master to the selected Slave.
The operation consists of:
The parameter addr is the address of the slave to transmit the data to. The value can be ORed with ARM_I2C_ADDRESS_10BIT to identify a 10-bit address value.
The parameter data and num specify the address of a data buffer and the number of bytes to transmit.
Set the parameter xfer_pending to 'true' if another transfer operation follows. With xfer_pending set to 'false' a STOP condition is generated.
The function is non-blocking and returns as soon as the driver has started the operation. During the operation it is not allowed to call any Master function again. Also the data buffer must stay allocated and the contents of data must not be modified. When transmit operation has finished the ARM_I2C_EVENT_TRANSFER_DONE event is generated. When not all the data is transferred then the ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
Number of data bytes transmitted and acknowledged is returned by the function ARM_I2C_GetDataCount during and after the operation has finished.
The operation is aborted in the following cases (ARM_I2C_EVENT_TRANSFER_DONE event is generated together with):
Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.
Transmit operation can be aborted also by calling ARM_I2C_Control with ARM_I2C_ABORT_TRANSFER as the control parameter.
int32_t ARM_I2C_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control I2C Interface Power.
[in] | state | Power state |
Allows controlling the power modes of the I2C interface.
void ARM_I2C_SignalEvent | ( | uint32_t | event | ) |
Signal I2C Events.
[in] | event | I2C Events notification mask |
The function ARM_I2C_SignalEvent is called by the I2C driver to notify the application of the I2C Events and it is registered by the function ARM_I2C_Initialize.
The argument event represents the notification mask of the events.
Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:
Bit | Event | Description |
---|---|---|
0 | ARM_I2C_EVENT_TRANSFER_DONE | Occurs after Master/Slave Transmit/Receive operation has finished. |
1 | ARM_I2C_EVENT_TRANSFER_INCOMPLETE | Occurs together with ARM_I2C_EVENT_TRANSFER_DONE when less data is transferred then requested. |
2 | ARM_I2C_EVENT_SLAVE_TRANSMIT | Occurs when addressed as Slave Transmitter and ARM_I2C_SlaveTransmit has not been started. |
3 | ARM_I2C_EVENT_SLAVE_RECEIVE | Occurs when addressed as Slave Receiver and ARM_I2C_SlaveReceive has not been started. |
4 | ARM_I2C_EVENT_GENERAL_CALL | Indicates General Call in slave mode together with ARM_I2C_EVENT_TRANSFER_DONE, ARM_I2C_EVENT_SLAVE_TRANSMIT and ARM_I2C_EVENT_SLAVE_RECEIVE. |
5 | ARM_I2C_EVENT_ADDRESS_NACK | Occurs in master mode when address is not acknowledged from slave. |
6 | ARM_I2C_EVENT_ARBITRATION_LOST | Occurs in master mode when arbitration is lost. |
7 | ARM_I2C_EVENT_BUS_ERROR | Occurs when bus error is detected. |
8 | ARM_I2C_EVENT_BUS_CLEAR | Occurs after ARM_I2C_BUS_CLEAR Control operation has finished. |
int32_t ARM_I2C_SlaveReceive | ( | uint8_t * | data, |
uint32_t | num | ||
) |
Start receiving data as I2C Slave.
[out] | data | Pointer to buffer for data to receive from I2C Master |
[in] | num | Number of data bytes to receive |
This function is used to receive data as Slave from the Master.
The parameter data and num specify the address of a data buffer and the number of bytes to receive.
The function is non-blocking and returns as soon as the driver has registered the operation. The actual operation will start after being addressed by the master as a Slave Receiver. If the operation has not been registered at that point the ARM_I2C_EVENT_SLAVE_RECEIVE event is generated.
It is not allowed to call this function again if the operation has started until it finishes. Also the data buffer must stay allocated. When receive operation has finished the ARM_I2C_EVENT_TRANSFER_DONE event is generated. When not all the data is transferred then the ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
Number of data bytes received and acknowledged is returned by the function ARM_I2C_GetDataCount during and after the operation has finished.
In case that a General call has been detected the ARM_I2C_EVENT_GENERAL_CALL flag is indicated together with the ARM_I2C_EVENT_TRANSFER_DONE event (also with ARM_I2C_EVENT_SLAVE_RECEIVE event).
In case that bus error has been detected then the operation is aborted and the ARM_I2C_EVENT_BUS_ERROR event is generated together with ARM_I2C_EVENT_TRANSFER_DONE.
Slave will only respond to its own address (or General call if enabled) that is specified by calling ARM_I2C_Control with ARM_I2C_OWN_ADDRESS as control parameter. Using address 0 disables the slave.
Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.
Receive operation can be canceled or aborted by calling ARM_I2C_Control with ARM_I2C_ABORT_TRANSFER as the control parameter.
int32_t ARM_I2C_SlaveTransmit | ( | const uint8_t * | data, |
uint32_t | num | ||
) |
Start transmitting data as I2C Slave.
[in] | data | Pointer to buffer with data to transmit to I2C Master |
[in] | num | Number of data bytes to transmit |
This function is used to transmit data as Slave to the Master.
The parameter data and num specify the address of a data buffer and the number of bytes to transmit.
The function is non-blocking and returns as soon as the driver has registered the operation. The actual operation will start after being addressed by the master as a Slave Transmitter. If the operation has not been registered at that point the ARM_I2C_EVENT_SLAVE_TRANSMIT event is generated. The same event is also generated if the operation has finished (specified number of bytes transmitted) but more data is requested by the master.
It is not allowed to call this function again if the operation has started until it finishes. Also the data buffer must stay allocated and the contents of data must not be modified. When transmit operation has finished the ARM_I2C_EVENT_TRANSFER_DONE event is generated. When not all the data is transferred then the ARM_I2C_EVENT_TRANSFER_INCOMPLETE flag is set at the same time.
Number of data bytes transmitted is returned by the function ARM_I2C_GetDataCount during and after the operation has finished.
In case that a General call has been detected the ARM_I2C_EVENT_GENERAL_CALL flag is indicated together with the ARM_I2C_EVENT_TRANSFER_DONE event (also with ARM_I2C_EVENT_SLAVE_TRANSMIT event).
In case that bus error has been detected then the operation is aborted and the ARM_I2C_EVENT_BUS_ERROR event is generated together with ARM_I2C_EVENT_TRANSFER_DONE.
Slave will only respond to its own address (or General call if enabled) that is specified by calling ARM_I2C_Control with ARM_I2C_OWN_ADDRESS as control parameter. Using address 0 disables the slave.
Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.
Transmit operation can be canceled or aborted by calling ARM_I2C_Control with ARM_I2C_ABORT_TRANSFER as the control parameter.
int32_t ARM_I2C_Uninitialize | ( | void | ) |
De-initialize I2C Interface.
The function ARM_I2C_Uninitialize de-initializes the resources of I2C interface.
It is called when the middleware component stops operation and releases the software resources used by the interface.