Nut/OS  4.10.3
API Reference
AT91 Two Wire Interface

Two wire interface. More...

Collaboration diagram for AT91 Two Wire Interface:

Defines

#define TWI_PIO_ASR   PIOA_ASR
#define TWI_PIO_PDR   PIOA_PDR
#define TWI_PIO_MDER   PIOA_MDER

Functions

int TwMasterTransact (uint8_t sla, CONST void *txdata, uint16_t txlen, void *rxdata, uint16_t rxsiz, uint32_t tmo)
 Transmit and/or receive data as a master.
int TwMasterRegRead (uint8_t sla, uint32_t iadr, uint8_t iadrlen, void *rxdata, uint16_t rxsiz, uint32_t tmo)
 Receive data as a master from a device having internal addressable registers.
int TwMasterRegWrite (uint8_t sla, uint32_t iadr, uint8_t iadrlen, CONST void *txdata, uint16_t txsiz, uint32_t tmo)
 Transmit data as a master to a device having internal addressable registers.
int TwMasterError (void)
 Get last master mode error.
uint16_t TwMasterIndexes (uint8_t idx)
 Get last transfer results.
int TwIOCtl (int req, void *conf)
 Perform TWI control functions.
int TwInit (uint8_t sla)
 Initialize TWI interface.

TWI Control Register

#define TWI_CR_OFF   0x00000000
 Control register offset.
#define TWI_CR   (TWI_BASE + TWI_CR_OFF)
 Control register address.
#define TWI_START   0x00000001
 Send start condition.
#define TWI_STOP   0x00000002
 Send stop condition.
#define TWI_MSEN   0x00000004
 Enable master mode.
#define TWI_MSDIS   0x00000008
 Disable master mode.
#define TWI_SVEN   0x00000010
 Enable slave mode.
#define TWI_SVDIS   0x00000020
 Disable slave mode.
#define TWI_SWRST   0x00000080
 Software reset.

TWI Master Mode Register

#define TWI_MMR_OFF   0x00000004
 Master mode register offset.
#define TWI_MMR   (TWI_BASE + TWI_MMR_OFF)
 Master mode register address.
#define TWI_IADRSZ   0x00000300
 Internal device address size mask.
#define TWI_IADRSZ_NONE   0x00000000
 No internal device address.
#define TWI_IADRSZ_1BYTE   0x00000100
 One byte internal device address.
#define TWI_IADRSZ_2BYTE   0x00000200
 Two byte internal device address.
#define TWI_IADRSZ_3BYTE   0x00000300
 Three byte internal device address.
#define TWI_MREAD   0x00001000
 Master read direction.
#define TWI_DADR   0x007F0000
 Device address mask.
#define TWI_DADR_LSB   16
 Device address LSB.

TWI Slave Mode Register

#define TWI_SMR_OFF   0x00000008
 Slave mode register offset.
#define TWI_SMR   (TWI_BASE + TWI_SMR_OFF)
 Slave mode register address.
#define TWI_SADR   0x007F0000
 Slave address mask.
#define TWI_SADR_LSB   16
 Slave address LSB.

TWI Internal Address Register

#define TWI_IADRR_OFF   0x0000000C
 Internal address register offset.
#define TWI_IADRR   (TWI_BASE + TWI_IADRR_OFF)
 Internal address register address.
#define TWI_IADR   0x00FFFFFF
 Internal address mask.
#define TWI_IADR_LSB   0
 Internal address LSB.

TWI Clock Waveform Generator Register

#define TWI_CWGR_OFF   0x00000010
 Clock waveform generator register offset.
#define TWI_CWGR   (TWI_BASE + TWI_CWGR_OFF)
 Clock waveform generator register address.
#define TWI_CLDIV   0x000000FF
 Clock low divider mask.
#define TWI_CLDIV_LSB   0
 Clock low divider LSB.
#define TWI_CHDIV   0x0000FF00
 Clock high divider mask.
#define TWI_CHDIV_LSB   8
 Clock high divider LSB.
#define TWI_CKDIV   0x00070000
 Clock divider mask.
#define TWI_CKDIV_LSB   16
 Clock divider LSB.

TWI Status and Interrupt Registers

#define TWI_SR_OFF   0x00000020
 Status register offset.
#define TWI_SR   (TWI_BASE + TWI_SR_OFF)
 Status register address.
#define TWI_IER_OFF   0x00000024
 Interrupt enable register offset.
#define TWI_IER   (TWI_BASE + TWI_IER_OFF)
 Interrupt enable register address.
#define TWI_IDR_OFF   0x00000028
 Interrupt disable register offset.
#define TWI_IDR   (TWI_BASE + TWI_IDR_OFF)
 Interrupt disable register address.
#define TWI_IMR_OFF   0x0000002C
 Interrupt mask register offset.
#define TWI_IMR   (TWI_BASE + TWI_IMR_OFF)
 Interrupt mask register address.
#define TWI_TXCOMP   0x00000001
 Transmission completed.
#define TWI_RXRDY   0x00000002
 Receive holding register ready.
#define TWI_TXRDY   0x00000004
 Transmit holding register ready.
#define TWI_SVREAD   0x00000008
 Slave read.
#define TWI_SVACC   0x00000010
 Slave access.
#define TWI_GACC   0x00000020
 General call access.
#define TWI_OVRE   0x00000040
 Overrun error.
#define TWI_NACK   0x00000100
 Not acknowledged.
#define TWI_ARBLST   0x00000200
 Arbitration lost.
#define TWI_SCLWS   0x00000400
 Clock wait state.
#define TWI_EOSACC   0x00000800
 End of slave access.

TWI Receive Holding Register

#define TWI_RHR_OFF   0x00000030
 Receive holding register offset.
#define TWI_RHR   (TWI_BASE + TWI_RHR_OFF)
 Receive holding register address.

TWI Transmit Holding Register

#define TWI_THR_OFF   0x00000034
 Transmit holding register offset.
#define TWI_THR   (TWI_BASE + TWI_THR_OFF)
 Transmit holding register address.

Detailed Description

Two wire interface.


Define Documentation

#define TWI_CR_OFF   0x00000000

Control register offset.

Definition at line 60 of file at91_twi.h.

#define TWI_CR   (TWI_BASE + TWI_CR_OFF)

Control register address.

Definition at line 61 of file at91_twi.h.

Referenced by TwInit(), TwMasterRegRead(), and TwMasterTransact().

#define TWI_START   0x00000001

Send start condition.

Definition at line 62 of file at91_twi.h.

Referenced by TwMasterRegRead(), and TwMasterTransact().

#define TWI_STOP   0x00000002

Send stop condition.

Definition at line 63 of file at91_twi.h.

Referenced by TwMasterRegRead(), and TwMasterTransact().

#define TWI_MSEN   0x00000004

Enable master mode.

Definition at line 64 of file at91_twi.h.

Referenced by TwInit().

#define TWI_MSDIS   0x00000008

Disable master mode.

Definition at line 65 of file at91_twi.h.

#define TWI_SVEN   0x00000010

Enable slave mode.

Definition at line 66 of file at91_twi.h.

#define TWI_SVDIS   0x00000020

Disable slave mode.

Definition at line 67 of file at91_twi.h.

Referenced by TwInit().

#define TWI_SWRST   0x00000080

Software reset.

Definition at line 68 of file at91_twi.h.

Referenced by TwInit().

#define TWI_MMR_OFF   0x00000004

Master mode register offset.

Definition at line 73 of file at91_twi.h.

#define TWI_MMR   (TWI_BASE + TWI_MMR_OFF)

Master mode register address.

Definition at line 74 of file at91_twi.h.

Referenced by TwMasterRegRead(), TwMasterRegWrite(), and TwMasterTransact().

#define TWI_IADRSZ   0x00000300

Internal device address size mask.

Definition at line 75 of file at91_twi.h.

#define TWI_IADRSZ_NONE   0x00000000

No internal device address.

Definition at line 76 of file at91_twi.h.

#define TWI_IADRSZ_1BYTE   0x00000100

One byte internal device address.

Definition at line 77 of file at91_twi.h.

#define TWI_IADRSZ_2BYTE   0x00000200

Two byte internal device address.

Definition at line 78 of file at91_twi.h.

#define TWI_IADRSZ_3BYTE   0x00000300

Three byte internal device address.

Definition at line 79 of file at91_twi.h.

#define TWI_MREAD   0x00001000

Master read direction.

Definition at line 80 of file at91_twi.h.

Referenced by TwMasterRegRead(), and TwMasterTransact().

#define TWI_DADR   0x007F0000

Device address mask.

Definition at line 81 of file at91_twi.h.

#define TWI_DADR_LSB   16

Device address LSB.

Definition at line 82 of file at91_twi.h.

Referenced by TwMasterRegRead(), TwMasterRegWrite(), and TwMasterTransact().

#define TWI_SMR_OFF   0x00000008

Slave mode register offset.

Definition at line 87 of file at91_twi.h.

#define TWI_SMR   (TWI_BASE + TWI_SMR_OFF)

Slave mode register address.

Definition at line 88 of file at91_twi.h.

#define TWI_SADR   0x007F0000

Slave address mask.

Definition at line 89 of file at91_twi.h.

#define TWI_SADR_LSB   16

Slave address LSB.

Definition at line 90 of file at91_twi.h.

#define TWI_IADRR_OFF   0x0000000C

Internal address register offset.

Definition at line 95 of file at91_twi.h.

#define TWI_IADRR   (TWI_BASE + TWI_IADRR_OFF)

Internal address register address.

Definition at line 96 of file at91_twi.h.

Referenced by TwMasterRegRead(), and TwMasterRegWrite().

#define TWI_IADR   0x00FFFFFF

Internal address mask.

Definition at line 97 of file at91_twi.h.

#define TWI_IADR_LSB   0

Internal address LSB.

Definition at line 98 of file at91_twi.h.

#define TWI_CWGR_OFF   0x00000010

Clock waveform generator register offset.

Definition at line 103 of file at91_twi.h.

#define TWI_CWGR   (TWI_BASE + TWI_CWGR_OFF)

Clock waveform generator register address.

Definition at line 104 of file at91_twi.h.

Referenced by TwIOCtl().

#define TWI_CLDIV   0x000000FF

Clock low divider mask.

Definition at line 105 of file at91_twi.h.

#define TWI_CLDIV_LSB   0

Clock low divider LSB.

Definition at line 106 of file at91_twi.h.

#define TWI_CHDIV   0x0000FF00

Clock high divider mask.

Definition at line 107 of file at91_twi.h.

#define TWI_CHDIV_LSB   8

Clock high divider LSB.

Definition at line 108 of file at91_twi.h.

#define TWI_CKDIV   0x00070000

Clock divider mask.

Definition at line 109 of file at91_twi.h.

#define TWI_CKDIV_LSB   16

Clock divider LSB.

Definition at line 110 of file at91_twi.h.

#define TWI_SR_OFF   0x00000020

Status register offset.

Definition at line 115 of file at91_twi.h.

#define TWI_SR   (TWI_BASE + TWI_SR_OFF)

Status register address.

Definition at line 116 of file at91_twi.h.

#define TWI_IER_OFF   0x00000024

Interrupt enable register offset.

Definition at line 118 of file at91_twi.h.

#define TWI_IER   (TWI_BASE + TWI_IER_OFF)

Interrupt enable register address.

Definition at line 119 of file at91_twi.h.

Referenced by TwMasterRegRead(), TwMasterRegWrite(), and TwMasterTransact().

#define TWI_IDR_OFF   0x00000028

Interrupt disable register offset.

Definition at line 121 of file at91_twi.h.

#define TWI_IDR   (TWI_BASE + TWI_IDR_OFF)

Interrupt disable register address.

Definition at line 122 of file at91_twi.h.

Referenced by TwInit(), TwMasterRegRead(), TwMasterRegWrite(), and TwMasterTransact().

#define TWI_IMR_OFF   0x0000002C

Interrupt mask register offset.

Definition at line 124 of file at91_twi.h.

#define TWI_IMR   (TWI_BASE + TWI_IMR_OFF)

Interrupt mask register address.

Definition at line 125 of file at91_twi.h.

#define TWI_TXCOMP   0x00000001

Transmission completed.

Definition at line 127 of file at91_twi.h.

#define TWI_RXRDY   0x00000002

Receive holding register ready.

Definition at line 128 of file at91_twi.h.

Referenced by TwMasterRegRead(), and TwMasterTransact().

#define TWI_TXRDY   0x00000004

Transmit holding register ready.

Definition at line 129 of file at91_twi.h.

Referenced by TwMasterRegWrite(), and TwMasterTransact().

#define TWI_SVREAD   0x00000008

Slave read.

Definition at line 130 of file at91_twi.h.

#define TWI_SVACC   0x00000010

Slave access.

Definition at line 131 of file at91_twi.h.

#define TWI_GACC   0x00000020

General call access.

Definition at line 132 of file at91_twi.h.

#define TWI_OVRE   0x00000040

Overrun error.

Definition at line 133 of file at91_twi.h.

#define TWI_NACK   0x00000100

Not acknowledged.

Definition at line 134 of file at91_twi.h.

#define TWI_ARBLST   0x00000200

Arbitration lost.

Definition at line 135 of file at91_twi.h.

#define TWI_SCLWS   0x00000400

Clock wait state.

Definition at line 136 of file at91_twi.h.

#define TWI_EOSACC   0x00000800

End of slave access.

Definition at line 137 of file at91_twi.h.

#define TWI_RHR_OFF   0x00000030

Receive holding register offset.

Definition at line 142 of file at91_twi.h.

#define TWI_RHR   (TWI_BASE + TWI_RHR_OFF)

Receive holding register address.

Definition at line 143 of file at91_twi.h.

#define TWI_THR_OFF   0x00000034

Transmit holding register offset.

Definition at line 148 of file at91_twi.h.

#define TWI_THR   (TWI_BASE + TWI_THR_OFF)

Transmit holding register address.

Definition at line 149 of file at91_twi.h.

Referenced by TwMasterRegWrite(), and TwMasterTransact().

#define TWI_PIO_ASR   PIOA_ASR

Definition at line 79 of file at91_twi.c.

Referenced by TwInit().

#define TWI_PIO_PDR   PIOA_PDR

Definition at line 82 of file at91_twi.c.

Referenced by TwInit().

#define TWI_PIO_MDER   PIOA_MDER

Definition at line 85 of file at91_twi.c.

Referenced by TwInit().


Function Documentation

int TwMasterTransact ( uint8_t  sla,
CONST void *  txdata,
uint16_t  txlen,
void *  rxdata,
uint16_t  rxsiz,
uint32_t  tmo 
)

Transmit and/or receive data as a master.

The two-wire serial interface must have been initialized by calling TwInit() before this function can be used.

Parameters:
slaSlave address of the destination. This slave address must be specified as a 7-bit address. For example, the PCF8574A may be configured to slave addresses from 0x38 to 0x3F.
txdataPoints to the data to transmit. Ignored, if the number of data bytes to transmit is zero.
txlenNumber of data bytes to transmit. If zero, then the interface will not send any data to the slave device and will directly enter the master receive mode.
rxdataPoints to a buffer, where the received data will be stored. Ignored, if the maximum number of bytes to receive is zero.
rxsizMaximum number of bytes to receive. Set to zero, if no bytes are expected from the slave device.
tmoTimeout in milliseconds. To disable timeout, set this parameter to NUT_WAIT_INFINITE.
Returns:
The number of bytes received, -1 in case of an error or timeout.

Definition at line 180 of file at91_twi.c.

References NutEventPost(), NutEventWait(), outr, tw_mm_mutex, tw_mm_que, TWERR_IF_LOCKED, TWERR_TIMEOUT, TWI_CR, TWI_DADR_LSB, TWI_IDR, TWI_IER, TWI_MMR, TWI_MREAD, TWI_RXRDY, TWI_START, TWI_STOP, TWI_THR, and TWI_TXRDY.

Here is the call graph for this function:

int TwMasterRegRead ( uint8_t  sla,
uint32_t  iadr,
uint8_t  iadrlen,
void *  rxdata,
uint16_t  rxsiz,
uint32_t  tmo 
)

Receive data as a master from a device having internal addressable registers.

The two-wire serial interface must have been initialized by calling TwInit() before this function can be used.

Parameters:
slaSlave address of the destination. This slave address must be specified as a 7-bit address. For example, the PCF8574A may be configured to slave addresses from 0x38 to 0x3F.
iadrAddress send to the device to access certain registers or memory addresses of it.
iadrlenNumber of bytes to send as address, maximum 3 bytes are supported from AT91SAM7
rxdataPoints to a buffer, where the received data will be stored.
rxsizMaximum number of bytes to receive.
tmoTimeout in milliseconds. To disable timeout, set this parameter to NUT_WAIT_INFINITE.
Returns:
The number of bytes received, -1 in case of an error or timeout.

Definition at line 276 of file at91_twi.c.

References NutEventPost(), NutEventWait(), outr, tw_mm_mutex, tw_mm_que, TWERR_IF_LOCKED, TWERR_TIMEOUT, TWI_CR, TWI_DADR_LSB, TWI_IADRR, TWI_IDR, TWI_IER, TWI_MMR, TWI_MREAD, TWI_RXRDY, TWI_START, and TWI_STOP.

Referenced by IOExpGetBit(), and IOExpRawRead().

Here is the call graph for this function:

int TwMasterRegWrite ( uint8_t  sla,
uint32_t  iadr,
uint8_t  iadrlen,
CONST void *  txdata,
uint16_t  txsiz,
uint32_t  tmo 
)

Transmit data as a master to a device having internal addressable registers.

The two-wire serial interface must have been initialized by calling TwInit() before this function can be used.

Parameters:
slaSlave address of the destination. This slave address must be specified as a 7-bit address. For example, the PCF8574A may be configured to slave addresses from 0x38 to 0x3F.
iadrAddress send to the device to access certain registers or memory addresses of it.
iadrlenNumber of bytes to send as address, maximum 3 bytes are supported from AT91SAM7
txdataPoints to a buffer, where the data to transmit will be stored.
txsizMaximum number of bytes to transmit.
tmoTimeout in milliseconds. To disable timeout, set this parameter to NUT_WAIT_INFINITE.
Returns:
The number of bytes transmitted, -1 in case of an error or timeout. Number could be less if slave end transmission with NAK.

Definition at line 350 of file at91_twi.c.

References NutEventPost(), NutEventWait(), outb, outr, tw_mm_mutex, tw_mm_que, TWERR_IF_LOCKED, TWERR_TIMEOUT, TWI_DADR_LSB, TWI_IADRR, TWI_IDR, TWI_IER, TWI_MMR, TWI_THR, and TWI_TXRDY.

Referenced by IOExpInit(), IOExpPinConfigSet(), IOExpRawWrite(), IOExpSetBitHigh(), and IOExpSetBitLow().

Here is the call graph for this function:

int TwMasterError ( void  )

Get last master mode error.

You may call this function to determine the specific cause of an error after twi transaction failed.

Definition at line 398 of file at91_twi.c.

uint16_t TwMasterIndexes ( uint8_t  idx)

Get last transfer results.

Todo:
Do we really need this. It may not work with competing threads.

You may call this function to determine how many bytes where transferred before the twi transaction failed.

Definition at line 414 of file at91_twi.c.

int TwIOCtl ( int  req,
void *  conf 
)

Perform TWI control functions.

Parameters:
reqRequested control function. May be set to one of the following constants:
  • TWI_SETSPEED, if conf points to an uint32_t value containing the bitrate.
  • TWI_GETSPEED, if conf points to an uint32_t value receiving the current bitrate.
confPoints to a buffer that contains any data required for the given control function or receives data from that function.
Returns:
0 on success, -1 otherwise.
Note:
Timeout is limited to the granularity of the system timer.

Definition at line 443 of file at91_twi.c.

References inr, NUT_HWCLK_PERIPHERAL, NutClockGet, NutGetCpuClock(), outr, TWI_CWGR, TWI_GETSPEED, TWI_GETSTATUS, TWI_SETSPEED, and TWI_SETSTATUS.

Here is the call graph for this function:

int TwInit ( uint8_t  sla)

Initialize TWI interface.

The specified slave address is not used here as we don't support twi-slave on AT91SAM7X

Note:
This function is only available on AT91SAM7xxxx systems.
Parameters:
slaSlave address, must be specified as a 7-bit address, always lower than 128.

Definition at line 508 of file at91_twi.c.

References _BV, NUT_IRQMODE_LEVEL, NutEventPost(), NutIrqEnable(), NutIrqSetMode(), NutRegisterIrqHandler(), outr, PMC_PCER, tw_mm_mutex, TWI_CR, TWI_ID, TWI_IDR, TWI_MSEN, TWI_PIO_ASR, TWI_PIO_MDER, TWI_PIO_PDR, TWI_SETSPEED, TWI_SVDIS, TWI_SWRST, and TwIOCtl().

Here is the call graph for this function: