SFBHWI2C Class Reference

Provide access to the I2C bus hardware on the IXM. More...

#include <SFBHWI2C.h>

Public Member Functions
	SFBHWI2C (u32 interface)
	Construct an SFBHWI2c.
void	setByteSource (I2CByteSource function)
	Enable or disable 'streaming transmit' mode.
void	setByteSink (I2CByteSink function)
	Enable or disable 'streaming receive' mode.
void	transmit (u8 address, u32 length, u8 *message)
	Begin transmitting an I2C command.
void	receive (u8 address, u32 length, u8 *message)
	Begin receiving an I2C command.
void	transceive (u8 address, u32 xmtLength, u8 *xmtData, u32 rcvLength, u8 *rcvData)
	Begin an I2C combined transmit/receive transaction.
void	init (u32 pins, u32 bitRate)
	Specify which pins to use for I2C operation, and the clock speed of the I2C bus.
s8	status ()
	Access current I2C interface status.
void	setBitRate (u32 bitRate)
	Set the I2C clock bit rate to bitRate, measured in KHz.
u32	count ()
	The current 'data count' -- which byte is being sent or received after a transmit or a receive call.
Friends
void	I2C1Handler ()
	Internal use only. Static ISR for I2C_1.
void	I2C2Handler ()
	Internal use only. Static ISR for I2C_2.

---

Detailed Description

Provide access to the I2C bus hardware on the IXM.

For working code samples, see i2c1::cpp, i2c2::cpp, and i2cstream::cpp.

Examples:

i2cDAC.cpp, i2cDACFast.cpp, and i2cEeprom.cpp.

---

Constructor & Destructor Documentation

SFBHWI2C::SFBHWI2C

(

u32

interface

)

Construct an SFBHWI2c.

Note the constructed instance must be initialized, via init, before use.

Parameters:

interface

which IC2 interface this controls. I2C_1 and I2C_2 are available.

---

Member Function Documentation

u32 SFBHWI2C::count

(

)

The current 'data count' -- which byte is being sent or received after a transmit or a receive call.

Perhaps useful as a progress indicator.

void SFBHWI2C::init	(	u32	pins,
		u32	bitRate
	)

Specify which pins to use for I2C operation, and the clock speed of the I2C bus.

Parameters:

	pins	controls which pair of pins SDA and SCL are mapped to, drawn from I2CPinSelectCode. For I2C_1, options are I2C1_PINS_WEST_TX_RX and I2C1_PINS_SOUTH_D3_D2. For I2C_2, the only pins available are I2C2_PINS_EAST_TX_RX
	bitRate	(in kHz) should be either 100 or 400; see setBitRate for details.

Examples:

i2cDAC.cpp, i2cDACFast.cpp, and i2cEeprom.cpp.

void SFBHWI2C::receive	(	u8	address,
		u32	length,
		u8 *	message
	)

Begin receiving an I2C command.

The interface must already have been initialized via init. Note this function only begins reception! User code should use status to check when the command has completed.

Parameters:

	address	specifies the I2C address to receive from
	length	specifies the number of bytes to receive and store in message
	message	points to a length bytes buffer to be filled with data received from address

void SFBHWI2C::setBitRate

(

u32

bitRate

)

Set the I2C clock bit rate to bitRate, measured in KHz.

Officially speaking only 100KHz (normal mode) and 400KHz (fast mode) clocks are supported, but many slave devices (particularly simple ones), may tolerate rates between, below, and above those two values.

Parameters:

bitRate

(in kHz) should be either 100 or 400, for normal or fast mode operation, respectively. Other bitRates -- between those values and sometimes beyond them -- may work depending on the device(s) on the I2C bus.

void SFBHWI2C::setByteSink

(

I2CByteSink

function

)

[inline]

Enable or disable 'streaming receive' mode.

'Streaming receive' mode causes the I2C controller to call back to user code as each byte of an I2C command is received, allowing arbitrary length I2C commands to be received without having to preallocate space for the entire command in memory, or, indeed, knowing how long the command will be in advance. A downside of 'streaming receive' mode is that the user code is called at interrupt level and so must be reasonably quick to avoid introducing delays.

Parameters:

function

if 0, disable streaming receive mode. Otherwise, enable streaming receive mode, calling this function as needed (at interrupt level!) to dispose of each byte as it is received.

void SFBHWI2C::setByteSource

(

I2CByteSource

function

)

[inline]

Enable or disable 'streaming transmit' mode.

'Streaming transmit' mode causes the I2C controller to call back to user code for each byte of an I2C command, allowing arbitrary length I2C commands to be transmitted without having to buffer the entire command in memory. A downside of 'streaming transmit' mode is that the user code is called at interrupt level and so must be reasonably quick to avoid introducing delays.

Parameters:

function

if 0, disable streaming transmit mode. Otherwise, enable streaming transmit mode, calling this function as needed (at interrupt level!) to obtain the next byte to transmit.

Examples:

i2cDACFast.cpp.

s8 SFBHWI2C::status

(

)

Access current I2C interface status.

Returns one of the values specified by I2CStatusCodes. Any status greater than 0 (I2C_MODE_DONE) means things are in progress and still working properly. A status less than 0 means that something went wrong. Status equal to 0 means that the I2C is not presently transmitting/receiving (or that it has finished transmitting/receiving). Checking for I2C_MODE_DONE is the typical way to determine if another I2C command can be initiated.

Examples:

i2cDAC.cpp, and i2cEeprom.cpp.

void SFBHWI2C::transceive	(	u8	address,
		u32	xmtLength,
		u8 *	xmtData,
		u32	rcvLength,
		u8 *	rcvData
	)

Begin an I2C combined transmit/receive transaction.

The interface must already have been initialized via init. Note this function only begins the transmit/receive process! User code should use status to check when the entire transaction has completed.

The I2C bus protocol provides a 'repeated start' mechanism to allow a bus master to perform more than one transaction with a slave without yielding the bus. The repeated start can be used, for example, for a master to transmit some information -- such as a memory address -- and then immediately receive information -- such as the contents of the that address -- without giving up the bus. Without the repeated start mechanism, there could be a risk that another master might grab the bus after the transmit and interject an interfering command.

Parameters:

	address	specifies the I2C address to transmit to
	xmtLength	specifies the number of bytes to transmit, starting from xmtData
	xmtData	points to xmtLength bytes to be transmitted to address
	rcvLength	specifies the number of bytes to receive, starting from rcvData
	rcvData	points to rcvLength bytes buffer to fill with data received from address

Examples:

i2cEeprom.cpp.

void SFBHWI2C::transmit	(	u8	address,
		u32	length,
		u8 *	message
	)

Begin transmitting an I2C command.

The interface must already have been initialized via init. Note this function only begins the transmission! User code should use status to check when the command has completed.

Parameters:

	address	specifies the I2C address to transmit to
	length	specifies the number of bytes to transmit, starting from message
	message	points to length bytes to be transmitted to address

Examples:

i2cDAC.cpp, i2cDACFast.cpp, and i2cEeprom.cpp.

---

The documentation for this class was generated from the following files:

• src/include/SFBHWI2C.h
• src/components/board/SFBHWI2C.cpp