source: rtems-docs/networking/networking_old_reference_only.rst @ ca49bfd

4.115am
Last change on this file since ca49bfd was ca49bfd, checked in by Amar Takhar <verm@…>, on 01/16/16 at 23:26:00

Split document.

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