TWIHS Interface

Driver API for TWIHS (plib_twihs0.h) More...

Typedefs
typedef void(*	TWIHS_CALLBACK_HANDLER) (void)
	Function pointer type for TWI event callback handler.

Enumerations
enum	TWIHS_HOST_HWREG_STATUS {   TWIHS_HOST_HWREG_OK = 0 , TWIHS_HOST_HWREG_ERROR , TWIHS_HOST_HWREG_INVALID_PARAM , TWIHS_HOST_HWREG_TIMEOUT ,   TWIHS_HOST_HWREG_BUSY , TWIHS_HOST_HWREG_UNSUPPORTED }
	Status codes for TWIHS hardware register operations. More...
enum	TWIHS_HOST_INTERNAL_ADDRESS_SIZE { TWIHS_HOST_NO_INTERNAL_ADDRESS = 0 , TWIHS_HOST_ONE_BYTE_INTERNAL_ADDRESS = 1 , TWIHS_HOST_TWO_BYTE_INTERNAL_ADDRESS = 2 , TWIHS_HOST_THREE_BYTE_INTERNAL_ADDRESS = 3 }
	TWIHS internal device address size selection. More...
enum	TWIHS_CLIENT_ACK_STATUS { TWIHS_CLIENT_ACK_STATUS_RECEIVED_ACK = 0 , TWIHS_CLIENT_ACK_STATUS_RECEIVED_NACK = 1 }
	In TWIHS mode ACK/NACK status received from master. More...
enum	TWIHS_TRANSFER_DIR { TWIHS_TRANSFER_DIR_WRITE = 0 , TWIHS_TRANSFER_DIR_READ = 1 }
	TWIHS transfer direction selection. Common for Host and Client. More...
enum	TWIHS_INTERRUPT_ENABLE {   TWIHS_INTERRUPT_TX_COMPLETION_EN = TWIHS_IER_TXCOMP_Msk , TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_EN = TWIHS_IER_RXRDY_Msk , TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_EN = TWIHS_IER_TXRDY_Msk , TWIHS_INTERRUPT_CLIENT_ACCESS_EN = TWIHS_IER_SVACC_Msk ,   TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_EN = TWIHS_IER_GACC_Msk , TWIHS_INTERRUPT_SCL_WAIT_STATE_EN = TWIHS_IER_SCL_WS_Msk , TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_EN = TWIHS_IER_EOSACC_Msk , TWIHS_INTERRUPT_HOST_CODE_ACK_EN = TWIHS_IER_MCACK_Msk ,   TWIHS_INTERRUPT_NACK_EN = TWIHS_IER_NACK_Msk , TWIHS_INTERRUPT_ARBITERATION_LOST_EN = TWIHS_IER_ARBLST_Msk , TWIHS_INTERRUPT_OVERRUN_ERROR_EN = TWIHS_IER_OVRE_Msk , TWIHS_INTERRUPT_UNDERRUN_ERROR_EN = TWIHS_IER_UNRE_Msk ,   TWIHS_INTERRUPT_TIMEOUT_ERROR_EN = TWIHS_IER_TOUT_Msk , TWIHS_INTERRUPT_PEC_ERROR_EN = TWIHS_IER_PECERR_Msk }
	TWIHS interrupt enable selection. Common for Host and Client. More...
enum	TWIHS_INTERRUPT_DISABLE {   TWIHS_INTERRUPT_TX_COMPLETION_DIS = TWIHS_IDR_TXCOMP_Msk , TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_DIS = TWIHS_IDR_RXRDY_Msk , TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_DIS = TWIHS_IDR_TXRDY_Msk , TWIHS_INTERRUPT_CLIENT_ACCESS_DIS = TWIHS_IDR_SVACC_Msk ,   TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_DIS = TWIHS_IDR_GACC_Msk , TWIHS_INTERRUPT_SCL_WAIT_STATE_DIS = TWIHS_IDR_SCL_WS_Msk , TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_DIS = TWIHS_IDR_EOSACC_Msk , TWIHS_INTERRUPT_HOST_CODE_ACK_DIS = TWIHS_IDR_MCACK_Msk ,   TWIHS_INTERRUPT_NACK_DIS = TWIHS_IDR_NACK_Msk , TWIHS_INTERRUPT_ARBITERATION_LOST_DIS = TWIHS_IDR_ARBLST_Msk , TWIHS_INTERRUPT_OVERRUN_ERROR_DIS = TWIHS_IDR_OVRE_Msk , TWIHS_INTERRUPT_UNDERRUN_ERROR_DIS = TWIHS_IDR_UNRE_Msk ,   TWIHS_INTERRUPT_TIMEOUT_ERROR_DIS = TWIHS_IDR_TOUT_Msk , TWIHS_INTERRUPT_PEC_ERROR_DIS = TWIHS_IDR_PECERR_Msk }
	TWIHS interrupt disable selection. Common for Host and Client. More...
enum	TWIHS_STATUS_EVENTS {   TWIHS_EVENT_TX_COMPLETION = TWIHS_SR_TXCOMP_Msk , TWIHS_EVENT_RX_HOLDING_REGISTER_READY = TWIHS_SR_RXRDY_Msk , TWIHS_EVENT_TX_HOLDING_REGISTER_READY = TWIHS_SR_TXRDY_Msk , TWIHS_EVENT_CLIENT_ACCESS = TWIHS_SR_SVACC_Msk ,   TWIHS_EVENT_GENERAL_CALL_ACCESS = TWIHS_SR_GACC_Msk , TWIHS_EVENT_SCL_WAIT_STATE = TWIHS_SR_SCLWS_Msk , TWIHS_EVENT_END_OF_CLIENT_ACCESS = TWIHS_SR_EOSACC_Msk , TWIHS_EVENT_HOST_CODE_ACK = TWIHS_SR_MCACK_Msk ,   TWIHS_EVENT_NACK = TWIHS_SR_NACK_Msk , TWIHS_EVENT_ARBITERATION_LOST = TWIHS_SR_ARBLST_Msk , TWIHS_EVENT_OVERRUN_ERROR = TWIHS_SR_OVRE_Msk , TWIHS_EVENT_UNDERRUN_ERROR = TWIHS_SR_UNRE_Msk ,   TWIHS_EVENT_TIMEOUT_ERROR = TWIHS_SR_TOUT_Msk , TWIHS_EVENT_READ_ACCESS_BY_HOST = TWIHS_SR_SVREAD_Msk , TWIHS_EVENT_SCL_LINE_VALUE = TWIHS_SR_SCL_Msk , TWIHS_EVENT_SDA_LINE_VALUE = TWIHS_SR_SDA_Msk }
	TWIHS hardware events. Common for Host and Client,. More...

Functions
void	TWIHS0_Host_Enable (void)
	Enables the TWIHS Host mode operation.
void	TWIHS0_Host_Disable (void)
	Disables the TWIHS Host mode operation.
void	TWIHS0_Host_SendStop (void)
	Sends the I2C STOP condition on the bus by writing into the STOP bit in TWIHS_CR register.
void	TWIHS0_Host_SendStart (void)
	Sends the I2C START condition on the bus by writing into the START bit in TWIHS_CR register. A frame beginning with a START bit is transmitted according to the features defined in the TWIHS Host Mode Register (TWIHS_MMR).
void	TWIHS0_Host_SendStartAndStop (void)
	Sets both the I2C START and STOP condition START and the STOP bits in TWIHS_CR register.
void	TWIHS0_Host_SetTransferDirection (TWIHS_TRANSFER_DIR transfer_direction)
	Sets the TWIHS host transfer direction.
void	TWIHS0_Host_SendAddress (uint32_t address)
	Sets the target client address by writing the DADR bits in TWIHS_MMR register.
void	TWIHS0_Host_SetInternalAddressSize (TWIHS_HOST_INTERNAL_ADDRESS_SIZE internal_address_size)
	Configures the internal address size for the transfer based on the the size of the client address. Set to 1, 2 or 3 when client address exceeds 7 bits. Set to 0 when client address is within 7 bits.
TWIHS_HOST_HWREG_STATUS	TWIHS0_SetBaudRate (uint32_t srcClkFreq, uint32_t i2cClkSpeed)
	Sets the TWIHS clock speed by writing CKDIV, CHDIV and CLDIV bits in the TWIHS_CWGR register.
void	TWIHS0_Client_Enable (void)
	Enables the TWIHS Client mode operation.
void	TWIHS0_Client_Disable (void)
	Disables the TWIHS Client mode operation.
void	TWIHS0_Client_Set7bitAddress (uint8_t addr)
	Sets the 7-bit client address by writing into SADR bits in the TWIHS_SMR register. The Client device address is used in Client mode in order to be accessed by Host devices in Read orWrite mode.
void	TWIHS0_Client_Set7bitAddressMask (uint8_t addr_mask)
	Sets the 7-bit client address mask by writing into MASK bits in the TWIHS_SMR register. A mask can be applied on the Client device address in Client mode in order to allow multiple address answer. For each bit of the MASK field set to 1, the corresponding SADR bit is masked. If the MASK field value is 0, no mask is applied to the SADR field.
TWIHS_TRANSFER_DIR	TWIHS0_Client_TransferDirGet (void)
	Returns the current client transfer direction. This bit is used in Client mode only. When SVACC is low (no Client access has been detected) SVREAD is irrelevant.
void	TWIHS0_Client_NACKDataPhase (bool isNACKEnable)
	Sets the NACK value to be returned in the ACK cycle of the data phase by setting the NACKEN bit in TWIHS_SMR register. NACKEN bit can only be set during the client mode operation.
TWIHS_CLIENT_ACK_STATUS	TWIHS0_LastByteAckStatusGet (void)
	Returns the acknowledge status of the last received byte.
void	TWIHS0_ResetSoftware (void)
	Perform a software reset of the TWIHS module.
void	TWIHS0_ClearTransmitHoldRegister (void)
	Clears the Transmit Holding Register and sets TXRDY, TXCOMP flags. This api is called before enabling the TWIHS peripheral either in host or client mode.
void	TWIHS0_EnableInterrupts (TWIHS_INTERRUPT_ENABLE interrupts)
	Enable a specific TWIHS interrupt source.
void	TWIHS0_DisableInterrupts (TWIHS_INTERRUPT_DISABLE interrupts)
	Disable a specific TWI interrupt source.
void	TWIHS0_SendData (uint8_t data)
	Send a single data word via TWI. Writes data to the TWIHS_THR (Transmit Holding register) to initiate a data transfer.
uint8_t	TWIHS0_ReceiveData (void)
	Receive a single data word via SPI. Reads data from the TWIHS_RHR (Receive Holding register) that was received from the TWI bus.
uint32_t	TWIHS0_GetBusStatus (void)
	Returns the current TWIHS bus status.
void	TWIHS0_SetCallbackHandler (TWIHS_CALLBACK_HANDLER callback)
	Register an interrupt callback handler.
uint32_t	TWIHS0_GetInterruptMask (void)
	Returns the current interrupt mask register value.

Description

Driver API for TWIHS (plib_twihs0.h)

Typedef Documentation

TWIHS_CALLBACK_HANDLER

TWIHS_CALLBACK_HANDLER

Function pointer type for TWI event callback handler.

Enumeration Type Documentation

TWIHS_CLIENT_ACK_STATUS

enum TWIHS_CLIENT_ACK_STATUS

In TWIHS mode ACK/NACK status received from master.

Enumerator
TWIHS_CLIENT_ACK_STATUS_RECEIVED_ACK
TWIHS_CLIENT_ACK_STATUS_RECEIVED_NACK

TWIHS_HOST_HWREG_STATUS

enum TWIHS_HOST_HWREG_STATUS

Status codes for TWIHS hardware register operations.

Enumerator
TWIHS_HOST_HWREG_OK	Operation completed successfully.
TWIHS_HOST_HWREG_ERROR	Generic hardware error.
TWIHS_HOST_HWREG_INVALID_PARAM	Invalid parameter passed.
TWIHS_HOST_HWREG_TIMEOUT	Operation timed out.
TWIHS_HOST_HWREG_BUSY	Hardware is busy.
TWIHS_HOST_HWREG_UNSUPPORTED	Operation not supported.

TWIHS_HOST_INTERNAL_ADDRESS_SIZE

enum TWIHS_HOST_INTERNAL_ADDRESS_SIZE

TWIHS internal device address size selection.

Enumerator
TWIHS_HOST_NO_INTERNAL_ADDRESS	No internal device address.
TWIHS_HOST_ONE_BYTE_INTERNAL_ADDRESS	Internal device address is 1 byte.
TWIHS_HOST_TWO_BYTE_INTERNAL_ADDRESS	Internal device address is 2 bytes.
TWIHS_HOST_THREE_BYTE_INTERNAL_ADDRESS	Internal device address is 3 bytes.

TWIHS_INTERRUPT_DISABLE

enum TWIHS_INTERRUPT_DISABLE

TWIHS interrupt disable selection. Common for Host and Client.

Enumerator
TWIHS_INTERRUPT_TX_COMPLETION_DIS	Transmission completed interrupt disable.
TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_DIS	Receive holding register ready interrupt disable.
TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_DIS	Transmit holding register ready interrupt disable.
TWIHS_INTERRUPT_CLIENT_ACCESS_DIS	Client access interrupt disable.
TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_DIS	General call access interrupt disable.
TWIHS_INTERRUPT_SCL_WAIT_STATE_DIS	SCL wait state interrupt disable.
TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_DIS	End of client access interrupt disable.
TWIHS_INTERRUPT_HOST_CODE_ACK_DIS	Host code acknowledge interrupt disable.
TWIHS_INTERRUPT_NACK_DIS	NACK detected interrupt disable.
TWIHS_INTERRUPT_ARBITERATION_LOST_DIS	Arbitration lost interrupt disable.
TWIHS_INTERRUPT_OVERRUN_ERROR_DIS	Overrun error interrupt disable.
TWIHS_INTERRUPT_UNDERRUN_ERROR_DIS	Underrun error interrupt disable.
TWIHS_INTERRUPT_TIMEOUT_ERROR_DIS	Timeout error interrupt disable.
TWIHS_INTERRUPT_PEC_ERROR_DIS	PEC error interrupt disable.

TWIHS_INTERRUPT_ENABLE

enum TWIHS_INTERRUPT_ENABLE

TWIHS interrupt enable selection. Common for Host and Client.

Enumerator
TWIHS_INTERRUPT_TX_COMPLETION_EN	Transmission completed interrupt enable.
TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_EN	Receive holding register ready interrupt enable.
TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_EN	Transmit holding register ready interrupt enable.
TWIHS_INTERRUPT_CLIENT_ACCESS_EN	Client access interrupt enable.
TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_EN	General call access interrupt enable.
TWIHS_INTERRUPT_SCL_WAIT_STATE_EN	SCL wait state interrupt enable.
TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_EN	End of client access interrupt enable.
TWIHS_INTERRUPT_HOST_CODE_ACK_EN	Host code acknowledge interrupt enable.
TWIHS_INTERRUPT_NACK_EN	NACK detected interrupt enable.
TWIHS_INTERRUPT_ARBITERATION_LOST_EN	Arbitration lost interrupt enable.
TWIHS_INTERRUPT_OVERRUN_ERROR_EN	Overrun error interrupt enable.
TWIHS_INTERRUPT_UNDERRUN_ERROR_EN	Underrun error interrupt enable.
TWIHS_INTERRUPT_TIMEOUT_ERROR_EN	Timeout error interrupt enable.
TWIHS_INTERRUPT_PEC_ERROR_EN	PEC error interrupt enable.

TWIHS_STATUS_EVENTS

enum TWIHS_STATUS_EVENTS

TWIHS hardware events. Common for Host and Client,.

Enumerator
TWIHS_EVENT_TX_COMPLETION	Transmission completed.
TWIHS_EVENT_RX_HOLDING_REGISTER_READY	A byte has been received
TWIHS_EVENT_TX_HOLDING_REGISTER_READY	data has been transmitted and acknowledged.
TWIHS_EVENT_CLIENT_ACCESS	address decoding sequence has matched.
TWIHS_EVENT_GENERAL_CALL_ACCESS	general call has been detected.
TWIHS_EVENT_SCL_WAIT_STATE	The clock is stretched.
TWIHS_EVENT_END_OF_CLIENT_ACCESS	The Client Access is finished.
TWIHS_EVENT_HOST_CODE_ACK	A Host Code has been received since the last read of TWIHS_SR.
TWIHS_EVENT_NACK	A data or address byte has not been acknowledged by the Client.
TWIHS_EVENT_ARBITERATION_LOST	Arbitration lost.
TWIHS_EVENT_OVERRUN_ERROR	Overrun error event.
TWIHS_EVENT_UNDERRUN_ERROR	Underrun error event.
TWIHS_EVENT_TIMEOUT_ERROR	Timeout error event.
TWIHS_EVENT_READ_ACCESS_BY_HOST	read access is performed by a Host.
TWIHS_EVENT_SCL_LINE_VALUE	SCL line sampled value is 1 when set.
TWIHS_EVENT_SDA_LINE_VALUE	SDA line sampled value is 1 when set.

TWIHS_TRANSFER_DIR

enum TWIHS_TRANSFER_DIR

TWIHS transfer direction selection. Common for Host and Client.

Enumerator
TWIHS_TRANSFER_DIR_WRITE	TWIHS host writes data to client.
TWIHS_TRANSFER_DIR_READ	TWIHS host reads data from client.

Function Documentation

TWIHS0_ClearTransmitHoldRegister()

void TWIHS0_ClearTransmitHoldRegister

(

void

)

Clears the Transmit Holding Register and sets TXRDY, TXCOMP flags. This api is called before enabling the TWIHS peripheral either in host or client mode.

Parameters

None.

Returns

None.

TWIHS0_Client_Disable()

void TWIHS0_Client_Disable

(

void

)

Disables the TWIHS Client mode operation.

Disables the TWIHS0 peripheral Client functionality by setting the SVDIS bit in the TWIHS_CR register. The function ensures that ongoing transfers are completed before shutdown.

Note

This api should be called before enabling the TWIHS0 in Host mode.

Unlike TWIHS0_ResetSoftware, this does not reset configuration registers.

Parameters

None.

Returns

None.

TWIHS0_Client_Enable()

void TWIHS0_Client_Enable

(

void

)

Enables the TWIHS Client mode operation.

Enables the TWIHS0 peripheral Client functionality by setting the SVEN bit in the TWIHS_CR register. The peripheral clock must be enabled via PMC before calling this function.

Note

Host mode should be disabled by setting MSDIS bit from TWIHS_CR register before calling this api.

Client address should be set in TWIHS_SMR register before calling this api.

Parameters

None.

Returns

None.

TWIHS0_Client_NACKDataPhase()

void TWIHS0_Client_NACKDataPhase

(

bool

isNACKEnable

)

Sets the NACK value to be returned in the ACK cycle of the data phase by setting the NACKEN bit in TWIHS_SMR register. NACKEN bit can only be set during the client mode operation.

Parameters

isNACKEnable

- Enable or disable NACK generation.

Returns

None.

TWIHS0_Client_Set7bitAddress()

void TWIHS0_Client_Set7bitAddress

(

uint8_t

addr

)

Sets the 7-bit client address by writing into SADR bits in the TWIHS_SMR register. The Client device address is used in Client mode in order to be accessed by Host devices in Read orWrite mode.

Note

SADR must be programmed before enabling the Client mode or after a general call. Writes at other times have no effect.

Parameters

addr	- 7-bit client address.

Returns

None.

TWIHS0_Client_Set7bitAddressMask()

void TWIHS0_Client_Set7bitAddressMask

(

uint8_t

addr_mask

)

Sets the 7-bit client address mask by writing into MASK bits in the TWIHS_SMR register. A mask can be applied on the Client device address in Client mode in order to allow multiple address answer. For each bit of the MASK field set to 1, the corresponding SADR bit is masked. If the MASK field value is 0, no mask is applied to the SADR field.

Parameters

addr	- 7-bit client address mask.

Returns

None.

TWIHS0_Client_TransferDirGet()

TWIHS_TRANSFER_DIR TWIHS0_Client_TransferDirGet

(

void

)

Returns the current client transfer direction. This bit is used in Client mode only. When SVACC is low (no Client access has been detected) SVREAD is irrelevant.

Parameters

None.

Returns

Indicates that a read/write access is performed by a Host.

TWIHS0_DisableInterrupts()

void TWIHS0_DisableInterrupts

(

TWIHS_INTERRUPT_DISABLE

interrupts

)

Disable a specific TWI interrupt source.

Disables the specified interrupt(s) by setting the corresponding bits in TWIHS_IDR (Interrupt Disable Register). When disabled, TWI interrupts of those types will not trigger the ISR or invoke the callback, but the interrupt flag(s) may still be set in TWIHS_SR and can be polled.

Available interrupt sources (TWIHS_INTERRUPT_ENABLE):

• TWIHS_INTERRUPT_TX_COMPLETION_DIS : Transmission completed interrupt disable.
• TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_DIS : Receive holding register ready interrupt disable.
• TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_DIS : Transmit holding register ready interrupt disable.
• TWIHS_INTERRUPT_CLIENT_ACCESS_DIS : Client access interrupt disable.
• TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_DIS : General call access interrupt disable.
• TWIHS_INTERRUPT_SCL_WAIT_STATE_DIS : SCL wait state interrupt disable.
• TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_DIS : End of client access interrupt disable.
• TWIHS_INTERRUPT_HOST_CODE_ACK_DIS : Host code acknowledge interrupt disable.
• TWIHS_INTERRUPT_NACK_DIS : NACK detected interrupt disable.
• TWIHS_INTERRUPT_ARBITERATION_LOST_DIS : Arbitration lost interrupt disable.
• TWIHS_INTERRUPT_OVERRUN_ERROR_DIS : Overrun error interrupt disable.
• TWIHS_INTERRUPT_UNDERRUN_ERROR_DIS : Underrun error interrupt disable.
• TWIHS_INTERRUPT_TIMEOUT_ERROR_DIS : Timeout error interrupt disable.
• TWIHS_INTERRUPT_PEC_ERROR_DIS : PEC error interrupt disable.

Parameters

interrupts

- One or more interrupt source(s) (OR'd together) to disable. Example: DisableInterrupt(TWIHS_INTERRUPT_NACK_DIS | TWIHS_INTERRUPT_ARBITERATION_LOST_DIS)

Note

Multiple interrupt sources can be disabled simultaneously.

Disabling does not affect the TWI module functionality, only interrupt signaling.

See also

TWIHS0_EnableInterrupt() to enable specific sources.

TWIHS0_InterruptFlagIsSet() to poll interrupt status.

TWIHS_INTERRUPT_DISABLE for available sources.

TWIHS0_EnableInterrupts()

void TWIHS0_EnableInterrupts

(

TWIHS_INTERRUPT_ENABLE

interrupts

)

Enable a specific TWIHS interrupt source.

Enables the specified interrupt(s) by setting the corresponding bits in TWIHS_IER (Interrupt Enable Register). When enabled, TWI interrupts will trigger the ISR, which invokes the registered callback (if set via SetCallbackHandler).

Available interrupt sources (TWIHS_INTERRUPT_ENABLE):

• TWIHS_INTERRUPT_TX_COMPLETION_EN : Transmission completed interrupt enable.
• TWIHS_INTERRUPT_RX_HOLDING_REGISTER_READY_EN : Receive holding register ready interrupt enable.
• TWIHS_INTERRUPT_TX_HOLDING_REGISTER_READY_EN : Transmit holding register ready interrupt enable.
• TWIHS_INTERRUPT_CLIENT_ACCESS_EN : Client access interrupt enable.
• TWIHS_INTERRUPT_GENERAL_CALL_ACCESS_EN : General call access interrupt enable.
• TWIHS_INTERRUPT_SCL_WAIT_STATE_EN : SCL wait state interrupt enable.
• TWIHS_INTERRUPT_END_OF_CLIENT_ACCESS_EN : End of client access interrupt enable.
• TWIHS_INTERRUPT_HOST_CODE_ACK_EN : Host code acknowledge interrupt enable.
• TWIHS_INTERRUPT_NACK_EN : NACK detected interrupt enable.
• TWIHS_INTERRUPT_ARBITERATION_LOST_EN : Arbitration lost interrupt enable.
• TWIHS_INTERRUPT_OVERRUN_ERROR_EN : Overrun error interrupt enable.
• TWIHS_INTERRUPT_UNDERRUN_ERROR_EN : Underrun error interrupt enable.
• TWIHS_INTERRUPT_TIMEOUT_ERROR_EN : Timeout error interrupt enable.
• TWIHS_INTERRUPT_PEC_ERROR_EN : PEC error interrupt enable.

Parameters

interrupts

- One or more interrupt source(s) (OR'd together) to enable. Example: EnableInterrupt(TWIHS_INTERRUPT_NACK_EN | TWIHS_INTERRUPT_ARBITERATION_LOST_EN)

Note

Before enabling interrupts, ensure the interrupt controller is configured to route TWIHS0 interrupts to the CPU.

The TWIHS0_SetCallbackHandler() must be called before enabling interrupts to register the callback function.

Multiple interrupt sources can be enabled simultaneously.

Some interrupts are mode-specific (e.g., EOSACC, SVACC only in Client mode).

See also

TWIHS0_DisableInterrupt() to disable specific sources.

TWIHS0_SetCallbackHandler() to register the callback.

TWIHS_INTERRUPT_ENABLE for available sources.

TWIHS0_GetBusStatus()

uint32_t TWIHS0_GetBusStatus

(

void

)

Returns the current TWIHS bus status.

Parameters

None.

Returns

Current bus status flags.

Returns the current TWIHS bus status.

Available bus status (TWIHS_STATUS_EVENTS):

• TWIHS_EVENT_TX_COMPLETION : Transmission completed.
• TWIHS_EVENT_RX_HOLDING_REGISTER_READY : A byte has been received
• TWIHS_EVENT_TX_HOLDING_REGISTER_READY : data has been transmitted and acknowledged.
• TWIHS_EVENT_CLIENT_ACCESS : address decoding sequence has matched.
• TWIHS_EVENT_GENERAL_CALL_ACCESS : general call has been detected.
• TWIHS_EVENT_SCL_WAIT_STATE : The clock is stretched.
• TWIHS_EVENT_END_OF_CLIENT_ACCESS : The Client Access is finished.
• TWIHS_EVENT_HOST_CODE_ACK : A Host Code has been received since the last read of TWIHS_SR.
• TWIHS_EVENT_NACK : A data or address byte has not been acknowledged by the Client.
• TWIHS_EVENT_ARBITERATION_LOST : Arbitration lost.
• TWIHS_EVENT_OVERRUN_ERROR : Overrun error event.
• TWIHS_EVENT_UNDERRUN_ERROR : Underrun error event.
• TWIHS_EVENT_TIMEOUT_ERROR : Timeout error event.
• TWIHS_EVENT_READ_ACCESS_BY_HOST : read access is performed by a Host.
• TWIHS_EVENT_SCL_LINE_VALUE : SCL line sampled value is 1 when set.
• TWIHS_EVENT_SDA_LINE_VALUE : SDA line sampled value is 1 when set.

Note

Multiple bus status can be received simultaneously.

Use this function inside the TWI host/client state machine to get the bus status.

Parameters

None.

Returns

Current bus status flags - each bit specifies each bus event. Once this api is called the returned uint32_t bit data should be masked with TWIHS_STATUS_EVENTS elements to get the correct event status Example: status = TWIHS0_GetBusStatus(); if ((status & TWIHS_EVENT_NACK) != 0U) { }

TWIHS0_GetInterruptMask()

uint32_t TWIHS0_GetInterruptMask

(

void

)

Returns the current interrupt mask register value.

Parameters

None.

Returns

Current interrupt mask register value.

TWIHS0_Host_Disable()

void TWIHS0_Host_Disable

(

void

)

Disables the TWIHS Host mode operation.

Disables the TWIHS0 peripheral Host functionality by setting the MSDIS bit in the TWIHS_CR register. The function ensures that ongoing transfers are completed before shutdown.

Note

This api should be called before enabling the TWIHS0 in Client mode.

Unlike TWIHS0_ResetSoftware, this does not reset configuration registers.

Parameters

None.

Returns

None.

TWIHS0_Host_Enable()

void TWIHS0_Host_Enable

(

void

)

Enables the TWIHS Host mode operation.

Enables the TWIHS0 peripheral Host functionality by setting the MSEN bit in the TWIHS_CR register. The peripheral clock must be enabled via PMC before calling this function.

Note

Client mode should be disabled by setting SVDIS bit from TWIHS_CR register before calling this api.

TWIHS_CWGR register should be configured with the required TWI clock speed before calling this api.

Parameters

None.

Returns

None.

TWIHS0_Host_SendAddress()

void TWIHS0_Host_SendAddress

(

uint32_t

address

)

Sets the target client address by writing the DADR bits in TWIHS_MMR register.

Calling this api doesn't initiate the client address transfer directly , instead it sets the client address which will be sent on bus once the transfer is initiated by writing into the TWIHS_THR register in Host write mode or setting the START bit in TWIHS_THR register in Host read mode.

Note

While setting the DADR bits, the internal address size should be set in IADRSZ bits, which is done by this api itself.

During Host write operation, this api should be called before writing the data byte into the TWIHS_THR register.

During Host Read operation, this api should be called before initiating the Start condition by calling TWIHS0_Host_SendStart().

Parameters

address

- 7-bit or 10-bit client address.

Returns

None.

TWIHS0_Host_SendStart()

void TWIHS0_Host_SendStart

(

void

)

Sends the I2C START condition on the bus by writing into the START bit in TWIHS_CR register. A frame beginning with a START bit is transmitted according to the features defined in the TWIHS Host Mode Register (TWIHS_MMR).

This action is necessary when the TWIHS peripheral needs to read data from a Client. When configured in Host mode with a write operation, a frame is sent as soon as the user writes a character in the Transmit Holding Register (TWIHS_THR).

Note

This api should be called only during Host read operation.

Ensure the Client address is set in DADR bits in TWIHS_MMR register before calling this api.

Ensure the Transfer direction is set in MREAD bit in TWIHS_MMR register before calling this api.

Parameters

None.

Returns

None.

TWIHS0_Host_SendStartAndStop()

void TWIHS0_Host_SendStartAndStop

(

void

)

Sets both the I2C START and STOP condition START and the STOP bits in TWIHS_CR register.

In single data byte Host read, both START and STOP must be set.

Note

This api should be called before initiating the read operation.

TXCOMP interrupt is generated after the STOP condition has been sent.

Parameters

None.

Returns

None.

TWIHS0_Host_SendStop()

void TWIHS0_Host_SendStop

(

void

)

Sends the I2C STOP condition on the bus by writing into the STOP bit in TWIHS_CR register.

In single data byte Host read, both START and STOP must be set. In multiple data bytes Host read, the STOP must be set after the last data received but one. In Host Read mode, if a NACK bit is received, the STOP is automatically performed. In Host data write operation, a STOP condition will be sent after the transmission of the current data is finished.

Note

TXCOMP interrupt is generated after the STOP condition has been sent.

In Host Read mode call this api to set the STOP bit before reading the TWIHS_RHR on the next-to-last access.

In Host Write mode call this api to send the STOP bit after writing the last byte to be transfered into the TWIHS_THR register.

Parameters

None.

Returns

None.

TWIHS0_Host_SetInternalAddressSize()

void TWIHS0_Host_SetInternalAddressSize

(

TWIHS_HOST_INTERNAL_ADDRESS_SIZE

internal_address_size

)

Configures the internal address size for the transfer based on the the size of the client address. Set to 1, 2 or 3 when client address exceeds 7 bits. Set to 0 when client address is within 7 bits.

Parameters

internal_address_size

- Internal address size (set to zero for 7-bit addressing).

Returns

None.

TWIHS0_Host_SetTransferDirection()

void TWIHS0_Host_SetTransferDirection

(

TWIHS_TRANSFER_DIR

transfer_direction

)

Sets the TWIHS host transfer direction.

Note

During Host write operation, this api should be called before writing the data byte into the TWIHS_THR register.

During Host Read operation, this api should be called before initiating the Start condition by calling TWIHS0_Host_SendStart().

Parameters

transfer_direction

- Direction of transfer (Host read or write).

Returns

None.

TWIHS0_LastByteAckStatusGet()

TWIHS_CLIENT_ACK_STATUS TWIHS0_LastByteAckStatusGet

(

void

)

Returns the acknowledge status of the last received byte.

In Host mode NACK bit is set when a data or address byte has not been acknowledged by the Client component. Set at the same time as TXCOMP

In Client mode In Read mode, NACK bit is set when a data byte has not been acknowledged by the Host. When NACK is set, the user must not fill TWIHS_THR even if TXRDY is set, because it means that the Host stops the data transfer or re-initiate it.

Parameters

None.

Returns

Acknowledge status of the last byte.

TWIHS0_ReceiveData()

uint8_t TWIHS0_ReceiveData

(

void

)

Receive a single data word via SPI. Reads data from the TWIHS_RHR (Receive Holding register) that was received from the TWI bus.

In Host read mode, The read sequence begins by setting the START bit. After the START condition has been sent, the Host sends a 7-bit Client address to notify the Client device The bit following the Client address indicates the transfer direction, 0 in this case (MREAD = 0 in TWIHS_MMR). When TWIHS_SR.RXRDY is set, a character has been received in the Receive Holding register (TWIHS_RHR). The RXRDY bit is reset when reading the TWIHS_RHR.

In Client read mode, After a START or a REPEATED START, the decoding of the address starts. If the Client address is decoded, SVACC is set and SVREAD indicates the direction of the transfer (SVREAD is low in this case). Until a STOP or REPEATED START condition is detected, the TWIHS stores the received data in TWIHS_RHR. If a STOP condition or a REPEATED START + an address different from SADR is detected, SVACC is reset.

Note

In Host/Client mode TWIHS0_GetBusStatus should be called to check the TWIHS_SR.RXRDY status set before calling this api to read data.

Parameters

void

Returns

The received data byte (8 bits;).

TWIHS0_ResetSoftware()

void TWIHS0_ResetSoftware

(

void

)

Perform a software reset of the TWIHS module.

Resets the TWI module to its initial state by setting the SWRST bit in TWIHS_CR register. After reset, all registers return to their default values:

• TWIHS is disabled
• All interrupt flags are cleared
• All pending transfers are aborted

After calling this function, the TWIHS peripheral must be reconfigured before use.

Note

This is a non-destructive reset; TWIHS configuration registers are reset, not preserved.

Use TWIHS0_Client_Disable() or TWIHS0_Host_Disable() if you need to stop transfers without losing configuration.

After reset, always reconfigure:

1. Bus speed for Host mode (TWIHS0_SetBaudRate)
2. 7-bit client address (TWIHS0_Client_Set7bitAddress)
3. Interrupts (TWIHS0_EnableInterrupts) Then call TWIHS0_Client_Enable() or TWIHS0_Host_Enable() to restart operation.

Parameters

None.

Returns

None.

TWIHS0_SendData()

void TWIHS0_SendData

(

uint8_t

data

)

Send a single data word via TWI. Writes data to the TWIHS_THR (Transmit Holding register) to initiate a data transfer.

In Host write mode, writing to TWIHS_THR register initiates a START condition, it sends a 7-bit Client address, configured in the Host Mode register (DADR in TWIHS_MMR), to notify the Client device. The bit following the Client address indicates the transfer direction, 0 in this case (MREAD = 0 in TWIHS_MMR).

In Client write mode, After a START or a REPEATED START condition is detected, the decoding of the address starts. If the Client address (SADR) is decoded, SVACC is set and SVREAD indicates the direction of the transfer. Until a STOP or REPEATED START condition is detected, the TWIHS continues sending data loaded in TWIHS_THR. If a STOP condition or a REPEATED START + an address different from SADR is detected, SVACC is reset.

Note

In Host mode TWIHS0_Host_SetTransferDirection should be set before calling this api.

In Client mode, this api should be called whe the transfer direction is read ( checked by calling TWIHS0_Client_TransferDirGetmode).

Parameters

data	The data byte to transmit (8 bits;).

Returns

void

TWIHS0_SetBaudRate()

TWIHS_HOST_HWREG_STATUS TWIHS0_SetBaudRate	(	uint32_t	srcClkFreq,
		uint32_t	i2cClkSpeed )

Sets the TWIHS clock speed by writing CKDIV, CHDIV and CLDIV bits in the TWIHS_CWGR register.

This api internally calculates the register values to be configured taking the system clock and the required I2C clock as the input.

Parameters

srcClkFreq	- Source clock frequency in Hz.
i2cClkSpeed	- Desired I2C clock speed in Hz.

Returns

Status of the baud rate configuration.

TWIHS0_SetCallbackHandler()

void TWIHS0_SetCallbackHandler

(

TWIHS_CALLBACK_HANDLER

callback

)

Register an interrupt callback handler.

Registers a user-defined callback function to be invoked from the TWI interrupt service routine (ISR) when any enabled TWI interrupt occurs.

Note

Interrupt callbacks are invoked from ISR context (high priority). Keep callback code short and fast to avoid latency.

The callback must be registered before enabling interrupts with EnableInterrupt().

Pass NULL to disable callback invocation (though interrupts remain enabled).

Each TWI instance has its own callback handler; TWIHS0_SetCallbackHandler() sets the handler for TWIHS0 only.

See also

TWIHS0_EnableInterrupt() to enable specific interrupt sources.

TWIHS_CALLBACK_HANDLER for callback function signature.

Parameters

callback

Function pointer to the callback handler: typedef void (*TWIHS_CALLBACK_HANDLER)(void);