3 <!-- =============================================================== -->
7 <!-- eCos TCP/IP Stacks -->
9 <!-- =============================================================== -->
10 <!-- ####COPYRIGHTBEGIN#### -->
12 <!-- =============================================================== -->
13 <!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc. -->
14 <!-- This material may be distributed only subject to the terms -->
15 <!-- and conditions set forth in the Open Publication License, v1.0 -->
16 <!-- or later (the latest version is presently available at -->
17 <!-- http://www.opencontent.org/openpub/) -->
18 <!-- Distribution of the work or derivative of the work in any -->
19 <!-- standard (paper) book form is prohibited unless prior -->
20 <!-- permission obtained from the copyright holder -->
21 <!-- =============================================================== -->
23 <!-- ####COPYRIGHTEND#### -->
24 <!-- =============================================================== -->
25 <!-- #####DESCRIPTIONBEGIN#### -->
27 <!-- ####DESCRIPTIONEND#### -->
28 <!-- =============================================================== -->
32 <PART id="net-common-tcpip">
33 <TITLE>TCP/IP Stack Support for eCos</TITLE>
36 The Common Networking for <productname>eCos</productname> package
37 provides support for a complete TCP/IP networking stack.
38 The design allows for the actual stack to be modular and at the
39 current time two different implementations, one based on OpenBSD
40 from 2000 and a new version based on FreeBSD, are available.
41 The particulars of each stack implementation are presented in
42 separate sections following this top-level discussion.
45 <CHAPTER id="net-common-ethernet-driver-design">
46 <TITLE>Ethernet Driver Design</TITLE>
47 <PARA>Currently, the networking stack only supports ethernet based
49 <PARA>The network drivers use a two-layer design. One layer is
50 hardware independent and contains all the stack specific code.
51 The other layer is platform dependent and communicates with the
52 hardware independent layer via a very simple API. In this way,
53 hardware device drivers can actually be used with other stacks,
54 if the same API can be provided by that stack. We designed the
55 drivers this way to encourage the development of other stacks in
56 eCos while allowing re-use of the actual hardware specific code. </PARA>
57 <PARA>More comprehensive documentation of the ethernet device driver and
58 the associated API can be found in the generic ethernet device driver
60 <xref linkend="io-eth-drv-generic">
61 The driver and API is the same as the minimal debug stack used by
62 the RedBoot application. See the RedBoot documentation
66 <CHAPTER id="net-common-sample-code">
67 <TITLE>Sample Code</TITLE>
68 <PARA>Many examples using the networking support are provided.
69 These are arranged as eCos test programs, primarily for use in verifying
70 the package, but they can also serve as useful frameworks for program
71 design. We have taken a
72 <acronym>KISS</acronym>
73 approach to building programs which
74 use the network. A single include file
75 <<FILENAME>network.h</FILENAME>> is
76 all that is required to access the stack. A complete, annotated
77 test program can be found at
78 <FILENAME>net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests/ftp_test.c</FILENAME>,
79 with its associated files. </PARA>
81 <CHAPTER id="net-common-configuring-ip-addresses">
82 <TITLE>Configuring IP Addresses</TITLE>
83 <PARA>Each interface (“eth0” and “eth1”)
84 has independent configuration of its setup. Each can be set up
85 manually (in which case you must write code to do this), or by using
86 <acronym>BOOTP/DHCP</acronym>,
87 or explicitly, with configured values. If additional
88 interfaces are added, these must be configured manually.</PARA>
89 <PARA>The configurable values are: </PARA>
91 <LISTITEM><PARA>IP address</para></listitem>
92 <LISTITEM><PARA>netmask</para></listitem>
93 <LISTITEM><PARA>broadcast address</para></listitem>
94 <LISTITEM><PARA>gateway/router</para></listitem>
95 <LISTITEM><PARA>server address.</para></listitem>
97 <PARA>Server address is the DHCP server if applicable, but in addition,
98 many test cases use it as “the machine to talk to” in
99 whatever manner the test exercises the protocol stack.</PARA>
100 <PARA>The initialization is invoked by calling the C routine
102 void <function>init_all_network_interfaces</function>(void);
106 Additionally, if the system is configured to support IPv6 then each
107 interface may have an address assigned which is a composite of a 64 bit
108 prefix and the 32 bit IPv4 address for that interface.
109 The prefix is controlled by the CDL setting
110 CYGHWR_NET_DRIVER_ETH0_IPV6_PREFIX for “eth0”, etc.
111 This is a CDL booldata type, allowing this address to be suppressed if
115 <PARA>Alternatively, the system can configure its IPv6 address using
116 router solicitation. When the CDL option
117 CYGOPT_NET_IPV6_ROUTING_THREAD is enabled,
118 <function>init_all_network_interface</function> will start a thread which sends out router solicit messages, process router advertisements and thus configure an IPv6 address to the interface.</PARA>
121 Refer to the test cases,
122 <FILENAME>…/packages/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests/ftp_test.c</FILENAME>
123 for example usage, and the source files in
124 <FILENAME>…/packages/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/src/bootp_support.c</FILENAME>
126 <FILENAME>network_support.c</FILENAME>
127 to see what that call does.</PARA>
128 <PARA>This assumes that the MAC address (also known as
129 <acronym>ESA</acronym> or Ethernet Station Address)
130 is already defined in the
131 serial EEPROM or however the particular target implements this;
132 support for setting the MAC address is hardware dependent.</PARA>
133 <PARA>DHCP support is active by default, and there are configuration
134 options to control it. Firstly, in the top level of the
135 “Networking” configuration
136 tree, “Use full DHCP instead of BOOTP” enables
137 DHCP, and it contains an option to have the system provide a thread
138 to renew DHCP leases and manage lease expiry. Secondly, the individual
139 interfaces “eth0” and “eth1” each
140 have new options within the “Use BOOTP/DHCP to
141 initialize ‘<EMPHASIS>ethX</EMPHASIS>’” to
142 select whether to use DHCP rather than BOOTP.</PARA>
144 Note that you are completely at liberty to ignore this startup code and its
145 configuration in building your application.
146 <function>init_all_network_interfaces()</function>
147 is provided for three main purposes:
149 <LISTITEM><PARA>For use by Red Hat's own test programs.</para></listitem>
150 <LISTITEM><PARA>As an easy “get you going” utility for
151 newcomers to <productname>eCos</productname>.</para></listitem>
152 <LISTITEM><PARA>As readable example code from which further development
153 might start.</para></listitem>
156 If your application has different requirements for bringing up
157 available network interfaces, setting up routes, determining IP addresses
158 and the like from the defaults that the example code provides, you can
159 write your own initialization code to use whatever sequence of
160 <function>ioctl()</function> function
161 calls carries out the desired setup. Analogously, in larger systems,
162 a sequence of “ifconfig&rdquo invocations is used; these mostly
163 map to <function>ioctl()</function> calls to manipulate the state of
164 the interface in question.
167 <CHAPTER id="net-common-tests-and-demonstrations">
168 <TITLE>Tests and Demonstrations</TITLE>
169 <SECT1 id="net-common-loopback-tests">
170 <TITLE><!-- <xref> -->Loopback tests</TITLE>
171 <PARA>By default, only tests which can execute on any target
172 will be built. These therefore do not actually use external
173 network interfaces (though they may configure and initialize
174 them) but are limited to testing via the loopback
176 <PROGRAMLISTING><EMPHASIS>ping_lo_test</EMPHASIS> - ping test of the loopback address
177 <EMPHASIS>tcp_lo_select</EMPHASIS> - simple test of select with TCP via loopback
178 <EMPHASIS>tcp_lo_test</EMPHASIS> - trivial TCP test via loopback
179 <EMPHASIS>udp_lo_test</EMPHASIS> - trivial UDP test via loopback
180 <EMPHASIS>multi_lo_select</EMPHASIS> - test of multiple select() calls simultaneously</PROGRAMLISTING>
182 <SECT1 id="net-common-building-the-network-tests">
183 <TITLE>Building the Network Tests</TITLE>
184 <PARA>To build further network tests, ensure that the configuration
185 option CYGPKG_NET_BUILD_TESTS is set in your build
186 and then make the tests in the usual way. Alternatively
187 (with that option set) use
188 <PROGRAMLISTING>make -C net/common/<REPLACEABLE>VERSION</REPLACEABLE>/ tests </PROGRAMLISTING>
189 after building the eCos library, if you wish to build
190 <emphasis>only</emphasis>
191 the network tests.</PARA>
192 <PARA>This should give test executables in
193 <FILENAME>install/tests/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests</FILENAME>
195 the following:</PARA>
196 <PROGRAMLISTING><EMPHASIS>socket_test</EMPHASIS> - trivial test of socket creation API
197 <EMPHASIS>mbuf_test</EMPHASIS> - trivial test of mbuf allocation API
198 <EMPHASIS>ftp_test</EMPHASIS> - simple FTP test, connects to “server”
199 <EMPHASIS>ping_test</EMPHASIS> - pings “server” and non-existent host to test timeout
200 <EMPHASIS>dhcp_test</EMPHASIS> - ping test, but also relinquishes and
201 reacquires DHCP leases periodically
202 <EMPHASIS>flood</EMPHASIS> - a flood ping test; use with care
203 <EMPHASIS>tcp_echo</EMPHASIS> - data forwarding program for performance test
204 <EMPHASIS>nc_test_master </EMPHASIS>- network characterization master
205 <EMPHASIS>nc_test_slave </EMPHASIS>- network characterization slave
206 <EMPHASIS>server_test</EMPHASIS> - a very simple server example
207 <EMPHASIS>tftp_client_test</EMPHASIS> - performs a tftp get and put from/to “server”
208 <EMPHASIS>tftp_server_test</EMPHASIS> - runs a tftp server for a short while
209 <EMPHASIS>set_mac_address </EMPHASIS>- set MAC address(es) of interfaces in NVRAM
210 <EMPHASIS>bridge</EMPHASIS> - contributed network bridge code
211 <EMPHASIS>nc6_test_master </EMPHASIS>- IPv4/IPv6 network characterization master
212 <EMPHASIS>nc6_test_slave </EMPHASIS>- IPv4/IPv6 network characterization slave
213 <EMPHASIS>ga_server_test</EMPHASIS> - a very simple IPv4/IPv6 server example
216 <SECT1 id="net-common-standalone-tests">
217 <TITLE>Standalone Tests</TITLE>
218 <PROGRAMLISTING><EMPHASIS>socket_test</EMPHASIS> - trivial test of socket creation API
219 <EMPHASIS>mbuf_test</EMPHASIS> - trivial test of mbuf allocation API</PROGRAMLISTING>
220 <PARA>These two do not communicate over the net; they just perform
221 simple API tests then exit.</PARA>
222 <PROGRAMLISTING><EMPHASIS>ftp_test</EMPHASIS> - simple FTP test, connects to “server”</PROGRAMLISTING>
223 <PARA>This test initializes the interface(s) then connects to the
224 FTP server on the “server” machine for for each
225 active interface in turn, confirms that the connection was successful,
226 disconnects and exits. This tests interworking with the server.</PARA>
227 <PROGRAMLISTING><EMPHASIS>ping_test</EMPHASIS> - pings “server” and non-existent host to test timeout</PROGRAMLISTING>
228 <PARA>This test initializes the interface(s) then pings the server
229 machine in the standard way, then pings address “32 up” from
230 the server in the expectation that there is no machine there. This
231 confirms that the successful ping is not a false positive, and tests
232 the receive timeout. If there is such a machine, of course the
233 2nd set of pings succeeds, confirming that we can talk to a machine
234 not previously mentioned by configuration or by bootp. It then does
235 the same thing on the other interface, eth1.</PARA>
237 <PARA>If IPv6 is enabled, the program will also ping to the address it
238 last received a router advertisement from. Also a ping will be made to
239 that address plus 32, in a similar way the the IPv4 case.</PARA>
241 <PROGRAMLISTING><EMPHASIS>dhcp_test</EMPHASIS> - ping test, but also manipulates DHCP leases</PROGRAMLISTING>
242 <PARA>This test is very similar to the ping test, but in addition,
243 provided the network package is not configured to do this automatically,
244 it manually relinquishes and reclaims DHCP leases for all available
245 interfaces. This tests the external API to DHCP. See section below
246 describing this.</PARA>
247 <PROGRAMLISTING><EMPHASIS>flood</EMPHASIS> - a flood ping test; use with care</PROGRAMLISTING>
248 <PARA>This test performs pings on all interfaces as quickly as possible,
249 and only prints status information periodically. Flood pinging is
250 bad for network performance; so do not use this test on general
251 purpose networks unless protected by a switch.</PARA>
253 <SECT1 id="net-common-performance-test">
254 <TITLE>Performance Test</TITLE>
255 <PROGRAMLISTING><EMPHASIS>tcp_echo</EMPHASIS> - data forwarding program for performance test</PROGRAMLISTING>
256 <PARA><command>tcp_echo</command> is one
257 part of the standard performance test we use. The other parts are
258 host programs <LITERAL>tcp_source</LITERAL> and <LITERAL>tcp_sink</LITERAL>.
259 To make these (under your <emphasis>HOST</emphasis> system) cd to the tests source directory in
260 the eCos repository and type “<LITERAL>make -f make.host</LITERAL>” -
261 this should build <LITERAL>tcp_source</LITERAL> and <LITERAL>tcp_sink</LITERAL>.</PARA>
262 <PARA>The host program “<LITERAL>tcp_source</LITERAL>” sends
263 data to the target. On the target, “<LITERAL>tcp_echo</LITERAL>” sends
264 it onwards to “<LITERAL>tcp_sink</LITERAL>” running
265 on your host. So the target must receive and send on all the data that <LITERAL>tcp_source</LITERAL> sends
266 it; the time taken for this is measured and the data rate is calculated.</PARA>
267 <PARA>To invoke the test, first start <LITERAL>tcp_echo</LITERAL> on
268 the target board and wait for it to become quiescent - it will report
269 work to calibrate a CPU load which can be used to simulate real
270 operating conditions for the stack.</PARA>
271 <PARA>Then on your host machine, in one terminal window, invoke <LITERAL>tcp_sink</LITERAL> giving
272 it the IP address (or hostname) of one interface of the target board.
273 For example “<LITERAL>tcp_sink 10.130.39.66</LITERAL>”.
274 <LITERAL>tcp_echo</LITERAL> on the target
275 will print something like “<LITERAL>SINK connection
276 from 10.130.39.13:1143</LITERAL>” when <LITERAL>tcp_sink</LITERAL> is
277 correctly invoked.</PARA>
278 <PARA>Next, in another host terminal window, invoke <LITERAL>tcp_source</LITERAL>,
279 giving it the IP address (or hostname) of an interface of the target
280 board, and optionally a background load to apply to the target while
281 the test runs. For example, “<LITERAL>tcp_source
282 194.130.39.66</LITERAL>” to run the test with no
283 additional target CPU load, or “<LITERAL>tcp_source
284 194.130.39.66 85</LITERAL>” to load it up to 85% used.
285 The target load must be a multiple of 5. <LITERAL>tcp_echo</LITERAL> on
286 the target will print something like “<LITERAL>SOURCE
287 connection from 194.130.39.13:1144</LITERAL>” when
288 tcp_source is correctly invoked.</PARA>
289 <PARA>You can connect tcp_sink to one target interface
290 and tcp_source to another, or both to the same interface.
291 Similarly, you can run <LITERAL>tcp_sink</LITERAL> and <LITERAL>tcp_source</LITERAL> on
292 the same host machine or different ones. TCP/IP and ARP
293 look after them finding one another, as intended.</PARA>
294 <PROGRAMLISTING><EMPHASIS>nc_test_master</EMPHASIS> - network characterization master
295 <EMPHASIS>nc_test_slave</EMPHASIS> - network characterization slave</PROGRAMLISTING>
296 <PARA>These tests talk to each other to measure network performance.
297 They can each run on either a test target or a host computer
298 given some customization to your local environment. As provided, <literal>nc_test_slave</literal> must
299 run on the test target, and <literal>nc_test_master</literal> must
300 be run on a host computer, and be given the test target's
301 IP address or hostname.</PARA>
302 <PARA>The tests print network performance for various packet sizes
303 over UDP and TCP, versus various additional CPU loads on the target.</PARA>
305 The programs <PROGRAMLISTING><EMPHASIS>nc6_test_slave</EMPHASIS>
306 <EMPHASIS>nc6_test_master</EMPHASIS></PROGRAMLISTING>
307 are additional forms which support both IPv4 and IPv6 addressing.
310 <SECT1 id="net-common-interactive-tests">
311 <TITLE>Interactive Tests</TITLE>
312 <PROGRAMLISTING><EMPHASIS>server_test</EMPHASIS> - a very simple server example</PROGRAMLISTING>
313 <PARA>This test simply awaits a connection on port 7734 and after
314 accepting a connection, gets a packet (with a timeout of a few seconds)
315 and prints it. </PARA>
316 <PARA>The connection is then closed. We then loop to await the next
317 connection, and so on. To use it, telnet to the target on port 7734
318 then type something (quickly!)</PARA>
319 <screen>% telnet 172.16.19.171 7734
320 Hello target board</screen>
321 <PARA>and the test program will print something like:</PARA>
322 <screen>connection from 172.16.19.13:3369
323 buf = "Hello target board"</screen>
325 <PROGRAMLISTING><EMPHASIS>ga_server_test</EMPHASIS> - another very simple server example</PROGRAMLISTING>
326 <PARA>This is a variation on the <EMPHASIS>ga_server_test</EMPHASIS> test
327 with the difference being that it uses the <FUNCTION>getaddrinfo</FUNCTION>
328 function to set up its addresses. On a system with IPv6 enabled, it will
329 listen on port 7734 for a TCP connection via either IPv4 or IPv6.
332 <PROGRAMLISTING><EMPHASIS>tftp_client_test</EMPHASIS> - performs a tftp get and put from/to “server”</PROGRAMLISTING>
333 <PARA>This is only partially interactive. You need to set things
334 up on the “server” in order for this to work,
335 and you will need to look at the server afterwards to confirm that all
337 <PARA>For each interface in turn, this test attempts to read by
338 tftp from the server, a file called
339 <filename>tftp_get</filename>
341 prints the status and contents it read (if any). It then writes
342 the same data to a file called
343 <filename>tftp_put</filename>
345 the same server.</PARA>
346 <PARA>In order for this to succeed, both files must already exist.
347 The TFTP protocol does not require that a WRQ request _create_ a
348 file, just that it can write it. The TFTP server on Linux certainly
349 will only allow writes to an existing file, given the appropriate
350 permission. Thus, you need to have these files in place, with proper permission,
351 before running the test.</PARA>
352 <PARA>The conventional place for the tftp server to operate in LINUX
353 is /tftpboot/; you will likely need root privileges
354 to create files there. The data contents of
355 <filename>tftp_get</filename>
357 be anything you like, but anything very large will waste lots of
358 time printing it on the test’s stdout, and anything above
359 32kB will cause a buffer overflow and unpredictable failure.</PARA>
360 <PARA>Creating an empty tftp_put file (eg. by copying /dev/null
361 to it) is neatest. So before the test you should have something
363 <PROGRAMLISTING>-rw-rw-rw- 1 root 1076 May 1 11:39 tftp_get
364 -rw-rw-rw- 1 root 0 May 1 15:52 tftp_put </PROGRAMLISTING>
365 <PARA>note that both files have public permissions wide open. After
367 <filename>tftp_put</filename>
370 <filename>tftp_get</filename>.</PARA>
371 <PROGRAMLISTING>-rw-rw-rw- 1 root 1076 May 1 11:39 tftp_get
372 -rw-rw-rw- 1 root 1076 May 1 15:52 tftp_put
376 <PARA>If the configuration contains IPv6 support, the test program
377 will also use IPv6. It will attempt to put/get the files listed above
378 from the address it last received a routers solicit from.</PARA>
380 <PROGRAMLISTING><EMPHASIS>tftp_server_test</EMPHASIS> - runs a tftp server for a short while</PROGRAMLISTING>
381 <PARA>This test is truly interactive, in that you can use a standard
382 tftp application to get and put files from the server, during the
383 5 minutes that it runs. The dummy filesystem which underlies the
384 server initially contains one file, called “uu” which contains
385 part of a familiar text and some padding. It also accommodates
386 creation of 3 further files of up to 1Mb in size and names of up
387 to 256 bytes. Exceeding these limits will cause a buffer overflow
388 and unpredictable failure.</PARA>
389 <PARA>The dummy filesystem is an implementation of the generic API
390 which allows a true filesystem to be attached to the tftp server
391 in the network stack.</PARA>
392 <PARA>We have been testing the tftp server by running the test on
393 the target board, then using two different host computers connecting
394 to the different target interfaces, putting a file from each, getting
395 the “uu” file, and getting the file from the other computer.
396 This verifies that data is preserved during the transfer as well
397 as interworking with standard tftp applications.</PARA>
399 <SECT1 id="net-common-maintenance-tools">
400 <TITLE>Maintenance Tools </TITLE>
401 <PROGRAMLISTING><EMPHASIS>set_mac_address</EMPHASIS> - set MAC address(es) of interfaces in NVRAM</PROGRAMLISTING>
402 <PARA>This program makes an example <function>ioctl()</function> call
403 <acronym>SIOCSIFHWADDR</acronym>
404 “Socket IO Set InterFace HardWare ADDRess”
405 to set the MAC address on targets
406 where this is supported and enabled in the configuration. You must
407 edit the source to choose a MAC address and further edit it to allow
408 this very dangerous operation. Not all ethernet drivers support
409 this operation, because most ethernet hardware does not support
410 it — or it comes pre-set from the factory.
411 <emphasis>Do not use this program.</emphasis></PARA>
414 <CHAPTER id="net-common-support">
415 <title>Support Features</title>
416 <SECT1 id="net-common-tftp">
418 <PARA>The TFTP client and server are described in
419 <filename>tftp_support.h</filename>;
421 <PARA>The TFTP client has and new and an older, deprecated, API. The
422 new API works for both IPv4 and IPv6 where as the deprecated API is
426 The new API is as follows:
428 <PROGRAMLISTING>int tftp_client_get(const char * const filename,
429 const char * const server,
436 int tftp_client_put(const char * const filename,
437 const char * const server,
444 <PARA>Currently <varname>server</varname> can only be a numeric IPv4 or
445 IPv6 address. The resolver is currently not used, but it is planned to
446 add this feature (patches welcome). If <varname>port</varname> is zero
447 the client connects to the default TFTP port on the server. Otherwise
448 the specified port is used.
451 The deprecated API is:
453 int tftp_get(const char * const filename,
454 const struct sockaddr_in * const server,
460 int tftp_put(const char * const filename,
461 const struct sockaddr_in * const server,
469 The <varname>server</varname> should contain the address of the
470 server to contact. If the <varname>sin_port</varname> member of the
471 structure is zero the default TFTP port is used. Otherwise the
472 specified port is used.
475 Both API's report errors in the same way. The functions return a value
476 of -1 and <varname>*err</varname> will be set to one of the
480 #define TFTP_ENOTFOUND 1 /* file not found */
481 #define TFTP_EACCESS 2 /* access violation */
482 #define TFTP_ENOSPACE 3 /* disk full or allocation exceeded */
483 #define TFTP_EBADOP 4 /* illegal TFTP operation */
484 #define TFTP_EBADID 5 /* unknown transfer ID */
485 #define TFTP_EEXISTS 6 /* file already exists */
486 #define TFTP_ENOUSER 7 /* no such user */
487 #define TFTP_TIMEOUT 8 /* operation timed out */
488 #define TFTP_NETERR 9 /* some sort of network error */
489 #define TFTP_INVALID 10 /* invalid parameter */
490 #define TFTP_PROTOCOL 11 /* protocol violation */
491 #define TFTP_TOOLARGE 12 /* file is larger than buffer */
493 <PARA>If there are no errors the return value is the number of bytes
497 <PARA>The server is more complex. It requires a filesystem implementation
498 to be supplied by the user, and attached to the tftp server by means
499 of a vector of function pointers:</PARA>
500 <PROGRAMLISTING>struct tftpd_fileops {
501 int (*open)(const char *, int);
502 int (*close)(int);
503 int (*write)(int, const void *, int);
504 int (*read)(int, void *, int);
506 <PARA>These functions have the obvious semantics. The structure
507 describing the filesystem is an argument to the <function>tftpd_start</function>:
509 int tftp_start(int port,
510 struct tftpd_fileops *ops);
513 <PARA>The first argument is the port to use for the server. If this
514 port number is zero, the default TFTP port number will be used. The
515 return value from <function>tftpd_start</function> is a handle which
516 can be passed to <function>tftpd_stop</function>. This will kill the
517 tftpd thread. Note that this is not a clean shutdown. The thread will
518 simply be killed. <function>tftpd_stop</function> will attempt to
519 close the sockets the thread was listening on and free some of its
520 allocated memory. But if the thread was actively transferreing data at
521 the time <function>tftpd_stop</function> is called, it is quite likely
522 some memory and a socket will be leaked. Use this function with
523 caution (or implement a clean shutdown and please contribute the code
527 <PARA>There are two CDL configuration options that control how many
528 servers on how many different ports tftp can be
529 started. CYGSEM_NET_TFTPD_MULTITHREADED, when enabled, allows multiple
530 tftpd threads to operate on the same port number. With only one
531 thread, while the thread is active transferring data, new requests for
532 transfers will not be served until the active transfer is
533 complete. When multiple threads are started on the same port, multiple
534 transfers can take place simultaneous, up to the number of threads
535 started. However a semaphore is required to synchronise the
536 threads. This semaphore is required per port. The CDL option
537 CYGNUM_NET_TFTPD_MULTITHREADED_PORTS controls how many different port
538 numbers multithreaded servers can service.
540 <PARA>If CYGSEM_NET_TFTPD_MULTITHREADED is not enabled, only one
541 thread may be run per port number. But this removes the need for a
542 semaphore and so CYGNUM_NET_TFTPD_MULTITHREADED_PORTS is not required
543 and unlimited number of ports can be used. </PARA>
545 <PARA>It should be noted that the TFTPD does not perform any form of
546 file locking. When multiple servers are active, it is assumed the
547 underlying filesystem will refuse to open the same file multiple
548 times, operate correctly with simultaneous read/writes to the same
549 file, or if you are unlucky, corrupt itself beyond all repair.</PARA>
551 <PARA>When IPv6 is enabled the tftpd thread will listen for requests
552 from both IPv4 and IPv6 addresses.</PARA>
554 <PARA>As discussed in the description of the tftp_server_test
555 above, an example filesystem is provided in
556 <filename>net/common/<REPLACEABLE>VERSION</REPLACEABLE>/src/tftp_dummy_file.c</filename>
558 use by the tftp server test. The dummy filesystem is not a supported
559 part of the network stack, it exists purely for demonstration purposes.</PARA>
561 <SECT1 id="net-common-dhcp">
563 <PARA>This API publishes a routine to maintain DHCP state, and a
564 semaphore that is signalled when a lease requires attention: this
565 is your clue to call the aforementioned routine.</PARA>
566 <PARA>The intent with this API is that a simple DHCP client thread,
567 which maintains the state of the interfaces, can go as follows:
568 (after <function>init_all_network_interfaces()</function> is
569 called from elsewhere)</PARA>
570 <PROGRAMLISTING>while ( 1 ) {
572 cyg_semaphore_wait( &dhcp_needs_attention );
573 if ( ! dhcp_bind() ) // a lease expired
574 break; // If we need to re-bind
576 dhcp_halt(); // tear everything down
577 init_all_network_interfaces(); // re-initialize
579 <PARA>and if the application does not want to suffer the overhead
580 of a separate thread and its stack for this, this functionality
581 can be placed in the app’s server loop in an obvious fashion.
582 That is the goal of breaking out these internal elements. For example,
583 some server might be arranged to poll DHCP from time to time like
585 <PROGRAMLISTING>while ( 1 ) {
586 init_all_network_interfaces();
587 open-my-listen-sockets();
590 // sleeps if no connections, but not forever;
591 // so this loop is polled a few times a minute...
592 if ( cyg_semaphore_trywait( &dhcp_needs_attention )) {
593 if ( ! dhcp_bind() ) {
594 close-my-listen-sockets();
601 <PARA>If the configuration option CYGOPT_NET_DHCP_DHCP_THREAD
602 is defined, then eCos provides a thread as described initially.
603 Independent of this option, initialization of the interfaces still
604 occurs in <function>init_all_network_interfaces()</function> and
605 your startup code can call that. It will start the DHCP management
606 thread if configured. If a lease fails to be renewed, the management
607 thread will shut down all interfaces and attempt to initialize all
608 the interfaces again from scratch. This may cause chaos in the
609 app, which is why managing the DHCP state in an application aware
610 thread is actually better, just far less convenient for testing.</PARA>
612 <PARA>If the configuration option CYGOPT_NET_DHCP_OPTION_HOST_NAME
613 is defined, then the TAG_HOST_NAME DHCP option will be included
614 in any DHCP lease requests. The text for the hostname is set by
615 calling <function>dhcp_set_hostname()</function>. Any DHCP lease requests
616 made prior to calling <function>dhcp_set_hostname()</function> will not
617 include the TAG_HOST_NAME DHCP option. The configuration option
618 CYGNUM_NET_DHCP_OPTION_HOST_NAME_LEN controls the maximum length allowed
619 for the hostname. This permits the hostname text to be determined at
620 run-time. Setting the hostname to the empty string will have the effect
621 of disabling the TAG_HOST_NAME DHCP option.</PARA>
622 <PARA>If the configuration option CYGOPT_NET_DHCP_OPTION_DHCP_CLIENTID_MAC
623 is defined, then the TAG_DHCP_CLIENTID DHCP option will be included
624 in any DHCP lease requests. The client ID used will be the current
625 MAC address of the network interface.</PARA>
627 <PARA>The option CYGOPT_NET_DHCP_PARM_REQ_LIST_ADDITIONAL allows
628 additional DHCP options to be added to the request sent to the DHCP
629 server. This option should be set to a comma separated list of options.
632 <PARA> The option CYGOPT_NET_DHCP_PARM_REQ_LIST_REPLACE is similar to
633 CYGOPT_NET_DHCP_PARM_REQ_LIST_ADDITIONAL but in this case it
634 completely replaces the default list of options with the configured
635 set of comma separated options.</para>
638 &net-common-tcpip-manpages-sgml;
projects / karo-tx-redboot.git / blob