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

4.104.114.84.9
Last change on this file since ab0c689 was ab0c689, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 19, 1998 at 8:29:35 PM

Baseline

  • Property mode set to 100644
File size: 7.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 KA9Q 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_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.  This structure may be declared @code{const} since the
69network initialization functions do not write to any of the entries.
70
71The structure entries are described in the following table.
72If your application uses BOOTP to obtain network configuration
73information and if you are happy with the default values described
74below, you need to provide only the first two entries in this structure.
75
76@table @code
77
78@item struct rtems_bsdnet_ifconfig *ifconfig
79A pointer to the first configuration structure of the first network
80device.  This structure is described in the following section.
81You must provide a value for this entry since there is no default value for it.
82
83
84@item void (*bootp)(void)
85This entry should be set to @code{rtems_bsdnet_do_bootp}
86if your application will use BOOTP to obtain network configuration information.
87It should be set to @code{NULL}
88if your application does not use BOOTP.
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 entry is @code{NULL} the host name,
107and all the remaining values specified by the @code{rtems_bsdnet_configuration}
108structure will be obtained from a BOOTP server.
109
110@item char *domainname
111The name of the Internet domain to which the system belongs.
112
113@item char *gateway
114The Internet host number of the network gateway machine,
115specified in `dotted decimal' (@code{129.128.4.1}) form.
116
117@item char *log_host
118The Internet host number of the machine to which @code{syslog} messages
119will be sent.
120
121@item char *name_server
122The Internet host number of up to three machines to be used as
123Internet Domain Name Servers.
124
125@end table
126
127@example
128rtems_task_set_priority (RTEMS_SELF, 30, &oldPri);
129@end example
130
131@subsection Network device configuration
132Network devices are specified and configured by declaring and initializing a
133@code{struct rtems_bsdnet_ifcontig} structure for each network device.
134These structures may be declared @code{const} since the
135network initialization functions do not write to any of the entries.
136
137The structure entries are described in the following table.  An application
138which uses a single network interface, gets network configuration information
139from a BOOTP server, and uses the default values for all driver
140parameters needs to initialize only the first two entries in the
141structure.
142
143@table @code
144@item char *name
145The full name of the network device.  This name consists of the
146driver name and the unit number (e.g. @code{"scc1"}).
147
148@item int (*attach)(struct rtems_bsdnet_ifconfig *conf)
149The address of the driver @code{attach} function.   The network
150initialization function calls this function to configure the driver and
151attach it to the network stack.
152
153@item struct rtems_bsdnet_ifconfig *next
154A pointer to the network device configuration structure for the next network
155interface, or @code{NULL} if this is the configuration structure of the
156last network interface.
157
158@item char *ip_address
159The Internet address of the device,
160specified in `dotted decimal' (@code{129.128.4.2}) form, or @code{NULL}
161if the device configuration information is being obtained from a
162BOOTP server.
163
164@item char *ip_netmask
165The Internet inetwork mask of the device,
166specified in `dotted decimal' (@code{255.255.255.0}) form, or @code{NULL}
167if the device configuration information is being obtained from a
168BOOTP server.
169
170
171@item void *hardware_address
172The hardware address of the device, or @code{NULL} if the driver is
173to obtain the hardware address in some other way (usually  by reading
174it from the device or from the bootstrap ROM).
175
176@item int ignore_broadcast
177Zero if the device is to accept broadcast packets, non-zero if the device
178is to ignore broadcast packets.
179
180@item int mtu
181The maximum transmission unit of the device, or zero if the driver
182is to choose a default value (typically 1500 for Ethernet devices).
183
184@item int rbuf_count
185The number of receive buffers to use, or zero if the driver is to
186choose a default value
187
188@item int xbuf_count
189The number of transmit buffers to use, or zero if the driver is to
190choose a default value
191Keep in mind that some network devices may use 4 or more
192transmit descriptors for a single transmit buffer.
193
194@end table
195
196
197@subsection Network initialization
198The networking tasks must be started before any
199network I/O operations can be performed.  This is done by calling:
200@example
201rtems_bsdnet_initialize_network ();
202@end example
203
204
205@section Application code
206The RTEMS network package provides almost a complete set of BSD network
207services.  The network functions work like their BSD counterparts
208with the following exceptions:
209
210@itemize
211@item A given socket can be read or written by only one task at a time.
212@item There is no @code{select} function.
213@item You must call @code{openlog} before calling any of the @code{syslog} functions.
214@item @b{Some of the network functions are not thread-safe.}
215For example the following functions return a pointer to a static
216buffer which remains valid only until the next call:
217
218@table @code
219@item gethostbyaddr
220@item gethostbyname
221@item inet_ntoa
222(@code{inet_ntop} is thread-safe, though).
223@end table
224@end itemize
225
226@subsection Network statistics
227There are a number of functions to print statistics gathered by the network stack:
228@table @code
229@item rtems_bsdnet_show_if_stats
230Display statistics gathered by network interfaces.
231
232@item rtems_bsdnet_show_ip_stats
233Display IP packet statistics.
234
235@item rtems_bsdnet_show_icmp_stats
236Display ICMP packet statistics.
237
238@item rtems_bsdnet_show_tcp_stats
239Display TCP packet statistics.
240
241@item rtems_bsdnet_show_udp_stats
242Display UDP packet statistics.
243
244@item rtems_bsdnet_show_mbuf_stats
245Display mbuf statistics.
246
247@item rtems_bsdnet_show_inet_routes
248Display the routing table.
249
250@end table
Note: See TracBrowser for help on using the repository browser.