diff options
Diffstat (limited to 'networking/networking_driver.rst')
| -rw-r--r-- | networking/networking_driver.rst | 305 |
1 files changed, 0 insertions, 305 deletions
diff --git a/networking/networking_driver.rst b/networking/networking_driver.rst deleted file mode 100644 index c161c2b..0000000 --- a/networking/networking_driver.rst +++ /dev/null @@ -1,305 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. COMMENT: Written by Eric Norum -.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR) - -Networking Driver -################# - -Introduction -============ - -This chapter is intended to provide an introduction to the procedure for -writing RTEMS network device drivers. The example code is taken from the -'Generic 68360' network device driver. The source code for this driver is -located in the :file:`bsps/m68k/gen68360/net` directory in the -RTEMS source code distribution. Having a copy of this driver at hand when -reading the following notes will help significantly. - -Learn about the network device -============================== - -Before starting to write the network driver become completely familiar with the -programmer's view of the device. The following points list some of the details -of the device that must be understood before a driver can be written. - -- Does the device use DMA to transfer packets to and from memory or does the - processor have to copy packets to and from memory on the device? - -- If the device uses DMA, is it capable of forming a single outgoing packet - from multiple fragments scattered in separate memory buffers? - -- If the device uses DMA, is it capable of chaining multiple outgoing packets, - or does each outgoing packet require intervention by the driver? - -- Does the device automatically pad short frames to the minimum 64 bytes or - does the driver have to supply the padding? - -- Does the device automatically retry a transmission on detection of a - collision? - -- If the device uses DMA, is it capable of buffering multiple packets to - memory, or does the receiver have to be restarted after the arrival of each - packet? - -- How are packets that are too short, too long, or received with CRC errors - handled? Does the device automatically continue reception or does the driver - have to intervene? - -- How is the device Ethernet address set? How is the device programmed to - accept or reject broadcast and multicast packets? - -- What interrupts does the device generate? Does it generate an interrupt for - each incoming packet, or only for packets received without error? Does it - generate an interrupt for each packet transmitted, or only when the transmit - queue is empty? What happens when a transmit error is detected? - -In addition, some controllers have specific questions regarding board specific -configuration. For example, the SONIC Ethernet controller has a very -configurable data bus interface. It can even be configured for sixteen and -thirty-two bit data buses. This type of information should be obtained from -the board vendor. - -Understand the network scheduling conventions -============================================= - -When writing code for the driver transmit and receive tasks, take care to -follow the network scheduling conventions. All tasks which are associated with -networking share various data structures and resources. To ensure the -consistency of these structures the tasks execute only when they hold the -network semaphore (``rtems_bsdnet_semaphore``). The transmit and receive tasks -must abide by this protocol. Be very careful to avoid 'deadly embraces' with -the other network tasks. A number of routines are provided to make it easier -for the network driver code to conform to the network task scheduling -conventions. - -- ``void rtems_bsdnet_semaphore_release(void)`` - This function releases the network semaphore. The network driver tasks must - call this function immediately before making any blocking RTEMS request. - -- ``void rtems_bsdnet_semaphore_obtain(void)`` - This function obtains the network semaphore. If a network driver task has - released the network semaphore to allow other network-related tasks to run - while the task blocks, then this function must be called to reobtain the - semaphore immediately after the return from the blocking RTEMS request. - -- ``rtems_bsdnet_event_receive(rtems_event_set, rtems_option, rtems_interval, rtems_event_set *)`` - The network driver task should call this function when it wishes to wait for - an event. This function releases the network semaphore, calls - ``rtems_event_receive`` to wait for the specified event or events and - reobtains the semaphore. The value returned is the value returned by the - ``rtems_event_receive``. - -Network Driver Makefile -======================= - -Network drivers are considered part of the BSD network package and as such are -to be compiled with the appropriate flags. This can be accomplished by adding -``-D__INSIDE_RTEMS_BSD_TCPIP_STACK__`` to the ``command line``. If the driver -is inside the RTEMS source tree or is built using the RTEMS application -Makefiles, then adding the following line accomplishes this: - -.. code-block:: makefile - - DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__ - -This is equivalent to the following list of definitions. Early versions of the -RTEMS BSD network stack required that all of these be defined. - -.. code-block:: makefile - - -D_COMPILING_BSD_KERNEL_ -DKERNEL -DINET -DNFS \ - -DDIAGNOSTIC -DBOOTP_COMPAT - -Defining these macros tells the network header files that the driver is to be -compiled with extended visibility into the network stack. This is in sharp -contrast to applications that simply use the network stack. Applications do -not require this level of visibility and should stick to the portable -application level API. - -As a direct result of being logically internal to the network stack, network -drivers use the BSD memory allocation routines This means, for example, that -malloc takes three arguments. See the SONIC device driver -(:file:`c/src/lib/libchip/network/sonic.c`) for an example of this. Because of -this, network drivers should not include ``<stdlib.h>``. Doing so will result -in conflicting definitions of ``malloc()``. - -*Application level* code including network servers such as the FTP daemon are -*not* part of the BSD kernel network code and should not be compiled with the -BSD network flags. They should include ``<stdlib.h>`` and not define the -network stack visibility macros. - -Write the Driver Attach Function -================================ - -The driver attach function is responsible for configuring the driver and making -the connection between the network stack and the driver. - -Driver attach functions take a pointer to an ``rtems_bsdnet_ifconfig`` -structure as their only argument. and set the driver parameters based on the -values in this structure. If an entry in the configuration structure is zero -the attach function chooses an appropriate default value for that parameter. - -The driver should then set up several fields in the ifnet structure in the -device-dependent data structure supplied and maintained by the driver: - -``ifp->if_softc`` - Pointer to the device-dependent data. The first entry in the - device-dependent data structure must be an ``arpcom`` structure. - -``ifp->if_name`` - The name of the device. The network stack uses this string and the device - number for device name lookups. The device name should be obtained from - the ``name`` entry in the configuration structure. - -``ifp->if_unit`` - The device number. The network stack uses this number and the device name - for device name lookups. For example, if ``ifp->if_name`` is ``scc`` and - ``ifp->if_unit`` is ``1``, the full device name would be ``scc1``. The - unit number should be obtained from the 'name' entry in the configuration - structure. - -``ifp->if_mtu`` - The maximum transmission unit for the device. For Ethernet devices this - value should almost always be 1500. - -``ifp->if_flags`` - The device flags. Ethernet devices should set the flags to - ``IFF_BROADCAST|IFF_SIMPLEX``, indicating that the device can broadcast - packets to multiple destinations and does not receive and transmit at the - same time. - -``ifp->if_snd.ifq_maxlen`` - The maximum length of the queue of packets waiting to be sent to the - driver. This is normally set to ``ifqmaxlen``. - -``ifp->if_init`` - The address of the driver initialization function. - -``ifp->if_start`` - The address of the driver start function. - -``ifp->if_ioctl`` - The address of the driver ioctl function. - -``ifp->if_output`` - The address of the output function. Ethernet devices should set this to - ``ether_output``. - -RTEMS provides a function to parse the driver name in the configuration -structure into a device name and unit number. - -.. code-block:: c - - int rtems_bsdnet_parse_driver_name ( - const struct rtems_bsdnet_ifconfig *config, - char **namep - ); - -The function takes two arguments; a pointer to the configuration structure and -a pointer to a pointer to a character. The function parses the configuration -name entry, allocates memory for the driver name, places the driver name in -this memory, sets the second argument to point to the name and returns the unit -number. On error, a message is printed and ``-1`` is returned. - -Once the attach function has set up the above entries it must link the driver -data structure onto the list of devices by calling ``if_attach``. Ethernet -devices should then call ``ether_ifattach``. Both functions take a pointer to -the device's ``ifnet`` structure as their only argument. - -The attach function should return a non-zero value to indicate that the driver -has been successfully configured and attached. - -Write the Driver Start Function. -================================ - -This function is called each time the network stack wants to start the -transmitter. This occures whenever the network stack adds a packet to a -device's send queue and the ``IFF_OACTIVE`` bit in the device's ``if_flags`` is -not set. - -For many devices this function need only set the ``IFF_OACTIVE`` bit in the -``if_flags`` and send an event to the transmit task indicating that a packet is -in the driver transmit queue. - -Write the Driver Initialization Function. -========================================= - -This function should initialize the device, attach to interrupt handler, and -start the driver transmit and receive tasks. The function - -.. code-block:: c - - rtems_id - rtems_bsdnet_newproc (char *name, - int stacksize, - void(*entry)(void *), - void *arg); - -should be used to start the driver tasks. - -Note that the network stack may call the driver initialization function more -than once. Make sure multiple versions of the receive and transmit tasks are -not accidentally started. - -Write the Driver Transmit Task -============================== - -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 driver start function indicating that packets are waiting to be -transmitted. When the transmit task has drained the driver send queue the task -should clear the ``IFF_OACTIVE`` bit in ``if_flags`` and block until another -outgoing packet is queued. - -Write the Driver Receive Task -============================= - -This task should block until a packet arrives from the device. If the device -is an Ethernet interface the function ``ether_input`` should be called to -forward the packet to the network stack. The arguments to ``ether_input`` are -a pointer to the interface data structure, a pointer to the ethernet header and -a pointer to an mbuf containing the packet itself. - -Write the Driver Interrupt Handler -================================== - -A typical interrupt handler will do nothing more than the hardware manipulation -required to acknowledge the interrupt and send an RTEMS event to wake up the -driver receive or transmit task waiting for the event. Network interface -interrupt handlers must not make any calls to other network routines. - -Write the Driver IOCTL Function -=============================== - -This function handles ioctl requests directed at the device. The ioctl -commands which must be handled are: - -``SIOCGIFADDR`` - -``SIOCSIFADDR`` - If the device is an Ethernet interface these commands should be passed on - to ``ether_ioctl``. - -``SIOCSIFFLAGS`` - This command should be used to start or stop the device, depending on the - state of the interface ``IFF_UP`` and ``IFF_RUNNING`` bits in ``if_flags``: - - ``IFF_RUNNING`` - Stop the device. - - ``IFF_UP`` - Start the device. - - ``IFF_UP|IFF_RUNNING`` - Stop then start the device. - - ``0`` - Do nothing. - -Write the Driver Statistic-Printing Function -============================================ - -This function should print the values of any statistic/diagnostic counters the -network driver may use. The driver ioctl function should call the -statistic-printing function when the ioctl command is ``SIO_RTEMS_SHOW_STATS``. |