This file contains the implementation of the XSpiPs driver. It works for both the master and slave mode. User documentation for the driver functions is contained in this file in the form of comment blocks at the front of each function.
An SPI device connects to an SPI bus through a 4-wire serial interface. The SPI bus is a full-duplex, synchronous bus that facilitates communication between one master and one slave. The device is always full-duplex, which means that for every byte sent, one is received, and vice-versa. The master controls the clock, so it can regulate when it wants to send or receive data. The slave is under control of the master, it must respond quickly since it has no control of the clock and must send/receive data as fast or as slow as the master does.
Initialization & Configuration
The XSpiPs_Config structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.
To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in the following way:
Multiple Masters
More than one master can exist, but arbitration is the responsibility of the higher layer software. The device driver does not perform any type of arbitration.
Multiple Slaves
Contention between multiple masters is detected by the hardware, in which case a mode fault occurs on the device. The device is disabled immediately by hardware, and the current word transfer is stopped. The Aborted word transfer due to the mode fault is resumed once the devie is enabled again.
Modes of Operation
There are four modes to perform a data transfer and the selection of a mode is based on Chip Select(CS) and Start. These two options individually, can be controlled either by software(Manual) or hardware(Auto).
The preferred combination is Manual CS and Auto Start. In this combination, the software asserts CS before loading any data into TXFIFO. In Auto Start mode, whenever data is in TXFIFO, controller sends it out until TXFIFO becomes empty. The software reads the RXFIFO whenever the data is available. If no further data, software disables CS.
Risks/challenges of other combinations:
Interrupts
The user must connect the interrupt handler of the driver, XSpiPs_InterruptHandler, to an interrupt system such that it will be called when an interrupt occurs. This function does not save and restore the processor context such that the user must provide this processing.
The driver handles the following interrupts:
The Data Transmit Register/FIFO Overwater interrupt -- indicates that the SPI device has transmitted the data available to transmit, and now its data register and FIFO is ready to accept more data. The driver uses this interrupt to indicate progress while sending data. The driver may have more data to send, in which case the data transmit register and FIFO is filled for subsequent transmission. When this interrupt arrives and all the data has been sent, the driver invokes the status callback with a value of XST_SPI_TRANSFER_DONE to inform the upper layer software that all data has been sent.
The Data Transmit Register/FIFO Underflow interrupt -- indicates that, as slave, the SPI device was required to transmit but there was no data available to transmit in the transmit register (or FIFO). This may not be an error if the master is not expecting data. But in the case where the master is expecting data, this serves as a notification of such a condition. The driver reports this condition to the upper layer software through the status handler.
The Data Receive Register/FIFO Overrun interrupt -- indicates that the SPI device received data and subsequently dropped the data because the data receive register and FIFO was full. The interrupt applies to both master and slave operation. The driver reports this condition to the upper layer software through the status handler. This likely indicates a problem with the higher layer protocol, or a problem with the slave performance.
The Mode Fault Error interrupt -- indicates that while configured as a master, the device was selected as a slave by another master. This can be used by the application for arbitration in a multimaster environment or to indicate a problem with arbitration. When this interrupt occurs, the driver invokes the status callback with a status value of XST_SPI_MODE_FAULT. It is up to the application to resolve the conflict. When configured as a slave, Mode Fault Error interrupt indicates that a slave device was selected as a slave by a master, but the slave device was disabled. When configured as a master, Mode Fault Error interrupt indicates that another SPI device is acting as a master on the bus.
Polled Operation
Transfer in polled mode is supported through a separate interface function XSpiPs_PolledTransfer(). Unlike the transfer function in the interrupt mode, this function blocks until all data has been sent/received.
Device Busy
Some operations are disallowed when the device is busy. The driver tracks whether a device is busy. The device is considered busy when a data transfer request is outstanding, and is considered not busy only when that transfer completes (or is aborted with a mode fault error). This applies to both master and slave devices.
Device Configuration
The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the xspips_g.c file or passed in via XSpiPs_CfgInitialize(). A table is defined where each entry contains configuration information for an SPI device, including the base address for the device.
RTOS Independence
This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.
MODIFICATION HISTORY:
Ver Who Date Changes
----- ------ -------- -----------------------------------------------
1.00 drg/jz 01/25/10 First release
1.00 sdm 10/25/11 Removed the Divide by 2 in the SPI Clock Prescaler
options as this is not supported in the device.
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.02 sg 05/31/12 Updated XSPIPS_FIFO_DEPTH to 128 from 32 to match HW
for CR 658289
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 Created XSPIPS_MANUAL_START_OPTION. Created macros
XSpiPs_IsMaster, XSpiPs_IsManualStart and
XSpiPs_IsManualChipSelect. Changed SPI
Enable/Disable macro argument from BaseAddress to
Instance Pointer. Added DelayNss argument to SetDelays
and GetDelays API's. Added macros to set/get the
RX Watermark value.Created macros XSpiPs_IsMaster,
XSpiPs_IsManualStart and XSpiPs_IsManualChipSelect.
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.
Created XSPIPS_CR_MODF_GEN_EN_MASK macro and added it
to XSPIPS_CR_RESET_STATE. Created
XSPIPS_IXR_WR_TO_CLR_MASK for interrupts which need
write-to-clear. Added shift and mask macros for d_nss
parameter. Added Rx Watermark mask.
1.05a hk 26/04/13 Added disable and enable in XSpiPs_SetOptions when
CPOL/CPHA bits are set/reset. Fix for CR#707669.
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 prototypes of reset API and related constant
definitions.
Added check for MODF in polled transfer function.Copyright © 1995-2014 Xilinx, Inc. All rights reserved.