Subversion Repositories openrisc_me

The Common Networking for eCos 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.

Currently, the networking stack only supports ethernet based

networking. 

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. 

More comprehensive documentation of the ethernet device driver and

the associated API can be found in the generic ethernet device driver

documentation

The driver and API is the same as the minimal debug stack used by

the RedBoot application. See the RedBoot documentation

for further

information.

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

KISS

approach to building programs which

use the network.  A single include file

<network.h> is

all that is required to access the stack.  A complete, annotated

test program can be found at

net/common/VERSION/tests/ftp_test.c,

with its associated files.     

Each interface (“eth0” and “eth1”)

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

BOOTP/DHCP,

or explicitly, with configured values. If additional

interfaces are added, these must be configured manually.

The configurable values are: 

IP address

netmask

broadcast address

gateway/router

server address.

Server address is the DHCP server if applicable, but in addition,

many test cases use it as “the machine to talk to” in

whatever manner the test exercises the protocol stack.

The initialization is invoked by calling the C routine

void init_all_network_interfaces(void);

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 “eth0”, etc.

This is a CDL booldata type, allowing this address to be suppressed if

not desired.

Refer to the test cases,

…/packages/net/common/VERSION/tests/ftp_test.c

for example usage, and the source files in

…/packages/net/common/VERSION/src/bootp_support.c

and

network_support.c

to see what that call does.

This assumes that the MAC address (also known as

ESA 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.

DHCP support is active by default, and there are configuration

options to control it.  Firstly, in the top level of the

“Networking” configuration

tree, “Use full DHCP instead of BOOTP” 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 “eth0” and “eth1” each

have new options within the “Use BOOTP/DHCP to

initialize ‘ethX’” to

select whether to use DHCP rather than BOOTP.

Note that you are completely at liberty to ignore this startup code and its

configuration in building your application.

init_all_network_interfaces()

is provided for three main purposes:

For use by Red Hat's own test programs.

As an easy “get you going” utility for

newcomers to eCos.

As readable example code from which further development

might start.

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

ioctl() function

calls carries out the desired setup.  Analogously, in larger systems,

a sequence of “ifconfig&rdquo invocations is used; these mostly

map to ioctl() calls to manipulate the state of

the interface in question.

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.

ping_lo_test - ping test of the loopback address

tcp_lo_select - simple test of select with TCP via loopback

tcp_lo_test - trivial TCP test via loopback

udp_lo_test - trivial UDP test via loopback

multi_lo_select - test of multiple select() calls simultaneously

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

make -C net/common/VERSION/ tests 

after building the eCos library, if you wish to build

only

the network tests.

This should give test executables in

install/tests/net/common/VERSION/tests

including

the following:

socket_test - trivial test of socket creation API

mbuf_test - trivial test of mbuf allocation API

ftp_test - simple FTP test, connects to “server”

ping_test - pings “server” and non-existent host to test timeout

dhcp_test - ping test, but also relinquishes and

            reacquires DHCP leases periodically

flood - a flood ping test; use with care

tcp_echo - data forwarding program for performance test

nc_test_master - network characterization master

nc_test_slave - network characterization slave

server_test - a very simple server example

tftp_client_test - performs a tftp get and put from/to “server”

tftp_server_test - runs a tftp server for a short while

set_mac_address - set MAC address(es) of interfaces in NVRAM

bridge - contributed network bridge code

nc6_test_master - IPv4/IPv6 network characterization master

nc6_test_slave - IPv4/IPv6 network characterization slave

ga_server_test - a very simple IPv4/IPv6 server example

socket_test - trivial test of socket creation API

mbuf_test - trivial test of mbuf allocation API

These two do not communicate over the net; they just perform

simple API tests then exit.

ftp_test      - simple FTP test, connects to “server”

This test initializes the interface(s) then connects to the

FTP server on the “server” machine for for each

active interface in turn, confirms that the connection was successful,

disconnects and exits.  This tests interworking with the server.

ping_test      - pings “server” and non-existent host to test timeout

This test initializes the interface(s) then pings the server

machine in the standard way, then pings address “32 up” 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.

dhcp_test    - ping test, but also manipulates DHCP leases

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.

flood        - a flood ping test; use with care

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.

tcp_echo      - data forwarding program for performance test

tcp_echo is one

part of the standard performance test we use.  The other parts are

host programs tcp_source and tcp_sink.

 To make these (under LINUX) cd to the tests source directory in

the eCos repository and type “make -f make.linux” -

this should build tcp_source and tcp_sink.

The LINUX program “tcp_source” sends

data to the target.  On the target, “tcp_echo” sends

it onwards to “tcp_sink” running

on LINUX.  So the target must receive and send on all the data that tcp_source sends

it; the time taken for this is measured and the data rate is calculated.

To invoke the test, first start tcp_echo on

the target board and wait for it to become quiescent - it will report

work to calibrate a CPU load which can be used to simulate real

operating conditions for the stack.

Then on your LINUX machine, in one terminal window, invoke tcp_sink giving

it the IP address (or hostname) of one interface of the target board.

 For example “tcp_sink 10.130.39.66”.

 tcp_echo on the target

will print something like “SINK connection

from 10.130.39.13:1143” when tcp_sink is

correctly invoked.

Next, in another LINUX terminal window, invoke tcp_source,

giving it the IP address (or hostname) of an interface of the target

board, and optionally a background load to apply to the target while

the test runs.  For example, “tcp_source

194.130.39.66” to run the test with no

additional target CPU load, or “tcp_source

194.130.39.66 85” to load it up to 85% used.

 The target load must be a multiple of 5.  tcp_echo on

the target will print something like “SOURCE

connection from 194.130.39.13:1144” when

tcp_source is correctly invoked.

You can connect tcp_sink to one target interface

and tcp_source to another, or both to the same interface.

 Similarly, you can run tcp_sink and tcp_source on

the same LINUX machine or different ones.  TCP/IP and ARP

look after them finding one another, as intended.

nc_test_master - network characterization master

nc_test_slave - network characterization slave

These tests talk to each other to measure network performance.

They can each run on either a test target or a LINUX host computer

given some customization to your local environment. As provided, nc_test_slave must

run on the test target, and nc_test_master must

be run on a LINUX host, and be given the test target's

IP address or hostname.

The tests print network performance for various packet sizes

over UDP and TCP, versus various additional CPU loads on the target.

The programs nc6_test_slave

nc6_test_master

are additional forms which support both IPv4 and IPv6 addressing.

server_test - a very simple server example

This test simply awaits a connection on port 7734 and after

accepting a connection, gets a packet (with a timeout of a few seconds)

and prints it. 

The connection is then closed. We then loop to await the next

connection, and so on. To use it, telnet to the target on port 7734

then type something (quickly!)

% telnet 172.16.19.171 7734

Hello target board

and the test program will print something like:

connection from 172.16.19.13:3369

buf = "Hello target board"

ga_server_test - another very simple server example

This is a variation on the ga_server_test test

with the difference being that it uses the getaddrinfo

function to set up its addresses.  On a system with IPv6 enabled, it will

listen on port 7734 for a TCP connection via either IPv4 or IPv6.

tftp_client_test - performs a tftp get and put from/to “server”

This is only partially interactive.  You need to set things

up on the “server” in order for this to work,

and you will need to look at the server afterwards to confirm that all

was well.

For each interface in turn, this test attempts to read by

tftp from the server, a file called

tftp_get

and

prints the status and contents it read (if any).  It then writes

the same data to a file called

tftp_put

on

the same server.

In order for this to succeed, both files must already exist.

 The TFTP protocol does not require that a WRQ request _create_ a

file, just that it can write it.  The TFTP server on Linux certainly

will only allow writes to an existing file, given the appropriate

permission.  Thus, you need to have these files in place, with proper permission,

before running the test.

The conventional place for the tftp server to operate in LINUX

is /tftpboot/; you will likely need root privileges

to create files there. The data contents of

tftp_get

can

be anything you like, but anything very large will waste lots of

time printing it on the test’s stdout, and anything above

32kB will cause a buffer overflow and unpredictable failure.

Creating an empty tftp_put file (eg. by copying /dev/null

to it) is neatest.  So before the test you should have something

like:

-rw-rw-rw- 1 root        1076 May  1 11:39 tftp_get

-rw-rw-rw- 1 root        0 May  1 15:52 tftp_put 

note that both files have public permissions wide open.  After

running the test,

tftp_put

should

be a copy of

tftp_get.

-rw-rw-rw-  1 root       1076 May  1 11:39 tftp_get

-rw-rw-rw-  1 root       1076 May  1 15:52 tftp_put

tftp_server_test - runs a tftp server for a short while

This test is truly interactive, in that you can use a standard

tftp application to get and put files from the server, during the

5 minutes that it runs.  The dummy filesystem which underlies the

server initially contains one file, called “uu” which contains

part of a familiar text and some padding.  It also accommodates

creation of 3 further files of up to 1Mb in size and names of up

to 256 bytes.  Exceeding these limits will cause a buffer overflow

and unpredictable failure.

The dummy filesystem is an implementation of the generic API

which allows a true filesystem to be attached to the tftp server

in the network stack.

We have been testing the tftp server by running the test on

the target board, then using two different host computers connecting

to the different target interfaces, putting a file from each, getting

the “uu” file, and getting the file from the other computer.

 This verifies that data is preserved during the transfer as well

as interworking with standard tftp applications.

set_mac_address - set MAC address(es) of interfaces in NVRAM

This program makes an example ioctl() call

SIOCSIFHWADDR

“Socket IO Set InterFace HardWare ADDRess”

to set the MAC address on targets

where this is supported and enabled in the configuration. You must

edit the source to choose a MAC address and further edit it to allow

this very dangerous operation. Not all ethernet drivers support

this operation, because most ethernet hardware does not support

it — or it comes pre-set from the factory.

Do not use this program.

The TFTP client and server are described in

tftp_support.h;

the client API is simple and can be easily understood by reading

tftp_client_test.c.

The server is more complex.  It requires a filesystem implementation

to be supplied by the user, and attached to the tftp server by means

of a vector of function pointers:

struct tftpd_fileops {

             int (*open)(const char *, int);

             int (*close)(int);

             int (*write)(int, const void *, int);

             int (*read)(int, void *, int);

};

These functions have the obvious semantics.  The structure

describing the filesystem is an argument to the tftpd_start(int,

struct tftpd_fileops *); call.

 The first argument is the port to use for the server.

As discussed in the description of the tftp_server_test

above, an example filesystem is provided in

net/common/VERSION/src/tftp_dummy_file.c

for

use by the tftp server test.  The dummy filesystem is not a supported

part of the network stack, it exists purely for demonstration purposes.

This API publishes a routine to maintain DHCP state, and a

semaphore that is signalled when a lease requires attention: this

is your clue to call the aforementioned routine.

The intent with this API is that a simple DHCP client thread,

which maintains the state of the interfaces, can go as follows:

(after init_all_network_interfaces() is

called from elsewhere)

while ( 1 ) {

        while ( 1 ) {

            cyg_semaphore_wait( &dhcp_needs_attention );

            if ( ! dhcp_bind() ) // a lease expired

                break; // If we need to re-bind

        }

        dhcp_halt(); // tear everything down

        init_all_network_interfaces(); // re-initialize

}

and if the application does not want to suffer the overhead

of a separate thread and its stack for this, this functionality

can be placed in the app’s server loop in an obvious fashion.

 That is the goal of breaking out these internal elements.  For example,

some server might be arranged to poll DHCP from time to time like

this:

while ( 1 ) {

    init_all_network_interfaces();

    open-my-listen-sockets();

    while ( 1 ) {

       serve-one-request();

       // sleeps if no connections, but not forever;

       // so this loop is polled a few times a minute...

       if ( cyg_semaphore_trywait( &dhcp_needs_attention )) {

             if ( ! dhcp_bind() ) {

                 close-my-listen-sockets();

                 dhcp_halt();

                 break;

             }

       }

    }

}

If the configuration option CYGOPT_NET_DHCP_DHCP_THREAD

is defined, then eCos provides a thread as described initially.

Independent of this option, initialization of the interfaces still

occurs in init_all_network_interfaces() and

your startup code can call that.  It will start the DHCP management

thread if configured.  If a lease fails to be renewed, the management

thread will shut down all interfaces and attempt to initialize all

the interfaces again from scratch.  This may cause chaos in the

app, which is why managing the DHCP state in an application aware

thread is actually better, just far less convenient for testing.

    &net-common-tcpip-manpages-sgml;