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

4.104.114.84.9
Last change on this file since cdd26ca2 was cdd26ca2, checked in by Joel Sherrill <joel.sherrill@…>, on Dec 10, 1998 at 11:35:40 PM

Document from Ian Lance Taylor <ian@…> on the tap function.

  • 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 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 code
235The RTEMS network package provides almost a complete set of BSD network
236services.  The network functions work like their BSD counterparts
237with the following exceptions:
238
239@itemize @bullet
240@item A given socket can be read or written by only one task at a time.
241@item There is no @code{select} function.
242@item You must call @code{openlog} before calling any of the @code{syslog} functions.
243@item @b{Some of the network functions are not thread-safe.}
244For example the following functions return a pointer to a static
245buffer which remains valid only until the next call:
246
247@table @code
248@item gethostbyaddr
249@item gethostbyname
250@item inet_ntoa
251(@code{inet_ntop} is thread-safe, though).
252@end table
253@end itemize
254
255@subsection Network Statistics
256There are a number of functions to print statistics gathered by the network stack.
257These function are declared in @code{rtems/rtems_bsdnet.h}.
258@table @code
259@item rtems_bsdnet_show_if_stats
260Display statistics gathered by network interfaces.
261
262@item rtems_bsdnet_show_ip_stats
263Display IP packet statistics.
264
265@item rtems_bsdnet_show_icmp_stats
266Display ICMP packet statistics.
267
268@item rtems_bsdnet_show_tcp_stats
269Display TCP packet statistics.
270
271@item rtems_bsdnet_show_udp_stats
272Display UDP packet statistics.
273
274@item rtems_bsdnet_show_mbuf_stats
275Display mbuf statistics.
276
277@item rtems_bsdnet_show_inet_routes
278Display the routing table.
279
280@end table
281
282In addition, RTEMS add two new ioctls to the BSD networking code:
283SIOCSIFTAP and SIOCGIFTAP.  These may be used to set and get a
284@i{tap function}.  The tap function will be called for every
285Ethernet packet received by the interface.
286
287These are called like other interface ioctls, such as SIOCSIFADDR.
288When setting the tap function with SIOCSIFTAP, set the ifr_tap field
289of the ifreq struct to the tap function.  When retrieving the tap
290function with SIOCGIFTAP, the current tap function will be returned in
291the ifr_tap field.  To stop tapping packets, call SIOCSIFTAP with a
292ifr_tap field of 0.
293
294The tap function is called like this:
295
296@example
297int tap (struct ifnet *, struct ether_header *, struct mbuf *)
298@end example
299
300The tap function should return 1 if the packet was fully handled, in
301which case the caller will simply discard the mbuf.  The tap function
302should return 0 if the packet should be passed up to the higher
303networking layers.
304
305The tap function is called with the network semaphore locked.  It must
306not make any calls on the application levels of the networking level
307itself.  It is safe to call other non-networking RTEMS functions.
308
Note: See TracBrowser for help on using the repository browser.