source: rtems-docs/networking/networking.rst @ 75a59fd

4.115am
Last change on this file since 75a59fd was 75a59fd, checked in by Amar Takhar <verm@…>, on 01/16/16 at 21:11:25

Fix images.

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