Documentation/networking/device_drivers/ethernet/altera/altera_tse.rst

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