All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
I2C Master Driver
I2C: Inter-Integrated Circuit Driver

## Overview

## Data Structures

struct | i2c_master_config_t
| Structure with settings to initialize the I2C master module. More...
struct | i2c_master_transfer_t
| Non-blocking transfer descriptor structure. More...
struct | i2c_master_handle_t
| Driver handle for master non-blocking APIs. More...

## Typedefs

typedef void(* | i2c_master_transfer_callback_t )(I2C_Type *base, i2c_master_handle_t *handle, status_t completionStatus, void *userData)
| Master completion callback function pointer type. More...

## Enumerations

enum | _i2c_master_flags { kI2C_MasterPendingFlag = I2C_STAT_MSTPENDING_MASK, kI2C_MasterArbitrationLostFlag, kI2C_MasterStartStopErrorFlag }
| I2C master peripheral flags. More...
enum | i2c_direction_t { kI2C_Write = 0U, kI2C_Read = 1U }
| Direction of master and slave transfers. More...
enum | _i2c_master_transfer_flags { kI2C_TransferDefaultFlag = 0x00U, kI2C_TransferNoStartFlag = 0x01U, kI2C_TransferRepeatedStartFlag = 0x02U, kI2C_TransferNoStopFlag = 0x04U }
| Transfer option flags. More...
enum | _i2c_transfer_states
| States for the state machine used by transactional APIs. More...

## Initialization and deinitialization

void | I2C_MasterGetDefaultConfig (i2c_master_config_t *masterConfig)
| Provides a default configuration for the I2C master peripheral. More...
void | I2C_MasterInit (I2C_Type *base, const i2c_master_config_t *masterConfig, uint32_t srcClock_Hz)
| Initializes the I2C master peripheral. More...
void | I2C_MasterDeinit (I2C_Type *base)
| Deinitializes the I2C master peripheral. More...
uint32_t | I2C_GetInstance (I2C_Type *base)
| Returns an instance number given a base address. More...
static void | I2C_MasterReset (I2C_Type *base)
| Performs a software reset. More...
static void | I2C_MasterEnable (I2C_Type *base, bool enable)
| Enables or disables the I2C module as master. More...

## Status

static uint32_t | I2C_GetStatusFlags (I2C_Type *base)
| Gets the I2C status flags. More...
static void | I2C_MasterClearStatusFlags (I2C_Type *base, uint32_t statusMask)
| Clears the I2C master status flag state. More...

## Interrupts

static void | I2C_EnableInterrupts (I2C_Type *base, uint32_t interruptMask)
| Enables the I2C master interrupt requests. More...
static void | I2C_DisableInterrupts (I2C_Type *base, uint32_t interruptMask)
| Disables the I2C master interrupt requests. More...
static uint32_t | I2C_GetEnabledInterrupts (I2C_Type *base)
| Returns the set of currently enabled I2C master interrupt requests. More...

## Bus operations

void | I2C_MasterSetBaudRate (I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz)
| Sets the I2C bus frequency for master transactions. More...
static bool | I2C_MasterGetBusIdleState (I2C_Type *base)
| Returns whether the bus is idle. More...
status_t | I2C_MasterStart (I2C_Type *base, uint8_t address, i2c_direction_t direction)
| Sends a START on the I2C bus. More...
status_t | I2C_MasterStop (I2C_Type *base)
| Sends a STOP signal on the I2C bus. More...
static status_t | I2C_MasterRepeatedStart (I2C_Type *base, uint8_t address, i2c_direction_t direction)
| Sends a REPEATED START on the I2C bus. More...
status_t | I2C_MasterWriteBlocking (I2C_Type *base, const void *txBuff, size_t txSize, uint32_t flags)
| Performs a polling send transfer on the I2C bus. More...
status_t | I2C_MasterReadBlocking (I2C_Type *base, void *rxBuff, size_t rxSize, uint32_t flags)
| Performs a polling receive transfer on the I2C bus. More...
status_t | I2C_MasterTransferBlocking (I2C_Type *base, i2c_master_transfer_t *xfer)
| Performs a master polling transfer on the I2C bus. More...

## Non-blocking

void | I2C_MasterTransferCreateHandle (I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_callback_t callback, void *userData)
| Creates a new handle for the I2C master non-blocking APIs. More...
status_t | I2C_MasterTransferNonBlocking (I2C_Type *base, i2c_master_handle_t *handle, i2c_master_transfer_t *xfer)
| Performs a non-blocking transaction on the I2C bus. More...
status_t | I2C_MasterTransferGetCount (I2C_Type *base, i2c_master_handle_t *handle, size_t *count)
| Returns number of bytes transferred so far. More...
status_t | I2C_MasterTransferAbort (I2C_Type *base, i2c_master_handle_t *handle)
| Terminates a non-blocking I2C master transmission early. More...

## IRQ handler

void | I2C_MasterTransferHandleIRQ (I2C_Type *base, void *i2cHandle)
| Reusable routine to handle master interrupts. More...

## Data Structure Documentation

struct i2c_master_config_t

This structure holds configuration settings for the I2C peripheral. To initialize this structure to reasonable defaults, call the I2C_MasterGetDefaultConfig() function and pass a pointer to your configuration structure instance.

The configuration structure can be made constant so it resides in flash.

### Data Fields

bool | enableMaster
| Whether to enable master mode. More...
uint32_t | baudRate_Bps
| Desired baud rate in bits per second. More...
bool | enableTimeout
| Enable internal timeout function. More...

#### Field Documentation

bool i2c_master_config_t::enableMaster

uint32_t i2c_master_config_t::baudRate_Bps

bool i2c_master_config_t::enableTimeout

struct _i2c_master_transfer

I2C master transfer typedef.

This structure is used to pass transaction parameters to the I2C_MasterTransferNonBlocking() API.

### Data Fields

uint32_t | flags
| Bit mask of options for the transfer. More...
uint16_t | slaveAddress
| The 7-bit slave address. More...
i2c_direction_t | direction
| Either kI2C_Read or kI2C_Write. More...
uint32_t | subaddress
| Sub address. More...
size_t | subaddressSize
| Length of sub address to send in bytes. More...
void * | data
| Pointer to data to transfer. More...
size_t | dataSize
| Number of bytes to transfer. More...

#### Field Documentation

uint32_t i2c_master_transfer_t::flags

See enumeration _i2c_master_transfer_flags for available options. Set to 0 or kI2C_TransferDefaultFlag for normal transfers.

uint16_t i2c_master_transfer_t::slaveAddress

i2c_direction_t i2c_master_transfer_t::direction

uint32_t i2c_master_transfer_t::subaddress

Transferred MSB first.

size_t i2c_master_transfer_t::subaddressSize

Maximum size is 4 bytes.

void* i2c_master_transfer_t::data

size_t i2c_master_transfer_t::dataSize

struct _i2c_master_handle

I2C master handle typedef.

Note
  The contents of this structure are private and subject to change.

### Data Fields

uint8_t | state
| Transfer state machine current state. More...
uint32_t | transferCount
| Indicates progress of the transfer.
uint32_t | remainingBytes
| Remaining byte count in current state. More...
uint8_t * | buf
| Buffer pointer for current state. More...
i2c_master_transfer_t | transfer
| Copy of the current transfer info. More...
i2c_master_transfer_callback_t | completionCallback
| Callback function pointer. More...
void * | userData
| Application data passed to callback. More...

#### Field Documentation

uint8_t i2c_master_handle_t::state

uint32_t i2c_master_handle_t::remainingBytes

uint8_t* i2c_master_handle_t::buf

i2c_master_transfer_t i2c_master_handle_t::transfer

i2c_master_transfer_callback_t i2c_master_handle_t::completionCallback

void* i2c_master_handle_t::userData

## Typedef Documentation

typedef void(* i2c_master_transfer_callback_t)(I2C_Type *base, i2c_master_handle_t *handle, status_t completionStatus, void *userData)

This callback is used only for the non-blocking master transfer API. Specify the callback you wish to use in the call to I2C_MasterTransferCreateHandle().

Parameters

  base | The I2C peripheral base address.
  completionStatus | Either kStatus_Success or an error code describing how the transfer completed.
  userData | Arbitrary pointer-sized value passed from the application.

## Enumeration Type Documentation

enum _i2c_master_flags

Note
  These enums are meant to be OR'd together to form a bit mask.

Enumerator
kI2C_MasterPendingFlag | The I2C module is waiting for software interaction.
kI2C_MasterArbitrationLostFlag | The arbitration of the bus was lost. There was collision on the bus
kI2C_MasterStartStopErrorFlag | There was an error during start or stop phase of the transaction.

enum i2c_direction_t

Enumerator
kI2C_Write | Master transmit.
kI2C_Read | Master receive.

enum _i2c_master_transfer_flags

Note
  These enumerations are intended to be OR'd together to form a bit mask of options for the _i2c_master_transfer::flags field.

Enumerator
kI2C_TransferDefaultFlag | Transfer starts with a start signal, stops with a stop signal.
kI2C_TransferNoStartFlag | Don't send a start condition, address, and sub address.
kI2C_TransferRepeatedStartFlag | Send a repeated start condition.
kI2C_TransferNoStopFlag | Don't send a stop condition.

enum _i2c_transfer_states

## Function Documentation

void I2C_MasterGetDefaultConfig | ( | i2c_master_config_t * | masterConfig | ) |

This function provides the following default configuration for the I2C master peripheral:

* masterConfig->enableMaster = true;
* masterConfig->baudRate_Bps = 100000U;
* masterConfig->enableTimeout = false;
*

After calling this function, you can override any settings in order to customize the configuration, prior to initializing the master driver with I2C_MasterInit().

Parameters

  [out] | masterConfig | User provided configuration structure for default values. Refer to i2c_master_config_t.

void I2C_MasterInit | ( | I2C_Type * | base,
|  | const i2c_master_config_t * | masterConfig,
|  | uint32_t | srcClock_Hz
| ) |  |

This function enables the peripheral clock and initializes the I2C master peripheral as described by the user provided configuration. A software reset is performed prior to configuration.

Parameters

  base | The I2C peripheral base address.
  masterConfig | User provided peripheral configuration. Use I2C_MasterGetDefaultConfig() to get a set of defaults that you can override.
  srcClock_Hz | Frequency in Hertz of the I2C functional clock. Used to calculate the baud rate divisors, filter widths, and timeout periods.

void I2C_MasterDeinit | ( | I2C_Type * | base | ) |

This function disables the I2C master peripheral and gates the clock. It also performs a software reset to restore the peripheral to reset conditions.

Parameters

  base | The I2C peripheral base address.

uint32_t I2C_GetInstance | ( | I2C_Type * | base | ) |

If an invalid base address is passed, debug builds will assert. Release builds will just return instance number 0.

Parameters

  base | The I2C peripheral base address.

Returns
  I2C instance number starting from 0.

static void I2C_MasterReset | ( | I2C_Type * | base | ) |

inlinestatic

Restores the I2C master peripheral to reset conditions.

Parameters

  base | The I2C peripheral base address.

static void I2C_MasterEnable | ( | I2C_Type * | base,
|  | bool | enable
| ) |  |

inlinestatic

Parameters

  base | The I2C peripheral base address.
  enable | Pass true to enable or false to disable the specified I2C as master.

static uint32_t I2C_GetStatusFlags | ( | I2C_Type * | base | ) |

inlinestatic

A bit mask with the state of all I2C status flags is returned. For each flag, the corresponding bit in the return value is set if the flag is asserted.

Parameters

  base | The I2C peripheral base address.

Returns
  State of the status flags:
  - 1: related status flag is set.
  - 0: related status flag is not set.

See Also
  _i2c_master_flags

static void I2C_MasterClearStatusFlags | ( | I2C_Type * | base,
|  | uint32_t | statusMask
| ) |  |

inlinestatic

The following status register flags can be cleared:

- kI2C_MasterArbitrationLostFlag
- kI2C_MasterStartStopErrorFlag

Attempts to clear other flags has no effect.

Parameters

  base | The I2C peripheral base address.
  statusMask | A bitmask of status flags that are to be cleared. The mask is composed of _i2c_master_flags enumerators OR'd together. You may pass the result of a previous call to I2C_GetStatusFlags().

See Also
  _i2c_master_flags.

static void I2C_EnableInterrupts | ( | I2C_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

inlinestatic

Parameters

  base | The I2C peripheral base address.
  interruptMask | Bit mask of interrupts to enable. See _i2c_master_flags for the set of constants that should be OR'd together to form the bit mask.

static void I2C_DisableInterrupts | ( | I2C_Type * | base,
|  | uint32_t | interruptMask
| ) |  |

inlinestatic

Parameters

  base | The I2C peripheral base address.
  interruptMask | Bit mask of interrupts to disable. See _i2c_master_flags for the set of constants that should be OR'd together to form the bit mask.

static uint32_t I2C_GetEnabledInterrupts | ( | I2C_Type * | base | ) |

inlinestatic

Parameters

  base | The I2C peripheral base address.

Returns
  A bitmask composed of _i2c_master_flags enumerators OR'd together to indicate the set of enabled interrupts.

void I2C_MasterSetBaudRate | ( | I2C_Type * | base,
|  | uint32_t | baudRate_Bps,
|  | uint32_t | srcClock_Hz
| ) |  |

The I2C master is automatically disabled and re-enabled as necessary to configure the baud rate. Do not call this function during a transfer, or the transfer is aborted.

Parameters

  base | The I2C peripheral base address.
  srcClock_Hz | I2C functional clock frequency in Hertz.
  baudRate_Bps | Requested bus frequency in bits per second.

static bool I2C_MasterGetBusIdleState | ( | I2C_Type * | base | ) |

inlinestatic

Requires the master mode to be enabled.

Parameters

  base | The I2C peripheral base address.

Return values

  true | Bus is busy.
  false | Bus is idle.

status_t I2C_MasterStart | ( | I2C_Type * | base,
|  | uint8_t | address,
|  | i2c_direction_t | direction
| ) |  |

This function is used to initiate a new master mode transfer by sending the START signal. The slave address is sent following the I2C START signal.

Parameters

  base | I2C peripheral base pointer
  address | 7-bit slave device address.
  direction | Master transfer directions(transmit/receive).

Return values

  kStatus_Success | Successfully send the start signal.
  kStatus_I2C_Busy | Current bus is busy.

status_t I2C_MasterStop | ( | I2C_Type * | base | ) |

Return values

  kStatus_Success | Successfully send the stop signal.
  kStatus_I2C_Timeout | Send stop signal failed, timeout.

static status_t I2C_MasterRepeatedStart | ( | I2C_Type * | base,
|  | uint8_t | address,
|  | i2c_direction_t | direction
| ) |  |

inlinestatic

Parameters

  base | I2C peripheral base pointer
  address | 7-bit slave device address.
  direction | Master transfer directions(transmit/receive).

Return values

  kStatus_Success | Successfully send the start signal.
  kStatus_I2C_Busy | Current bus is busy but not occupied by current I2C master.

status_t I2C_MasterWriteBlocking | ( | I2C_Type * | base,
|  | const void * | txBuff,
|  | size_t | txSize,
|  | uint32_t | flags
| ) |  |

Sends up to txSize number of bytes to the previously addressed slave device. The slave may reply with a NAK to any byte in order to terminate the transfer early. If this happens, this function returns kStatus_I2C_Nak.

Parameters

  base | The I2C peripheral base address.
  txBuff | The pointer to the data to be transferred.
  txSize | The length in bytes of the data to be transferred.
  flags | Transfer control flag to control special behavior like suppressing start or stop, for normal transfers use kI2C_TransferDefaultFlag

Return values

  kStatus_Success | Data was sent successfully.
  kStatus_I2C_Busy | Another master is currently utilizing the bus.
  kStatus_I2C_Nak | The slave device sent a NAK in response to a byte.
  kStatus_I2C_ArbitrationLost | Arbitration lost error.

status_t I2C_MasterReadBlocking | ( | I2C_Type * | base,
|  | void * | rxBuff,
|  | size_t | rxSize,
|  | uint32_t | flags
| ) |  |

Parameters

  base | The I2C peripheral base address.
  rxBuff | The pointer to the data to be transferred.
  rxSize | The length in bytes of the data to be transferred.
  flags | Transfer control flag to control special behavior like suppressing start or stop, for normal transfers use kI2C_TransferDefaultFlag

Return values

  kStatus_Success | Data was received successfully.
  kStatus_I2C_Busy | Another master is currently utilizing the bus.
  kStatus_I2C_Nak | The slave device sent a NAK in response to a byte.
  kStatus_I2C_ArbitrationLost | Arbitration lost error.

status_t I2C_MasterTransferBlocking | ( | I2C_Type * | base,
|  | i2c_master_transfer_t * | xfer
| ) |  |

Note
  The API does not return until the transfer succeeds or fails due to arbitration lost or receiving a NAK.

Parameters

  base | I2C peripheral base address.
  xfer | Pointer to the transfer structure.

Return values

  kStatus_Success | Successfully complete the data transmission.
  kStatus_I2C_Busy | Previous transmission still not finished.
  kStatus_I2C_Timeout | Transfer error, wait signal timeout.
  kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost.
  kStataus_I2C_Nak | Transfer error, receive NAK during transfer.

void I2C_MasterTransferCreateHandle | ( | I2C_Type * | base,
|  | i2c_master_handle_t * | handle,
|  | i2c_master_transfer_callback_t | callback,
|  | void * | userData
| ) |  |

The creation of a handle is for use with the non-blocking APIs. Once a handle is created, there is not a corresponding destroy handle. If the user wants to terminate a transfer, the I2C_MasterTransferAbort() API shall be called.

Parameters

  | base | The I2C peripheral base address.
  [out] | handle | Pointer to the I2C master driver handle.
  | callback | User provided pointer to the asynchronous callback function.
  | userData | User provided pointer to the application callback data.

status_t I2C_MasterTransferNonBlocking | ( | I2C_Type * | base,
|  | i2c_master_handle_t * | handle,
|  | i2c_master_transfer_t * | xfer
| ) |  |

Parameters

  base | The I2C peripheral base address.
  handle | Pointer to the I2C master driver handle.
  xfer | The pointer to the transfer descriptor.

Return values

  kStatus_Success | The transaction was started successfully.
  kStatus_I2C_Busy | Either another master is currently utilizing the bus, or a non-blocking transaction is already in progress.

status_t I2C_MasterTransferGetCount | ( | I2C_Type * | base,
|  | i2c_master_handle_t * | handle,
|  | size_t * | count
| ) |  |

Parameters

  | base | The I2C peripheral base address.
  | handle | Pointer to the I2C master driver handle.
  [out] | count | Number of bytes transferred so far by the non-blocking transaction.

Return values

  kStatus_Success |
  kStatus_I2C_Busy |

status_t I2C_MasterTransferAbort | ( | I2C_Type * | base,
|  | i2c_master_handle_t * | handle
| ) |  |

Note
  It is not safe to call this function from an IRQ handler that has a higher priority than the I2C peripheral's IRQ priority.

Parameters

  base | The I2C peripheral base address.
  handle | Pointer to the I2C master driver handle.

Return values

  kStatus_Success | A transaction was successfully aborted.
  kStatus_I2C_Timeout | Abort failure due to flags polling timeout.

void I2C_MasterTransferHandleIRQ | ( | I2C_Type * | base,
|  | void * | i2cHandle
| ) |  |

Note
  This function does not need to be called unless you are reimplementing the nonblocking API's interrupt handler routines to add special functionality.

Parameters

  base | The I2C peripheral base address.
  i2cHandle | Pointer to the I2C master driver handle i2c_master_handle_t.