Changeset b412038 in rtems-docs for networking/networking_driver.rst


Ignore:
Timestamp:
04/11/16 03:53:58 (7 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, 5, am, 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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • 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``.
Note: See TracChangeset for help on using the changeset viewer.