source: rtems-docs/networking/networking_driver.rst @ fb72a00

5am
Last change on this file since fb72a00 was e52906b, checked in by Sebastian Huber <sebastian.huber@…>, on 01/09/19 at 15:14:06

Simplify SPDX-License-Identifier comment

  • Property mode set to 100644
File size: 12.4 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. COMMENT: Written by Eric Norum
4.. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR)
5
6Networking Driver
7#################
8
9Introduction
10============
11
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:`bsps/m68k/gen68360/net` directory in the
16RTEMS source code distribution.  Having a copy of this driver at hand when
17reading the following notes will help significantly.
18
19Learn about the network device
20==============================
21
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.
62
63Understand the network scheduling conventions
64=============================================
65
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.
75
76- ``void rtems_bsdnet_semaphore_release(void)``
77  This function releases the network semaphore.  The network driver tasks must
78  call this function immediately before making any blocking RTEMS request.
79
80- ``void rtems_bsdnet_semaphore_obtain(void)``
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``.
92
93Network Driver Makefile
94=======================
95
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
103
104    DEFINES += -D__INSIDE_RTEMS_BSD_TCPIP_STACK__
105
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.
131
132Write the Driver Attach Function
133================================
134
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:
145
146``ifp->if_softc``
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
160    structure.
161
162``ifp->if_mtu``
163    The maximum transmission unit for the device.  For Ethernet devices this
164    value should almost always be 1500.
165
166``ifp->if_flags``
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.
171
172``ifp->if_snd.ifq_maxlen``
173    The maximum length of the queue of packets waiting to be sent to the
174    driver.  This is normally set to ``ifqmaxlen``.
175
176``ifp->if_init``
177    The address of the driver initialization function.
178
179``ifp->if_start``
180    The address of the driver start function.
181
182``ifp->if_ioctl``
183    The address of the driver ioctl function.
184
185``ifp->if_output``
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
193
194    int rtems_bsdnet_parse_driver_name (
195        const struct rtems_bsdnet_ifconfig *config,
196        char **namep
197    );
198
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.
212
213Write the Driver Start Function.
214================================
215
216This function is called each time the network stack wants to start the
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.
224
225Write the Driver Initialization Function.
226=========================================
227
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
232
233    rtems_id
234    rtems_bsdnet_newproc (char *name,
235        int stacksize,
236        void(*entry)(void *),
237        void *arg);
238
239should be used to start the driver tasks.
240
241Note that the network stack may call the driver initialization function more
242than once.  Make sure multiple versions of the receive and transmit tasks are
243not accidentally started.
244
245Write the Driver Transmit Task
246==============================
247
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.
254
255Write the Driver Receive Task
256=============================
257
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.
263
264Write the Driver Interrupt Handler
265==================================
266
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.
271
272Write the Driver IOCTL Function
273===============================
274
275This function handles ioctl requests directed at the device.  The ioctl
276commands which must be handled are:
277
278``SIOCGIFADDR``
279
280``SIOCSIFADDR``
281    If the device is an Ethernet interface these commands should be passed on
282    to ``ether_ioctl``.
283
284``SIOCSIFFLAGS``
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``:
287
288    ``IFF_RUNNING``
289        Stop the device.
290
291    ``IFF_UP``
292        Start the device.
293
294    ``IFF_UP|IFF_RUNNING``
295        Stop then start the device.
296
297    ``0``
298        Do nothing.
299
300Write the Driver Statistic-Printing Function
301============================================
302
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 TracBrowser for help on using the repository browser.