9e790c6a41
This patch updates the doxygen for the emacps driver. Signed-off-by: Kedareswara rao Appana <appanad@xilinx.com>
118 lines
14 KiB
HTML
Executable file
118 lines
14 KiB
HTML
Executable file
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
|
|
<title>
|
|
emacps v2_2
|
|
</title>
|
|
<link href="$DriverApiDocsCssPath" 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.4.7 -->
|
|
<div class="tabs">
|
|
<ul>
|
|
<li id="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>
|
|
<h1>emacps v2_2</h1>
|
|
<p>
|
|
The Xilinx Embedded Processor Block Ethernet driver.<p>
|
|
For a full description of XEMACPS features, please see the hardware spec. This driver supports the following features:<ul>
|
|
<li>Memory mapped access to host interface registers</li><li>Statistics counter registers for RMON/MIB</li><li>API for interrupt driven frame transfers for hardware configured DMA</li><li>Virtual memory support</li><li>Unicast, broadcast, and multicast receive address filtering</li><li>Full and half duplex operation</li><li>Automatic PAD & FCS insertion and stripping</li><li>Flow control</li><li>Support up to four 48bit addresses</li><li>Address checking for four specific 48bit addresses</li><li>VLAN frame support</li><li>Pause frame support</li><li>Large frame support up to 1536 bytes</li><li>Checksum offload</li></ul>
|
|
<p>
|
|
<b>Driver Description</b><p>
|
|
The device driver enables higher layer software (e.g., an application) to communicate to the <a class="el" href="struct_x_emac_ps.html">XEmacPs</a>. The driver handles transmission and reception of Ethernet frames, as well as configuration and control. No pre or post processing of frame data is performed. The driver does not validate the contents of an incoming frame in addition to what has already occurred in hardware. A single device driver can support multiple devices even when those devices have significantly different configurations.<p>
|
|
<b>Initialization & Configuration</b><p>
|
|
The <a class="el" href="struct_x_emac_ps___config.html">XEmacPs_Config</a> structure is used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on hardware build properties.<p>
|
|
The driver instance can be initialized in<p>
|
|
<ul>
|
|
<li>XEmacPs_CfgInitialize(InstancePtr, CfgPtr, EffectiveAddress): 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>
|
|
The device supports DMA only as current development plan. No FIFO mode is supported. The driver expects to start the DMA channels and expects that the user has set up the buffer descriptor lists.<p>
|
|
<b>Interrupts and Asynchronous Callbacks</b><p>
|
|
The driver has no dependencies on the interrupt controller. When an interrupt occurs, the handler will perform a small amount of housekeeping work, determine the source of the interrupt, and call the appropriate callback function. All callbacks are registered by the user level application.<p>
|
|
<b>Virtual Memory</b><p>
|
|
All virtual to physical memory mappings must occur prior to accessing the driver API.<p>
|
|
For DMA transactions, user buffers supplied to the driver must be in terms of their physical address.<p>
|
|
<b>DMA</b><p>
|
|
The DMA engine uses buffer descriptors (BDs) to describe Ethernet frames. These BDs are typically chained together into a list the hardware follows when transferring data in and out of the packet buffers. Each BD describes a memory region containing either a full or partial Ethernet packet.<p>
|
|
Interrupt coalescing is not suppoted from this built-in DMA engine.<p>
|
|
This API requires the user to understand how the DMA operates. The following paragraphs provide some explanation, but the user is encouraged to read documentation in <a class="el" href="xemacps__bdring_8h.html">xemacps_bdring.h</a> as well as study example code that accompanies this driver.<p>
|
|
The API is designed to get BDs to and from the DMA engine in the most efficient means possible. The first step is to establish a memory region to contain all BDs for a specific channel. This is done with <a class="el" href="xemacps__bdring_8c.html#1b6f53633ad6466e00391274d182fc6b">XEmacPs_BdRingCreate()</a>. This function sets up a BD ring that hardware will follow as BDs are processed. The ring will consist of a user defined number of BDs which will all be partially initialized. For example on the transmit channel, the driver will initialize all BDs' so that they are configured for transmit. The more fields that can be permanently setup at initialization, then the fewer accesses will be needed to each BD while the DMA engine is in operation resulting in better throughput and CPU utilization. The best case initialization would require the user to set only a frame buffer address and length prior to submitting the BD to the engine.<p>
|
|
BDs move through the engine with the help of functions <a class="el" href="xemacps__bdring_8c.html#6d7d4a8a571956b6ddef55307f3b2c7b">XEmacPs_BdRingAlloc()</a>, <a class="el" href="xemacps__bdring_8c.html#def8169a514444cbb7e615d6e11b05a3">XEmacPs_BdRingToHw()</a>, XEmacPs_BdRingFromHw(), and <a class="el" href="xemacps__bdring_8c.html#7bb4a77d78a9111d56b6bb8dacf6926d">XEmacPs_BdRingFree()</a>. All these functions handle BDs that are in place. That is, there are no copies of BDs kept anywhere and any BD the user interacts with is an actual BD from the same ring hardware accesses.<p>
|
|
BDs in the ring go through a series of states as follows: 1. Idle. The driver controls BDs in this state. 2. The user has data to transfer. <a class="el" href="xemacps__bdring_8c.html#6d7d4a8a571956b6ddef55307f3b2c7b">XEmacPs_BdRingAlloc()</a> is called to reserve BD(s). Once allocated, the user may setup the BD(s) with frame buffer address, length, and other attributes. The user controls BDs in this state. 3. The user submits BDs to the DMA engine with XEmacPs_BdRingToHw. BDs in this state are either waiting to be processed by hardware, are in process, or have been processed. The DMA engine controls BDs in this state. 4. Processed BDs are retrieved with XEmacEpv_BdRingFromHw() by the user. Once retrieved, the user can examine each BD for the outcome of the DMA transfer. The user controls BDs in this state. After examining the BDs the user calls <a class="el" href="xemacps__bdring_8c.html#7bb4a77d78a9111d56b6bb8dacf6926d">XEmacPs_BdRingFree()</a> which places the BDs back into state 1.<p>
|
|
Each of the four BD accessor functions operate on a set of BDs. A set is defined as a segment of the BD ring consisting of one or more BDs. The user views the set as a pointer to the first BD along with the number of BDs for that set. The set can be navigated by using macros XEmacPs_BdNext(). The user must exercise extreme caution when changing BDs in a set as there is nothing to prevent doing a mBdNext past the end of the set and modifying a BD out of bounds.<p>
|
|
<a class="el" href="xemacps__bdring_8c.html#6d7d4a8a571956b6ddef55307f3b2c7b">XEmacPs_BdRingAlloc()</a> + <a class="el" href="xemacps__bdring_8c.html#def8169a514444cbb7e615d6e11b05a3">XEmacPs_BdRingToHw()</a>, as well as XEmacPs_BdRingFromHw() + <a class="el" href="xemacps__bdring_8c.html#7bb4a77d78a9111d56b6bb8dacf6926d">XEmacPs_BdRingFree()</a> are designed to be used in tandem. The same BD set retrieved with BdRingAlloc should be the same one provided to hardware with BdRingToHw. Same goes with BdRingFromHw and BdRIngFree.<p>
|
|
<b>Alignment & Data Cache Restrictions</b><p>
|
|
Due to the design of the hardware, all RX buffers, BDs need to be 4-byte aligned. Please reference <a class="el" href="xemacps__bd_8h.html">xemacps_bd.h</a> for cache related macros.<p>
|
|
DMA Tx:<p>
|
|
<ul>
|
|
<li>If frame buffers exist in cached memory, then they must be flushed prior to committing them to hardware.</li></ul>
|
|
<p>
|
|
DMA Rx:<p>
|
|
<ul>
|
|
<li>If frame buffers exist in cached memory, then the cache must be invalidated for the memory region containing the frame prior to data access</li></ul>
|
|
<p>
|
|
Both cache invalidate/flush are taken care of in driver code.<p>
|
|
<b>Buffer Copying</b><p>
|
|
The driver is designed for a zero-copy buffer scheme. That is, the driver will not copy buffers. This avoids potential throughput bottlenecks within the driver. If byte copying is required, then the transfer will take longer to complete.<p>
|
|
<b>Checksum Offloading</b><p>
|
|
The Embedded Processor Block Ethernet can be configured to perform IP, TCP and UDP checksum offloading in both receive and transmit directions.<p>
|
|
IP packets contain a 16-bit checksum field, which is the 16-bit 1s complement of the 1s complement sum of all 16-bit words in the header. TCP and UDP packets contain a 16-bit checksum field, which is the 16-bit 1s complement of the 1s complement sum of all 16-bit words in the header, the data and a conceptual pseudo header.<p>
|
|
To calculate these checksums in software requires each byte of the packet to be read. For TCP and UDP this can use a large amount of processing power. Offloading the checksum calculation to hardware can result in significant performance improvements.<p>
|
|
The transmit checksum offload is only available to use DMA in packet buffer mode. This is because the complete frame to be transmitted must be read into the packet buffer memory before the checksum can be calculated and written to the header at the beginning of the frame.<p>
|
|
For IP, TCP or UDP receive checksum offload to be useful, the operating system containing the protocol stack must be aware that this offload is available so that it can make use of the fact that the hardware has verified the checksum.<p>
|
|
When receive checksum offloading is enabled in the hardware, the IP header checksum is checked, where the packet meets the following criteria:<p>
|
|
1. If present, the VLAN header must be four octets long and the CFI bit must not be set. 2. Encapsulation must be RFC 894 Ethernet Type Encoding or RFC 1042 SNAP encoding. 3. IP v4 packet. 4. IP header is of a valid length. 5. Good IP header checksum. 6. No IP fragmentation. 7. TCP or UDP packet.<p>
|
|
When an IP, TCP or UDP frame is received, the receive buffer descriptor gives an indication if the hardware was able to verify the checksums. There is also an indication if the frame had SNAP encapsulation. These indication bits will replace the type ID match indication bits when the receive checksum offload is enabled.<p>
|
|
If any of the checksums are verified incorrect by the hardware, the packet is discarded and the appropriate statistics counter incremented.<p>
|
|
<b>PHY Interfaces</b><p>
|
|
RGMII 1.3 is the only interface supported.<p>
|
|
<b>Asserts</b><p>
|
|
Asserts are used within all Xilinx drivers to enforce constraints on parameters. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development. For deployment use -DNDEBUG compiler switch to remove assert code.<p>
|
|
<dl compact><dt><b>Note:</b></dt><dd></dd></dl>
|
|
Xilinx drivers are typically composed of two parts, one is the driver and the other is the adapter. The driver is independent of OS and processor and is intended to be highly portable. The adapter is OS-specific and facilitates communication between the driver and an OS. This driver is intended to be RTOS and processor independent. Any needs for dynamic memory management, threads or thread mutual exclusion, or cache control must be satisfied bythe layer above this driver.<p>
|
|
<pre>
|
|
MODIFICATION HISTORY:</pre><p>
|
|
<pre> Ver Who Date Changes
|
|
----- ---- -------- -------------------------------------------------------
|
|
1.00a wsy 01/10/10 First release
|
|
1.00a asa 11/21/11 The function XEmacPs_BdRingFromHwTx in file
|
|
<a class="el" href="xemacps__bdring_8c.html">xemacps_bdring.c</a> is modified. Earlier it was checking for
|
|
"BdLimit"(passed argument) number of BDs for finding out
|
|
which BDs are successfully processed. Now one more check
|
|
is added. It looks for BDs till the current BD pointer
|
|
reaches HwTail. By doing this processing time is saved.
|
|
1.00a asa 01/24/12 The function XEmacPs_BdRingFromHwTx in file
|
|
<a class="el" href="xemacps__bdring_8c.html">xemacps_bdring.c</a> is modified. Now start of packet is
|
|
searched for returning the number of BDs processed.
|
|
1.02a asa 11/05/12 Added a new API for deleting an entry from the HASH
|
|
registers. Added a new API to set the bust length.
|
|
Added some new hash-defines.
|
|
1.03a asa 01/23/12 Fix for CR #692702 which updates error handling for
|
|
Rx errors. Under heavy Rx traffic, there will be a large
|
|
number of errors related to receive buffer not available.
|
|
Because of a HW bug (SI #692601), under such heavy errors,
|
|
the Rx data path can become unresponsive. To reduce the
|
|
probabilities for hitting this HW bug, the SW writes to
|
|
bit 18 to flush a packet from Rx DPRAM immediately. The
|
|
changes for it are done in the function
|
|
XEmacPs_IntrHandler.
|
|
1.05a asa 09/23/13 Cache operations on BDs are not required and hence
|
|
removed. It is expected that all BDs are allocated in
|
|
from uncached area.
|
|
1.06a asa 11/02/13 Changed the value for XEMACPS_RXBUF_LEN_MASK from 0x3fff
|
|
to 0x1fff. This fixes the CR#744902.
|
|
Made changes in example file xemacps_example.h to fix compilation
|
|
issues with iarcc compiler.
|
|
2.0 adk 10/12/13 Updated as per the New Tcl API's
|
|
2.1 adk 11/08/14 Fixed the CR#811288. Changes are made in the driver tcl file.
|
|
2.1 bss 09/08/14 Modified driver tcl to fix CR#820349 to export phy
|
|
address in xparameters.h when GMII to RGMII converter
|
|
is present in hw.
|
|
2.2 adk 29/10/14 Fixed CR#827686 when PCS/PMA core is configured with
|
|
1000BASE-X mode export proper values to the xparameters.h
|
|
file. Changes are made in the driver tcl file.
|
|
</pre> Copyright @ 1995-2014 Xilinx, Inc. All rights reserved.
|