Documentation/networking/altera_tse.txt

   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 5.2.2.1.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 5.2.2.1.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 5.2.2.1.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 5.2.2.1.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 5.2.2.1.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 5.2.2.1.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 30.3.4.2. 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 30.3.4.3. 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).