<h1>spi v4_1</h1><p>This component contains the implementation of the <aclass="el"href="struct_x_spi.html">XSpi</a> component. It is the driver for an SPI master or slave device. It supports 8-bit, 16-bit and 32-bit wide data transfers.</p>
<p>SPI is a 4-wire serial interface. It 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.</p>
<p>The application software between master and slave must implement a higher layer protocol so that slaves know what to transmit to the master and when.</p>
<p><b>Initialization & Configuration</b></p>
<p>The <aclass="el"href="struct_x_spi___config.html">XSpi_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on HW build properties.</p>
<p>To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized in one of the following ways:</p>
<li>XSpi_Initialize(InstancePtr, DeviceId) - The driver looks up its own configuration structure created by the tool-chain based on an ID provided by the tool-chain.</li>
<li>XSpi_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddr) - Uses a configuration structure provided by the caller. If running in a system with address translation, the provided virtual memory base address replaces the physical address present in the configuration structure.</li>
</ul>
<p><b>Multiple Masters</b></p>
<p>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.</p>
<p><b>Multiple Slaves</b></p>
<p>Multiple slaves are supported by adding additional slave select (SS) signals to each device, one for each slave on the bus. The driver ensures that only one slave can be selected at any one time.</p>
<p><b>FIFOs</b></p>
<p>The SPI hardware is parameterized such that it can be built with or without FIFOs. When using FIFOs, both send and receive must have FIFOs. The driver will not function correctly if one direction has a FIFO but the other direction does not. The frequency of the interrupts which occur is proportional to the data rate such that high data rates without the FIFOs could cause the software to consume large amounts of processing time. The driver is designed to work with or without the FIFOs.</p>
<p><b>Interrupts</b></p>
<p>The user must connect the interrupt handler of the driver, XSpi_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.</p>
<p>The driver handles the following interrupts:</p>
<ul>
<li>Data Transmit Register/FIFO Empty</li>
<li>Data Transmit FIFO Half Empty</li>
<li>Data Transmit Register/FIFO Underrun</li>
<li>Data Receive Register/FIFO Overrun</li>
<li>Mode Fault Error</li>
<li>Slave Mode Fault Error</li>
<li>Slave Mode Select</li>
<li>Data Receive FIFO not Empty</li>
</ul>
<p>The Data Transmit Register/FIFO Empty interrupt indicates that the SPI device has transmitted all the data available to transmit, and now its data register (or FIFO) is empty. 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 (or 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.</p>
<p>The Data Transmit FIFO Half Empty interrupt indicates that the SPI device has transmitted half of the data available, in the FIFO, to transmit. 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 FIFO is filled for subsequent transmission. This interrupt is particualrly useful in slave mode, while transfering more than FIFO_DEPTH number of bytes. In this case, the driver ensures that the FIFO is never empty during a transfer and avoids master receiving invalid data.</p>
<p>The Data Transmit Register/FIFO Underrun 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.</p>
<p>The Data Receive Register/FIFO Overrun interrupt indicates that the SPI device received data and subsequently dropped the data because the data receive register (or 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.</p>
<p>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.</p>
<p>The Slave Mode Fault Error interrupt indicates that a slave device was selected as a slave by a master, but the slave device was disabled. This can be used during system debugging or by the slave application to learn when the slave application has not prepared for a master operation in a timely fashion. This likely indicates a problem with the higher layer protocol, or a problem with the slave performance.</p>
<p>The Slave Mode Select interrupt indicates that the SPI device was selected as a slave by a master. The driver reports this condition to the upper layer software through the status handler.</p>
<p>Data Receive FIFO not Empty interrupt indicates that the SPI device, in slave mode, has received a data byte in the Data Receive FIFO, after the master has started a transfer. The driver reports this condition to the upper layer software through the status handler.</p>
<p><b>Polled Operation</b></p>
<p>This driver operates in polled mode operation too. To put the driver in polled mode the Global Interrupt must be disabled after the Spi is Initialized and Spi driver is started.</p>
<p>Statistics are not updated in this mode of operation.</p>
<p><b>Device Busy</b></p>
<p>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.</p>
<p><b>Device Configuration</b></p>
<p>The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the <aclass="el"href="xspi__g_8c.html">xspi_g.c</a> file or passed in via _CfgInitialize(). A table is defined where each entry contains configuration information for an SPI device. This information includes such things as the base address of the memory-mapped device, the number of slave select bits in the device, and whether the device has FIFOs and is configured as slave-only.</p>
<p><b>RTOS Independence</b></p>
<p>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.</p>
register/bit definitions from <aclass="el"href="xspi__i_8h.html">xspi_i.h</a> to xpsi_l.h.
Even for the polled mode of operation the Interrupt Logic
in the core should be included. The driver can be put in
polled mode of operation by disabling the Global Interrupt
after the Spi Initialization is completed and Spi is
started.
2.01a sdm 08/22/08 Removed support for static interrupt handlers from the MDD
file
2.01b sdm 04/08/09 Fixed an issue in the XSpi_Transfer function where the
Global Interrupt is being enabled in polled mode when a
slave is not selected.
3.00a ktn 10/22/09 Converted all register accesses to 32 bit access.
Updated driver to use the HAL APIs/macros.
Removed the macro XSpi_mReset, XSpi_Reset API should be
used in its place.
The macros have been renamed to remove _m from the name
XSpi_mIntrGlobalEnable is renamed XSpi_IntrGlobalEnable,
XSpi_mIntrGlobalDisable is now XSpi_IntrGlobalDisable,
XSpi_mIsIntrGlobalEnabled is now XSpi_IsIntrGlobalEnabled,
XSpi_mIntrGetStatus is now XSpi_IntrGetStatus,
XSpi_mIntrClear is now XSpi_IntrClear,
XSpi_mIntrEnable is now XSpi_IntrEnable,
XSpi_mIntrDisable is now XSpi_IntrDisable,
XSpi_mIntrGetEnabled is now XSpi_IntrGetEnabled,
XSpi_mSetControlReg is now XSpi_SetControlReg,
XSpi_mGetControlReg is now XSpi_GetControlReg,
XSpi_mGetStatusReg is now XSpi_GetStatusReg,
XSpi_mSetSlaveSelectReg is now XSpi_SetSlaveSelectReg,
XSpi_mGetSlaveSelectReg is now XSpi_GetSlaveSelectReg,
XSpi_mEnable is now XSpi_Enable,
XSpi_mDisable is now XSpi_Disable.
3.01a sdm 04/23/10 Updated the driver to handle new slave mode interrupts
and the DTR Half Empty interrupt.
3.02a sdm 03/30/11 Updated to support axi_qspi.
3.03a sdm 08/09/11 Updated the selftest to check for a correct default value
in the case of axi_qspi - CR 620502
Updated tcl to generate a config parameter for C_SPI_MODE
3.04a bss 03/21/12 Updated <aclass="el"href="struct_x_spi___config.html">XSpi_Config</a> and <aclass="el"href="struct_x_spi.html">XSpi</a> instance structure to support
XIP Mode.
Updated XSpi_CfgInitialize to support XIP Mode
Added XIP Mode Register masks in <aclass="el"href="xspi__l_8h.html">xspi_l.h</a>
Tcl Script changes:
Added C_TYPE_OF_AXI4_INTERFACE, C_AXI4_BASEADDR and
C_XIP_MODE to config structure.
Modified such that based on C_XIP_MODE and
C_TYPE_OF_AXI4_INTERFACE parameters C_BASEADDR will
be updated with C_AXI4_BASEADDR.
Modified such that C_FIFO_EXIST will be updated based
on C_FIFO_DEPTH for compatability of the driver with
Axi Spi.
3.05a adk 18/04/13 Updated the code to avoid unused variable
warnings when compiling with the -Wextra -Wall flags
In the file <aclass="el"href="xspi_8c.html">xspi.c</a>. CR:705005.
3.06a adk 07/08/13 Added a dummy read in the CfgInitialize(), if startup
block is used in the h/w design (CR 721229).
3.07a adk 11/10/13 Fixed CR:732962 Changes are made in the <aclass="el"href="xspi_8c.html">xspi.c</a> file
