source: rtems/doc/networking/networkapp.t @ 0ed9ac7

4.104.114.84.95
Last change on this file since 0ed9ac7 was 0ed9ac7, checked in by Joel Sherrill <joel.sherrill@…>, on Dec 17, 1998 at 6:18:44 PM

Updated socket information

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