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

Description

Driver API for I2C Bus Peripheral (Driver_I2C.h)

I²C (Inter-Integrated Circuit, referred to as I-squared-C, I-two-C, or IIC) is a multi-master serial single-ended bus and is mostly used on single boards, but can also connect to components which are linked via cable.

Most significant features of the I²C bus include:

• Only two bus lines are required
• I²C is a true multi-master bus. Simple master/slave relationships exist between all components
• A baud rate is not required; the master device determines a bus clock
• Each connected device is addressable by a unique address
• Providing arbitration and collision detection

For more information about I²C refer to the following web pages:

• Wikipedia: I²C
• www.i2c-bus.org.

Devices can operation in Master or Slave mode:

• To operate in Master mode call the functions ARM_I2C_MasterTransmit or ARM_I2C_MasterReceive. These functions get as argument a slave address.
• To operate in Slave mode set the slave address using the function ARM_I2C_Control. The functions ARM_I2C_SlaveTransmit or ARM_I2C_SlaveReceive are used to transfer data in Slave mode.

I²C Slave Address

Depending on the device, I²C supports 7-bit and 10-bit Slaves addresses. The element address_10_bit in ARM_I2C_CAPABILITIES indicates that the driver is able to handle 10-bit addresses. A 10-bit Slave address is ORed with ARM_I2C_ADDRESS_10BIT.

I²C also supports a General Call to all Slaves by using the slave address value 0. A General Call is recognized by Slaves have a slave address value ARM_I2C_ADDRESS_GC registered with the function ARM_I2C_Control.

Block Diagram

The I2C driver allows you to connect low-speed peripherals to a motherboard, embedded system, cellphone, or other electronic device.

Master/Slave connected via I2C interface

I²C API

The following header files define the Application Programming Interface (API) for the I²C interface:

• Driver_I2C.h : Driver API for I2C Bus Peripheral

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 Common Driver Functions

• ARM_DRIVER_I2C : access struct for I2C driver functions

Example Code

The following example code shows the usage of the I²C interface in Master mode.

#include "Driver_I2C.h"
 
#define EEPROM_I2C_ADDR       0x51      /* EEPROM I2C address */
 
/* I2C driver instance */
extern ARM_DRIVER_I2C            Driver_I2C0;
static ARM_DRIVER_I2C *I2Cdrv = &Driver_I2C0;
 
static volatile uint32_t I2C_Event;
 
/* I2C Signal Event function callback */
void I2C_SignalEvent (uint32_t event) {
 
  /* Save received events */
  I2C_Event |= event;
 
  /* Optionally, user can define specific actions for an event */
 
  if (event & ARM_I2C_EVENT_TRANSFER_INCOMPLETE) {
    /* Less data was transferred than requested */
  }
 
  if (event & ARM_I2C_EVENT_TRANSFER_DONE) {
    /* Transfer or receive is finished */
  }
 
  if (event & ARM_I2C_EVENT_ADDRESS_NACK) {
    /* Slave address was not acknowledged */
  }
 
  if (event & ARM_I2C_EVENT_ARBITRATION_LOST) {
    /* Master lost bus arbitration */
  }
 
  if (event & ARM_I2C_EVENT_BUS_ERROR) {
    /* Invalid start/stop position detected */
  }
 
  if (event & ARM_I2C_EVENT_BUS_CLEAR) {
    /* Bus clear operation completed */
  }
 
  if (event & ARM_I2C_EVENT_GENERAL_CALL) {
    /* Slave was addressed with a general call address */
  }
 
  if (event & ARM_I2C_EVENT_SLAVE_RECEIVE) {
    /* Slave addressed as receiver but SlaveReceive operation is not started */
  }
 
  if (event & ARM_I2C_EVENT_SLAVE_TRANSMIT) {
    /* Slave addressed as transmitter but SlaveTransmit operation is not started */
  }
}
 
/* Read I2C connected EEPROM (event driven example) */
int32_t EEPROM_Read_Event (uint16_t addr, uint8_t *buf, uint32_t len) {
  uint8_t a[2];
 
  a[0] = (uint8_t)(addr >> 8);
  a[1] = (uint8_t)(addr & 0xFF);
 
  /* Clear event flags before new transfer */
  I2C_Event = 0U;
 
  I2Cdrv->MasterTransmit (EEPROM_I2C_ADDR, a, 2, true);
 
  /* Wait until transfer completed */
  while ((I2C_Event & ARM_I2C_EVENT_TRANSFER_DONE) == 0U);
  /* Check if all data transferred */
  if ((I2C_Event & ARM_I2C_EVENT_TRANSFER_INCOMPLETE) != 0U) return -1;
 
  /* Clear event flags before new transfer */
  I2C_Event = 0U;
 
  I2Cdrv->MasterReceive (EEPROM_I2C_ADDR, buf, len, false);
 
  /* Wait until transfer completed */
  while ((I2C_Event & ARM_I2C_EVENT_TRANSFER_DONE) == 0U);
  /* Check if all data transferred */
  if ((I2C_Event & ARM_I2C_EVENT_TRANSFER_INCOMPLETE) != 0U) return -1;
 
  return 0;
}
 
/* Read I2C connected EEPROM (pooling example) */
int32_t EEPROM_Read_Pool (uint16_t addr, uint8_t *buf, uint32_t len) {
  uint8_t a[2];
 
  a[0] = (uint8_t)(addr >> 8);
  a[1] = (uint8_t)(addr & 0xFF);
 
  I2Cdrv->MasterTransmit (EEPROM_I2C_ADDR, a, 2, true);
 
  /* Wait until transfer completed */
  while (I2Cdrv->GetStatus().busy);
  /* Check if all data transferred */
  if (I2Cdrv->GetDataCount () != len) return -1;
 
  I2Cdrv->MasterReceive (EEPROM_I2C_ADDR, buf, len, false);
 
  /* Wait until transfer completed */
  while (I2Cdrv->GetStatus().busy);
  /* Check if all data transferred */
  if (I2Cdrv->GetDataCount () != len) return -1;
 
  return 0;
}
 
/* Initialize I2C connected EEPROM */
int32_t EEPROM_Initialize (bool pooling) {
  int32_t status;
  uint8_t val;
 
  if (pooling == true) {
    I2Cdrv->Initialize (NULL);
  } else {
    I2Cdrv->Initialize (I2C_SignalEvent);
  }
  I2Cdrv->PowerControl (ARM_POWER_FULL);
  I2Cdrv->Control      (ARM_I2C_BUS_SPEED, ARM_I2C_BUS_SPEED_FAST);
  I2Cdrv->Control      (ARM_I2C_BUS_CLEAR, 0);
 
  /* Check if EEPROM can be accessed */
  if (pooling == true) {
    status = EEPROM_Read_Pool (0x00, &val, 1);
  } else {
    status = EEPROM_Read_Event (0x00, &val, 1);
  }
 
  return (status);
}

The following example code shows the usage of the I²C interface in Slave mode.

#include "Driver_I2C.h"
 
/* I2C driver instance */
extern ARM_DRIVER_I2C            Driver_I2C0; 
static ARM_DRIVER_I2C *I2Cdrv = &Driver_I2C0;
 
static volatile uint32_t I2C_Event;
 
/* I2C Signal Event function callback */
static void I2C_SignalEvent (uint32_t event) {
  I2C_Event |= event;
}
 
int main (void) {
  uint8_t cnt = 0;
 
  /* Initialize I2C peripheral */
  I2Cdrv->Initialize(I2C_SignalEvent);
 
  /* Power-on I2C peripheral */
  I2Cdrv->PowerControl(ARM_POWER_FULL);
 
  /* Configure I2C bus */
  I2Cdrv->Control(ARM_I2C_OWN_ADDRESS, 0x78);
 
  I2C_Event = 0;
 
  while (1) {
    /* Receive chunk */
    I2Cdrv->SlaveReceive(&cnt, 1);
    while ((I2C_Event & ARM_I2C_EVENT_TRANSFER_DONE) == 0);
    /* Clear transfer done flag */
    I2C_Event &= ~ARM_I2C_EVENT_TRANSFER_DONE;
 
    /* Transmit chunk back */
    I2Cdrv->SlaveTransmit(&cnt, 1);
    while ((I2C_Event & ARM_I2C_EVENT_TRANSFER_DONE) == 0);
    /* Clear transfer done flag */
    I2C_Event &= ~ARM_I2C_EVENT_TRANSFER_DONE;
  }
}

---

Data Structure Documentation

ARM_DRIVER_I2C

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

Field Documentation

GetVersion

ARM_DRIVER_VERSION(* GetVersion) (void)

Pointer to ARM_I2C_GetVersion : Get driver version.

GetCapabilities

ARM_I2C_CAPABILITIES(* GetCapabilities) (void)

Pointer to ARM_I2C_GetCapabilities : Get driver capabilities.

Initialize

int32_t(* Initialize) (ARM_I2C_SignalEvent_t cb_event)

Pointer to ARM_I2C_Initialize : Initialize I2C Interface.

Uninitialize

int32_t(* Uninitialize) (void)

Pointer to ARM_I2C_Uninitialize : De-initialize I2C Interface.

PowerControl

int32_t(* PowerControl) (ARM_POWER_STATE state)

Pointer to ARM_I2C_PowerControl : Control I2C Interface Power.

MasterTransmit

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.

MasterReceive

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.

SlaveTransmit

int32_t(* SlaveTransmit) (const uint8_t *data, uint32_t num)

Pointer to ARM_I2C_SlaveTransmit : Start transmitting data as I2C Slave.

SlaveReceive

int32_t(* SlaveReceive) (uint8_t *data, uint32_t num)

Pointer to ARM_I2C_SlaveReceive : Start receiving data as I2C Slave.

GetDataCount

int32_t(* GetDataCount) (void)

Pointer to ARM_I2C_GetDataCount : Get transferred data count.

Control

int32_t(* Control) (uint32_t control, uint32_t arg)

Pointer to ARM_I2C_Control : Control I2C Interface.

GetStatus

ARM_I2C_STATUS(* GetStatus) (void)

Pointer to ARM_I2C_GetStatus : Get I2C status.

ARM_I2C_CAPABILITIES

struct ARM_I2C_CAPABILITIES

I2C Driver Capabilities.

An I2C driver can be implemented with different capabilities. The data fields 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:

• ARM_I2C_GetCapabilities

Data Fields
uint32_t	address_10_bit: 1	supports 10-bit addressing
uint32_t	reserved: 31	Reserved (must be zero)

ARM_I2C_STATUS

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:

• when Master operation starts: after calling ARM_I2C_MasterTransmit or ARM_I2C_MasterReceive
• when Slave operation starts: after calling ARM_I2C_SlaveTransmit or ARM_I2C_SlaveReceive and after being addressed by a Master as the Slave

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_GetStatus

Data Fields
uint32_t	busy: 1	Busy flag.
uint32_t	mode: 1	Mode: 0=Slave, 1=Master.
uint32_t	direction: 1	Direction: 0=Transmitter, 1=Receiver.
uint32_t	general_call: 1	General Call indication (cleared on start of next Slave operation)
uint32_t	arbitration_lost: 1	Master lost arbitration (cleared on start of next Master operation)
uint32_t	bus_error: 1	Bus error detected (cleared on start of next Master/Slave operation)
uint32_t	reserved: 26

Typedef Documentation

ARM_I2C_SignalEvent_t

ARM_I2C_SignalEvent_t

Pointer to ARM_I2C_SignalEvent : Signal I2C Event.

Provides the typedef for the callback function ARM_I2C_SignalEvent.

Parameter for:

• ARM_I2C_Initialize

Function Documentation

ARM_I2C_GetVersion()

ARM_DRIVER_VERSION ARM_I2C_GetVersion

(

void

)

Get driver version.

Returns

ARM_DRIVER_VERSION

The function ARM_I2C_GetVersion 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)  {
  ARM_DRIVER_VERSION  version;
 
  drv_info = &Driver_I2C0;  
  version = drv_info->GetVersion ();
  if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
    // error handling
    return;
  }
}

ARM_I2C_GetCapabilities()

ARM_I2C_CAPABILITIES ARM_I2C_GetCapabilities

(

void

)

Get driver capabilities.

Returns

ARM_I2C_CAPABILITIES

The function ARM_I2C_GetCapabilities returns information about capabilities of this driver implementation. The data fields of the struct ARM_I2C_CAPABILITIES encodes the driver 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_Initialize()

int32_t ARM_I2C_Initialize

(

ARM_I2C_SignalEvent_t

cb_event

)

Initialize I2C Interface.

Parameters

[in]

cb_event

Pointer to ARM_I2C_SignalEvent

Returns

Status Error Codes

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

The function performs the following operations:

• Initializes and the I/O resources for the I2C interface.
• Registers the ARM_I2C_SignalEvent callback function.

The parameter cb_event is a pointer to the ARM_I2C_SignalEvent callback function. Use a NULL pointer when no callback events are required.

Can be called multiple times. If the peripheral is already initialized the function performs no operation and returns with ARM_DRIVER_OK. Refer to Function Call Sequence for more information.

See also

ARM_I2C_PowerControl

ARM_I2C_Uninitialize

Example:

• refer to Example Code

ARM_I2C_Uninitialize()

int32_t ARM_I2C_Uninitialize

(

void

)

De-initialize I2C Interface.

Returns

Status Error Codes

The function ARM_I2C_Uninitialize releases the I/O resources of I2C interface.

It is called when the middleware component stops operation and releases the I/O resources used by the I2C interface. Refer to Function Call Sequence for more information.

See also

ARM_I2C_Initialize

ARM_I2C_PowerControl

ARM_I2C_PowerControl()

int32_t ARM_I2C_PowerControl

(

ARM_POWER_STATE

state

)

Control I2C Interface Power.

Parameters

[in]

state

Power state

Returns

Status Error Codes

The function ARM_I2C_PowerControl operates the power modes of the I2C interface.

The parameter state can have the following values:

• ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode, then the function performs no operation and returns with ARM_DRIVER_OK.
• ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
• ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Refer to Function Call Sequence for more information.

See also

ARM_I2C_Initialize

ARM_I2C_Uninitialize

ARM_I2C_MasterTransmit()

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

Returns

Status Error Codes

This function ARM_I2C_MasterTransmit transmits data as Master to the selected Slave.

The operation consists of:

• Master generates START condition
• Master addresses the Slave as Master Transmitter
• Master transmits data to the addressed Slave
• Master generates STOP condition (if xfer_pending is "false")

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):

• selected slave has not acknowledged the address: ARM_I2C_EVENT_ADDRESS_NACK event
• arbitration has been lost: ARM_I2C_EVENT_ARBITRATION_LOST event
• bus error has been detected: ARM_I2C_EVENT_BUS_ERROR event

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 the parameter control ARM_I2C_ABORT_TRANSFER.

ARM_I2C_MasterReceive()

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

Returns

Status Error Codes

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

The operation consists of:

• Master generates START condition
• Master addresses the Slave as Master Receiver
• Master receives data from the addressed Slave
• Master generates STOP condition (if xfer_pending is "false")

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):

• selected slave has not acknowledged the address: ARM_I2C_EVENT_ADDRESS_NACK event
• arbitration has been lost: ARM_I2C_EVENT_ARBITRATION_LOST event
• bus error has been detected: ARM_I2C_EVENT_BUS_ERROR event

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 the parameter control = ARM_I2C_ABORT_TRANSFER.

ARM_I2C_SlaveTransmit()

int32_t ARM_I2C_SlaveTransmit	(	const uint8_t *	data,
		uint32_t	num
	)

Start transmitting data as I2C Slave.

Parameters

[in]	data	Pointer to buffer with data to transmit to I2C Master
[in]	num	Number of data bytes to transmit

Returns

Status Error Codes

This function ARM_I2C_SlaveTransmit is used to transmit data as Slave to the Master.

The parameter data is a pointer to the data to transmit.
The parameter num specifies 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 the parameter control = ARM_I2C_ABORT_TRANSFER.

ARM_I2C_SlaveReceive()

int32_t ARM_I2C_SlaveReceive	(	uint8_t *	data,
		uint32_t	num
	)

Start receiving data as I2C Slave.

Parameters

[out]	data	Pointer to buffer for data to receive from I2C Master
[in]	num	Number of data bytes to receive

Returns

Status Error Codes

This function ARM_I2C_SlaveReceive receives data as Slave from the Master.

The parameter data is a pointer to the data to receive.
The parameter num specifies 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 the parameter control = ARM_I2C_ABORT_TRANSFER.

ARM_I2C_GetDataCount()

int32_t ARM_I2C_GetDataCount

(

void

)

Get transferred data count.

Returns

number of data bytes transferred; -1 when Slave is not addressed by Master

The function ARM_I2C_GetDataCount returns the number of currently transferred data bytes during and after:

• ARM_I2C_MasterTransmit : number of data bytes transmitted and acknowledged
• ARM_I2C_MasterReceive : number of data bytes received
• ARM_I2C_SlaveTransmit : number of data bytes transmitted
• ARM_I2C_SlaveReceive : number of data bytes received and acknowledged

When the Slave is not yet addressed by the Master then -1 is returned.

ARM_I2C_Control()

int32_t ARM_I2C_Control	(	uint32_t	control,
		uint32_t	arg
	)

Control I2C Interface.

Parameters

[in]	control	Operation
[in]	arg	Argument of operation (optional)

Returns

Status Error Codes

The function ARM_I2C_Control operates the I2C interface and executes various operations.

The parameter control specifies various operations as listed in the table below.
The parameter arg provides, depending on the operation, additional information.

Parameter control	Operation
ARM_I2C_OWN_ADDRESS	Set Own Slave Address; arg = slave address
ARM_I2C_BUS_SPEED	Set 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

Set Own Slave Address

After initialization, the I2C Device has no slave address assigned and does not accept any requests from an I2C Master.

The control operation ARM_I2C_OWN_ADDRESS sets the slave address with the parameter arg. The slave address can be ORed with ARM_I2C_ADDRESS_10BIT to indicate a 10-bit address.

The slave address can be ORed with ARM_I2C_ADDRESS_GC to indicate that the slave accepts a General Call. If the slave address value is only ARM_I2C_ADDRESS_GC, then the slave only accepts a General Call.

The slave address value 0 disables Slave mode and clears any assigned slave address.

Examples:**

Set the Slave address value 0x45 as 7-bit address.

I2Cdrv->Control      (ARM_I2C_OWN_ADDRESS, 0x45);

Set the Slave address value 0x135 as 10-bit address and accept a General Call.

I2Cdrv->Control      (ARM_I2C_OWN_ADDRESS, 0x135 | ARM_I2C_ADDRESS_10BIT | ARM_I2C_ADDRESS_GC);

Bus Speed

The control operation ARM_I2C_BUS_SPEED sets the bus speed using the parameter arg.

Parameter arg	Bus Speed
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)

Example:**

I2Cdrv->Control      (ARM_I2C_BUS_SPEED, I2C_BUS_SPEED_FAST);

ARM_I2C_GetStatus()

ARM_I2C_STATUS ARM_I2C_GetStatus

(

void

)

Get I2C status.

Returns

I2C status ARM_I2C_STATUS

The function ARM_I2C_GetStatus returns the current I2C interface status.

Refer to ARM_I2C_STATUS for details.

ARM_I2C_SignalEvent()

void ARM_I2C_SignalEvent

(

uint32_t

event

)

Signal I2C Events.

Parameters

[in]

event

I2C Events notification mask

The function ARM_I2C_SignalEvent is a callback function registered by the function ARM_I2C_Initialize.. It is called by the I2C driver to notify the application about I2C Events occurred during operation.

The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

The following events can be generated:

Parameter event	Bit	Description
ARM_I2C_EVENT_TRANSFER_DONE	1UL << 0	Occurs after Master/Slave Transmit/Receive operation has finished.
ARM_I2C_EVENT_TRANSFER_INCOMPLETE	1UL << 1	Occurs together with ARM_I2C_EVENT_TRANSFER_DONE when less data is transferred then requested.
ARM_I2C_EVENT_SLAVE_TRANSMIT	1UL << 2	Occurs when addressed as Slave Transmitter and ARM_I2C_SlaveTransmit has not been started.
ARM_I2C_EVENT_SLAVE_RECEIVE	1UL << 3	Occurs when addressed as Slave Receiver and ARM_I2C_SlaveReceive has not been started.
ARM_I2C_EVENT_ADDRESS_NACK	1UL << 4	Occurs in master mode when address is not acknowledged from slave.
ARM_I2C_EVENT_GENERAL_CALL	1UL << 5	Indicates General Call in slave mode together with ARM_I2C_EVENT_TRANSFER_DONE, ARM_I2C_EVENT_SLAVE_TRANSMIT and ARM_I2C_EVENT_SLAVE_RECEIVE.
ARM_I2C_EVENT_ARBITRATION_LOST	1UL << 6	Occurs in master mode when arbitration is lost.
ARM_I2C_EVENT_BUS_ERROR	1UL << 7	Occurs when bus error is detected.
ARM_I2C_EVENT_BUS_CLEAR	1UL << 8	Occurs after ARM_I2C_BUS_CLEAR Control operation has finished.