source: rtems/doc/bsp_howto/network.t @ febb47e

4.104.114.84.95
Last change on this file since febb47e was febb47e, checked in by Joel Sherrill <joel.sherrill@…>, on 11/19/98 at 16:59:38

Changed version string.

Added much new stuff to the POSIX User's Guide.

New chapters stuff shrunk.

  • Property mode set to 100644
File size: 9.8 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.  You should have a copy of this driver at
21hand when reading the following notes.
22
23@section Learn about the network device
24
25Before starting to write the network driver you need to be 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
37outtoing 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 your driver transmit and receive tasks you must
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}).
83Your transmit and receive tasks must abide by this protocol which means you must
84be careful to avoid `deadly embraces' with the other network tasks.
85A number of routines are provided to make it easier for your code
86to 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.
93Your task 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 your task has released the network semaphore to allow other
100network-related tasks to run while your task blocks you must call this
101function 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 *)}
105Your task should call this function when it wishes to wait for an event.
106This 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 Write your driver attach function
114The driver attach function is responsible for configuring the driver
115and making the connection between the network stack
116and the driver.
117
118Driver attach functions take a pointer to an
119@code{rtems_bsdnet_ifconfig} structure as their only argument.
120and set the driver parameters based on the
121values in this structure.  If an entry in the configuration
122structure is zero the attach function chooses an
123appropriate default value for that parameter.
124
125
126The driver should then set up several fields in the ifnet structure
127in the device-dependent data structure supplied and maintained by the driver:
128
129@table @code
130@item ifp->if_softc
131Pointer to the device-dependent data.  The first entry
132in the device-dependent data structure must be an @code{arpcom}
133structure.
134
135@item ifp->if_name
136The name of the device.  The network stack uses this string
137and the device number for device name lookups.  The name should not
138contain digits as these will be assumed to be part of the unit number
139and not part of the device name.
140
141
142@item ifp->if_unit
143The device number.  The network stack uses this number and the
144device name for device name lookups.  For example, if
145@code{ifp->if_name} is @samp{scc}, and @code{ifp->if_unit} is @samp{1},
146the full device name would be @samp{scc1}.
147
148@item ifp->if_mtu
149The maximum transmission unit for the device.  For Ethernet
150devices this value should almost always be 1500.
151
152@item ifp->if_flags
153The device flags.  Ethernet devices should set the flags
154to @code{IFF_BROADCAST|IFF_SIMPLEX}, indicating that the
155device can broadcast packets to multiple destinations
156and does not receive and transmit at the same time.
157
158@item ifp->if_snd.ifq_maxlen
159The maximum length of the queue of packets waiting to be
160sent to the driver.  This is normally set to @code{ifqmaxlen}.
161
162@item ifp->if_init
163The address of the driver initialization function.
164
165@item ifp->if_start
166The address of the driver start function.
167
168@item ifp->if_ioctl
169The address of the driver ioctl function.
170
171@item ifp->if_output
172The address of the output function.  Ethernet devices
173should set this to @code{ether_output}.
174@end table
175
176Once the attach function  has set up the above entries it must link the
177driver data structure onto the list of devices by
178calling @code{if_attach}.  Ethernet devices should then
179call @code{ether_ifattach}.  Both functions take a pointer to the
180device's @code{ifnet} structure as their only argument.
181
182The attach function should return a non-zero value to indicate that
183the driver has been successfully configured and attached.
184
185
186
187
188@section Write your driver start function.
189This function is called each time the network stack wants to start the
190transmitter.  This occures whenever the network stack adds a packet
191to a device's send queue and the @code{IFF_OACTIVE} bit in the
192device's @code{if_flags} is not set.
193
194For many devices this function need only set the @code{IFF_OACTIVE} bit in the
195@code{if_flags} and send an event to the transmit task
196indicating that a packet is in the driver transmit queue.
197
198
199@section Write your driver initialization function.
200This function should initialize the device, attach to interrupt handler,
201and start the driver transmit and receive tasks.  The function
202
203@example
204rtems_id
205rtems_bsdnet_newproc (char *name,
206                      int stacksize,
207                      void(*entry)(void *),
208                      void *arg);
209@end example
210
211should be used to start the driver tasks.
212
213Note that the network stack may call the driver initialization function more
214than once.
215Make sure you don't start multiple versions of the receive and transmit tasks.
216
217
218
219@section Write your driver transmit task.
220This 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
221driver start function indicating that packets are waiting to be transmitted.
222When the transmit task has drained the driver send queue the task should clear
223the @code{IFF_OACTIVE} bit in @code{if_flags} and block until another outgoing
224packet is queued.
225
226
227@section Write your driver receive task.
228This task should block until a packet arrives from the device.  If the
229device is an Ethernet interface the function @code{ether_input} should be called
230to forward the packet to the network stack.   The arguments to @code{ether_input}
231are a pointer to the interface data structure, a pointer to the ethernet
232header and a pointer to an mbuf containing the packet itself.
233
234
235
236
237@section Write your driver interrupt handler.
238A typical interrupt handler will do nothing more than the hardware
239manipulation required to acknowledge the interrupt and send an RTEMS event
240to wake up the driver receive or transmit task waiting for the event.
241Network interface interrupt handlers must not make any calls to other
242network routines.
243
244
245
246@section Write your driver ioctl function.
247This function handles ioctl requests directed at the device.  The ioctl
248commands which must be handled are:
249
250@table @code
251@item SIOCGIFADDR
252@item SIOCSIFADDR
253If the device is an Ethernet interface these
254commands should be passed on to @code{ether_ioctl}.
255
256@item SIOCSIFFLAGS
257This command should be used to start or stop the device,
258depending on the state of the interface @code{IFF_UP} and
259@code{IFF_RUNNING} bits in @code{if_flags}:
260@table @code
261@item IFF_RUNNING
262Stop the device.
263
264@item IFF_UP
265Start the device.
266
267@item IFF_UP|IFF_RUNNING
268Stop then start the device.
269
270@item 0
271Do nothing.
272
273@end table
274@end table
275
276
277
278@section Write Your Driver Statistic-Printing Function
279This function should print the values of any statistic/diagnostic
280counters your driver may use.  The driver ioctl function should call
281the statistic-printing function when the ioctl command is
282@code{SIO_RTEMS_SHOW_STATS}.
283
284
Note: See TracBrowser for help on using the repository browser.