source: rtems/doc/networking/networkapp.t @ 33bbd74

4.104.114.84.9
Last change on this file since 33bbd74 was 33bbd74, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 11, 1999 at 2:51:31 AM

Added information about the NTP servier field and included a copy
of the C definition of the configuration structure.

  • Property mode set to 100644
File size: 14.0 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_config}
68structure.
69
70@example
71@group
72struct rtems_bsdnet_config @{
73  /*
74   * This entry points to the head of the ifconfig chain.
75   */
76  struct rtems_bsdnet_ifconfig *ifconfig;
77
78  /*
79   * This entry should be rtems_bsdnet_do_bootp if BOOTP
80   * is being used to configure the network, and NULL
81   * if BOOTP is not being used.
82   */
83  void                    (*bootp)(void);
84
85  /*
86   * The remaining items can be initialized to 0, in
87   * which case the default value will be used.
88   */
89  rtems_task_priority  network_task_priority;  /* 100        */
90  unsigned long        mbuf_bytecount;         /* 64 kbytes  */
91  unsigned long        mbuf_cluster_bytecount; /* 128 kbytes */
92  char                *hostname;               /* BOOTP      */
93  char                *domainname;             /* BOOTP      */
94  char                *gateway;                /* BOOTP      */
95  char                *log_host;               /* BOOTP      */
96  char                *name_server[3];         /* BOOTP      */
97  char                *ntp_server[3];          /* BOOTP      */
98@};
99@end group
100@end example
101
102The structure entries are described in the following table.
103If your application uses BOOTP/DHCP to obtain network configuration
104information and if you are happy with the default values described
105below, you need to provide only the first two entries in this structure.
106
107@table @code
108
109@item struct rtems_bsdnet_ifconfig *ifconfig
110A pointer to the first configuration structure of the first network
111device.  This structure is described in the following section.
112You must provide a value for this entry since there is no default value for it.
113
114
115@item void (*bootp)(void)
116This entry should be set to @code{rtems_bsdnet_do_bootp}
117if your application will use BOOTP/DHCP
118to obtain network configuration information.
119It should be set to @code{NULL}
120if your application does not use BOOTP/DHCP.
121
122
123@item int network_task_priority
124The priority at which the network task and network device
125receive and transmit tasks will run.
126If a value of 0 is specified the tasks will run at priority 100.
127
128@item unsigned long mbuf_bytecount
129The number of bytes to allocate from the heap for use as mbufs. 
130If a value of 0 is specified, 64 kbytes will be allocated.
131
132@item unsigned long mbuf_cluster_bytecount
133The number of bytes to allocate from the heap for use as mbuf clusters. 
134If a value of 0 is specified, 128 kbytes will be allocated.
135
136@item char *hostname
137The host name of the system.
138If this, or any of the following, entries are @code{NULL} the value
139may be obtained from a BOOTP/DHCP server.
140
141@item char *domainname
142The name of the Internet domain to which the system belongs.
143
144@item char *gateway
145The Internet host number of the network gateway machine,
146specified in `dotted decimal' (@code{129.128.4.1}) form.
147
148@item char *log_host
149The Internet host number of the machine to which @code{syslog} messages
150will be sent.
151
152@item char *name_server[3]
153The Internet host numbers of up to three machines to be used as
154Internet Domain Name Servers.
155
156@item char *name_server[3]
157The Internet host numbers of up to three machines to be used as
158Network Time Protocol (NTP) Servers.
159
160@end table
161
162In addition, the following fields in the @code{rtems_bsdnet_ifconfig}
163are of interest.
164
165@table @b
166
167@item int port
168The I/O port number (ex: 0x240) on which the external Ethernet
169can be accessed.
170
171@item int irno
172The interrupt number of the external Ethernet controller.
173
174@item int bpar
175The address of the shared memory on the external Ethernet controller.
176
177
178@end table
179
180@subsection Network device configuration
181Network devices are specified and configured by declaring and initializing a
182@code{struct rtems_bsdnet_ifcontig} structure for each network device.
183
184The structure entries are described in the following table.  An application
185which uses a single network interface, gets network configuration information
186from a BOOTP/DHCP server, and uses the default values for all driver
187parameters needs to initialize only the first two entries in the
188structure.
189
190@table @code
191@item char *name
192The full name of the network device.  This name consists of the
193driver name and the unit number (e.g. @code{"scc1"}).
194The @code{bsp.h} include file usually defines RTEMS_BSP_NETWORK_DRIVER_NAME as
195the name of the primary (or only) network driver.
196
197@item int (*attach)(struct rtems_bsdnet_ifconfig *conf)
198The address of the driver @code{attach} function.   The network
199initialization function calls this function to configure the driver and
200attach it to the network stack.
201The @code{bsp.h} include file usually defines RTEMS_BSP_NETWORK_DRIVER_ATTACH as
202the name of the  attach function of the primary (or only) network driver.
203
204@item struct rtems_bsdnet_ifconfig *next
205A pointer to the network device configuration structure for the next network
206interface, or @code{NULL} if this is the configuration structure of the
207last network interface.
208
209@item char *ip_address
210The Internet address of the device,
211specified in `dotted decimal' (@code{129.128.4.2}) form, or @code{NULL}
212if the device configuration information is being obtained from a
213BOOTP/DHCP server.
214
215@item char *ip_netmask
216The Internet inetwork mask of the device,
217specified in `dotted decimal' (@code{255.255.255.0}) form, or @code{NULL}
218if the device configuration information is being obtained from a
219BOOTP/DHCP server.
220
221
222@item void *hardware_address
223The hardware address of the device, or @code{NULL} if the driver is
224to obtain the hardware address in some other way (usually  by reading
225it from the device or from the bootstrap ROM).
226
227@item int ignore_broadcast
228Zero if the device is to accept broadcast packets, non-zero if the device
229is to ignore broadcast packets.
230
231@item int mtu
232The maximum transmission unit of the device, or zero if the driver
233is to choose a default value (typically 1500 for Ethernet devices).
234
235@item int rbuf_count
236The number of receive buffers to use, or zero if the driver is to
237choose a default value
238
239@item int xbuf_count
240The number of transmit buffers to use, or zero if the driver is to
241choose a default value
242Keep in mind that some network devices may use 4 or more
243transmit descriptors for a single transmit buffer.
244
245@end table
246
247A complete network configuration specification can be as simple as the one
248shown in the following example.
249This configuration uses a single network interface, gets
250network configuration information
251from a BOOTP/DHCP server, and uses the default values for all driver
252parameters.
253
254@example
255static struct rtems_bsdnet_ifconfig netdriver_config = @{
256        RTEMS_BSP_NETWORK_DRIVER_NAME,
257        RTEMS_BSP_NETWORK_DRIVER_ATTACH
258@};
259struct rtems_bsdnet_config rtems_bsdnet_config = @{
260        &netdriver_config,
261        rtems_bsdnet_do_bootp,
262@};
263@end example
264
265
266@subsection Network initialization
267The networking tasks must be started before any
268network I/O operations can be performed.  This is done by calling:
269@example
270rtems_bsdnet_initialize_network ();
271@end example
272
273This function is declared in @code{rtems/rtems_bsdnet.h}.
274
275
276
277@section Application Programming Interface
278
279The RTEMS network package provides almost a complete set of BSD network
280services.  The network functions work like their BSD counterparts
281with the following exceptions:
282
283@itemize @bullet
284@item A given socket can be read or written by only one task at a time.
285
286@item The @code{select} function only works for file descriptors associated
287with sockets.
288
289@item You must call @code{openlog} before calling any of the @code{syslog} functions.
290
291@item @b{Some of the network functions are not thread-safe.}
292For example the following functions return a pointer to a static
293buffer which remains valid only until the next call:
294
295@table @code
296@item gethostbyaddr
297@item gethostbyname
298@item inet_ntoa
299(@code{inet_ntop} is thread-safe, though).
300@end table
301
302@item The RTEMS network package gathers statistics.
303
304@item Addition of a mechanism to "tap onto" an interface
305and monitor every packet received and transmitted.
306
307@item Addition of @code{SO_SNDWAKEUP} and @code{SO_RCVWAKEUP} socket options.
308
309@end itemize
310
311Some of the new features are discussed in more detail in the following
312sections.
313
314@subsection Network Statistics
315
316There are a number of functions to print statistics gathered by
317the network stack.
318These function are declared in @code{rtems/rtems_bsdnet.h}.
319
320@table @code
321@item rtems_bsdnet_show_if_stats
322Display statistics gathered by network interfaces.
323
324@item rtems_bsdnet_show_ip_stats
325Display IP packet statistics.
326
327@item rtems_bsdnet_show_icmp_stats
328Display ICMP packet statistics.
329
330@item rtems_bsdnet_show_tcp_stats
331Display TCP packet statistics.
332
333@item rtems_bsdnet_show_udp_stats
334Display UDP packet statistics.
335
336@item rtems_bsdnet_show_mbuf_stats
337Display mbuf statistics.
338
339@item rtems_bsdnet_show_inet_routes
340Display the routing table.
341
342@end table
343
344@subsection Tapping Into an Interface
345
346RTEMS add two new ioctls to the BSD networking code:
347SIOCSIFTAP and SIOCGIFTAP.  These may be used to set and get a
348@i{tap function}.  The tap function will be called for every
349Ethernet packet received by the interface.
350
351These are called like other interface ioctls, such as SIOCSIFADDR.
352When setting the tap function with SIOCSIFTAP, set the ifr_tap field
353of the ifreq struct to the tap function.  When retrieving the tap
354function with SIOCGIFTAP, the current tap function will be returned in
355the ifr_tap field.  To stop tapping packets, call SIOCSIFTAP with a
356ifr_tap field of 0.
357
358The tap function is called like this:
359
360@example
361int tap (struct ifnet *, struct ether_header *, struct mbuf *)
362@end example
363
364The tap function should return 1 if the packet was fully handled, in
365which case the caller will simply discard the mbuf.  The tap function
366should return 0 if the packet should be passed up to the higher
367networking layers.
368
369The tap function is called with the network semaphore locked.  It must
370not make any calls on the application levels of the networking level
371itself.  It is safe to call other non-networking RTEMS functions.
372
373@subsection Socket Options
374
375RTEMS adds two new @code{SOL_SOCKET} level options for @code{setsockopt} and
376@code{getsockopt}: @code{SO_SNDWAKEUP} and @code{SO_RCVWAKEUP}.  For both, the
377option value should point to a sockwakeup structure.  The sockwakeup
378structure has the following fields:
379
380@example
381@group
382  void    (*sw_pfn) (struct socket *, caddr_t);
383  caddr_t sw_arg;
384@end group
385@end example
386
387These options are used to set a function to be called when there is
388data available from the socket (@code{SO_RCVWAKEUP}) and when there is space
389available to accept data written to the socket (@code{SO_SNDWAKEUP}).
390
391If @code{setsockopt} is called with the @code{SO_RCVWAKEUP} option, and the
392@code{sw_pfn} field is not zero, then when there is data
393available to be read from
394the socket, the function pointed to by the @code{sw_pfn} field will be
395called.  A pointer to the socket structure will be passed as the first
396argument to the function.  The @code{sw_arg} field set by the
397@code{SO_RCVWAKEUP} call will be passed as the second argument to the function.
398
399If @code{setsockopt} is called with the @code{SO_SNDWAKEUP}
400function, and the @code{sw_pfn} field is not zero, then when
401there is space available to accept data written to the socket,
402the function pointed to by the @code{sw_pfn} field
403will be called.  The arguments passed to the function will be as with
404@code{SO_SNDWAKEUP}.
405
406When the function is called, the network semaphore will be locked.
407The function must be careful not to call any networking functions.  It
408is OK to call an RTEMS function; for example, it is OK to send an
409RTEMS event.
410
411The purpose of these functions is to permit a more efficient
412alternative to the select call when dealing with a large number of
413sockets.
414
415@subsection Time Synchronization Using NTP
416
417@example
418int rtems_bsdnet_synchronize_ntp (int interval, rtems_task_priority priority);
419@end example
420
421If the interval argument is 0 the routine synchronizes the RTEMS time-of-day
422clock with the first NTP server in the rtems_bsdnet_ntpserve array and
423returns.  The priority argument is ignored.
424
425If the interval argument is greater than 0, the routine also starts an
426RTEMS task at the specified priority and polls the NTP server every
427`interval' seconds.  NOTE: This mode of operation has not yet been
428implemented.
429
430On successful synchronization of the RTEMS time-of-day clock the routine
431returns 0.  If an error occurs a message is printed and the routine returns -1
432with an error code in errno.
433There is no timeout -- if there is no response from an NTP server the
434routine will wait forever.
435
436
437
438
Note: See TracBrowser for help on using the repository browser.