All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
FlexIO I2C Master Driver
FlexIO: FlexIO Driver

## Overview

The KSDK provides a peripheral driver for I2C master function using Flexible I/O module of Kinetis devices.

The FlexIO I2C master driver includes functional APIs and transactional APIs.

Functional APIs are feature/property target low level APIs. Functional APIs can be used for the FlexIO I2C master initialization/configuration/operation for optimization/customization purpose. Using the functional APIs requires the knowledge of the FlexIO I2C master peripheral and how to organize functional APIs to meet the application requirements. The FlexIO I2C master functional operation groups provide the functional APIs set.

Transactional APIs are transaction target high level APIs. The transactional APIs can be used to enable the peripheral quickly and also in the application if the code size and performance of transactional APIs satisfy the requirements. If the code size and performance are critical requirements, see the transactional API implementation and write custom code using the functional APIs or accessing the hardware registers.

Transactional APIs support asynchronous transfer. This means that the functions FLEXIO_I2C_MasterTransferNonBlocking() set up the interrupt non-blocking transfer. When the transfer completes, the upper layer is notified through a callback function with the kStatus_Success status.

# Typical use case

## FlexIO I2C master transfer using an interrupt method

flexio_i2c_master_handle_t g_m_handle;
flexio_i2c_master_config_t masterConfig;
flexio_i2c_master_transfer_t masterXfer;
volatile bool completionFlag = false;
const uint8_t sendData[] = [......];
FLEXIO_I2C_Type i2cDev;
void FLEXIO_I2C_MasterCallback(FLEXIO_I2C_Type *base, status_t status, void *userData)
{
userData = userData;
if (kStatus_Success == status)
{
completionFlag = true;
}
}
void main(void)
{
//...
FLEXIO_I2C_MasterGetDefaultConfig(&masterConfig);
FLEXIO_I2C_MasterInit(&i2cDev, &user_config);
FLEXIO_I2C_MasterTransferCreateHandle(&i2cDev, &g_m_handle, FLEXIO_I2C_MasterCallback, NULL);
// Prepares to send.
masterXfer.slaveAddress = g_accel_address[0];
masterXfer.direction = kI2C_Read;
masterXfer.subaddress = &who_am_i_reg;
masterXfer.subaddressSize = 1;
masterXfer.data = &who_am_i_value;
masterXfer.dataSize = 1;
masterXfer.flags = kI2C_TransferDefaultFlag;
// Sends out.
FLEXIO_I2C_MasterTransferNonBlocking(&i2cDev, &g_m_handle, &masterXfer);
// Wait for sending is complete.
while (!completionFlag)
{
}
// ...
}

## Data Structures

struct | FLEXIO_I2C_Type
| Define FlexIO I2C master access structure typedef. More...
struct | flexio_i2c_master_config_t
| Define FlexIO I2C master user configuration structure. More...
struct | flexio_i2c_master_transfer_t
| Define FlexIO I2C master transfer structure. More...
struct | flexio_i2c_master_handle_t
| Define FlexIO I2C master handle structure. More...

## Typedefs

typedef void(* | flexio_i2c_master_transfer_callback_t )(FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, status_t status, void *userData)
| FlexIO I2C master transfer callback typedef. More...

## Enumerations

enum | _flexio_i2c_status { kStatus_FLEXIO_I2C_Busy = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 0), kStatus_FLEXIO_I2C_Idle = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 1), kStatus_FLEXIO_I2C_Nak = MAKE_STATUS(kStatusGroup_FLEXIO_I2C, 2) }
| FlexIO I2C transfer status. More...
enum | _flexio_i2c_master_interrupt { kFLEXIO_I2C_TxEmptyInterruptEnable = 0x1U, kFLEXIO_I2C_RxFullInterruptEnable = 0x2U }
| Define FlexIO I2C master interrupt mask. More...
enum | _flexio_i2c_master_status_flags { kFLEXIO_I2C_TxEmptyFlag = 0x1U, kFLEXIO_I2C_RxFullFlag = 0x2U, kFLEXIO_I2C_ReceiveNakFlag = 0x4U }
| Define FlexIO I2C master status mask. More...
enum | flexio_i2c_direction_t { kFLEXIO_I2C_Write = 0x0U, kFLEXIO_I2C_Read = 0x1U }
| Direction of master transfer. More...

## Driver version

#define | FSL_FLEXIO_I2C_MASTER_DRIVER_VERSION (MAKE_VERSION(2, 1, 2))
| FlexIO I2C master driver version 2.1.2. More...

## Initialization and deinitialization

void | FLEXIO_I2C_MasterInit (FLEXIO_I2C_Type *base, flexio_i2c_master_config_t *masterConfig, uint32_t srcClock_Hz)
| Ungates the FlexIO clock, resets the FlexIO module, and configures the FlexIO I2C hardware configuration. More...
void | FLEXIO_I2C_MasterDeinit (FLEXIO_I2C_Type *base)
| De-initializes the FlexIO I2C master peripheral. More...
void | FLEXIO_I2C_MasterGetDefaultConfig (flexio_i2c_master_config_t *masterConfig)
| Gets the default configuration to configure the FlexIO module. More...
static void | FLEXIO_I2C_MasterEnable (FLEXIO_I2C_Type *base, bool enable)
| Enables/disables the FlexIO module operation. More...

## Status

uint32_t | FLEXIO_I2C_MasterGetStatusFlags (FLEXIO_I2C_Type *base)
| Gets the FlexIO I2C master status flags. More...
void | FLEXIO_I2C_MasterClearStatusFlags (FLEXIO_I2C_Type *base, uint32_t mask)
| Clears the FlexIO I2C master status flags. More...

## Interrupts

void | FLEXIO_I2C_MasterEnableInterrupts (FLEXIO_I2C_Type *base, uint32_t mask)
| Enables the FlexIO i2c master interrupt requests. More...
void | FLEXIO_I2C_MasterDisableInterrupts (FLEXIO_I2C_Type *base, uint32_t mask)
| Disables the FlexIO I2C master interrupt requests. More...

## Bus Operations

void | FLEXIO_I2C_MasterSetBaudRate (FLEXIO_I2C_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz)
| Sets the FlexIO I2C master transfer baudrate. More...
void | FLEXIO_I2C_MasterStart (FLEXIO_I2C_Type *base, uint8_t address, flexio_i2c_direction_t direction)
| Sends START + 7-bit address to the bus. More...
void | FLEXIO_I2C_MasterStop (FLEXIO_I2C_Type *base)
| Sends the stop signal on the bus. More...
void | FLEXIO_I2C_MasterRepeatedStart (FLEXIO_I2C_Type *base)
| Sends the repeated start signal on the bus. More...
void | FLEXIO_I2C_MasterAbortStop (FLEXIO_I2C_Type *base)
| Sends the stop signal when transfer is still on-going. More...
void | FLEXIO_I2C_MasterEnableAck (FLEXIO_I2C_Type *base, bool enable)
| Configures the sent ACK/NAK for the following byte. More...
status_t | FLEXIO_I2C_MasterSetTransferCount (FLEXIO_I2C_Type *base, uint8_t count)
| Sets the number of bytes to be transferred from a start signal to a stop signal. More...
static void | FLEXIO_I2C_MasterWriteByte (FLEXIO_I2C_Type *base, uint32_t data)
| Writes one byte of data to the I2C bus. More...
static uint8_t | FLEXIO_I2C_MasterReadByte (FLEXIO_I2C_Type *base)
| Reads one byte of data from the I2C bus. More...
status_t | FLEXIO_I2C_MasterWriteBlocking (FLEXIO_I2C_Type *base, const uint8_t *txBuff, uint8_t txSize)
| Sends a buffer of data in bytes. More...
void | FLEXIO_I2C_MasterReadBlocking (FLEXIO_I2C_Type *base, uint8_t *rxBuff, uint8_t rxSize)
| Receives a buffer of bytes. More...
status_t | FLEXIO_I2C_MasterTransferBlocking (FLEXIO_I2C_Type *base, flexio_i2c_master_transfer_t *xfer)
| Performs a master polling transfer on the I2C bus. More...

## Transactional

status_t | FLEXIO_I2C_MasterTransferCreateHandle (FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, flexio_i2c_master_transfer_callback_t callback, void *userData)
| Initializes the I2C handle which is used in transactional functions. More...
status_t | FLEXIO_I2C_MasterTransferNonBlocking (FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, flexio_i2c_master_transfer_t *xfer)
| Performs a master interrupt non-blocking transfer on the I2C bus. More...
status_t | FLEXIO_I2C_MasterTransferGetCount (FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, size_t *count)
| Gets the master transfer status during a interrupt non-blocking transfer. More...
void | FLEXIO_I2C_MasterTransferAbort (FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle)
| Aborts an interrupt non-blocking transfer early. More...
void | FLEXIO_I2C_MasterTransferHandleIRQ (void *i2cType, void *i2cHandle)
| Master interrupt handler. More...

## Data Structure Documentation

struct FLEXIO_I2C_Type

### Data Fields

FLEXIO_Type * | flexioBase
| FlexIO base pointer. More...
uint8_t | SDAPinIndex
| Pin select for I2C SDA. More...
uint8_t | SCLPinIndex
| Pin select for I2C SCL. More...
uint8_t | shifterIndex [2]
| Shifter index used in FlexIO I2C. More...
uint8_t | timerIndex [2]
| Timer index used in FlexIO I2C. More...

#### Field Documentation

FLEXIO_Type* FLEXIO_I2C_Type::flexioBase

uint8_t FLEXIO_I2C_Type::SDAPinIndex

uint8_t FLEXIO_I2C_Type::SCLPinIndex

uint8_t FLEXIO_I2C_Type::shifterIndex[2]

uint8_t FLEXIO_I2C_Type::timerIndex[2]

struct flexio_i2c_master_config_t

### Data Fields

bool | enableMaster
| Enables the FLEXIO I2C peripheral at initialization time. More...
bool | enableInDoze
| Enable/disable FlexIO operation in doze mode. More...
bool | enableInDebug
| Enable/disable FlexIO operation in debug mode. More...
bool | enableFastAccess

     Enable/disable fast access to FlexIO registers, fast access requires

the FlexIO clock to be at least twice the frequency of the bus clock. More...

uint32_t | baudRate_Bps
| Baud rate in Bps. More...

#### Field Documentation

bool flexio_i2c_master_config_t::enableMaster

bool flexio_i2c_master_config_t::enableInDoze

bool flexio_i2c_master_config_t::enableInDebug

bool flexio_i2c_master_config_t::enableFastAccess

uint32_t flexio_i2c_master_config_t::baudRate_Bps

struct flexio_i2c_master_transfer_t

### Data Fields

uint32_t | flags
| Transfer flag which controls the transfer, reserved for FlexIO I2C. More...
uint8_t | slaveAddress
| 7-bit slave address. More...
flexio_i2c_direction_t | direction
| Transfer direction, read or write. More...
uint32_t | subaddress
| Sub address. More...
uint8_t | subaddressSize
| Size of command buffer. More...
uint8_t volatile * | data
| Transfer buffer. More...
volatile size_t | dataSize
| Transfer size. More...

#### Field Documentation

uint32_t flexio_i2c_master_transfer_t::flags

uint8_t flexio_i2c_master_transfer_t::slaveAddress

flexio_i2c_direction_t flexio_i2c_master_transfer_t::direction

uint32_t flexio_i2c_master_transfer_t::subaddress

Transferred MSB first.

uint8_t flexio_i2c_master_transfer_t::subaddressSize

uint8_t volatile* flexio_i2c_master_transfer_t::data

volatile size_t flexio_i2c_master_transfer_t::dataSize

struct _flexio_i2c_master_handle

FlexIO I2C master handle typedef.

### Data Fields

flexio_i2c_master_transfer_t | transfer
| FlexIO I2C master transfer copy. More...
size_t | transferSize
| Total bytes to be transferred. More...
uint8_t | state
| Transfer state maintained during transfer. More...
flexio_i2c_master_transfer_callback_t | completionCallback
| Callback function called at transfer event. More...
void * | userData
| Callback parameter passed to callback function. More...

#### Field Documentation

flexio_i2c_master_transfer_t flexio_i2c_master_handle_t::transfer

size_t flexio_i2c_master_handle_t::transferSize

uint8_t flexio_i2c_master_handle_t::state

flexio_i2c_master_transfer_callback_t flexio_i2c_master_handle_t::completionCallback

Callback function called at transfer event.

void* flexio_i2c_master_handle_t::userData

## Macro Definition Documentation

#define FSL_FLEXIO_I2C_MASTER_DRIVER_VERSION (MAKE_VERSION(2, 1, 2))

## Typedef Documentation

typedef void(* flexio_i2c_master_transfer_callback_t)(FLEXIO_I2C_Type *base, flexio_i2c_master_handle_t *handle, status_t status, void *userData)

## Enumeration Type Documentation

enum _flexio_i2c_status

Enumerator
kStatus_FLEXIO_I2C_Busy | I2C is busy doing transfer.
kStatus_FLEXIO_I2C_Idle | I2C is busy doing transfer.
kStatus_FLEXIO_I2C_Nak | NAK received during transfer.

enum _flexio_i2c_master_interrupt

Enumerator
kFLEXIO_I2C_TxEmptyInterruptEnable | Tx buffer empty interrupt enable.
kFLEXIO_I2C_RxFullInterruptEnable | Rx buffer full interrupt enable.

enum _flexio_i2c_master_status_flags

Enumerator
kFLEXIO_I2C_TxEmptyFlag | Tx shifter empty flag.
kFLEXIO_I2C_RxFullFlag | Rx shifter full/Transfer complete flag.
kFLEXIO_I2C_ReceiveNakFlag | Receive NAK flag.

enum flexio_i2c_direction_t

Enumerator
kFLEXIO_I2C_Write | Master send to slave.
kFLEXIO_I2C_Read | Master receive from slave.

## Function Documentation

void FLEXIO_I2C_MasterInit | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_config_t * | masterConfig,
|  | uint32_t | srcClock_Hz
| ) |  |

Example

FLEXIO_I2C_Type base = {
.flexioBase = FLEXIO,
.SDAPinIndex = 0,
.SCLPinIndex = 1,
.shifterIndex = {0,1},
.timerIndex = {0,1}
};
flexio_i2c_master_config_t config = {
.enableInDoze = false,
.enableInDebug = true,
.enableFastAccess = false,
.baudRate_Bps = 100000
};
FLEXIO_I2C_MasterInit(base, &config, srcClock_Hz);

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  masterConfig | pointer to flexio_i2c_master_config_t structure.
  srcClock_Hz | FlexIO source clock in Hz.

void FLEXIO_I2C_MasterDeinit | ( | FLEXIO_I2C_Type * | base | ) |

Calling this API gates the FlexIO clock, so the FlexIO I2C master module can't work unless call FLEXIO_I2C_MasterInit.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

void FLEXIO_I2C_MasterGetDefaultConfig | ( | flexio_i2c_master_config_t * | masterConfig | ) |

The configuration can be used directly for calling FLEXIO_I2C_MasterInit().

Example:

flexio_i2c_master_config_t config;
FLEXIO_I2C_MasterGetDefaultConfig(&config);

Parameters

  masterConfig | pointer to flexio_i2c_master_config_t structure.

static void FLEXIO_I2C_MasterEnable | ( | FLEXIO_I2C_Type * | base,
|  | bool | enable
| ) |  |

inlinestatic

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  enable | pass true to enable module, false to disable module.

uint32_t FLEXIO_I2C_MasterGetStatusFlags | ( | FLEXIO_I2C_Type * | base | ) |

Parameters

  base | pointer to FLEXIO_I2C_Type structure

Returns
  status flag, use status flag to AND _flexio_i2c_master_status_flags could get the related status.

void FLEXIO_I2C_MasterClearStatusFlags | ( | FLEXIO_I2C_Type * | base,
|  | uint32_t | mask
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

  mask

  status flag. The parameter could be any combination of the following values:
  - kFLEXIO_I2C_RxFullFlag
  - kFLEXIO_I2C_ReceiveNakFlag

void FLEXIO_I2C_MasterEnableInterrupts | ( | FLEXIO_I2C_Type * | base,
|  | uint32_t | mask
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

  mask

  interrupt source. Currently only one interrupt request source:
  - kFLEXIO_I2C_TransferCompleteInterruptEnable

void FLEXIO_I2C_MasterDisableInterrupts | ( | FLEXIO_I2C_Type * | base,
|  | uint32_t | mask
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  mask | interrupt source.

void FLEXIO_I2C_MasterSetBaudRate | ( | FLEXIO_I2C_Type * | base,
|  | uint32_t | baudRate_Bps,
|  | uint32_t | srcClock_Hz
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure
  baudRate_Bps | the baud rate value in HZ
  srcClock_Hz | source clock in HZ

void FLEXIO_I2C_MasterStart | ( | FLEXIO_I2C_Type * | base,
|  | uint8_t | address,
|  | flexio_i2c_direction_t | direction
| ) |  |

Note
  This is API should be called when transfer configuration is ready to send a START signal and 7-bit address to the bus. This is a non-blocking API, which returns directly after the address is put into the data register but not address transfer finished on the bus. Ensure that the kFLEXIO_I2C_RxFullFlag status is asserted before calling this API.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  address | 7-bit address.

  direction

  transfer direction. This parameter is one of the values in flexio_i2c_direction_t:
  - kFLEXIO_I2C_Write: Transmit
  - kFLEXIO_I2C_Read: Receive

void FLEXIO_I2C_MasterStop | ( | FLEXIO_I2C_Type * | base | ) |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

void FLEXIO_I2C_MasterRepeatedStart | ( | FLEXIO_I2C_Type * | base | ) |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

void FLEXIO_I2C_MasterAbortStop | ( | FLEXIO_I2C_Type * | base | ) |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

void FLEXIO_I2C_MasterEnableAck | ( | FLEXIO_I2C_Type * | base,
|  | bool | enable
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  enable | true to configure send ACK, false configure to send NAK.

status_t FLEXIO_I2C_MasterSetTransferCount | ( | FLEXIO_I2C_Type * | base,
|  | uint8_t | count
| ) |  |

Note
  Call this API before a transfer begins because the timer generates a number of clocks according to the number of bytes that need to be transferred.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  count | number of bytes need to be transferred from a start signal to a re-start/stop signal

Return values

  kStatus_Success | Successfully configured the count.
  kStatus_InvalidArgument | Input argument is invalid.

static void FLEXIO_I2C_MasterWriteByte | ( | FLEXIO_I2C_Type * | base,
|  | uint32_t | data
| ) |  |

inlinestatic

Note
  This is a non-blocking API, which returns directly after the data is put into the data register but not data transfer finished on the bus. Ensure that the TxEmptyFlag is asserted before calling this API.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  data | a byte of data.

static uint8_t FLEXIO_I2C_MasterReadByte | ( | FLEXIO_I2C_Type * | base | ) |

inlinestatic

Note
  This is a non-blocking API, which returns directly after the data is read from the data register. Ensure that the data is ready in the register.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.

Returns
  data byte read.

status_t FLEXIO_I2C_MasterWriteBlocking | ( | FLEXIO_I2C_Type * | base,
|  | const uint8_t * | txBuff,
|  | uint8_t | txSize
| ) |  |

Note
  This function blocks via polling until all bytes have been sent.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  txBuff | The data bytes to send.
  txSize | The number of data bytes to send.

Return values

  kStatus_Success | Successfully write data.
  kStatus_FLEXIO_I2C_Nak | Receive NAK during writing data.

void FLEXIO_I2C_MasterReadBlocking | ( | FLEXIO_I2C_Type * | base,
|  | uint8_t * | rxBuff,
|  | uint8_t | rxSize
| ) |  |

Note
  This function blocks via polling until all bytes have been received.

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  rxBuff | The buffer to store the received bytes.
  rxSize | The number of data bytes to be received.

status_t FLEXIO_I2C_MasterTransferBlocking | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_transfer_t * | xfer
| ) |  |

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

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  xfer | pointer to flexio_i2c_master_transfer_t structure.

Returns
  status of status_t.

status_t FLEXIO_I2C_MasterTransferCreateHandle | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_handle_t * | handle,
|  | flexio_i2c_master_transfer_callback_t | callback,
|  | void * | userData
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  handle | pointer to flexio_i2c_master_handle_t structure to store the transfer state.
  callback | pointer to user callback function.
  userData | user param passed to the callback function.

Return values

  kStatus_Success | Successfully create the handle.
  kStatus_OutOfRange | The FlexIO type/handle/isr table out of range.

status_t FLEXIO_I2C_MasterTransferNonBlocking | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_handle_t * | handle,
|  | flexio_i2c_master_transfer_t * | xfer
| ) |  |

Note
  The API returns immediately after the transfer initiates. Call FLEXIO_I2C_MasterGetTransferCount to poll the transfer status to check whether the transfer is finished. If the return status is not kStatus_FLEXIO_I2C_Busy, the transfer is finished.

Parameters

  base | pointer to FLEXIO_I2C_Type structure
  handle | pointer to flexio_i2c_master_handle_t structure which stores the transfer state
  xfer | pointer to flexio_i2c_master_transfer_t structure

Return values

  kStatus_Success | Successfully start a transfer.
  kStatus_FLEXIO_I2C_Busy | FlexIO I2C is not idle, is running another transfer.

status_t FLEXIO_I2C_MasterTransferGetCount | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_handle_t * | handle,
|  | size_t * | count
| ) |  |

Parameters

  base | pointer to FLEXIO_I2C_Type structure.
  handle | pointer to flexio_i2c_master_handle_t structure which stores the transfer state.
  count | Number of bytes transferred so far by the non-blocking transaction.

Return values

  kStatus_InvalidArgument | count is Invalid.
  kStatus_Success | Successfully return the count.

void FLEXIO_I2C_MasterTransferAbort | ( | FLEXIO_I2C_Type * | base,
|  | flexio_i2c_master_handle_t * | handle
| ) |  |

Note
  This API can be called at any time when an interrupt non-blocking transfer initiates to abort the transfer early.

Parameters

  base | pointer to FLEXIO_I2C_Type structure
  handle | pointer to flexio_i2c_master_handle_t structure which stores the transfer state

void FLEXIO_I2C_MasterTransferHandleIRQ | ( | void * | i2cType,
|  | void * | i2cHandle
| ) |  |

Parameters

  i2cType | pointer to FLEXIO_I2C_Type structure
  i2cHandle | pointer to flexio_i2c_master_transfer_t structure