tcpip.sgml

ecos实时嵌入式操作系统

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     tcpip.sgml                                                  -->
<!--                                                                 -->
<!--     eCos TCP/IP Stacks                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART id="net-common-tcpip">
<TITLE>TCP/IP Stack Support for eCos</TITLE>
<PARTINTRO>
<PARA>
The Common Networking for <productname>eCos</productname> package
provides support for a complete TCP/IP networking stack.
The design allows for the actual stack to be modular and at the
current time two different implementations, one based on OpenBSD
from 2000 and a new version based on FreeBSD, are available.
The particulars of each stack implementation are presented in
separate sections following this top-level discussion.
</PARA>
</PARTINTRO>
<CHAPTER id="net-common-ethernet-driver-design">
<TITLE>Ethernet Driver Design</TITLE>
<PARA>Currently, the networking stack only supports ethernet based
networking. </PARA>
<PARA>The network drivers use a two-layer design.  One layer is
hardware independent and contains all the stack specific code. 
The other layer is platform dependent and communicates with the
hardware independent layer via a very simple API.  In this way,
hardware device drivers can actually be used with other stacks,
if the same API can be provided by that stack.  We designed the
drivers this way to encourage the development of other stacks in
eCos while allowing re-use of the actual hardware specific code. </PARA>
<PARA>More comprehensive documentation of the ethernet device driver and
the associated API can be found in the generic ethernet device driver
documentation
<xref linkend="io-eth-drv-generic">
The driver and API is the same as the minimal debug stack used by
the RedBoot application. See the RedBoot documentation
<xref linkend="redboot">
for further
information.</PARA>
</CHAPTER>
<CHAPTER id="net-common-sample-code">
<TITLE>Sample Code</TITLE>
<PARA>Many examples using the networking support are provided. 
These are arranged as eCos test programs, primarily for use in verifying
the package, but they can also serve as useful frameworks for program
design.  We have taken a
<acronym>KISS</acronym>
approach to building programs which
use the network.  A single include file
&lt;<FILENAME>network.h</FILENAME>&gt; is
all that is required to access the stack.  A complete, annotated
test program can be found at
<FILENAME>net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests/ftp_test.c</FILENAME>,
with its associated files.     </PARA>
</CHAPTER>
<CHAPTER id="net-common-configuring-ip-addresses">
<TITLE>Configuring IP Addresses</TITLE>
<PARA>Each interface (&ldquo;eth0&rdquo; and &ldquo;eth1&rdquo;)
has independent configuration of its setup.  Each can be set up
manually (in which case you must write code to do this), or by using
<acronym>BOOTP/DHCP</acronym>,
or explicitly, with configured values. If additional
interfaces are added, these must be configured manually.</PARA>
<PARA>The configurable values are: </PARA>
<itemizedlist>
<LISTITEM><PARA>IP address</para></listitem>
<LISTITEM><PARA>netmask</para></listitem>
<LISTITEM><PARA>broadcast address</para></listitem>
<LISTITEM><PARA>gateway/router</para></listitem>
<LISTITEM><PARA>server address.</para></listitem>
</itemizedlist>
<PARA>Server address is the DHCP server if applicable, but in addition,
many test cases use it as &ldquo;the machine to talk to&rdquo; in
whatever manner the test exercises the protocol stack.</PARA>
<PARA>The initialization is invoked by calling the C routine   
<PROGRAMLISTING>
void <function>init_all_network_interfaces</function>(void);
</PROGRAMLISTING>
</PARA>
<PARA>
Additionally, if the system is configured to support IPv6 then each
interface may have an address assigned which is a composite of a 64 bit
prefix and the 32 bit IPv4 address for that interface.
The prefix is controlled by the CDL setting 
CYGHWR_NET_DRIVER_ETH0_IPV6_PREFIX for &ldquo;eth0&rdquo;, etc.
This is a CDL booldata type, allowing this address to be suppressed if
not desired.
</PARA>
<PARA>
Refer to the test cases,
<FILENAME>&hellip;/packages/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests/ftp_test.c</FILENAME>
for example usage, and the source files in
<FILENAME>&hellip;/packages/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/src/bootp_support.c</FILENAME>
and
<FILENAME>network_support.c</FILENAME>
to see what that call does.</PARA>
<PARA>This assumes that the MAC address (also known as 
<acronym>ESA</acronym> or Ethernet Station Address)
is already defined in the
serial EEPROM or however the particular target implements this;
support for setting the MAC address is hardware dependent.</PARA>
<PARA>DHCP support is active by default, and there are configuration
options to control it.  Firstly, in the top level of the
&ldquo;Networking&rdquo; configuration
tree, &ldquo;Use full DHCP instead of BOOTP&rdquo; enables
DHCP, and it contains an option to have the system provide a thread
to renew DHCP leases and manage lease expiry. Secondly, the individual
interfaces &ldquo;eth0&rdquo; and &ldquo;eth1&rdquo; each
have new options within the &ldquo;Use BOOTP/DHCP to
initialize &lsquo;<EMPHASIS>ethX</EMPHASIS>&rsquo;&rdquo; to
select whether to use DHCP rather than BOOTP.</PARA>
<para>
Note that you are completely at liberty to ignore this startup code and its
configuration in building your application.
<function>init_all_network_interfaces()</function>
is provided for three main purposes:
<itemizedlist>
<LISTITEM><PARA>For use by Red Hat's own test programs.</para></listitem>
<LISTITEM><PARA>As an easy &ldquo;get you going&rdquo; utility for
newcomers to <productname>eCos</productname>.</para></listitem>
<LISTITEM><PARA>As readable example code from which further development
might start.</para></listitem>
</itemizedlist>
</para><para>
If your application has different requirements for bringing up 
available network interfaces, setting up routes, determining IP addresses
and the like from the defaults that the example code provides, you can
write your own initialization code to use whatever sequence of
<function>ioctl()</function> function
calls carries out the desired setup.  Analogously, in larger systems,
a sequence of &ldquo;ifconfig&rdquo invocations is used; these mostly
map to <function>ioctl()</function> calls to manipulate the state of
the interface in question.
</para>
</CHAPTER>
<CHAPTER id="net-common-tests-and-demonstrations">
<TITLE>Tests and Demonstrations</TITLE>
<SECT1 id="net-common-loopback-tests">
<TITLE><!-- <xref> -->Loopback tests</TITLE>
<PARA>By default, only tests which can execute on any target
	  will be built. These therefore do not actually use external
	  network interfaces (though they may configure and initialize
	  them) but are limited to testing via the loopback
	  interface.</PARA>
<PROGRAMLISTING><EMPHASIS>ping_lo_test</EMPHASIS> - ping test of the loopback address 
<EMPHASIS>tcp_lo_select</EMPHASIS> - simple test of select with TCP via loopback 
<EMPHASIS>tcp_lo_test</EMPHASIS> - trivial TCP test via loopback 
<EMPHASIS>udp_lo_test</EMPHASIS> - trivial UDP test via loopback 
<EMPHASIS>multi_lo_select</EMPHASIS> - test of multiple select() calls simultaneously</PROGRAMLISTING>
</SECT1>
<SECT1 id="net-common-building-the-network-tests">
<TITLE>Building the Network Tests</TITLE>
<PARA>To build further network tests, ensure that the configuration
option CYGPKG_NET_BUILD_TESTS is set in your build
and then make the tests in the usual way.  Alternatively
(with that option set) use
<PROGRAMLISTING>make -C net/common/<REPLACEABLE>VERSION</REPLACEABLE>/ tests </PROGRAMLISTING>
after building the eCos library, if you wish to build
<emphasis>only</emphasis>
the network tests.</PARA>
<PARA>This should give test executables in
<FILENAME>install/tests/net/common/<REPLACEABLE>VERSION</REPLACEABLE>/tests</FILENAME>
including
the following:</PARA>
<PROGRAMLISTING><EMPHASIS>socket_test</EMPHASIS> - trivial test of socket creation API 
<EMPHASIS>mbuf_test</EMPHASIS> - trivial test of mbuf allocation API 
<EMPHASIS>ftp_test</EMPHASIS> - simple FTP test, connects to &ldquo;server&rdquo; 
<EMPHASIS>ping_test</EMPHASIS> - pings &ldquo;server&rdquo; and non-existent host to test timeout 
<EMPHASIS>dhcp_test</EMPHASIS> - ping test, but also relinquishes and
            reacquires DHCP leases periodically 
<EMPHASIS>flood</EMPHASIS> - a flood ping test; use with care 
<EMPHASIS>tcp_echo</EMPHASIS> - data forwarding program for performance test
<EMPHASIS>nc_test_master </EMPHASIS>- network characterization master
<EMPHASIS>nc_test_slave </EMPHASIS>- network characterization slave
<EMPHASIS>server_test</EMPHASIS> - a very simple server example
<EMPHASIS>tftp_client_test</EMPHASIS> - performs a tftp get and put from/to &ldquo;server&rdquo; 
<EMPHASIS>tftp_server_test</EMPHASIS> - runs a tftp server for a short while 
<EMPHASIS>set_mac_address </EMPHASIS>- set MAC address(es) of interfaces in NVRAM
<EMPHASIS>bridge</EMPHASIS> - contributed network bridge code
<EMPHASIS>nc6_test_master </EMPHASIS>- IPv4/IPv6 network characterization master
<EMPHASIS>nc6_test_slave </EMPHASIS>- IPv4/IPv6 network characterization slave
<EMPHASIS>ga_server_test</EMPHASIS> - a very simple IPv4/IPv6 server example
</PROGRAMLISTING>
</SECT1>
<SECT1 id="net-common-standalone-tests">
<TITLE>Standalone Tests</TITLE>
<PROGRAMLISTING><EMPHASIS>socket_test</EMPHASIS> - trivial test of socket creation API 
<EMPHASIS>mbuf_test</EMPHASIS> - trivial test of mbuf allocation API</PROGRAMLISTING>
<PARA>These two do not communicate over the net; they just perform
simple API tests then exit.</PARA>
<PROGRAMLISTING><EMPHASIS>ftp_test</EMPHASIS>      - simple FTP test, connects to &ldquo;server&rdquo;</PROGRAMLISTING>
<PARA>This test initializes the interface(s) then connects to the
FTP server on the &ldquo;server&rdquo; machine for for each
active interface in turn, confirms that the connection was successful,
disconnects and exits.  This tests interworking with the server.</PARA>
<PROGRAMLISTING><EMPHASIS>ping_test</EMPHASIS>      - pings &ldquo;server&rdquo; and non-existent host to test timeout</PROGRAMLISTING>
<PARA>This test initializes the interface(s) then pings the server
machine in the standard way, then pings address &ldquo;32 up&rdquo; from
the server in the expectation that there is no machine there.  This
confirms that the successful ping is not a false positive, and tests
the receive timeout.  If there is such a machine, of course the
2nd set of pings succeeds, confirming that we can talk to a machine
not previously mentioned by configuration or by bootp. It then does
the same thing on the other interface, eth1.</PARA>
<PROGRAMLISTING><EMPHASIS>dhcp_test</EMPHASIS>    - ping test, but also manipulates DHCP leases</PROGRAMLISTING>
<PARA>This test is very similar to the ping test, but in addition,
provided the network package is not configured to do this automatically,
it manually relinquishes and reclaims DHCP leases for all available
interfaces. This tests the external API to DHCP. See section below
describing this.</PARA>
<PROGRAMLISTING><EMPHASIS>flood</EMPHASIS>        - a flood ping test; use with care</PROGRAMLISTING>
<PARA>This test performs pings on all interfaces as quickly as possible,
and only prints status information periodically. Flood pinging is
bad for network performance; so do not use this test on general
purpose networks unless protected by a switch.</PARA>