xiicps.h File Reference

#include "xil_types.h"
#include "xil_assert.h"
#include "xstatus.h"
#include "xiicps_hw.h"

Classes
struct	XIicPs_Config
struct	XIicPs
Defines
#define	XIICPS_H
Configuration options
The following options may be specified or retrieved for the device and enable/disable additional features of the IIC. Each of the options are bit fields, so more than one may be specified.
#define	XIICPS_7_BIT_ADDR_OPTION 0x01
#define	XIICPS_10_BIT_ADDR_OPTION 0x02
#define	XIICPS_SLAVE_MON_OPTION 0x04
#define	XIICPS_REP_START_OPTION 0x08
Callback events
These constants specify the handler events that are passed to an application event handler from the driver. These constants are bit masks such that more than one event can be passed to the handler.
#define	XIICPS_EVENT_COMPLETE_SEND 0x0001
#define	XIICPS_EVENT_COMPLETE_RECV 0x0002
#define	XIICPS_EVENT_TIME_OUT 0x0004
#define	XIICPS_EVENT_ERROR 0x0008
#define	XIICPS_EVENT_ARB_LOST 0x0010
#define	XIICPS_EVENT_NACK 0x0020
#define	XIICPS_EVENT_SLAVE_RDY 0x0040
#define	XIICPS_EVENT_RX_OVR 0x0080
#define	XIICPS_EVENT_TX_OVR 0x0100
#define	XIICPS_EVENT_RX_UNF 0x0200
Role constants
These constants are used to pass into the device setup routines to set up the device according to transfer direction.
#define	SENDING_ROLE 1
#define	RECVING_ROLE 0
#define	XIICPS_MAX_TRANSFER_SIZE (255 - 3)
#define	XIicPs_SendByte(InstancePtr)
#define	XIicPs_RecvByte(InstancePtr)
typedef void(*	XIicPs_IntrHandler )(void *CallBackRef, u32 StatusEvent)
XIicPs_Config *	XIicPs_LookupConfig (u16 DeviceId)
int	XIicPs_CfgInitialize (XIicPs InstancePtr, XIicPs_Config Config, u32 EffectiveAddr)
void	XIicPs_Abort (XIicPs *InstancePtr)
void	XIicPs_Reset (XIicPs *InstancePtr)
int	XIicPs_BusIsBusy (XIicPs *InstancePtr)
void	XIicPs_SetStatusHandler (XIicPs InstancePtr, void CallBackRef, XIicPs_IntrHandler FuncPtr)
void	XIicPs_MasterSend (XIicPs InstancePtr, u8 MsgPtr, int ByteCount, u16 SlaveAddr)
void	XIicPs_MasterRecv (XIicPs InstancePtr, u8 MsgPtr, int ByteCount, u16 SlaveAddr)
int	XIicPs_MasterSendPolled (XIicPs InstancePtr, u8 MsgPtr, int ByteCount, u16 SlaveAddr)
int	XIicPs_MasterRecvPolled (XIicPs InstancePtr, u8 MsgPtr, int ByteCount, u16 SlaveAddr)
void	XIicPs_EnableSlaveMonitor (XIicPs *InstancePtr, u16 SlaveAddr)
void	XIicPs_DisableSlaveMonitor (XIicPs *InstancePtr)
void	XIicPs_MasterInterruptHandler (XIicPs *InstancePtr)
void	XIicPs_SetupSlave (XIicPs *InstancePtr, u16 SlaveAddr)
void	XIicPs_SlaveSend (XIicPs InstancePtr, u8 MsgPtr, int ByteCount)
void	XIicPs_SlaveRecv (XIicPs InstancePtr, u8 MsgPtr, int ByteCount)
int	XIicPs_SlaveSendPolled (XIicPs InstancePtr, u8 MsgPtr, int ByteCount)
int	XIicPs_SlaveRecvPolled (XIicPs InstancePtr, u8 MsgPtr, int ByteCount)
void	XIicPs_SlaveInterruptHandler (XIicPs *InstancePtr)
int	XIicPs_SelfTest (XIicPs *InstancePtr)
int	XIicPs_SetOptions (XIicPs *InstancePtr, u32 Options)
int	XIicPs_ClearOptions (XIicPs *InstancePtr, u32 Options)
u32	XIicPs_GetOptions (XIicPs *InstancePtr)
int	XIicPs_SetSClk (XIicPs *InstancePtr, u32 FsclHz)
u32	XIicPs_GetSClk (XIicPs *InstancePtr)

Detailed Description

Define Documentation

#define RECVING_ROLE 0

Transfer direction is receiving

#define SENDING_ROLE 1

Transfer direction is sending

#define XIICPS_10_BIT_ADDR_OPTION 0x02

10-bit address mode

#define XIICPS_7_BIT_ADDR_OPTION 0x01

7-bit address mode

#define XIICPS_EVENT_ARB_LOST 0x0010

Arbitration lost

#define XIICPS_EVENT_COMPLETE_RECV 0x0002

Receive Complete Event

#define XIICPS_EVENT_COMPLETE_SEND 0x0001

Transmit Complete Event

#define XIICPS_EVENT_ERROR 0x0008

Receive error

#define XIICPS_EVENT_NACK 0x0020

NACK Received

#define XIICPS_EVENT_RX_OVR 0x0080

RX overflow

#define XIICPS_EVENT_RX_UNF 0x0200

RX underflow

#define XIICPS_EVENT_SLAVE_RDY 0x0040

Slave ready

#define XIICPS_EVENT_TIME_OUT 0x0004

Transfer timed out

#define XIICPS_EVENT_TX_OVR 0x0100

TX overflow

#define XIICPS_H

#define XIICPS_MAX_TRANSFER_SIZE (255 - 3)

#define XIicPs_RecvByte ( InstancePtr )

Value:

{                                                                       \
        *(InstancePtr)->RecvBufferPtr ++ =                              \
         (u8)XIicPs_In32((InstancePtr)->Config.BaseAddress              \
                  + XIICPS_DATA_OFFSET);                                \
         (InstancePtr)->RecvByteCount --;                               \
}

#define XIICPS_REP_START_OPTION 0x08

Repeated Start

#define XIicPs_SendByte ( InstancePtr )

Value:

{                                                                       \
         XIicPs_Out32((InstancePtr)->Config.BaseAddress                 \
                         + XIICPS_DATA_OFFSET,                          \
        *(InstancePtr)->SendBufferPtr ++);                              \
         (InstancePtr)->SendByteCount --;                               \
}

#define XIICPS_SLAVE_MON_OPTION 0x04

Slave monitor mode

Typedef Documentation

typedef void(* XIicPs_IntrHandler)(void *CallBackRef, u32 StatusEvent)

The handler data type allows the user to define a callback function to respond to interrupt events in the system. This function is executed in interrupt context, so amount of processing should be minimized.

Parameters:

	CallBackRef	is the callback reference passed in by the upper layer when setting the callback functions, and passed back to the upper layer when the callback is invoked. Its type is not important to the driver, so it is a void pointer.
	StatusEvent	indicates one or more status events that occurred.

Function Documentation

void XIicPs_Abort ( XIicPs * InstancePtr )

Aborts a transfer in progress by resetting the FIFOs. The byte counts are cleared.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: None.

Note:: None.

int XIicPs_BusIsBusy ( XIicPs * InstancePtr )

Check whether the I2C bus is busy

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:

TRUE if the bus is busy.
FALSE if the bus is not busy.

Note:: None.

int XIicPs_CfgInitialize	(	XIicPs *	InstancePtr,
		XIicPs_Config *	ConfigPtr,
		u32	EffectiveAddr
	)

Initializes a specific XIicPs instance such that the driver is ready to use.

The state of the device after initialization is:

Device is disabled
Slave mode

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	ConfigPtr	is a reference to a structure containing information about a specific IIC device. This function initializes an InstancePtr object for a specific device specified by the contents of Config.
	EffectiveAddr	is the device base address in the virtual memory address space. The caller is responsible for keeping the address mapping from EffectiveAddr to the device physical base address unchanged once this function is invoked. Unexpected errors may occur if the address mapping changes after this function is called. If address translation is not used, use ConfigPtr->BaseAddress for this parameter, passing the physical address instead.

Returns:: The return value is XST_SUCCESS if successful.

Note:: None.

int XIicPs_ClearOptions	(	XIicPs *	InstancePtr,
		u32	Options
	)

This function clears the options for the IIC device driver. The options control how the device behaves relative to the IIC bus. The device must be idle rather than busy transferring data before setting these device options.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	Options	contains the specified options to be cleared. This is a bit mask where a 1 means to turn the option off. One or more bit values may be contained in the mask. See the bit definitions named XIICPS_*_OPTION in xiicps.h.

Returns:

XST_SUCCESS if options are successfully set.
XST_DEVICE_IS_STARTED if the device is currently transferring data. The transfer must complete or be aborted before setting options.

Note:: None

void XIicPs_DisableSlaveMonitor ( XIicPs * InstancePtr )

This function disables slave monitor mode.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: None.

Note:: None.

void XIicPs_EnableSlaveMonitor	(	XIicPs *	InstancePtr,
		u16	SlaveAddr
	)

This function enables the slave monitor mode.

It enables slave monitor in the control register and enables slave ready interrupt. It then does an address transfer to slave. Interrupt handler will signal the caller if slave responds to the address transfer.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	SlaveAddr	is the address of the slave we want to contact.

Returns:: None.

Note:: None.

u32 XIicPs_GetOptions ( XIicPs * InstancePtr )

This function gets the options for the IIC device. The options control how the device behaves relative to the IIC bus.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: 32 bit mask of the options, where a 1 means the option is on, and a 0 means to the option is off. One or more bit values may be contained in the mask. See the bit definitions named XIICPS_*_OPTION in the file xiicps.h.

Note:: None.

u32 XIicPs_GetSClk ( XIicPs * InstancePtr )

This function gets the serial clock rate for the IIC device. The device must be idle rather than busy transferring data before setting these device options.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: The value of the IIC clock to the nearest Hz based on the control register settings. The actual value may not be exact to to integer math rounding errors.

Note:: None.

XIicPs_Config* XIicPs_LookupConfig ( u16 DeviceId )

Looks up the device configuration based on the unique device ID. A table contains the configuration info for each device in the system.

Parameters:

DeviceId

contains the ID of the device to look up the configuration for.

Returns:: A pointer to the configuration found or NULL if the specified device ID was not found. See xiicps.h for the definition of XIicPs_Config.

Note:: None.

void XIicPs_MasterInterruptHandler ( XIicPs * InstancePtr )

The interrupt handler for the master mode. It does the protocol handling for the interrupt-driven transfers.

Completion events and errors are signaled to upper layer for proper handling.

The interrupts that are handled are:

DATA This case is handled only for master receive data. The master has to request for more data (if there is more data to receive) and read the data from the FIFO .


COMP
	If the Master is transmitting data and there is more data to be
	sent then the data is written to the FIFO. If there is no more data to
	be transmitted then a completion event is signalled to the upper layer
	by calling the callback handler.

	If the Master is receiving data then the data is read from the FIFO and
	the Master has to request for more data (if there is more data to
	receive). If all the data has been received then a completion event
	is signalled to the upper layer by calling the callback handler.
	It is an error if the amount of received data is more than expected.


NAK and SLAVE_RDY
	This is signalled to the upper layer by calling the callback handler.


All Other interrupts
	These interrupts are marked as error. This is signalled to the upper
	layer by calling the callback handler.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: None.

Note:: None.

void XIicPs_MasterRecv	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount,
		u16	SlaveAddr
	)

This function initiates an interrupt-driven receive in master mode.

It sets the transfer size register so the slave can send data to us. The rest of the work is managed by interrupt handler.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the receive buffer.
	ByteCount	is the number of bytes to be received.
	SlaveAddr	is the address of the slave we are receiving from.

Returns:: None.

Note:: This receive routine is for interrupt-driven transfer only.

int XIicPs_MasterRecvPolled	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount,
		u16	SlaveAddr
	)

This function initiates a polled mode receive in master mode.

It repeatedly sets the transfer size register so the slave can send data to us. It polls the data register for data to come in. If slave fails to send us data, it fails with time out.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the receive buffer.
	ByteCount	is the number of bytes to be received.
	SlaveAddr	is the address of the slave we are receiving from.

Returns:

XST_SUCCESS if everything went well.
XST_FAILURE if timed out.

Note:: This receive routine is for polled mode transfer only.

void XIicPs_MasterSend	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount,
		u16	SlaveAddr
	)

This function initiates an interrupt-driven send in master mode.

It tries to send the first FIFO-full of data, then lets the interrupt handler to handle the rest of the data if there is any.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the send buffer.
	ByteCount	is the number of bytes to be sent.
	SlaveAddr	is the address of the slave we are sending to.

Returns:: None.

Note:: This send routine is for interrupt-driven transfer only.

int XIicPs_MasterSendPolled	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount,
		u16	SlaveAddr
	)

This function initiates a polled mode send in master mode.

It sends data to the FIFO and waits for the slave to pick them up. If slave fails to remove data from FIFO, the send fails with time out.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the send buffer.
	ByteCount	is the number of bytes to be sent.
	SlaveAddr	is the address of the slave we are sending to.

Returns:

XST_SUCCESS if everything went well.
XST_FAILURE if timed out.

Note:: This send routine is for polled mode transfer only.

void XIicPs_Reset ( XIicPs * InstancePtr )

Resets the IIC device. Reset must only be called after the driver has been initialized. The configuration of the device after reset is the same as its configuration after initialization. Any data transfer that is in progress is aborted.

The upper layer software is responsible for re-configuring (if necessary) and reenabling interrupts for the IIC device after the reset.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: None.

Note:: None.

int XIicPs_SelfTest ( XIicPs * InstancePtr )

Runs a self-test on the driver/device. The self-test is destructive in that a reset of the device is performed in order to check the reset values of the registers and to get the device into a known state.

Upon successful return from the self-test, the device is reset.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:

XST_SUCCESS if successful.
XST_REGISTER_ERROR indicates a register did not read or write correctly

Note:: None.

int XIicPs_SetOptions	(	XIicPs *	InstancePtr,
		u32	Options
	)

This function sets the options for the IIC device driver. The options control how the device behaves relative to the IIC bus. The device must be idle rather than busy transferring data before setting these device options.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	Options	contains the specified options to be set. This is a bit mask where a 1 means to turn the option on. One or more bit values may be contained in the mask. See the bit definitions named XIICPS_*_OPTION in xiicps.h.

Returns:

XST_SUCCESS if options are successfully set.
XST_DEVICE_IS_STARTED if the device is currently transferring data. The transfer must complete or be aborted before setting options.

Note:: None.

int XIicPs_SetSClk	(	XIicPs *	InstancePtr,
		u32	FsclHz
	)

This function sets the serial clock rate for the IIC device. The device must be idle rather than busy transferring data before setting these device options.

The data rate is set by values in the control register. The formula for determining the correct register values is: Fscl = Fpclk/(22 x (divisor_a+1) x (divisor_b+1)) See the hardware data sheet for a full explanation of setting the serial clock rate.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	FsclHz	is the clock frequency in Hz. The two most common clock rates are 100KHz and 400KHz.

Returns:

XST_SUCCESS if options are successfully set.
XST_DEVICE_IS_STARTED if the device is currently transferring data. The transfer must complete or be aborted before setting options.
XST_FAILURE if the Fscl frequency can not be set.

Note:: The clock can not be faster than the input clock divide by 22.

void XIicPs_SetStatusHandler	(	XIicPs *	InstancePtr,
		void *	CallBackRef,
		XIicPs_IntrHandler	FuncPtr
	)

This function sets the status callback function, the status handler, which the driver calls when it encounters conditions that should be reported to the higher layer software. The handler executes in an interrupt context, so the amount of processing should be minimized

Refer to the xiicps.h file for a list of the Callback events. The events are defined to start with XIICPS_EVENT_*.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	CallBackRef	is the upper layer callback reference passed back when the callback function is invoked.
	FuncPtr	is the pointer to the callback function.

Returns:: None.

Note:

The handler is called within interrupt context, so it should finish its work quickly.

void XIicPs_SetupSlave	(	XIicPs *	InstancePtr,
		u16	SlaveAddr
	)

This function sets up the device to be a slave.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	SlaveAddr	is the address of the slave we are receiving from.

Returns:: None.

Note:: Interrupt is always enabled no matter the tranfer is interrupt- driven or polled mode. Whether device will be interrupted or not depends on whether the device is connected to an interrupt controller and interrupt for the device is enabled.

void XIicPs_SlaveInterruptHandler ( XIicPs * InstancePtr )

The interrupt handler for slave mode. It does the protocol handling for the interrupt-driven transfers.

Completion events and errors are signaled to upper layer for proper handling.

The interrupts that are handled are:

DATA If the instance is sending, it means that the master wants to read more data from us. Send more data, and check whether we are done with this send.

	If the instance is receiving, it means that the master has writen
	more data to us. Receive more data, and check whether we are done with
	with this receive.


COMP
	This marks that stop sequence has been sent from the master, transfer
	is about to terminate. However, for receiving, the master may have
	written us some data, so receive that first.

	It is an error if the amount of transfered data is less than expected.


NAK
	This marks that master does not want our data. It is for send only.


Other interrupts
	These interrupts are marked as error.

Parameters:

InstancePtr

is a pointer to the XIicPs instance.

Returns:: None.

Note:: None.

void XIicPs_SlaveRecv	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount
	)

This function setup a slave interrupt-driven receive. Data processing for the receive is handled by the interrupt handler.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the receive buffer.
	ByteCount	is the number of bytes to be received.

Returns:: None.

Note:: This routine is for interrupt-driven transfer only.

int XIicPs_SlaveRecvPolled	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount
	)

This function receives a buffer in polled mode as a slave.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the receive buffer.
	ByteCount	is the number of bytes to be received.

Returns:

XST_SUCCESS if everything went well.
XST_FAILURE if timed out.

Note:: This receive routine is for polled mode transfer only.

void XIicPs_SlaveSend	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount
	)

This function setup a slave interrupt-driven send. It set the repeated start for the device is the tranfer size is larger than FIFO depth. Data processing for the send is initiated by the interrupt handler.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the send buffer.
	ByteCount	is the number of bytes to be sent.

Returns:: None.

Note:: This send routine is for interrupt-driven transfer only.

int XIicPs_SlaveSendPolled	(	XIicPs *	InstancePtr,
		u8 *	MsgPtr,
		int	ByteCount
	)

This function sends a buffer in polled mode as a slave.

Parameters:

	InstancePtr	is a pointer to the XIicPs instance.
	MsgPtr	is the pointer to the send buffer.
	ByteCount	is the number of bytes to be sent.

Returns:

XST_SUCCESS if everything went well.
XST_FAILURE if master sends us data or master terminates the transfer before all data has sent out.

Note:: This send routine is for polled mode transfer only.

Xilinx Processor IP Library

xiicps.h File Reference

Classes

Defines

Role constants

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation