CMSIS Driver  Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
I2C Interface

Driver API for I2C Bus Master Peripheral (Driver_I2C.h) More...

Data Structures

struct  ARM_DRIVER_I2C
 Access structure of the I2C Driver. More...
 
struct  ARM_I2C_CAPABILITIES
 I2C Driver Capabilities. More...
 

Typedefs

typedef void(* ARM_I2C_SignalEvent_t )(ARM_I2C_EVENT event)
 Pointer to ARM_I2C_SignalEvent : Signal I2C Event.
 

Enumerations

enum  ARM_I2C_BUS_SPEED {
  ARM_I2C_BUS_SPEED_LOW,
  ARM_I2C_BUS_SPEED_STANDARD,
  ARM_I2C_BUS_SPEED_FAST,
  ARM_I2C_BUS_SPEED_FAST_PLUS,
  ARM_I2C_BUS_SPEED_HIGH
}
 I2C Bus Speed. More...
 
enum  ARM_I2C_EVENT { ARM_I2C_EVENT_RESERVED }
 I2C Event. More...
 
enum  ARM_I2C_STATUS {
  ARM_I2C_OK = 0,
  ARM_I2C_ERROR = 1,
  ARM_I2C_ERROR_UNSUPPORTED = 2,
  ARM_I2C_ERROR_NO_SLAVE = 3,
  ARM_I2C_ERROR_BUS_BUSY = 4
}
 I2C Status of executed operation. More...
 

Functions

ARM_DRV_VERSION ARM_I2C_GetVersion (void)
 Get driver version.
 
ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities (void)
 Get driver capabilities.
 
void ARM_I2C_SignalEvent (ARM_I2C_EVENT event)
 Signal I2C Event.
 
ARM_I2C_STATUS ARM_I2C_Initialize (ARM_I2C_SignalEvent_t cb_event)
 Initialize I2C Interface.
 
ARM_I2C_STATUS ARM_I2C_Uninitialize (void)
 De-initialize ARM_I2C Interface.
 
ARM_I2C_STATUS ARM_I2C_PowerControl (ARM_POWER_STATE state)
 Control I2C Interface Power.
 
ARM_I2C_STATUS ARM_I2C_BusSpeed (ARM_I2C_BUS_SPEED speed)
 Set bus speed for I2C transfers.
 
ARM_I2C_STATUS ARM_I2C_BusClear (void)
 Send nine clock pulses to clear the bus.
 
int32_t ARM_I2C_SendData (uint32_t addr, const uint8_t *data, uint32_t size, bool xfer_pending)
 Send data to I2C Slave.
 
int32_t ARM_I2C_ReceiveData (uint32_t addr, uint8_t *data, uint32_t size, bool xfer_pending)
 Receive data from I2C Slave.
 
ARM_I2C_STATUS ARM_I2C_AbortTransfer (void)
 Abort current I2C transfer.
 

Description

Driver API for I2C Bus Master 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

A typical setup sequence for the driver is shown below:

Example Code:


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:

  • ARM_DRIVER_I2C0 is the name of the access struct of the first instance (no. 0).
  • ARM_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 ARM_DRIVER_I2Cn. The default is 0, which connects a middleware to the first instance of a driver.

Data Fields

ARM_DRV_VERSION(* GetVersion )(void)
 Pointer to ARM_I2C_GetVersion : Get driver version.
 
ARM_I2C_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_I2C_GetCapabilities : Get driver capabilities.
 
ARM_I2C_STATUS(* Initialize )(ARM_I2C_SignalEvent_t cb_event)
 Pointer to ARM_I2C_Initialize : Initialize I2C Interface.
 
ARM_I2C_STATUS(* Uninitialize )(void)
 Pointer to ARM_I2C_Uninitialize : De-initialize I2C Interface.
 
ARM_I2C_STATUS(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_I2C_PowerControl : Control I2C Interface Power.
 
ARM_I2C_STATUS(* BusSpeed )(ARM_I2C_BUS_SPEED speed)
 Pointer to ARM_I2C_BusSpeed : Set bus speed for I2C transfers.
 
ARM_I2C_STATUS(* BusClear )(void)
 Pointer to ARM_I2C_BusClear : Send nine clock pulses to clear the bus.
 
int32_t(* SendData )(uint32_t addr, const uint8_t *data, uint32_t size, bool xfer_pending)
 Pointer to ARM_I2C_SendData : Send data to I2C Slave.
 
int32_t(* ReceiveData )(uint32_t addr, uint8_t *data, uint32_t size, bool xfer_pending)
 Pointer to ARM_I2C_ReceiveData : Receive data from I2C Slave.
 
ARM_I2C_STATUS(* AbortTransfer )(void)
 Pointer to ARM_I2C_AbortTransfer : Abort current I2C transfer.
 

Field Documentation

ARM_I2C_STATUS(* AbortTransfer)(void)

Pointer to ARM_I2C_AbortTransfer : Abort current I2C transfer.

ARM_I2C_STATUS(* BusClear)(void)

Pointer to ARM_I2C_BusClear : Send nine clock pulses to clear the bus.

ARM_I2C_STATUS(* BusSpeed)(ARM_I2C_BUS_SPEED speed)

Pointer to ARM_I2C_BusSpeed : Set bus speed for I2C transfers.

ARM_I2C_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_I2C_GetCapabilities : Get driver capabilities.

ARM_DRV_VERSION(* GetVersion)(void)

Pointer to ARM_I2C_GetVersion : Get driver version.

ARM_I2C_STATUS(* Initialize)(ARM_I2C_SignalEvent_t cb_event)

Pointer to ARM_I2C_Initialize : Initialize I2C Interface.

ARM_I2C_STATUS(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_I2C_PowerControl : Control I2C Interface Power.

int32_t(* ReceiveData)(uint32_t addr, uint8_t *data, uint32_t size, bool xfer_pending)

Pointer to ARM_I2C_ReceiveData : Receive data from I2C Slave.

int32_t(* SendData)(uint32_t addr, const uint8_t *data, uint32_t size, bool xfer_pending)

Pointer to ARM_I2C_SendData : Send data to I2C Slave.

ARM_I2C_STATUS(* 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 reserved: 32 reserved for future use

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:

Enumeration Type Documentation

I2C Bus Speed.

Lists the supported bus speeds for an I2C bus. The master device determines the bus speed.

Parameter for:

Enumerator:
ARM_I2C_BUS_SPEED_LOW 

I2C Bus: Low Speed ( 10kHz)

ARM_I2C_BUS_SPEED_STANDARD 

I2C Bus: Standard Speed (100kHz)

ARM_I2C_BUS_SPEED_FAST 

I2C Bus: Fast Speed (400kHz)

ARM_I2C_BUS_SPEED_FAST_PLUS 

I2C Bus: Fast+ Speed ( 1MHz)

ARM_I2C_BUS_SPEED_HIGH 

I2C Bus: High Speed (3.4MHz)

I2C Event.

Provides the event information for the ARM_I2C_SignalEvent callback function (which is registered by the function ARM_I2C_Initialize).

Parameter for:

Enumerator:
ARM_I2C_EVENT_RESERVED 

reserved for future use

I2C Status of executed operation.

Defines status and error codes returned by most of the I2C driver functions.

Returned by:

Enumerator:
ARM_I2C_OK 

I2C Status: Operation succeeded.

ARM_I2C_ERROR 

I2C Status: Unspecified error.

ARM_I2C_ERROR_UNSUPPORTED 

I2C Status: Operation not supported.

ARM_I2C_ERROR_NO_SLAVE 

I2C Status: Slave not responding.

ARM_I2C_ERROR_BUS_BUSY 

I2C Status: Communication ongoing on the bus.

Function Documentation

ARM_I2C_STATUS ARM_I2C_AbortTransfer ( void  )

Abort current I2C transfer.

Returns
execution status ARM_I2C_STATUS
ARM_I2C_STATUS ARM_I2C_BusClear ( void  )

Send nine clock pulses to clear the bus.

Returns
execution status ARM_I2C_STATUS
ARM_I2C_STATUS ARM_I2C_BusSpeed ( ARM_I2C_BUS_SPEED  speed)

Set bus speed for I2C transfers.

Parameters
[in]speedRequested bus speed
Returns
execution status ARM_I2C_STATUS

Set the data transfer speed of the I2C to the requested baud rate in bits per second.

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, for example if a hardware is capable to create signal events using the ARM_I2C_SignalEvent callback function.

Example:

extern ARM_DRIVER_I2C ARM_Driver_I2C0;
ARM_DRIVER_I2C *drv_info;
void read_capabilities (void) {
ARM_I2C_CAPABILITIES drv_capabilities;
drv_info = &ARM_Driver_I2C0;
drv_capablilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
DRV_VERSION ARM_I2C_GetVersion ( void  )

Get driver version.

Returns
ARM_DRV_VERSION

Returns version information of the driver implementation in ARM_DRV_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 ARM_Driver_I2C0;
ARM_DRIVER_I2C *drv_info;
void setup_i2c (void) {
ARM_DRV_VERSION version;
drv_info = &ARM_Driver_I2C0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_I2C_STATUS ARM_I2C_Initialize ( ARM_I2C_SignalEvent_t  cb_event)

Initialize I2C Interface.

Parameters
[in]cb_eventPointer to ARM_I2C_SignalEvent
Returns
execution status ARM_I2C_STATUS

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:

ARM_I2C_STATUS ARM_I2C_PowerControl ( ARM_POWER_STATE  state)

Control I2C Interface Power.

Parameters
[in]statePower state
Returns
execution status ARM_I2C_STATUS

Allows controlling the power modes of the interface.

int32_t ARM_I2C_ReceiveData ( uint32_t  addr,
uint8_t *  data,
uint32_t  size,
bool  xfer_pending 
)

Receive data from I2C Slave.

Parameters
[in]addrSlave address (7-bit or 10-bit)
[out]dataPointer to buffer for data received from I2C slave
[in]sizeData buffer size in bytes
[in]xfer_pendingTransfer operation is pending - Stop condition will not be generated
Returns
number of data bytes received or execution status
  • value >= 0: number of data bytes received
  • value < 0: error occurred, -value is execution status as defined with ARM_I2C_STATUS
int32_t ARM_I2C_SendData ( uint32_t  addr,
const uint8_t *  data,
uint32_t  size,
bool  xfer_pending 
)

Send data to I2C Slave.

Parameters
[in]addrSlave address (7-bit or 10-bit)
[in]dataPointer to buffer with data to send to I2C slave
[in]sizeData buffer size in bytes
[in]xfer_pendingTransfer operation is pending - Stop condition will not be generated
Returns
number of data bytes sent and acknowledged or execution status
  • value >= 0: number of data bytes sent and acknowledged
  • value < 0: error occurred, -value is execution status as defined with ARM_I2C_STATUS
void ARM_I2C_SignalEvent ( ARM_I2C_EVENT  event)

Signal I2C Event.

Parameters
[in]eventARM_I2C_EVENT

Get driver capabilities.

ARM_I2C_STATUS ARM_I2C_Uninitialize ( void  )

De-initialize ARM_I2C Interface.

Returns
execution status ARM_I2C_STATUS

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.