Xilinx Processor IP Library

Software Drivers

xspips.c File Reference

#include "xspips.h"

Defines

#define XSpiPs_SendByte(BaseAddress, Data)   XSpiPs_Out32((BaseAddress) + XSPIPS_TXD_OFFSET, (Data))
#define XSpiPs_RecvByte(BaseAddress)   (u8)XSpiPs_In32((BaseAddress) + XSPIPS_RXD_OFFSET)

Functions

int XSpiPs_CfgInitialize (XSpiPs *InstancePtr, XSpiPs_Config *ConfigPtr, u32 EffectiveAddr)
void XSpiPs_Reset (XSpiPs *InstancePtr)
int XSpiPs_Transfer (XSpiPs *InstancePtr, u8 *SendBufPtr, u8 *RecvBufPtr, unsigned ByteCount)
int XSpiPs_PolledTransfer (XSpiPs *InstancePtr, u8 *SendBufPtr, u8 *RecvBufPtr, unsigned ByteCount)
int XSpiPs_SetSlaveSelect (XSpiPs *InstancePtr, u8 SlaveSel)
u8 XSpiPs_GetSlaveSelect (XSpiPs *InstancePtr)
void XSpiPs_SetStatusHandler (XSpiPs *InstancePtr, void *CallBackRef, XSpiPs_StatusHandler FuncPtr)
void XSpiPs_InterruptHandler (void *InstancePtr)
void XSpiPs_Abort (XSpiPs *InstancePtr)

Detailed Description

Contains implements the interface functions of the XSpiPs driver. See xspips.h for a detailed description of the device and driver.

 MODIFICATION HISTORY:
 Ver   Who    Date     Changes
 ----- ------ -------- -----------------------------------------------
 1.00  drg/jz 01/25/10 First release
 1.01	sg     03/07/12 Updated the code to always clear the relevant bits
			before writing to config register.
			Always clear the slave select bits before write and
			clear the bits to no slave at the end of transfer
			Modified the Polled transfer transmit/receive logic.
			Tx should wait on TXOW Interrupt and Rx on RXNEMTY.
 1.03	sg     09/21/12 Added memory barrier dmb in polled transfer and
			interrupt handler to overcome the clock domain
			crossing issue in the controller. For CR #679252.
 1.04a	sg     01/30/13 Changed SPI transfer logic for polled and interrupt
			modes to be based on filled tx fifo count and receive
			based on it. RXNEMPTY interrupt is not used.
			SetSlaveSelect API logic is modified to drive the bit
			position low based on the slave select value
			requested. GetSlaveSelect API will return the value
			based on bit position that is low.
 1.06a hk     08/22/13 Changed GetSlaveSelect function. CR# 727866.
                       Added masking ConfigReg before writing in SetSlaveSel
                       Added extended slave select support - CR#722569.
                       Added check for MODF in polled transfer function.

Define Documentation

#define XSpiPs_RecvByte ( BaseAddress   )     (u8)XSpiPs_In32((BaseAddress) + XSPIPS_RXD_OFFSET)
#define XSpiPs_SendByte ( BaseAddress,
Data   )     XSpiPs_Out32((BaseAddress) + XSPIPS_TXD_OFFSET, (Data))

Function Documentation

void XSpiPs_Abort ( XSpiPs *  InstancePtr  ) 

Aborts a transfer in progress by disabling the device and resetting the FIFOs if present. The byte counts are cleared, the busy flag is cleared, and mode fault is cleared.

Parameters:
InstancePtr is a pointer to the XSpiPs instance.
Returns:
None.
Note:

This function does a read/modify/write of the Config register. The user of this function needs to take care of critical sections.

int XSpiPs_CfgInitialize ( XSpiPs *  InstancePtr,
XSpiPs_Config *  ConfigPtr,
u32  EffectiveAddr 
)

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

The state of the device after initialization is:

  • Device is disabled
  • Slave mode
  • Active high clock polarity
  • Clock phase 0
Parameters:
InstancePtr is a pointer to the XSpiPs instance.
ConfigPtr is a reference to a structure containing information about a specific SPI device. This function initializes an InstancePtr object for a specific device specified by the contents of Config. This function can initialize multiple instance objects with the use of multiple calls giving different Config information on each call.
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->Config.BaseAddress for this device.
Returns:
  • XST_SUCCESS if successful.
  • XST_DEVICE_IS_STARTED if the device is already started. It must be stopped to re-initialize.
Note:
None.
u8 XSpiPs_GetSlaveSelect ( XSpiPs *  InstancePtr  ) 

Gets the current slave select setting for the SPI device.

Parameters:
InstancePtr is a pointer to the XSpiPs instance.
Returns:
The slave number selected (starting from 0).
Note:
None.
void XSpiPs_InterruptHandler ( void *  InstancePtr  ) 

The interrupt handler for SPI interrupts. This function must be connected by the user to an interrupt controller.

The interrupts that are handled are:

  • Mode Fault Error. This interrupt is generated if this device is selected as a slave when it is configured as a master. The driver aborts any data transfer that is in progress by resetting FIFOs (if present) and resetting its buffer pointers. The upper layer software is informed of the error.
  • Data Transmit Register (FIFO) Empty. This interrupt is generated when the transmit register or FIFO is empty. The driver uses this interrupt during a transmission to continually send/receive data until the transfer is done.
  • Data Transmit Register (FIFO) Underflow. This interrupt is generated when the SPI device, when configured as a slave, attempts to read an empty DTR/FIFO. An empty DTR/FIFO usually means that software is not giving the device data in a timely manner. No action is taken by the driver other than to inform the upper layer software of the error.
  • Data Receive Register (FIFO) Overflow. This interrupt is generated when the SPI device attempts to write a received byte to an already full DRR/FIFO. A full DRR/FIFO usually means software is not emptying the data in a timely manner. No action is taken by the driver other than to inform the upper layer software of the error.
  • Slave Mode Fault Error. This interrupt is generated if a slave device is selected as a slave while it is disabled. No action is taken by the driver other than to inform the upper layer software of the error.
Parameters:
InstancePtr is a pointer to the XSpiPs instance.
Returns:
None.
Note:

The slave select register is being set to deselect the slave when a transfer is complete. This is being done regardless of whether it is a slave or a master since the hardware does not drive the slave select as a slave.

int XSpiPs_PolledTransfer ( XSpiPs *  InstancePtr,
u8 *  SendBufPtr,
u8 *  RecvBufPtr,
unsigned  ByteCount 
)

Transfers specified data on the SPI bus in polled mode.

The caller has the option of providing two different buffers for send and receive, or one buffer for both send and receive, or no buffer for receive. The receive buffer must be at least as big as the send buffer to prevent unwanted memory writes. This implies that the byte count passed in as an argument must be the smaller of the two buffers if they differ in size. Here are some sample usages: 

   XSpiPs_PolledTransfer(InstancePtr, SendBuf, RecvBuf, ByteCount)
	The caller wishes to send and receive, and provides two different
	buffers for send and receive.
   XSpiPs_PolledTransfer(InstancePtr, SendBuf, NULL, ByteCount)
	The caller wishes only to send and does not care about the received
	data. The driver ignores the received data in this case.
   XSpiPs_PolledTransfer(InstancePtr, SendBuf, SendBuf, ByteCount)
	The caller wishes to send and receive, but provides the same buffer
	for doing both. The driver sends the data and overwrites the send
	buffer with received data as it transfers the data.
   XSpiPs_PolledTransfer(InstancePtr, RecvBuf, RecvBuf, ByteCount)
	The caller wishes to only receive and does not care about sending
	data.  In this case, the caller must still provide a send buffer, but
	it can be the same as the receive buffer if the caller does not care
	what it sends.  The device must send N bytes of data if it wishes to
	receive N bytes of data.
Parameters:
InstancePtr is a pointer to the XSpiPs instance.
SendBufPtr is a pointer to a buffer of data for sending. This buffer must not be NULL.
RecvBufPtr is a pointer to a buffer for received data. This argument can be NULL if do not care about receiving.
ByteCount contains the number of bytes to send/receive. The number of bytes received always equals the number of bytes sent.
Returns:
  • XST_SUCCESS if the buffers are successfully handed off to the device for transfer.
  • XST_DEVICE_BUSY indicates that a data transfer is already in progress. This is determined by the driver.
Note:

This function is not thread-safe. The higher layer software must ensure that no two threads are transferring data on the SPI bus at the same time.

void XSpiPs_Reset ( XSpiPs *  InstancePtr  ) 

Resets the SPI 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 restarting the SPI device after the reset.

Parameters:
InstancePtr is a pointer to the XSpiPs instance.
Returns:
None.
Note:
None.
int XSpiPs_SetSlaveSelect ( XSpiPs *  InstancePtr,
u8  SlaveSel 
)

Selects or deselect the slave with which the master communicates. This setting affects the SPI_ss_outN signals. The behavior depends on the setting of the CR_SSDECEN bit. If CR_SSDECEN is 0, the SPI_ss_outN bits will be output with a single signal low. If CR_SSDECEN is 1, the SPI_ss_outN bits will reflect the value set.

The user is not allowed to deselect the slave while a transfer is in progress. If no transfer is in progress, the user can select a new slave, which implicitly deselects the current slave. In order to explicitly deselect the current slave, a value of all 1's, 0x0F can be passed in as the argument to the function.

Parameters:
InstancePtr is a pointer to the XSpiPs instance.
SlaveSel is the slave number to be selected. Normally, 3 slaves can be selected with values 0-2. In case, 3-8 decode option is set, then upto 8 slaves can be selected. Only one slave can be selected at a time.
Returns:
  • XST_SUCCESS if the slave is selected or deselected successfully.
  • XST_DEVICE_BUSY if a transfer is in progress, slave cannot be changed.
Note:

This function only sets the slave which will be selected when a transfer occurs. The slave is not selected when the SPI is idle. The slave select has no affect when the device is configured as a slave.

void XSpiPs_SetStatusHandler ( XSpiPs *  InstancePtr,
void *  CallBackRef,
XSpiPs_StatusHandler  FuncPtr 
)

Sets the status callback function, the status handler, which the driver calls when it encounters conditions that should be reported to upper layer software. The handler executes in an interrupt context, so it must minimize the amount of processing performed. One of the following status events is passed to the status handler.

 XST_SPI_MODE_FAULT		A mode fault error occurred, meaning the device
				is selected as slave while being a master.
 XST_SPI_TRANSFER_DONE		The requested data transfer is done
 XST_SPI_TRANSMIT_UNDERRUN	As a slave device, the master clocked data
				but there were none available in the transmit
				register/FIFO. This typically means the slave
				application did not issue a transfer request
				fast enough, or the processor/driver could not
				fill the transmit register/FIFO fast enough.
 XST_SPI_RECEIVE_OVERRUN	The SPI device lost data. Data was received
				but the receive data register/FIFO was full.
 XST_SPI_SLAVE_MODE_FAULT	A slave SPI device was selected as a slave
				while it was disabled. This indicates the
				master is already transferring data (which is
				being dropped until the slave application
				issues a transfer).
Parameters:
InstancePtr is a pointer to the XSpiPs 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 do its work quickly and queue potentially time-consuming work to a task-level thread.

int XSpiPs_Transfer ( XSpiPs *  InstancePtr,
u8 *  SendBufPtr,
u8 *  RecvBufPtr,
unsigned  ByteCount 
)

Transfers specified data on the SPI bus. If the SPI device is configured as a master, this function initiates bus communication and sends/receives the data to/from the selected SPI slave. If the SPI device is configured as a slave, this function prepares the buffers to be sent/received when selected by a master. For every byte sent, a byte is received. This function should be used to perform interrupt based transfers.

The caller has the option of providing two different buffers for send and receive, or one buffer for both send and receive, or no buffer for receive. The receive buffer must be at least as big as the send buffer to prevent unwanted memory writes. This implies that the byte count passed in as an argument must be the smaller of the two buffers if they differ in size. Here are some sample usages: 

   XSpiPs_Transfer(InstancePtr, SendBuf, RecvBuf, ByteCount)
	The caller wishes to send and receive, and provides two different
	buffers for send and receive.
   XSpiPs_Transfer(InstancePtr, SendBuf, NULL, ByteCount)
	The caller wishes only to send and does not care about the received
	data. The driver ignores the received data in this case.
   XSpiPs_Transfer(InstancePtr, SendBuf, SendBuf, ByteCount)
	The caller wishes to send and receive, but provides the same buffer
	for doing both. The driver sends the data and overwrites the send
	buffer with received data as it transfers the data.
   XSpiPs_Transfer(InstancePtr, RecvBuf, RecvBuf, ByteCount)
	The caller wishes to only receive and does not care about sending
	data.  In this case, the caller must still provide a send buffer, but
	it can be the same as the receive buffer if the caller does not care
	what it sends.  The device must send N bytes of data if it wishes to
	receive N bytes of data.

Although this function takes entire buffers as arguments, the driver can only transfer a limited number of bytes at a time, limited by the size of the FIFO. A call to this function only starts the transfer, then subsequent transfers of the data is performed by the interrupt service routine until the entire buffer has been transferred. The status callback function is called when the entire buffer has been sent/received.

This function is non-blocking. As a master, the SetSlaveSelect function must be called prior to this function.

Parameters:
InstancePtr is a pointer to the XSpiPs instance.
SendBufPtr is a pointer to a buffer of data for sending. This buffer must not be NULL.
RecvBufPtr is a pointer to a buffer for received data. This argument can be NULL if do not care about receiving.
ByteCount contains the number of bytes to send/receive. The number of bytes received always equals the number of bytes sent.
Returns:
  • XST_SUCCESS if the buffers are successfully handed off to the device for transfer.
  • XST_DEVICE_BUSY indicates that a data transfer is already in progress. This is determined by the driver.
Note:

This function is not thread-safe. The higher layer software must ensure that no two threads are transferring data on the SPI bus at the same time.

Copyright © 1995-2014 Xilinx, Inc. All rights reserved.