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