Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
High-Speed Two-Wire Interface (TWIHS)

Driver for the TWIHS (High-Speed Two-Wire Interface).

This driver provides access to the main features of the TWIHS controller. The TWIHS interconnects components on a unique two-wire bus. The TWIHS is programmable as a master or a slave with sequential or single-byte access. Multiple master capability is supported. The High Speed of 3.4Mbits per second can be achieved in slave mode only.

Usage
  1. Enable the TWIHS peripheral clock in the PMC.
  2. Enable the required TWIHS PIOs (see pio.h).
  3. Enable TWIHS master mode by calling twihs_enable_master_mode if it is a master on the I2C bus.
  4. Configure the TWIHS in master mode by calling twihs_master_init.
  5. Send data to a slave device on the I2C bus by calling twihs_master_write.
  6. Receive data from a slave device on the I2C bus by calling the twihs_master_read.
  7. Enable TWIHS slave mode by calling twihs_enable_slave_mode if it is a slave on the I2C bus.
  8. Configure the TWIHS in slave mode by calling twihs_slave_init.

Macros

#define I2C_FAST_MODE_SPEED   400000
 
#define LOW_LEVEL_TIME_LIMIT   384000
 
#define TWIHS_CLK_CALC_ARGU   3
 
#define TWIHS_CLK_DIV_MAX   0xFF
 
#define TWIHS_CLK_DIV_MIN   7
 
#define TWIHS_CLK_DIVIDER   2
 

Functions

void twihs_disable_interrupt (Twihs *p_twihs, uint32_t ul_sources)
 Disable TWIHS interrupts. More...
 
void twihs_disable_master_mode (Twihs *p_twihs)
 Disable TWIHS master mode. More...
 
void twihs_disable_slave_mode (Twihs *p_twihs)
 Disable TWIHS slave mode. More...
 
void twihs_enable_interrupt (Twihs *p_twihs, uint32_t ul_sources)
 Enable TWIHS interrupts. More...
 
void twihs_enable_master_mode (Twihs *p_twihs)
 Enable TWIHS master mode. More...
 
void twihs_enable_slave_mode (Twihs *p_twihs)
 Enable TWIHS slave mode. More...
 
uint32_t twihs_get_interrupt_mask (Twihs *p_twihs)
 Read TWIHS interrupt mask. More...
 
uint32_t twihs_get_interrupt_status (Twihs *p_twihs)
 Get TWIHS interrupt status. More...
 
Pdc * twihs_get_pdc_base (Twihs *p_twihs)
 Get TWIHS PDC base address. More...
 
void twihs_mask_slave_addr (Twihs *p_twihs, uint32_t ul_mask)
 A mask can be applied on the slave device address in slave mode in order to allow multiple address answer. More...
 
uint32_t twihs_master_init (Twihs *p_twihs, const twihs_options_t *p_opt)
 Initialize TWIHS master mode. More...
 
uint32_t twihs_master_read (Twihs *p_twihs, twihs_packet_t *p_packet)
 Read multiple bytes from a TWIHS compatible slave device. More...
 
uint32_t twihs_master_write (Twihs *p_twihs, twihs_packet_t *p_packet)
 Write multiple bytes to a TWIHS compatible slave device. More...
 
static uint32_t twihs_mk_addr (const uint8_t *addr, int len)
 Construct the TWIHS module address register field. More...
 
uint32_t twihs_probe (Twihs *p_twihs, uint8_t uc_slave_addr)
 Test if a chip answers a given I2C address. More...
 
uint8_t twihs_read_byte (Twihs *p_twihs)
 Reads a byte from the TWIHS bus. More...
 
void twihs_read_write_protection_status (Twihs *p_twihs, uint32_t *p_status)
 Read the write protection status. More...
 
void twihs_reset (Twihs *p_twihs)
 Reset TWIHS. More...
 
void twihs_set_alternative_command (Twihs *p_twihs, uint32_t ul_alt_cmd)
 Set length/direction/PEC for alternative command mode. More...
 
void twihs_set_filter (Twihs *p_twihs, uint32_t ul_filter)
 Set the filter for TWIHS. More...
 
void twihs_set_slave_addr (Twihs *p_twihs, uint32_t ul_device_addr)
 Set TWIHS slave address. More...
 
void twihs_set_sleepwalking (Twihs *p_twihs, uint32_t ul_matching_addr1, bool flag1, uint32_t ul_matching_addr2, bool flag2, uint32_t ul_matching_addr3, bool flag3, uint32_t ul_matching_data, bool flag)
 Set sleepwalking match mode. More...
 
uint32_t twihs_set_speed (Twihs *p_twihs, uint32_t ul_speed, uint32_t ul_mck)
 Set the I2C bus speed in conjunction with the clock frequency. More...
 
void twihs_set_write_protection (Twihs *p_twihs, bool flag)
 Enables/Disables write protection mode. More...
 
void twihs_slave_init (Twihs *p_twihs, uint32_t ul_device_addr)
 Initialize TWIHS slave mode. More...
 
uint32_t twihs_slave_read (Twihs *p_twihs, uint8_t *p_data)
 Read data from master. More...
 
uint32_t twihs_slave_write (Twihs *p_twihs, uint8_t *p_data)
 Write data to TWIHS bus. More...
 
void twihs_smbus_set_timing (Twihs *p_twihs, uint32_t ul_timing)
 Set the prescaler, TLOW:SEXT, TLOW:MEXT and clock high max cycles for SMBUS mode. More...
 
void twihs_write_byte (Twihs *p_twihs, uint8_t uc_byte)
 Sends a byte of data to one of the TWIHS slaves on the bus. More...
 

#define I2C_FAST_MODE_SPEED   400000

Referenced by twihs_set_speed().

#define LOW_LEVEL_TIME_LIMIT   384000

Referenced by twihs_set_speed().

#define TWIHS_CLK_CALC_ARGU   3

Referenced by twihs_set_speed().

#define TWIHS_CLK_DIV_MAX   0xFF

Referenced by twihs_set_speed().

#define TWIHS_CLK_DIV_MIN   7

Referenced by twihs_set_speed().

#define TWIHS_CLK_DIVIDER   2

Referenced by twihs_set_speed().

void twihs_disable_interrupt ( Twihs *  p_twihs,
uint32_t  ul_sources 
)

Disable TWIHS interrupts.

Parameters
p_twihsPointer to a TWIHS instance.
ul_sourcesInterrupts to be disabled.
void twihs_disable_master_mode ( Twihs *  p_twihs)

Disable TWIHS master mode.

Parameters
p_twihsPointer to a TWIHS instance.
void twihs_disable_slave_mode ( Twihs *  p_twihs)

Disable TWIHS slave mode.

Parameters
p_twihsPointer to a TWIHS instance.
void twihs_enable_interrupt ( Twihs *  p_twihs,
uint32_t  ul_sources 
)

Enable TWIHS interrupts.

Parameters
p_twihsPointer to a TWIHS instance.
ul_sourcesInterrupts to be enabled.
void twihs_enable_master_mode ( Twihs *  p_twihs)

Enable TWIHS master mode.

Parameters
p_twihsPointer to a TWIHS instance.

Referenced by twihs_master_init().

void twihs_enable_slave_mode ( Twihs *  p_twihs)

Enable TWIHS slave mode.

Parameters
p_twihsPointer to a TWIHS instance.

Referenced by twihs_slave_init().

uint32_t twihs_get_interrupt_mask ( Twihs *  p_twihs)

Read TWIHS interrupt mask.

Parameters
p_twihsPointer to a TWIHS instance.
Returns
The interrupt mask value.
uint32_t twihs_get_interrupt_status ( Twihs *  p_twihs)

Get TWIHS interrupt status.

Parameters
p_twihsPointer to a TWIHS instance.
Return values
TWIHSinterrupt status.
Pdc* twihs_get_pdc_base ( Twihs *  p_twihs)

Get TWIHS PDC base address.

Parameters
p_twihsPointer to a TWIHS instance.
Returns
TWIHS PDC registers base for PDC driver to access.

References Assert, and NULL.

void twihs_mask_slave_addr ( Twihs *  p_twihs,
uint32_t  ul_mask 
)

A mask can be applied on the slave device address in slave mode in order to allow multiple address answer.

For each bit of the MASK field set to one the corresponding SADR bit will be masked.

Parameters
p_twihsBase address of the TWIHS instance.
ul_maskMask value.
uint32_t twihs_master_init ( Twihs *  p_twihs,
const twihs_options_t p_opt 
)

Initialize TWIHS master mode.

Parameters
p_twihsPointer to a TWIHS instance.
p_optOptions for initializing the TWIHS module (see twihs_options_t).
Returns
TWIHS_SUCCESS if initialization is complete, error code otherwise.

References FAIL, twihs_options::master_clk, twihs_options::speed, twihs_enable_master_mode(), TWIHS_INVALID_ARGUMENT, twihs_reset(), twihs_set_speed(), and TWIHS_SUCCESS.

Referenced by nm_bus_init().

uint32_t twihs_master_read ( Twihs *  p_twihs,
twihs_packet_t p_packet 
)

Read multiple bytes from a TWIHS compatible slave device.

Note
This function will NOT return until all data has been read or error occurs.
Parameters
p_twihsPointer to a TWIHS instance.
p_packetPacket information and data (see twihs_packet_t).
Returns
TWIHS_SUCCESS if all bytes were read, error code otherwise.

References twihs_packet::addr, twihs_packet::addr_length, twihs_packet::buffer, twihs_packet::chip, twihs_packet::length, TWIHS_ERROR_TIMEOUT, TWIHS_INVALID_ARGUMENT, twihs_mk_addr(), TWIHS_RECEIVE_NACK, TWIHS_SUCCESS, and TWIHS_TIMEOUT.

uint32_t twihs_master_write ( Twihs *  p_twihs,
twihs_packet_t p_packet 
)

Write multiple bytes to a TWIHS compatible slave device.

Note
This function will NOT return until all data has been written or error occurred.
Parameters
p_twihsPointer to a TWIHS instance.
p_packetPacket information and data (see twihs_packet_t).
Returns
TWIHS_SUCCESS if all bytes were written, error code otherwise.

References twihs_packet::addr, twihs_packet::addr_length, twihs_packet::buffer, twihs_packet::chip, twihs_packet::length, TWIHS_INVALID_ARGUMENT, twihs_mk_addr(), TWIHS_RECEIVE_NACK, and TWIHS_SUCCESS.

Referenced by twihs_probe().

static uint32_t twihs_mk_addr ( const uint8_t *  addr,
int  len 
)
static

Construct the TWIHS module address register field.

The TWIHS module address register is sent out MSB first. And the size controls which byte is the MSB to start with.

Please see the device datasheet for details on this.

Referenced by twihs_master_read(), and twihs_master_write().

uint32_t twihs_probe ( Twihs *  p_twihs,
uint8_t  uc_slave_addr 
)

Test if a chip answers a given I2C address.

Parameters
p_twihsPointer to a TWIHS instance.
uc_slave_addrAddress of the remote chip to search for.
Returns
TWIHS_SUCCESS if a chip was found, error code otherwise.

References twihs_packet::addr, twihs_packet::addr_length, twihs_packet::buffer, twihs_packet::chip, twihs_packet::length, and twihs_master_write().

uint8_t twihs_read_byte ( Twihs *  p_twihs)

Reads a byte from the TWIHS bus.

Parameters
p_twihsPointer to a TWIHS instance.
Returns
The byte read.
void twihs_read_write_protection_status ( Twihs *  p_twihs,
uint32_t *  p_status 
)

Read the write protection status.

Parameters
p_twihsPointer to a TWIHS instance.
p_statusPointer to save the status.
void twihs_reset ( Twihs *  p_twihs)

Reset TWIHS.

Parameters
p_twihsPointer to a TWIHS instance.

Referenced by twihs_master_init(), and twihs_slave_init().

void twihs_set_alternative_command ( Twihs *  p_twihs,
uint32_t  ul_alt_cmd 
)

Set length/direction/PEC for alternative command mode.

Parameters
p_twihsBase address of the TWIHS instance.
ul_alt_cmdAlternative command parameters.
void twihs_set_filter ( Twihs *  p_twihs,
uint32_t  ul_filter 
)

Set the filter for TWIHS.

Parameters
p_twihsBase address of the TWIHS instance.
ul_filterFilter value.
void twihs_set_slave_addr ( Twihs *  p_twihs,
uint32_t  ul_device_addr 
)

Set TWIHS slave address.

Parameters
p_twihsPointer to a TWIHS instance.
ul_device_addrDevice address of the SAM slave device on the I2C bus.
void twihs_set_sleepwalking ( Twihs *  p_twihs,
uint32_t  ul_matching_addr1,
bool  flag1,
uint32_t  ul_matching_addr2,
bool  flag2,
uint32_t  ul_matching_addr3,
bool  flag3,
uint32_t  ul_matching_data,
bool  flag 
)

Set sleepwalking match mode.

Parameters
p_twihsPointer to a TWIHS instance.
ul_matching_addr1Address 1 value.
ul_matching_addr2Address 2 value.
ul_matching_addr3Address 3 value.
ul_matching_dataData value.
flag1ture for set, false for no.
flag2ture for set, false for no.
flag3ture for set, false for no.
flagture for set, false for no.
uint32_t twihs_set_speed ( Twihs *  p_twihs,
uint32_t  ul_speed,
uint32_t  ul_mck 
)

Set the I2C bus speed in conjunction with the clock frequency.

Parameters
p_twihsPointer to a TWIHS instance.
ul_speedThe desired I2C bus speed (in Hz).
ul_mckMain clock of the device (in Hz).
Return values
PASSNew speed setting is accepted.
FAILNew speed setting is rejected.

References FAIL, I2C_FAST_MODE_SPEED, LOW_LEVEL_TIME_LIMIT, PASS, TWIHS_CLK_CALC_ARGU, TWIHS_CLK_DIV_MAX, TWIHS_CLK_DIV_MIN, and TWIHS_CLK_DIVIDER.

Referenced by twihs_master_init().

void twihs_set_write_protection ( Twihs *  p_twihs,
bool  flag 
)

Enables/Disables write protection mode.

Parameters
p_twihsPointer to a TWIHS instance.
flagture for enable, false for disable.
void twihs_slave_init ( Twihs *  p_twihs,
uint32_t  ul_device_addr 
)

Initialize TWIHS slave mode.

Parameters
p_twihsPointer to a TWIHS instance.
ul_device_addrDevice address of the SAM slave device on the I2C bus.

References twihs_enable_slave_mode(), and twihs_reset().

uint32_t twihs_slave_read ( Twihs *  p_twihs,
uint8_t *  p_data 
)

Read data from master.

Note
This function will NOT return until master sends a STOP condition.
Parameters
p_twihsPointer to a TWIHS instance.
p_dataPointer to the data buffer where data received will be stored.
Returns
Number of bytes read.
uint32_t twihs_slave_write ( Twihs *  p_twihs,
uint8_t *  p_data 
)

Write data to TWIHS bus.

Note
This function will NOT return until master sends a STOP condition.
Parameters
p_twihsPointer to a TWIHS instance.
p_dataPointer to the data buffer to be sent.
Returns
Number of bytes written.
void twihs_smbus_set_timing ( Twihs *  p_twihs,
uint32_t  ul_timing 
)

Set the prescaler, TLOW:SEXT, TLOW:MEXT and clock high max cycles for SMBUS mode.

Parameters
p_twihsBase address of the TWIHS instance.
ul_timingParameter for prescaler, TLOW:SEXT, TLOW:MEXT and clock high max cycles.
void twihs_write_byte ( Twihs *  p_twihs,
uint8_t  uc_byte 
)

Sends a byte of data to one of the TWIHS slaves on the bus.

Parameters
p_twihsPointer to a TWIHS instance.
byteThe byte to send.