altera_tse.rst (13017B)
1.. SPDX-License-Identifier: GPL-2.0 2 3.. include:: <isonum.txt> 4 5======================================= 6Altera Triple-Speed Ethernet MAC driver 7======================================= 8 9Copyright |copy| 2008-2014 Altera Corporation 10 11This is the driver for the Altera Triple-Speed Ethernet (TSE) controllers 12using the SGDMA and MSGDMA soft DMA IP components. The driver uses the 13platform bus to obtain component resources. The designs used to test this 14driver were built for a Cyclone(R) V SOC FPGA board, a Cyclone(R) V FPGA board, 15and tested with ARM and NIOS processor hosts separately. The anticipated use 16cases are simple communications between an embedded system and an external peer 17for status and simple configuration of the embedded system. 18 19For more information visit www.altera.com and www.rocketboards.org. Support 20forums for the driver may be found on www.rocketboards.org, and a design used 21to test this driver may be found there as well. Support is also available from 22the maintainer of this driver, found in MAINTAINERS. 23 24The Triple-Speed Ethernet, SGDMA, and MSGDMA components are all soft IP 25components that can be assembled and built into an FPGA using the Altera 26Quartus toolchain. Quartus 13.1 and 14.0 were used to build the design that 27this driver was tested against. The sopc2dts tool is used to create the 28device tree for the driver, and may be found at rocketboards.org. 29 30The driver probe function examines the device tree and determines if the 31Triple-Speed Ethernet instance is using an SGDMA or MSGDMA component. The 32probe function then installs the appropriate set of DMA routines to 33initialize, setup transmits, receives, and interrupt handling primitives for 34the respective configurations. 35 36The SGDMA component is to be deprecated in the near future (over the next 1-2 37years as of this writing in early 2014) in favor of the MSGDMA component. 38SGDMA support is included for existing designs and reference in case a 39developer wishes to support their own soft DMA logic and driver support. Any 40new designs should not use the SGDMA. 41 42The SGDMA supports only a single transmit or receive operation at a time, and 43therefore will not perform as well compared to the MSGDMA soft IP. Please 44visit www.altera.com for known, documented SGDMA errata. 45 46Scatter-gather DMA is not supported by the SGDMA or MSGDMA at this time. 47Scatter-gather DMA will be added to a future maintenance update to this 48driver. 49 50Jumbo frames are not supported at this time. 51 52The driver limits PHY operations to 10/100Mbps, and has not yet been fully 53tested for 1Gbps. This support will be added in a future maintenance update. 54 551. Kernel Configuration 56======================= 57 58The kernel configuration option is ALTERA_TSE: 59 60 Device Drivers ---> Network device support ---> Ethernet driver support ---> 61 Altera Triple-Speed Ethernet MAC support (ALTERA_TSE) 62 632. Driver parameters list 64========================= 65 66 - debug: message level (0: no output, 16: all); 67 - dma_rx_num: Number of descriptors in the RX list (default is 64); 68 - dma_tx_num: Number of descriptors in the TX list (default is 64). 69 703. Command line options 71======================= 72 73Driver parameters can be also passed in command line by using:: 74 75 altera_tse=dma_rx_num:128,dma_tx_num:512 76 774. Driver information and notes 78=============================== 79 804.1. Transmit process 81--------------------- 82When the driver's transmit routine is called by the kernel, it sets up a 83transmit descriptor by calling the underlying DMA transmit routine (SGDMA or 84MSGDMA), and initiates a transmit operation. Once the transmit is complete, an 85interrupt is driven by the transmit DMA logic. The driver handles the transmit 86completion in the context of the interrupt handling chain by recycling 87resource required to send and track the requested transmit operation. 88 894.2. Receive process 90-------------------- 91The driver will post receive buffers to the receive DMA logic during driver 92initialization. Receive buffers may or may not be queued depending upon the 93underlying DMA logic (MSGDMA is able queue receive buffers, SGDMA is not able 94to queue receive buffers to the SGDMA receive logic). When a packet is 95received, the DMA logic generates an interrupt. The driver handles a receive 96interrupt by obtaining the DMA receive logic status, reaping receive 97completions until no more receive completions are available. 98 994.3. Interrupt Mitigation 100------------------------- 101The driver is able to mitigate the number of its DMA interrupts 102using NAPI for receive operations. Interrupt mitigation is not yet supported 103for transmit operations, but will be added in a future maintenance release. 104 1054.4) Ethtool support 106-------------------- 107Ethtool is supported. Driver statistics and internal errors can be taken using: 108ethtool -S ethX command. It is possible to dump registers etc. 109 1104.5) PHY Support 111---------------- 112The driver is compatible with PAL to work with PHY and GPHY devices. 113 1144.7) List of source files: 115-------------------------- 116 - Kconfig 117 - Makefile 118 - altera_tse_main.c: main network device driver 119 - altera_tse_ethtool.c: ethtool support 120 - altera_tse.h: private driver structure and common definitions 121 - altera_msgdma.h: MSGDMA implementation function definitions 122 - altera_sgdma.h: SGDMA implementation function definitions 123 - altera_msgdma.c: MSGDMA implementation 124 - altera_sgdma.c: SGDMA implementation 125 - altera_sgdmahw.h: SGDMA register and descriptor definitions 126 - altera_msgdmahw.h: MSGDMA register and descriptor definitions 127 - altera_utils.c: Driver utility functions 128 - altera_utils.h: Driver utility function definitions 129 1305. Debug Information 131==================== 132 133The driver exports debug information such as internal statistics, 134debug information, MAC and DMA registers etc. 135 136A user may use the ethtool support to get statistics: 137e.g. using: ethtool -S ethX (that shows the statistics counters) 138or sees the MAC registers: e.g. using: ethtool -d ethX 139 140The developer can also use the "debug" module parameter to get 141further debug information. 142 1436. Statistics Support 144===================== 145 146The controller and driver support a mix of IEEE standard defined statistics, 147RFC defined statistics, and driver or Altera defined statistics. The four 148specifications containing the standard definitions for these statistics are 149as follows: 150 151 - IEEE 802.3-2012 - IEEE Standard for Ethernet. 152 - RFC 2863 found at http://www.rfc-editor.org/rfc/rfc2863.txt. 153 - RFC 2819 found at http://www.rfc-editor.org/rfc/rfc2819.txt. 154 - Altera Triple Speed Ethernet User Guide, found at http://www.altera.com 155 156The statistics supported by the TSE and the device driver are as follows: 157 158"tx_packets" is equivalent to aFramesTransmittedOK defined in IEEE 802.3-2012, 159Section 5.2.2.1.2. This statistics is the count of frames that are successfully 160transmitted. 161 162"rx_packets" is equivalent to aFramesReceivedOK defined in IEEE 802.3-2012, 163Section 5.2.2.1.5. This statistic is the count of frames that are successfully 164received. This count does not include any error packets such as CRC errors, 165length errors, or alignment errors. 166 167"rx_crc_errors" is equivalent to aFrameCheckSequenceErrors defined in IEEE 168802.3-2012, Section 5.2.2.1.6. This statistic is the count of frames that are 169an integral number of bytes in length and do not pass the CRC test as the frame 170is received. 171 172"rx_align_errors" is equivalent to aAlignmentErrors defined in IEEE 802.3-2012, 173Section 5.2.2.1.7. This statistic is the count of frames that are not an 174integral number of bytes in length and do not pass the CRC test as the frame is 175received. 176 177"tx_bytes" is equivalent to aOctetsTransmittedOK defined in IEEE 802.3-2012, 178Section 5.2.2.1.8. This statistic is the count of data and pad bytes 179successfully transmitted from the interface. 180 181"rx_bytes" is equivalent to aOctetsReceivedOK defined in IEEE 802.3-2012, 182Section 5.2.2.1.14. This statistic is the count of data and pad bytes 183successfully received by the controller. 184 185"tx_pause" is equivalent to aPAUSEMACCtrlFramesTransmitted defined in IEEE 186802.3-2012, Section 30.3.4.2. This statistic is a count of PAUSE frames 187transmitted from the network controller. 188 189"rx_pause" is equivalent to aPAUSEMACCtrlFramesReceived defined in IEEE 190802.3-2012, Section 30.3.4.3. This statistic is a count of PAUSE frames 191received by the network controller. 192 193"rx_errors" is equivalent to ifInErrors defined in RFC 2863. This statistic is 194a count of the number of packets received containing errors that prevented the 195packet from being delivered to a higher level protocol. 196 197"tx_errors" is equivalent to ifOutErrors defined in RFC 2863. This statistic 198is a count of the number of packets that could not be transmitted due to errors. 199 200"rx_unicast" is equivalent to ifInUcastPkts defined in RFC 2863. This 201statistic is a count of the number of packets received that were not addressed 202to the broadcast address or a multicast group. 203 204"rx_multicast" is equivalent to ifInMulticastPkts defined in RFC 2863. This 205statistic is a count of the number of packets received that were addressed to 206a multicast address group. 207 208"rx_broadcast" is equivalent to ifInBroadcastPkts defined in RFC 2863. This 209statistic is a count of the number of packets received that were addressed to 210the broadcast address. 211 212"tx_discards" is equivalent to ifOutDiscards defined in RFC 2863. This 213statistic is the number of outbound packets not transmitted even though an 214error was not detected. An example of a reason this might occur is to free up 215internal buffer space. 216 217"tx_unicast" is equivalent to ifOutUcastPkts defined in RFC 2863. This 218statistic counts the number of packets transmitted that were not addressed to 219a multicast group or broadcast address. 220 221"tx_multicast" is equivalent to ifOutMulticastPkts defined in RFC 2863. This 222statistic counts the number of packets transmitted that were addressed to a 223multicast group. 224 225"tx_broadcast" is equivalent to ifOutBroadcastPkts defined in RFC 2863. This 226statistic counts the number of packets transmitted that were addressed to a 227broadcast address. 228 229"ether_drops" is equivalent to etherStatsDropEvents defined in RFC 2819. 230This statistic counts the number of packets dropped due to lack of internal 231controller resources. 232 233"rx_total_bytes" is equivalent to etherStatsOctets defined in RFC 2819. 234This statistic counts the total number of bytes received by the controller, 235including error and discarded packets. 236 237"rx_total_packets" is equivalent to etherStatsPkts defined in RFC 2819. 238This statistic counts the total number of packets received by the controller, 239including error, discarded, unicast, multicast, and broadcast packets. 240 241"rx_undersize" is equivalent to etherStatsUndersizePkts defined in RFC 2819. 242This statistic counts the number of correctly formed packets received less 243than 64 bytes long. 244 245"rx_oversize" is equivalent to etherStatsOversizePkts defined in RFC 2819. 246This statistic counts the number of correctly formed packets greater than 1518 247bytes long. 248 249"rx_64_bytes" is equivalent to etherStatsPkts64Octets defined in RFC 2819. 250This statistic counts the total number of packets received that were 64 octets 251in length. 252 253"rx_65_127_bytes" is equivalent to etherStatsPkts65to127Octets defined in RFC 2542819. This statistic counts the total number of packets received that were 255between 65 and 127 octets in length inclusive. 256 257"rx_128_255_bytes" is equivalent to etherStatsPkts128to255Octets defined in 258RFC 2819. This statistic is the total number of packets received that were 259between 128 and 255 octets in length inclusive. 260 261"rx_256_511_bytes" is equivalent to etherStatsPkts256to511Octets defined in 262RFC 2819. This statistic is the total number of packets received that were 263between 256 and 511 octets in length inclusive. 264 265"rx_512_1023_bytes" is equivalent to etherStatsPkts512to1023Octets defined in 266RFC 2819. This statistic is the total number of packets received that were 267between 512 and 1023 octets in length inclusive. 268 269"rx_1024_1518_bytes" is equivalent to etherStatsPkts1024to1518Octets define 270in RFC 2819. This statistic is the total number of packets received that were 271between 1024 and 1518 octets in length inclusive. 272 273"rx_gte_1519_bytes" is a statistic defined specific to the behavior of the 274Altera TSE. This statistics counts the number of received good and errored 275frames between the length of 1519 and the maximum frame length configured 276in the frm_length register. See the Altera TSE User Guide for More details. 277 278"rx_jabbers" is equivalent to etherStatsJabbers defined in RFC 2819. This 279statistic is the total number of packets received that were longer than 1518 280octets, and had either a bad CRC with an integral number of octets (CRC Error) 281or a bad CRC with a non-integral number of octets (Alignment Error). 282 283"rx_runts" is equivalent to etherStatsFragments defined in RFC 2819. This 284statistic is the total number of packets received that were less than 64 octets 285in length and had either a bad CRC with an integral number of octets (CRC 286error) or a bad CRC with a non-integral number of octets (Alignment Error).