source: rtems/doc/networking/driver.t @ f3482e3

4.104.114.84.95
Last change on this file since f3482e3 was 202d54e, checked in by Joel Sherrill <joel.sherrill@…>, on 04/19/99 at 14:58:16

Comments from Eric Norum taken into account.

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