source: rtems/doc/networking/networkapp.t @ d102810e

4.104.114.84.9
Last change on this file since d102810e was 461caa5c, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 25, 1999 at 1:45:10 PM

Swapped SO_SNDWAKEUP and SO_RCVWAKEUP in many places since they were
backwards.

  • Property mode set to 100644
File size: 11.9 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 Using Networking in an RTEMS Application
12
13@section Makefile changes
14@subsection Including the required managers
15The FreeBSD networking code requires several RTEMS managers
16in the application:
17
18@example
19MANAGERS = io event semaphore
20@end example
21
22@subsection Increasing the size of the heap
23The networking tasks allocate a lot of memory.  For most applications
24the heap should be at least 256 kbytes.
25The amount of memory set aside for the heap can be adjusted by setting
26the @code{CFLAGS_LD} definition as shown below:
27
28@example
29CFLAGS_LD += -Wl,--defsym -Wl,HeapSize=0x80000
30@end example
31
32This sets aside 512 kbytes of memory for the heap.
33
34@section System Configuration
35
36The networking tasks allocate some RTEMS objects.  These
37must be accounted for in the application configuration table.  The following
38lists the requirements.
39
40@table @b
41@item TASKS
42One network task plus a receive and transmit task for each device.
43
44@item SEMAPHORES
45One network semaphore plus one syslog mutex semaphore if the application uses
46openlog/syslog.
47
48@item EVENTS
49The network stack uses @code{RTEMS_EVENT_24} and @code{RTEMS_EVENT_25}.
50This has no effect on the application configuration, but
51application tasks which call the network functions should not
52use these events for other purposes.
53
54@end table
55
56@section Initialization
57@subsection Additional include files
58The source file which declares the network configuration
59structures and calls the network initialization function must include
60
61@example
62#include <rtems/rtems_bsdnet.h>
63@end example
64
65@subsection Network configuration
66The network configuration is specified by declaring
67and initializing the @code{rtems_bsdnet_configuration}
68structure.
69
70The structure entries are described in the following table.
71If your application uses BOOTP/DHCP to obtain network configuration
72information and if you are happy with the default values described
73below, you need to provide only the first two entries in this structure.
74
75@table @code
76
77@item struct rtems_bsdnet_ifconfig *ifconfig
78A pointer to the first configuration structure of the first network
79device.  This structure is described in the following section.
80You must provide a value for this entry since there is no default value for it.
81
82
83@item void (*bootp)(void)
84This entry should be set to @code{rtems_bsdnet_do_bootp}
85if your application will use BOOTP/DHCP
86to obtain network configuration information.
87It should be set to @code{NULL}
88if your application does not use BOOTP/DHCP.
89
90
91@item int network_task_priority
92The priority at which the network task and network device
93receive and transmit tasks will run.
94If a value of 0 is specified the tasks will run at priority 100.
95
96@item unsigned long mbuf_bytecount
97The number of bytes to allocate from the heap for use as mbufs. 
98If a value of 0 is specified, 64 kbytes will be allocated.
99
100@item unsigned long mbuf_cluster_bytecount
101The number of bytes to allocate from the heap for use as mbuf clusters. 
102If a value of 0 is specified, 128 kbytes will be allocated.
103
104@item char *hostname
105The host name of the system.
106If this, or any of the following, entries are @code{NULL} the value
107may be obtained from a BOOTP/DHCP server.
108
109@item char *domainname
110The name of the Internet domain to which the system belongs.
111
112@item char *gateway
113The Internet host number of the network gateway machine,
114specified in `dotted decimal' (@code{129.128.4.1}) form.
115
116@item char *log_host
117The Internet host number of the machine to which @code{syslog} messages
118will be sent.
119
120@item char *name_server[3]
121The Internet host numbers of up to three machines to be used as
122Internet Domain Name Servers.
123
124@item int port
125The I/O port number (ex: 0x240) on which the external Ethernet
126can be accessed.
127
128@item int irno
129The interrupt number of the external Ethernet controller.
130
131@item int bpar
132The address of the shared memory on the external Ethernet controller.
133
134
135@end table
136
137@subsection Network device configuration
138Network devices are specified and configured by declaring and initializing a
139@code{struct rtems_bsdnet_ifcontig} structure for each network device.
140
141The structure entries are described in the following table.  An application
142which uses a single network interface, gets network configuration information
143from a BOOTP/DHCP server, and uses the default values for all driver
144parameters needs to initialize only the first two entries in the
145structure.
146
147@table @code
148@item char *name
149The full name of the network device.  This name consists of the
150driver name and the unit number (e.g. @code{"scc1"}).
151The @code{bsp.h} include file usually defines RTEMS_BSP_NETWORK_DRIVER_NAME as
152the name of the primary (or only) network driver.
153
154@item int (*attach)(struct rtems_bsdnet_ifconfig *conf)
155The address of the driver @code{attach} function.   The network
156initialization function calls this function to configure the driver and
157attach it to the network stack.
158The @code{bsp.h} include file usually defines RTEMS_BSP_NETWORK_DRIVER_ATTACH as
159the name of the  attach function of the primary (or only) network driver.
160
161@item struct rtems_bsdnet_ifconfig *next
162A pointer to the network device configuration structure for the next network
163interface, or @code{NULL} if this is the configuration structure of the
164last network interface.
165
166@item char *ip_address
167The Internet address of the device,
168specified in `dotted decimal' (@code{129.128.4.2}) form, or @code{NULL}
169if the device configuration information is being obtained from a
170BOOTP/DHCP server.
171
172@item char *ip_netmask
173The Internet inetwork mask of the device,
174specified in `dotted decimal' (@code{255.255.255.0}) form, or @code{NULL}
175if the device configuration information is being obtained from a
176BOOTP/DHCP server.
177
178
179@item void *hardware_address
180The hardware address of the device, or @code{NULL} if the driver is
181to obtain the hardware address in some other way (usually  by reading
182it from the device or from the bootstrap ROM).
183
184@item int ignore_broadcast
185Zero if the device is to accept broadcast packets, non-zero if the device
186is to ignore broadcast packets.
187
188@item int mtu
189The maximum transmission unit of the device, or zero if the driver
190is to choose a default value (typically 1500 for Ethernet devices).
191
192@item int rbuf_count
193The number of receive buffers to use, or zero if the driver is to
194choose a default value
195
196@item int xbuf_count
197The number of transmit buffers to use, or zero if the driver is to
198choose a default value
199Keep in mind that some network devices may use 4 or more
200transmit descriptors for a single transmit buffer.
201
202@end table
203
204A complete network configuration specification can be as simple as the one
205shown in the following example.
206This configuration uses a single network interface, gets
207network configuration information
208from a BOOTP/DHCP server, and uses the default values for all driver
209parameters.
210
211@example
212static struct rtems_bsdnet_ifconfig netdriver_config = @{
213        RTEMS_BSP_NETWORK_DRIVER_NAME,
214        RTEMS_BSP_NETWORK_DRIVER_ATTACH
215@};
216struct rtems_bsdnet_config rtems_bsdnet_config = @{
217        &netdriver_config,
218        rtems_bsdnet_do_bootp,
219@};
220@end example
221
222
223@subsection Network initialization
224The networking tasks must be started before any
225network I/O operations can be performed.  This is done by calling:
226@example
227rtems_bsdnet_initialize_network ();
228@end example
229
230This function is declared in @code{rtems/rtems_bsdnet.h}.
231
232
233
234@section Application Programming Interface
235
236The RTEMS network package provides almost a complete set of BSD network
237services.  The network functions work like their BSD counterparts
238with the following exceptions:
239
240@itemize @bullet
241@item A given socket can be read or written by only one task at a time.
242
243@item The @code{select} function only works for file descriptors associated
244with sockets.
245
246@item You must call @code{openlog} before calling any of the @code{syslog} functions.
247
248@item @b{Some of the network functions are not thread-safe.}
249For example the following functions return a pointer to a static
250buffer which remains valid only until the next call:
251
252@table @code
253@item gethostbyaddr
254@item gethostbyname
255@item inet_ntoa
256(@code{inet_ntop} is thread-safe, though).
257@end table
258
259@item The RTEMS network package gathers statistics.
260
261@item Addition of a mechanism to "tap onto" an interface
262and monitor every packet received and transmitted.
263
264@item Addition of @code{SO_SNDWAKEUP} and @code{SO_RCVWAKEUP} socket options.
265
266@end itemize
267
268Some of the new features are discussed in more detail in the following
269sections.
270
271@subsection Network Statistics
272
273There are a number of functions to print statistics gathered by
274the network stack.
275These function are declared in @code{rtems/rtems_bsdnet.h}.
276
277@table @code
278@item rtems_bsdnet_show_if_stats
279Display statistics gathered by network interfaces.
280
281@item rtems_bsdnet_show_ip_stats
282Display IP packet statistics.
283
284@item rtems_bsdnet_show_icmp_stats
285Display ICMP packet statistics.
286
287@item rtems_bsdnet_show_tcp_stats
288Display TCP packet statistics.
289
290@item rtems_bsdnet_show_udp_stats
291Display UDP packet statistics.
292
293@item rtems_bsdnet_show_mbuf_stats
294Display mbuf statistics.
295
296@item rtems_bsdnet_show_inet_routes
297Display the routing table.
298
299@end table
300
301@subsection Tapping Into an Interface
302
303RTEMS add two new ioctls to the BSD networking code:
304SIOCSIFTAP and SIOCGIFTAP.  These may be used to set and get a
305@i{tap function}.  The tap function will be called for every
306Ethernet packet received by the interface.
307
308These are called like other interface ioctls, such as SIOCSIFADDR.
309When setting the tap function with SIOCSIFTAP, set the ifr_tap field
310of the ifreq struct to the tap function.  When retrieving the tap
311function with SIOCGIFTAP, the current tap function will be returned in
312the ifr_tap field.  To stop tapping packets, call SIOCSIFTAP with a
313ifr_tap field of 0.
314
315The tap function is called like this:
316
317@example
318int tap (struct ifnet *, struct ether_header *, struct mbuf *)
319@end example
320
321The tap function should return 1 if the packet was fully handled, in
322which case the caller will simply discard the mbuf.  The tap function
323should return 0 if the packet should be passed up to the higher
324networking layers.
325
326The tap function is called with the network semaphore locked.  It must
327not make any calls on the application levels of the networking level
328itself.  It is safe to call other non-networking RTEMS functions.
329
330@subsection Socket Options
331
332RTEMS adds two new @code{SOL_SOCKET} level options for @code{setsockopt} and
333@code{getsockopt}: @code{SO_SNDWAKEUP} and @code{SO_RCVWAKEUP}.  For both, the
334option value should point to a sockwakeup structure.  The sockwakeup
335structure has the following fields:
336
337@example
338@group
339  void    (*sw_pfn) (struct socket *, caddr_t);
340  caddr_t sw_arg;
341@end group
342@end example
343
344These options are used to set a function to be called when there is
345data available from the socket (@code{SO_RCVWAKEUP}) and when there is space
346available to accept data written to the socket (@code{SO_SNDWAKEUP}).
347
348If @code{setsockopt} is called with the @code{SO_RCVWAKEUP} option, and the
349@code{sw_pfn} field is not zero, then when there is data
350available to be read from
351the socket, the function pointed to by the @code{sw_pfn} field will be
352called.  A pointer to the socket structure will be passed as the first
353argument to the function.  The @code{sw_arg} field set by the
354@code{SO_RCVWAKEUP} call will be passed as the second argument to the function.
355
356If @code{setsockopt} is called with the @code{SO_SNDWAKEUP}
357function, and the @code{sw_pfn} field is not zero, then when
358there is space available to accept data written to the socket,
359the function pointed to by the @code{sw_pfn} field
360will be called.  The arguments passed to the function will be as with
361@code{SO_SNDWAKEUP}.
362
363When the function is called, the network semaphore will be locked.
364The function must be careful not to call any networking functions.  It
365is OK to call an RTEMS function; for example, it is OK to send an
366RTEMS event.
367
368The purpose of these functions is to permit a more efficient
369alternative to the select call when dealing with a large number of
370sockets.
371
372
Note: See TracBrowser for help on using the repository browser.