The Xilinx AXI Ethernet MAC driver component. This driver supports hard Ethernet core for Virtex-6(TM) devices and soft Ethernet core for Spartan-6(TM) and other supported devices. The supported speed can be 10/100/1000 Mbps and can reach upto 2000/2500 Mbps (1000Base-X versions).<p>
For a full description of AXI Ethernet features, please see the hardware spec. This driver supports the following features:<ul>
<li>Memory mapped access to host interface registers</li><li>Virtual memory support</li><li>Unicast, broadcast, and multicast receive address filtering</li><li>Full duplex operation</li><li>Automatic source address insertion or overwrite (programmable)</li><li>Automatic PAD & FCS insertion and stripping (programmable)</li><li>Flow control</li><li>VLAN frame support</li><li>Pause frame support</li><li>Jumbo frame support</li><li>Partial and full checksum offload</li><li>Extended multicast addresses to 2**23.</li><li>Extended VLAN translation, tagging and stripping supports.</li></ul>
The device driver enables higher layer software (e.g., an application) to configure a Axi Ethernet device. It is intended that this driver be used in cooperation with another driver (FIFO or DMA) for data communication. This device driver can support multiple devices even when those devices have significantly different configurations.<p>
The <aclass="el"href="struct_x_axi_ethernet___config.html">XAxiEthernet_Config</a> structure can be used by the driver to configure itself. This configuration structure is typically created by the tool-chain based on hardware build properties, although, other methods are allowed and currently used in some systems.<p>
To support multiple runtime loading and initialization strategies employed by various operating systems, the driver instance can be initialized using the XAxiEthernet_CfgInitialze() routine.<p>
The driver has no dependencies on the interrupt controller. It provides no interrupt handlers. The application/OS software should set up its own interrupt handlers if required.<p>
When a Axi Ethernet device is connected up to a FIFO or DMA core in hardware, errors may be reported on one of those cores (FIFO or DMA) such that it can be determined that the Axi Ethernet device needs to be reset. If a reset is performed, the calling code should also reconfigure and reapply the proper settings in the Axi Ethernet device.<p>
When a Axi Ethernet device reset is required, <aclass="el"href="xaxiethernet_8c.html#091a291d11f394e3eaf0b79195666d9f">XAxiEthernet_Reset()</a> should be utilized.<p>
This driver may be used in systems with virtual memory support by passing the appropriate value for the <em>EffectiveAddress</em> parameter to the <aclass="el"href="xaxiethernet_8c.html#73871df4ff59ae908c63c51db94f1a90">XAxiEthernet_CfgInitialize()</a> routine.<p>
The Axi Ethernet core by itself is not capable of transmitting or receiving data in any meaningful way. Instead the Axi Ethernet device need to be connected to a FIFO or DMA core in hardware.<p>
This Axi Ethernet driver is modeled in a similar fashion where the application code or O/S adapter driver needs to make use of a separate FIFO or DMA driver in connection with this driver to establish meaningful communication over Ethernet.<p>
If configured, the device can compute a 16-bit checksum from frame data. In most circumstances this can lead to a substantial gain in throughput.<p>
The checksum offload settings for each frame sent or received are transmitted through the AXI4-Stream interface in hardware. What this means is that the checksum offload feature is indirectly controlled in the Axi Ethernet device through the driver for DMA core connected to the Axi Ethernet device.<p>
Refer to the documentation for DMA driver used for data communication on how to set the values for the relevant AXI4-Stream control words.<p>
Since this hardware implementation is general purpose in nature system software must perform pre and post frame processing to obtain the desired results for the types of packets being transferred. Most of the time this will be TCP/IP traffic.<p>
TCP/IP and UDP/IP frames contain separate checksums for the IP header and UDP/TCP header+data. For partial checksum offloading (enabled while configuring the hardware), the IP header checksum cannot be offloaded. Many stacks that support offloading will compute the IP header if required and use hardware to compute the UDP/TCP header+data checksum. There are other complications concerning the IP pseudo header that must be taken into consideration. Readers should consult a TCP/IP design reference for more details.<p>
For full checksum offloading (enabled while configuring the hardware), the IPv4 checksum calculation and validation can also be offloaded at the harwdare. Full checksum offload is supported only under certain conditions. IP checksum offload will be supported on valid IP datagrams that meet the following conditions.<ul>
<li>If present, the VLAN header is 4 bytes long</li><li>Encapsulation into the Ethernet frame is either Ethernet II or Ethernet SNAP format</li><li>Only IPv4 is supported. IPv6 is not supported.</li><li>IP header is a valid length TCP/UDP checksum offloading will be supported on valid TCP/UDP segments that meet the following conditions.</li><li>Encapsulated in IPv4 (IPv6 is not supported)</li><li>Good IP header checksum</li><li>No fragmentation</li><li>TCP or UDP segment When full checksum offload is enabled, the hardware does the following:</li><li>Calculates the IP header checksum and inserts it in the IP header.</li><li>Calculates the TCP/UDP Pseudo header from IP header.</li><li>Calculates TCP/UDP header from, TCP/UDP psedu header, TCP/UDP header and TCP/UDP payload.</li><li>On the receive path, it again calculates all the above and validates for IP header checksum and TCP/UDP checksum.</li></ul>
<p>
There are certain device options that will affect the checksum calculation performed by hardware for Tx:<p>
<li>FCS insertion disabled (XAE_FCS_INSERT_OPTION): software is required to calculate and insert the FCS value at the end of the frame, but the checksum must be known ahead of time prior to calculating the FCS. Therefore checksum offloading cannot be used in this situation.</li></ul>
<li>FCS/PAD stripping disabled (XAE_FCS_STRIP_OPTION): The 4 byte FCS at the end of frame will be included in the hardware calculated checksum. software must subtract out this data.</li></ul>
<li>FCS/PAD stripping disabled (XAE_FCS_STRIP_OPTION): For frames smaller than 64 bytes, padding will be included in the hardware calculated checksum. software must subtract out this data. It may be better to allow the TCP/IP stack verify checksums for this type of packet.</li></ul>
<li>VLAN enabled (XAE_VLAN_OPTION): The 4 extra bytes in the Ethernet header affect the hardware calculated checksum. software must subtract out the 1st two 16-bit words starting at the 15th byte.</li></ul>
For partial checksum offloading, for the TX path, the software can specify where in the frame the checksum calculation is to start, where the result should be inserted, and a seed value. The checksum is calculated from the start point through the end of frame.<p>
For full checksum offloading, for the TX path, the software just need to enable Full Checksum offload in the appropriate AXI4-Stream Control word on a per packet basis.<p>
The checksum offloading settings are sent in the transmit AXI4 Stream control words. The relevant control word fields are described in brief below. Refer to the Axi Ethernet hardware specification for more details.<p>
For partial checksum offload on the RX path, the 15th byte to end of frame is check summed. This range of bytes is the entire Ethernet payload (for non-VLAN frames).<p>
For full checksum offload on the RX path, both the IP and TCP checksums are validated if the packet meets the specified conditions.<p>
The checksum offloading information is sent in the receive AXI4-Stream status words. There are 4 relevant status words available. However only the relevant status words are described in brief below. Refer to the Axi Ethernet hardware specification for more details.<p>
Bits 5-3 : Specifies the receive full checksum status. This is relevant only for full checksum offloading. 000 -> Neither the IP header nor the TCP/UDP checksums were checked. 001 -> The IP header checksum was checked and was correct. The TCP/UDP checksum was not checked. 010 -> Both the IP header checksum and the TCP checksum were checked and were correct. 011 -> Both the IP header checksum and the UDP checksum were checked and were correct. 100 -> Reserved. 101 -> The IP header checksum was checked and was incorrect. The TCP/UDP checksum was not checked. 110 -> The IP header checksum was checked and is correct but the TCP checksum was checked and was incorrect. 111 -> The IP header checksum was checked and is correct but the UDP checksum was checked and was incorrect.<p>
(XAE_EXT_MULTICAST_OPTION): Allow and perform address filtering more than 4 multicast addresses. Hardware requires to enable promiscuous mode (XAE_PROMISCUOUS_OPTION) and disable legacy multicast mode (XAE_MULTICAST_OPTION) for this feature to work.<p>
(XAE_EXT_[T|R]XVLAN_STRP_OPTION) handles transmit/receive one VLAN tag stripping in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XAE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION) and disable (XAE_VLAN_OPTION). Supports three modes, -XAE_VSTRP_NONE : no stripping -XAE_VSTRP_ALL : strip one tag from all frames -XAE_VSTRP_SELECT : strip one tag from selected frames<p>
(XATE_EXT_[T|R]XVLAN_TRAN_OPTION) handles transmit/receive one VLAN tag translation in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XATE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION), and disable (XAE_VLAN_OPTION).<p>
(XAE_EXT_[T|R]XVLAN_TAG_OPTION) adds transmit/receive one VLAN tag in Ethernet frames. To enable this option, hardware requires to build with this feature and enable (XAE_FCS_INSERT_OPTION), (XAE_FCS_STRP_OPTION), (XAE_JUMBO_OPTION) and disable (XAE_VLAN_OPTION). Support four modes, -XAE_VTAG_NONE : no tagging -XAE_VTAG_ALL : tag all frames -XAE_VTAG_EXISTED : tag already tagged frames -XAE_VTAG_SELECT : tag selected already tagged frames<p>
Prior to PHY access, the MDIO clock must be setup. This driver will set a safe default that should work with AXI4-Lite bus speeds of up to 150 MHz and keep the MDIO clock below 2.5 MHz. If the user wishes faster access to the PHY then the clock divisor can be set to a different value (see <aclass="el"href="xaxiethernet_8c.html#2b33bc77237bf039c02d4619a811aed6">XAxiEthernet_PhySetMdioDivisor()</a>).<p>
MII register access is performed through the functions <aclass="el"href="xaxiethernet_8c.html#6dc70adcb2c07eb801facc8e2243ea98">XAxiEthernet_PhyRead()</a> and <aclass="el"href="xaxiethernet_8c.html#9394dd066a7497ed9346b26457c28247">XAxiEthernet_PhyWrite()</a>.<p>
When the device is used in a multi speed environment, the link speed must be explicitly set using <aclass="el"href="xaxiethernet_8c.html#b2d0106f26a1a2e1f2b902dc0a2822c9">XAxiEthernet_SetOperatingSpeed()</a> and must match the speed PHY has negotiated. If the speeds are mismatched, then the MAC will not pass traffic.<p>
The application/OS software may use the AutoNegotiation interrupt to be notified when the PHY has completed auto-negotiation.<p>
Asserts are used within all Xilinx drivers to enforce constraints on argument values. 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>
<li>A dropped receive frame indication may be reported by the driver after calling <aclass="el"href="xaxiethernet_8c.html#4e952a55f342f176ba9ec2b49e2e47cb">XAxiEthernet_Stop()</a> followed by <aclass="el"href="xaxiethernet_8c.html#2cfa48d42e55238f6f30aff6d658e4fe">XAxiEthernet_Start()</a>. This can occur if a frame is arriving when stop is called.</li><li>On Rx with checksum offloading enabled and FCS/PAD stripping disabled, FCS and PAD data will be included in the checksum result.</li><li>On Tx with checksum offloading enabled and auto FCS insertion disabled, the user calculated FCS will be included in the checksum result.</li></ul>
<p>
<dlcompact><dt><b>Note:</b></dt><dd></dd></dl>
Xilinx drivers are typically composed of two components, 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. <br>
<br>
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 by the layer above this driver.<p>
