Changeset b412038 in rtems-docs


Ignore:
Timestamp:
Apr 11, 2016, 3:53:58 AM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
bc37517
Parents:
ea0777e
git-author:
Chris Johns <chrisj@…> (04/11/16 03:53:58)
git-committer:
Amar Takhar <verm@…> (05/03/16 00:51:27)
Message:

Clean up and review of Networking User Guide.

Location:
networking
Files:
9 edited

Legend:

Unmodified
Added
Removed
  • networking/conf.py

    rea0777e rb412038  
    44from conf import *
    55
    6 version = '1.0'
    7 release = '5.0'
     6version = '4.11.0'
     7release = '4.11.0'
     8
     9project = "RTEMS Networking User Manual"
    810
    911latex_documents = [
    10         ('index', 'networking.tex', u'RTEMS Networking Documentation', u'RTEMS Documentation Project', 'manual'),
     12        ('index', 'networking.tex', u'RTEMS Networking User Documentation', u'RTEMS Documentation Project', 'manual'),
    1113]
    12 
  • networking/dec_21140.rst

    rea0777e rb412038  
    77.. COMMENT: XXX add back in cross reference to list of boards.
    88
    9 One aim of our project is to port RTEMS on a standard PowerPC platform.
    10 To achieve it, we have chosen a Motorola MCP750 board. This board includes
    11 an Ethernet controller based on a DEC21140 chip. Because RTEMS has a
    12 TCP/IP stack, we will
    13 have to develop the DEC21140 related ethernet driver for the PowerPC port of
    14 RTEMS. As this controller is able to support 100Mbps network and as there is
    15 a lot of PCI card using this DEC chip, we have decided to first
     9One aim of our project is to port RTEMS on a standard PowerPC platform.  To
     10achieve it, we have chosen a Motorola MCP750 board. This board includes an
     11Ethernet controller based on a DEC21140 chip. Because RTEMS has a TCP/IP stack,
     12we will have to develop the DEC21140 related ethernet driver for the PowerPC
     13port of RTEMS. As this controller is able to support 100Mbps network and as
     14there is a lot of PCI card using this DEC chip, we have decided to first
    1615implement this driver on an Intel PC386 target to provide a solution for using
    17 RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in
    18 a second phase.
    19 
    20 The aim of this document is to give some PCI board generalities and
    21 to explain the software architecture of the RTEMS driver. Finally, we will see
    22 what will be done for ChorusOs and Netboot environment .
     16RTEMS on PC with the 100Mbps network and then to port this code on PowerPC in a
     17second phase.
     18
     19The aim of this document is to give some PCI board generalities and to explain
     20the software architecture of the RTEMS driver. Finally, we will see what will
     21be done for ChorusOs and Netboot environment .
    2322
    2423Document Revision History
     
    4847This is a dual-speed 10/100Mbps Ethernet PCI adapter with a DEC21140AF chip.
    4948Like other PCI devices, this board has a PCI device's header containing some
    50 required configuration registers, as shown in the PCI Register Figure.
    51 By reading
    52 or writing these registers, a driver can obtain information about the type of
    53 the board, the interrupt it uses, the mapping of the chip specific registers, ...
    54 
    55 On Intel target, the chip specific registers can be accessed via 2
    56 methods : I/O port access or PCI address mapped access. We have chosen to implement
    57 the PCI address access to obtain compatible source code to the port the driver
    58 on a PowerPC target.
     49required configuration registers, as shown in the PCI Register Figure.  By
     50reading or writing these registers, a driver can obtain information about the
     51type of the board, the interrupt it uses, the mapping of the chip specific
     52registers, ...
     53
     54On Intel target, the chip specific registers can be accessed via 2 methods :
     55I/O port access or PCI address mapped access. We have chosen to implement the
     56PCI address access to obtain compatible source code to the port the driver on a
     57PowerPC target.
    5958
    6059.. COMMENT: PCI Device's Configuration Header Space Format
     
    6665.. COMMENT: XXX add crossreference to PCI Register Figure
    6766
    68 On RTEMS, a PCI API exists. We have used it to configure the board. After initializing
    69 this PCI module via the ``pci_initialize()`` function, we try to detect
    70 the DEC21140 based ethernet board. This board is characterized by its Vendor
    71 ID (0x1011) and its Device ID (0x0009). We give these arguments to the``pcib_find_by_deviceid``
    72 function which returns , if the device is present, a pointer to the configuration
    73 header space (see PCI Registers Fgure). Once this operation performed,
    74 the driver
    75 is able to extract the information it needs to configure the board internal
    76 registers, like the interrupt line, the base address,... The board internal
    77 registers will not be detailled here. You can find them in *DIGITAL
    78 Semiconductor 21140A PCI Fast Ethernet LAN Controller
     67On RTEMS, a PCI API exists. We have used it to configure the board. After
     68initializing this PCI module via the ``pci_initialize()`` function, we try to
     69detect the DEC21140 based ethernet board. This board is characterized by its
     70Vendor ID (0x1011) and its Device ID (0x0009). We give these arguments to
     71the``pcib_find_by_deviceid`` function which returns , if the device is present,
     72a pointer to the configuration header space (see PCI Registers Fgure). Once
     73this operation performed, the driver is able to extract the information it
     74needs to configure the board internal registers, like the interrupt line, the
     75base address,... The board internal registers will not be detailled here. You
     76can find them in *DIGITAL Semiconductor 21140A PCI Fast Ethernet LAN Controller
    7977- Hardware Reference Manual*.
    8078
     
    9088--------------------
    9189
    92 The DEC21140 Ethernet driver keeps the same software architecture than the other
    93 RTEMS ethernet drivers. The only API the programmer can use is the ``rtems_dec21140_driver_attach````(struct rtems_bsdnet_ifconfig \*config)`` function which
    94 detects the board and initializes the associated data structure (with registers
    95 base address, entry points to low-level initialization function,...), if the
    96 board is found.
    97 
    98 Once the attach function executed, the driver initializes the DEC
    99 chip. Then the driver connects an interrupt handler to the interrupt line driven
    100 by the Ethernet controller (the only interrupt which will be treated is the
    101 receive interrupt) and launches 2 threads : a receiver thread and a transmitter
     90The DEC21140 Ethernet driver keeps the same software architecture than the
     91other RTEMS ethernet drivers. The only API the programmer can use is the
     92``rtems_dec21140_driver_attach(struct rtems_bsdnet_ifconfig *config)``
     93function which detects the board and initializes the associated data structure
     94(with registers base address, entry points to low-level initialization
     95function,...), if the board is found.
     96
     97Once the attach function executed, the driver initializes the DEC chip. Then
     98the driver connects an interrupt handler to the interrupt line driven by the
     99Ethernet controller (the only interrupt which will be treated is the receive
     100interrupt) and launches 2 threads : a receiver thread and a transmitter
    102101thread. Then the driver waits for incoming frame to give to the protocol stack
    103102or outcoming frame to send on the physical link.
     
    109108
    110109This DEC chip uses the host memory to store the incoming Ethernet frames and
    111 the descriptor of these frames. We have chosen to use 7 receive buffers and
    112 1 transmit buffer to optimize memory allocation due to cache and paging problem
     110the descriptor of these frames. We have chosen to use 7 receive buffers and 1
     111transmit buffer to optimize memory allocation due to cache and paging problem
    113112that will be explained in the section *Encountered Problems*.
    114113
    115114To reference these buffers to the DEC chip we use a buffer descriptors
    116115ring. The descriptor structure is defined in the Buffer Descriptor Figure.
    117 Each descriptor
    118 can reference one or two memory buffers. We choose to use only one buffer of
    119 1520 bytes per descriptor.
    120 
    121 The difference between a receive and a transmit buffer descriptor
    122 is located in the status and control bits fields. We do not give details here,
    123 please refer to the \[DEC21140 Hardware Manual].
     116Each descriptor can reference one or two memory buffers. We choose to use only
     117one buffer of 1520 bytes per descriptor.
     118
     119The difference between a receive and a transmit buffer descriptor is located in
     120the status and control bits fields. We do not give details here, please refer
     121to the DEC21140 Hardware Manual.
    124122
    125123.. COMMENT: Buffer Descriptor
     
    133131
    134132This thread is event driven. Each time a DEC PCI board interrupt occurs, the
    135 handler checks if this is a receive interrupt and send an event "reception"
    136 to the receiver thread which looks into the entire buffer descriptors ring the
    137 ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs
    138 to host processor). Each valid incoming ethernet frame is sent to the protocol
    139 stack and the buffer descriptor is given back to the DEC board (the host processor
    140 reset bit OWN, which means descriptor belongs to 21140).
     133handler checks if this is a receive interrupt and send an event "reception" to
     134the receiver thread which looks into the entire buffer descriptors ring the
     135ones that contain a valid incoming frame (bit OWN=0 means descriptor belongs to
     136host processor). Each valid incoming ethernet frame is sent to the protocol
     137stack and the buffer descriptor is given back to the DEC board (the host
     138processor reset bit OWN, which means descriptor belongs to 21140).
    141139
    142140Transmitter Thread
     
    152150
    153151On Intel PC386 target, we were faced with a problem of memory cache management.
    154 Because the DEC chip uses the host memory to store the incoming frame and because
    155 the DEC21140 configuration registers are mapped into the PCI address space,
    156 we must ensure that the data read (or written) by the host processor are the
    157 ones written (or read) by the DEC21140 device in the host memory and not old
    158 data stored in the cache memory. Therefore, we had to provide a way to manage
    159 the cache. This module is described in the document *RTEMS
    160 Cache Management For Intel*. On Intel, the
    161 memory region cache management is available only if the paging unit is enabled.
    162 We have used this paging mechanism, with 4Kb page. All the buffers allocated
    163 to store the incoming or outcoming frames, buffer descriptor and also the PCI
    164 address space of the DEC board are located in a memory space with cache disable.
    165 
    166 Concerning the buffers and their descriptors, we have tried to optimize
    167 the memory space in term of allocated page. One buffer has 1520 bytes, one descriptor
    168 has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and for each,
    169 1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire pages. This
    170 allows not to lose too much memory or not to disable cache memory for a page
    171 which contains other data than buffer, which could decrease performance.
    172 
    173 ChorusOs DEC Driver
    174 ===================
    175 
    176 Because ChorusOs is used in several Canon CRF projects, we must provide such
    177 a driver on this OS to ensure compatibility between the RTEMS and ChorusOs developments.
    178 On ChorusOs, a DEC driver source code already exists but only for a PowerPC
    179 target. We plan to port this code (which uses ChorusOs API) on Intel target.
    180 This will allow us to have homogeneous developments. Moreover, the port of the
    181 development performed with ChorusOs environment to RTEMS environment will be
    182 easier for the developers.
     152Because the DEC chip uses the host memory to store the incoming frame and
     153because the DEC21140 configuration registers are mapped into the PCI address
     154space, we must ensure that the data read (or written) by the host processor are
     155the ones written (or read) by the DEC21140 device in the host memory and not
     156old data stored in the cache memory. Therefore, we had to provide a way to
     157manage the cache. This module is described in the document *RTEMS Cache
     158Management For Intel*. On Intel, the memory region cache management is
     159available only if the paging unit is enabled.  We have used this paging
     160mechanism, with 4Kb page. All the buffers allocated to store the incoming or
     161outcoming frames, buffer descriptor and also the PCI address space of the DEC
     162board are located in a memory space with cache disable.
     163
     164Concerning the buffers and their descriptors, we have tried to optimize the
     165memory space in term of allocated page. One buffer has 1520 bytes, one
     166descriptor has 16 bytes. We have 7 receive buffers and 1 transmit buffer, and
     167for each, 1 descriptor : (7+1)*(1520+16) = 12288 bytes = 12Kb = 3 entire
     168pages. This allows not to lose too much memory or not to disable cache memory
     169for a page which contains other data than buffer, which could decrease
     170performance.
    183171
    184172Netboot DEC driver
    185173==================
    186174
    187 We use Netboot tool to load our development from a server to the target via
    188 an ethernet network. Currently, this tool does not support the DEC board. We
    189 plan to port the DEC driver for the Netboot tool.
    190 
    191 But concerning the port of the DEC driver into Netboot, we are faced
    192 with a problem : in RTEMS environment, the DEC driver is interrupt or event
    193 driven, in Netboot environment, it must be used in polling mode. It means that
    194 we will have to re-write some mechanisms of this driver.
     175We use Netboot tool to load our development from a server to the target via an
     176ethernet network. Currently, this tool does not support the DEC board. We plan
     177to port the DEC driver for the Netboot tool.
     178
     179But concerning the port of the DEC driver into Netboot, we are faced with a
     180problem: in RTEMS environment, the DEC driver is interrupt or event driven, in
     181Netboot environment, it must be used in polling mode. It means that we will
     182have to re-write some mechanisms of this driver.
    195183
    196184List of Ethernet cards using the DEC chip
     
    239227DFE500-TX.
    240228
    241 - *[DEC21140 Hardware Manual] DIGITAL, *DIGITAL
    242   Semiconductor 21140A PCI Fast Ethernet LAN Controller - Hardware
    243   Reference Manual**.
     229- DEC21140 Hardware Manual DIGITAL, DIGITAL Semiconductor 21140A PCI Fast
     230  Ethernet LAN Controller - Hardware Reference Manual**.
    244231
    245232- *[99.TA.0021.M.ER]Emmanuel Raguet,*RTEMS Cache Management For Intel**.
    246 
  • networking/index.rst

    rea0777e rb412038  
    1 ========================
    2 RTEMS Network Supplement
    3 ========================
    4 COPYRIGHT (c) 1988 - 2015.
     1.. highlight:: c
    52
    6 On-Line Applications Research Corporation (OAR).
     3===================================
     4RTEMS |version| Network User Manual
     5===================================
    76
    8 The authors have used their best efforts in preparing
    9 this material.  These efforts include the development, research,
    10 and testing of the theories and programs to determine their
    11 effectiveness.  No warranty of any kind, expressed or implied,
    12 with regard to the software or the material contained in this
    13 document is provided.  No liability arising out of the
    14 application or use of any product described in this document is
    15 assumed.  The authors reserve the right to revise this material
    16 and to make changes from time to time in the content hereof
    17 without obligation to notify anyone of such revision or changes.
     7 | COPYRIGHT (c) 1988 - 2015.
     8 | On-Line Applications Research Corporation (OAR).
    189
    19 The RTEMS Project is hosted at http://www.rtems.org.  Any
    20 inquiries concerning RTEMS, its related support components, or its
    21 documentation should be directed to the Community Project hosted athttp://www.rtems.org.
     10The authors have used their best efforts in preparing this material.  These
     11efforts include the development, research, and testing of the theories and
     12programs to determine their effectiveness.  No warranty of any kind, expressed
     13or implied, with regard to the software or the material contained in this
     14document is provided.  No liability arising out of the application or use of
     15any product described in this document is assumed.  The authors reserve the
     16right to revise this material and to make changes from time to time in the
     17content hereof without obligation to notify anyone of such revision or changes.
    2218
    23 Any inquiries for commercial services including training, support, custom
    24 development, application development assistance should be directed tohttp://www.rtems.com.
     19The RTEMS Project is hosted at http://www.rtems.org/.  Any inquiries concerning
     20RTEMS, its related support components, or its documentation should be directed
     21to the Community Project hosted at http://www.rtems.org/.
    2522
     23.. topic:: RTEMS Online Resources
    2624
    27 Table of Contents
    28 -----------------
    29 
    30 .. toctree::
    31 
    32         preface
    33 
     25  ================  =============================
     26  Home              https://www.rtems.org/
     27  Developers        https://devel.rtems.org/
     28  Documentation     https://docs.rtems.org/
     29  Bug Reporting     https://devel.rtems.org/query
     30  Mailing Lists     https://lists.rtems.org/
     31  Git Repositories  https://git.rtems.org/
     32  ================  =============================
    3433
    3534.. toctree::
     
    4645        command
    4746
    48 
    4947*       :ref:`genindex`
    5048*       :ref:`search`
    51 
  • networking/network_servers.rst

    rea0777e rb412038  
     1.. COMMENT: RTEMS Remote Debugger Server Specifications
     2.. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>
     3
    14Network Servers
    25###############
     
    58================
    69
    7 The RTEMS FTPD is a complete file transfer protocol (FTP) daemon
    8 which can store, retrieve, and manipulate files on the local
    9 filesystem.  In addition, the RTEMS FTPD provides "hooks"
    10 which are actions performed on received data.  Hooks are useful
    11 in situations where a destination file is not necessarily
    12 appropriate or in cases when a formal device driver has not yet
    13 been implemented.
     10The RTEMS FTPD is a complete file transfer protocol (FTP) daemon which can
     11store, retrieve, and manipulate files on the local filesystem.  In addition,
     12the RTEMS FTPD provides "hooks" which are actions performed on received data.
     13Hooks are useful in situations where a destination file is not necessarily
     14appropriate or in cases when a formal device driver has not yet been
     15implemented.
    1416
    1517This server was implemented and documented by Jake Janovetz
     
    2022
    2123The configuration structure for FTPD is as follows:
    22 .. code:: c
     24
     25.. code-block:: c
    2326
    2427    struct rtems_ftpd_configuration
    2528    {
    26     rtems_task_priority     priority;           /* FTPD task priority  \*/
    27     unsigned long           max_hook_filesize;  /* Maximum buffersize  \*/
    28     /*    for hooks        \*/
    29     int                     port;               /* Well-known port     \*/
    30     struct rtems_ftpd_hook  \*hooks;             /* List of hooks       \*/
     29        rtems_task_priority     priority;           /* FTPD task priority  */
     30        unsigned long           max_hook_filesize;  /* Maximum buffersize  */
     31        /*    for hooks        */
     32        int                     port;               /* Well-known port     */
     33        struct rtems_ftpd_hook  *hooks;             /* List of hooks       */
    3134    };
    3235
    33 The FTPD task priority is specified with ``priority``.  Because
    34 hooks are not saved as files, the received data is placed in an
    35 allocated buffer.  ``max_hook_filesize`` specifies the maximum
    36 size of this buffer.  Finally, ``hooks`` is a pointer to the
    37 configured hooks structure.
     36The FTPD task priority is specified with ``priority``.  Because hooks are not
     37saved as files, the received data is placed in an allocated buffer.
     38``max_hook_filesize`` specifies the maximum size of this buffer.  Finally,
     39``hooks`` is a pointer to the configured hooks structure.
    3840
    3941Initializing FTPD (Starting the daemon)
    4042---------------------------------------
    4143
    42 Starting FTPD is done with a call to ``rtems_initialize_ftpd()``.
    43 The configuration structure must be provided in the application
    44 source code.  Example hooks structure and configuration structure
    45 folllow.
    46 .. code:: c
     44Starting FTPD is done with a call to ``rtems_initialize_ftpd()``.  The
     45configuration structure must be provided in the application source code.
     46Example hooks structure and configuration structure folllow.
     47
     48.. code-block:: c
    4749
    4850    struct rtems_ftpd_hook ftp_hooks[] =
    4951    {
    50     {"untar", Untar_FromMemory},
    51     {NULL, NULL}
     52        {"untar", Untar_FromMemory},
     53        {NULL, NULL}
    5254    };
     55
    5356    struct rtems_ftpd_configuration rtems_ftpd_configuration =
    5457    {
    55     40,                     /* FTPD task priority \*/
    56     512*1024,               /* Maximum hook 'file' size \*/
    57     0,                      /* Use default port \*/
    58     ftp_hooks               /* Local ftp hooks \*/
     58        40,                     /* FTPD task priority */
     59        512*1024,               /* Maximum hook 'file' size */
     60        0,                      /* Use default port */
     61        ftp_hooks               /* Local ftp hooks */
    5962    };
    6063
    61 Specifying 0 for the well-known port causes FTPD to use the
    62 UNIX standard FTPD port (21).
     64Specifying 0 for the well-known port causes FTPD to use the UNIX standard FTPD
     65port (21).
    6366
    6467Using Hooks
    6568-----------
    6669
    67 In the example above, one hook was installed.  The hook causes
    68 FTPD to call the function ``Untar_FromMemory`` when the
    69 user sends data to the file ``untar``.  The prototype for
    70 the ``untar`` hook (and hooks, in general) is:
    71 .. code:: c
     70In the example above, one hook was installed.  The hook causes FTPD to call the
     71function ``Untar_FromMemory`` when the user sends data to the file ``untar``.
     72The prototype for the ``untar`` hook (and hooks, in general) is:
    7273
    73     int Untar_FromMemory(unsigned char \*tar_buf, unsigned long size);
     74.. code-block:: c
     75
     76    int Untar_FromMemory(unsigned char *tar_buf, unsigned long size);
    7477
    7578An example FTP transcript which exercises this hook is:
    76 .. code:: c
     79
     80.. code-block:: shell
    7781
    7882    220 RTEMS FTP server (Version 1.0-JWJ) ready.
     
    103107    ftp> quit
    104108    221 Goodbye.
    105 
    106 .. COMMENT: RTEMS Remote Debugger Server Specifications
    107 
    108 .. COMMENT: Written by: Emmanuel Raguet <raguet@crf.canon.fr>
    109 
  • networking/network_task_structure.rst

    rea0777e rb412038  
     1.. COMMENT: Written by Eric Norum
     2.. COMMENT: COPYRIGHT (c) 1988-2002.
     3.. COMMENT: On-Line Applications Research Corporation (OAR).
     4.. COMMENT: All rights reserved.
     5
    16Network Task Structure and Data Flow
    27####################################
    38
    4 A schematic diagram of the tasks and message *mbuf* queues in a
    5 simple RTEMS networking application is shown in the following
    6 figure:
     9A schematic diagram of the tasks and message *mbuf* queues in a simple RTEMS
     10networking application is shown in the following figure:
    711
    812.. image:: images/networkflow.jpg
    913
    1014
    11 The transmit task  for each network interface is normally blocked waiting
    12 for a packet to arrive in the transmit queue.  Once a packet arrives, the
    13 transmit task may block waiting for an event from the transmit interrupt
    14 handler.  The transmit interrupt handler sends an RTEMS event to the transmit
    15 task to indicate that transmit hardware resources have become available.
     15The transmit task for each network interface is normally blocked waiting for a
     16packet to arrive in the transmit queue.  Once a packet arrives, the transmit
     17task may block waiting for an event from the transmit interrupt handler.  The
     18transmit interrupt handler sends an RTEMS event to the transmit task to
     19indicate that transmit hardware resources have become available.
    1620
    17 The receive task for each network interface is normally blocked waiting
    18 for an event from the receive interrupt handler.  When this event is received
    19 the receive task reads the packet and forwards it to the network stack
    20 for subsequent processing by the network task.
     21The receive task for each network interface is normally blocked waiting for an
     22event from the receive interrupt handler.  When this event is received the
     23receive task reads the packet and forwards it to the network stack for
     24subsequent processing by the network task.
    2125
    22 The network task processes incoming packets and takes care of
    23 timed operations such as handling TCP timeouts and
    24 aging and removing routing table entries.
     26The network task processes incoming packets and takes care of timed operations
     27such as handling TCP timeouts and aging and removing routing table entries.
    2528
    26 The 'Network code' contains routines which may run in the context of
    27 the user application tasks, the interface receive task or the network task.
    28 A network semaphore ensures that
    29 the data structures manipulated by the network code remain consistent.
    30 
    31 .. COMMENT: Written by Eric Norum
    32 
    33 .. COMMENT: COPYRIGHT (c) 1988-2002.
    34 
    35 .. COMMENT: On-Line Applications Research Corporation (OAR).
    36 
    37 .. COMMENT: All rights reserved.
    38 
     29The 'Network code' contains routines which may run in the context of the user
     30application tasks, the interface receive task or the network task.  A network
     31semaphore ensures that the data structures manipulated by the network code
     32remain consistent.
  • networking/networking_driver.rst

    rea0777e rb412038  
     1.. COMMENT: Written by Eric Norum
     2.. COMMENT: COPYRIGHT (c) 1988-2002.
     3.. COMMENT: On-Line Applications Research Corporation (OAR).
     4.. COMMENT: All rights reserved.
     5
    16Networking Driver
    27#################
     
    510============
    611
    7 This chapter is intended to provide an introduction to the
    8 procedure for writing RTEMS network device drivers.
    9 The example code is taken from the 'Generic 68360' network device
    10 driver.  The source code for this driver is located in the``c/src/lib/libbsp/m68k/gen68360/network`` directory in the RTEMS
    11 source code distribution.  Having a copy of this driver at
    12 hand when reading the following notes will help significantly.
     12This chapter is intended to provide an introduction to the procedure for
     13writing RTEMS network device drivers.  The example code is taken from the
     14'Generic 68360' network device driver.  The source code for this driver is
     15located in the :file:`c/src/lib/libbsp/m68k/gen68360/network` directory in the
     16RTEMS source code distribution.  Having a copy of this driver at hand when
     17reading the following notes will help significantly.
    1318
    1419Learn about the network device
    1520==============================
    1621
    17 Before starting to write the network driver become completely
    18 familiar with the programmer's view of the device.
    19 The following points list some of the details of the
    20 device that must be understood before a driver can be written.
    21 
    22 - Does the device use DMA to transfer packets to and from
    23   memory or does the processor have to
    24   copy packets to and from memory on the device?
    25 
    26 - If the device uses DMA, is it capable of forming a single
    27   outgoing packet from multiple fragments scattered in separate
    28   memory buffers?
    29 
    30 - If the device uses DMA, is it capable of chaining multiple
    31   outgoing packets, or does each outgoing packet require
    32   intervention by the driver?
    33 
    34 - Does the device automatically pad short frames to the minimum
    35   64 bytes or does the driver have to supply the padding?
    36 
    37 - Does the device automatically retry a transmission on detection
    38   of a collision?
    39 
    40 - If the device uses DMA, is it capable of buffering multiple
    41   packets to memory, or does the receiver have to be restarted
    42   after the arrival of each packet?
    43 
    44 - How are packets that are too short, too long, or received with
    45   CRC errors handled?  Does the device automatically continue
    46   reception or does the driver have to intervene?
    47 
    48 - How is the device Ethernet address set?  How is the device
    49   programmed to accept or reject broadcast and multicast packets?
    50 
    51 - What interrupts does the device generate?  Does it generate an
    52   interrupt for each incoming packet, or only for packets received
    53   without error?  Does it generate an interrupt for each packet
    54   transmitted, or only when the transmit queue is empty?  What
    55   happens when a transmit error is detected?
    56 
    57 In addition, some controllers have specific questions regarding
    58 board specific configuration.  For example, the SONIC Ethernet
    59 controller has a very configurable data bus interface.  It can
    60 even be configured for sixteen and thirty-two bit data buses.  This
    61 type of information should be obtained from the board vendor.
     22Before starting to write the network driver become completely familiar with the
     23programmer's view of the device.  The following points list some of the details
     24of the device that must be understood before a driver can be written.
     25
     26- Does the device use DMA to transfer packets to and from memory or does the
     27  processor have to copy packets to and from memory on the device?
     28
     29- If the device uses DMA, is it capable of forming a single outgoing packet
     30  from multiple fragments scattered in separate memory buffers?
     31
     32- If the device uses DMA, is it capable of chaining multiple outgoing packets,
     33  or does each outgoing packet require intervention by the driver?
     34
     35- Does the device automatically pad short frames to the minimum 64 bytes or
     36  does the driver have to supply the padding?
     37
     38- Does the device automatically retry a transmission on detection of a
     39  collision?
     40
     41- If the device uses DMA, is it capable of buffering multiple packets to
     42  memory, or does the receiver have to be restarted after the arrival of each
     43  packet?
     44
     45- How are packets that are too short, too long, or received with CRC errors
     46  handled?  Does the device automatically continue reception or does the driver
     47  have to intervene?
     48
     49- How is the device Ethernet address set?  How is the device programmed to
     50  accept or reject broadcast and multicast packets?
     51
     52- What interrupts does the device generate?  Does it generate an interrupt for
     53  each incoming packet, or only for packets received without error?  Does it
     54  generate an interrupt for each packet transmitted, or only when the transmit
     55  queue is empty?  What happens when a transmit error is detected?
     56
     57In addition, some controllers have specific questions regarding board specific
     58configuration.  For example, the SONIC Ethernet controller has a very
     59configurable data bus interface.  It can even be configured for sixteen and
     60thirty-two bit data buses.  This type of information should be obtained from
     61the board vendor.
    6262
    6363Understand the network scheduling conventions
    6464=============================================
    6565
    66 When writing code for the driver transmit and receive tasks,
    67 take care to follow the network scheduling conventions.  All tasks
    68 which are associated with networking share various
    69 data structures and resources.  To ensure the consistency
    70 of these structures the tasks
    71 execute only when they hold the network semaphore (``rtems_bsdnet_semaphore``).
    72 The transmit and receive tasks must abide by this protocol.  Be very
    73 careful to avoid 'deadly embraces' with the other network tasks.
    74 A number of routines are provided to make it easier for the network
    75 driver code to conform to the network task scheduling conventions.
     66When writing code for the driver transmit and receive tasks, take care to
     67follow the network scheduling conventions.  All tasks which are associated with
     68networking share various data structures and resources.  To ensure the
     69consistency of these structures the tasks execute only when they hold the
     70network semaphore (``rtems_bsdnet_semaphore``).  The transmit and receive tasks
     71must abide by this protocol.  Be very careful to avoid 'deadly embraces' with
     72the other network tasks.  A number of routines are provided to make it easier
     73for the network driver code to conform to the network task scheduling
     74conventions.
    7675
    7776- ``void rtems_bsdnet_semaphore_release(void)``
    78   This function releases the network semaphore.
    79   The network driver tasks must call this function immediately before
    80   making any blocking RTEMS request.
     77  This function releases the network semaphore.  The network driver tasks must
     78  call this function immediately before making any blocking RTEMS request.
    8179
    8280- ``void rtems_bsdnet_semaphore_obtain(void)``
    83   This function obtains the network semaphore.
    84   If a network driver task has released the network semaphore to allow other
    85   network-related tasks to run while the task blocks, then this function must
    86   be called to reobtain the semaphore immediately after the return from the
    87   blocking RTEMS request.
    88 
    89 - ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set \*)``
    90   The network driver task should call this function when it wishes to wait
    91   for an event.  This function releases the network semaphore,
    92   calls ``rtems_event_receive`` to wait for the specified event
    93   or events and reobtains the semaphore.
    94   The value returned is the value returned by the ``rtems_event_receive``.
     81  This function obtains the network semaphore.  If a network driver task has
     82  released the network semaphore to allow other network-related tasks to run
     83  while the task blocks, then this function must be called to reobtain the
     84  semaphore immediately after the return from the blocking RTEMS request.
     85
     86- ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)``
     87  The network driver task should call this function when it wishes to wait for
     88  an event.  This function releases the network semaphore, calls
     89  ``rtems_event_receive`` to wait for the specified event or events and
     90  reobtains the semaphore.  The value returned is the value returned by the
     91  ``rtems_event_receive``.
    9592
    9693Network Driver Makefile
    9794=======================
    9895
    99 Network drivers are considered part of the BSD network package and as such
    100 are to be compiled with the appropriate flags.  This can be accomplished by
    101 adding ``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``.
    102 If the driver is inside the RTEMS source tree or is built using the
    103 RTEMS application Makefiles, then adding the following line accomplishes
    104 this:
    105 .. code:: c
     96Network drivers are considered part of the BSD network package and as such are
     97to be compiled with the appropriate flags.  This can be accomplished by adding
     98``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``.  If the driver
     99is inside the RTEMS source tree or is built using the RTEMS application
     100Makefiles, then adding the following line accomplishes this:
     101
     102.. code-block:: c
    106103
    107104    DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
    108105
    109 This is equivalent to the following list of definitions.  Early versions
    110 of the RTEMS BSD network stack required that all of these be defined.
    111 
    112 .. code:: c
    113 
    114     -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \\
    115     -DDIAGNOSTIC -DBOOTP_COMPAT
    116 
    117 Defining these macros tells the network header files that the driver
    118 is to be compiled with extended visibility into the network stack.  This
    119 is in sharp contrast to applications that simply use the network stack.
    120 Applications do not require this level of visibility and should stick
    121 to the portable application level API.
    122 
    123 As a direct result of being logically internal to the network stack,
    124 network drivers use the BSD memory allocation routines   This means,
    125 for example, that malloc takes three arguments.  See the SONIC
    126 device driver (``c/src/lib/libchip/network/sonic.c``) for an example
    127 of this.  Because of this, network drivers should not include``<stdlib.h>``.  Doing so will result in conflicting definitions
    128 of ``malloc()``.
    129 
    130 *Application level* code including network servers such as the FTP
    131 daemon are *not* part of the BSD kernel network code and should not be
    132 compiled with the BSD network flags.  They should include``<stdlib.h>`` and not define the network stack visibility
    133 macros.
     106This is equivalent to the following list of definitions.  Early versions of the
     107RTEMS BSD network stack required that all of these be defined.
     108
     109.. code-block:: c
     110
     111    -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \
     112      -DDIAGNOSTIC -DBOOTP_COMPAT
     113
     114Defining these macros tells the network header files that the driver is to be
     115compiled with extended visibility into the network stack.  This is in sharp
     116contrast to applications that simply use the network stack.  Applications do
     117not require this level of visibility and should stick to the portable
     118application level API.
     119
     120As a direct result of being logically internal to the network stack, network
     121drivers use the BSD memory allocation routines This means, for example, that
     122malloc takes three arguments.  See the SONIC device driver
     123(:file:`c/src/lib/libchip/network/sonic.c`) for an example of this.  Because of
     124this, network drivers should not include ``<stdlib.h>``.  Doing so will result
     125in conflicting definitions of ``malloc()``.
     126
     127*Application level* code including network servers such as the FTP daemon are
     128*not* part of the BSD kernel network code and should not be compiled with the
     129BSD network flags.  They should include ``<stdlib.h>`` and not define the
     130network stack visibility macros.
    134131
    135132Write the Driver Attach Function
    136133================================
    137134
    138 The driver attach function is responsible for configuring the driver
    139 and making the connection between the network stack
    140 and the driver.
    141 
    142 Driver attach functions take a pointer to an``rtems_bsdnet_ifconfig`` structure as their only argument.
    143 and set the driver parameters based on the
    144 values in this structure.  If an entry in the configuration
    145 structure is zero the attach function chooses an
    146 appropriate default value for that parameter.
    147 
    148 The driver should then set up several fields in the ifnet structure
    149 in the device-dependent data structure supplied and maintained by the driver:
     135The driver attach function is responsible for configuring the driver and making
     136the connection between the network stack and the driver.
     137
     138Driver attach functions take a pointer to an ``rtems_bsdnet_ifconfig``
     139structure as their only argument.  and set the driver parameters based on the
     140values in this structure.  If an entry in the configuration structure is zero
     141the attach function chooses an appropriate default value for that parameter.
     142
     143The driver should then set up several fields in the ifnet structure in the
     144device-dependent data structure supplied and maintained by the driver:
    150145
    151146``ifp->if_softc``
    152     Pointer to the device-dependent data.  The first entry
    153     in the device-dependent data structure must be an ``arpcom``
     147    Pointer to the device-dependent data.  The first entry in the
     148    device-dependent data structure must be an ``arpcom`` structure.
     149
     150``ifp->if_name``
     151    The name of the device.  The network stack uses this string and the device
     152    number for device name lookups.  The device name should be obtained from
     153    the ``name`` entry in the configuration structure.
     154
     155``ifp->if_unit``
     156    The device number.  The network stack uses this number and the device name
     157    for device name lookups.  For example, if ``ifp->if_name`` is ``scc`` and
     158    ``ifp->if_unit`` is ``1``, the full device name would be ``scc1``.  The
     159    unit number should be obtained from the 'name' entry in the configuration
    154160    structure.
    155161
    156 ``ifp->if_name``
    157     The name of the device.  The network stack uses this string
    158     and the device number for device name lookups.  The device name should
    159     be obtained from the ``name`` entry in the configuration structure.
    160 
    161 ``ifp->if_unit``
    162     The device number.  The network stack uses this number and the
    163     device name for device name lookups.  For example, if``ifp->if_name`` is '``scc``' and ``ifp->if_unit`` is '``1``',
    164     the full device name would be '``scc1``'.  The unit number should be
    165     obtained from the 'name' entry in the configuration structure.
    166 
    167162``ifp->if_mtu``
    168     The maximum transmission unit for the device.  For Ethernet
    169     devices this value should almost always be 1500.
     163    The maximum transmission unit for the device.  For Ethernet devices this
     164    value should almost always be 1500.
    170165
    171166``ifp->if_flags``
    172     The device flags.  Ethernet devices should set the flags
    173     to ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the
    174     device can broadcast packets to multiple destinations
    175     and does not receive and transmit at the same time.
     167    The device flags.  Ethernet devices should set the flags to
     168    ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the device can broadcast
     169    packets to multiple destinations and does not receive and transmit at the
     170    same time.
    176171
    177172``ifp->if_snd.ifq_maxlen``
    178     The maximum length of the queue of packets waiting to be
    179     sent to the driver.  This is normally set to ``ifqmaxlen``.
     173    The maximum length of the queue of packets waiting to be sent to the
     174    driver.  This is normally set to ``ifqmaxlen``.
    180175
    181176``ifp->if_init``
     
    189184
    190185``ifp->if_output``
    191     The address of the output function.  Ethernet devices
    192     should set this to ``ether_output``.
    193 
    194 RTEMS provides a function to parse the driver name in the
    195 configuration structure into a device name and unit number.
    196 .. code:: c
     186    The address of the output function.  Ethernet devices should set this to
     187    ``ether_output``.
     188
     189RTEMS provides a function to parse the driver name in the configuration
     190structure into a device name and unit number.
     191
     192.. code-block:: c
    197193
    198194    int rtems_bsdnet_parse_driver_name (
    199     const struct rtems_bsdnet_ifconfig \*config,
    200     char \**namep
     195        const struct rtems_bsdnet_ifconfig *config,
     196        char **namep
    201197    );
    202198
    203 The function takes two arguments; a pointer to the configuration
    204 structure and a pointer to a pointer to a character.  The function
    205 parses the configuration name entry, allocates memory for the driver
    206 name, places the driver name in this memory, sets the second argument
    207 to point to the name and returns the unit number.
    208 On error, a message is printed and -1 is returned.
    209 
    210 Once the attach function  has set up the above entries it must link the
    211 driver data structure onto the list of devices by
    212 calling ``if_attach``.  Ethernet devices should then
    213 call ``ether_ifattach``.  Both functions take a pointer to the
    214 device's ``ifnet`` structure as their only argument.
    215 
    216 The attach function should return a non-zero value to indicate that
    217 the driver has been successfully configured and attached.
     199The function takes two arguments; a pointer to the configuration structure and
     200a pointer to a pointer to a character.  The function parses the configuration
     201name entry, allocates memory for the driver name, places the driver name in
     202this memory, sets the second argument to point to the name and returns the unit
     203number.  On error, a message is printed and ``-1`` is returned.
     204
     205Once the attach function has set up the above entries it must link the driver
     206data structure onto the list of devices by calling ``if_attach``.  Ethernet
     207devices should then call ``ether_ifattach``.  Both functions take a pointer to
     208the device's ``ifnet`` structure as their only argument.
     209
     210The attach function should return a non-zero value to indicate that the driver
     211has been successfully configured and attached.
    218212
    219213Write the Driver Start Function.
     
    221215
    222216This function is called each time the network stack wants to start the
    223 transmitter.  This occures whenever the network stack adds a packet
    224 to a device's send queue and the ``IFF_OACTIVE`` bit in the
    225 device's ``if_flags`` is not set.
    226 
    227 For many devices this function need only set the ``IFF_OACTIVE`` bit in the``if_flags`` and send an event to the transmit task
    228 indicating that a packet is in the driver transmit queue.
     217transmitter.  This occures whenever the network stack adds a packet to a
     218device's send queue and the ``IFF_OACTIVE`` bit in the device's ``if_flags`` is
     219not set.
     220
     221For many devices this function need only set the ``IFF_OACTIVE`` bit in the
     222``if_flags`` and send an event to the transmit task indicating that a packet is
     223in the driver transmit queue.
    229224
    230225Write the Driver Initialization Function.
    231226=========================================
    232227
    233 This function should initialize the device, attach to interrupt handler,
    234 and start the driver transmit and receive tasks.  The function
    235 .. code:: c
     228This function should initialize the device, attach to interrupt handler, and
     229start the driver transmit and receive tasks.  The function
     230
     231.. code-block:: c
    236232
    237233    rtems_id
    238     rtems_bsdnet_newproc (char \*name,
    239     int stacksize,
    240     void(\*entry)(void \*),
    241     void \*arg);
     234    rtems_bsdnet_newproc (char *name,
     235        int stacksize,
     236        void(*entry)(void *),
     237        void *arg);
    242238
    243239should be used to start the driver tasks.
    244240
    245241Note that the network stack may call the driver initialization function more
    246 than once.
    247 Make sure multiple versions of the receive and transmit tasks are not accidentally
    248 started.
     242than once.  Make sure multiple versions of the receive and transmit tasks are
     243not accidentally started.
    249244
    250245Write the Driver Transmit Task
    251246==============================
    252247
    253 This 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
    254 driver start function indicating that packets are waiting to be transmitted.
    255 When the transmit task has drained the driver send queue the task should clear
    256 the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another outgoing
    257 packet is queued.
     248This task is reponsible for removing packets from the driver send queue and
     249sending them to the device.  The task should block waiting for an event from
     250the driver start function indicating that packets are waiting to be
     251transmitted.  When the transmit task has drained the driver send queue the task
     252should clear the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another
     253outgoing packet is queued.
    258254
    259255Write the Driver Receive Task
    260256=============================
    261257
    262 This task should block until a packet arrives from the device.  If the
    263 device is an Ethernet interface the function ``ether_input`` should be called
    264 to forward the packet to the network stack.   The arguments to ``ether_input``
    265 are a pointer to the interface data structure, a pointer to the ethernet
    266 header and a pointer to an mbuf containing the packet itself.
     258This task should block until a packet arrives from the device.  If the device
     259is an Ethernet interface the function ``ether_input`` should be called to
     260forward the packet to the network stack.  The arguments to ``ether_input`` are
     261a pointer to the interface data structure, a pointer to the ethernet header and
     262a pointer to an mbuf containing the packet itself.
    267263
    268264Write the Driver Interrupt Handler
    269265==================================
    270266
    271 A typical interrupt handler will do nothing more than the hardware
    272 manipulation required to acknowledge the interrupt and send an RTEMS event
    273 to wake up the driver receive or transmit task waiting for the event.
    274 Network interface interrupt handlers must not make any calls to other
    275 network routines.
     267A typical interrupt handler will do nothing more than the hardware manipulation
     268required to acknowledge the interrupt and send an RTEMS event to wake up the
     269driver receive or transmit task waiting for the event.  Network interface
     270interrupt handlers must not make any calls to other network routines.
    276271
    277272Write the Driver IOCTL Function
     
    284279
    285280``SIOCSIFADDR``
    286 
    287     If the device is an Ethernet interface these
    288     commands should be passed on to ``ether_ioctl``.
     281    If the device is an Ethernet interface these commands should be passed on
     282    to ``ether_ioctl``.
    289283
    290284``SIOCSIFFLAGS``
    291 
    292     This command should be used to start or stop the device,
    293     depending on the state of the interface ``IFF_UP`` and``IFF_RUNNING`` bits in ``if_flags``:
     285    This command should be used to start or stop the device, depending on the
     286    state of the interface ``IFF_UP`` and ``IFF_RUNNING`` bits in ``if_flags``:
    294287
    295288    ``IFF_RUNNING``
    296 
    297289        Stop the device.
    298290
    299291    ``IFF_UP``
    300 
    301292        Start the device.
    302293
    303294    ``IFF_UP|IFF_RUNNING``
    304 
    305295        Stop then start the device.
    306296
    307297    ``0``
    308 
    309298        Do nothing.
    310299
     
    312301============================================
    313302
    314 This function should print the values of any statistic/diagnostic
    315 counters the network driver may use.  The driver ioctl function should call
    316 the statistic-printing function when the ioctl command is``SIO_RTEMS_SHOW_STATS``.
    317 
    318 .. COMMENT: Written by Eric Norum
    319 
    320 .. COMMENT: COPYRIGHT (c) 1988-2002.
    321 
    322 .. COMMENT: On-Line Applications Research Corporation (OAR).
    323 
    324 .. COMMENT: All rights reserved.
    325 
     303This function should print the values of any statistic/diagnostic counters the
     304network driver may use.  The driver ioctl function should call the
     305statistic-printing function when the ioctl command is ``SIO_RTEMS_SHOW_STATS``.
  • networking/preface.rst

    rea0777e rb412038  
    1 =======
     1.. COMMENT: Written by Eric Norum
     2.. COMMENT: COPYRIGHT (c) 1988-2002.
     3.. COMMENT: On-Line Applications Research Corporation (OAR).
     4.. COMMENT: All rights reserved.
     5
    26Preface
    3 =======
     7#######
    48
    5 This document describes the RTEMS specific parts of the FreeBSD TCP/IP
    6 stack.  Much of this documentation was written by Eric Norum
    7 (eric@skatter.usask.ca)
    8 of the Saskatchewan Accelerator Laboratory
    9 who also ported the FreeBSD TCP/IP stack to RTEMS.
     9This document describes the RTEMS specific parts of the FreeBSD TCP/IP stack.
     10Much of this documentation was written by Eric Norum (eric@skatter.usask.ca) of
     11the Saskatchewan Accelerator Laboratory who also ported the FreeBSD TCP/IP
     12stack to RTEMS.
    1013
    11 The following is a list of resources which should be useful in trying
    12 to understand Ethernet:
     14The following is a list of resources which should be useful in trying to
     15understand Ethernet:
    1316
    1417- *Charles Spurgeon's Ethernet Web Site*
    15   "This site provides extensive information about Ethernet
    16   (IEEE 802.3) local area network (LAN) technology. Including
    17   the original 10 Megabit per second (Mbps) system, the 100 Mbps
    18   Fast Ethernet system (802.3u), and the Gigabit Ethernet system (802.3z)."
    19   The URL is:
     18  "This site provides extensive information about Ethernet (IEEE 802.3) local
     19  area network (LAN) technology. Including the original 10 Megabit per second
     20  (Mbps) system, the 100 Mbps Fast Ethernet system (802.3u), and the Gigabit
     21  Ethernet system (802.3z)."  The URL is:
    2022  (http://www.ethermanage.com/ethernet/ethernet.html)
    2123
    22 - *TCP/IP Illustrated, Volume 1 : The Protocols* by
     24- *TCP/IP Illustrated, Volume 1 : The Protocols*
    2325  by W. Richard Stevens (ISBN: 0201633469)
    2426  This book provides detailed introduction to TCP/IP and includes diagnostic
    2527  programs which are publicly available.
    2628
    27 - *TCP/IP Illustrated, Volume 2 : The Implementation* by W. Richard
    28   Stevens and Gary Wright (ISBN: 020163354X)
     29- *TCP/IP Illustrated, Volume 2 : The Implementation*
     30  by W. Richard Stevens and Gary Wright (ISBN: 020163354X)
    2931  This book focuses on implementation issues regarding TCP/IP.  The
    3032  treat for RTEMS users is that the implementation covered is the BSD
    3133  stack with most of the source code described in detail.
    3234
    33 - *UNIX Network Programming, Volume 1 : 2nd Edition* by W. Richard
    34   Stevens (ISBN: 0-13-490012-X)
     35- *UNIX Network Programming, Volume 1 : 2nd Edition*
     36  by W. Richard Stevens (ISBN: 0-13-490012-X)
    3537  This book describes how to write basic TCP/IP applications, again with primary
    3638  focus on the BSD stack.
    37 
    38 .. COMMENT: Written by Eric Norum
    39 
    40 .. COMMENT: COPYRIGHT (c) 1988-2002.
    41 
    42 .. COMMENT: On-Line Applications Research Corporation (OAR).
    43 
    44 .. COMMENT: All rights reserved.
    45 
  • networking/testing_the_driver.rst

    rea0777e rb412038  
     1.. COMMENT: Text Written by Jake Janovetz
     2.. COMMENT: COPYRIGHT (c) 1988-2002.
     3.. COMMENT: On-Line Applications Research Corporation (OAR).
     4.. COMMENT: All rights reserved.
     5
    16Testing the Driver
    27##################
     
    712The network used to test the driver should include at least:
    813
    9 - The hardware on which the driver is to run.
    10   It makes testing much easier if you can run a debugger to control
    11   the operation of the target machine.
    12 
    13 - An Ethernet network analyzer or a workstation with an
    14   'Ethernet snoop' program such as ``ethersnoop`` or``tcpdump``.
     14- The hardware on which the driver is to run.  It makes testing much easier if
     15  you can run a debugger to control the operation of the target machine.
     16
     17- An Ethernet network analyzer or a workstation with an 'Ethernet snoop'
     18  program such as ``ethersnoop`` or ``tcpdump``.
    1519
    1620- A workstation.
    1721
    18 During early debug, you should consider putting the target, workstation,
    19 and snooper on a small network by themselves.  This offers a few
    20 advantages:
    21 
    22 - There is less traffic to look at on the snooper and for the target
    23   to process while bringing the driver up.
    24 
    25 - Any serious errors will impact only your small network not a building
    26   or campus network.  You want to avoid causing any unnecessary problems.
     22During early debug, you should consider putting the target, workstation, and
     23snooper on a small network by themselves.  This offers a few advantages:
     24
     25- There is less traffic to look at on the snooper and for the target to process
     26  while bringing the driver up.
     27
     28- Any serious errors will impact only your small network not a building or
     29  campus network.  You want to avoid causing any unnecessary problems.
    2730
    2831- Test traffic is easier to repeatably generate.
    2932
    30 - Performance measurements are not impacted by other systems on
    31   the network.
     33- Performance measurements are not impacted by other systems on the network.
    3234
    3335Debug Output
    3436============
    3537
    36 There are a number of sources of debug output that can be enabled
    37 to aid in tracing the behavior of the network stack.  The following
    38 is a list of them:
     38There are a number of sources of debug output that can be enabled to aid in
     39tracing the behavior of the network stack.  The following is a list of them:
    3940
    4041- mbuf activity
    41   There are commented out calls to ``printf`` in the file``sys/mbuf.h`` in the network stack code.  Uncommenting
    42   these lines results in output when mbuf's are allocated
    43   and freed.  This is very useful for finding memory leaks.
     42  There are commented out calls to ``printf`` in the file ``sys/mbuf.h`` in the
     43  network stack code.  Uncommenting these lines results in output when mbuf's
     44  are allocated and freed.  This is very useful for finding memory leaks.
    4445
    4546- TX and RX queuing
    46   There are commented out calls to ``printf`` in the file``net/if.h`` in the network stack code.  Uncommenting
    47   these lines results in output when packets are placed
    48   on or removed from one of the transmit or receive packet
    49   queues.  These queues can be viewed as the boundary line
    50   between a device driver and the network stack.  If the
    51   network stack is enqueuing packets to be transmitted that
    52   the device driver is not dequeuing, then that is indicative
    53   of a problem in the transmit side of the device driver.
    54   Conversely, if the device driver is enqueueing packets
    55   as it receives them (via a call to ``ether_input``) and
    56   they are not being dequeued by the network stack,
    57   then there is a problem.  This situation would likely indicate
    58   that the network server task is not running.
     47  There are commented out calls to ``printf`` in the file ``net/if.h`` in the
     48  network stack code.  Uncommenting these lines results in output when packets
     49  are placed on or removed from one of the transmit or receive packet queues.
     50  These queues can be viewed as the boundary line between a device driver and
     51  the network stack.  If the network stack is enqueuing packets to be
     52  transmitted that the device driver is not dequeuing, then that is indicative
     53  of a problem in the transmit side of the device driver.  Conversely, if the
     54  device driver is enqueueing packets as it receives them (via a call to
     55  ``ether_input``) and they are not being dequeued by the network stack, then
     56  there is a problem.  This situation would likely indicate that the network
     57  server task is not running.
    5958
    6059- TCP state transitions
    61   In the unlikely event that one would actually want to see
    62   TCP state transitions, the ``TCPDEBUG`` macro can be defined
    63   in the file ``opt_tcpdebug.h``.  This results in the routine``tcp_trace()`` being called by the network stack and
    64   the state transitions logged into the ``tcp_debug`` data
    65   structure.  If the variable ``tcpconsdebug`` in the file``netinet/tcp_debug.c`` is set to 1, then the state transitions
    66   will also be printed to the console.
     60
     61  In the unlikely event that one would actually want to see TCP state
     62  transitions, the ``TCPDEBUG`` macro can be defined in the file
     63  ``opt_tcpdebug.h``.  This results in the routine ``tcp_trace()`` being called
     64  by the network stack and the state transitions logged into the ``tcp_debug``
     65  data structure.  If the variable ``tcpconsdebug`` in the file
     66  ``netinet/tcp_debug.c`` is set to ``1``, then the state transitions will also
     67  be printed to the console.
    6768
    6869Monitor Commands
    6970================
    7071
    71 There are a number of command available in the shell / monitor
    72 to aid in tracing the behavior of the network stack.  The following
    73 is a list of them:
     72There are a number of command available in the shell / monitor to aid in
     73tracing the behavior of the network stack.  The following is a list of them:
    7474
    7575- ``inet``
    76   This command shows the current routing information for the TCP/IP stack. Following is an
    77   example showing the output of this command.
    78 
    79   .. code:: c
     76  This command shows the current routing information for the TCP/IP
     77  stack. Following is an example showing the output of this command.
     78
     79  .. code-block:: shell
    8080
    8181      Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
     
    8383      127.0.0.1       127.0.0.1          UH          0        0      0 lo0
    8484
    85   In this example, there is only one network interface with an IP address of 10.8.1.1.  This
    86   link is currently not up.
    87   Two routes that are shown are the default routes for the Ethernet interface (10.0.0.0) and the
    88   loopback interface (127.0.0.1).
    89   Since the stack comes from BSD, this command is very similar to the netstat command.  For more
    90   details on the network routing please look the following
    91   URL: (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html)
     85  In this example, there is only one network interface with an IP address of
     86  10.8.1.1.  This link is currently not up.  Two routes that are shown are the
     87  default routes for the Ethernet interface (10.0.0.0) and the loopback
     88  interface (127.0.0.1).  Since the stack comes from BSD, this command is very
     89  similar to the netstat command.  For more details on the network routing
     90  please look the following URL:
     91  (http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-routing.html)
    9292  For a quick reference to the flags, see the table below:
    9393
     
    9999
    100100  '``G``'
    101       Gateway: Send anything for this destination on to this remote system, which
    102       will figure out from there where to send it.
     101      Gateway: Send anything for this destination on to this remote system,
     102      which will figure out from there where to send it.
    103103
    104104  '``S``'
    105       Static: This route was configured manually, not automatically generated by the
    106       system.
     105      Static: This route was configured manually, not automatically generated
     106      by the system.
    107107
    108108  '``C``'
    109       Clone: Generates a new route based upon this route for machines we connect
    110       to. This type of route is normally used for local networks.
     109      Clone: Generates a new route based upon this route for machines we
     110      connect to. This type of route is normally used for local networks.
    111111
    112112  '``W``'
    113       WasCloned: Indicated a route that was auto-configured based upon a local area
    114       network (Clone) route.
     113      WasCloned: Indicated a route that was auto-configured based upon a local
     114      area network (Clone) route.
    115115
    116116  '``L``'
     
    118118
    119119- ``mbuf``
    120 
    121   This command shows the current MBUF statistics.  An example of the command is shown below:
    122 
    123   .. code:: c
     120  This command shows the current MBUF statistics.  An example of the command is
     121  shown below:
     122
     123  .. code-block:: shell
    124124
    125125      ************ MBUF STATISTICS \************
     
    127127      drops:   0       waits:   0  drains:   0
    128128      free:4080          data:16          header:0           socket:0
    129       pcb:0           rtable:0           htable:0           atable:0
    130       soname:0           soopts:0           ftable:0           rights:0
    131       ifaddr:0          control:0          oobdata:0
     129      pcb:0             rtable:0          htable:0           atable:0
     130      soname:0          soopts:0          ftable:0           rights:0
     131      ifaddr:0         control:0         oobdata:0
    132132
    133133- ``if``
    134 
    135   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:
    136 
    137   .. code:: c
     134  This command shows the current statistics for your Ethernet driver as long as
     135  the ioctl hook ``SIO_RTEMS_SHOW_STATS`` has been implemented.  Below is an
     136  example:
     137
     138  .. code-block:: shell
    138139
    139140      ************ INTERFACE STATISTICS \************
     
    145146      SMC91C111 RTEMS driver A0.01 11/03/2002 Ian Caddy (ianc@microsol.iinet.net.au)
    146147      Rx Interrupts:0              Not First:0               Not Last:0
    147       Giant:0                   Runt:0              Non-octet:0
    148       Bad CRC:0                Overrun:0              Collision:0
     148      Giant:0                           Runt:0              Non-octet:0
     149      Bad CRC:0                      Overrun:0              Collision:0
    149150      Tx Interrupts:2               Deferred:0        Missed Hearbeat:0
    150       No Carrier:0       Retransmit Limit:0         Late Collision:0
    151       Underrun:0        Raw output wait:0              Coalesced:0
     151      No Carrier:0          Retransmit Limit:0         Late Collision:0
     152      Underrun:0             Raw output wait:0              Coalesced:0
    152153      Coalesce failed:0                Retries:0
    153154      \***** lo0 \*****
     
    177178- Start with ``RTEMS_USE_BOOTP`` not defined.
    178179
    179 - Edit ``networkconfig.h`` to configure the driver
    180   with an
    181   explicit Ethernet and Internet address and with reception of
    182   broadcast packets disabled:
    183   Verify that the program continues to run once the driver has been attached.
    184 
    185 - Issue a '``u``' command to send UDP
    186   packets to the 'discard' port.
    187   Verify that the packets appear on the network.
     180- Edit ``networkconfig.h`` to configure the driver with an explicit Ethernet
     181  and Internet address and with reception of broadcast packets disabled: Verify
     182  that the program continues to run once the driver has been attached.
     183
     184- Issue a '``u``' command to send UDP packets to the 'discard' port.  Verify
     185  that the packets appear on the network.
    188186
    189187- Issue a '``s``' command to print the network and driver statistics.
     
    194192  Verify that the ICMP echo request and reply packets appear on the net.
    195193
    196 - Remove the static route to the target system.
    197   Modify ``networkconfig.h`` to attach the driver
    198   with reception of broadcast packets enabled.
    199   Try to 'ping' the target system again.
    200   Verify that ARP request/reply and ICMP echo request/reply packets appear
    201   on the net.
    202 
    203 - Issue a '``t``' command to send TCP
    204   packets to the 'discard' port.
    205   Verify that the packets appear on the network.
     194- Remove the static route to the target system.  Modify ``networkconfig.h`` to
     195  attach the driver with reception of broadcast packets enabled.  Try to 'ping'
     196  the target system again.  Verify that ARP request/reply and ICMP echo
     197  request/reply packets appear on the net.
     198
     199- Issue a '``t``' command to send TCP packets to the 'discard' port.  Verify
     200  that the packets appear on the network.
    206201
    207202- Issue a '``s``' command to print the network and driver statistics.
    208203
    209 - Verify that you can telnet to ports 24742
    210   and 24743 on the target system from one or more
    211   workstations on your network.
     204- Verify that you can telnet to ports 24742 and 24743 on the target system from
     205  one or more workstations on your network.
    212206
    213207BOOTP/DHCP operation
    214208====================
    215209
    216 Set up a BOOTP/DHCP server on the network.
    217 Set define ``RTEMS USE_BOOT`` in ``networkconfig.h``.
    218 Run the ``netdemo`` test program.
    219 Verify that the target system configures itself from the BOOTP/DHCP server and
    220 that all the above tests succeed.
     210Set up a BOOTP/DHCP server on the network.  Set define ``RTEMS USE_BOOT`` in
     211``networkconfig.h``.  Run the ``netdemo`` test program.  Verify that the target
     212system configures itself from the BOOTP/DHCP server and that all the above
     213tests succeed.
    221214
    222215Stress Tests
    223216============
    224217
    225 Once the driver passes the tests described in the previous section it should
    226 be subjected to conditions which exercise it more
    227 thoroughly and which test its error handling routines.
     218Once the driver passes the tests described in the previous section it should be
     219subjected to conditions which exercise it more thoroughly and which test its
     220error handling routines.
    228221
    229222Giant packets
    230223-------------
    231224
    232 - Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to
    233   a smaller value, say 514.
    234 
    235 - 'Ping' the driver from another workstation and verify
    236   that frames larger than 514 bytes are correctly rejected.
     225- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` set to a smaller value,
     226  say 514.
     227
     228- 'Ping' the driver from another workstation and verify that frames larger than
     229  514 bytes are correctly rejected.
    237230
    238231- Recompile the driver with ``MAXIMUM_FRAME_SIZE`` restored  to 1518.
     
    241234-------------------
    242235
    243 - Edit  ``networkconfig.h``
    244   so that the driver is configured with just two receive and transmit descriptors.
     236- Edit ``networkconfig.h`` so that the driver is configured with just two
     237  receive and transmit descriptors.
    245238
    246239- Compile and run the ``netdemo`` program.
    247240
    248 - Verify that the program operates properly and that you can
    249   still telnet to both the ports.
    250 
    251 - Display the driver statistics (Console '``s``' command or telnet
    252   'control-G' character) and verify that:
    253 
    254   # The number of transmit interrupts is non-zero.
    255     This indicates that all transmit descriptors have been in use at some time.
    256 
    257   # The number of missed packets is non-zero.
    258     This indicates that all receive descriptors have been in use at some time.
     241- Verify that the program operates properly and that you can still telnet to
     242  both the ports.
     243
     244- Display the driver statistics (Console '``s``' command or telnet 'control-G'
     245  character) and verify that:
     246
     247  #. The number of transmit interrupts is non-zero.  This indicates that all
     248    transmit descriptors have been in use at some time.
     249
     250  #. The number of missed packets is non-zero.  This indicates that all receive
     251    descriptors have been in use at some time.
    259252
    260253Cable Faults
     
    263256- Run the ``netdemo`` program.
    264257
    265 - Issue a '``u``' console command to make the target machine transmit
    266   a bunch of UDP packets.
    267 
    268 - While the packets are being transmitted, disconnect and reconnect the
    269   network cable.
    270 
    271 - Display the network statistics and verify that the driver has
    272   detected the loss of carrier.
     258- Issue a '``u``' console command to make the target machine transmit a bunch
     259  of UDP packets.
     260
     261- While the packets are being transmitted, disconnect and reconnect the network
     262  cable.
     263
     264- Display the network statistics and verify that the driver has detected the
     265  loss of carrier.
    273266
    274267- Verify that you can still telnet to both ports on the target machine.
     
    277270----------
    278271
    279 Run the ``ttcp`` network benchmark program.
    280 Transfer large amounts of data (100's of megabytes) to and from the target
    281 system.
    282 
    283 The procedure for testing throughput from a host to an RTEMS target
    284 is as follows:
    285 
    286 # Download and start the ttcp program on the Target.
    287 
    288 # In response to the ``ttcp`` prompt, enter ``-s -r``.  The
    289   meaning of these flags is described in the ``ttcp.1`` manual page
    290   found in the ``ttcp_orig`` subdirectory.
    291 
    292 # On the host run ``ttcp -s -t <<insert the hostname or IP address of  the Target here>>``
    293 
    294 The procedure for testing throughput from an RTEMS target
    295 to a Host is as follows:
    296 
    297 # On the host run ``ttcp -s -r``.
    298 
    299 # Download and start the ttcp program on the Target.
    300 
    301 # In response to the ``ttcp`` prompt, enter ``-s -t <<insert  the hostname or IP address of the Target here>>``.  You need to type the
    302   IP address of the host unless your Target is talking to your Domain Name
    303   Server.
    304 
    305 To change the number of buffers, the buffer size, etc. you just add the
    306 extra flags to the ``-t`` machine as specified in the ``ttcp.1``
    307 manual page found in the ``ttcp_orig`` subdirectory.
    308 
    309 .. COMMENT: Text Written by Jake Janovetz
    310 
    311 .. COMMENT: COPYRIGHT (c) 1988-2002.
    312 
    313 .. COMMENT: On-Line Applications Research Corporation (OAR).
    314 
    315 .. COMMENT: All rights reserved.
    316 
     272Run the ``ttcp`` network benchmark program.  Transfer large amounts of data
     273(100's of megabytes) to and from the target system.
     274
     275The procedure for testing throughput from a host to an RTEMS target is as
     276follows:
     277
     278 #. Download and start the ttcp program on the Target.
     279
     280 #. In response to the ``ttcp`` prompt, enter ``-s -r``.  The meaning of these
     281    flags is described in the ``ttcp.1`` manual page found in the ``ttcp_orig``
     282    subdirectory.
     283
     284 #. On the host run ``ttcp -s -t <<insert the hostname or IP address of  the Target here>>``
     285
     286The procedure for testing throughput from an RTEMS target to a Host is as
     287follows:
     288
     289 #. On the host run ``ttcp -s -r``.
     290
     291 #. Download and start the ttcp program on the Target.
     292
     293 #. In response to the ``ttcp`` prompt, enter ``-s -t <<insert the hostname or
     294    IP address of the Target here>>``.  You need to type the IP address of the
     295    host unless your Target is talking to your Domain Name Server.
     296
     297To change the number of buffers, the buffer size, etc. you just add the extra
     298flags to the ``-t`` machine as specified in the ``ttcp.1`` manual page found in
     299the ``ttcp_orig`` subdirectory.
  • networking/using_networking_rtems_app.rst

    rea0777e rb412038  
     1.. COMMENT: Written by Eric Norum
     2.. COMMENT: COPYRIGHT (c) 1988-2002.
     3.. COMMENT: On-Line Applications Research Corporation (OAR).
     4.. COMMENT: All rights reserved.
     5
    16Using Networking in an RTEMS Application
    27########################################
     
    813-------------------------------
    914
    10 The FreeBSD networking code requires several RTEMS managers
    11 in the application:
    12 .. code:: c
     15The FreeBSD networking code requires several RTEMS managers in the application:
     16
     17.. code-block:: c
    1318
    1419    MANAGERS = io event semaphore
     
    1722-------------------------------
    1823
    19 The networking tasks allocate a lot of memory.  For most applications
    20 the heap should be at least 256 kbytes.
    21 The amount of memory set aside for the heap can be adjusted by setting
    22 the ``CFLAGS_LD`` definition as shown below:
    23 .. code:: c
     24The networking tasks allocate a lot of memory.  For most applications the heap
     25should be at least 256 kbytes.  The amount of memory set aside for the heap can
     26be adjusted by setting the ``CFLAGS_LD`` definition as shown below:
     27
     28.. code-block:: c
    2429
    2530    CFLAGS_LD += -Wl,--defsym -Wl,HeapSize=0x80000
     
    3035====================
    3136
    32 The networking tasks allocate some RTEMS objects.  These
    33 must be accounted for in the application configuration table.  The following
    34 lists the requirements.
     37The networking tasks allocate some RTEMS objects.  These must be accounted for
     38in the application configuration table.  The following lists the requirements.
    3539
    3640*TASKS*
     
    3842
    3943*SEMAPHORES*
    40     One network semaphore plus one syslog mutex semaphore if the application uses
    41     openlog/syslog.
     44    One network semaphore plus one syslog mutex semaphore if the application
     45    uses openlog/syslog.
    4246
    4347*EVENTS*
    44     The network stack uses ``RTEMS_EVENT_24`` and ``RTEMS_EVENT_25``.
    45     This has no effect on the application configuration, but
    46     application tasks which call the network functions should not
    47     use these events for other purposes.
     48    The network stack uses ``RTEMS_EVENT_24`` and ``RTEMS_EVENT_25``.  This has
     49    no effect on the application configuration, but application tasks which
     50    call the network functions should not use these events for other purposes.
    4851
    4952Initialization
     
    5356------------------------
    5457
    55 The source file which declares the network configuration
    56 structures and calls the network initialization function must include
    57 .. code:: c
     58The source file which declares the network configuration structures and calls
     59the network initialization function must include
     60
     61.. code-block:: c
    5862
    5963    #include <rtems/rtems_bsdnet.h>
     
    6266---------------------
    6367
    64 The network configuration is specified by declaring
    65 and initializing the ``rtems_bsdnet_config``
    66 structure.
    67 .. code:: c
     68The network configuration is specified by declaring and initializing the
     69``rtems_bsdnet_config`` structure.
     70
     71.. code-block:: c
    6872
    6973    struct rtems_bsdnet_config {
    70     /*
    71     * This entry points to the head of the ifconfig chain.
    72     \*/
    73     struct rtems_bsdnet_ifconfig \*ifconfig;
    74     /*
    75     * This entry should be rtems_bsdnet_do_bootp if BOOTP
    76     * is being used to configure the network, and NULL
    77     * if BOOTP is not being used.
    78     \*/
    79     void                    (\*bootp)(void);
    80     /*
    81     * The remaining items can be initialized to 0, in
    82     * which case the default value will be used.
    83     \*/
    84     rtems_task_priority  network_task_priority;  /* 100        \*/
    85     unsigned long        mbuf_bytecount;         /* 64 kbytes  \*/
    86     unsigned long        mbuf_cluster_bytecount; /* 128 kbytes \*/
    87     char                \*hostname;               /* BOOTP      \*/
    88     char                \*domainname;             /* BOOTP      \*/
    89     char                \*gateway;                /* BOOTP      \*/
    90     char                \*log_host;               /* BOOTP      \*/
    91     char                \*name_server[3];         /* BOOTP      \*/
    92     char                \*ntp_server[3];          /* BOOTP      \*/
    93     unsigned long        sb_efficiency;          /* 2          \*/
    94     /* UDP TX: 9216 bytes \*/
    95     unsigned long        udp_tx_buf_size;
    96     /* UDP RX: 40 * (1024 + sizeof(struct sockaddr_in)) \*/
    97     unsigned long        udp_rx_buf_size;
    98     /* TCP TX: 16 * 1024 bytes \*/
    99     unsigned long        tcp_tx_buf_size;
    100     /* TCP TX: 16 * 1024 bytes \*/
    101     unsigned long        tcp_rx_buf_size;
    102     /* Default Network Tasks CPU Affinity \*/
    103     #ifdef RTEMS_SMP
    104     const cpu_set_t     \*network_task_cpuset;
    105     size_t               network_task_cpuset_size;
    106     #endif
     74        /*
     75         * This entry points to the head of the ifconfig chain.
     76         */
     77        struct rtems_bsdnet_ifconfig *ifconfig;
     78        /*
     79         * This entry should be rtems_bsdnet_do_bootp if BOOTP
     80         * is being used to configure the network, and NULL
     81         * if BOOTP is not being used.
     82         */
     83        void                          (*bootp)(void);
     84         /*
     85          * The remaining items can be initialized to 0, in
     86          * which case the default value will be used.
     87          */
     88        rtems_task_priority           network_task_priority;  /* 100        */
     89        unsigned long                 mbuf_bytecount;         /* 64 kbytes  */
     90        unsigned long                 mbuf_cluster_bytecount; /* 128 kbytes */
     91        char                          *hostname;              /* BOOTP      */
     92        char                          *domainname;            /* BOOTP      */
     93        char                          *gateway;               /* BOOTP      */
     94        char                          *log_host;              /* BOOTP      */
     95        char                          *name_server[3];        /* BOOTP      */
     96        char                          *ntp_server[3];         /* BOOTP      */
     97        unsigned long                 sb_efficiency;          /* 2          */
     98        /* UDP TX: 9216 bytes */
     99        unsigned long                 udp_tx_buf_size;
     100        /* UDP RX: 40 * (1024 + sizeof(struct sockaddr_in)) */
     101        unsigned long                 udp_rx_buf_size;
     102        /* TCP TX: 16 * 1024 bytes */
     103        unsigned long                 tcp_tx_buf_size;
     104        /* TCP TX: 16 * 1024 bytes */
     105        unsigned long                 tcp_rx_buf_size;
     106        /* Default Network Tasks CPU Affinity */
     107        #ifdef RTEMS_SMP
     108             const cpu_set_t         *network_task_cpuset;
     109             size_t                   network_task_cpuset_size;
     110        #endif
    107111    };
    108112
    109 The structure entries are described in the following table.
    110 If your application uses BOOTP/DHCP to obtain network configuration
    111 information and if you are happy with the default values described
    112 below, you need to provide only the first two entries in this structure.
    113 
    114 ``struct rtems_bsdnet_ifconfig \*ifconfig``
    115 
    116     A pointer to the first configuration structure of the first network
    117     device.  This structure is described in the following section.
    118     You must provide a value for this entry since there is no default value for it.
    119 
    120 ``void (\*bootp)(void)``
    121 
    122     This entry should be set to ``rtems_bsdnet_do_bootp`` if your
    123     application by default uses the BOOTP/DHCP client protocol to obtain
    124     network configuration information.  It should be set to ``NULL`` if
    125     your application does not use BOOTP/DHCP.
    126     You can also use ``rtems_bsdnet_do_bootp_rootfs`` to have a set of
    127     standard files created with the information return by the BOOTP/DHCP
    128     protocol. The IP address is added to :file:`/etc/hosts` with the host
    129     name and domain returned. If no host name or domain is returned``me.mydomain`` is used. The BOOTP/DHCP server's address is also
    130     added to :file:`/etc/hosts`. The domain name server listed in the
    131     BOOTP/DHCP information are added to :file:`/etc/resolv.conf`. A``search`` record is also added if a domain is returned. The files
    132     are created if they do not exist.
    133     The default ``rtems_bsdnet_do_bootp`` and``rtems_bsdnet_do_bootp_rootfs`` handlers will loop for-ever
    134     waiting for a BOOTP/DHCP server to respond. If an error is detected
    135     such as not valid interface or valid hardware address the target will
    136     reboot allowing any hardware reset to correct itself.
    137     You can provide your own custom handler which allows you to perform
    138     an initialization that meets your specific system requirements. For
    139     example you could try BOOTP/DHCP then enter a configuration tool if no
    140     server is found allowing the user to switch to a static configuration.
     113The structure entries are described in the following table.  If your
     114application uses BOOTP/DHCP to obtain network configuration information and if
     115you are happy with the default values described below, you need to provide only
     116the first two entries in this structure.
     117
     118``struct rtems_bsdnet_ifconfig *ifconfig``
     119    A pointer to the first configuration structure of the first network device.
     120    This structure is described in the following section.  You must provide a
     121    value for this entry since there is no default value for it.
     122
     123``void (*bootp)(void)``
     124    This entry should be set to ``rtems_bsdnet_do_bootp`` if your application
     125    by default uses the BOOTP/DHCP client protocol to obtain network
     126    configuration information.  It should be set to ``NULL`` if your
     127    application does not use BOOTP/DHCP.  You can also use
     128    ``rtems_bsdnet_do_bootp_rootfs`` to have a set of standard files created
     129    with the information return by the BOOTP/DHCP protocol. The IP address is
     130    added to :file:`/etc/hosts` with the host name and domain returned. If no
     131    host name or domain is returned ``me.mydomain`` is used. The BOOTP/DHCP
     132    server's address is also added to :file:`/etc/hosts`. The domain name
     133    server listed in the BOOTP/DHCP information are added to
     134    :file:`/etc/resolv.conf`. A``search`` record is also added if a domain is
     135    returned. The files are created if they do not exist.  The default
     136    ``rtems_bsdnet_do_bootp`` and ``rtems_bsdnet_do_bootp_rootfs`` handlers
     137    will loop for-ever waiting for a BOOTP/DHCP server to respond. If an error
     138    is detected such as not valid interface or valid hardware address the
     139    target will reboot allowing any hardware reset to correct itself.  You can
     140    provide your own custom handler which allows you to perform an
     141    initialization that meets your specific system requirements. For example
     142    you could try BOOTP/DHCP then enter a configuration tool if no server is
     143    found allowing the user to switch to a static configuration.
    141144
    142145``int network_task_priority``
     
    153156    If a value of 0 is specified, 128 kbytes will be allocated.
    154157
    155 ``char \*hostname``
     158``char *hostname``
    156159    The host name of the system.
    157160    If this, or any of the following, entries are ``NULL`` the value
    158161    may be obtained from a BOOTP/DHCP server.
    159162
    160 ``char \*domainname``
     163``char *domainname``
    161164    The name of the Internet domain to which the system belongs.
    162165
    163 ``char \*gateway``
    164     The Internet host number of the network gateway machine,
    165     specified in 'dotted decimal' (``129.128.4.1``) form.
    166 
    167 ``char \*log_host``
    168     The Internet host number of the machine to which ``syslog`` messages
    169     will be sent.
    170 
    171 ``char \*name_server[3]``
    172     The Internet host numbers of up to three machines to be used as
    173     Internet Domain Name Servers.
    174 
    175 ``char \*ntp_server[3]``
     166``char *gateway``
     167    The Internet host number of the network gateway machine, specified in
     168    'dotted decimal' (``129.128.4.1``) form.
     169
     170``char *log_host``
     171    The Internet host number of the machine to which ``syslog`` messages will
     172    be sent.
     173
     174``char *name_server[3]``
     175    The Internet host numbers of up to three machines to be used as Internet
     176    Domain Name Servers.
     177
     178``char *ntp_server[3]``
    176179    The Internet host numbers of up to three machines to be used as
    177180    Network Time Protocol (NTP) Servers.
    178181
    179182``unsigned long sb_efficiency``
    180     This is the first of five configuration parameters related to
    181     the amount of memory each socket may consume for buffers.  The
    182     TCP/IP stack reserves buffers (e.g. mbufs) for each open socket.  The
    183     TCP/IP stack has different limits for the transmit and receive
    184     buffers associated with each TCP and UDP socket.  By tuning these
    185     parameters, the application developer can make trade-offs between
    186     memory consumption and performance.  The default parameters favor
    187     performance over memory consumption.  Seehttp://www.rtems.org/ml/rtems-users/2004/february/msg00200.html
    188     for more details but note that after the RTEMS 4.8 release series,
    189     the sb_efficiency default was changed from ``8`` to ``2``.
    190     The user should also be aware of the ``SO_SNDBUF`` and ``SO_RCVBUF``
    191     IO control operations.  These can be used to specify the
    192     send and receive buffer sizes for a specific socket.  There
    193     is no standard IO control to change the ``sb_efficiency`` factor.
    194     The ``sb_efficiency`` parameter is a buffering factor used
    195     in the implementation of the TCP/IP stack.  The default is ``2``
    196     which indicates double buffering.  When allocating memory for each
     183    This is the first of five configuration parameters related to the amount of
     184    memory each socket may consume for buffers.  The TCP/IP stack reserves
     185    buffers (e.g. mbufs) for each open socket.  The TCP/IP stack has different
     186    limits for the transmit and receive buffers associated with each TCP and
     187    UDP socket.  By tuning these parameters, the application developer can make
     188    trade-offs between memory consumption and performance.  The default
     189    parameters favor performance over memory consumption.  See
     190    http://www.rtems.org/ml/rtems-users/2004/february/msg00200.html for more
     191    details but note that after the RTEMS 4.8 release series, the
     192    ``sb_efficiency`` default was changed from ``8`` to ``2``.  The user should
     193    also be aware of the ``SO_SNDBUF`` and ``SO_RCVBUF`` IO control operations.
     194    These can be used to specify the send and receive buffer sizes for a
     195    specific socket.  There is no standard IO control to change the
     196    ``sb_efficiency`` factor.  The ``sb_efficiency`` parameter is a buffering
     197    factor used in the implementation of the TCP/IP stack.  The default is
     198    ``2`` which indicates double buffering.  When allocating memory for each
    197199    socket, this number is multiplied by the buffer sizes for that socket.
    198200
    199201``unsigned long udp_tx_buf_size``
    200 
    201     This configuration parameter specifies the maximum amount of
    202     buffer memory which may be used for UDP sockets to transmit
    203     with.  The default size is 9216 bytes which corresponds to
    204     the maximum datagram size.
     202    This configuration parameter specifies the maximum amount of buffer memory
     203    which may be used for UDP sockets to transmit with.  The default size is
     204    9216 bytes which corresponds to the maximum datagram size.
    205205
    206206``unsigned long udp_rx_buf_size``
    207 
    208     This configuration parameter specifies the maximum amount of
    209     buffer memory which may be used for UDP sockets to receive
    210     into.  The default size is the following length in bytes:
    211 
    212     .. code:: c
     207    This configuration parameter specifies the maximum amount of buffer memory
     208    which may be used for UDP sockets to receive into.  The default size is the
     209    following length in bytes:
     210
     211    .. code-block:: c
    213212
    214213        40 * (1024 + sizeof(struct sockaddr_in)
    215214
    216215``unsigned long tcp_tx_buf_size``
    217 
    218     This configuration parameter specifies the maximum amount of
    219     buffer memory which may be used for TCP sockets to transmit
    220     with.  The default size is sixteen kilobytes.
     216    This configuration parameter specifies the maximum amount of buffer memory
     217    which may be used for TCP sockets to transmit with.  The default size is
     218    sixteen kilobytes.
    221219
    222220``unsigned long tcp_rx_buf_size``
    223 
    224     This configuration parameter specifies the maximum amount of
    225     buffer memory which may be used for TCP sockets to receive
    226     into.  The default size is sixteen kilobytes.
    227 
    228 ``const cpu_set_t \*network_task_cpuset``
    229 
    230     This configuration parameter specifies the CPU affinity of the
    231     network task. If set to ``0`` the network task can be scheduled on
    232     any CPU. Only available in SMP configurations.
     221    This configuration parameter specifies the maximum amount of buffer memory
     222    which may be used for TCP sockets to receive into.  The default size is
     223    sixteen kilobytes.
     224
     225``const cpu_set_t *network_task_cpuset``
     226    This configuration parameter specifies the CPU affinity of the network
     227    task. If set to ``0`` the network task can be scheduled on any CPU. Only
     228    available in SMP configurations.
    233229
    234230``size_t network_task_cpuset_size``
    235 
    236     This configuration parameter specifies the size of the``network_task_cpuset`` used. Only available in SMP configurations.
    237 
    238 In addition, the following fields in the ``rtems_bsdnet_ifconfig``
    239 are of interest.
     231    This configuration parameter specifies the size of the
     232    ``network_task_cpuset`` used. Only available in SMP configurations.
     233
     234In addition, the following fields in the ``rtems_bsdnet_ifconfig`` are of
     235interest.
    240236
    241237*int port*
    242     The I/O port number (ex: 0x240) on which the external Ethernet
    243     can be accessed.
     238    The I/O port number (ex: 0x240) on which the external Ethernet can be
     239    accessed.
    244240
    245241*int irno*
     
    252248----------------------------
    253249
    254 Network devices are specified and configured by declaring and initializing a``struct rtems_bsdnet_ifconfig`` structure for each network device.
     250Network devices are specified and configured by declaring and initializing a
     251``struct rtems_bsdnet_ifconfig`` structure for each network device.
    255252
    256253The structure entries are described in the following table.  An application
    257254which uses a single network interface, gets network configuration information
    258 from a BOOTP/DHCP server, and uses the default values for all driver
    259 parameters needs to initialize only the first two entries in the
    260 structure.
    261 
    262 ``char \*name``
    263     The full name of the network device.  This name consists of the
    264     driver name and the unit number (e.g. ``"scc1"``).
    265     The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_NAME as
    266     the name of the primary (or only) network driver.
    267 
    268 ``int (\*attach)(struct rtems_bsdnet_ifconfig \*conf)``
    269     The address of the driver ``attach`` function.   The network
    270     initialization function calls this function to configure the driver and
    271     attach it to the network stack.
    272     The ``bsp.h`` include file usually defines RTEMS_BSP_NETWORK_DRIVER_ATTACH as
    273     the name of the  attach function of the primary (or only) network driver.
    274 
    275 ``struct rtems_bsdnet_ifconfig \*next``
    276     A pointer to the network device configuration structure for the next network
    277     interface, or ``NULL`` if this is the configuration structure of the
    278     last network interface.
    279 
    280 ``char \*ip_address``
    281     The Internet address of the device,
    282     specified in 'dotted decimal' (``129.128.4.2``) form, or ``NULL``
    283     if the device configuration information is being obtained from a
    284     BOOTP/DHCP server.
    285 
    286 ``char \*ip_netmask``
    287     The Internet inetwork mask of the device,
    288     specified in 'dotted decimal' (``255.255.255.0``) form, or ``NULL``
    289     if the device configuration information is being obtained from a
    290     BOOTP/DHCP server.
    291 
    292 ``void \*hardware_address``
    293     The hardware address of the device, or ``NULL`` if the driver is
    294     to obtain the hardware address in some other way (usually  by reading
    295     it from the device or from the bootstrap ROM).
     255from a BOOTP/DHCP server, and uses the default values for all driver parameters
     256needs to initialize only the first two entries in the structure.
     257
     258``char *name``
     259    The full name of the network device.  This name consists of the driver name
     260    and the unit number (e.g. ``"scc1"``).  The ``bsp.h`` include file usually
     261    defines ``RTEMS_BSP_NETWORK_DRIVER_NAME`` as the name of the primary (or
     262    only) network driver.
     263
     264``int (*attach)(struct rtems_bsdnet_ifconfig *conf)``
     265
     266    The address of the driver ``attach`` function.  The network initialization
     267    function calls this function to configure the driver and attach it to the
     268    network stack.  The ``bsp.h`` include file usually defines
     269    ``RTEMS_BSP_NETWORK_DRIVER_ATTACH`` as the name of the attach function of
     270    the primary (or only) network driver.
     271
     272``struct rtems_bsdnet_ifconfig *next``
     273    A pointer to the network device configuration structure for the next
     274    network interface, or ``NULL`` if this is the configuration structure of
     275    the last network interface.
     276
     277``char *ip_address``
     278    The Internet address of the device, specified in 'dotted decimal'
     279    (``129.128.4.2``) form, or ``NULL`` if the device configuration information
     280    is being obtained from a BOOTP/DHCP server.
     281
     282``char *ip_netmask``
     283    The Internet inetwork mask of the device, specified in 'dotted decimal'
     284    (``255.255.255.0``) form, or ``NULL`` if the device configuration
     285    information is being obtained from a BOOTP/DHCP server.
     286
     287``void *hardware_address``
     288    The hardware address of the device, or ``NULL`` if the driver is to obtain
     289    the hardware address in some other way (usually by reading it from the
     290    device or from the bootstrap ROM).
    296291
    297292``int ignore_broadcast``
     
    300295
    301296``int mtu``
    302     The maximum transmission unit of the device, or zero if the driver
    303     is to choose a default value (typically 1500 for Ethernet devices).
     297    The maximum transmission unit of the device, or zero if the driver is to
     298    choose a default value (typically 1500 for Ethernet devices).
    304299
    305300``int rbuf_count``
    306     The number of receive buffers to use, or zero if the driver is to
    307     choose a default value
     301    The number of receive buffers to use, or zero if the driver is to choose a
     302    default value
    308303
    309304``int xbuf_count``
    310     The number of transmit buffers to use, or zero if the driver is to
    311     choose a default value
    312     Keep in mind that some network devices may use 4 or more
     305    The number of transmit buffers to use, or zero if the driver is to choose a
     306    default value Keep in mind that some network devices may use 4 or more
    313307    transmit descriptors for a single transmit buffer.
    314308
    315309A complete network configuration specification can be as simple as the one
    316 shown in the following example.
    317 This configuration uses a single network interface, gets
    318 network configuration information
    319 from a BOOTP/DHCP server, and uses the default values for all driver
    320 parameters.
    321 .. code:: c
     310shown in the following example.  This configuration uses a single network
     311interface, gets network configuration information from a BOOTP/DHCP server, and
     312uses the default values for all driver parameters.
     313
     314.. code-block:: c
    322315
    323316    static struct rtems_bsdnet_ifconfig netdriver_config = {
    324     RTEMS_BSP_NETWORK_DRIVER_NAME,
    325     RTEMS_BSP_NETWORK_DRIVER_ATTACH
     317        RTEMS_BSP_NETWORK_DRIVER_NAME,
     318        RTEMS_BSP_NETWORK_DRIVER_ATTACH
    326319    };
    327320    struct rtems_bsdnet_config rtems_bsdnet_config = {
    328     &netdriver_config,
    329     rtems_bsdnet_do_bootp,
     321        &netdriver_config,
     322        rtems_bsdnet_do_bootp,
    330323    };
    331324
     
    333326----------------------
    334327
    335 The networking tasks must be started before any network I/O operations
    336 can be performed. This is done by calling:
    337 
    338 .. code:: c
     328The networking tasks must be started before any network I/O operations can be
     329performed. This is done by calling:
     330
     331.. code-block:: c
    339332
    340333    rtems_bsdnet_initialize_network ();
    341334
    342 This function is declared in ``rtems/rtems_bsdnet.h``.
    343 t returns 0 on success and -1 on failure with an error code
    344 in ``errno``.  It is not possible to undo the effects of
    345 a partial initialization, though, so the function can be
    346 called only once irregardless of the return code.  Consequently,
    347 if the condition for the failure can be corrected, the
    348 system must be reset to permit another network initialization
    349 attempt.
     335This function is declared in ``rtems/rtems_bsdnet.h``.  t returns 0 on success
     336and -1 on failure with an error code in ``errno``.  It is not possible to undo
     337the effects of a partial initialization, though, so the function can be called
     338only once irregardless of the return code.  Consequently, if the condition for
     339the failure can be corrected, the system must be reset to permit another
     340network initialization attempt.
    350341
    351342Application Programming Interface
     
    353344
    354345The RTEMS network package provides almost a complete set of BSD network
    355 services.  The network functions work like their BSD counterparts
    356 with the following exceptions:
     346services.  The network functions work like their BSD counterparts with the
     347following exceptions:
    357348
    358349- A given socket can be read or written by only one task at a time.
    359350
    360 - The ``select`` function only works for file descriptors associated
    361   with sockets.
     351- The ``select`` function only works for file descriptors associated with
     352  sockets.
    362353
    363354- You must call ``openlog`` before calling any of the ``syslog`` functions.
    364355
    365 - *Some of the network functions are not thread-safe.*
    366   For example the following functions return a pointer to a static
    367   buffer which remains valid only until the next call:
     356- *Some of the network functions are not thread-safe.* For example the
     357  following functions return a pointer to a static buffer which remains valid
     358  only until the next call:
    368359
    369360  ``gethostbyaddr``
    370 
    371361  ``gethostbyname``
    372 
    373362  ``inet_ntoa``
    374 
    375363      (``inet_ntop`` is thread-safe, though).
    376364
    377365- The RTEMS network package gathers statistics.
    378366
    379 - Addition of a mechanism to "tap onto" an interface
    380   and monitor every packet received and transmitted.
     367- Addition of a mechanism to "tap onto" an interface and monitor every packet
     368  received and transmitted.
    381369
    382370- Addition of ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP`` socket options.
     
    388376------------------
    389377
    390 There are a number of functions to print statistics gathered by
    391 the network stack.
    392 These function are declared in ``rtems/rtems_bsdnet.h``.
     378There are a number of functions to print statistics gathered by the network
     379stack.  These function are declared in ``rtems/rtems_bsdnet.h``.
    393380
    394381``rtems_bsdnet_show_if_stats``
     
    416403-------------------------
    417404
    418 RTEMS add two new ioctls to the BSD networking code:
    419 SIOCSIFTAP and SIOCGIFTAP.  These may be used to set and get a*tap function*.  The tap function will be called for every
    420 Ethernet packet received by the interface.
    421 
    422 These are called like other interface ioctls, such as SIOCSIFADDR.
    423 When setting the tap function with SIOCSIFTAP, set the ifr_tap field
    424 of the ifreq struct to the tap function.  When retrieving the tap
    425 function with SIOCGIFTAP, the current tap function will be returned in
    426 the ifr_tap field.  To stop tapping packets, call SIOCSIFTAP with a
    427 ifr_tap field of 0.
     405RTEMS add two new ioctls to the BSD networking code, ``SIOCSIFTAP`` and
     406``SIOCGIFTAP``.  These may be used to set and get a *tap function*.  The tap
     407function will be called for every Ethernet packet received by the interface.
     408
     409These are called like other interface ioctls, such as ``SIOCSIFADDR``.  When
     410setting the tap function with ``SIOCSIFTAP``, set the ifr_tap field of the
     411ifreq struct to the tap function.  When retrieving the tap function with
     412``SIOCGIFTAP``, the current tap function will be returned in the ifr_tap field.
     413To stop tapping packets, call ``SIOCSIFTAP`` with a ``ifr_tap`` field of ``0``.
    428414
    429415The tap function is called like this:
    430 .. code:: c
    431 
    432     int tap (struct ifnet \*, struct ether_header \*, struct mbuf \*)
    433 
    434 The tap function should return 1 if the packet was fully handled, in
    435 which case the caller will simply discard the mbuf.  The tap function
    436 should return 0 if the packet should be passed up to the higher
    437 networking layers.
    438 
    439 The tap function is called with the network semaphore locked.  It must
    440 not make any calls on the application levels of the networking level
    441 itself.  It is safe to call other non-networking RTEMS functions.
     416
     417.. code-block:: c
     418
     419    int tap (struct ifnet *, struct ether_header *, struct mbuf *)
     420
     421The tap function should return ``1`` if the packet was fully handled, in which
     422case the caller will simply discard the mbuf.  The tap function should return
     423``0`` if the packet should be passed up to the higher networking layers.
     424
     425The tap function is called with the network semaphore locked.  It must not make
     426any calls on the application levels of the networking level itself.  It is safe
     427to call other non-networking RTEMS functions.
    442428
    443429Socket Options
    444430--------------
    445431
    446 RTEMS adds two new ``SOL_SOCKET`` level options for ``setsockopt`` and``getsockopt``: ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP``.  For both, the
    447 option value should point to a sockwakeup structure.  The sockwakeup
    448 structure has the following fields:
    449 .. code:: c
    450 
    451     void    (\*sw_pfn) (struct socket \*, caddr_t);
     432RTEMS adds two new ``SOL_SOCKET`` level options for ``setsockopt`` and
     433``getsockopt``: ``SO_SNDWAKEUP`` and ``SO_RCVWAKEUP``.  For both, the option
     434value should point to a sockwakeup structure.  The sockwakeup structure has the
     435following fields:
     436
     437.. code-block:: c
     438
     439    void    (*sw_pfn) (struct socket *, caddr_t);
    452440    caddr_t sw_arg;
    453441
    454442These options are used to set a callback function to be called when, for
    455 example, there is
    456 data available from the socket (``SO_RCVWAKEUP``) and when there is space
    457 available to accept data written to the socket (``SO_SNDWAKEUP``).
    458 
    459 If ``setsockopt`` is called with the ``SO_RCVWAKEUP`` option, and the``sw_pfn`` field is not zero, then when there is data
    460 available to be read from
    461 the socket, the function pointed to by the ``sw_pfn`` field will be
    462 called.  A pointer to the socket structure will be passed as the first
    463 argument to the function.  The ``sw_arg`` field set by the``SO_RCVWAKEUP`` call will be passed as the second argument to the function.
    464 
    465 If ``setsockopt`` is called with the ``SO_SNDWAKEUP``
    466 function, and the ``sw_pfn`` field is not zero, then when
    467 there is space available to accept data written to the socket,
    468 the function pointed to by the ``sw_pfn`` field
    469 will be called.  The arguments passed to the function will be as with``SO_SNDWAKEUP``.
    470 
    471 When the function is called, the network semaphore will be locked and
    472 the callback function runs in the context of the networking task.
    473 The function must be careful not to call any networking functions.  It
    474 is OK to call an RTEMS function; for example, it is OK to send an
    475 RTEMS event.
     443example, there is data available from the socket (``SO_RCVWAKEUP``) and when
     444there is space available to accept data written to the socket
     445(``SO_SNDWAKEUP``).
     446
     447If ``setsockopt`` is called with the ``SO_RCVWAKEUP`` option, and the
     448``sw_pfn`` field is not zero, then when there is data available to be read from
     449the socket, the function pointed to by the ``sw_pfn`` field will be called.  A
     450pointer to the socket structure will be passed as the first argument to the
     451function.  The ``sw_arg`` field set by the ``SO_RCVWAKEUP`` call will be passed
     452as the second argument to the function.
     453
     454If ``setsockopt`` is called with the ``SO_SNDWAKEUP`` function, and the
     455``sw_pfn`` field is not zero, then when there is space available to accept data
     456written to the socket, the function pointed to by the ``sw_pfn`` field will be
     457called.  The arguments passed to the function will be as with ``SO_SNDWAKEUP``.
     458
     459When the function is called, the network semaphore will be locked and the
     460callback function runs in the context of the networking task.  The function
     461must be careful not to call any networking functions.  It is OK to call an
     462RTEMS function; for example, it is OK to send an RTEMS event.
    476463
    477464The purpose of these callback functions is to permit a more efficient
    478 alternative to the select call when dealing with a large number of
    479 sockets.
    480 
    481 The callbacks are called by the same criteria that the select
    482 function uses for indicating "ready" sockets. In Stevens *Unix
    483 Network Programming* on page 153-154 in the section "Under what Conditions
    484 Is a Descriptor Ready?" you will find the definitive list of conditions
    485 for readable and writable that also determine when the functions are
    486 called.
    487 
    488 When the number of received bytes equals or exceeds the socket receive
    489 buffer "low water mark" (default 1 byte) you get a readable callback. If
    490 there are 100 bytes in the receive buffer and you only read 1, you will
    491 not immediately get another callback. However, you will get another
    492 callback after you read the remaining 99 bytes and at least 1 more byte
    493 arrives. Using a non-blocking socket you should probably read until it
    494 produces error  EWOULDBLOCK and then allow the readable callback to tell
    495 you when more data has arrived.  (Condition 1.a.)
    496 
    497 For sending, when the socket is connected and the free space becomes at
    498 or above the "low water mark" for the send buffer (default 4096 bytes)
    499 you will receive a writable callback. You don't get continuous callbacks
    500 if you don't write anything. Using a non-blocking write socket, you can
    501 then call write until it returns a value less than the amount of data
    502 requested to be sent or it produces error EWOULDBLOCK (indicating buffer
    503 full and no longer writable). When this happens you can
    504 try the write again, but it is often better to go do other things and
    505 let the writable callback tell you when space is available to send
    506 again. You only get a writable callback when the free space transitions
    507 to above the "low water mark" and not every time you
    508 write to a non-full send buffer. (Condition 2.a.)
    509 
    510 The remaining conditions enumerated by Stevens handle the fact that
    511 sockets become readable and/or writable when connects, disconnects and
    512 errors occur, not just when data is received or sent. For example, when
    513 a server "listening" socket becomes readable it indicates that a client
    514 has connected and accept can be called without blocking, not that
    515 network data was received (Condition 1.c).
     465alternative to the select call when dealing with a large number of sockets.
     466
     467The callbacks are called by the same criteria that the select function uses for
     468indicating "ready" sockets. In Stevens *Unix Network Programming* on page
     469153-154 in the section "Under what Conditions Is a Descriptor Ready?" you will
     470find the definitive list of conditions for readable and writable that also
     471determine when the functions are called.
     472
     473When the number of received bytes equals or exceeds the socket receive buffer
     474"low water mark" (default 1 byte) you get a readable callback. If there are 100
     475bytes in the receive buffer and you only read 1, you will not immediately get
     476another callback. However, you will get another callback after you read the
     477remaining 99 bytes and at least 1 more byte arrives. Using a non-blocking
     478socket you should probably read until it produces error ``EWOULDBLOCK`` and
     479then allow the readable callback to tell you when more data has arrived.
     480(Condition 1.a.)
     481
     482For sending, when the socket is connected and the free space becomes at or
     483above the "low water mark" for the send buffer (default 4096 bytes) you will
     484receive a writable callback. You don't get continuous callbacks if you don't
     485write anything. Using a non-blocking write socket, you can then call write
     486until it returns a value less than the amount of data requested to be sent or
     487it produces error ``EWOULDBLOCK`` (indicating buffer full and no longer
     488writable). When this happens you can try the write again, but it is often
     489better to go do other things and let the writable callback tell you when space
     490is available to send again. You only get a writable callback when the free
     491space transitions to above the "low water mark" and not every time you write to
     492a non-full send buffer. (Condition 2.a.)
     493
     494The remaining conditions enumerated by Stevens handle the fact that sockets
     495become readable and/or writable when connects, disconnects and errors occur,
     496not just when data is received or sent. For example, when a server "listening"
     497socket becomes readable it indicates that a client has connected and accept can
     498be called without blocking, not that network data was received (Condition 1.c).
    516499
    517500Adding an IP Alias
     
    519502
    520503The following code snippet adds an IP alias:
    521 .. code:: c
    522 
    523     void addAlias(const char \*pName, const char \*pAddr, const char \*pMask)
     504
     505.. code-block:: c
     506
     507    void addAlias(const char *pName, const char *pAddr, const char *pMask)
    524508    {
    525     struct ifaliasreq      aliasreq;
    526     struct sockaddr_in    \*in;
    527     /* initialize alias request \*/
    528     memset(&aliasreq, 0, sizeof(aliasreq));
    529     sprintf(aliasreq.ifra_name, pName);
    530     /* initialize alias address \*/
    531     in = (struct sockaddr_in \*)&aliasreq.ifra_addr;
    532     in->sin_family = AF_INET;
    533     in->sin_len    = sizeof(aliasreq.ifra_addr);
    534     in->sin_addr.s_addr = inet_addr(pAddr);
    535     /* initialize alias mask \*/
    536     in = (struct sockaddr_in \*)&aliasreq.ifra_mask;
    537     in->sin_family = AF_INET;
    538     in->sin_len    = sizeof(aliasreq.ifra_mask);
    539     in->sin_addr.s_addr = inet_addr(pMask);
    540     /* call to setup the alias \*/
    541     rtems_bsdnet_ifconfig(pName, SIOCAIFADDR, &aliasreq);
     509        struct ifaliasreq   aliasreq;
     510        struct sockaddr_in *in;
     511
     512        /* initialize alias request */
     513        memset(&aliasreq, 0, sizeof(aliasreq));
     514        sprintf(aliasreq.ifra_name, pName);
     515
     516        /* initialize alias address */
     517        in = (struct sockaddr_in *)&aliasreq.ifra_addr;
     518        in->sin_family = AF_INET;
     519        in->sin_len    = sizeof(aliasreq.ifra_addr);
     520        in->sin_addr.s_addr = inet_addr(pAddr);
     521
     522        /* initialize alias mask */
     523        in = (struct sockaddr_in *)&aliasreq.ifra_mask;
     524        in->sin_family = AF_INET;
     525        in->sin_len    = sizeof(aliasreq.ifra_mask);
     526        in->sin_addr.s_addr = inet_addr(pMask);
     527
     528        /* call to setup the alias */
     529        rtems_bsdnet_ifconfig(pName, SIOCAIFADDR, &aliasreq);
    542530    }
    543531
    544 Thanks to `Mike Seirs <mailto:mikes@poliac.com>`_ for this example
    545 code.
     532Thanks to Mike Seirs <mailto:mikes@poliac.com> for this example code.
    546533
    547534Adding a Default Route
    548535----------------------
    549536
    550 The function provided in this section is functionally equivalent to
    551 the command ``route add default gw yyy.yyy.yyy.yyy``:
    552 .. code:: c
    553 
    554     void mon_ifconfig(int argc, char \*argv[],  unsigned32 command_arg,
    555     bool verbose)
     537The function provided in this section is functionally equivalent to the command
     538``route add default gw yyy.yyy.yyy.yyy``:
     539
     540.. code-block:: c
     541
     542    void mon_ifconfig(int argc, char *argv[],  unsigned32 command_arg, bool verbose)
    556543    {
    557     struct sockaddr_in  ipaddr;
    558     struct sockaddr_in  dstaddr;
    559     struct sockaddr_in  netmask;
    560     struct sockaddr_in  broadcast;
    561     char               \*iface;
    562     int                 f_ip        = 0;
    563     int                 f_ptp       = 0;
    564     int                 f_netmask   = 0;
    565     int                 f_up        = 0;
    566     int                 f_down      = 0;
    567     int                 f_bcast     = 0;
    568     int                 cur_idx;
    569     int                 rc;
    570     int                 flags;
    571     bzero((void*) &ipaddr, sizeof(ipaddr));
    572     bzero((void*) &dstaddr, sizeof(dstaddr));
    573     bzero((void*) &netmask, sizeof(netmask));
    574     bzero((void*) &broadcast, sizeof(broadcast));
    575     ipaddr.sin_len = sizeof(ipaddr);
    576     ipaddr.sin_family = AF_INET;
    577     dstaddr.sin_len = sizeof(dstaddr);
    578     dstaddr.sin_family = AF_INET;
    579     netmask.sin_len = sizeof(netmask);
    580     netmask.sin_family = AF_INET;
    581     broadcast.sin_len = sizeof(broadcast);
    582     broadcast.sin_family = AF_INET;
    583     cur_idx = 0;
    584     if (argc <= 1) {
    585     /* display all interfaces \*/
    586     iface = NULL;
    587     cur_idx += 1;
    588     } else {
    589     iface = argv[1];
    590     if (isdigit(\*argv[2])) {
    591     if (inet_pton(AF_INET, argv[2], &ipaddr.sin_addr) < 0) {
    592     printf("bad ip address: %s\\n", argv[2]);
    593     return;
     544        struct sockaddr_in  ipaddr;
     545        struct sockaddr_in  dstaddr;
     546        struct sockaddr_in  netmask;
     547        struct sockaddr_in  broadcast;
     548        char               *iface;
     549        int                 f_ip        = 0;
     550        int                 f_ptp       = 0;
     551        int                 f_netmask   = 0;
     552        int                 f_up        = 0;
     553        int                 f_down      = 0;
     554        int                 f_bcast     = 0;
     555        int                 cur_idx;
     556        int                 rc;
     557        int                 flags;
     558
     559        bzero((void*) &ipaddr, sizeof(ipaddr));
     560        bzero((void*) &dstaddr, sizeof(dstaddr));
     561        bzero((void*) &netmask, sizeof(netmask));
     562        bzero((void*) &broadcast, sizeof(broadcast));
     563        ipaddr.sin_len = sizeof(ipaddr);
     564        ipaddr.sin_family = AF_INET;
     565        dstaddr.sin_len = sizeof(dstaddr);
     566        dstaddr.sin_family = AF_INET;
     567        netmask.sin_len = sizeof(netmask);
     568        netmask.sin_family = AF_INET;
     569        broadcast.sin_len = sizeof(broadcast);
     570        broadcast.sin_family = AF_INET;
     571        cur_idx = 0;
     572
     573        if (argc <= 1) {
     574            /* display all interfaces */
     575            iface = NULL;
     576            cur_idx += 1;
     577        } else {
     578            iface = argv[1];
     579            if (isdigit(*argv[2])) {
     580                if (inet_pton(AF_INET, argv[2], &ipaddr.sin_addr) < 0) {
     581                    printf("bad ip address: %s\n", argv[2]);
     582                    return;
     583                }
     584                f_ip = 1;
     585                cur_idx += 3;
     586            } else {
     587                cur_idx += 2;
     588            }
     589        }
     590
     591        if ((f_down !=0) && (f_ip != 0)) {
     592            f_up = 1;
     593        }
     594
     595        while(argc > cur_idx) {
     596            if (strcmp(argv[cur_idx], "up") == 0) {
     597                f_up = 1;
     598                if (f_down != 0) {
     599                    printf("Can't make interface up and down\n");
     600                }
     601            } else if(strcmp(argv[cur_idx], "down") == 0) {
     602                f_down = 1;
     603                if (f_up != 0) {
     604                    printf("Can't make interface up and down\n");
     605                }
     606            } else if(strcmp(argv[cur_idx], "netmask") == 0) {
     607                if ((cur_idx + 1) >= argc) {
     608                    printf("No netmask address\n");
     609                    return;
     610                }
     611                if (inet_pton(AF_INET, argv[cur_idx+1], &netmask.sin_addr) < 0) {
     612                    printf("bad netmask: %s\n", argv[cur_idx]);
     613                    return;
     614                }
     615                f_netmask = 1;
     616                cur_idx += 1;
     617            } else if(strcmp(argv[cur_idx], "broadcast") == 0) {
     618                if ((cur_idx + 1) >= argc) {
     619                    printf("No broadcast address\n");
     620                    return;
     621                }
     622                if (inet_pton(AF_INET, argv[cur_idx+1], &broadcast.sin_addr) < 0) {
     623                    printf("bad broadcast: %s\n", argv[cur_idx]);
     624                    return;
     625                }
     626               f_bcast = 1;
     627               cur_idx += 1;
     628            } else if(strcmp(argv[cur_idx], "pointopoint") == 0) {
     629                if ((cur_idx + 1) >= argc) {
     630                    printf("No pointopoint address\n");
     631                    return;
     632                }
     633                if (inet_pton(AF_INET, argv[cur_idx+1], &dstaddr.sin_addr) < 0) {
     634                    printf("bad pointopoint: %s\n", argv[cur_idx]);
     635                    return;
     636                }
     637                f_ptp = 1;
     638                cur_idx += 1;
     639            } else {
     640                printf("Bad parameter: %s\n", argv[cur_idx]);
     641                return;
     642            }
     643            cur_idx += 1;
     644        }
     645
     646        printf("ifconfig ");
     647
     648        if (iface != NULL) {
     649            printf("%s ", iface);
     650            if (f_ip != 0) {
     651                char str[256];
     652                inet_ntop(AF_INET, &ipaddr.sin_addr, str, 256);
     653                printf("%s ", str);
     654            }
     655            if (f_netmask != 0) {
     656                char str[256];
     657                inet_ntop(AF_INET, &netmask.sin_addr, str, 256);
     658                printf("netmask %s ", str);
     659            }
     660            if (f_bcast != 0) {
     661                char str[256];
     662                inet_ntop(AF_INET, &broadcast.sin_addr, str, 256);
     663                printf("broadcast %s ", str);
     664            }
     665            if (f_ptp != 0) {
     666                char str[256];
     667                inet_ntop(AF_INET, &dstaddr.sin_addr, str, 256);
     668                printf("pointopoint %s ", str);
     669            }
     670            if (f_up != 0) {
     671                printf("up\n");
     672            } else if (f_down != 0) {
     673                printf("down\n");
     674            } else {
     675                printf("\n");
     676            }
     677        }
     678
     679        if ((iface == NULL) || ((f_ip == 0) && (f_down == 0) && (f_up == 0))) {
     680            rtems_bsdnet_show_if_stats();
     681            return;
     682        }
     683
     684        flags = 0;
     685        if (f_netmask) {
     686            rc = rtems_bsdnet_ifconfig(iface, SIOCSIFNETMASK, &netmask);
     687            if (rc < 0) {
     688                printf("Could not set netmask: %s\n", strerror(errno));
     689                return;
     690            }
     691        }
     692        if (f_bcast) {
     693            rc = rtems_bsdnet_ifconfig(iface, SIOCSIFBRDADDR, &broadcast);
     694            if (rc < 0) {
     695                printf("Could not set broadcast: %s\n", strerror(errno));
     696                return;
     697            }
     698        }
     699        if (f_ptp) {
     700            rc = rtems_bsdnet_ifconfig(iface, SIOCSIFDSTADDR, &dstaddr);
     701            if (rc < 0) {
     702                printf("Could not set destination address: %s\n", strerror(errno));
     703                return;
     704            }
     705            flags |= IFF_POINTOPOINT;
     706        }
     707
     708        /* This must come _after_ setting the netmask, broadcast addresses */
     709        if (f_ip) {
     710            rc = rtems_bsdnet_ifconfig(iface, SIOCSIFADDR, &ipaddr);
     711            if (rc < 0) {
     712                printf("Could not set IP address: %s\n", strerror(errno));
     713                return;
     714            }
     715        }
     716        if (f_up != 0) {
     717            flags |= IFF_UP;
     718        }
     719        if (f_down != 0) {
     720            printf("Warning: taking interfaces down is not supported\n");
     721        }
     722
     723        rc = rtems_bsdnet_ifconfig(iface, SIOCSIFFLAGS, &flags);
     724        if (rc < 0) {
     725            printf("Could not set interface flags: %s\n", strerror(errno));
     726            return;
     727        }
    594728    }
    595     f_ip = 1;
    596     cur_idx += 3;
    597     } else {
    598     cur_idx += 2;
     729
     730    void mon_route(int argc, char *argv[],  unsigned32 command_arg, bool verbose)
     731    {
     732        int                cmd;
     733        struct sockaddr_in dst;
     734        struct sockaddr_in gw;
     735        struct sockaddr_in netmask;
     736        int                f_host;
     737        int                f_gw       = 0;
     738        int                cur_idx;
     739        int                flags;
     740        int                rc;
     741
     742        memset(&dst, 0, sizeof(dst));
     743        memset(&gw, 0, sizeof(gw));
     744        memset(&netmask, 0, sizeof(netmask));
     745        dst.sin_len = sizeof(dst);
     746        dst.sin_family = AF_INET;
     747        dst.sin_addr.s_addr = inet_addr("0.0.0.0");
     748        gw.sin_len = sizeof(gw);
     749        gw.sin_family = AF_INET;
     750        gw.sin_addr.s_addr = inet_addr("0.0.0.0");
     751        netmask.sin_len = sizeof(netmask);
     752        netmask.sin_family = AF_INET;
     753        netmask.sin_addr.s_addr = inet_addr("255.255.255.0");
     754
     755        if (argc < 2) {
     756            rtems_bsdnet_show_inet_routes();
     757            return;
     758        }
     759
     760        if (strcmp(argv[1], "add") == 0) {
     761            cmd = RTM_ADD;
     762        } else if (strcmp(argv[1], "del") == 0) {
     763            cmd = RTM_DELETE;
     764        } else {
     765            printf("invalid command: %s\n", argv[1]);
     766            printf("\tit should be 'add' or 'del'\n");
     767            return;
     768        }
     769
     770        if (argc < 3) {
     771            printf("not enough arguments\n");
     772            return;
     773        }
     774
     775        if (strcmp(argv[2], "-host") == 0) {
     776            f_host = 1;
     777        } else if (strcmp(argv[2], "-net") == 0) {
     778            f_host = 0;
     779        } else {
     780            printf("Invalid type: %s\n", argv[1]);
     781            printf("\tit should be '-host' or '-net'\n");
     782            return;
     783        }
     784
     785        if (argc < 4) {
     786            printf("not enough arguments\n");
     787            return;
     788        }
     789
     790        inet_pton(AF_INET, argv[3], &dst.sin_addr);
     791
     792        cur_idx = 4;
     793        while(cur_idx < argc) {
     794            if (strcmp(argv[cur_idx], "gw") == 0) {
     795                if ((cur_idx +1) >= argc) {
     796                    printf("no gateway address\n");
     797                    return;
     798                }
     799                f_gw = 1;
     800                inet_pton(AF_INET, argv[cur_idx + 1], &gw.sin_addr);
     801                cur_idx += 1;
     802            } else if(strcmp(argv[cur_idx], "netmask") == 0) {
     803                if ((cur_idx +1) >= argc) {
     804                    printf("no netmask address\n");
     805                    return;
     806                }
     807                f_gw = 1;
     808                inet_pton(AF_INET, argv[cur_idx + 1], &netmask.sin_addr);
     809                cur_idx += 1;
     810            } else {
     811                printf("Unknown argument\n");
     812                return;
     813            }
     814            cur_idx += 1;
     815        }
     816
     817        flags = RTF_STATIC;
     818        if (f_gw != 0) {
     819            flags |= RTF_GATEWAY;
     820        }
     821        if (f_host != 0) {
     822            flags |= RTF_HOST;
     823        }
     824
     825        rc = rtems_bsdnet_rtrequest(cmd, &dst, &gw, &netmask, flags, NULL);
     826        if (rc < 0) {
     827            printf("Error adding route\n");
     828        }
    599829    }
    600     }
    601     if ((f_down !=0) && (f_ip != 0)) {
    602     f_up = 1;
    603     }
    604     while(argc > cur_idx) {
    605     if (strcmp(argv[cur_idx], "up") == 0) {
    606     f_up = 1;
    607     if (f_down != 0) {
    608     printf("Can't make interface up and down\\n");
    609     }
    610     } else if(strcmp(argv[cur_idx], "down") == 0) {
    611     f_down = 1;
    612     if (f_up != 0) {
    613     printf("Can't make interface up and down\\n");
    614     }
    615     } else if(strcmp(argv[cur_idx], "netmask") == 0) {
    616     if ((cur_idx + 1) >= argc) {
    617     printf("No netmask address\\n");
    618     return;
    619     }
    620     if (inet_pton(AF_INET, argv[cur_idx+1], &netmask.sin_addr) < 0) {
    621     printf("bad netmask: %s\\n", argv[cur_idx]);
    622     return;
    623     }
    624     f_netmask = 1;
    625     cur_idx += 1;
    626     } else if(strcmp(argv[cur_idx], "broadcast") == 0) {
    627     if ((cur_idx + 1) >= argc) {
    628     printf("No broadcast address\\n");
    629     return;
    630     }
    631     if (inet_pton(AF_INET, argv[cur_idx+1], &broadcast.sin_addr) < 0) {
    632     printf("bad broadcast: %s\\n", argv[cur_idx]);
    633     return;
    634     }
    635     f_bcast = 1;
    636     cur_idx += 1;
    637     } else if(strcmp(argv[cur_idx], "pointopoint") == 0) {
    638     if ((cur_idx + 1) >= argc) {
    639     printf("No pointopoint address\\n");
    640     return;
    641     }
    642     if (inet_pton(AF_INET, argv[cur_idx+1], &dstaddr.sin_addr) < 0) {
    643     printf("bad pointopoint: %s\\n", argv[cur_idx]);
    644     return;
    645     }
    646     f_ptp = 1;
    647     cur_idx += 1;
    648     } else {
    649     printf("Bad parameter: %s\\n", argv[cur_idx]);
    650     return;
    651     }
    652     cur_idx += 1;
    653     }
    654     printf("ifconfig ");
    655     if (iface != NULL) {
    656     printf("%s ", iface);
    657     if (f_ip != 0) {
    658     char str[256];
    659     inet_ntop(AF_INET, &ipaddr.sin_addr, str, 256);
    660     printf("%s ", str);
    661     }
    662     if (f_netmask != 0) {
    663     char str[256];
    664     inet_ntop(AF_INET, &netmask.sin_addr, str, 256);
    665     printf("netmask %s ", str);
    666     }
    667     if (f_bcast != 0) {
    668     char str[256];
    669     inet_ntop(AF_INET, &broadcast.sin_addr, str, 256);
    670     printf("broadcast %s ", str);
    671     }
    672     if (f_ptp != 0) {
    673     char str[256];
    674     inet_ntop(AF_INET, &dstaddr.sin_addr, str, 256);
    675     printf("pointopoint %s ", str);
    676     }
    677     if (f_up != 0) {
    678     printf("up\\n");
    679     } else if (f_down != 0) {
    680     printf("down\\n");
    681     } else {
    682     printf("\\n");
    683     }
    684     }
    685     if ((iface == NULL) \|| ((f_ip == 0) && (f_down == 0) && (f_up == 0))) {
    686     rtems_bsdnet_show_if_stats();
    687     return;
    688     }
    689     flags = 0;
    690     if (f_netmask) {
    691     rc = rtems_bsdnet_ifconfig(iface, SIOCSIFNETMASK, &netmask);
    692     if (rc < 0) {
    693     printf("Could not set netmask: %s\\n", strerror(errno));
    694     return;
    695     }
    696     }
    697     if (f_bcast) {
    698     rc = rtems_bsdnet_ifconfig(iface, SIOCSIFBRDADDR, &broadcast);
    699     if (rc < 0) {
    700     printf("Could not set broadcast: %s\\n", strerror(errno));
    701     return;
    702     }
    703     }
    704     if (f_ptp) {
    705     rc = rtems_bsdnet_ifconfig(iface, SIOCSIFDSTADDR, &dstaddr);
    706     if (rc < 0) {
    707     printf("Could not set destination address: %s\\n", strerror(errno));
    708     return;
    709     }
    710     flags \|= IFF_POINTOPOINT;
    711     }
    712     /* This must come _after_ setting the netmask, broadcast addresses \*/
    713     if (f_ip) {
    714     rc = rtems_bsdnet_ifconfig(iface, SIOCSIFADDR, &ipaddr);
    715     if (rc < 0) {
    716     printf("Could not set IP address: %s\\n", strerror(errno));
    717     return;
    718     }
    719     }
    720     if (f_up != 0) {
    721     flags \|= IFF_UP;
    722     }
    723     if (f_down != 0) {
    724     printf("Warning: taking interfaces down is not supported\\n");
    725     }
    726     rc = rtems_bsdnet_ifconfig(iface, SIOCSIFFLAGS, &flags);
    727     if (rc < 0) {
    728     printf("Could not set interface flags: %s\\n", strerror(errno));
    729     return;
    730     }
    731     }
    732     void mon_route(int argc, char \*argv[],  unsigned32 command_arg,
    733     bool verbose)
    734     {
    735     int                cmd;
    736     struct sockaddr_in dst;
    737     struct sockaddr_in gw;
    738     struct sockaddr_in netmask;
    739     int                f_host;
    740     int                f_gw       = 0;
    741     int                cur_idx;
    742     int                flags;
    743     int                rc;
    744     memset(&dst, 0, sizeof(dst));
    745     memset(&gw, 0, sizeof(gw));
    746     memset(&netmask, 0, sizeof(netmask));
    747     dst.sin_len = sizeof(dst);
    748     dst.sin_family = AF_INET;
    749     dst.sin_addr.s_addr = inet_addr("0.0.0.0");
    750     gw.sin_len = sizeof(gw);
    751     gw.sin_family = AF_INET;
    752     gw.sin_addr.s_addr = inet_addr("0.0.0.0");
    753     netmask.sin_len = sizeof(netmask);
    754     netmask.sin_family = AF_INET;
    755     netmask.sin_addr.s_addr = inet_addr("255.255.255.0");
    756     if (argc < 2) {
    757     rtems_bsdnet_show_inet_routes();
    758     return;
    759     }
    760     if (strcmp(argv[1], "add") == 0) {
    761     cmd = RTM_ADD;
    762     } else if (strcmp(argv[1], "del") == 0) {
    763     cmd = RTM_DELETE;
    764     } else {
    765     printf("invalid command: %s\\n", argv[1]);
    766     printf("\\tit should be 'add' or 'del'\\n");
    767     return;
    768     }
    769     if (argc < 3) {
    770     printf("not enough arguments\\n");
    771     return;
    772     }
    773     if (strcmp(argv[2], "-host") == 0) {
    774     f_host = 1;
    775     } else if (strcmp(argv[2], "-net") == 0) {
    776     f_host = 0;
    777     } else {
    778     printf("Invalid type: %s\\n", argv[1]);
    779     printf("\\tit should be '-host' or '-net'\\n");
    780     return;
    781     }
    782     if (argc < 4) {
    783     printf("not enough arguments\\n");
    784     return;
    785     }
    786     inet_pton(AF_INET, argv[3], &dst.sin_addr);
    787     cur_idx = 4;
    788     while(cur_idx < argc) {
    789     if (strcmp(argv[cur_idx], "gw") == 0) {
    790     if ((cur_idx +1) >= argc) {
    791     printf("no gateway address\\n");
    792     return;
    793     }
    794     f_gw = 1;
    795     inet_pton(AF_INET, argv[cur_idx + 1], &gw.sin_addr);
    796     cur_idx += 1;
    797     } else if(strcmp(argv[cur_idx], "netmask") == 0) {
    798     if ((cur_idx +1) >= argc) {
    799     printf("no netmask address\\n");
    800     return;
    801     }
    802     f_gw = 1;
    803     inet_pton(AF_INET, argv[cur_idx + 1], &netmask.sin_addr);
    804     cur_idx += 1;
    805     } else {
    806     printf("Unknown argument\\n");
    807     return;
    808     }
    809     cur_idx += 1;
    810     }
    811     flags = RTF_STATIC;
    812     if (f_gw != 0) {
    813     flags \|= RTF_GATEWAY;
    814     }
    815     if (f_host != 0) {
    816     flags \|= RTF_HOST;
    817     }
    818     rc = rtems_bsdnet_rtrequest(cmd, &dst, &gw, &netmask, flags, NULL);
    819     if (rc < 0) {
    820     printf("Error adding route\\n");
    821     }
    822     }
    823 
    824 Thanks to `Jay Monkman <mailto:jtm@smoothmsmoothie.com>`_ for this example
     830
     831Thanks to Jay Monkman <mailto:jtm@smoothmsmoothie.com> for this example
    825832code.
    826833
     
    828835------------------------------
    829836
    830 .. code:: c
     837.. code-block:: c
    831838
    832839    int rtems_bsdnet_synchronize_ntp (int interval, rtems_task_priority priority);
    833840
    834 If the interval argument is 0 the routine synchronizes the RTEMS time-of-day
    835 clock with the first NTP server in the rtems_bsdnet_ntpserve array and
    836 returns.  The priority argument is ignored.
    837 
    838 If the interval argument is greater than 0, the routine also starts an
    839 RTEMS task at the specified priority and polls the NTP server every
    840 'interval' seconds.  NOTE: This mode of operation has not yet been
    841 implemented.
     841If the interval argument is ``0`` the routine synchronizes the RTEMS
     842time-of-day clock with the first NTP server in the ``rtems_bsdnet_ntpserve``
     843array and returns.  The priority argument is ignored.
     844
     845If the interval argument is greater than 0, the routine also starts an RTEMS
     846task at the specified priority and polls the NTP server every 'interval'
     847seconds.  NOTE: This mode of operation has not yet been implemented.
    842848
    843849On successful synchronization of the RTEMS time-of-day clock the routine
    844 returns 0.  If an error occurs a message is printed and the routine returns -1
    845 with an error code in errno.
    846 There is no timeout - if there is no response from an NTP server the
    847 routine will wait forever.
    848 
    849 .. COMMENT: Written by Eric Norum
    850 
    851 .. COMMENT: COPYRIGHT (c) 1988-2002.
    852 
    853 .. COMMENT: On-Line Applications Research Corporation (OAR).
    854 
    855 .. COMMENT: All rights reserved.
    856 
     850returns ``0``.  If an error occurs a message is printed and the routine returns
     851``-1`` with an error code in errno.  There is no timeout - if there is no
     852response from an NTP server the routine will wait forever.
Note: See TracChangeset for help on using the changeset viewer.