Driver for the TWIM (Two-Wire Master Interface).

This driver provides access to the main features of the TWIM controller. The TWIM interconnects components on a unique two-wire bus. The TWIM is programmable as a master with sequential or single-byte access. Multiple master capability is supported.

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

	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the TWIM - Two-Wire Master Interface.

Data Structures
struct	twim_config
	Input parameters when initializing the TWIM module mode. More...

struct	twim_package
	Information concerning the data transmission. More...

Macros
#define	TWIM_IER_NAK_MASK (TWIM_IER_ANAK \| TWIM_IER_DNAK)
	Interrupt Enable Register Mask for No Acknowledgements. More...

#define	TWIM_IER_STD_MASK (TWIM_IER_ANAK \| TWIM_IER_ARBLST)
	Frequently used Interrupt Enable Register Mask. More...

#define	TWIM_LOW_POWER_ENABLE 1
	Enable TWIM Low Power Transfer in default. More...

#define	TWIM_SCR_NAK_MASK (TWIM_SCR_ANAK \| TWIM_SCR_DNAK)
	Status Clear Register Mask for No Acknowledgements. More...

#define	TWIM_SR_NAK_MASK (TWIM_SR_ANAK \| TWIM_SR_DNAK)
	Status Register Mask for No Acknowledgements. More...

#define	TWIM_SR_STD_MASK (TWIM_SR_ANAK \| TWIM_SR_ARBLST)
	Frequently used Status Clear Register Mask. More...

Typedefs
typedef void(*	twim_callback_t )(Twim *)

Functions
status_code_t	twi_master_read (Twim twim, struct twim_package package)
	Read multiple bytes from a TWI compatible slave device. More...

status_code_t	twi_master_write (Twim twim, struct twim_package package)
	Write multiple bytes to a TWI compatible slave device. More...

void	twim_clear_status (Twim *twim, uint32_t clear_status)
	Clear the current status of the TWIM. More...

void	twim_default_callback (Twim *twim)
	TWIM default callback function. More...

static void	twim_disable (Twim *twim)
	Disable Master Mode of the TWI. More...

void	twim_disable_interrupt (Twim *twim, uint32_t interrupt_source)
	Disable the TWIM interrupts and clear their status. More...

static void	twim_enable (Twim *twim)
	Enable Master Mode of the TWI. More...

void	twim_enable_interrupt (Twim *twim, uint32_t interrupt_source)
	Enable the TWIM interrupts. More...

uint32_t	twim_get_interrupt_mask (Twim *twim)
	Get the TWIM interrupt mask. More...

uint32_t	twim_get_status (Twim *twim)
	Information about the current status of the TWIM. More...

void	twim_pdca_transfer_prepare (Twim twim, twi_package_t package, bool read)
	Set TWIM for PDCA transfer. More...

status_code_t	twim_probe (Twim *twim, uint32_t chip_addr)
	Test if a chip answers for a given TWI address. More...

void	twim_set_callback (Twim *twim, uint32_t interrupt_source, twim_callback_t callback, uint8_t irq_level)
	Set callback for TWIM. More...

status_code_t	twim_set_config (Twim twim, struct twim_config config)
	Initialize the TWIM module. More...

status_code_t	twim_set_hsmode_speed (Twim *twim, uint32_t speed, uint32_t clk, uint8_t cycles)
	Set the TWI bus speed in conjunction with the clock frequency in high speed mode. More...

status_code_t	twim_set_speed (Twim *twim, uint32_t speed, uint32_t clk, uint8_t cycles)
	Set the TWI bus speed in conjunction with the clock frequency. More...

TWI transfer speed definitions
#define	TWI_STD_MODE_SPEED ( 100000 /* kbit/s */)
	TWI Standard Mode. More...

#define	TWI_FAST_MODE_SPEED ( 400000 /* kbit/s */)
	TWI Fast Mode. More...

#define	TWI_FAST_MODE_PLUS_SPEED (1000000 /* kbit/s */)
	TWI Fast Mode Plus. More...

#define	TWI_HIGH_SPEED_MODE_SPEED (3400000 /* kbit/s */)
	TWI High Speed Mode. More...

enum	twim_transfer_status { TWI_SUCCESS = 0, TWI_INVALID_ARGUMENT = -1, TWI_ARBITRATION_LOST = -2, TWI_NO_CHIP_FOUND = -3, TWI_RECEIVE_NACK = -4, TWI_SEND_NACK = -5, TWI_INVALID_CLOCK_DIV = -6 }
	Status Codes for TWI Transfer. More...

typedef enum twim_transfer_status	twim_transfer_status_t

TWI Driver Compatibility
Codes for SAM devices using TWI modules can easily be ported to SAM devices with TWIM module
#define	twi_options_t struct twim_config

#define	twi_package_t struct twim_package

#define	twi_master_init twim_set_config

#define	twi_probe twim_probe

#define TWI_FAST_MODE_PLUS_SPEED (1000000 /* kbit/s */)

TWI Fast Mode Plus.

Referenced by twim_set_config().

#define TWI_FAST_MODE_SPEED ( 400000 /* kbit/s */)

TWI Fast Mode.

#define TWI_HIGH_SPEED_MODE_SPEED (3400000 /* kbit/s */)

TWI High Speed Mode.

#define twi_master_init twim_set_config

Referenced by twi_master_setup().

#define twi_options_t struct twim_config

#define twi_package_t struct twim_package

Referenced by main(), qt_read_regs(), and qt_write_regs().

#define twi_probe twim_probe

#define TWI_STD_MODE_SPEED ( 100000 /* kbit/s */)

TWI Standard Mode.

#define TWIM_IER_NAK_MASK (TWIM_IER_ANAK | TWIM_IER_DNAK)

Interrupt Enable Register Mask for No Acknowledgements.

#define TWIM_IER_STD_MASK (TWIM_IER_ANAK | TWIM_IER_ARBLST)

Frequently used Interrupt Enable Register Mask.

Referenced by twi_master_read(), and twi_master_write().

#define TWIM_LOW_POWER_ENABLE 1

Enable TWIM Low Power Transfer in default.

#define TWIM_SCR_NAK_MASK (TWIM_SCR_ANAK | TWIM_SCR_DNAK)

Status Clear Register Mask for No Acknowledgements.

#define TWIM_SR_NAK_MASK (TWIM_SR_ANAK | TWIM_SR_DNAK)

Status Register Mask for No Acknowledgements.

#define TWIM_SR_STD_MASK (TWIM_SR_ANAK | TWIM_SR_ARBLST)

Frequently used Status Clear Register Mask.

Referenced by twim_default_callback().

typedef void(* twim_callback_t)(Twim *)

typedef enum twim_transfer_status twim_transfer_status_t

enum twim_transfer_status

Status Codes for TWI Transfer.

Enumerator
TWI_SUCCESS
TWI_INVALID_ARGUMENT	TWI Transaction Success.
TWI_ARBITRATION_LOST	Invalid Argument Passed.
TWI_NO_CHIP_FOUND	Bus Arbitration Lost.
TWI_RECEIVE_NACK	Slave Not Found.
TWI_SEND_NACK	Data No Acknowledgement Received.
TWI_INVALID_CLOCK_DIV	Data No Acknowledgement Send.

status_code_t twi_master_read	(	Twim *	twim,
		struct twim_package *	package
	)

Read multiple bytes from a TWI compatible slave device.

Parameters

twim	Base address of the TWIM
package	Package information and data

Return values

STATUS_OK	If all bytes were read successfully
ERR_IO_ERROR	NACK received or Bus Arbitration lost

References twim_package::addr, twim_package::addr_length, twim_package::buffer, twim_package::chip, ERR_IO_ERROR, find_twim_channel_num(), twim_package::high_speed, twim_package::high_speed_code, twim_package::length, p_twim_next_rx_data, p_twim_rx_data, p_twim_tx_data, sleepmgr_enter_sleep(), sleepmgr_lock_mode(), SLEEPMGR_SLEEP_1, sleepmgr_unlock_mode(), STATUS_OK, twim_package::ten_bit, transfer_status, TWI_ARBITRATION_LOST, TWI_RECEIVE_NACK, TWI_SUCCESS, twim_get_status(), TWIM_IER_STD_MASK, twim_it_mask, TWIM_MAX_NBYTES_PER_XFER, twim_next_cmd_xfer_valid, twim_next_rx_nb_bytes, twim_next_tx_nb_bytes, twim_rx_nb_bytes, and twim_tx_nb_bytes.

Referenced by main(), qt_read_regs(), read_test(), and twim_probe().

status_code_t twi_master_write	(	Twim *	twim,
		struct twim_package *	package
	)

Write multiple bytes to a TWI compatible slave device.

Parameters

twim	Base address of the TWIM
*package	Package information and data

Return values

STATUS_OK	If all bytes were send successfully
ERR_IO_ERROR	NACK received or Bus Arbitration lost

References twim_package::addr, twim_package::addr_length, twim_package::buffer, twim_package::chip, ERR_IO_ERROR, find_twim_channel_num(), twim_package::high_speed, twim_package::high_speed_code, twim_package::length, p_twim_next_tx_data, p_twim_tx_data, sleepmgr_enter_sleep(), sleepmgr_lock_mode(), SLEEPMGR_SLEEP_1, sleepmgr_unlock_mode(), STATUS_OK, twim_package::ten_bit, transfer_status, TWI_ARBITRATION_LOST, TWI_RECEIVE_NACK, TWI_SUCCESS, twim_get_status(), TWIM_IER_STD_MASK, twim_it_mask, TWIM_MAX_NBYTES_PER_XFER, twim_next_cmd_xfer_valid, twim_next_rx_nb_bytes, twim_next_tx_nb_bytes, and twim_tx_nb_bytes.

Referenced by main(), qt_read_regs(), qt_write_regs(), read_test_pdca(), and write_test().

void twim_clear_status	(	Twim *	twim,
		uint32_t	clear_status
	)

Clear the current status of the TWIM.

Parameters

twim	Base address of the TWIM
clear_status	The TWIM status to be clear

void twim_default_callback ( Twim * twim )

TWIM default callback function.

References find_twim_channel_num(), NCMDR_FREE_WAIT, p_twim_next_rx_data, p_twim_next_tx_data, p_twim_rx_data, p_twim_tx_data, status, transfer_status, TWI_ARBITRATION_LOST, TWI_RECEIVE_NACK, twim_it_mask, TWIM_MAX_NBYTES_PER_XFER, twim_next_cmd_xfer_valid, twim_next_rx_nb_bytes, twim_next_tx_nb_bytes, twim_rx_nb_bytes, TWIM_SR_STD_MASK, and twim_tx_nb_bytes.

Referenced by init_test(), and twi_master_setup().

static void twim_disable ( Twim * twim )

inlinestatic

Disable Master Mode of the TWI.

Parameters

twim	Base address of the TWIM instance.

void twim_disable_interrupt	(	Twim *	twim,
		uint32_t	interrupt_source
	)

Disable the TWIM interrupts and clear their status.

Parameters

twim	Base address of the TWIM.
interrupt_source	The TWI interrupt to be disabled

static void twim_enable ( Twim * twim )

inlinestatic

Enable Master Mode of the TWI.

Parameters

twim	Base address of the TWIM instance.

void twim_enable_interrupt	(	Twim *	twim,
		uint32_t	interrupt_source
	)

Enable the TWIM interrupts.

Parameters

twim	Base address of the TWIM
interrupt_source	The TWI interrupt to be enabled

Referenced by twim_set_callback().

uint32_t twim_get_interrupt_mask ( Twim * twim )

Get the TWIM interrupt mask.

Parameters

twim	Base address of the TWIM

Return values

TWIM	interrupt mask

uint32_t twim_get_status ( Twim * twim )

Information about the current status of the TWIM.

Parameters

twim	Base address of the TWIM

Referenced by twi_master_read(), and twi_master_write().

void twim_pdca_transfer_prepare	(	Twim *	twim,
		twi_package_t *	package,
		bool	read
	)

Set TWIM for PDCA transfer.

Parameters

twim	Base address of the TWIM
package	Package information and data (see twim_package_t)
read	True if it's a read trasnfer

Referenced by read_test_pdca(), and write_test_pdca().

status_code_t twim_probe	(	Twim *	twim,
		uint32_t	chip_addr
	)

Test if a chip answers for a given TWI address.

Parameters

twim	Base address of the TWIM
chip_addr	Address of the chip which is searched for

Return values

STATUS_OK	Slave Found
ERR_IO_ERROR	ANAK received or Bus Arbitration lost

References twim_package::addr_length, twim_package::buffer, twim_package::chip, data, twim_package::length, and twi_master_read().

void twim_set_callback	(	Twim *	twim,
		uint32_t	interrupt_source,
		twim_callback_t	callback,
		uint8_t	irq_level
	)

Set callback for TWIM.

Parameters

twim	Base address of the TWIM
interrupt_source	TWIM interrupt source
callback	Callback function pointer
irq_level	Interrupt level

References callback, find_twim_channel_num(), twim_callback_pointer, and twim_enable_interrupt().

Referenced by init_test(), and twi_master_setup().

status_code_t twim_set_config	(	Twim *	twim,
		struct twim_config *	config
	)

Initialize the TWIM module.

Parameters

twim	Base address of the TWIM
config	Options for initializing the TWIM module

Return values

STATUS_OK	Transaction is successful
ERR_INVALID_ARG	Invalid arg resulting in wrong CWGR Exponential

References twim_config::clock_drive_strength_low, twim_config::clock_slew_limit, twim_config::data_drive_strength_low, twim_config::data_setup_cycles, twim_config::data_slew_limit, ERR_INVALID_ARG, twim_config::hs_clock_drive_strength_high, twim_config::hs_clock_drive_strength_low, twim_config::hs_clock_slew_limit, twim_config::hs_data_drive_strength_low, twim_config::hs_data_slew_limit, twim_config::hsmode_data_setup_cycles, twim_config::hsmode_speed, sleepmgr_init(), twim_config::smbus, twim_config::speed, STATUS_OK, sysclk_enable_peripheral_clock(), TWI_FAST_MODE_PLUS_SPEED, twim_config::twim_clk, twim_set_hsmode_speed(), and twim_set_speed().

Referenced by init_test().

status_code_t twim_set_hsmode_speed	(	Twim *	twim,
		uint32_t	speed,
		uint32_t	clk,
		uint8_t	cycles
	)

Set the TWI bus speed in conjunction with the clock frequency in high speed mode.

Parameters

twim	Base address of the TWIM
speed	The desired twim bus speed
clk	The current running system clock frequency
cycles	Clock cycles for data setup count

Return values

STATUS_OK	Transaction is successful
ERR_INVALID_ARG	Invalid arg resulting in wrong CWGR Exponential

References ERR_INVALID_ARG, and STATUS_OK.

Referenced by twim_set_config().

status_code_t twim_set_speed	(	Twim *	twim,
		uint32_t	speed,
		uint32_t	clk,
		uint8_t	cycles
	)

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

Parameters

twim	Base address of the TWIM
speed	The desired twim bus speed
clk	The current running system clock frequency
cycles	Clock cycles for data setup count

Return values

STATUS_OK	Transaction is successful
ERR_INVALID_ARG	Invalid arg resulting in wrong CWGR Exponential

References ERR_INVALID_ARG, and STATUS_OK.

Referenced by twim_set_config().

Microchip® Advanced Software Framework

Modules

Data Structures

Macros

Typedefs

Functions

TWI transfer speed definitions

TWI Driver Compatibility