About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / altera_tse.txt




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:40 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 seperately. 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 initites 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	intialization. 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).
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.