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

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

Modules
	Related Project(s)
	In this section you can find all the projects related to the High-Speed Two-Wire Interface (TWIHS).

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

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_twihs	Pointer to a TWIHS instance.
ul_sources	Interrupts to be disabled.

Referenced by BOARD_TWIHS_Handler().

void twihs_disable_master_mode ( Twihs * p_twihs )

Disable TWIHS master mode.

Parameters

p_twihs Pointer to a TWIHS instance.

void twihs_disable_slave_mode ( Twihs * p_twihs )

Disable TWIHS slave mode.

Parameters

p_twihs Pointer to a TWIHS instance.

void twihs_enable_interrupt	(	Twihs *	p_twihs,
		uint32_t	ul_sources
	)

Enable TWIHS interrupts.

Parameters

p_twihs	Pointer to a TWIHS instance.
ul_sources	Interrupts to be enabled.

Referenced by BOARD_TWIHS_Handler(), and main().

void twihs_enable_master_mode ( Twihs * p_twihs )

Enable TWIHS master mode.

Parameters

p_twihs Pointer to a TWIHS instance.

Referenced by twihs_master_init().

void twihs_enable_slave_mode ( Twihs * p_twihs )

Enable TWIHS slave mode.

Parameters

p_twihs Pointer to a TWIHS instance.

Referenced by twihs_slave_init().

uint32_t twihs_get_interrupt_mask ( Twihs * p_twihs )

Read TWIHS interrupt mask.

Parameters

p_twihs Pointer to a TWIHS instance.

Returns: The interrupt mask value.

uint32_t twihs_get_interrupt_status ( Twihs * p_twihs )

Get TWIHS interrupt status.

Parameters

p_twihs Pointer to a TWIHS instance.

Return values

TWIHS interrupt status.

Referenced by BOARD_TWIHS_Handler().

Pdc* twihs_get_pdc_base ( Twihs * p_twihs )

Get TWIHS PDC base address.

Parameters

p_twihs Pointer 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_twihs	Base address of the TWIHS instance.
ul_mask	Mask value.

uint32_t twihs_master_init	(	Twihs *	p_twihs,
		const twihs_options_t *	p_opt
	)

Initialize TWIHS master mode.

Parameters

p_twihs	Pointer to a TWIHS instance.
p_opt	Options 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, status, twihs_enable_master_mode(), TWIHS_INVALID_ARGUMENT, twihs_reset(), twihs_set_speed(), and TWIHS_SUCCESS.

Referenced by at30tse_init(), bno055_i2c_bus_init(), main(), nm_bus_init(), and twihs_master_setup().

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_twihs	Pointer to a TWIHS instance.
p_packet	Packet 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, status, TWIHS_ERROR_TIMEOUT, TWIHS_INVALID_ARGUMENT, twihs_mk_addr(), TWIHS_RECEIVE_NACK, TWIHS_SUCCESS, and TWIHS_TIMEOUT.

Referenced by at24macxx_read_byte(), at24macxx_read_continuous(), at24macxx_read_page(), at30tse_eeprom_read(), at30tse_read_register(), bno055_i2c_bus_read(), main(), mxt_get_crc_value(), mxt_get_message_count(), mxt_probe_device(), mxt_read_config_object(), mxt_read_config_reg(), mxt_read_id_block(), mxt_read_message(), mxt_read_object_table(), and ov_read_reg().

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_twihs	Pointer to a TWIHS instance.
p_packet	Packet 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, status, TWIHS_INVALID_ARGUMENT, twihs_mk_addr(), TWIHS_RECEIVE_NACK, and TWIHS_SUCCESS.

Referenced by at24macxx_acknowledge_polling(), at24macxx_write_byte(), at24macxx_write_page(), at30tse_eeprom_write(), at30tse_set_register_pointer(), at30tse_write_register(), bno055_i2c_bus_write(), main(), mxt_write_config_object(), mxt_write_config_reg(), ov_write_reg(), and 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_twihs	Pointer to a TWIHS instance.
uc_slave_addr	Address 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_twihs Pointer to a TWIHS instance.

Returns: The byte read.

Referenced by BOARD_TWIHS_Handler(), and main().

void twihs_read_write_protection_status	(	Twihs *	p_twihs,
		uint32_t *	p_status
	)

Read the write protection status.

Parameters

p_twihs	Pointer to a TWIHS instance.
p_status	Pointer to save the status.

void twihs_reset ( Twihs * p_twihs )

Reset TWIHS.

Parameters

p_twihs Pointer 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_twihs	Base address of the TWIHS instance.
ul_alt_cmd	Alternative command parameters.

void twihs_set_filter	(	Twihs *	p_twihs,
		uint32_t	ul_filter
	)

Set the filter for TWIHS.

Parameters

p_twihs	Base address of the TWIHS instance.
ul_filter	Filter value.

void twihs_set_slave_addr	(	Twihs *	p_twihs,
		uint32_t	ul_device_addr
	)

Set TWIHS slave address.

Parameters

p_twihs	Pointer to a TWIHS instance.
ul_device_addr	Device address of the SAM slave device on the I2C bus.

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_twihs	Pointer to a TWIHS instance.
ul_speed	The desired I2C bus speed (in Hz).
ul_mck	Main clock of the device (in Hz).

Return values

PASS	New speed setting is accepted.
FAIL	New 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_twihs	Pointer to a TWIHS instance.
flag	ture for enable, false for disable.

void twihs_slave_init	(	Twihs *	p_twihs,
		uint32_t	ul_device_addr
	)

Initialize TWIHS slave mode.

Parameters

p_twihs	Pointer to a TWIHS instance.
ul_device_addr	Device address of the SAM slave device on the I2C bus.

References twihs_enable_slave_mode(), and twihs_reset().

Referenced by main(), and twihs_slave_setup().

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_twihs	Pointer to a TWIHS instance.
p_data	Pointer to the data buffer where data received will be stored.

Returns: Number of bytes read.

References status.

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_twihs	Pointer to a TWIHS instance.
p_data	Pointer to the data buffer to be sent.

Returns: Number of bytes written.

References status.

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_twihs	Base address of the TWIHS instance.
ul_timing	Parameter 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_twihs	Pointer to a TWIHS instance.
byte	The byte to send.

Referenced by BOARD_TWIHS_Handler().

Microchip® Advanced Software Framework

Modules

Macros

Functions