Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM I2C (SERCOM I2C) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's SERCOM I2C module, for the transfer of data via an I2C bus.

The following driver API modes are covered by this manual:

The following peripheral is used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites.

Module Overview

The outline of this section is as follows:

Driver Feature Macro Definition

Driver Feature Macro Supported devices
FEATURE_I2C_FAST_MODE_PLUS_AND_HIGH_SPEED SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_10_BIT_ADDRESS SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_SCL_STRETCH_MODE SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
FEATURE_I2C_SCL_EXTEND_TIMEOUT SAM D21/R21/D10/D11/L21/L22/DA1/C20/C21/HA1/R34/R35
Note
The specific features are only available in the driver when the selected device supports those features.
When using the I2C high-speed mode for off-board communication, there are various high frequency interference, which can lead to distortion of the signals and communication failure. When using Xplained Pro boards in order to test I2C high-speed communication, the following recommendation should be followed:
  • Use the SDA-line on PA08 and SCL-line on PA09 for both boards. This will provide stronger pull-ups on both SDA and SCL.
  • The SCL should not be higher than 1.5MHz.

Functional Description

The I2C provides a simple two-wire bidirectional bus consisting of a wired-AND type serial clock line (SCL) and a wired-AND type serial data line (SDA).

The I2C bus provides a simple, but efficient method of interconnecting multiple master and slave devices. An arbitration mechanism is provided for resolving bus ownership between masters, as only one master device may own the bus at any given time. The arbitration mechanism relies on the wired-AND connections to avoid bus drivers short-circuiting.

A unique address is assigned to all slave devices connected to the bus. A device can contain both master and slave logic, and can emulate multiple slave devices by responding to more than one address.

Bus Topology

The I2C bus topology is illustrated in the figure below. The pull-up resistors (Rs) will provide a high level on the bus lines when none of the I2C devices are driving the bus. These are optional, and can be replaced with a constant current source.

bus_topology.svg
I2C Bus Topology

Transactions

The I2C standard defines three fundamental transaction formats:

A data transfer starts with the master issuing a Start condition on the bus, followed by the address of the slave together with a bit to indicate whether the master wants to read from or write to the slave. The addressed slave must respond to this by sending an ACK back to the master.

After this, data packets are sent from the master or slave, according to the read/write bit. Each packet must be acknowledged (ACK) or not acknowledged (NACK) by the receiver.

If a slave responds with a NACK, the master must assume that the slave cannot receive any more data and cancel the write operation.

The master completes a transaction by issuing a Stop condition.

A master can issue multiple Start conditions during a transaction; this is then called a Repeated Start condition.

Address Packets

The slave address consists of seven bits. The 8th bit in the transfer determines the data direction (read or write). An address packet always succeeds a Start or Repeated Start condition. The 8th bit is handled in the driver, and the user will only have to provide the 7-bit address.

Data Packets

Data packets are nine bits long, consisting of one 8-bit data byte, and an acknowledgement bit. Data packets follow either an address packet or another data packet on the bus.

Transaction Examples

The gray bits in the following examples are sent from master to slave, and the white bits are sent from slave to master. Example of a read transaction is shown in the figure below. Here, the master first issues a Start condition and gets ownership of the bus. An address packet with the direction flag set to read is then sent and acknowledged by the slave. Then the slave sends one data packet which is acknowledged by the master. The slave sends another packet, which is not acknowledged by the master and indicates that the master will terminate the transaction. In the end, the transaction is terminated by the master issuing a Stop condition.

i2c_read.svg
I2C Packet Read

Example of a write transaction is shown in the figure below. Here, the master first issues a Start condition and gets ownership of the bus. An address packet with the dir flag set to write is then sent and acknowledged by the slave. Then the master sends two data packets, each acknowledged by the slave. In the end, the transaction is terminated by the master issuing a Stop condition.

i2c_write.svg
I2C Packet Write

Packet Timeout

When a master sends an I2C packet, there is no way of being sure that a slave will acknowledge the packet. To avoid stalling the device forever while waiting for an acknowledge, a user selectable timeout is provided in the i2c_master_config struct which lets the driver exit a read or write operation after the specified time. The function will then return the STATUS_ERR_TIMEOUT flag.

This is also the case for the slave when using the functions postfixed _wait.

The time before the timeout occurs, will be the same as for unknown bus state timeout.

Repeated Start

To issue a Repeated Start, the functions postfixed _no_stop must be used. These functions will not send a Stop condition when the transfer is done, thus the next transfer will start with a Repeated Start. To end the transaction, the functions without the _no_stop postfix must be used for the last read/write.

Multi Master

In a multi master environment, arbitration of the bus is important, as only one master can own the bus at any point.

Arbitration

Clock stretching
The serial clock line is always driven by a master device. However, all devices connected to the bus are allowed stretch the low period of the clock to slow down the overall clock frequency or to insert wait states while processing data. Both master and slave can randomly stretch the clock, which will force the other device into a wait-state until the clock line goes high again.
Arbitration on the data line
If two masters start transmitting at the same time, they will both transmit until one master detects that the other master is pulling the data line low. When this is detected, the master not pulling the line low, will stop the transmission and wait until the bus is idle. As it is the master trying to contact the slave with the lowest address that will get the bus ownership, this will create an arbitration scheme always prioritizing the slaves with the lowest address in case of a bus collision.

Clock Synchronization

In situations where more than one master is trying to control the bus clock line at the same time, a clock synchronization algorithm based on the same principles used for clock stretching is necessary.

Bus States

As the I2C bus is limited to one transaction at the time, a master that wants to perform a bus transaction must wait until the bus is free. Because of this, it is necessary for all masters in a multi-master system to know the current status of the bus to be able to avoid conflicts and to ensure data integrity.

The bus state diagram can be seen in the figure below.

Bus Timing

Inactive bus timeout for the master and SDA hold time is configurable in the drivers.

Unknown Bus State Timeout

When a master is enabled or connected to the bus, the bus state will be unknown until either a given timeout or a stop command has occurred. The timeout is configurable in the i2c_master_config struct. The timeout time will depend on toolchain and optimization level used, as the timeout is a loop incrementing a value until it reaches the specified timeout value.

SDA Hold Timeout

When using the I2C in slave mode, it will be important to set a SDA hold time which assures that the master will be able to pick up the bit sent from the slave. The SDA hold time makes sure that this is the case by holding the data line low for a given period after the negative edge on the clock.

The SDA hold time is also available for the master driver, but is not a necessity.

Operation in Sleep Modes

The I2C module can operate in all sleep modes by setting the run_in_standby Boolean in the i2c_master_config or i2c_slave_config struct. The operation in slave and master mode is shown in the table below.

I2C Standby Operations
Run in standby Slave Master
false Disabled, all reception is dropped Generic Clock (GCLK) disabled when master is idle
true Wake on address match when enabled GCLK enabled while in sleep modes

Special Considerations

Interrupt-driven Operation

While an interrupt-driven operation is in progress, subsequent calls to a write or read operation will return the STATUS_BUSY flag, indicating that only one operation is allowed at any given time.

To check if another transmission can be initiated, the user can either call another transfer operation, or use the i2c_master_get_job_status/i2c_slave_get_job_status functions depending on mode.

If the user would like to get callback from operations while using the interrupt-driven driver, the callback must be registered and then enabled using the "register_callback" and "enable_callback" functions.

Extra Information

For extra information, see Extra Information for SERCOM I2C Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for SERCOM I2C Driver.

API Overview

Data Structures

struct  i2c_master_config
 Configuration structure for the I2C Master device. More...
 
struct  i2c_master_module
 SERCOM I2C Master driver software device instance structure. More...
 
struct  i2c_master_packet
 I2C master packet for read/write. More...
 
struct  i2c_slave_config
 Configuration structure for the I2C slave device. More...
 
struct  i2c_slave_module
 SERCOM I2C slave driver software device instance structure. More...
 
struct  i2c_slave_packet
 I2C slave packet for read/write. More...
 

Enumerations

enum  i2c_master_baud_rate {
  I2C_MASTER_BAUD_RATE_100KHZ = 100,
  I2C_MASTER_BAUD_RATE_400KHZ = 400
}
 I2C frequencies. More...
 
enum  i2c_master_callback {
  I2C_MASTER_CALLBACK_WRITE_COMPLETE = 0,
  I2C_MASTER_CALLBACK_READ_COMPLETE = 1,
  I2C_MASTER_CALLBACK_ERROR = 2
}
 Callback types. More...
 
enum  i2c_master_inactive_timeout {
  I2C_MASTER_INACTIVE_TIMEOUT_DISABLED = SERCOM_I2CM_CTRLA_INACTOUT(0),
  I2C_MASTER_INACTIVE_TIMEOUT_55US = SERCOM_I2CM_CTRLA_INACTOUT(1),
  I2C_MASTER_INACTIVE_TIMEOUT_105US = SERCOM_I2CM_CTRLA_INACTOUT(2),
  I2C_MASTER_INACTIVE_TIMEOUT_205US = SERCOM_I2CM_CTRLA_INACTOUT(3)
}
 Values for inactive bus time-out. More...
 
enum  i2c_master_interrupt_flag {
  I2C_MASTER_INTERRUPT_WRITE = 0,
  I2C_MASTER_INTERRUPT_READ = 1
}
 Interrupt flags. More...
 
enum  i2c_master_start_hold_time {
  I2C_MASTER_START_HOLD_TIME_DISABLED = SERCOM_I2CM_CTRLA_SDAHOLD(0),
  I2C_MASTER_START_HOLD_TIME_50NS_100NS = SERCOM_I2CM_CTRLA_SDAHOLD(1),
  I2C_MASTER_START_HOLD_TIME_300NS_600NS = SERCOM_I2CM_CTRLA_SDAHOLD(2),
  I2C_MASTER_START_HOLD_TIME_400NS_800NS = SERCOM_I2CM_CTRLA_SDAHOLD(3)
}
 Values for hold time after start bit. More...
 
enum  i2c_slave_address_mode {
  I2C_SLAVE_ADDRESS_MODE_MASK = SERCOM_I2CS_CTRLB_AMODE(0),
  I2C_SLAVE_ADDRESS_MODE_TWO_ADDRESSES = SERCOM_I2CS_CTRLB_AMODE(1),
  I2C_SLAVE_ADDRESS_MODE_RANGE = SERCOM_I2CS_CTRLB_AMODE(2)
}
 Enum for the possible address modes. More...
 
enum  i2c_slave_callback {
  I2C_SLAVE_CALLBACK_WRITE_COMPLETE,
  I2C_SLAVE_CALLBACK_READ_COMPLETE,
  I2C_SLAVE_CALLBACK_READ_REQUEST,
  I2C_SLAVE_CALLBACK_WRITE_REQUEST,
  I2C_SLAVE_CALLBACK_ERROR,
  I2C_SLAVE_CALLBACK_ERROR_LAST_TRANSFER
}
 Callback types. More...
 
enum  i2c_slave_direction {
  I2C_SLAVE_DIRECTION_READ,
  I2C_SLAVE_DIRECTION_WRITE,
  I2C_SLAVE_DIRECTION_NONE
}
 Enum for the direction of a request. More...
 
enum  i2c_slave_sda_hold_time {
  I2C_SLAVE_SDA_HOLD_TIME_DISABLED,
  I2C_SLAVE_SDA_HOLD_TIME_50NS_100NS,
  I2C_SLAVE_SDA_HOLD_TIME_300NS_600NS,
  I2C_SLAVE_SDA_HOLD_TIME_400NS_800NS
}
 Enum for the possible SDA hold times with respect to the negative edge of SCL. More...
 
enum  i2c_transfer_direction {
  I2C_TRANSFER_WRITE = 0,
  I2C_TRANSFER_READ = 1
}
 Transfer direction. More...
 

Lock/Unlock

static enum status_code i2c_master_lock (struct i2c_master_module *const module)
 Attempt to get lock on driver instance. More...
 
static void i2c_master_unlock (struct i2c_master_module *const module)
 Unlock driver instance. More...
 

Configuration and Initialization

static bool i2c_master_is_syncing (const struct i2c_master_module *const module)
 Returns the synchronization status of the module. More...
 
static void i2c_master_get_config_defaults (struct i2c_master_config *const config)
 Gets the I2C master default configurations. More...
 
enum status_code i2c_master_init (struct i2c_master_module *const module, Sercom *const hw, const struct i2c_master_config *const config)
 Initializes the requested I2C hardware module. More...
 
static void i2c_master_enable (const struct i2c_master_module *const module)
 Enables the I2C module. More...
 
static void i2c_master_disable (const struct i2c_master_module *const module)
 Disable the I2C module. More...
 
void i2c_master_reset (struct i2c_master_module *const module)
 Resets the hardware module. More...
 

Read and Write

enum status_code i2c_master_read_packet_wait (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Reads data packet from slave. More...
 
enum status_code i2c_master_read_packet_wait_no_stop (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Reads data packet from slave without sending a stop condition when done. More...
 
enum status_code i2c_master_write_packet_wait (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Writes data packet to slave. More...
 
enum status_code i2c_master_write_packet_wait_no_stop (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Writes data packet to slave without sending a stop condition when done. More...
 
void i2c_master_send_stop (struct i2c_master_module *const module)
 Sends stop condition on bus. More...
 
void i2c_master_send_nack (struct i2c_master_module *const module)
 Sends nack signal on bus. More...
 
enum status_code i2c_master_read_byte (struct i2c_master_module *const module, uint8_t *byte)
 Reads one byte data from slave. More...
 
enum status_code i2c_master_write_byte (struct i2c_master_module *const module, uint8_t byte)
 Write one byte data to slave. More...
 
enum status_code i2c_master_read_packet_wait_no_nack (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Reads data packet from slave without sending a nack signal and a stop condition when done. More...
 

Callbacks

void i2c_master_register_callback (struct i2c_master_module *const module, i2c_master_callback_t callback, enum i2c_master_callback callback_type)
 Registers callback for the specified callback type. More...
 
void i2c_master_unregister_callback (struct i2c_master_module *const module, enum i2c_master_callback callback_type)
 Unregisters callback for the specified callback type. More...
 
static void i2c_master_enable_callback (struct i2c_master_module *const module, enum i2c_master_callback callback_type)
 Enables callback. More...
 
static void i2c_master_disable_callback (struct i2c_master_module *const module, enum i2c_master_callback callback_type)
 Disables callback. More...
 

Read and Write, Interrupt-driven

enum status_code i2c_master_read_bytes (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 
enum status_code i2c_master_read_packet_job (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Initiates a read packet operation. More...
 
enum status_code i2c_master_read_packet_job_no_stop (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Initiates a read packet operation without sending a STOP condition when done. More...
 
enum status_code i2c_master_read_packet_job_no_nack (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Initiates a read packet operation without sending a NACK signal and a STOP condition when done. More...
 
enum status_code i2c_master_write_bytes (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 
enum status_code i2c_master_write_packet_job (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Initiates a write packet operation. More...
 
enum status_code i2c_master_write_packet_job_no_stop (struct i2c_master_module *const module, struct i2c_master_packet *const packet)
 Initiates a write packet operation without sending a STOP condition when done. More...
 
static void i2c_master_cancel_job (struct i2c_master_module *const module)
 Cancel any currently ongoing operation. More...
 
static enum status_code i2c_master_get_job_status (struct i2c_master_module *const module)
 Get status from ongoing job. More...
 

I2C Slave Status Flags

I2C slave status flags, returned by i2c_slave_get_status() and cleared by i2c_slave_clear_status().

#define I2C_SLAVE_STATUS_ADDRESS_MATCH   (1UL << 0)
 Address Match. More...
 
#define I2C_SLAVE_STATUS_DATA_READY   (1UL << 1)
 Data Ready. More...
 
#define I2C_SLAVE_STATUS_STOP_RECEIVED   (1UL << 2)
 Stop Received. More...
 
#define I2C_SLAVE_STATUS_CLOCK_HOLD   (1UL << 3)
 Clock Hold. More...
 
#define I2C_SLAVE_STATUS_SCL_LOW_TIMEOUT   (1UL << 4)
 SCL Low Timeout. More...
 
#define I2C_SLAVE_STATUS_REPEATED_START   (1UL << 5)
 Repeated Start. More...
 
#define I2C_SLAVE_STATUS_RECEIVED_NACK   (1UL << 6)
 Received not acknowledge. More...
 
#define I2C_SLAVE_STATUS_COLLISION   (1UL << 7)
 Transmit Collision. More...
 
#define I2C_SLAVE_STATUS_BUS_ERROR   (1UL << 8)
 Bus error. More...
 

Lock/Unlock

static enum status_code i2c_slave_lock (struct i2c_slave_module *const module)
 Attempt to get lock on driver instance. More...
 
static void i2c_slave_unlock (struct i2c_slave_module *const module)
 Unlock driver instance. More...
 

Configuration and Initialization

static bool i2c_slave_is_syncing (const struct i2c_slave_module *const module)
 Returns the synchronization status of the module. More...
 
static void i2c_slave_get_config_defaults (struct i2c_slave_config *const config)
 Gets the I2C slave default configurations. More...
 
enum status_code i2c_slave_init (struct i2c_slave_module *const module, Sercom *const hw, const struct i2c_slave_config *const config)
 Initializes the requested I2C hardware module. More...
 
static void i2c_slave_enable (const struct i2c_slave_module *const module)
 Enables the I2C module. More...
 
static void i2c_slave_disable (const struct i2c_slave_module *const module)
 Disables the I2C module. More...
 
void i2c_slave_reset (struct i2c_slave_module *const module)
 Resets the hardware module. More...
 

Read and Write

enum status_code i2c_slave_write_packet_wait (struct i2c_slave_module *const module, struct i2c_slave_packet *const packet)
 Writes a packet to the master. More...
 
enum status_code i2c_slave_read_packet_wait (struct i2c_slave_module *const module, struct i2c_slave_packet *const packet)
 Reads a packet from the master. More...
 
enum i2c_slave_direction i2c_slave_get_direction_wait (struct i2c_slave_module *const module)
 Waits for a start condition on the bus. More...
 

Status Management

uint32_t i2c_slave_get_status (struct i2c_slave_module *const module)
 Retrieves the current module status. More...
 
void i2c_slave_clear_status (struct i2c_slave_module *const module, uint32_t status_flags)
 Clears a module status flag. More...
 

Address Match Functionality

void i2c_slave_enable_nack_on_address (struct i2c_slave_module *const module)
 Enables sending of NACK on address match. More...
 
void i2c_slave_disable_nack_on_address (struct i2c_slave_module *const module)
 Disables sending NACK on address match. More...
 

Callbacks

void i2c_slave_register_callback (struct i2c_slave_module *const module, i2c_slave_callback_t callback, enum i2c_slave_callback callback_type)
 Registers callback for the specified callback type. More...
 
void i2c_slave_unregister_callback (struct i2c_slave_module *const module, enum i2c_slave_callback callback_type)
 Unregisters callback for the specified callback type. More...
 
static void i2c_slave_enable_callback (struct i2c_slave_module *const module, enum i2c_slave_callback callback_type)
 Enables callback. More...
 
static void i2c_slave_disable_callback (struct i2c_slave_module *const module, enum i2c_slave_callback callback_type)
 Disables callback. More...
 

Read and Write, Interrupt-Driven

enum status_code i2c_slave_read_packet_job (struct i2c_slave_module *const module, struct i2c_slave_packet *const packet)
 Initiates a reads packet operation. More...
 
enum status_code i2c_slave_write_packet_job (struct i2c_slave_module *const module, struct i2c_slave_packet *const packet)
 Initiates a write packet operation. More...
 
static void i2c_slave_cancel_job (struct i2c_slave_module *const module)
 Cancels any currently ongoing operation. More...
 
static enum status_code i2c_slave_get_job_status (struct i2c_slave_module *const module)
 Gets status of ongoing job. More...
 

#define I2C_SLAVE_STATUS_ADDRESS_MATCH   (1UL << 0)

Address Match.

Note
Should only be cleared internally by driver.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

#define I2C_SLAVE_STATUS_BUS_ERROR   (1UL << 8)

Bus error.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

#define I2C_SLAVE_STATUS_CLOCK_HOLD   (1UL << 3)

Clock Hold.

Note
Cannot be cleared, only valid when I2C_SLAVE_STATUS_ADDRESS_MATCH is set.

Referenced by i2c_slave_get_status().

#define I2C_SLAVE_STATUS_COLLISION   (1UL << 7)

Transmit Collision.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

#define I2C_SLAVE_STATUS_DATA_READY   (1UL << 1)

Data Ready.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

#define I2C_SLAVE_STATUS_RECEIVED_NACK   (1UL << 6)

Received not acknowledge.

Note
Cannot be cleared.

Referenced by i2c_slave_get_status().

#define I2C_SLAVE_STATUS_REPEATED_START   (1UL << 5)

Repeated Start.

Note
Cannot be cleared, only valid when I2C_SLAVE_STATUS_ADDRESS_MATCH is set.

Referenced by i2c_slave_get_status().

#define I2C_SLAVE_STATUS_SCL_LOW_TIMEOUT   (1UL << 4)

SCL Low Timeout.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

#define I2C_SLAVE_STATUS_STOP_RECEIVED   (1UL << 2)

Stop Received.

Referenced by i2c_slave_clear_status(), and i2c_slave_get_status().

I2C frequencies.

Values for I2C speeds supported by the module. The driver will also support setting any other value, in which case set the value in the i2c_master_config at desired value divided by 1000.

Example: If 10KHz operation is required, give baud_rate in the configuration structure the value 10.

Enumerator
I2C_MASTER_BAUD_RATE_100KHZ 

Baud rate at 100KHz (Standard-mode)

I2C_MASTER_BAUD_RATE_400KHZ 

Baud rate at 400KHz (Fast-mode)

Callback types.

The available callback types for the I2C master module.

Enumerator
I2C_MASTER_CALLBACK_WRITE_COMPLETE 

Callback for packet write complete.

I2C_MASTER_CALLBACK_READ_COMPLETE 

Callback for packet read complete.

I2C_MASTER_CALLBACK_ERROR 

Callback for error.

Values for inactive bus time-out.

If the inactive bus time-out is enabled and the bus is inactive for longer than the time-out setting, the bus state logic will be set to idle.

Enumerator
I2C_MASTER_INACTIVE_TIMEOUT_DISABLED 

Inactive bus time-out disabled.

I2C_MASTER_INACTIVE_TIMEOUT_55US 

Inactive bus time-out 5-6 SCL cycle time-out.

I2C_MASTER_INACTIVE_TIMEOUT_105US 

Inactive bus time-out 10-11 SCL cycle time-out.

I2C_MASTER_INACTIVE_TIMEOUT_205US 

Inactive bus time-out 20-21 SCL cycle time-out.

Interrupt flags.

Flags used when reading or setting interrupt flags.

Enumerator
I2C_MASTER_INTERRUPT_WRITE 

Interrupt flag used for write.

I2C_MASTER_INTERRUPT_READ 

Interrupt flag used for read.

Values for hold time after start bit.

Values for the possible I2C master mode SDA internal hold times after start bit has been sent.

Enumerator
I2C_MASTER_START_HOLD_TIME_DISABLED 

Internal SDA hold time disabled.

I2C_MASTER_START_HOLD_TIME_50NS_100NS 

Internal SDA hold time 50ns - 100ns.

I2C_MASTER_START_HOLD_TIME_300NS_600NS 

Internal SDA hold time 300ns - 600ns.

I2C_MASTER_START_HOLD_TIME_400NS_800NS 

Internal SDA hold time 400ns - 800ns.

Enum for the possible address modes.

Enum for the possible address modes.

Enumerator
I2C_SLAVE_ADDRESS_MODE_MASK 

Address match on address_mask used as a mask to address.

I2C_SLAVE_ADDRESS_MODE_TWO_ADDRESSES 

Address math on both address and address_mask.

I2C_SLAVE_ADDRESS_MODE_RANGE 

Address match on range of addresses between and including address and address_mask.

Callback types.

The available callback types for the I2C slave.

Enumerator
I2C_SLAVE_CALLBACK_WRITE_COMPLETE 

Callback for packet write complete.

I2C_SLAVE_CALLBACK_READ_COMPLETE 

Callback for packet read complete.

I2C_SLAVE_CALLBACK_READ_REQUEST 

Callback for read request from master - can be used to issue a write.

I2C_SLAVE_CALLBACK_WRITE_REQUEST 

Callback for write request from master - can be used to issue a read.

I2C_SLAVE_CALLBACK_ERROR 

Callback for error.

I2C_SLAVE_CALLBACK_ERROR_LAST_TRANSFER 

Callback for error in last transfer.

Discovered on a new address interrupt.

Enum for the direction of a request.

Enum for the direction of a request.

Enumerator
I2C_SLAVE_DIRECTION_READ 

Read.

I2C_SLAVE_DIRECTION_WRITE 

Write.

I2C_SLAVE_DIRECTION_NONE 

No direction.

Enum for the possible SDA hold times with respect to the negative edge of SCL.

Enum for the possible SDA hold times with respect to the negative edge of SCL.

Enumerator
I2C_SLAVE_SDA_HOLD_TIME_DISABLED 

SDA hold time disabled.

I2C_SLAVE_SDA_HOLD_TIME_50NS_100NS 

SDA hold time 50ns - 100ns.

I2C_SLAVE_SDA_HOLD_TIME_300NS_600NS 

SDA hold time 300ns - 600ns.

I2C_SLAVE_SDA_HOLD_TIME_400NS_800NS 

SDA hold time 400ns - 800ns.

Transfer direction.

For master: transfer direction or setting direction bit in address. For slave: direction of request from master.

Enumerator
I2C_TRANSFER_WRITE 

Master write operation is in progress.

I2C_TRANSFER_READ 

Master read operation is in progress.

static void i2c_master_cancel_job ( struct i2c_master_module *const  module)
inlinestatic

Cancel any currently ongoing operation.

Terminates the running transfer operation.

Parameters
[in,out]modulePointer to software module structure

References Assert, and STATUS_ABORTED.

static void i2c_master_disable ( const struct i2c_master_module *const  module)
inlinestatic

Disable the I2C module.

Disables the requested I2C module.

Parameters
[in]modulePointer to the software module struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_disable().

Referenced by i2c_master_reset().

static void i2c_master_disable_callback ( struct i2c_master_module *const  module,
enum i2c_master_callback  callback_type 
)
inlinestatic

Disables callback.

Disables the callback specified by the callback_type.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeCallback type to disable

References Assert.

static void i2c_master_enable ( const struct i2c_master_module *const  module)
inlinestatic

Enables the I2C module.

Enables the requested I2C module and set the bus state to IDLE after the specified timeout period if no stop bit is detected.

Parameters
[in]modulePointer to the software module struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_enable().

static void i2c_master_enable_callback ( struct i2c_master_module *const  module,
enum i2c_master_callback  callback_type 
)
inlinestatic

Enables callback.

Enables the callback specified by the callback_type.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeCallback type to enable

References Assert.

static void i2c_master_get_config_defaults ( struct i2c_master_config *const  config)
inlinestatic

Gets the I2C master default configurations.

Use to initialize the configuration structure to known default values.

The default configuration is as follows:

  • Baudrate 100KHz
  • GCLK generator 0
  • Do not run in standby
  • Start bit hold time 300ns - 600ns
  • Buffer timeout = 65535
  • Unknown bus status timeout = 65535
  • Do not run in standby
  • PINMUX_DEFAULT for SERCOM pads

Those default configuration only available if the device supports it:

  • High speed baudrate 3.4MHz
  • Standard-mode and Fast-mode transfer speed
  • SCL stretch disabled
  • Slave SCL low extend time-out disabled
  • Master SCL low extend time-out disabled
Parameters
[out]configPointer to configuration structure to be initiated

References Assert, i2c_master_config::baud_rate, i2c_master_config::buffer_timeout, GCLK_GENERATOR_0, i2c_master_config::generator_source, I2C_MASTER_BAUD_RATE_100KHZ, I2C_MASTER_INACTIVE_TIMEOUT_DISABLED, I2C_MASTER_START_HOLD_TIME_300NS_600NS, i2c_master_config::inactive_timeout, PINMUX_DEFAULT, i2c_master_config::pinmux_pad0, i2c_master_config::pinmux_pad1, i2c_master_config::run_in_standby, i2c_master_config::scl_low_timeout, i2c_master_config::sda_scl_rise_time_ns, i2c_master_config::start_hold_time, and i2c_master_config::unknown_bus_state_timeout.

static enum status_code i2c_master_get_job_status ( struct i2c_master_module *const  module)
inlinestatic

Get status from ongoing job.

Will return the status of a transfer operation.

Parameters
[in]modulePointer to software module structure
Returns
Last status code from transfer operation.
Return values
STATUS_OKNo error has occurred
STATUS_BUSYIf transfer is in progress
STATUS_BUSYIf master module is busy
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address
STATUS_ERR_TIMEOUTIf timeout occurred
STATUS_ERR_OVERFLOWIf slave did not acknowledge last sent data, indicating that slave does not want more data and was not able to read

References Assert.

enum status_code i2c_master_init ( struct i2c_master_module *const  module,
Sercom *const  hw,
const struct i2c_master_config *const  config 
)

Initializes the requested I2C hardware module.

Initializes the SERCOM I2C master device requested and sets the provided software module struct. Run this function before any further use of the driver.

Parameters
[out]modulePointer to software module struct
[in]hwPointer to the hardware instance
[in]configPointer to the configuration struct
Returns
Status of initialization.
Return values
STATUS_OKModule initiated correctly
STATUS_ERR_DENIEDIf module is enabled
STATUS_BUSYIf module is busy resetting
STATUS_ERR_ALREADY_INITIALIZEDIf setting other GCLK generator than previously set
STATUS_ERR_BAUDRATE_UNAVAILABLEIf given baudrate is not compatible with set GCLK frequency

References _i2c_master_interrupt_handler(), _sercom_get_sercom_inst_index(), _sercom_instances, _sercom_set_handler(), Assert, i2c_master_config::generator_source, sercom_set_gclk_generator(), system_gclk_chan_config::source_generator, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), and system_gclk_chan_set_config().

static bool i2c_master_is_syncing ( const struct i2c_master_module *const  module)
inlinestatic

Returns the synchronization status of the module.

Returns the synchronization status of the module.

Parameters
[in]modulePointer to software module structure
Returns
Status of the synchronization.
Return values
trueModule is busy synchronizing
falseModule is not synchronizing

References Assert.

static enum status_code i2c_master_lock ( struct i2c_master_module *const  module)
inlinestatic

Attempt to get lock on driver instance.

This function checks the instance's lock, which indicates whether or not it is currently in use, and sets the lock if it was not already set.

The purpose of this is to enable exclusive access to driver instances, so that, e.g., transactions by different services will not interfere with each other.

Parameters
[in,out]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf the module was already locked

References STATUS_BUSY, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

enum status_code i2c_master_read_byte ( struct i2c_master_module *const  module,
uint8_t *  byte 
)

Reads one byte data from slave.

Parameters
[in,out]modulePointer to software module struct
[out]byteRead one byte data to slave
Returns
Status of reading byte.
Return values
STATUS_OKOne byte was read successfully
STATUS_ERR_TIMEOUTIf no response was given within specified timeout period
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address

References _i2c_master_wait_for_bus().

enum status_code i2c_master_read_bytes ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Starts a read bytes operation.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting reading I2C packet.
Return values
STATUS_OKIf reading was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References Assert, i2c_master_packet::data, i2c_master_packet::data_length, I2C_TRANSFER_READ, STATUS_BUSY, and STATUS_OK.

enum status_code i2c_master_read_packet_job ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Initiates a read packet operation.

Reads a data packet from the specified slave address on the I2C bus. This is the non-blocking equivalent of i2c_master_read_packet_wait.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting reading I2C packet.
Return values
STATUS_OKIf reading was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_read_packet_job_no_nack ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Initiates a read packet operation without sending a NACK signal and a STOP condition when done.

Reads a data packet from the specified slave address on the I2C bus without sending a nack and a stop condition, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition must be performed.

This is the non-blocking equivalent of i2c_master_read_packet_wait_no_stop.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting reading I2C packet.
Return values
STATUS_OKIf reading was started successfully
STATUS_BUSYIf module is currently busy with another operation

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_read_packet_job_no_stop ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Initiates a read packet operation without sending a STOP condition when done.

Reads a data packet from the specified slave address on the I2C bus without sending a stop condition, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition must be performed.

This is the non-blocking equivalent of i2c_master_read_packet_wait_no_stop.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting reading I2C packet.
Return values
STATUS_OKIf reading was started successfully
STATUS_BUSYIf module is currently busy with another operation

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_read_packet_wait ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Reads data packet from slave.

Reads a data packet from the specified slave address on the I2C bus and sends a stop condition when finished.

Note
This will stall the device from any other operation. For interrupt-driven operation, see i2c_master_read_packet_job.
Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of reading packet.
Return values
STATUS_OKThe packet was read successfully
STATUS_ERR_TIMEOUTIf no response was given within specified timeout period
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_read_packet_wait_no_nack ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Reads data packet from slave without sending a nack signal and a stop condition when done.

Starts blocking read operation. Reads a data packet from the specified slave address on the I2C bus without sending a nack signal and a stop condition when done, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition must be performed.

Note
This will stall the device from any other operation. For interrupt-driven operation, see i2c_master_read_packet_job.
Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of reading packet.
Return values
STATUS_OKThe packet was read successfully
STATUS_ERR_TIMEOUTIf no response was given within specified timeout period
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_read_packet_wait_no_stop ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Reads data packet from slave without sending a stop condition when done.

Reads a data packet from the specified slave address on the I2C bus without sending a stop condition when done, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition must be performed.

Note
This will stall the device from any other operation. For interrupt-driven operation, see i2c_master_read_packet_job.
Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of reading packet.
Return values
STATUS_OKThe packet was read successfully
STATUS_ERR_TIMEOUTIf no response was given within specified timeout period
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address

References _i2c_master_read_packet(), Assert, and STATUS_BUSY.

void i2c_master_register_callback ( struct i2c_master_module *const  module,
const i2c_master_callback_t  callback,
enum i2c_master_callback  callback_type 
)

Registers callback for the specified callback type.

Associates the given callback function with the specified callback type.

To enable the callback, the i2c_master_enable_callback function must be used.

Parameters
[in,out]modulePointer to the software module struct
[in]callbackPointer to the function desired for the specified callback
[in]callback_typeCallback type to register

References Assert.

void i2c_master_reset ( struct i2c_master_module *const  module)

Resets the hardware module.

Reset the module to hardware defaults.

Parameters
[in,out]modulePointer to software module structure

References _sercom_get_interrupt_vector(), Assert, i2c_master_disable(), system_interrupt_clear_pending(), system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

void i2c_master_send_nack ( struct i2c_master_module *const  module)

Sends nack signal on bus.

Sends a nack signal on bus.

Note
This function can only be used after the i2c_master_write_packet_wait_no_nack function, or i2c_master_read_byte function.
Parameters
[in,out]modulePointer to the software instance struct

References Assert.

void i2c_master_send_stop ( struct i2c_master_module *const  module)

Sends stop condition on bus.

Sends a stop condition on bus.

Note
This function can only be used after the i2c_master_write_packet_wait_no_stop function. If a stop condition is to be sent after a read, the i2c_master_read_packet_wait function must be used.
Parameters
[in,out]modulePointer to the software instance struct

References Assert.

static void i2c_master_unlock ( struct i2c_master_module *const  module)
inlinestatic

Unlock driver instance.

This function clears the instance lock, indicating that it is available for use.

Parameters
[in,out]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf the module was already locked
void i2c_master_unregister_callback ( struct i2c_master_module *const  module,
enum i2c_master_callback  callback_type 
)

Unregisters callback for the specified callback type.

When called, the currently registered callback for the given callback type will be removed.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeSpecifies the callback type to unregister

References Assert.

enum status_code i2c_master_write_byte ( struct i2c_master_module *const  module,
uint8_t  byte 
)

Write one byte data to slave.

Parameters
[in,out]modulePointer to software module struct
[in]byteSend one byte data to slave
Returns
Status of writing byte.
Return values
STATUS_OKOne byte was write successfully
STATUS_ERR_TIMEOUTIf no response was given within specified timeout period
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address

References _i2c_master_wait_for_bus().

enum status_code i2c_master_write_bytes ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Starts a write bytes operation.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting write I2C bytes.
Return values
STATUS_OKIf writing was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References Assert, i2c_master_packet::data, i2c_master_packet::data_length, I2C_TRANSFER_WRITE, STATUS_BUSY, and STATUS_OK.

enum status_code i2c_master_write_packet_job ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Initiates a write packet operation.

Writes a data packet to the specified slave address on the I2C bus. This is the non-blocking equivalent of i2c_master_write_packet_wait.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting writing I2C packet job.
Return values
STATUS_OKIf writing was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References _i2c_master_write_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_write_packet_job_no_stop ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Initiates a write packet operation without sending a STOP condition when done.

Writes a data packet to the specified slave address on the I2C bus without sending a stop condition, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition or sending a stop with the i2c_master_send_stop function must be performed.

This is the non-blocking equivalent of i2c_master_write_packet_wait_no_stop.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting writing I2C packet job.
Return values
STATUS_OKIf writing was started successfully
STATUS_BUSYIf module is currently busy with another

References _i2c_master_write_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_write_packet_wait ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Writes data packet to slave.

Writes a data packet to the specified slave address on the I2C bus and sends a stop condition when finished.

Note
This will stall the device from any other operation. For interrupt-driven operation, see i2c_master_read_packet_job.
Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of write packet.
Return values
STATUS_OKIf packet was write successfully
STATUS_BUSYIf master module is busy with a job
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address
STATUS_ERR_TIMEOUTIf timeout occurred
STATUS_ERR_OVERFLOWIf slave did not acknowledge last sent data, indicating that slave does not want more data and was not able to read last data sent

References _i2c_master_write_packet(), Assert, and STATUS_BUSY.

enum status_code i2c_master_write_packet_wait_no_stop ( struct i2c_master_module *const  module,
struct i2c_master_packet *const  packet 
)

Writes data packet to slave without sending a stop condition when done.

Writes a data packet to the specified slave address on the I2C bus without sending a stop condition, thus retaining ownership of the bus when done. To end the transaction, a read or write with stop condition or sending a stop with the i2c_master_send_stop function must be performed.

Note
This will stall the device from any other operation. For interrupt-driven operation, see i2c_master_read_packet_job.
Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of write packet.
Return values
STATUS_OKIf packet was write successfully
STATUS_BUSYIf master module is busy
STATUS_ERR_DENIEDIf error on bus
STATUS_ERR_PACKET_COLLISIONIf arbitration is lost
STATUS_ERR_BAD_ADDRESSIf slave is busy, or no slave acknowledged the address
STATUS_ERR_TIMEOUTIf timeout occurred
STATUS_ERR_OVERFLOWIf slave did not acknowledge last sent data, indicating that slave do not want more data

References _i2c_master_write_packet(), Assert, and STATUS_BUSY.

static void i2c_slave_cancel_job ( struct i2c_slave_module *const  module)
inlinestatic

Cancels any currently ongoing operation.

Terminates the running transfer operation.

Parameters
[in,out]modulePointer to software module structure

References Assert.

void i2c_slave_clear_status ( struct i2c_slave_module *const  module,
uint32_t  status_flags 
)

Clears a module status flag.

Clears the given status flag of the module.

Note
Not all status flags can be cleared.
Parameters
[in]modulePointer to the I2C software device struct
[in]status_flagsBit mask of status flags to clear

References Assert, I2C_SLAVE_STATUS_ADDRESS_MATCH, I2C_SLAVE_STATUS_BUS_ERROR, I2C_SLAVE_STATUS_COLLISION, I2C_SLAVE_STATUS_DATA_READY, I2C_SLAVE_STATUS_SCL_LOW_TIMEOUT, and I2C_SLAVE_STATUS_STOP_RECEIVED.

static void i2c_slave_disable ( const struct i2c_slave_module *const  module)
inlinestatic

Disables the I2C module.

This will disable the I2C module specified in the provided software module structure.

Parameters
[in]modulePointer to the software module struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_disable().

Referenced by i2c_slave_reset().

static void i2c_slave_disable_callback ( struct i2c_slave_module *const  module,
enum i2c_slave_callback  callback_type 
)
inlinestatic

Disables callback.

Disables the callback specified by the callback_type.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeCallback type to disable

References Assert, I2C_SLAVE_CALLBACK_READ_REQUEST, I2C_SLAVE_CALLBACK_WRITE_REQUEST, and STATUS_BUSY.

void i2c_slave_disable_nack_on_address ( struct i2c_slave_module *const  module)

Disables sending NACK on address match.

Disables sending of NACK on address match, thus acknowledging incoming transactions.

Parameters
[in,out]modulePointer to software module structure

References Assert.

static void i2c_slave_enable ( const struct i2c_slave_module *const  module)
inlinestatic

Enables the I2C module.

This will enable the requested I2C module.

Parameters
[in]modulePointer to the software module struct

References _sercom_get_interrupt_vector(), Assert, and system_interrupt_enable().

static void i2c_slave_enable_callback ( struct i2c_slave_module *const  module,
enum i2c_slave_callback  callback_type 
)
inlinestatic

Enables callback.

Enables the callback specified by the callback_type.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeCallback type to enable

References Assert, I2C_SLAVE_CALLBACK_READ_REQUEST, and I2C_SLAVE_CALLBACK_WRITE_REQUEST.

void i2c_slave_enable_nack_on_address ( struct i2c_slave_module *const  module)

Enables sending of NACK on address match.

Enables sending of NACK on address match, thus discarding any incoming transaction.

Parameters
[in,out]modulePointer to software module structure

References Assert.

static void i2c_slave_get_config_defaults ( struct i2c_slave_config *const  config)
inlinestatic

Gets the I2C slave default configurations.

This will initialize the configuration structure to known default values.

The default configuration is as follows:

  • Disable SCL low timeout
  • 300ns - 600ns SDA hold time
  • Buffer timeout = 65535
  • Address with mask
  • Address = 0
  • Address mask = 0 (one single address)
  • General call address disabled
  • Address nack disabled if the interrupt driver is used
  • GCLK generator 0
  • Do not run in standby
  • PINMUX_DEFAULT for SERCOM pads

Those default configuration only available if the device supports it:

  • Not using 10-bit addressing
  • Standard-mode and Fast-mode transfer speed
  • SCL stretch disabled
  • Slave SCL low extend time-out disabled
Parameters
[out]configPointer to configuration structure to be initialized

References i2c_slave_config::address, i2c_slave_config::address_mask, i2c_slave_config::address_mode, Assert, i2c_slave_config::buffer_timeout, i2c_slave_config::enable_general_call_address, i2c_slave_config::enable_nack_on_address, i2c_slave_config::enable_scl_low_timeout, GCLK_GENERATOR_0, i2c_slave_config::generator_source, I2C_SLAVE_ADDRESS_MODE_MASK, I2C_SLAVE_SDA_HOLD_TIME_300NS_600NS, PINMUX_DEFAULT, i2c_slave_config::pinmux_pad0, i2c_slave_config::pinmux_pad1, i2c_slave_config::run_in_standby, i2c_slave_config::scl_low_timeout, and i2c_slave_config::sda_hold_time.

enum i2c_slave_direction i2c_slave_get_direction_wait ( struct i2c_slave_module *const  module)

Waits for a start condition on the bus.

Note
This function is only available for 7-bit slave addressing.

Waits for the master to issue a start condition on the bus.

Note
This function does not check for errors in the last transfer, this will be discovered when reading or writing.
Parameters
[in]modulePointer to software module structure
Returns
Direction of the current transfer, when in slave mode.
Return values
I2C_SLAVE_DIRECTION_NONENo request from master within timeout period
I2C_SLAVE_DIRECTION_READWrite request from master
I2C_SLAVE_DIRECTION_WRITERead request from master

References _i2c_slave_wait_for_bus(), Assert, I2C_SLAVE_DIRECTION_NONE, I2C_SLAVE_DIRECTION_READ, I2C_SLAVE_DIRECTION_WRITE, and STATUS_OK.

static enum status_code i2c_slave_get_job_status ( struct i2c_slave_module *const  module)
inlinestatic

Gets status of ongoing job.

Will return the status of the ongoing job, or the error that occurred in the last transfer operation. The status will be cleared when starting a new job.

Parameters
[in,out]modulePointer to software module structure
Returns
Status of job.
Return values
STATUS_OKNo error has occurred
STATUS_BUSYTransfer is in progress
STATUS_ERR_IOA collision, timeout or bus error happened in the last transfer
STATUS_ERR_TIMEOUTA timeout occurred
STATUS_ERR_OVERFLOWData from master overflows receive buffer

References Assert.

uint32_t i2c_slave_get_status ( struct i2c_slave_module *const  module)

Retrieves the current module status.

Checks the status of the module and returns it as a bitmask of status flags.

Parameters
[in]modulePointer to the I2C slave software device struct
Returns
Bitmask of status flags.
Return values
I2C_SLAVE_STATUS_ADDRESS_MATCHA valid address has been received
I2C_SLAVE_STATUS_DATA_READYA I2C slave byte transmission is successfully completed
I2C_SLAVE_STATUS_STOP_RECEIVEDA stop condition is detected for a transaction being processed
I2C_SLAVE_STATUS_CLOCK_HOLDThe slave is holding the SCL line low
I2C_SLAVE_STATUS_SCL_LOW_TIMEOUTAn SCL low time-out has occurred
I2C_SLAVE_STATUS_REPEATED_STARTIndicates a repeated start, only valid if I2C_SLAVE_STATUS_ADDRESS_MATCH is set
I2C_SLAVE_STATUS_RECEIVED_NACKThe last data packet sent was not acknowledged
I2C_SLAVE_STATUS_COLLISIONThe I2C slave was not able to transmit a high data or NACK bit
I2C_SLAVE_STATUS_BUS_ERRORAn illegal bus condition has occurred on the bus

References Assert, I2C_SLAVE_STATUS_ADDRESS_MATCH, I2C_SLAVE_STATUS_BUS_ERROR, I2C_SLAVE_STATUS_CLOCK_HOLD, I2C_SLAVE_STATUS_COLLISION, I2C_SLAVE_STATUS_DATA_READY, I2C_SLAVE_STATUS_RECEIVED_NACK, I2C_SLAVE_STATUS_REPEATED_START, I2C_SLAVE_STATUS_SCL_LOW_TIMEOUT, and I2C_SLAVE_STATUS_STOP_RECEIVED.

enum status_code i2c_slave_init ( struct i2c_slave_module *const  module,
Sercom *const  hw,
const struct i2c_slave_config *const  config 
)

Initializes the requested I2C hardware module.

Initializes the SERCOM I2C slave device requested and sets the provided software module struct. Run this function before any further use of the driver.

Parameters
[out]modulePointer to software module struct
[in]hwPointer to the hardware instance
[in]configPointer to the configuration struct
Returns
Status of initialization.
Return values
STATUS_OKModule initiated correctly
STATUS_ERR_DENIEDIf module is enabled
STATUS_BUSYIf module is busy resetting
STATUS_ERR_ALREADY_INITIALIZEDIf setting other GCLK generator than previously set

References _i2c_slave_interrupt_handler(), _i2c_slave_set_config(), _sercom_get_sercom_inst_index(), _sercom_instances, _sercom_set_handler(), Assert, i2c_slave_config::enable_nack_on_address, i2c_slave_config::generator_source, sercom_set_gclk_generator(), system_gclk_chan_config::source_generator, STATUS_BUSY, STATUS_ERR_DENIED, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), and system_gclk_chan_set_config().

static bool i2c_slave_is_syncing ( const struct i2c_slave_module *const  module)
inlinestatic

Returns the synchronization status of the module.

Returns the synchronization status of the module.

Parameters
[out]modulePointer to software module structure
Returns
Status of the synchronization.
Return values
trueModule is busy synchronizing
falseModule is not synchronizing

References Assert.

static enum status_code i2c_slave_lock ( struct i2c_slave_module *const  module)
inlinestatic

Attempt to get lock on driver instance.

This function checks the instance's lock, which indicates whether or not it is currently in use, and sets the lock if it was not already set.

The purpose of this is to enable exclusive access to driver instances, so that, e.g., transactions by different services will not interfere with each other.

Parameters
[in,out]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf the module was already locked

References STATUS_BUSY, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

enum status_code i2c_slave_read_packet_job ( struct i2c_slave_module *const  module,
struct i2c_slave_packet *const  packet 
)

Initiates a reads packet operation.

Reads a data packet from the master. A write request must be initiated by the master before the packet can be read.

The I2C_SLAVE_CALLBACK_WRITE_REQUEST callback can be used to call this function.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting asynchronously reading I2C packet.
Return values
STATUS_OKIf reading was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References Assert, i2c_slave_packet::data, i2c_slave_packet::data_length, STATUS_BUSY, and STATUS_OK.

enum status_code i2c_slave_read_packet_wait ( struct i2c_slave_module *const  module,
struct i2c_slave_packet *const  packet 
)

Reads a packet from the master.

Reads a packet from the master. This will wait for the master to issue a request.

Parameters
[in]modulePointer to software module structure
[out]packetPacket to read from master
Returns
Status of packet read.
Return values
STATUS_OKPacket was read successfully
STATUS_ABORTEDMaster sent stop condition or repeated start before specified length of bytes was received
STATUS_ERR_IOThere was an error in the previous transfer
STATUS_ERR_DENIEDStart condition not received, another interrupt flag is set
STATUS_ERR_INVALID_ARGInvalid argument(s) was provided
STATUS_ERR_BUSYThe I2C module is busy with a job
STATUS_ERR_BAD_FORMATMaster wants to read data
STATUS_ERR_ERR_OVERFLOWLast byte received overflows buffer

References _i2c_slave_wait_for_bus(), Assert, i2c_slave_packet::data, i2c_slave_packet::data_length, STATUS_ABORTED, STATUS_BUSY, STATUS_ERR_BAD_FORMAT, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_IO, and STATUS_OK.

void i2c_slave_register_callback ( struct i2c_slave_module *const  module,
i2c_slave_callback_t  callback,
enum i2c_slave_callback  callback_type 
)

Registers callback for the specified callback type.

Associates the given callback function with the specified callback type. To enable the callback, the i2c_slave_enable_callback function must be used.

Parameters
[in,out]modulePointer to the software module struct
[in]callbackPointer to the function desired for the specified callback
[in]callback_typeCallback type to register

References Assert.

void i2c_slave_reset ( struct i2c_slave_module *const  module)

Resets the hardware module.

This will reset the module to hardware defaults.

Parameters
[in,out]modulePointer to software module structure

References _sercom_get_interrupt_vector(), Assert, i2c_slave_disable(), system_interrupt_clear_pending(), system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

static void i2c_slave_unlock ( struct i2c_slave_module *const  module)
inlinestatic

Unlock driver instance.

This function clears the instance lock, indicating that it is available for use.

Parameters
[in,out]modulePointer to the driver instance to lock
Return values
STATUS_OKIf the module was locked
STATUS_BUSYIf the module was already locked
void i2c_slave_unregister_callback ( struct i2c_slave_module *const  module,
enum i2c_slave_callback  callback_type 
)

Unregisters callback for the specified callback type.

Removes the currently registered callback for the given callback type.

Parameters
[in,out]modulePointer to the software module struct
[in]callback_typeCallback type to unregister

References Assert.

enum status_code i2c_slave_write_packet_job ( struct i2c_slave_module *const  module,
struct i2c_slave_packet *const  packet 
)

Initiates a write packet operation.

Writes a data packet to the master. A read request must be initiated by the master before the packet can be written.

The I2C_SLAVE_CALLBACK_READ_REQUEST callback can be used to call this function.

Parameters
[in,out]modulePointer to software module struct
[in,out]packetPointer to I2C packet to transfer
Returns
Status of starting writing I2C packet.
Return values
STATUS_OKIf writing was started successfully
STATUS_BUSYIf module is currently busy with another transfer

References Assert, i2c_slave_packet::data, i2c_slave_packet::data_length, STATUS_BUSY, and STATUS_OK.

enum status_code i2c_slave_write_packet_wait ( struct i2c_slave_module *const  module,
struct i2c_slave_packet *const  packet 
)

Writes a packet to the master.

Writes a packet to the master. This will wait for the master to issue a request.

Parameters
[in]modulePointer to software module structure
[in]packetPacket to write to master
Returns
Status of packet write.
Return values
STATUS_OKPacket was written successfully
STATUS_ERR_DENIEDStart condition not received, another interrupt flag is set
STATUS_ERR_IOThere was an error in the previous transfer
STATUS_ERR_BAD_FORMATMaster wants to write data
STATUS_ERR_INVALID_ARGInvalid argument(s) was provided
STATUS_ERR_BUSYThe I2C module is busy with a job
STATUS_ERR_ERR_OVERFLOWMaster NACKed before entire packet was transferred
STATUS_ERR_TIMEOUTNo response was given within the timeout period

References _i2c_slave_wait_for_bus(), Assert, i2c_slave_packet::data, i2c_slave_packet::data_length, STATUS_BUSY, STATUS_ERR_BAD_FORMAT, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_ERR_IO, STATUS_ERR_OVERFLOW, STATUS_ERR_TIMEOUT, and STATUS_OK.