source: rtems-docs/networking/dec_21140.rst @ f29d91d

5
Last change on this file since f29d91d was f29d91d, checked in by Marçal Comajoan Cara <mcomajoancara@…>, on 12/11/18 at 17:10:59

Integrate images redrawn as part of GCI 2018

All of the redrawings were made by me except images/c_user/states which
was made by LukaMag?. This patch serves to update all the images.

This work was part of GCI 2018.

  • Property mode set to 100644
File size: 9.5 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3DEC 21140 Driver
4################
5
6DEC 21240 Driver Introduction
7=============================
8
9.. COMMENT: XXX add back in cross reference to list of boards.
10
11One aim of our project is to port RTEMS on a standard PowerPC platform.  To
12achieve it, we have chosen a Motorola MCP750 board. This board includes an
13Ethernet controller based on a DEC21140 chip. Because RTEMS has a TCP/IP stack,
14we will have to develop the DEC21140 related ethernet driver for the PowerPC
15port of RTEMS. As this controller is able to support 100Mbps network and as
16there is a lot of PCI card using this DEC chip, we have decided to first
17implement this driver on an Intel PC386 target to provide a solution for using
18RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in a
19second phase.
20
21The aim of this document is to give some PCI board generalities and to explain
22the software architecture of the RTEMS driver. Finally, we will see what will
23be done for ChorusOs and Netboot environment .
24
25Document Revision History
26=========================
27
28*Current release*:
29
30- Current applicable release is 1.0.
31
32*Existing releases*:
33
34- 1.0 : Released the 10/02/98. First version of this document.
35
36- 0.1 : First draft of this document
37
38*Planned releases*:
39
40- None planned today.
41
42DEC21140 PCI Board Generalities
43===============================
44
45.. COMMENT: XXX add crossreference to PCI Register Figure
46
47This chapter describes rapidely the PCI interface of this Ethernet controller.
48The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.
49This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
50Like other PCI devices, this board has a PCI device's header containing some
51required configuration registers, as shown in the PCI Register Figure.  By
52reading or writing these registers, a driver can obtain information about the
53type of the board, the interrupt it uses, the mapping of the chip specific
54registers, ...
55
56On Intel target, the chip specific registers can be accessed via 2 methods :
57I/O port access or PCI address mapped access. We have chosen to implement the
58PCI address access to obtain compatible source code to the port the driver on a
59PowerPC target.
60
61.. COMMENT: PCI Device's Configuration Header Space Format
62
63
64.. figure ../images/networking/PCIreg.png
65  :align: center
66  :alt: PCI Device's Configuration Header Space Format
67
68.. COMMENT: XXX add crossreference to PCI Register Figure
69
70On RTEMS, a PCI API exists. We have used it to configure the board. After
71initializing this PCI module via the ``pci_initialize()`` function, we try to
72detect the DEC21140 based ethernet board. This board is characterized by its
73Vendor ID (0x1011) and its Device ID (0x0009). We give these arguments to
74the``pcib_find_by_deviceid`` function which returns , if the device is present,
75a pointer to the configuration header space (see PCI Registers Fgure). Once
76this operation performed, the driver is able to extract the information it
77needs to configure the board internal registers, like the interrupt line, the
78base address,... The board internal registers will not be detailled here. You
79can find them in *DIGITAL Semiconductor 21140A PCI Fast Ethernet LAN Controller
80- Hardware Reference Manual*.
81
82.. COMMENT: fix citation
83
84RTEMS Driver Software Architecture
85==================================
86
87In this chapter will see the initialization phase, how the controller uses the
88host memory and the 2 threads launched at the initialization time.
89
90Initialization phase
91--------------------
92
93The DEC21140 Ethernet driver keeps the same software architecture than the
94other RTEMS ethernet drivers. The only API the programmer can use is the
95``rtems_dec21140_driver_attach(struct rtems_bsdnet_ifconfig *config)``
96function which detects the board and initializes the associated data structure
97(with registers base address, entry points to low-level initialization
98function,...), if the board is found.
99
100Once the attach function executed, the driver initializes the DEC chip. Then
101the driver connects an interrupt handler to the interrupt line driven by the
102Ethernet controller (the only interrupt which will be treated is the receive
103interrupt) and launches 2 threads : a receiver thread and a transmitter
104thread. Then the driver waits for incoming frame to give to the protocol stack
105or outcoming frame to send on the physical link.
106
107Memory Buffer
108-------------
109
110.. COMMENT: XXX add cross reference to Problem
111
112This DEC chip uses the host memory to store the incoming Ethernet frames and
113the descriptor of these frames. We have chosen to use 7 receive buffers and 1
114transmit buffer to optimize memory allocation due to cache and paging problem
115that will be explained in the section *Encountered Problems*.
116
117To reference these buffers to the DEC chip we use a buffer descriptors
118ring. The descriptor structure is defined in the Buffer Descriptor Figure.
119Each descriptor can reference one or two memory buffers. We choose to use only
120one buffer of 1520 bytes per descriptor.
121
122The difference between a receive and a transmit buffer descriptor is located in
123the status and control bits fields. We do not give details here, please refer
124to the DEC21140 Hardware Manual.
125
126.. COMMENT: Buffer Descriptor
127
128
129.. figure:: ../images/networking/recvbd.png
130  :align: center
131  :alt: Buffer Descriptor
132
133Receiver Thread
134---------------
135
136This thread is event driven. Each time a DEC PCI board interrupt occurs, the
137handler checks if this is a receive interrupt and send an event "reception" to
138the receiver thread which looks into the entire buffer descriptors ring the
139ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs to
140host processor). Each valid incoming ethernet frame is sent to the protocol
141stack and the buffer descriptor is given back to the DEC board (the host
142processor reset bit OWN, which means descriptor belongs to 21140).
143
144Transmitter Thread
145------------------
146
147This thread is also event driven. Each time an Ethernet frame is put in the
148transmit queue, an event is sent to the transmit thread, which empty the queue
149by sending each outcoming frame. Because we use only one transmit buffer, we
150are sure that the frame is well-sent before sending the next.
151
152Encountered Problems
153====================
154
155On Intel PC386 target, we were faced with a problem of memory cache management.
156Because the DEC chip uses the host memory to store the incoming frame and
157because the DEC21140 configuration registers are mapped into the PCI address
158space, we must ensure that the data read (or written) by the host processor are
159the ones written (or read) by the DEC21140 device in the host memory and not
160old data stored in the cache memory. Therefore, we had to provide a way to
161manage the cache. This module is described in the document *RTEMS Cache
162Management For Intel*. On Intel, the memory region cache management is
163available only if the paging unit is enabled.  We have used this paging
164mechanism, with 4Kb page. All the buffers allocated to store the incoming or
165outcoming frames, buffer descriptor and also the PCI address space of the DEC
166board are located in a memory space with cache disable.
167
168Concerning the buffers and their descriptors, we have tried to optimize the
169memory space in term of allocated page. One buffer has 1520 bytes, one
170descriptor has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and
171for each, 1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire
172pages. This allows not to lose too much memory or not to disable cache memory
173for a page which contains other data than buffer, which could decrease
174performance.
175
176Netboot DEC driver
177==================
178
179We use Netboot tool to load our development from a server to the target via an
180ethernet network. Currently, this tool does not support the DEC board. We plan
181to port the DEC driver for the Netboot tool.
182
183But concerning the port of the DEC driver into Netboot, we are faced with a
184problem: in RTEMS environment, the DEC driver is interrupt or event driven, in
185Netboot environment, it must be used in polling mode. It means that we will
186have to re-write some mechanisms of this driver.
187
188List of Ethernet cards using the DEC chip
189=========================================
190
191Many Ethernet adapter cards use the Tulip chip. Here is a non exhaustive list
192of adapters which support this driver :
193
194- Accton EtherDuo PCI.
195
196- Accton EN1207 All three media types supported.
197
198- Adaptec ANA6911/TX 21140-AC.
199
200- Cogent EM110 21140-A with DP83840 N-Way MII transceiver.
201
202- Cogent EM400 EM100 with 4 21140 100mbps-only ports + PCI Bridge.
203
204- Danpex EN-9400P3.
205
206- D-Link DFE500-Tx 21140-A with DP83840 transceiver.
207
208- Kingston EtherX KNE100TX 21140AE.
209
210- Netgear FX310 TX 10/100 21140AE.
211
212- SMC EtherPower10/100 With DEC21140 and 68836 SYM transceiver.
213
214- SMC EtherPower10/100 With DEC21140-AC and DP83840 MII transceiver.
215  Note: The EtherPower II uses the EPIC chip, which requires a different driver.
216
217- Surecom EP-320X DEC 21140.
218
219- Thomas Conrad TC5048.
220
221- Znyx ZX345 21140-A, usually with the DP83840 N-Way MII transciever. Some ZX345
222  cards made in 1996 have an ICS 1890 transciver instead.
223
224- ZNYX ZX348 Two 21140-A chips using ICS 1890 transcievers and either a 21052
225  or 21152 bridge. Early versions used National 83840 transcievers, but later
226  versions are depopulated ZX346 boards.
227
228- ZNYX ZX351 21140 chip with a Broadcom 100BaseT4 transciever.
229
230Our DEC driver has not been tested with all these cards, only with the D-Link
231DFE500-TX.
232
233- DEC21140 Hardware Manual DIGITAL, DIGITAL Semiconductor 21140A PCI Fast
234  Ethernet LAN Controller - Hardware Reference Manual**.
235
236- *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**.
Note: See TracBrowser for help on using the repository browser.