CMSIS-Driver  Version 2.00
Peripheral Interface for Middleware and Application Code
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
I2C Interface

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, uint32_t arg)
 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_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, uint32_t arg)
 Signal I2C Events.
 

Description

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


Data Structure Documentation

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:

  • Driver_I2C0 is the name of the access struct of the first instance (no. 0).
  • Driver_I2C1 is the name of the access struct of the second instance (no. 1).

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

Field Documentation

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.

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.

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

Returned by:

Data Fields
uint32_t address_nack: 1 Address not acknowledged from Slave (cleared on read)
uint32_t arbitration_lost: 1 Master lost arbitration (cleared on read)
uint32_t bus_error: 1 Bus error detected (cleared on read)
uint32_t busy: 1 Busy flag.
uint32_t direction: 1 Direction = 0:Transmitter, 1:Receiver.
uint32_t general_call: 1 General Call indication.
uint32_t mode: 1 Mode = 0:Slave, 1:Master.

Typedef Documentation

ARM_I2C_SignalEvent_t

Pointer to ARM_I2C_SignalEvent : Signal I2C Event.

Provides the typedef for the callback function ARM_I2C_SignalEvent.

Parameter for:

Function Documentation

int32_t ARM_I2C_Control ( uint32_t  control,
uint32_t  arg 
)

Control I2C Interface.

Parameters
[in]controloperation
[in]argargument of operation (optional)
Returns
Status Error Codes

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 tables below). Depending on the control value, the parameter arg provides additional information or sets values.

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_SPI_Control with control = ARM_I2C_OWN_ADDRESS specifies with arg the slave own address. 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 General Call.

The function ARM_SPI_Control with control = ARM_I2C_BUS_SPEED specifies the bus speed with arg of the I2C interface using the following values.

Bus Speed Description
ARM_I2C_BUS_SPEED_STANDARD Set the Standard Speed to (100 kHz)
ARM_I2C_BUS_SPEED_FAST Set the interface to Fast Speed (400kHz)
ARM_I2C_BUS_SPEED_FAST_PLUS Set the interface to Fast+ Speed (1MHz)
ARM_I2C_BUS_SPEED_HIGH Set the interface to High Speed (3.4MHz)
ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_I2C_CAPABILITIES

Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_I2C_CAPABILITIES encode various capabilities.

Example:

extern ARM_DRIVER_I2C Driver_I2C0;
ARM_DRIVER_I2C *drv_info;
void read_capabilities (void) {
ARM_I2C_CAPABILITIES drv_capabilities;
drv_info = &Driver_I2C0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
ARM_I2C_STATUS ARM_I2C_GetStatus ( void  )

Get I2C status.

Returns
I2C status ARM_I2C_STATUS

Retrieves current I2C interface status.

ARM_DRIVER_VERSION ARM_I2C_GetVersion ( void  )

Get driver version.

Returns
ARM_DRIVER_VERSION

Returns version information of the driver implementation in ARM_DRIVER_VERSION

  • API version is the version of the CMSIS-Driver specification used to implement this driver.
  • Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_I2C Driver_I2C0;
ARM_DRIVER_I2C *drv_info;
void setup_i2c (void) {
drv_info = &Driver_I2C0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
int32_t ARM_I2C_Initialize ( ARM_I2C_SignalEvent_t  cb_event)

Initialize I2C Interface.

Parameters
[in]cb_eventPointer to ARM_I2C_SignalEvent
Returns
Status Error Codes

The function initializes the I2C interface. It is called when the middleware component starts operation.

The function performs the following operations:

  • Initializes the resources needed for the I2C interface.
  • Registers the ARM_I2C_SignalEvent callback function.
  • Sets the peripheral to ARM_POWER_LOW power mode.

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.

Parameters
[in]addrSlave address (7-bit or 10-bit)
[out]dataPointer to buffer for data to receive from I2C Slave
[in]numNumber of data bytes to receive
[in]xfer_pendingTransfer operation is pending - Stop condition will not be generated
Returns
Status Error Codes

This function is used to receive data as Master from selected Slave.

The parameter addr is the address of slave to receive the data from. The value is 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 '1' if another transfer operation follows. With xfer_pending set to '0' 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 this function again. Also the data buffer must stay allocated. When receive operation is finished the ARM_I2C_EVENT_MASTER_DONE event is generated (also indicates the number of data bytes received). In case that selected slave has not acknowledged the address the ARM_I2C_EVENT_ADDRESS_NACK event is generated at the same time. In case that arbitration has been lost the ARM_I2C_EVENT_ARBITRATION_LOST event is generated at the same time. In case that bus error has been detected the ARM_I2C_EVENT_BUS_ERROR event is generated at the same time.

Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.

Receive operation can be aborted 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.

Parameters
[in]addrSlave address (7-bit or 10-bit)
[in]dataPointer to buffer with data to send to I2C Slave
[in]numNumber of data bytes to send
[in]xfer_pendingTransfer operation is pending - Stop condition will not be generated
Returns
Status Error Codes

This function is used to transmit data as Master to selected Slave.

The parameter addr is the address of slave to transmit the data to. The value is 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 '1' if another transfer operation follows. With xfer_pending set to '0' 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 this function again. Also the data buffer must stay allocated and the contents of data must not be modified. When transmit operation is finished the ARM_I2C_EVENT_MASTER_DONE event is generated (also indicates the number of data bytes transmitted and acknowledged). In case that selected slave has not acknowledged the address the ARM_I2C_EVENT_ADDRESS_NACK event is generated at the same time. In case that arbitration has been lost the ARM_I2C_EVENT_ARBITRATION_LOST event is generated at the same time. In case that bus error has been detected the ARM_I2C_EVENT_BUS_ERROR event is generated at the same time.

Status can be monitored by calling the ARM_I2C_GetStatus and checking the flags.

Transmit operation can be aborted 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.

Parameters
[in]statePower state
Returns
Status Error Codes

Allows controlling the power modes of the I2C interface.

void ARM_I2C_SignalEvent ( uint32_t  event,
uint32_t  arg 
)

Signal I2C Events.

Parameters
[in]eventI2C Events notification mask
[in]argoptional argument of event

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. One or more events may be notified with the same callback.

The argument arg is used for optional parameters of an event.

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:

BitEvent Description
0 ARM_I2C_EVENT_MASTER_DONE Occurs after Master Transmit/Receive operation is finished. Number of transmitted and acknowledged bytes or number of received bytes provided in arg.
1 ARM_I2C_EVENT_SLAVE_DONE Occurs after Slave Transmit/Receive operation is finished. Number of received and acknowledged bytes or number of transmitted bytes provided in arg.
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_SLAVE_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 is finished.
int32_t ARM_I2C_SlaveReceive ( uint8_t *  data,
uint32_t  num 
)

Start receiving data as I2C Slave.

Parameters
[out]dataPointer to buffer for data to receive from I2C Master
[in]numNumber of data bytes to receive
Returns
Status Error Codes

This function is used to receive data as Slave from 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 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 is finished the ARM_I2C_EVENT_SLAVE_DONE event is generated (also indicates the number of data bytes received and acknowledged). In case that General call has been detected the ARM_I2C_EVENT_GENERAL_CALL is indicated at the same time. In case that bus error has been detected the ARM_I2C_EVENT_BUS_ERROR event is generated.

Slave will only respond to 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 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.

Parameters
[in]dataPointer to buffer with data to send to I2C Master
[in]numNumber of data bytes to send
Returns
Status Error Codes

This function is used to transmit data as Slave to 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 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 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 is finished the ARM_I2C_EVENT_SLAVE_DONE event is generated (also indicates the number of data bytes transmitted). In case that General call has been detected the ARM_I2C_EVENT_GENERAL_CALL is indicated at the same time. In case that bus error has been detected the ARM_I2C_EVENT_BUS_ERROR event is generated.

Slave will only respond to 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 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.

Returns
Status Error Codes

The function ARM_I2C_Uninitialize de-initializes the resources of I2C interface and sets the peripheral to ARM_POWER_OFF power mode.

It is called when the middleware component stops operation and releases the software resources used by the interface.