Accelerating Nios II Ethernet Applications
User Guide
Purpose
This user guide has been generated to provide you with a set of
instructions on how to use the hardware and software design files which
accompany the Accelerating Nios II Ethernet Applications application
note (AN440).
Table of contents
Accelerating Nios II Ethernet Applications User Guide................. 1
Purpose .............................................................. 1
Table of contents .................................................... 1
Prerequisites: ....................................................... 1
Example design contents: ............................................. 2
Benchmarking the system .............................................. 2
Benchmark application background .................................. 3
Setting up the system ............................................. 3
Running a benchmark session ....................................... 5
Building the benchmark application ................................... 7
Building the Nios II Application ..................................... 7
Setting up the hardware and software templates .................... 7
Building the software in the Nios II IDE .......................... 7
Building the workstation application .............................. 8
Using the fast packet memory optimization ............................ 9
Enabling the fast packet memory optimization ...................... 9
Using the C2H hardware checksum ..................................... 10
Enabling the hardware checksum ................................... 11
Examining the system hardware ....................................... 12
Appendix A. The benchmark application user interface ................ 13
Description ...................................................... 13
Application & command line arguments ............................. 13
Appendix B. The benchmark application source files .................. 16
Benchmark application construction ............................... 16
Source file hierarchy and information ............................ 16
Appendix C. Additional information and help ..................... 17
Prerequisites:
In order to use and rebuild this reference design, you must have the
following hardware and software tools:
Hardware tools
Workstation: A Windows or Linux workstation
Nios II development board: You must have a Nios II Stratix II ROHS
development board to immediately use these files. The design can be
migrated with some effort to the Nios II Cyclone II ROHS development
board, however, by following the instructions below.
Santa Cruz Connector “Marvell” 10/100/1000 Phy Card:
Software tools
Quartus II: Quartus II, version 9.0 or later
Megacore Library: Megacore library, version 9.0
Nios II EDS: Nios II EDS, version 9.0 or later
or later
Example design contents:
This reference design zip file contains a directory with the following
items:
 Readme.doc: This document.
 Pre-Generated Files (pre_generated directory):
o tse_optimized.sof : Nios II Stratix IIs60 ROHS FPGA image
o benchmark.elf : Nios II processor software binary file
o bm.exe : Windows workstation Cygwin benchmark application
 Hardware Project Files (tse_optimized directory): A Quartus II
hardware project which contains the design files for the Nios II
Stratix II ROHS development board. This hardware project file
contains a system with the following components:
o Nios II/f core (32K Instruction Cache, 32K Data Cache)
o System Timer
o FLASH Memory Component
o SSRAM Memory Component
o DDRAM Memory Component
o Triple Speed Ethernet (TSE) MAC w/
 Send Scatter Gather DMA Channel
 Receive Scatter Gather DMA Channel
o Hardware Checksum Component (Built by the C2H tool)
o Fast Packet Memory (MRAM block)
o Pipeline Bridge (used to isolate slower components)
All components in the system have been configured to run @
150MHz.
 Software Project Files (software directory): This folder
contains a directory called benchmark_source, which are the
source files for the benchmarking application program, and
another directory called workstation, which contains files needed
for compiling the benchmark program on the workstation machine.
This benchmarking application is provided in source form, written
in the C programming language.
Benchmarking the system
The hardware and software for this example design have been pre-built,
and are ready to run on a Windows workstation and on a Nios II Stratix
II ROHS board. The software image for the Nios II has been configured
to not use a DHCP server, and will default to an IP address of
137.57.235.80. You can change this system IP address to whatever IP
address you like by modifying the pound defines in the nios_init.h
source file.
#define
#define
#define
#define
IPADDR0
IPADDR1
IPADDR2
IPADDR3
137
57
235
80
Benchmark application background
Setting up the system
In order for this system to run correctly, you must decide how you wish
the Nios II system to resolve its IP address settings. One solution is
to allow the Nios II board to connect to a DHCP server to resolve its
networking settings, through a HUB or SWITCH. You can also turn of the
“Use DHCP” setting the Nichestack configuration and use the IP address
specified in nios_init.h. If you choose to use the DHCP service, but no
DHCP server is present on your network, the Nios II system will also
“time out” to the address specified in nios_init.h.
Hardware configuration
1) Verify that your Marvell Phy card is connected to the headers in
location J15, J16, and J17 of the Nios II Stratix II ROHS
development board.
2) Connect your PC to the Ethernet socket of the Marvell Phy card.
3) Connect you USB Blaster download cable from the workstation to
the JTAG->U62 connector on the development board.
4) Connect the Nios II’s power adapter to the development board.
Downloading the Nios II’s hardware and software
images
1) Start a Nios II Command Shell (From the Windows Workstation Start
menu, select Programs -> Altera -> Nios II EDS <version> -> Nios
II <version> Command Shell.
2) Change directories to folder containing the example design, and
enter the pre_generated directory.
3) We will now download the FPGA image to the board by entering the
following command:
> nios2-configure-sof NiosII_stratixII_2s60_RoHS_TSE_SGDMA.sof
This command will cause the FPGA image to be downloaded to the
Nios II development board through the USB Blaster programming
cable.
We will now download the Nios II processor’s software image to
the Nios II development board and start the processor’s
operation. To do this, type the following command:
> nios2-download –g benchmark.elf; nios2-terminal
The nios2-download command will take the Nios II processor’s
binary image file (ELF file) and will download it to the board.
You should see a series of messages indicating that the software
has been downloaded, and that the processor has begun code
execution. The nios2-terminal command will open up a terminal
connection to the NIos II processor’s JTAG UART peripheral,
enabling you to see the status messages being printed out by the
system. Once the Nios II processor begins executing the software,
you should see text which resembles the following:
[SOPC Builder]$ nios2-download -g benchmark.elf ; nios2-terminal
Using cable "USB-Blaster [USB-0]", device 1, instance 0x00
=============== Software License Reminder ================
This software project uses an unlicensed version of the NicheStack
TCP/IP
Network Stack - Nios II Edition. If you want to ship resulting object
code in your product, you must purchase a license for this software
from
Altera. For information go to: "http://www.altera.com/nichestack"
=====================================================
InterNiche Portable TCP/IP, v3.1
Copyright 1996-2008 by InterNiche Technologies. All rights reserved.
prep_tse_mac 0
Your Ethernet MAC address is 00:07:ed:ff:df:62
fooStatic IP Address is 137.57.235.80
prepped 1 interface, initializing...
[tse_mac_init]
INFO
: TSE MAC 0 found at address 0x08412000
INFO
: PHY Marvell 88E1111 found at PHY address 0x12 of MAC Group[0]
INFO
: PHY[0.0] - Automatically mapped to tse_mac_device[0]
INFO
: PHY[0.0] - Restart Auto-Negotiation, checking PHY link...
INFO
: PHY[0.0] - Auto-Negotiation PASSED
INFO
: PHY[0.0] - Checking link...
INFO
: PHY[0.0] - Link established
INFO
: PHY[0.0] - Speed = 1000, Duplex = Full
OK, x=4, CMD_CONFIG=0x00000000
MAC post-initialization: CMD_CONFIG=0x0400020b
[tse_sgdma_read_init] RX descriptor chain desc (1 depth) created
mctest init called
IP address of et1 : 137.57.235.80
Created "Inet main" task (Prio: 2)
Created "clock tick" task (Prio: 3)
Benchmark task starting up
> Created "benchmark task" task (Prio: 4)
4) In order to verify that the system is functional, we will now run
a series of ping commands from the workstation to the Nios II
board.
a. To do this, open a Windows command shell by clicking on the
Windows Start menu, and selecting the Run… option, which
will cause a Run window to be opened.
b. In the Open dialog box of the Run window, type the
following command: cmd.
c. In the command shell, issue the following command:
> ping <ip_address_of_the_NiosII_board>
(The IP address of the Nios II system will have been
printed out as one of the system messages, in the nios2terminal window, when the system started)
d. The ping command should execute without any problems, and
you should see output which resembles that as seen below:
C:\ >ping 137.57.235.80
Pinging 137.57.235.80 with 32 bytes of data:
Reply from 137.57.235.80: bytes=32 time<1ms TTL=64
Reply from 137.57.235.80: bytes=32 time<1ms TTL=64
Reply from 137.57.235.80: bytes=32 time<1ms TTL=64
Reply from 137.57.235.80: bytes=32 time<1ms TTL=64
Ping statistics for 137.57.235.80:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 0ms, Maximum = 0ms, Average = 0ms
Running a benchmark session
Now that we have verified that the Nios II system is operational, and
capable of being ‘pinged’ by the workstation, we can now perform a
benchmark measurement for the TCP throughput.
We have included a pre-compiled version of the workstation benchmark
program called bm.exe in the folder called pre_generated. This program
has been compiled for the Windows workstation utilizing the Cygwin
environment (installed with the Nios II EDS tool suite).
The user interface to the Ethernet benchmark application is commandline based, and is roughly the same between the Nios II system and the
workstation. To utilize the benchmark application, you first set up the
system which is going to receive the Ethernet data (receiver), followed
by setting up and starting the benchmark on the system which will be
transmitting the Ethernet data (transmitter). The transmitter will
begin sending data to the receiver (with the parameters specified by
the user), and after all the data has been sent, both the transmitter
and receiver will print out the average throughput for the test.
In this tutorial, we will provide you with a simple use case for the
benchmark program. More information on using and configuring the
benchmark program can be found in appendix A. at the end of this
document.
Workstation transmitting to the Nios II system
To conduct a benchmark test where the workstation is using the TCP
protocol to transmit data to the Nios II system, follow the steps
below:
1) Download the FPGA SOF and ELF image files, and open up a Nios II
terminal session to the Nios II system (described above, in the
Downloading the Nios II’s Hardware and Software Images section).
2) In the Nios II terminal, we will now enter the command to set it
up as the receiver for the TCP data. This is done by entering in
the following command at the prompt:
> bm –m :50 –p tcp –b 2000
This command has configured the Nios II system to become a TCP
receiver using port 50, and to use a receive buffer size of 2000
bytes. After entering this command, you should see output in the
Nios II terminal indicating that it has become the receiver for
the TCP test, which resembles the following:
----------------------------------------------------------- Test Role: Receiver
- Protocol: TCP
- Receiving at
:50
- Receive buffer size: 2000 bytes
----------------------------------------------------------3) We will now configure the workstation to become the TCP
transmitter for the test. To do this, open a Nios II Command
Shell and change directories to the pre_built directory
containing the bm.exe program.
4) At the command prompt, enter the following command:
> ./bm –m <ip_address_of_niosII_system>:50 –p tcp –b 1458
–d 100000000
[Note: Because of a bug in the system software, you may have to
hit the Enter key twice on your keyboard to get the Nios II
system to accept the command from the Nios II IDE software. This
problem does not occur when using the the Nios II command shell.]
This command has instructed the workstation
transmitter for the benchmark test, using a
1458 bytes to transmit 100,000,000 bytes of
attempt to send the data to a receiver with
<ip_address_of_niosII_system> at port 50.
to become a
send buffer size of
data. It will
an IP address of
[Note: Please replace the <ip_address_of_niosII_system> with the
actual IP address of your Nios II system (for example:
137.57.235.82).]
After issuing the command above, the benchmark test will begin
and will continuing running until the transmitter has sent all of
the data bytes to the receiver. During the test, you should
notice that the network activity lights on your workstation and
Nios II daughter card are active; however, there will be no
output on either the Nios II terminal, or Nios II Command Shell
windows, until the completion of the test.
When the test completes, a throughput message should be printed by both
the workstation and the Nios II system. The message printed should
resemble the one seen below:
----------------------------------------------------------- Test Role: Sender
- Protocol: TCP
- Sending to 137.57.235.80:50
- Send buffer size: 1458 bytes
--------------------------------------------------------------------------------------------------------------------- Test Role: Sender
- Protocol: TCP
- Status: Completed
- Total Bytes: 100000000
- Total Time: 6.900000 seconds
- Bits per second: 115.942024 Mbits/sec
- Total Packets: 68588
-----------------------------------------------------------
Nios II system transmitting to the workstation
Conducting a test where the Nios II system is the transmitter, and the
workstation is the receiver, is also very easy. To perform this test,
do the following:
1) To make the workstation the receiver, enter in the following
command in the Nios II Command Shell:
> ./bm –m :50 –p tcp –b 2000
2) In the Nios II terminal, we will now enter the command to set it
up as the receiver for the TCP data. This is done by entering in
the following command at the prompt:
> bm –m <ip_address_of_workstation>:50 –p tcp –b 1458
–d 100,000,000
Building the benchmark application
While a pre-canned design has been included for the Nios II Stratix II
ROHS development board, we have also included the hardware and software
design files for your use. We will now tell you how to re-build the
benchmark application for the system, as well as instruct you on how to
enable the fast packet memory and C2H hardware checksum optimizations.
Building the Nios II Application
Setting up the hardware and software templates
Before building the software project, we must copy the hardware project
files to the right locations on your workstation.
1) We will now copy the Quartus II hardware project files for the
tse_optimized design to a writeable location on your workstation.
Please copy the tse_optimized folder to a writeable location on
your system.
[Note: This step is optional. You do not need to perform this
step, however, any changes you make to your Quartus II project
file will modify the system.]
Building the software in the Nios II IDE
We will now build the benchmarking application using the Nios II IDE
environment.
1) In Nios II IDE, select File > New Nios II C/C++ Application
a. Select the Blank Project Template
2)
3)
4)
5)
6)
b. In the Name field, you can provide any name you wish or use
the default provided.
c. In the SOPC Builder System PTF File: text box, in the
“Select Target Hardware” section, click on the Browse…
button. Then select the PTF file for the system, located
in the tse_optimized folder. If you copied the hardware
project files to another location on your workstation,
please select this location instead.
d. Click the Next button.
e. Click the Finish button to create a new system library for
the design. You will see some activity as the project
files are setup.
f. Use the drag-and-drop functionality to include the
benchmark_source source code folder into your IDE prject.
Alternatively, you could simply copy the benchmark_source
folder into the project directory folder and do a refresh
for your project in the Nios II IDE.
We will now increase the system library’s optimization level to
be fully optmized (from –O0 to –O3). To do this, right click on
the system library project and select Properties.
In the Properties window, click on the C/C++ Build tab. Then in
the Configuration Settings pane, click on the General item. Then,
in the Optimizations Levels pull-down menu, select Optimize Most
(-03). Then, click OK to apply the settings.
Now we will configure the system library to include MicroC/OSII.
To do this, right click on the system library project and select
Properties. In the Properties window, click on the System Library
tab. Select “MicroC/OSII” for the RTOS field.
We also need to include the NicheStack networking stack into the
system library project. To do this, right click on the system
library project and select Properties. In the Properties window,
click on the System Library tab. Click on the “Software
Components…” tab. Then, click on the “NicheStack TCP/IP Stack”
and check “Add this software component”. Then, unclick the “Use
DHCP to automatically assign IP address” option to turn off DHCP.
We will now build the software project. To do this, right click
on the application project file and select the Build Project
option. This will now build the application files and system
library for the project.
[Note: You can also use the system library configuration gui for
modifying your run-time memory, as well as configure the NicheStack
Networking stack and MicroC/OS-II options.]
Building the workstation application
1) Open a Nios II Command Shell and change directories to the
location of the software project you created (above). To find
the exact location on the filesystem, right-click on the software
project name in the Nios II IDE and select Properties. The
location of the project will appear in the Info tab.
2) Change directories to the workstation directory.
3) Type the following command:
> make
This should result in an application being created called bm.exe,
which is the workstation benchmark application.
Using the fast packet memory optimization
The NicheStack networking stack uses two different memory queues for
sending and receiving networking packets, one for big packets and one
for smaller packets. When the networking stack, or a device driver,
needs to make use of this memory it uses the “memory queue” api to get,
and return, these memory buffers from the queue. The BB_ALLOC and
BB_FREE are used to manage the big memory buffers, and the LB_ALLOC and
LB_FREE are used to manage the small memory buffers.
#define BB_ALLOC(size)
#define BB_FREE(ptr)
#define LB_ALLOC(size)
#define LB_FREE(ptr)
npalloc(size) /* Big packet buffer alloc */
npfree(ptr)
npalloc(size) /* Little packet buffer alloc */
npfree(ptr)
In the standard implementation of the NicheStack networking stack, the
memory queue is constructed from the system’s heap memory via a series
of function calls which utilize the calloc memory allocation function.
The definitions for these function calls can be found in the source
file targnios.c (in the altera.components\Nios II Software
Packages\altera_iniche\UCOSII\src\nios2\) directory.
For this application note, we created an alternate method for
allocating these packet buffers from faster memory. More precisely, we
made use of a large, internal memory block found in the Stratix II FPGA
called the MRAM (64 Kbytes in size). This memory has the
characteristic of being accessed very quickly from the SOPC Builder
system, and therefore, is useful to speed up network packet operations.
We will now show you how to make use of the MRAM memory to increase the
speed of your packet operations.
Enabling the fast packet memory optimization
The Ethernet benchmark application template contains the source file to
enable use of the MRAM memory. The source file, called optimizations.c
is found in the nios2 directory for the benchmark project. In order to
use this optimization, perform the following steps:
1) Define the following macros in the ipport.h header file for the
system library (located in the Debug/system_description folder):
#define ALTERA_MRAM_FOR_PACKETS
#define ALTERA_MRAM_ALLOC_BASE
#define ALTERA_MRAM_ALLOC_SPAN
1
PACKET_MEMORY_BASE
PACKET_MEMORY_SPAN
2) We must now modify the memory allocation macros for the BB_ and
LB_ macros. To do this, locate the block of defined macros below
in ipport.h, and add in the red colored text:
#ifdef ALTERA_TRIPLE_SPEED_MAC
#if ALTERA_MRAM_FOR_PACKETS
#define BB_ALLOC(size)
ncpballoc(size)
#define BB_FREE(ptr)
ncpbfree(ptr)
#define LB_ALLOC(size)
ncpballoc(size)
#define LB_FREE(ptr)
#else
#define BB_ALLOC(size)
#define BB_FREE(ptr)
#define LB_ALLOC(size)
#define LB_FREE(ptr)
#endif
#else
#define BB_ALLOC(size)
#define BB_FREE(ptr)
#define LB_ALLOC(size)
#define LB_FREE(ptr)
#endif
ncpbfree(ptr)
ncpalloc(size) /* Big packet buffer alloc */
ncpfree(ptr)
ncpalloc(size) /* Little packet buffer alloc */
ncpfree(ptr)
npalloc(size) /* Big packet buffer alloc */
npfree(ptr)
npalloc(size) /* Little packet buffer alloc */
npfree(ptr)
3) The final step is to decrease the number
little buffers used by the stack because
64 Kbytes of memory. To do this, locate
macros below in ipport.h, and add in the
of big buffers and
the MRAM is limited to
the block of defined
red colored text:
#if ALTERA_MRAM_FOR_PACKETS
#define NUMBIGBUFS
30
#define NUMLILBUFS
30
/* some
#define
#define
#define
maximum packet buffer numbers */
MAXBIGPKTS
30
MAXLILPKTS
30
MAXPACKETS (MAXLILPKTS+MAXBIGPKTS)
#define
#define
#else
#define
#define
BIGBUFSIZE
LILBUFSIZE
1536
128
NUMBIGBUFS
NUMLILBUFS
30
30
/* some
#define
#define
#define
maximum packet buffer numbers */
MAXBIGPKTS
30
MAXLILPKTS
30
MAXPACKETS (MAXLILPKTS+MAXBIGPKTS)
#endif
4) After making these modifications, save the ipport.h configuration
file. The next time you rebuild the benchmark application, the
system library will be rebuilt, and the NicheStack networking
stack will make use of the MRAM for packet storage.
Using the C2H hardware checksum
The NicheStack software library needs a few modifications in order to
make the hardware checksum work. We must first modify the C source
file which implements the checksum selection logic, followed by copying
the C language checksum implementation into our application directory.
Enabling the hardware checksum
We must first modify the way that our hardware checksum routine will be
called. The current implementation flushes the contents of the Nios
II’s data cache (if present) every time the hardware checksum is
called, which can consume many processor cycles. In the case of the
TSE MAC design, flushing the data cache is totally unnecessary because
the memory used for Ethernet packet storage has been allocated as
uncached memory. Therefore, we can omit the function call to
alt_dcache_flush_all, which will greatly save on processor cycle
consumption in the system.
Instructions:
1) Open your system library project which contains the NicheStack
software library.
2) Navigate to the altera.components/Nios II Software
Packages/altera_iniche/UCOSII/src/misclib directory, and open the
file called cksum.c
In this file, locate the block of text (beginning around line
number 110) and comment out the alt_dcache_flush_all function (in
red):
#ifdef ALTERA_CKSUM
case 3:
//alt_dcache_flush_all();
return (alt_cksum((void *)((unsigned long)ptr & 0x7FFFFFFF),
count));
#endif
3) Save the cksum.c file.
Targeting the checksum with the C2H compiler
We will now use the C2H tool in the Nios II IDE to accelerate the C
version of the networking checksum. Performing this operation will
result in the C2H accelerated version of the checksum being created by
SOPC Builder, with the hardware image for the system being created by
the Quartus II software. Be warned, however, that this process can
take some time.
To do this, perform the following steps:
1) From your application project, open the benchmark_source folder
and open the file alt_cksum.c.
2) Highlight the function called alt_cksum with your mouse, and
right-click on it. From the menu that appears, select the option
Accelerate with the Nios II C2H Compiler. This should open a C2H
perspective at the bottom of the IDE.
3) In the C2H perspective, click on the + symbol to the left of the
project name. Select the radio button which is labeled
Build software, generate SOPC Builder system, and run Quartus II
compilation
4) We will now configure the alt_cksum C2H function to not flush the
data cache before being called. To do this, click on the +
symbol to the left of the function alt_cksum. Then, select the
radio button labeled
Use hardware accelerator in place of software implementation
5) We will now build perform the generation and building of the
accelerated system. To do this, right-click on your project in
the Nios II C/C++ Projects pane (left side of the IDE), and
select the Build Project option. This will compile the software
for the project, generate the C2H accelerator, and perform a
Quartus II hardware compilation. This process can take a large
about of time, varying from several minutes to about an hour, so
plan accordingly.
[Note: The C2H compiler can be configured through the use of #pragma
statements in the C source file for the accelerator. In the case of
the alt_cksum function, we have inserted a series of connect_variable
pragmas to reduce the number of connections between the generated C2H
hardware and the memories in the system, as follows:
#pragma altera_accelerate connect_variable alt_cksum/addr to ext_ssram_bus
#pragma altera_accelerate connect_variable alt_cksum/addr to packet_mem/s1
//#pragma altera_accelerate connect_variable alt_cksum/addr to ddr_sdram_0
These pragmas have the effect of limiting the connections between the
generated C2H hardware to the SSRAM and MRAM memories used for packet
storage, while omitting a connection to the DDR SDRAM memory. This was
done to ensure that the design is able to meet all the timing
requirements, and can operate properly at the clock frequency selected
for the system (150MHz). By commenting out the SSRAM and MRAM pragmas,
and uncommenting out the DDR SDRAM pragma, you can then test the case
of operation from DDR SDRAM- this will require a regeneration of the
C2H hardware accelerator.]
Selecting which checksum routine to use
The NicheStack networking stack enables you to select which checksum
routine you wish to use by setting a macro in the ipport.h
configuration file. By default, the Nios II assembly implementation
for the checksum is used in the system.
To make the NicheStack stack use the C2H version of the networking
checksum, perform the following steps:
1) Open up the ipport.h configuration file for your system library.
The ipport.h configuration file can be found in the Debug >
system_description folder, in the system library project.
2) In the ipport.h header file, add the following macro:
#define ALT_CKSUM
3) Save the ipport.h file.
The next time you rebuild the system library and benchmark application
in the Nios II IDE, the NicheStack networking library will make use of
the C2H hardware checksum.
Examining the system hardware
The system hardware used in this design can be found in the directory
tse_optimized. This directory contains a complete Quartus II project
for the TSE Optimized design referenced in the application note. If
you wish to examine this design in greater detail, or make
modifications to it, please perform the following steps:
1) Open up the Quartus II software.
2) In the File menu, select the Open Project... option, and select
the NiosII_stratixII_2s60_RoHS_TSE_SGDMA.qpf file. This will
open the project file.
3) To see what components are present in the system, select SOPC
Builder... from the Tools menu. This will open up the SOPC
Builder project file in the SOPC Builder editor.
Conclusion
We hope that this example design has helped to provide you with several
techniques for accelerating your own Nios II networking system.
Appendix A. The benchmark application user interface
Description
The network benchmark application has been constructed to be very
simple in its implementation. The sole function of this benchmark
application is to measure the effective transfer rate of data using the
TCP or UDP protocols.
Application & command line arguments
Name
bm – Altera Ethernet Benchmark Program
Synopsis
bm [-m target ip address: port] [-p protocol] [-b buffer size] [-d
total data size]
Description
The bm application is a simple benchmark utility for TCP and UDP
applications. The application has been designed to work on a
workstation, or a Nios II system with a Sockets compliant stack, and
will provide users with an averaged throughput benchmark result for
transferring data over Ethernet.
The bm application enables the system to be configured as a transmitter
or receiver of Ethernet data, using the TCP or UDP protocols.
Additional parameters for configuring the application can be specified
on the command line as arguments.
Options
The following options should be specified on the command line to
configure the application properly:
-m ip address of target system : port number
This flag specifies the test mode of the system. If the ip address of
target system parameter is not specified, then the system assumes the
receiver mode. Specifying the ip address of target system parameter
indicates that the system is a transmitter, and should use this
parameter as the IP address of the receiver. The port number parameter
indicates what port the transmitter or receiver should use for the
test, and should always be specified.
-p protocol for test
This command flag specifies what protocol should be used for the test.
The protocol for test parameter must be specified, and can only be set
to tcp or udp.
-b buffer size
This command flag specifies what Sockets buffer size should be used for
sending or receiving data. The buffer size parameter directly maps into
the buffer size for the Sockets TCP send and receive function calls
(when using the TCP protocol), or the sendto and receivefrom function
calls (when using the UDP protocol). Additionally, the buffer size
parameter cannot be omitted from the test.
-d total data transfer size
This command flag specifies the amount of data which should be sent by
the transmitter for the test, in bytes. The command flag is only set
by the transmitter, and the total data transfer size must be specified
in this case.
Nios II / workstation discrepancies
While the benchmark application has been constructed to run on both the
Nios II and a Windows/ Unix environment, the following discrepancies
should be noted:
 Command invocation: In the workstation environment, the
benchmark application is executed as a sub-process of the
shell. Therefore, it depends on the shell for
STDIN/STDOUT/STDERR services, and will respond to the normal
shell signals (i.e. CTL-C to terminate the application in the
Windows environment). In the Nios II environment, the
benchmark application makes use of the STDIN/STDOUT/STDERR
services provided by the HAL library, which in turn make use
of the nios2-terminal application.
 Internal Operation: In the workstation environment, the
application depends on operating system libraries and device
drivers for execution. On the Nios II system, the application
depends on the HAL system library and NicheStack networking
stack.
TCP vs. UDP measurements
While the benchmark application has been constructed to use either the
TCP or UDP protocols for transporting data, the performance results
reported for either protocol are radically different based on the
protocol selected.
In the case of using the TCP protocol for the benchmark test, it can be
guaranteed that all data transmitted by the transmitter has been
received by the receiver. By design, the TCP protocol guarantees the
in-order arrival of the data between the transmitter and the receiver.
Therefore, the performance numbers presented reflect an accurate
throughput measurement of how long it took to transport all the data
using the TCP protocol.
However, when selecting the UDP protocol for data transmission, there
is no guarantee that the all the data sent by the transmitter arrived
at the receiver. The transmitter will send the data as fast as
possible to the receiver, with no guarantees that the data arrived (and
no knowledge that the receiver is actually functional). The benchmark
application uses the UDP protocol verbatim, and therefore, makes no
assumptions about whether the data was received or not.
Therefore, when performing benchmarking operations with the UDP
protocol, you may note substantial discrepancies between the data rates
of the transmitter and the receiver. Additionally, the amount of data
received by the receiver may not match that sent by the transmitter.
Examples
The following examples show how to configure the system as a
transmitter or receiver in the benchmark application.
Nios II configured as a receiver
> bm –m :50 –p tcp –b 2000
Explanation: In this case the Nios II system has been configured to be
the receiver for the test. It will use port 50 to receive data via
TCP, and will use a buffer size of 2000 bytes (Sockets receive function
call) to process incoming data.
Nios II configured as a transmitter
> bm –m 137.57.235.82:50 –p tcp –b 2000 –d 100000000
Explanation: In this case the Nios II system has been configured to be
the transmitter for the test. It will use transmit data using the TCP
protocol to a system with an IP address of 137.57.235.82, attempting to
connect to port 50. It will transmit 100,000,000 bytes of data for this
test.
Workstation configured as a receiver
> ./bm –m :50 –p tcp –b 2000
Explanation: In this case the workstation has been configured to be the
receiver for the test. It will use port 50 to receive data via TCP,
and will use a buffer size of 2000 bytes (Sockets receive function
call) to process incoming data.
Workstation configured as a transmitter
> ./bm –m 137.57.235.80:50 –p tcp –b 1458
Explanation: In this case the workstation has been configured to be the
transmitter for the test. It will use transmit data using the TCP
protocol to a system with an IP address of 137.57.235.82, attempting to
connect to port 50. It will transmit 100,000,000 bytes of data for this
test.
Appendix B. The benchmark application source files
The source file structure for the benchmark application is explained
here, so that you can modifications to it in the future.
Benchmark application construction
The benchmark application has been structured to be compileable for the
Nios II processor and the workstation environments. The core
functionality of the benchmark application relies on the Sockets API
for its operation, and as such, the functionality between the
workstastion and the Nios II processor should be identical. The only
deviations between the two platforms, is as follows:
 Command Line UI: See the section Nios II/ Workstation
Discrepancies (Appendix A).
 Time management: The workstation makes use of the gettimeofday
function for timekeeping. The Nios II version makes use of
modified gettmieofday and settimeofday functions which “hook”
into the system clock timer (see source file
nios_time_routines.c).
 Threading: The workstation version operates as a shell
application in the Cygwin environment. The Nios II version
makes use of a thread resource from the MicroC/OS-II operating
system (see source file nios_init_rtos.c).
 MAC/ IP Address Assignment: The workstation version makes use
of system services for its IP and MAC address assignment,
which is transparent to the user. The Nios II version must
provide it’s MAC and IP address to the NicheStack networking
stack (see source file network_utilities.c and
network_utilities.h).
Source file hierarchy and information
The tables below list the source files used in the benchmark
application, their location in the source tree, and a description of
their purpose in the design.
Directory: benchmark_source
Source File
benchmark_console.h
benchmark_defines.h
benchmark.h
benchmark_console.c
benchmark.c
tcp_receiver.c
tcp_sender.c
udp_receiver.c
udp_sender.c
Description
Prototypes
Prototypes
prototypes and command/result structures
front end for benchmark console
logic for selecting benchmarks (udp, tcp, send,
recv); also contains command and result print
outs
core logic implementing the TCP receiver
core logic implementing the TCP sender
core logic implementing the UDP receiver
core logic implementing the UDP sender
Source File
alt_error_handler.h
network_utilities.h
nios_init.h
nios_time_routines.h
alt_cksum.c
alt_error_handler.c
network_utilities.c
nios_benchmark_driver.c
nios_init_rtos.c
nios_init_nortos.c
nios_time_routines.c
optimizations.c
Description
prototypes
prototypes
macros to set networking IP values
prototypes; also maps unix time calls to HAL
timer functions
networking checksum, optimized for use by the
C2H compiler
status messages for various error conditions
implements retrieval of MAC and IP addresses
for system
implements top level benchmark logic (i.e. UI)
program “main”; also implements threaded
version of the benchmark
program “main”; implements non-threaded
version of the benchmark; unsupported by
Altera
implements benchmark timekeeping routines
implements “fast packet memory” optimization
Directory: workstation
Source File
workstation_benchmark_driver.c
Makefile
Description
program “main” for workstation
Cygwin tested makefile
Appendix C. Additional information and help
For additional information, to ask questions, or provide feedback,
please visit the Nios Forum website (www.niosforum.com), or contact
your local Altera distributor or FAE.