125 lines
12 KiB
HTML
125 lines
12 KiB
HTML
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
|
||
|
|
<title>
|
||
|
|
Xilinx Driver spips v2_0: spips v2_0
|
||
|
|
</title>
|
||
|
|
<link href="doxygen_kalyanidocs/doc/css/driver_api_doxygen.css" rel="stylesheet" type="text/css">
|
||
|
|
</head>
|
||
|
|
<h3 class="PageHeader">Xilinx Processor IP Library</h3>
|
||
|
|
<hl>Software Drivers</hl>
|
||
|
|
<hr class="whs1">
|
||
|
|
|
||
|
|
<!-- Generated by Doxygen 1.6.1 -->
|
||
|
|
<div class="navigation" id="top">
|
||
|
|
<div class="tabs">
|
||
|
|
<ul>
|
||
|
|
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
|
||
|
|
<li><a href="annotated.html"><span>Classes</span></a></li>
|
||
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="contents">
|
||
|
|
<h1>spips v2_0</h1><p>This file contains the implementation of the <a class="el" href="struct_x_spi_ps.html">XSpiPs</a> 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.</p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p><b>Initialization & Configuration</b></p>
|
||
|
|
<p>The <a class="el" href="struct_x_spi_ps___config.html">XSpiPs_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 the following way:</p>
|
||
|
|
<ul>
|
||
|
|
<li>XSpiPs_LookupConfig(DeviceId) - Use the devide identifier to find the static configuration structure defined in <a class="el" href="xspips__g_8c.html">xspips_g.c</a>. This is setup by the tools. For some operating systems the config structure will be initialized by the software and this call is not needed.</li>
|
||
|
|
<li>XSpiPs_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>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.</p>
|
||
|
|
<p><b>Modes of Operation</b></p>
|
||
|
|
<p>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).</p>
|
||
|
|
<ul>
|
||
|
|
<li>Auto CS: Chip select is automatically asserted as soon as the first word is written into the TXFIFO and deasserted when the TXFIFO becomes empty</li>
|
||
|
|
<li>Manual CS: Software must assert and deassert CS.</li>
|
||
|
|
<li>Auto Start: Data transmission starts as soon as there is data in the TXFIFO and stalls when the TXFIFO is empty</li>
|
||
|
|
<li>Manual Start: Software must start data transmission at the beginning of the transaction or whenever the TXFIFO has become empty</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>Risks/challenges of other combinations:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Manual CS and Manual Start: Manual Start bit should be set after each TXFIFO write otherwise there could be a race condition where the TXFIFO becomes empty before the new word is written. In that case the transmission stops.</li>
|
||
|
|
<li>Auto CS with Manual or Auto Start: It is very difficult for software to keep the TXFIFO filled. Whenever the TXFIFO runs empty, CS is deasserted. This results in a single transaction to be split into multiple pieces each with its own chip select. This will result in garbage data to be sent.</li>
|
||
|
|
</ul>
|
||
|
|
<p><b>Interrupts</b></p>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>The driver handles the following interrupts:</p>
|
||
|
|
<ul>
|
||
|
|
<li>Data Transmit Register/FIFO Underflow</li>
|
||
|
|
<li>Data Receive Register/FIFO Full</li>
|
||
|
|
<li>Data Receive Register/FIFO Not Empty</li>
|
||
|
|
<li>Data Transmit Register/FIFO Full</li>
|
||
|
|
<li>Data Transmit Register/FIFO Overwater</li>
|
||
|
|
<li>Mode Fault Error</li>
|
||
|
|
<li>Data Receive Register/FIFO Overrun</li>
|
||
|
|
</ul>
|
||
|
|
<p>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.</p>
|
||
|
|
<p>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.</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 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.</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. 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.</p>
|
||
|
|
<p><b>Polled Operation</b></p>
|
||
|
|
<p>Transfer in polled mode is supported through a separate interface function <a class="el" href="xspips_8c.html#a49a95c2c4040817b5c9bd33af1cf54a6">XSpiPs_PolledTransfer()</a>. Unlike the transfer function in the interrupt mode, this function blocks until all data has been sent/received.</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 <a class="el" href="xspips__g_8c.html">xspips_g.c</a> file or passed in via <a class="el" href="xspips_8c.html#a080d853850655991dc9097367496c224">XSpiPs_CfgInitialize()</a>. A table is defined where each entry contains configuration information for an SPI device, including the base address for the device.</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>
|
||
|
|
<pre>
|
||
|
|
MODIFICATION HISTORY:</pre><pre> 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.</pre><pre> </pre> </div>
|
||
|
|
<p class="Copyright">
|
||
|
|
Copyright © 1995-2014 Xilinx, Inc. All rights reserved.
|
||
|
|
</p>
|
||
|
|
</body>
|
||
|
|
</html>
|