source: rtems/doc/networking/decdriver.t @ 2ba8875

4.104.114.84.95
Last change on this file since 2ba8875 was 2ba8875, checked in by Joel Sherrill <joel.sherrill@…>, on Apr 26, 2000 at 6:02:26 PM

Patch rtemsdoc-4.5.0-rc-0.diff from Ralf Corsepius <corsepiu@…>
which contains the bulk of converting the documentation tree to automake
and GNU conventions. Comments follow:

This is the automake port of rtemsdoc.

To apply:

cvs co rtemsdoc
cd rtemsdoc
sh cvs-rm.sh
patch -p0 < rtemsdoc-4.5.0-rc-0.diff
sh cvs-add.sh

[Attention: cvs-rm.sh and cvs-add.sh directly modify cvs]

Known bugs:
1) src2html is not supported (yet? - Is this supposed to work?)
2) all *.pdf images now are generated on-the-fly, but not yet deleted
during "make distclean"
3) All supplements, including the templated ones, get build and
installed.
4) Building outside of the source tree is completely untested and very
likely does not work.
5) Make [ps|pdf] are not (yet) supported, make [dvi|info] are supported
by automake's default texinfo rules.

Fixing 2, 3 and 5 is almost trivial and needs to be done.
4) is a matter of testing and tool-properties, for now it is simply
untested.

General issues:

  • gif vs jpg vs png. I would recommend to replace all images with pngs to avoid potential copyright issues (gif) or lack in quality (jpg, jpg is good for real world photographs, but extremely poor on artificial images, graphs).
  • pdf images do net get placed correctly in pdf-documents.
  • texinfo: We now use a local copy of texinfo-4.0's texinfo.tex in texinfo/texinfo.tex for generating infos. However pdftex's system-wide texinfo.tex and pdftexinfo.tex are used for generating *.dvi, *.ps, *.pdf.
  • .cvsignore files still missing.
  • I have renamed the supplements filename not to use c_<supplement>, because automake seems to have problems with it.

Notes:

  • Again, I recommend not to put any generated files into CVS. Here, this comprises some *texi, all *.pdf and many *.html pages. Ie. I recommend to run make maintainer-clean before checking in any files.
  • To get building started, this should be sufficient: ./bootstrap ./configure cd tools; make; cd .. make info
  • To make a public tarball: [cvs co ; ./bootstrap] ./configure cd tools; make; cd .. make info [make clean] make dist

=> This generates a rtems-<version>.tar.gz in the toplevel directory.
=> Building the tools only is required after a "cvs co", but not in a

distribution tarball.

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