source: rtems-docs/networking/networking.rst @ 5daabd2

4.115am
Last change on this file since 5daabd2 was 5daabd2, checked in by Amar Takhar <amar@…>, on 01/16/16 at 04:41:06

Initial reST documentation using Sphinx.

  • Property mode set to 100644
File size: 72.6 KB
Line 
1:orphan:
2
3
4
5.. COMMENT: %**end of header
6
7.. COMMENT: COPYRIGHT (c) 1989-2013.
8
9.. COMMENT: On-Line Applications Research Corporation (OAR).
10
11.. COMMENT: All rights reserved.
12
13.. COMMENT: Master file for the network Supplement
14
15.. COMMENT: COPYRIGHT (c) 1988-2002.
16
17.. COMMENT: On-Line Applications Research Corporation (OAR).
18
19.. COMMENT: All rights reserved.
20
21.. COMMENT: The following determines which set of the tables and figures we will use.
22
23.. COMMENT: We default to ASCII but if available TeX or HTML versions will
24
25.. COMMENT: be used instead.
26
27.. COMMENT: @clear use-html
28
29.. COMMENT: @clear use-tex
30
31.. COMMENT: The following variable says to use texinfo or html for the two column
32
33.. COMMENT: texinfo tables.  For somethings the format does not look good in html.
34
35.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
36
37.. COMMENT: good printed.
38
39.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.
40
41.. COMMENT: Title Page Stuff
42
43.. COMMENT: I don't really like having a short title page.  -joel
44
45.. COMMENT: @shorttitlepage RTEMS Network Supplement
46
47========================
48RTEMS Network Supplement
49========================
50
51.. COMMENT: COPYRIGHT (c) 1988-2015.
52
53.. COMMENT: On-Line Applications Research Corporation (OAR).
54
55.. COMMENT: All rights reserved.
56
57.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
58
59.. COMMENT: can force the copyright description onto a left hand page.
60
61COPYRIGHT © 1988 - 2015.
62
63On-Line Applications Research Corporation (OAR).
64
65The authors have used their best efforts in preparing
66this material.  These efforts include the development, research,
67and testing of the theories and programs to determine their
68effectiveness.  No warranty of any kind, expressed or implied,
69with regard to the software or the material contained in this
70document is provided.  No liability arising out of the
71application or use of any product described in this document is
72assumed.  The authors reserve the right to revise this material
73and to make changes from time to time in the content hereof
74without obligation to notify anyone of such revision or changes.
75
76The RTEMS Project is hosted at http://www.rtems.org.  Any
77inquiries concerning RTEMS, its related support components, or its
78documentation should be directed to the Community Project hosted athttp://www.rtems.org.
79
80Any inquiries for commercial services including training, support, custom
81development, application development assistance should be directed tohttp://www.rtems.com.
82
83.. COMMENT: This prevents a black box from being printed on "overflow" lines.
84
85.. COMMENT: The alternative is to rework a sentence to avoid this problem.
86
87RTEMS TCP/IP Networking Supplement
88##################################
89
90.. COMMENT: COPYRIGHT (c) 1989-2011.
91
92.. COMMENT: On-Line Applications Research Corporation (OAR).
93
94.. COMMENT: All rights reserved.
95
96Preface
97#######
98
99This document describes the RTEMS specific parts of the FreeBSD TCP/IP
100stack.  Much of this documentation was written by Eric Norum
101(eric@skatter.usask.ca)
102of the Saskatchewan Accelerator Laboratory
103who also ported the FreeBSD TCP/IP stack to RTEMS.
104
105The following is a list of resources which should be useful in trying
106to understand Ethernet:
107
108- *Charles Spurgeon’s Ethernet Web Site*
109  "This site provides extensive information about Ethernet
110  (IEEE 802.3) local area network (LAN) technology. Including
111  the original 10 Megabit per second (Mbps) system, the 100 Mbps
112  Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z)."
113  The URL is:
114  (http://www.ethermanage.com/ethernet/ethernet.html)
115
116- *TCP/IP Illustrated, Volume 1 : The Protocols* by
117  by W. Richard Stevens (ISBN: 0201633469)
118  This book provides detailed introduction to TCP/IP and includes diagnostic
119  programs which are publicly available.
120
121- *TCP/IP Illustrated, Volume 2 : The Implementation* by W. Richard
122  Stevens and Gary Wright (ISBN: 020163354X)
123  This book focuses on implementation issues regarding TCP/IP.  The
124  treat for RTEMS users is that the implementation covered is the BSD
125  stack with most of the source code described in detail.
126
127- *UNIX Network Programming, Volume 1 : 2nd Edition* by W. Richard
128  Stevens (ISBN: 0-13-490012-X)
129  This book describes how to write basic TCP/IP applications, again with primary
130  focus on the BSD stack.
131
132.. COMMENT: Written by Eric Norum
133
134.. COMMENT: COPYRIGHT (c) 1988-2002.
135
136.. COMMENT: On-Line Applications Research Corporation (OAR).
137
138.. COMMENT: All rights reserved.
139
140Network Task Structure and Data Flow
141####################################
142
143A schematic diagram of the tasks and message *mbuf* queues in a
144simple RTEMS networking application is shown in the following
145figure:
146
147.. image:: networkflow.eps
148
149.. image:: networkflow.jpg
150
151.. image:: networkflow.pdf
152
153.. image:: networkflow.png
154
155The transmit task  for each network interface is normally blocked waiting
156for a packet to arrive in the transmit queue.  Once a packet arrives, the
157transmit task may block waiting for an event from the transmit interrupt
158handler.  The transmit interrupt handler sends an RTEMS event to the transmit
159task to indicate that transmit hardware resources have become available.
160
161The receive task for each network interface is normally blocked waiting
162for an event from the receive interrupt handler.  When this event is received
163the receive task reads the packet and forwards it to the network stack
164for subsequent processing by the network task.
165
166The network task processes incoming packets and takes care of
167timed operations such as handling TCP timeouts and
168aging and removing routing table entries.
169
170The ‘Network code’ contains routines which may run in the context of
171the user application tasks, the interface receive task or the network task.
172A network semaphore ensures that
173the data structures manipulated by the network code remain consistent.
174
175.. COMMENT: Written by Eric Norum
176
177.. COMMENT: COPYRIGHT (c) 1988-2002.
178
179.. COMMENT: On-Line Applications Research Corporation (OAR).
180
181.. COMMENT: All rights reserved.
182
183Networking Driver
184#################
185
186Introduction
187============
188
189This chapter is intended to provide an introduction to the
190procedure for writing RTEMS network device drivers.
191The example code is taken from the ‘Generic 68360’ network device
192driver.  The source code for this driver is located in the``c/src/lib/libbsp/m68k/gen68360/network`` directory in the RTEMS
193source code distribution.  Having a copy of this driver at
194hand when reading the following notes will help significantly.
195
196Learn about the network device
197==============================
198
199Before starting to write the network driver become completely
200familiar with the programmer’s view of the device.
201The following points list some of the details of the
202device that must be understood before a driver can be written.
203
204- Does the device use DMA to transfer packets to and from
205  memory or does the processor have to
206  copy packets to and from memory on the device?
207
208- If the device uses DMA, is it capable of forming a single
209  outgoing packet from multiple fragments scattered in separate
210  memory buffers?
211
212- If the device uses DMA, is it capable of chaining multiple
213  outgoing packets, or does each outgoing packet require
214  intervention by the driver?
215
216- Does the device automatically pad short frames to the minimum
217  64 bytes or does the driver have to supply the padding?
218
219- Does the device automatically retry a transmission on detection
220  of a collision?
221
222- If the device uses DMA, is it capable of buffering multiple
223  packets to memory, or does the receiver have to be restarted
224  after the arrival of each packet?
225
226- How are packets that are too short, too long, or received with
227  CRC errors handled?  Does the device automatically continue
228  reception or does the driver have to intervene?
229
230- How is the device Ethernet address set?  How is the device
231  programmed to accept or reject broadcast and multicast packets?
232
233- What interrupts does the device generate?  Does it generate an
234  interrupt for each incoming packet, or only for packets received
235  without error?  Does it generate an interrupt for each packet
236  transmitted, or only when the transmit queue is empty?  What
237  happens when a transmit error is detected?
238
239In addition, some controllers have specific questions regarding
240board specific configuration.  For example, the SONIC Ethernet
241controller has a very configurable data bus interface.  It can
242even be configured for sixteen and thirty-two bit data buses.  This
243type of information should be obtained from the board vendor.
244
245Understand the network scheduling conventions
246=============================================
247
248When writing code for the driver transmit and receive tasks,
249take care to follow the network scheduling conventions.  All tasks
250which are associated with networking share various
251data structures and resources.  To ensure the consistency
252of these structures the tasks
253execute only when they hold the network semaphore (``rtems_bsdnet_semaphore``).
254The transmit and receive tasks must abide by this protocol.  Be very
255careful to avoid ‘deadly embraces’ with the other network tasks.
256A number of routines are provided to make it easier for the network
257driver code to conform to the network task scheduling conventions.
258
259- ``void rtems_bsdnet_semaphore_release(void)``
260  This function releases the network semaphore.
261  The network driver tasks must call this function immediately before
262  making any blocking RTEMS request.
263
264- ``void rtems_bsdnet_semaphore_obtain(void)``
265  This function obtains the network semaphore.
266  If a network driver task has released the network semaphore to allow other
267  network-related tasks to run while the task blocks, then this function must
268  be called to reobtain the semaphore immediately after the return from the
269  blocking RTEMS request.
270
271- ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set \*)``
272  The network driver task should call this function when it wishes to wait
273  for an event.  This function releases the network semaphore,
274  calls ``rtems_event_receive`` to wait for the specified event
275  or events and reobtains the semaphore.
276  The value returned is the value returned by the ``rtems_event_receive``.
277
278Network Driver Makefile
279=======================
280
281Network drivers are considered part of the BSD network package and as such
282are to be compiled with the appropriate flags.  This can be accomplished by
283adding ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``.
284If the driver is inside the RTEMS source tree or is built using the
285RTEMS application Makefiles, then adding the following line accomplishes
286this:
287.. code:: c
288
289    DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
290
291This is equivalent to the following list of definitions.  Early versions
292of the RTEMS BSD network stack required that all of these be defined.
293.. code:: c
294
295    -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \\
296    -DDIAGNOSTIC -DBOOTP_COMPAT
297
298Defining these macros tells the network header files that the driver
299is to be compiled with extended visibility into the network stack.  This
300is in sharp contrast to applications that simply use the network stack.
301Applications do not require this level of visibility and should stick
302to the portable application level API.
303
304As a direct result of being logically internal to the network stack,
305network drivers use the BSD memory allocation routines   This means,
306for example, that malloc takes three arguments.  See the SONIC
307device driver (``c/src/lib/libchip/network/sonic.c``) for an example
308of this.  Because of this, network drivers should not include``<stdlib.h>``.  Doing so will result in conflicting definitions
309of ``malloc()``.
310
311*Application level* code including network servers such as the FTP
312daemon are *not* part of the BSD kernel network code and should not be
313compiled with the BSD network flags.  They should include``<stdlib.h>`` and not define the network stack visibility
314macros.
315
316Write the Driver Attach Function
317================================
318
319The driver attach function is responsible for configuring the driver
320and making the connection between the network stack
321and the driver.
322
323Driver attach functions take a pointer to an``rtems_bsdnet_ifconfig`` structure as their only argument.
324and set the driver parameters based on the
325values in this structure.  If an entry in the configuration
326structure is zero the attach function chooses an
327appropriate default value for that parameter.
328
329The driver should then set up several fields in the ifnet structure
330in the device-dependent data structure supplied and maintained by the driver:
331
332``ifp->if_softc``
333    Pointer to the device-dependent data.  The first entry
334    in the device-dependent data structure must be an ``arpcom``
335    structure.
336
337``ifp->if_name``
338    The name of the device.  The network stack uses this string
339    and the device number for device name lookups.  The device name should
340    be obtained from the ``name`` entry in the configuration structure.
341
342``ifp->if_unit``
343    The device number.  The network stack uses this number and the
344    device name for device name lookups.  For example, if``ifp->if_name`` is ‘``scc``’ and ``ifp->if_unit`` is ‘``1``’,
345    the full device name would be ‘``scc1``’.  The unit number should be
346    obtained from the ‘name’ entry in the configuration structure.
347
348``ifp->if_mtu``
349    The maximum transmission unit for the device.  For Ethernet
350    devices this value should almost always be 1500.
351
352``ifp->if_flags``
353    The device flags.  Ethernet devices should set the flags
354    to ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the
355    device can broadcast packets to multiple destinations
356    and does not receive and transmit at the same time.
357
358``ifp->if_snd.ifq_maxlen``
359    The maximum length of the queue of packets waiting to be
360    sent to the driver.  This is normally set to ``ifqmaxlen``.
361
362``ifp->if_init``
363    The address of the driver initialization function.
364
365``ifp->if_start``
366    The address of the driver start function.
367
368``ifp->if_ioctl``
369    The address of the driver ioctl function.
370
371``ifp->if_output``
372    The address of the output function.  Ethernet devices
373    should set this to ``ether_output``.
374
375RTEMS provides a function to parse the driver name in the
376configuration structure into a device name and unit number.
377.. code:: c
378
379    int rtems_bsdnet_parse_driver_name (
380    const struct rtems_bsdnet_ifconfig \*config,
381    char \**namep
382    );
383
384The function takes two arguments; a pointer to the configuration
385structure and a pointer to a pointer to a character.  The function
386parses the configuration name entry, allocates memory for the driver
387name, places the driver name in this memory, sets the second argument
388to point to the name and returns the unit number.
389On error, a message is printed and -1 is returned.
390
391Once the attach function  has set up the above entries it must link the
392driver data structure onto the list of devices by
393calling ``if_attach``.  Ethernet devices should then
394call ``ether_ifattach``.  Both functions take a pointer to the
395device’s ``ifnet`` structure as their only argument.
396
397The attach function should return a non-zero value to indicate that
398the driver has been successfully configured and attached.
399
400Write the Driver Start Function.
401================================
402
403This function is called each time the network stack wants to start the
404transmitter.  This occures whenever the network stack adds a packet
405to a device’s send queue and the ``IFF_OACTIVE`` bit in the
406device’s ``if_flags`` is not set.
407
408For many devices this function need only set the ``IFF_OACTIVE`` bit in the``if_flags`` and send an event to the transmit task
409indicating that a packet is in the driver transmit queue.
410
411Write the Driver Initialization Function.
412=========================================
413
414This function should initialize the device, attach to interrupt handler,
415and start the driver transmit and receive tasks.  The function
416.. code:: c
417
418    rtems_id
419    rtems_bsdnet_newproc (char \*name,
420    int stacksize,
421    void(\*entry)(void \*),
422    void \*arg);
423
424should be used to start the driver tasks.
425
426Note that the network stack may call the driver initialization function more
427than once.
428Make sure multiple versions of the receive and transmit tasks are not accidentally
429started.
430
431Write the Driver Transmit Task
432==============================
433
434This task is reponsible for removing packets from the driver send queue and sending them to the device.  The task should block waiting for an event from the
435driver start function indicating that packets are waiting to be transmitted.
436When the transmit task has drained the driver send queue the task should clear
437the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another outgoing
438packet is queued.
439
440Write the Driver Receive Task
441=============================
442
443This task should block until a packet arrives from the device.  If the
444device is an Ethernet interface the function ``ether_input`` should be called
445to forward the packet to the network stack.   The arguments to ``ether_input``
446are a pointer to the interface data structure, a pointer to the ethernet
447header and a pointer to an mbuf containing the packet itself.
448
449Write the Driver Interrupt Handler
450==================================
451
452A typical interrupt handler will do nothing more than the hardware
453manipulation required to acknowledge the interrupt and send an RTEMS event
454to wake up the driver receive or transmit task waiting for the event.
455Network interface interrupt handlers must not make any calls to other
456network routines.
457
458Write the Driver IOCTL Function
459===============================
460
461This function handles ioctl requests directed at the device.  The ioctl
462commands which must be handled are:
463
464``SIOCGIFADDR``
465
466``SIOCSIFADDR``
467    If the device is an Ethernet interface these
468    commands should be passed on to ``ether_ioctl``.
469
470``SIOCSIFFLAGS``
471    This command should be used to start or stop the device,
472    depending on the state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
473    ``IFF_RUNNING``
474        Stop the device.
475    ``IFF_UP``
476        Start the device.
477    ``IFF_UP|IFF_RUNNING``
478        Stop then start the device.
479    ``0``
480        Do nothing.
481
482Write the Driver Statistic-Printing Function
483============================================
484
485This function should print the values of any statistic/diagnostic
486counters the network driver may use.  The driver ioctl function should call
487the statistic-printing function when the ioctl command is``SIO_RTEMS_SHOW_STATS``.
488
489.. COMMENT: Written by Eric Norum
490
491.. COMMENT: COPYRIGHT (c) 1988-2002.
492
493.. COMMENT: On-Line Applications Research Corporation (OAR).
494
495.. COMMENT: All rights reserved.
496
497Using Networking in an RTEMS Application
498########################################
499
500Makefile changes
501================
502
503Including the required managers
504-------------------------------
505
506The FreeBSD networking code requires several RTEMS managers
507in the application:
508.. code:: c
509
510    MANAGERS = io event semaphore
511
512Increasing the size of the heap
513-------------------------------
514
515The networking tasks allocate a lot of memory.  For most applications
516the heap should be at least 256 kbytes.
517The amount of memory set aside for the heap can be adjusted by setting
518the ``CFLAGS_LD`` definition as shown below:
519.. code:: c
520
521    CFLAGS_LD += -Wl,--defsym -Wl,HeapSize=0x80000
522
523This sets aside 512 kbytes of memory for the heap.
524
525System Configuration
526====================
527
528The networking tasks allocate some RTEMS objects.  These
529must be accounted for in the application configuration table.  The following
530lists the requirements.
531
532*TASKS*
533    One network task plus a receive and transmit task for each device.
534
535*SEMAPHORES*
536    One network semaphore plus one syslog mutex semaphore if the application uses
537    openlog/syslog.
538
539*EVENTS*
540    The network stack uses ``RTEMS_EVENT_24`` and ``RTEMS_EVENT_25``.
541    This has no effect on the application configuration, but
542    application tasks which call the network functions should not
543    use these events for other purposes.
544
545Initialization
546==============
547
548Additional include files
549------------------------
550
551The source file which declares the network configuration
552structures and calls the network initialization function must include
553.. code:: c
554
555    #include <rtems/rtems_bsdnet.h>
556
557Network Configuration
558---------------------
559
560The network configuration is specified by declaring
561and initializing the ``rtems_bsdnet_config``
562structure.
563.. code:: c
564
565    struct rtems_bsdnet_config {
566    /*
567    * This entry points to the head of the ifconfig chain.
568    \*/
569    struct rtems_bsdnet_ifconfig \*ifconfig;
570    /*
571    * This entry should be rtems_bsdnet_do_bootp if BOOTP
572    * is being used to configure the network, and NULL
573    * if BOOTP is not being used.
574    \*/
575    void                    (\*bootp)(void);
576    /*
577    * The remaining items can be initialized to 0, in
578    * which case the default value will be used.
579    \*/
580    rtems_task_priority  network_task_priority;  /* 100        \*/
581    unsigned long        mbuf_bytecount;         /* 64 kbytes  \*/
582    unsigned long        mbuf_cluster_bytecount; /* 128 kbytes \*/
583    char                \*hostname;               /* BOOTP      \*/
584    char                \*domainname;             /* BOOTP      \*/
585    char                \*gateway;                /* BOOTP      \*/
586    char                \*log_host;               /* BOOTP      \*/
587    char                \*name_server[3];         /* BOOTP      \*/
588    char                \*ntp_server[3];          /* BOOTP      \*/
589    unsigned long        sb_efficiency;          /* 2          \*/
590    /* UDP TX: 9216 bytes \*/
591    unsigned long        udp_tx_buf_size;
592    /* UDP RX: 40 * (1024 + sizeof(struct sockaddr_in)) \*/
593    unsigned long        udp_rx_buf_size;
594    /* TCP TX: 16 * 1024 bytes \*/
595    unsigned long        tcp_tx_buf_size;
596    /* TCP TX: 16 * 1024 bytes \*/
597    unsigned long        tcp_rx_buf_size;
598    /* Default Network Tasks CPU Affinity \*/
599    #ifdef RTEMS_SMP
600    const cpu_set_t     \*network_task_cpuset;
601    size_t               network_task_cpuset_size;
602    #endif
603    };
604
605The structure entries are described in the following table.
606If your application uses BOOTP/DHCP to obtain network configuration
607information and if you are happy with the default values described
608below, you need to provide only the first two entries in this structure.
609
610``struct rtems_bsdnet_ifconfig \*ifconfig``
611    A pointer to the first configuration structure of the first network
612    device.  This structure is described in the following section.
613    You must provide a value for this entry since there is no default value for it.
614
615``void (\*bootp)(void)``
616    This entry should be set to ``rtems_bsdnet_do_bootp`` if your
617    application by default uses the BOOTP/DHCP client protocol to obtain
618    network configuration information.  It should be set to ``NULL`` if
619    your application does not use BOOTP/DHCP.
620    You can also use ``rtems_bsdnet_do_bootp_rootfs`` to have a set of
621    standard files created with the information return by the BOOTP/DHCP
622    protocol. The IP address is added to :file:`/etc/hosts` with the host
623    name and domain returned. If no host name or domain is returned``me.mydomain`` is used. The BOOTP/DHCP server’s address is also
624    added to :file:`/etc/hosts`. The domain name server listed in the
625    BOOTP/DHCP information are added to :file:`/etc/resolv.conf`. A``search`` record is also added if a domain is returned. The files
626    are created if they do not exist.
627    The default ``rtems_bsdnet_do_bootp`` and``rtems_bsdnet_do_bootp_rootfs`` handlers will loop for-ever
628    waiting for a BOOTP/DHCP server to respond. If an error is detected
629    such as not valid interface or valid hardware address the target will
630    reboot allowing any hardware reset to correct itself.
631    You can provide your own custom handler which allows you to perform
632    an initialization that meets your specific system requirements. For
633    example you could try BOOTP/DHCP then enter a configuration tool if no
634    server is found allowing the user to switch to a static configuration.
635
636``int network_task_priority``
637    The priority at which the network task and network device
638    receive and transmit tasks will run.
639    If a value of 0 is specified the tasks will run at priority 100.
640
641``unsigned long mbuf_bytecount``
642    The number of bytes to allocate from the heap for use as mbufs.
643    If a value of 0 is specified, 64 kbytes will be allocated.
644
645``unsigned long mbuf_cluster_bytecount``
646    The number of bytes to allocate from the heap for use as mbuf clusters.
647    If a value of 0 is specified, 128 kbytes will be allocated.
648
649``char \*hostname``
650    The host name of the system.
651    If this, or any of the following, entries are ``NULL`` the value
652    may be obtained from a BOOTP/DHCP server.
653
654``char \*domainname``
655    The name of the Internet domain to which the system belongs.
656
657``char \*gateway``
658    The Internet host number of the network gateway machine,
659    specified in ’dotted decimal’ (``129.128.4.1``) form.
660
661``char \*log_host``
662    The Internet host number of the machine to which ``syslog`` messages
663    will be sent.
664
665``char \*name_server[3]``
666    The Internet host numbers of up to three machines to be used as
667    Internet Domain Name Servers.
668
669``char \*ntp_server[3]``
670    The Internet host numbers of up to three machines to be used as
671    Network Time Protocol (NTP) Servers.
672
673``unsigned long sb_efficiency``
674    This is the first of five configuration parameters related to
675    the amount of memory each socket may consume for buffers.  The
676    TCP/IP stack reserves buffers (e.g. mbufs) for each open socket.  The
677    TCP/IP stack has different limits for the transmit and receive
678    buffers associated with each TCP and UDP socket.  By tuning these
679    parameters, the application developer can make trade-offs between
680    memory consumption and performance.  The default parameters favor
681    performance over memory consumption.  Seehttp://www.rtems.org/ml/rtems-users/2004/february/msg00200.html
682    for more details but note that after the RTEMS 4.8 release series,
683    the sb_efficiency default was changed from ``8`` to ``2``.
684    The user should also be aware of the ``SO_SNDBUF`` and ``SO_RCVBUF``
685    IO control operations.  These can be used to specify the
686    send and receive buffer sizes for a specific socket.  There
687    is no standard IO control to change the ``sb_efficiency`` factor.
688    The ``sb_efficiency`` parameter is a buffering factor used
689    in the implementation of the TCP/IP stack.  The default is ``2``
690    which indicates double buffering.  When allocating memory for each
691    socket, this number is multiplied by the buffer sizes for that socket.
692
693``unsigned long udp_tx_buf_size``
694    This configuration parameter specifies the maximum amount of
695    buffer memory which may be used for UDP sockets to transmit
696    with.  The default size is 9216 bytes which corresponds to
697    the maximum datagram size.
698
699``unsigned long udp_rx_buf_size``
700    This configuration parameter specifies the maximum amount of
701    buffer memory which may be used for UDP sockets to receive
702    into.  The default size is the following length in bytes:
703    .. code:: c
704        40 * (1024 + sizeof(struct sockaddr_in)
705
706``unsigned long tcp_tx_buf_size``
707    This configuration parameter specifies the maximum amount of
708    buffer memory which may be used for TCP sockets to transmit
709    with.  The default size is sixteen kilobytes.
710
711``unsigned long tcp_rx_buf_size``
712    This configuration parameter specifies the maximum amount of
713    buffer memory which may be used for TCP sockets to receive
714    into.  The default size is sixteen kilobytes.
715
716``const cpu_set_t \*network_task_cpuset``
717    This configuration parameter specifies the CPU affinity of the
718    network task. If set to ``0`` the network task can be scheduled on
719    any CPU. Only available in SMP configurations.
720
721``size_t network_task_cpuset_size``
722    This configuration parameter specifies the size of the``network_task_cpuset`` used. Only available in SMP configurations.
723
724In addition, the following fields in the ``rtems_bsdnet_ifconfig``
725are of interest.
726
727*int port*
728    The I/O port number (ex: 0x240) on which the external Ethernet
729    can be accessed.
730
731*int irno*
732    The interrupt number of the external Ethernet controller.
733
734*int bpar*
735    The address of the shared memory on the external Ethernet controller.
736
737Network device configuration
738----------------------------
739
740Network devices are specified and configured by declaring and initializing a``struct rtems_bsdnet_ifconfig`` structure for each network device.
741
742The structure entries are described in the following table.  An application
743which uses a single network interface, gets network configuration information
744from a BOOTP/DHCP server, and uses the default values for all driver
745parameters needs to initialize only the first two entries in the
746structure.
747
748``char \*name``
749    The full name of the network device.  This name consists of the
750    driver name and the unit number (e.g. ``"scc1"``).
751    The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_NAME as
752    the name of the primary (or only) network driver.
753
754``int (\*attach)(struct rtems_bsdnet_ifconfig \*conf)``
755    The address of the driver ``attach`` function.   The network
756    initialization function calls this function to configure the driver and
757    attach it to the network stack.
758    The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_ATTACH as
759    the name of the  attach function of the primary (or only) network driver.
760
761``struct rtems_bsdnet_ifconfig \*next``
762    A pointer to the network device configuration structure for the next network
763    interface, or ``NULL`` if this is the configuration structure of the
764    last network interface.
765
766``char \*ip_address``
767    The Internet address of the device,
768    specified in ‘dotted decimal’ (``129.128.4.2``) form, or ``NULL``
769    if the device configuration information is being obtained from a
770    BOOTP/DHCP server.
771
772``char \*ip_netmask``
773    The Internet inetwork mask of the device,
774    specified in ‘dotted decimal’ (``255.255.255.0``) form, or ``NULL``
775    if the device configuration information is being obtained from a
776    BOOTP/DHCP server.
777
778``void \*hardware_address``
779    The hardware address of the device, or ``NULL`` if the driver is
780    to obtain the hardware address in some other way (usually  by reading
781    it from the device or from the bootstrap ROM).
782
783``int ignore_broadcast``
784    Zero if the device is to accept broadcast packets, non-zero if the device
785    is to ignore broadcast packets.
786
787``int mtu``
788    The maximum transmission unit of the device, or zero if the driver
789    is to choose a default value (typically 1500 for Ethernet devices).
790
791``int rbuf_count``
792    The number of receive buffers to use, or zero if the driver is to
793    choose a default value
794
795``int xbuf_count``
796    The number of transmit buffers to use, or zero if the driver is to
797    choose a default value
798    Keep in mind that some network devices may use 4 or more
799    transmit descriptors for a single transmit buffer.
800
801A complete network configuration specification can be as simple as the one
802shown in the following example.
803This configuration uses a single network interface, gets
804network configuration information
805from a BOOTP/DHCP server, and uses the default values for all driver
806parameters.
807.. code:: c
808
809    static struct rtems_bsdnet_ifconfig netdriver_config = {
810    RTEMS_BSP_NETWORK_DRIVER_NAME,
811    RTEMS_BSP_NETWORK_DRIVER_ATTACH
812    };
813    struct rtems_bsdnet_config rtems_bsdnet_config = {
814    &netdriver_config,
815    rtems_bsdnet_do_bootp,
816    };
817
818Network initialization
819----------------------
820
821The networking tasks must be started before any network I/O operations
822can be performed. This is done by calling:
823
824.. code:: c
825
826    rtems_bsdnet_initialize_network ();
827
828This function is declared in ``rtems/rtems_bsdnet.h``.
829t returns 0 on success and -1 on failure with an error code
830in ``errno``.  It is not possible to undo the effects of
831a partial initialization, though, so the function can be
832called only once irregardless of the return code.  Consequently,
833if the condition for the failure can be corrected, the
834system must be reset to permit another network initialization
835attempt.
836
837Application Programming Interface
838=================================
839
840The RTEMS network package provides almost a complete set of BSD network
841services.  The network functions work like their BSD counterparts
842with the following exceptions:
843
844- A given socket can be read or written by only one task at a time.
845
846- The ``select`` function only works for file descriptors associated
847  with sockets.
848
849- You must call ``openlog`` before calling any of the ``syslog`` functions.
850
851- *Some of the network functions are not thread-safe.*
852  For example the following functions return a pointer to a static
853  buffer which remains valid only until the next call:
854  ``gethostbyaddr``
855  ``gethostbyname``
856  ``inet_ntoa``
857      (``inet_ntop`` is thread-safe, though).
858
859- The RTEMS network package gathers statistics.
860
861- Addition of a mechanism to "tap onto" an interface
862  and monitor every packet received and transmitted.
863
864- Addition of ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP`` socket options.
865
866Some of the new features are discussed in more detail in the following
867sections.
868
869Network Statistics
870------------------
871
872There are a number of functions to print statistics gathered by
873the network stack.
874These function are declared in ``rtems/rtems_bsdnet.h``.
875
876``rtems_bsdnet_show_if_stats``
877    Display statistics gathered by network interfaces.
878
879``rtems_bsdnet_show_ip_stats``
880    Display IP packet statistics.
881
882``rtems_bsdnet_show_icmp_stats``
883    Display ICMP packet statistics.
884
885``rtems_bsdnet_show_tcp_stats``
886    Display TCP packet statistics.
887
888``rtems_bsdnet_show_udp_stats``
889    Display UDP packet statistics.
890
891``rtems_bsdnet_show_mbuf_stats``
892    Display mbuf statistics.
893
894``rtems_bsdnet_show_inet_routes``
895    Display the routing table.
896
897Tapping Into an Interface
898-------------------------
899
900RTEMS add two new ioctls to the BSD networking code:
901SIOCSIFTAP and SIOCGIFTAP.  These may be used to set and get a*tap function*.  The tap function will be called for every
902Ethernet packet received by the interface.
903
904These are called like other interface ioctls, such as SIOCSIFADDR.
905When setting the tap function with SIOCSIFTAP, set the ifr_tap field
906of the ifreq struct to the tap function.  When retrieving the tap
907function with SIOCGIFTAP, the current tap function will be returned in
908the ifr_tap field.  To stop tapping packets, call SIOCSIFTAP with a
909ifr_tap field of 0.
910
911The tap function is called like this:
912.. code:: c
913
914    int tap (struct ifnet \*, struct ether_header \*, struct mbuf \*)
915
916The tap function should return 1 if the packet was fully handled, in
917which case the caller will simply discard the mbuf.  The tap function
918should return 0 if the packet should be passed up to the higher
919networking layers.
920
921The tap function is called with the network semaphore locked.  It must
922not make any calls on the application levels of the networking level
923itself.  It is safe to call other non-networking RTEMS functions.
924
925Socket Options
926--------------
927
928RTEMS adds two new ``SOL_SOCKET`` level options for ``setsockopt`` and``getsockopt``: ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP``.  For both, the
929option value should point to a sockwakeup structure.  The sockwakeup
930structure has the following fields:
931.. code:: c
932
933    void    (\*sw_pfn) (struct socket \*, caddr_t);
934    caddr_t sw_arg;
935
936These options are used to set a callback function to be called when, for
937example, there is
938data available from the socket (``SO_RCVWAKEUP``) and when there is space
939available to accept data written to the socket (``SO_SNDWAKEUP``).
940
941If ``setsockopt`` is called with the ``SO_RCVWAKEUP`` option, and the``sw_pfn`` field is not zero, then when there is data
942available to be read from
943the socket, the function pointed to by the ``sw_pfn`` field will be
944called.  A pointer to the socket structure will be passed as the first
945argument to the function.  The ``sw_arg`` field set by the``SO_RCVWAKEUP`` call will be passed as the second argument to the function.
946
947If ``setsockopt`` is called with the ``SO_SNDWAKEUP``
948function, and the ``sw_pfn`` field is not zero, then when
949there is space available to accept data written to the socket,
950the function pointed to by the ``sw_pfn`` field
951will be called.  The arguments passed to the function will be as with``SO_SNDWAKEUP``.
952
953When the function is called, the network semaphore will be locked and
954the callback function runs in the context of the networking task.
955The function must be careful not to call any networking functions.  It
956is OK to call an RTEMS function; for example, it is OK to send an
957RTEMS event.
958
959The purpose of these callback functions is to permit a more efficient
960alternative to the select call when dealing with a large number of
961sockets.
962
963The callbacks are called by the same criteria that the select
964function uses for indicating "ready" sockets. In Stevens *Unix
965Network Programming* on page 153-154 in the section "Under what Conditions
966Is a Descriptor Ready?" you will find the definitive list of conditions
967for readable and writable that also determine when the functions are
968called.
969
970When the number of received bytes equals or exceeds the socket receive
971buffer "low water mark" (default 1 byte) you get a readable callback. If
972there are 100 bytes in the receive buffer and you only read 1, you will
973not immediately get another callback. However, you will get another
974callback after you read the remaining 99 bytes and at least 1 more byte
975arrives. Using a non-blocking socket you should probably read until it
976produces error  EWOULDBLOCK and then allow the readable callback to tell
977you when more data has arrived.  (Condition 1.a.)
978
979For sending, when the socket is connected and the free space becomes at
980or above the "low water mark" for the send buffer (default 4096 bytes)
981you will receive a writable callback. You don’t get continuous callbacks
982if you don’t write anything. Using a non-blocking write socket, you can
983then call write until it returns a value less than the amount of data
984requested to be sent or it produces error EWOULDBLOCK (indicating buffer
985full and no longer writable). When this happens you can
986try the write again, but it is often better to go do other things and
987let the writable callback tell you when space is available to send
988again. You only get a writable callback when the free space transitions
989to above the "low water mark" and not every time you
990write to a non-full send buffer. (Condition 2.a.)
991
992The remaining conditions enumerated by Stevens handle the fact that
993sockets become readable and/or writable when connects, disconnects and
994errors occur, not just when data is received or sent. For example, when
995a server "listening" socket becomes readable it indicates that a client
996has connected and accept can be called without blocking, not that
997network data was received (Condition 1.c).
998
999Adding an IP Alias
1000------------------
1001
1002The following code snippet adds an IP alias:
1003.. code:: c
1004
1005    void addAlias(const char \*pName, const char \*pAddr, const char \*pMask)
1006    {
1007    struct ifaliasreq      aliasreq;
1008    struct sockaddr_in    \*in;
1009    /* initialize alias request \*/
1010    memset(&aliasreq, 0, sizeof(aliasreq));
1011    sprintf(aliasreq.ifra_name, pName);
1012    /* initialize alias address \*/
1013    in = (struct sockaddr_in \*)&aliasreq.ifra_addr;
1014    in->sin_family = AF_INET;
1015    in->sin_len    = sizeof(aliasreq.ifra_addr);
1016    in->sin_addr.s_addr = inet_addr(pAddr);
1017    /* initialize alias mask \*/
1018    in = (struct sockaddr_in \*)&aliasreq.ifra_mask;
1019    in->sin_family = AF_INET;
1020    in->sin_len    = sizeof(aliasreq.ifra_mask);
1021    in->sin_addr.s_addr = inet_addr(pMask);
1022    /* call to setup the alias \*/
1023    rtems_bsdnet_ifconfig(pName, SIOCAIFADDR, &aliasreq);
1024    }
1025
1026Thanks to `Mike Seirs <mailto:mikes@poliac.com>`_ for this example
1027code.
1028
1029Adding a Default Route
1030----------------------
1031
1032The function provided in this section is functionally equivalent to
1033the command ``route add default gw yyy.yyy.yyy.yyy``:
1034.. code:: c
1035
1036    void mon_ifconfig(int argc, char \*argv[],  unsigned32 command_arg,
1037    bool verbose)
1038    {
1039    struct sockaddr_in  ipaddr;
1040    struct sockaddr_in  dstaddr;
1041    struct sockaddr_in  netmask;
1042    struct sockaddr_in  broadcast;
1043    char               \*iface;
1044    int                 f_ip        = 0;
1045    int                 f_ptp       = 0;
1046    int                 f_netmask   = 0;
1047    int                 f_up        = 0;
1048    int                 f_down      = 0;
1049    int                 f_bcast     = 0;
1050    int                 cur_idx;
1051    int                 rc;
1052    int                 flags;
1053    bzero((void*) &ipaddr, sizeof(ipaddr));
1054    bzero((void*) &dstaddr, sizeof(dstaddr));
1055    bzero((void*) &netmask, sizeof(netmask));
1056    bzero((void*) &broadcast, sizeof(broadcast));
1057    ipaddr.sin_len = sizeof(ipaddr);
1058    ipaddr.sin_family = AF_INET;
1059    dstaddr.sin_len = sizeof(dstaddr);
1060    dstaddr.sin_family = AF_INET;
1061    netmask.sin_len = sizeof(netmask);
1062    netmask.sin_family = AF_INET;
1063    broadcast.sin_len = sizeof(broadcast);
1064    broadcast.sin_family = AF_INET;
1065    cur_idx = 0;
1066    if (argc <= 1) {
1067    /* display all interfaces \*/
1068    iface = NULL;
1069    cur_idx += 1;
1070    } else {
1071    iface = argv[1];
1072    if (isdigit(\*argv[2])) {
1073    if (inet_pton(AF_INET, argv[2], &ipaddr.sin_addr) < 0) {
1074    printf("bad ip address: %s\\n", argv[2]);
1075    return;
1076    }
1077    f_ip = 1;
1078    cur_idx += 3;
1079    } else {
1080    cur_idx += 2;
1081    }
1082    }
1083    if ((f_down !=0) && (f_ip != 0)) {
1084    f_up = 1;
1085    }
1086    while(argc > cur_idx) {
1087    if (strcmp(argv[cur_idx], "up") == 0) {
1088    f_up = 1;
1089    if (f_down != 0) {
1090    printf("Can't make interface up and down\\n");
1091    }
1092    } else if(strcmp(argv[cur_idx], "down") == 0) {
1093    f_down = 1;
1094    if (f_up != 0) {
1095    printf("Can't make interface up and down\\n");
1096    }
1097    } else if(strcmp(argv[cur_idx], "netmask") == 0) {
1098    if ((cur_idx + 1) >= argc) {
1099    printf("No netmask address\\n");
1100    return;
1101    }
1102    if (inet_pton(AF_INET, argv[cur_idx+1], &netmask.sin_addr) < 0) {
1103    printf("bad netmask: %s\\n", argv[cur_idx]);
1104    return;
1105    }
1106    f_netmask = 1;
1107    cur_idx += 1;
1108    } else if(strcmp(argv[cur_idx], "broadcast") == 0) {
1109    if ((cur_idx + 1) >= argc) {
1110    printf("No broadcast address\\n");
1111    return;
1112    }
1113    if (inet_pton(AF_INET, argv[cur_idx+1], &broadcast.sin_addr) < 0) {
1114    printf("bad broadcast: %s\\n", argv[cur_idx]);
1115    return;
1116    }
1117    f_bcast = 1;
1118    cur_idx += 1;
1119    } else if(strcmp(argv[cur_idx], "pointopoint") == 0) {
1120    if ((cur_idx + 1) >= argc) {
1121    printf("No pointopoint address\\n");
1122    return;
1123    }
1124    if (inet_pton(AF_INET, argv[cur_idx+1], &dstaddr.sin_addr) < 0) {
1125    printf("bad pointopoint: %s\\n", argv[cur_idx]);
1126    return;
1127    }
1128    f_ptp = 1;
1129    cur_idx += 1;
1130    } else {
1131    printf("Bad parameter: %s\\n", argv[cur_idx]);
1132    return;
1133    }
1134    cur_idx += 1;
1135    }
1136    printf("ifconfig ");
1137    if (iface != NULL) {
1138    printf("%s ", iface);
1139    if (f_ip != 0) {
1140    char str[256];
1141    inet_ntop(AF_INET, &ipaddr.sin_addr, str, 256);
1142    printf("%s ", str);
1143    }
1144    if (f_netmask != 0) {
1145    char str[256];
1146    inet_ntop(AF_INET, &netmask.sin_addr, str, 256);
1147    printf("netmask %s ", str);
1148    }
1149    if (f_bcast != 0) {
1150    char str[256];
1151    inet_ntop(AF_INET, &broadcast.sin_addr, str, 256);
1152    printf("broadcast %s ", str);
1153    }
1154    if (f_ptp != 0) {
1155    char str[256];
1156    inet_ntop(AF_INET, &dstaddr.sin_addr, str, 256);
1157    printf("pointopoint %s ", str);
1158    }
1159    if (f_up != 0) {
1160    printf("up\\n");
1161    } else if (f_down != 0) {
1162    printf("down\\n");
1163    } else {
1164    printf("\\n");
1165    }
1166    }
1167    if ((iface == NULL) \|| ((f_ip == 0) && (f_down == 0) && (f_up == 0))) {
1168    rtems_bsdnet_show_if_stats();
1169    return;
1170    }
1171    flags = 0;
1172    if (f_netmask) {
1173    rc = rtems_bsdnet_ifconfig(iface, SIOCSIFNETMASK, &netmask);
1174    if (rc < 0) {
1175    printf("Could not set netmask: %s\\n", strerror(errno));
1176    return;
1177    }
1178    }
1179    if (f_bcast) {
1180    rc = rtems_bsdnet_ifconfig(iface, SIOCSIFBRDADDR, &broadcast);
1181    if (rc < 0) {
1182    printf("Could not set broadcast: %s\\n", strerror(errno));
1183    return;
1184    }
1185    }
1186    if (f_ptp) {
1187    rc = rtems_bsdnet_ifconfig(iface, SIOCSIFDSTADDR, &dstaddr);
1188    if (rc < 0) {
1189    printf("Could not set destination address: %s\\n", strerror(errno));
1190    return;
1191    }
1192    flags \|= IFF_POINTOPOINT;
1193    }
1194    /* This must come _after_ setting the netmask, broadcast addresses \*/
1195    if (f_ip) {
1196    rc = rtems_bsdnet_ifconfig(iface, SIOCSIFADDR, &ipaddr);
1197    if (rc < 0) {
1198    printf("Could not set IP address: %s\\n", strerror(errno));
1199    return;
1200    }
1201    }
1202    if (f_up != 0) {
1203    flags \|= IFF_UP;
1204    }
1205    if (f_down != 0) {
1206    printf("Warning: taking interfaces down is not supported\\n");
1207    }
1208    rc = rtems_bsdnet_ifconfig(iface, SIOCSIFFLAGS, &flags);
1209    if (rc < 0) {
1210    printf("Could not set interface flags: %s\\n", strerror(errno));
1211    return;
1212    }
1213    }
1214    void mon_route(int argc, char \*argv[],  unsigned32 command_arg,
1215    bool verbose)
1216    {
1217    int                cmd;
1218    struct sockaddr_in dst;
1219    struct sockaddr_in gw;
1220    struct sockaddr_in netmask;
1221    int                f_host;
1222    int                f_gw       = 0;
1223    int                cur_idx;
1224    int                flags;
1225    int                rc;
1226    memset(&dst, 0, sizeof(dst));
1227    memset(&gw, 0, sizeof(gw));
1228    memset(&netmask, 0, sizeof(netmask));
1229    dst.sin_len = sizeof(dst);
1230    dst.sin_family = AF_INET;
1231    dst.sin_addr.s_addr = inet_addr("0.0.0.0");
1232    gw.sin_len = sizeof(gw);
1233    gw.sin_family = AF_INET;
1234    gw.sin_addr.s_addr = inet_addr("0.0.0.0");
1235    netmask.sin_len = sizeof(netmask);
1236    netmask.sin_family = AF_INET;
1237    netmask.sin_addr.s_addr = inet_addr("255.255.255.0");
1238    if (argc < 2) {
1239    rtems_bsdnet_show_inet_routes();
1240    return;
1241    }
1242    if (strcmp(argv[1], "add") == 0) {
1243    cmd = RTM_ADD;
1244    } else if (strcmp(argv[1], "del") == 0) {
1245    cmd = RTM_DELETE;
1246    } else {
1247    printf("invalid command: %s\\n", argv[1]);
1248    printf("\\tit should be 'add' or 'del'\\n");
1249    return;
1250    }
1251    if (argc < 3) {
1252    printf("not enough arguments\\n");
1253    return;
1254    }
1255    if (strcmp(argv[2], "-host") == 0) {
1256    f_host = 1;
1257    } else if (strcmp(argv[2], "-net") == 0) {
1258    f_host = 0;
1259    } else {
1260    printf("Invalid type: %s\\n", argv[1]);
1261    printf("\\tit should be '-host' or '-net'\\n");
1262    return;
1263    }
1264    if (argc < 4) {
1265    printf("not enough arguments\\n");
1266    return;
1267    }
1268    inet_pton(AF_INET, argv[3], &dst.sin_addr);
1269    cur_idx = 4;
1270    while(cur_idx < argc) {
1271    if (strcmp(argv[cur_idx], "gw") == 0) {
1272    if ((cur_idx +1) >= argc) {
1273    printf("no gateway address\\n");
1274    return;
1275    }
1276    f_gw = 1;
1277    inet_pton(AF_INET, argv[cur_idx + 1], &gw.sin_addr);
1278    cur_idx += 1;
1279    } else if(strcmp(argv[cur_idx], "netmask") == 0) {
1280    if ((cur_idx +1) >= argc) {
1281    printf("no netmask address\\n");
1282    return;
1283    }
1284    f_gw = 1;
1285    inet_pton(AF_INET, argv[cur_idx + 1], &netmask.sin_addr);
1286    cur_idx += 1;
1287    } else {
1288    printf("Unknown argument\\n");
1289    return;
1290    }
1291    cur_idx += 1;
1292    }
1293    flags = RTF_STATIC;
1294    if (f_gw != 0) {
1295    flags \|= RTF_GATEWAY;
1296    }
1297    if (f_host != 0) {
1298    flags \|= RTF_HOST;
1299    }
1300    rc = rtems_bsdnet_rtrequest(cmd, &dst, &gw, &netmask, flags, NULL);
1301    if (rc < 0) {
1302    printf("Error adding route\\n");
1303    }
1304    }
1305
1306Thanks to `Jay Monkman <mailto:jtm@smoothmsmoothie.com>`_ for this example
1307code.
1308
1309Time Synchronization Using NTP
1310------------------------------
1311
1312.. code:: c
1313
1314    int rtems_bsdnet_synchronize_ntp (int interval, rtems_task_priority priority);
1315
1316If the interval argument is 0 the routine synchronizes the RTEMS time-of-day
1317clock with the first NTP server in the rtems_bsdnet_ntpserve array and
1318returns.  The priority argument is ignored.
1319
1320If the interval argument is greater than 0, the routine also starts an
1321RTEMS task at the specified priority and polls the NTP server every
1322‘interval’ seconds.  NOTE: This mode of operation has not yet been
1323implemented.
1324
1325On successful synchronization of the RTEMS time-of-day clock the routine
1326returns 0.  If an error occurs a message is printed and the routine returns -1
1327with an error code in errno.
1328There is no timeout – if there is no response from an NTP server the
1329routine will wait forever.
1330
1331.. COMMENT: Written by Eric Norum
1332
1333.. COMMENT: COPYRIGHT (c) 1988-2002.
1334
1335.. COMMENT: On-Line Applications Research Corporation (OAR).
1336
1337.. COMMENT: All rights reserved.
1338
1339Testing the Driver
1340##################
1341
1342Preliminary Setup
1343=================
1344
1345The network used to test the driver should include at least:
1346
1347- The hardware on which the driver is to run.
1348  It makes testing much easier if you can run a debugger to control
1349  the operation of the target machine.
1350
1351- An Ethernet network analyzer or a workstation with an
1352  ‘Ethernet snoop’ program such as ``ethersnoop`` or``tcpdump``.
1353
1354- A workstation.
1355
1356During early debug, you should consider putting the target, workstation,
1357and snooper on a small network by themselves.  This offers a few
1358advantages:
1359
1360- There is less traffic to look at on the snooper and for the target
1361  to process while bringing the driver up.
1362
1363- Any serious errors will impact only your small network not a building
1364  or campus network.  You want to avoid causing any unnecessary problems.
1365
1366- Test traffic is easier to repeatably generate.
1367
1368- Performance measurements are not impacted by other systems on
1369  the network.
1370
1371Debug Output
1372============
1373
1374There are a number of sources of debug output that can be enabled
1375to aid in tracing the behavior of the network stack.  The following
1376is a list of them:
1377
1378- mbuf activity
1379  There are commented out calls to ``printf`` in the file``sys/mbuf.h`` in the network stack code.  Uncommenting
1380  these lines results in output when mbuf’s are allocated
1381  and freed.  This is very useful for finding memory leaks.
1382
1383- TX and RX queuing
1384  There are commented out calls to ``printf`` in the file``net/if.h`` in the network stack code.  Uncommenting
1385  these lines results in output when packets are placed
1386  on or removed from one of the transmit or receive packet
1387  queues.  These queues can be viewed as the boundary line
1388  between a device driver and the network stack.  If the
1389  network stack is enqueuing packets to be transmitted that
1390  the device driver is not dequeuing, then that is indicative
1391  of a problem in the transmit side of the device driver.
1392  Conversely, if the device driver is enqueueing packets
1393  as it receives them (via a call to ``ether_input``) and
1394  they are not being dequeued by the network stack,
1395  then there is a problem.  This situation would likely indicate
1396  that the network server task is not running.
1397
1398- TCP state transitions
1399  In the unlikely event that one would actually want to see
1400  TCP state transitions, the ``TCPDEBUG`` macro can be defined
1401  in the file ``opt_tcpdebug.h``.  This results in the routine``tcp_trace()`` being called by the network stack and
1402  the state transitions logged into the ``tcp_debug`` data
1403  structure.  If the variable ``tcpconsdebug`` in the file``netinet/tcp_debug.c`` is set to 1, then the state transitions
1404  will also be printed to the console.
1405
1406Monitor Commands
1407================
1408
1409There are a number of command available in the shell / monitor
1410to aid in tracing the behavior of the network stack.  The following
1411is a list of them:
1412
1413- ``inet``
1414  This command shows the current routing information for the TCP/IP stack. Following is an
1415  example showing the output of this command.
1416  .. code:: c
1417      Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
1418      10.0.0.0        255.0.0.0          U           0        0     17 smc1
1419      127.0.0.1       127.0.0.1          UH          0        0      0 lo0
1420  In this example, there is only one network interface with an IP address of 10.8.1.1.  This
1421  link is currently not up.
1422  Two routes that are shown are the default routes for the Ethernet interface (10.0.0.0) and the
1423  loopback interface (127.0.0.1).
1424  Since the stack comes from BSD, this command is very similar to the netstat command.  For more
1425  details on the network routing please look the following
1426  URL: (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html)
1427  For a quick reference to the flags, see the table below:
1428  ‘``U``’
1429      Up: The route is active.
1430  ‘``H``’
1431      Host: The route destination is a single host.
1432  ‘``G``’
1433      Gateway: Send anything for this destination on to this remote system, which
1434      will figure out from there where to send it.
1435  ‘``S``’
1436      Static: This route was configured manually, not automatically generated by the
1437      system.
1438  ‘``C``’
1439      Clone: Generates a new route based upon this route for machines we connect
1440      to. This type of route is normally used for local networks.
1441  ‘``W``’
1442      WasCloned: Indicated a route that was auto-configured based upon a local area
1443      network (Clone) route.
1444  ‘``L``’
1445      Link: Route involves references to Ethernet hardware.
1446
1447- ``mbuf``
1448  This command shows the current MBUF statistics.  An example of the command is shown below:
1449  .. code:: c
1450      ************ MBUF STATISTICS \************
1451      mbufs:4096    clusters: 256    free: 241
1452      drops:   0       waits:   0  drains:   0
1453      free:4080          data:16          header:0           socket:0
1454      pcb:0           rtable:0           htable:0           atable:0
1455      soname:0           soopts:0           ftable:0           rights:0
1456      ifaddr:0          control:0          oobdata:0
1457
1458- ``if``
1459  This command shows the current statistics for your Ethernet driver as long as the ioctl hook``SIO_RTEMS_SHOW_STATS`` has been implemented.  Below is an example:
1460  .. code:: c
1461      ************ INTERFACE STATISTICS \************
1462      \***** smc1 \*****
1463      Ethernet Address: 00:12:76:43:34:25
1464      Address:10.8.1.1        Broadcast Address:10.255.255.255  Net mask:255.0.0.0
1465      Flags: Up Broadcast Running Simplex
1466      Send queue limit:50   length:0    Dropped:0
1467      SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au)
1468      Rx Interrupts:0              Not First:0               Not Last:0
1469      Giant:0                   Runt:0              Non-octet:0
1470      Bad CRC:0                Overrun:0              Collision:0
1471      Tx Interrupts:2               Deferred:0        Missed Hearbeat:0
1472      No Carrier:0       Retransmit Limit:0         Late Collision:0
1473      Underrun:0        Raw output wait:0              Coalesced:0
1474      Coalesce failed:0                Retries:0
1475      \***** lo0 \*****
1476      Address:127.0.0.1       Net mask:255.0.0.0
1477      Flags: Up Loopback Running Multicast
1478      Send queue limit:50   length:0    Dropped:0
1479
1480- ``ip``
1481  This command show the IP statistics for the currently configured interfaces.
1482
1483- ``icmp``
1484  This command show the ICMP statistics for the currently configured interfaces.
1485
1486- ``tcp``
1487  This command show the TCP statistics for the currently configured interfaces.
1488
1489- ``udp``
1490  This command show the UDP statistics for the currently configured interfaces.
1491
1492Driver basic operation
1493======================
1494
1495The network demonstration program ``netdemo`` may be used for these tests.
1496
1497- Edit ``networkconfig.h`` to reflect the values for your network.
1498
1499- Start with ``RTEMS_USE_BOOTP`` not defined.
1500
1501- Edit ``networkconfig.h`` to configure the driver
1502  with an
1503  explicit Ethernet and Internet address and with reception of
1504  broadcast packets disabled:
1505  Verify that the program continues to run once the driver has been attached.
1506
1507- Issue a ‘``u``’ command to send UDP
1508  packets to the ‘discard’ port.
1509  Verify that the packets appear on the network.
1510
1511- Issue a ‘``s``’ command to print the network and driver statistics.
1512
1513- On a workstation, add a static route to the target system.
1514
1515- On that same workstation try to ‘ping’ the target system.
1516  Verify that the ICMP echo request and reply packets appear on the net.
1517
1518- Remove the static route to the target system.
1519  Modify ``networkconfig.h`` to attach the driver
1520  with reception of broadcast packets enabled.
1521  Try to ‘ping’ the target system again.
1522  Verify that ARP request/reply and ICMP echo request/reply packets appear
1523  on the net.
1524
1525- Issue a ‘``t``’ command to send TCP
1526  packets to the ‘discard’ port.
1527  Verify that the packets appear on the network.
1528
1529- Issue a ‘``s``’ command to print the network and driver statistics.
1530
1531- Verify that you can telnet to ports 24742
1532  and 24743 on the target system from one or more
1533  workstations on your network.
1534
1535BOOTP/DHCP operation
1536====================
1537
1538Set up a BOOTP/DHCP server on the network.
1539Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``.
1540Run the ``netdemo`` test program.
1541Verify that the target system configures itself from the BOOTP/DHCP server and
1542that all the above tests succeed.
1543
1544Stress Tests
1545============
1546
1547Once the driver passes the tests described in the previous section it should
1548be subjected to conditions which exercise it more
1549thoroughly and which test its error handling routines.
1550
1551Giant packets
1552-------------
1553
1554- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to
1555  a smaller value, say 514.
1556
1557- ‘Ping’ the driver from another workstation and verify
1558  that frames larger than 514 bytes are correctly rejected.
1559
1560- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored  to 1518.
1561
1562Resource Exhaustion
1563-------------------
1564
1565- Edit  ``networkconfig.h``
1566  so that the driver is configured with just two receive and transmit descriptors.
1567
1568- Compile and run the ``netdemo`` program.
1569
1570- Verify that the program operates properly and that you can
1571  still telnet to both the ports.
1572
1573- Display the driver statistics (Console ‘``s``’ command or telnet
1574  ‘control-G’ character) and verify that:
1575  # The number of transmit interrupts is non-zero.
1576    This indicates that all transmit descriptors have been in use at some time.
1577  # The number of missed packets is non-zero.
1578    This indicates that all receive descriptors have been in use at some time.
1579
1580Cable Faults
1581------------
1582
1583- Run the ``netdemo`` program.
1584
1585- Issue a ‘``u``’ console command to make the target machine transmit
1586  a bunch of UDP packets.
1587
1588- While the packets are being transmitted, disconnect and reconnect the
1589  network cable.
1590
1591- Display the network statistics and verify that the driver has
1592  detected the loss of carrier.
1593
1594- Verify that you can still telnet to both ports on the target machine.
1595
1596Throughput
1597----------
1598
1599Run the ``ttcp`` network benchmark program.
1600Transfer large amounts of data (100’s of megabytes) to and from the target
1601system.
1602
1603The procedure for testing throughput from a host to an RTEMS target
1604is as follows:
1605
1606# Download and start the ttcp program on the Target.
1607
1608# In response to the ``ttcp`` prompt, enter ``-s -r``.  The
1609  meaning of these flags is described in the ``ttcp.1`` manual page
1610  found in the ``ttcp_orig`` subdirectory.
1611
1612# On the host run ``ttcp -s -t <<insert the hostname or IP address of
1613  the Target here>>``
1614
1615The procedure for testing throughput from an RTEMS target
1616to a Host is as follows:
1617
1618# On the host run ``ttcp -s -r``.
1619
1620# Download and start the ttcp program on the Target.
1621
1622# In response to the ``ttcp`` prompt, enter ``-s -t <<insert
1623  the hostname or IP address of the Target here>>``.  You need to type the
1624  IP address of the host unless your Target is talking to your Domain Name
1625  Server.
1626
1627To change the number of buffers, the buffer size, etc. you just add the
1628extra flags to the ``-t`` machine as specified in the ``ttcp.1``
1629manual page found in the ``ttcp_orig`` subdirectory.
1630
1631.. COMMENT: Text Written by Jake Janovetz
1632
1633.. COMMENT: COPYRIGHT (c) 1988-2002.
1634
1635.. COMMENT: On-Line Applications Research Corporation (OAR).
1636
1637.. COMMENT: All rights reserved.
1638
1639Network Servers
1640###############
1641
1642RTEMS FTP Daemon
1643================
1644
1645The RTEMS FTPD is a complete file transfer protocol (FTP) daemon
1646which can store, retrieve, and manipulate files on the local
1647filesystem.  In addition, the RTEMS FTPD provides “hooks”
1648which are actions performed on received data.  Hooks are useful
1649in situations where a destination file is not necessarily
1650appropriate or in cases when a formal device driver has not yet
1651been implemented.
1652
1653This server was implemented and documented by Jake Janovetz
1654(janovetz@tempest.ece.uiuc.edu).
1655
1656Configuration Parameters
1657------------------------
1658
1659The configuration structure for FTPD is as follows:
1660.. code:: c
1661
1662    struct rtems_ftpd_configuration
1663    {
1664    rtems_task_priority     priority;           /* FTPD task priority  \*/
1665    unsigned long           max_hook_filesize;  /* Maximum buffersize  \*/
1666    /*    for hooks        \*/
1667    int                     port;               /* Well-known port     \*/
1668    struct rtems_ftpd_hook  \*hooks;             /* List of hooks       \*/
1669    };
1670
1671The FTPD task priority is specified with ``priority``.  Because
1672hooks are not saved as files, the received data is placed in an
1673allocated buffer.  ``max_hook_filesize`` specifies the maximum
1674size of this buffer.  Finally, ``hooks`` is a pointer to the
1675configured hooks structure.
1676
1677Initializing FTPD (Starting the daemon)
1678---------------------------------------
1679
1680Starting FTPD is done with a call to ``rtems_initialize_ftpd()``.
1681The configuration structure must be provided in the application
1682source code.  Example hooks structure and configuration structure
1683folllow.
1684.. code:: c
1685
1686    struct rtems_ftpd_hook ftp_hooks[] =
1687    {
1688    {"untar", Untar_FromMemory},
1689    {NULL, NULL}
1690    };
1691    struct rtems_ftpd_configuration rtems_ftpd_configuration =
1692    {
1693    40,                     /* FTPD task priority \*/
1694    512*1024,               /* Maximum hook 'file' size \*/
1695    0,                      /* Use default port \*/
1696    ftp_hooks               /* Local ftp hooks \*/
1697    };
1698
1699Specifying 0 for the well-known port causes FTPD to use the
1700UNIX standard FTPD port (21).
1701
1702Using Hooks
1703-----------
1704
1705In the example above, one hook was installed.  The hook causes
1706FTPD to call the function ``Untar_FromMemory`` when the
1707user sends data to the file ``untar``.  The prototype for
1708the ``untar`` hook (and hooks, in general) is:
1709.. code:: c
1710
1711    int Untar_FromMemory(unsigned char \*tar_buf, unsigned long size);
1712
1713An example FTP transcript which exercises this hook is:
1714.. code:: c
1715
1716    220 RTEMS FTP server (Version 1.0-JWJ) ready.
1717    Name (dcomm0:janovetz): John Galt
1718    230 User logged in.
1719    Remote system type is RTEMS.
1720    ftp> bin
1721    200 Type set to I.
1722    ftp> dir
1723    200 PORT command successful.
1724    150 ASCII data connection for LIST.
1725    drwxrwx--x      0     0         268  dev
1726    drwxrwx--x      0     0           0  TFTP
1727    226 Transfer complete.
1728    ftp> put html.tar untar
1729    local: html.tar remote: untar
1730    200 PORT command successful.
1731    150 BINARY data connection.
1732    210 File transferred successfully.
1733    471040 bytes sent in 0.48 secs (9.6e+02 Kbytes/sec)
1734    ftp> dir
1735    200 PORT command successful.
1736    150 ASCII data connection for LIST.
1737    drwxrwx--x      0     0         268  dev
1738    drwxrwx--x      0     0           0  TFTP
1739    drwxrwx--x      0     0        3484  public_html
1740    226 Transfer complete.
1741    ftp> quit
1742    221 Goodbye.
1743
1744.. COMMENT: RTEMS Remote Debugger Server Specifications
1745
1746.. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>
1747
1748DEC 21140 Driver
1749################
1750
1751DEC 21240 Driver Introduction
1752=============================
1753
1754.. COMMENT: XXX add back in cross reference to list of boards.
1755
1756One aim of our project is to port RTEMS on a standard PowerPC platform.
1757To achieve it, we have chosen a Motorola MCP750 board. This board includes
1758an Ethernet controller based on a DEC21140 chip. Because RTEMS has a
1759TCP/IP stack, we will
1760have to develop the DEC21140 related ethernet driver for the PowerPC port of
1761RTEMS. As this controller is able to support 100Mbps network and as there is
1762a lot of PCI card using this DEC chip, we have decided to first
1763implement this driver on an Intel PC386 target to provide a solution for using
1764RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in
1765a second phase.
1766
1767The aim of this document is to give some PCI board generalities and
1768to explain the software architecture of the RTEMS driver. Finally, we will see
1769what will be done for ChorusOs and Netboot environment .
1770
1771Document Revision History
1772=========================
1773
1774*Current release*:
1775
1776- Current applicable release is 1.0.
1777
1778*Existing releases*:
1779
1780- 1.0 : Released the 10/02/98. First version of this document.
1781
1782- 0.1 : First draft of this document
1783
1784*Planned releases*:
1785
1786- None planned today.
1787
1788DEC21140 PCI Board Generalities
1789===============================
1790
1791.. COMMENT: XXX add crossreference to PCI Register Figure
1792
1793This chapter describes rapidely the PCI interface of this Ethernet controller.
1794The board we have chosen for our PC386 implementation is a D-Link DFE-500TX.
1795This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
1796Like other PCI devices, this board has a PCI device’s header containing some
1797required configuration registers, as shown in the PCI Register Figure.
1798By reading
1799or writing these registers, a driver can obtain information about the type of
1800the board, the interrupt it uses, the mapping of the chip specific registers, ...
1801
1802On Intel target, the chip specific registers can be accessed via 2
1803methods : I/O port access or PCI address mapped access. We have chosen to implement
1804the PCI address access to obtain compatible source code to the port the driver
1805on a PowerPC target.
1806
1807.. COMMENT: PCI Device's Configuration Header Space Format
1808
1809.. image:: PCIreg.eps
1810
1811.. image:: PCIreg.jpg
1812
1813.. image:: PCIreg.pdf
1814
1815.. COMMENT: XXX add crossreference to PCI Register Figure
1816
1817On RTEMS, a PCI API exists. We have used it to configure the board. After initializing
1818this PCI module via the ``pci_initialize()`` function, we try to detect
1819the DEC21140 based ethernet board. This board is characterized by its Vendor
1820ID (0x1011) and its Device ID (0x0009). We give these arguments to the``pcib_find_by_deviceid``
1821function which returns , if the device is present, a pointer to the configuration
1822header space (see PCI Registers Fgure). Once this operation performed,
1823the driver
1824is able to extract the information it needs to configure the board internal
1825registers, like the interrupt line, the base address,... The board internal
1826registers will not be detailled here. You can find them in *DIGITAL
1827Semiconductor 21140A PCI Fast Ethernet LAN Controller
1828- Hardware Reference Manual*.
1829
1830.. COMMENT: fix citation
1831
1832RTEMS Driver Software Architecture
1833==================================
1834
1835In this chapter will see the initialization phase, how the controller uses the
1836host memory and the 2 threads launched at the initialization time.
1837
1838Initialization phase
1839--------------------
1840
1841The DEC21140 Ethernet driver keeps the same software architecture than the other
1842RTEMS ethernet drivers. The only API the programmer can use is the ``rtems_dec21140_driver_attach````(struct rtems_bsdnet_ifconfig \*config)`` function which
1843detects the board and initializes the associated data structure (with registers
1844base address, entry points to low-level initialization function,...), if the
1845board is found.
1846
1847Once the attach function executed, the driver initializes the DEC
1848chip. Then the driver connects an interrupt handler to the interrupt line driven
1849by the Ethernet controller (the only interrupt which will be treated is the
1850receive interrupt) and launches 2 threads : a receiver thread and a transmitter
1851thread. Then the driver waits for incoming frame to give to the protocol stack
1852or outcoming frame to send on the physical link.
1853
1854Memory Buffer
1855-------------
1856
1857.. COMMENT: XXX add cross reference to Problem
1858
1859This DEC chip uses the host memory to store the incoming Ethernet frames and
1860the descriptor of these frames. We have chosen to use 7 receive buffers and
18611 transmit buffer to optimize memory allocation due to cache and paging problem
1862that will be explained in the section *Encountered Problems*.
1863
1864To reference these buffers to the DEC chip we use a buffer descriptors
1865ring. The descriptor structure is defined in the Buffer Descriptor Figure.
1866Each descriptor
1867can reference one or two memory buffers. We choose to use only one buffer of
18681520 bytes per descriptor.
1869
1870The difference between a receive and a transmit buffer descriptor
1871is located in the status and control bits fields. We do not give details here,
1872please refer to the \[DEC21140 Hardware Manual].
1873
1874.. COMMENT: Buffer Descriptor
1875
1876.. image:: recvbd.eps
1877
1878.. image:: recvbd.jpg
1879
1880.. image:: recvbd.pdf
1881
1882Receiver Thread
1883---------------
1884
1885This thread is event driven. Each time a DEC PCI board interrupt occurs, the
1886handler checks if this is a receive interrupt and send an event “reception”
1887to the receiver thread which looks into the entire buffer descriptors ring the
1888ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs
1889to host processor). Each valid incoming ethernet frame is sent to the protocol
1890stack and the buffer descriptor is given back to the DEC board (the host processor
1891reset bit OWN, which means descriptor belongs to 21140).
1892
1893Transmitter Thread
1894------------------
1895
1896This thread is also event driven. Each time an Ethernet frame is put in the
1897transmit queue, an event is sent to the transmit thread, which empty the queue
1898by sending each outcoming frame. Because we use only one transmit buffer, we
1899are sure that the frame is well-sent before sending the next.
1900
1901Encountered Problems
1902====================
1903
1904On Intel PC386 target, we were faced with a problem of memory cache management.
1905Because the DEC chip uses the host memory to store the incoming frame and because
1906the DEC21140 configuration registers are mapped into the PCI address space,
1907we must ensure that the data read (or written) by the host processor are the
1908ones written (or read) by the DEC21140 device in the host memory and not old
1909data stored in the cache memory. Therefore, we had to provide a way to manage
1910the cache. This module is described in the document *RTEMS
1911Cache Management For Intel*. On Intel, the
1912memory region cache management is available only if the paging unit is enabled.
1913We have used this paging mechanism, with 4Kb page. All the buffers allocated
1914to store the incoming or outcoming frames, buffer descriptor and also the PCI
1915address space of the DEC board are located in a memory space with cache disable.
1916
1917Concerning the buffers and their descriptors, we have tried to optimize
1918the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor
1919has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each,
19201 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This
1921allows not to lose too much memory or not to disable cache memory for a page
1922which contains other data than buffer, which could decrease performance.
1923
1924ChorusOs DEC Driver
1925===================
1926
1927Because ChorusOs is used in several Canon CRF projects, we must provide such
1928a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.
1929On ChorusOs, a DEC driver source code already exists but only for a PowerPC
1930target. We plan to port this code (which uses ChorusOs API) on Intel target.
1931This will allow us to have homogeneous developments. Moreover, the port of the
1932development performed with ChorusOs environment to RTEMS environment will be
1933easier for the developers.
1934
1935Netboot DEC driver
1936==================
1937
1938We use Netboot tool to load our development from a server to the target via
1939an ethernet network. Currently, this tool does not support the DEC board. We
1940plan to port the DEC driver for the Netboot tool.
1941
1942But concerning the port of the DEC driver into Netboot, we are faced
1943with a problem : in RTEMS environment, the DEC driver is interrupt or event
1944driven, in Netboot environment, it must be used in polling mode. It means that
1945we will have to re-write some mechanisms of this driver.
1946
1947List of Ethernet cards using the DEC chip
1948=========================================
1949
1950Many Ethernet adapter cards use the Tulip chip. Here is a non exhaustive list
1951of adapters which support this driver :
1952
1953- Accton EtherDuo PCI.
1954
1955- Accton EN1207 All three media types supported.
1956
1957- Adaptec ANA6911/TX 21140-AC.
1958
1959- Cogent EM110 21140-A with DP83840 N-Way MII transceiver.
1960
1961- Cogent EM400 EM100 with 4 21140 100mbps-only ports + PCI Bridge.
1962
1963- Danpex EN-9400P3.
1964
1965- D-Link DFE500-Tx 21140-A with DP83840 transceiver.
1966
1967- Kingston EtherX KNE100TX 21140AE.
1968
1969- Netgear FX310 TX 10/100 21140AE.
1970
1971- SMC EtherPower10/100 With DEC21140 and 68836 SYM transceiver.
1972
1973- SMC EtherPower10/100 With DEC21140-AC and DP83840 MII transceiver.
1974  Note: The EtherPower II uses the EPIC chip, which requires a different driver.
1975
1976- Surecom EP-320X DEC 21140.
1977
1978- Thomas Conrad TC5048.
1979
1980- Znyx ZX345 21140-A, usually with the DP83840 N-Way MII transciever. Some ZX345
1981  cards made in 1996 have an ICS 1890 transciver instead.
1982
1983- ZNYX ZX348 Two 21140-A chips using ICS 1890 transcievers and either a 21052
1984  or 21152 bridge. Early versions used National 83840 transcievers, but later
1985  versions are depopulated ZX346 boards.
1986
1987- ZNYX ZX351 21140 chip with a Broadcom 100BaseT4 transciever.
1988
1989Our DEC driver has not been tested with all these cards, only with the D-Link
1990DFE500-TX.
1991
1992- ```` *[DEC21140 Hardware Manual] DIGITAL, *DIGITAL
1993  Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware
1994  Reference Manual**.
1995
1996- ```` *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**.
1997
1998Command and Variable Index
1999##########################
2000
2001There are currently no Command and Variable Index entries.
2002
2003.. COMMENT: @printindex fn
2004
2005Concept Index
2006#############
2007
2008There are currently no Concept Index entries.
2009
2010.. COMMENT: @printindex cp
Note: See TracBrowser for help on using the repository browser.