Network Stack Demos with the AC library

Introduction

To use networking, first perform network configuration using the System Config Tool to set up the network interface.

Overview

Name TCP server
Files so/ac/tcps.c so/ac/utl.c
Description This example demonstrates how to implement simple TCP server functionality using the socket library. The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
At this point, Cafe is ready to start using the socket library for data exchange. The example first initializes the socket library — SOInit.

The example creates a server thread that follows these steps.
  • Creates a server socket — SOSocket.
  • Binds the server socket to INADDR_ANY at port ECHO_SERVER_PORTSOBind.
  • Sets the maximum number of pending connections to ECHO_SERVER_BACKLOGSOListen.
  • Blocks in SOAccept and accepts a new connection from the remote client.
  • Blocks inSORecvFrom to receive data from the remote client.
  • Uses SOSendTo to send data that was received in the previous step.
  • Exits after the remote connection has either closed or was reset.
Setup
  • CAT-DEV v3 or later (a development unit acting as a TCP server).
  • Wireless AP (non-secure, DHCP server enabled).
  • Client machine (such as a Windows or UNIX computer).
  • Second CAT-DEV v3 or later (optional).

    Change the parameters in utl.h to match the wireless AP parameters (IP address, SSID, etc.) and recompile tcps.c. The client machine is set up such that it's connected to the AP either through a wireless or wired connection and can ping DEVICE_IP_ADDR (assigned by DHCP to the Cafe Wi-Fi interface ).

    Run the tcps program on Cafe.

    The quickest way to test is to run telnet <DEVICE_IP_ADDR> <ECHO_SERVER_PORT> from the client machine.

    The TCP echo client is available as a separate demo and it's possible to run it on a second CAT-DEV v3 or later instead of the client machine.

Name TCP client
Files so/ac/tcpc.c so/ac/utl.c
Description This example demonstrates how to implement simple TCP client functionality using the socket library. The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
At this point, Cafe is ready to start using the socket library for data exchange. The example first initializes the socket library — SOInit.

The example creates a server thread that follows these steps.
  • Creates a client socket — SOSocket
  • Connects to the server IP address at ECHO_SERVER_ADDR at port ECHO_SERVER_PORTSOConnect
  • After a connection is successful, it sends blocks of data to the server using SOSendTo.
  • The client thread exits after it has sent TRANSFER_SIZE of data to the server.
Setup
  • CAT-DEV v3 or later (a development unit acting as a TCP server).
  • Wireless AP (non-secure, DHCP server enabled).
  • Server machine (such as a Windows or UNIX computer).
  • Second CAT-DEV v3 or later (optional).

    Change the parameters in utl.h to match the wireless AP parameters (IP address, SSID, etc.) and recompile tcps.c. The server machine is set up such that it's connected to the AP either through a wireless or wired connection and can ping DEVICE_IP_ADDR (assigned by DHCP to the Cafe Wi-Fi interface).

    Run the tcpc program on Cafe.

    The quickest way to test is to enable the TCP echo service on the server machine and modify ECHO_SERVER_PORT in utl.h to match this service.

    The TCP echo server is available as a separate demo and it's possible to run it on a second CAT-DEV v3 or later instead of the client machine.

Name Resolver
Files so/ac/resolver.c so/ac/utl.c
Description This example demonstrates how to get a name from a dotted decimal address and how to get a dotted decimal address from a name. The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
At this point, Cafe is ready to start using the socket library for data exchange. The example first initializes the socket library — SOInit.

The example then follows these steps:
Setup
  • CAT-DEV v3 or later.
  • Wireless AP (non-secure, DHCP server enabled, must be connected to the internet).

    Change the parameters in utl.h to match the wireless AP parameters (IP address, SSID, etc.) and recompile resolver.c.

    Run the resolver program on Cafe.

Name Select
Files so/ac/select.c so/ac/utl.c
Description This example demonstrates how to implement simple TCP server functionality using the select function. The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
At this point, Cafe is ready to start using the socket library for data exchange. The example first initializes the socket library — SOInit.

The example creates a server thread that follows these steps:
  • Creates a server socket — SOSocket.
  • Binds the server socket to INADDR_ANY at port ECHO_SERVER_PORTSOBind.
  • Sets the maximum number of pending connections to ECHO_SERVER_BACKLOGSOListen.
  • Sets the socket to non-blocking mode — SOSetSockOpt.
  • Clears fd_set and adds the socket to fd_setFD_ZERO, FD_SET.
  • Blocks in SOSelect, after SOSelect returns and then checks the socket. The socket then becomes ready regardless of whether it is for an accept function with FD_ISSET.
  • Accepts a new connection from the remote client — SOAccept.
  • Closes the sockets and exits the server thread.
Setup
  • CAT-DEV v3 or later (a development unit acting as a TCP server).
  • Wireless AP (non-secure, DHCP server enabled).
  • A client machine (such as a Windows or UNIX computer).
  • A second CAT-DEV v3 or later (optional).

    Change the parameters in utl.h to match wireless AP parameters (IP address, SSID, etc.) and recompile select.c. the client machine is set up such that it's connected to the AP either through a wireless or wired connection and can ping DEVICE_IP_ADDR (assigned by DHCP to the Cafe Wi-Fi interface).

    Run select program on Cafe.

    The quickest way to test is to run telnet <DEVICE_IP_ADDR> <ECHO_SERVER_PORT> from the client machine.

    The TCP echo client is available as a separate demo and it's possible to run it on a second CAT-DEV v3 or later instead of on the client machine.

Name UDP Echo
Files so/ac/udpecho.c so/ac/utl.c
Description This example demonstrates how to implement simple UDP functionality and use buffers that are aligned with PPC cache line size for better performance (by avoiding internal buffer copying). The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
At this point, Cafe is ready to start using the socket library for data exchange. The example first initializes the socket library — SOInit.

It then implements the following.
  • Creates a server thread that follows these steps.
    • Allocates a read buffer that is aligned with PPC cache line size — MEMAllocFromDefaultHeapEx.
    • Creates a UDP socket — SOSocket.
    • Binds the server socket to INADDR_ANY at port UDP_ECHO_SERVER_PORTSOBind.
    • Signals that the server is ready.
    • Reads the incoming UDP packets with SORecvFrom and echoes them back to the sender with SOSendTo.
    • Closes the socket and exits the server thread.
  • Waits for the server to be ready and creates a client thread that follows these steps.
    • Allocates a read buffer that is aligned with PPC cache line size — MEMAllocFromDefaultHeapEx.
    • Creates a UDP socket — SOSocket.
    • Sends UDP packets to the server with SOSendTo and reads packets echoed by the server with SORecvFrom.
    • Closes the socket and exits the client thread.
Setup
  • CAT-DEV v3 or later (development unit).
  • Wireless AP (non-secure, DHCP server enabled).

    Change the parameters in utl.h to match the wireless AP parameters (IP address, SSID, etc.) and recompile udpecho.c.

    Run the udpecho program on Cafe.

Name CAT-DEV Speedtest
Files speedtest/catdev_speedtest.cpp speedtest/utl.cpp
Description This example demonstrates network performance between two CAT-DEVs by transferring a configurable amount of data between the machines and displaying throughput statistics. By default, internal send and receive buffers are increased to 64k but they can be reverted to their default sizes via the "#define ENABLE_LARGE_BUFFERS" command at the top of catdev_speedtest.cpp. For TCP, enabling window scaling can increase the buffer sizes to 128k, if "ENABLE_LARGE_BUFFERS" is enabled. TCP Window scaling is disabled by default but can be enabled via the "#define ENABLE_WINSCALE" command at the top of catdev_speedtest.cpp. This demo can perform a uni-directional transfer or a bi-directional transfer, i.e. the download and upload happen at the same time, depending on the command line arguments provided. Two CAT-DEVs are required. When initiating a bi-directional transfer, each CAT-DEV spawns two threads, one for sending and one for receiving, and establishes two separate connections with the opposite CAT-DEV. When initiating a uni-directional transfer, each CAT-DEV only spawns one thread, either to send or receive depending on the command line.

A connection is terminated when the specified amount of data has been sent, the max transfer duration value is reached, or an error occurs. It is possible to perform multiple tests(transfers) in the same program execution with different parameters. For this reason, the first parameter must be the number of transfers to perform. Parameter lists for each transfer are separated by '-n'. By default, if an IP address is provided but no other parameters are specified, the application will initiate a bi-directional transfer using TCP blocking sockets and send one MB with no max duration. If no IP address is provided, the test will be initiated as a uni-directional transfer acting as a receiver. Finally, subsequent tests will use the same parameters for the previous test unless a new value for that parameter is specified.
Usage: caferun [testCount] [ip] [options]
The only parameter that is mandatory for all configurations is [testCount]. [ip] is only mandatory if wishing to have your CAT-DEV operate as a sender in either a uni- or bi-directional transfer. [ip] is the IP address of the receiving CAT-DEV. If an IP address is specified for a test, all subsequent tests will use that same IP address unless a new one is specified. If desired, a different IP address can be specified for subsequent tests. If the '-r' switch is used for a subsequent test, the IP address will be ignored. All other parameters have default values.

Example 1:
CAT-DEV 1(192.168.1.1): "caferun 1 192.168.1.2 -s -d 52428800"
CAT-DEV 2(192.168.1.2): "caferun 1 -r"
Example 1 is a simple, working example of a uni-directional transfer. When the first command line above is entered on CAT-DEV 1, it will spawn a thread that will attempt to connect to the IP address 192.168.1.2(CAT-DEV 2) and send 50 MBs. When the second command line above is entered on CAT-DEV 2, it will spawn a thread that will listen for an incoming connection and receive data until the connection is closed by the sender.

Example 2:
CAT-DEV 1(192.168.1.1): "caferun 1 192.168.1.2 -d 52428800"
CAT-DEV 2(192.168.1.2): "caferun 1 192.168.1.1 -d 52428800"
Example 2 is a simple, working example of a bi-directional transfer. When the above command lines are entered on CAT-DEVs 1 and 2, respectively, each will establish a connection with the other and upload 50 MBs. Each CAT-DEV will be simultaneously uploading and downloading 50 MBs.

Example 3:
CAT-DEV 1: "caferun 3 192.168.1.2 -d 52428800 -n -p udp -d 104857600 -n 192.168.1.3 -s -n"
CAT-DEV 2: "caferun 2 192.168.1.1 -d 52428800 -n -p udp -d 10485760 -n"
CAT-DEV 3: "caferun 1 -p udp -r"
Example 3 is a somewhat complicated working example but demonstrates a large amount of the flexibility of this demo. The first command line, entered on CAT-DEV 1, will tell the application to run three tests. In the first test, CAT-DEV 1 will connect to IP address 192.168.1.2(CAT-DEV 2) over TCP and send 50 MBs. At the same time, CAT-DEV 1 will be receiving the amount of data specified by the command line entered on CAT-DEV 2(the second command line), which happens to be 50 MBs as well. It is not necessary that two CAT-DEVs send the same amount of data to each other. When both the download and upload are complete, the connection will be terminated and the second test will be initiated. The data amount specified for each test on each CAT-DEV is the number of bytes to upload. A given test is unaware of how many bytes it will receive as it will continue to download until the corresponding CAT-DEV has completed uploading.

The second test will reconnect CAT-DEV 1 to IP address 192.168.1.2(CAT-DEV 2) over UDP and send 100 MBs. At the same time, CAT-DEV 2 will have connected to IP address 192.168.1.1(CAT-DEV 1) and will be sending 10 MBs. Each connection will be terminated when the data transfer on that connection is complete. For of a bi-directional transfer, a test will not display throughput information until data transfer in both directions is complete, i.e. until both active connections on a single CAT-DEV are terminated. Throughput information will be displayed after each test is complete. So if multiple tests are specified, such as in this example, results will be viewed between each test.

For CAT-DEV 1 to be able to run the tests indicated, there must be a similar test specified on CAT-DEV 2. That is, in order for CAT-DEV 2 to receive the data being sent by CAT-DEV 1 over UDP, CAT-DEV 2 must also perform its second test over UDP. In this sense, the command lines for the two CAT-DEVs are paired. The first test on CAT-DEV 1 that connects to CAT-DEV 2 must use the same protocol as the first test on CAT-DEV 2 that connects to CAT-DEV 1, the second tests must do the same, and so on for all tests. The tests may differ in data amount and max transfer duration values.

When the second test completes, CAT-DEV 1 will then connect to 192.168.1.3(CAT-DEV 3) since a different IP address was specified for the third test. Because the third test contains a '-s' in its parameter list, the test will be initiated as a uni-directional test with CAT-DEV 1 acting as the sender. This is CAT-DEV 1's third test overall but the first test that is connecting to CAT-DEV 3. Similarly, it is CAT-DEV 3's first test connecting to CAT-DEV 1 so, as mentioned above, the protocols must match. The third test on CAT-DEV 1 inherits the parameters from the previous test. Although it is not specified in the command line, the third test is using UDP and sending 100 MBs with no max duration. The first test on CAT-DEV 3 is operating as receiver for CAT-DEV 1 and specifying UDP sockets.

Although the '-r' switch is included to specify that the test act solely as a receiver for CAT-DEV 1, it is enough to omit an IP address to act solely as a receiver. Remember that since an IP address will carry over to the next test, to have a test act solely as a receiver where a previous test(bi- or uni-) was acting as a sender, the '-r' switch must be specified. It should be emphasized that each parameter has a default value, except [testCount] and [ip], and that each parameter, excluding '-s' and '-r' switches but including [ip], will carry over to the following test, overriding the defaults where applicable.

This demo has multiple command line parameters as follows. Mandatory parameters are in brackets [ ].
WARNING:
If '-d 0' is used with the default duration of 0, the test will not terminate.
  • [testCount] : The number of transfers to perform before terminating the application. No default value.
    • Possible values: 1 - 10
  • ip : The IP address of the corresponding CAT-DEV. No default value for the first test.
    • IP address does apply to all subsequent tests
    • Although not technically mandatory, not specifying an IP address will cause a test to initiate as a uni-directional receiver, regardless of other parameters. A bi-directional transfer will not be performed.
  • -s : Perform a uni-directional transfer and send data
  • -r : Perform a uni-directional transfer and receive data
  • -p x : Specify a protocol to use where 'x' is the protocol. Defaults to tcp
    • Possible values: 'tcp', 'udp'
    • Ex: "-p tcp"
  • -d x : Specify how much data to send where x is the number of bytes. Defaults to 1048576(1 MB)
    • If passed 0, the program will continuously send data until the timeout is reached
    • Possible values: 0 to unsigned int max
    • Ex: "-d 104857600" for 100 megabytes
  • -t x : Specify how long, in seconds, to send data before terminating the connection
    • A value of 0 eliminates the max duration condition and the connection will terminate when all data has been sent
    • Possible values: 0 to unsigned int max
    • Ex: "-t 10"
  • -n : Mark the end of the list of parameters for the current transfer. The final '-n' is optional.
  • -h : Display help
Performance
Uni-directional TCP Send Results
Duration(seconds)204081
Amount Transferred(MB)50.00100.00200.00
Throughput(Mbps)20.97220.97220.713

Uni-directional TCP Recv Results
Duration(seconds)204081
Amount Transferred(MB)50.00100.00200.00
Throughput(Mbps)20.97220.97220.713

Uni-directional UDP Send Results
Duration(seconds)2551102
Amount Transferred(MB)50.00100.00200.00
Throughput(Mbps)16.77716.44816.448

Uni-directional UDP Recv Results
Duration(seconds)2651102
Amount Transferred(MB)50.00100.00200.00
Throughput(Mbps)16.13116.44816.448
Setup
  • Two CAT-DEV v3 or later (development unit).

    If initiating the demo on both CAT-DEVs from the same PC, run the catdev_speedtest program from the Multi Cafe environment. Otherwise, run the catdev_speedtest program on Cafe.

    For more information on running multiple CAT-DEVs from a single PC, see Multiple Devkit Feature.

Name ICMP
Files so/ac/icmp.c so/ac/utl.c
Description This example demonstrates how to use the SOIcmp API. The example first sets up networking using the AC library. The NetworkSetup function implements the following steps.
  • Initializes the AC library — nn::ac::Initialize.
  • Connect to the access point — nn::ac::Connect.
The program then performs the following.
Setup
  • CAT-DEV v3 or later (development unit).
  • In the initialization of the socket address, change the IP to the desired address.
  • Perform network configuration using System Config Tool to set up the network interface.
  • Run the icmp program on Cafe.

Name Socket buffer consumption check
Files so/ac/sockbuf_check.cpp
Description This example demonstrates how to check socket buffer consumption by the application. Do not export the code inside this demo program to the application. The purpose of this demo program is demonstrating the usage of SOLIB_OPT_SOCKBUF_CONSUMPTION with SOGetLibOpt. The code inside this demo is not suitable to any applications because server thread in this demo deliberately waits till the socket buffer gets full before it takes action which is NOT a recommended behavior

The example first initializes the socket library — SOInit. It then implements the following.
  • Creates THREAD_NUM number of server threads and each thread follows these steps.
    • Allocates a receive buffer that is aligned with PPC cache line size — MEMAllocFromDefaultHeapEx.
    • Creates a TCP socket — SOSocket.
    • Enables window-scaling — SOSetSockOpt.
    • Binds it to INADDR_ANY at port START_PORT+thread numberSOBind.
    • If the thread number is START_PORT-1, signals that servers are ready.
    • Waits a connection by a client — SOListen.
    • Accepts connection from a client — SOAccept.
    • Sets receive socket buffer size to 128KB — SOSetSockOpt.
    • It then goes into the main loop of the server thread and follows these steps.
      • First it goes into the loop which deliberately waits till the socket buffer gets full (by data sent by clients) which is NOT a recommended behavior but for demonstration.
        • Gets socket buffer consumption by the application — SOGetLibOpt.
        • When obtained consumption state is SO_SOCKBUF_CONSUMPTTION_HIGH or SO_SOCKBUF_CONSUMPTTION_MAX, or SOGetLibOpt is called 10 times, exits from this loop.
      • Reads data in socket receive buffer using SORecv till it gets SO_EWOULDBLOCK.
      • Goes back to the top of the server thread main loop.
      • Exits when the remote connection has closed.
  • Waits for servers to be ready then creates THREAD_NUM number of client threads and each thread follows these steps.
    • Allocates a send buffer that is aligned with PPC cache line size — MEMAllocFromDefaultHeapEx.
    • Creates a TCP socket — SOSocket.
    • Enables window-scaling and sets send socket buffer size to 128KB — SOSetSockOpt.
    • Connects to the server which is on LOOP_BACK (127.0.0.1) at port START_PORT+thread numberSOConnect.
    • After a connection is successful, it sends blocks of data to the server using SOSend every millisecond.
    • Each client thread retries to send data when it gets SO_EWOULDBLOCK or SO_ENOBUFS, exits after it has sent TOTAL_SEND of data to the server.
Setup
  • CAT-DEV (development unit).

    Run the sockbuf_check program on Cafe.

Revision History

2014/02/06 Added description for sockbuf_check.
2014/02/05 Added description for icmp.
2013/05/14 Added description for catdev_speedtest.
2013/01/23 Updates for System Config Tool.
2012/07/31 Cleanup pass.
2012/06/07 Initial version for the demo with AC library.
2011/12/16 Added description for udpecho.c.
2011/10/14 Modified description in setup section (added CAT-DEV v4).
2011/09/22 Added descriptions for resolver and select, modified description in setup section (removed CAT-DEV v2).
2011/08/16 Modified description in setup section (added CAT-DEV v3).
2011/02/21 Initial version.


CONFIDENTIAL