A highly configurable and easily extendable TCP/IP-Stack with IPv4, IPv6, UDP, TCP, ICMPv4, ICMPv6 support. This network stack is written in C++/AspectC++ and because it is build and designed around the idea of aspects, you may select your desired functionallity during build time in a very fine grained way and on the same time the code retains maintainability.
The Aspect-IP-Stack is plattform agnostic and supports little and big endian systems. It has been tested
on x86 32-bit/x86 64-bit as well as arm 32-bit, msp430 16-bit and avr 8-bit processors
(Supported Platforms).
There are two examples of integrating the IP-Stack into operating systems for embedded systems (CiAO-OS and Chibi-OS) and another example of using it as a linux userspace application on a tun-device. The last one allows us to easily debug and measure the code and using test-driven development for an efficient and correct implementation.
If you already use the CMake buildsystem, integrating the IP-Stack is very easy and explained here. Use application aspects for easily interfere and modify the ipstack without having explicit APIs to all and every function of this software.
If you do not use CMake nor AspectC++ in your project you still have the option of building a static library with a plain C++ / C Integration API for using TCP and UDP sockets on IPv4/IPv6. You find well documented examples in the linux userspace integration directory.
Please use the ticket system of github for bugs and feature suggestions.
This software is NOT USABLE in its current state. TODO:
- Add linux userspace ipstack support via raw sockets or tun device.
- Add API for non-multitasking support
- Add API for management sockets in own task.
- Add build system parts for adding own aspects outside of the libipstack/src directory.
- Add documentation papers to /doc (e.g. APIs, example step-by-step).
- Highly configurable at build time
- BSD-like (event based) sockets API
- Own memory management for ressource restricted systems. We not not use the heap in the default configuration.
- Only thin interface to your OS/APP has to be provided, IRQ/Multitask safe
| Link-Layer | IP-Layer | Transport-Layer |
|---|---|---|
|
|
|
The configuration of this software is done by the kconfig tool, developted and used by the linux-kernel community. We're using a slightly modified version, the kconfig-frontends packet (http://ymorin.is-a-geek.org/projects/kconfig-frontends).
Building and execution of kconfig is integrated into the cmake buildsystem. It is even prepared for the case that you already using kconfig for your os or application.
After building this software you have a static library that either has the integration with your
app/os weaved in via aspects (see Aspect-oriented integration)
or provides a C++ / C Integration API.
You may obtain CMake for configuring the buildsystem at http://www.cmake.org.
Additionally you need the aspectc++ compiler from http://www.aspectc.org.
We only explain the graphical way of configuring the build system (cmake-gui), but you may also use
the command line version.
- Create a directory called "build" (or any other name).
- Start cmake-gui and select the top directory as source and the "build" directory as build directory.
- Click "configure".
- A popup will appear and ask for the target build system.
We assume you are using
makefor buildsystem project files.
You will be presented with some build options.
- "BUILD_ONLY_ONE_TASK" will disable multitask support and is discussed in the section below.
- "BUILD_WITH_ASPECTLESS_INTERFACE" will provide the pure, aspectless C++ / C Integration API.
If you are done with configuring the buildsystem click on "generate". Depending on your selection in the first popup you have VisualStudio project files, make files or something else in your build directory.
- Change to your build directory.
- Execute
make. This will download and build the kconfig-frontend and automatically open the configuration editor. - Configure the ipstack to your needs. Close the editor and save the changes.
- Execute
makeagain to build the examples if selected and the libipstack library.
If you want to reconfigure libipstack do this:
- Change to your build directory.
- Execute
make reconfigure. This will open the configuration editor. - Configure the ipstack to your needs. Close the editor and save the changes.
- Execute
makeagain to build the examples if selected and the libipstack library.
The ipstack is designed for multitasking systems. Usually there exists the system task where interaction with the hardware takes place and traffic is received. The second the user task where traffic is generated and consumed. Places where tasks are used: For example we do some busy-waiting while waiting for an arp or IPv6 neighbour response and for timing tcp traffic etc. Check out the CiAO-OS integration as an example: We reschedule before entering a busy loop to allow for a better usage of the remaining waiting time. We use the alarm/event support of the operating system to make the task sleep while waiting for the next packet or tcp timeout.
But we realize that on some very restricted systems multitasking support costs valuable space or uses limited ressources like timers. We therefore provide the "BUILD_ONLY_ONE_TASK" cmake option. What it does is:
- Adding an IP::periodic() method that has to be called periodically from your main loop.
- You need to check reachability before sending with IP::is_reachable(addr) because we no longer blocking the "application-task" while resolving link layer (e.g. ethernet) addresses.
Example: Look at integration/linux_userspace_without_aspects_multitask.
If your buildsystem is CMake based you just need to use add_subdirectory(aspect-oriented-ipstack) and make
your target depends on libipstack. Futher information can be found here.
This allows you to use aspects to weave in more complex integration like
using network cards capability of calculating checksums etc.
For other buildsystems you may prebuild the static library and just use it with the
aspectless C++ / C Integration API.
We provide some example applications and example integrations into projects/operating systems. These applications listed below aren't executable on their own without an integration.
http_simple_server: Provides a very simple http server. Only one page is returned and the http headers and content are statically compiled in.
icmp_test: Only the ip management subsystem is enabled. This application is for testing ICMPv4/v6, udp send/receive, tcp reset.
You can ping by using:
- ping 10.0.3.2 (for icmp ping, substitue with your configured IP)
- ping6 fe80::6655:44ff:fe33:2211%tap0 (for icmp ping with ipv6 on tap0 device)
- echoping -u 10.0.3.2 (for udp ping; use ipv4 addresses, ipv6 is not supported by echoping for udp)
- sendip -p ipv6 -p udp -us 5070 -ud 7 -d "Hello" -v fe80::6655:44ff:fe33:2211 (for ipv6 udp ping)
- telnet 10.0.3.2 (for testing the tcp reset capability; use ipv4 or ipv6 address)
- Send udp to port 88 to get it printed out
For full network interaction
- activate ipv6 forwarding: sysctl -w net.ipv6.conf.all.forwarding=1
- have an ipv6 capable router (or the "radvd" software)
tcp_speedtest: This application is for testing the TCP Speed.
It is in one of three states:
- listening for a command
- receiving a predetermined amount of data as fast as possible
- sending a predetermined amount of data as fast as possible
It opens a tcp listen socket on port 1234 and starts in the listen-for-a-command state. Commands:
- "LISTEN": The application sends back "OK" and is ready to receive 10241024100 Bytes (100 MByte) of data without further interpretation.
- "SEND": The application begins immediatelly to send 10241024100 Bytes (100 MByte) of random data.
In the directory "linux_host_program" is a linux host program located for measuring tcp performance. Usage: speedtest 10.0.3.2 1234 LISTEN or speedtest 10.0.3.2 1234 SEND.
telnet: Use the telnet application to test this example. An echo to every message is returned.
linux_userspace_with_aspects: In this example we're using aspects to tie the ipstack and the linux tun device together. Two threads are initialized. One is for receiving traffic and feeding the ipstack buffers and the other one is for the application for generating and consuming traffic. All application examples from above can be used with this type of integration.
linux_userspace_without_aspects: The same as above, but the application example, tun-device and threads are tied together without aspects. This example demonstrates how to compile the ipstack as a standalone static lib that can be used from outside by just using the api methods.
linux_userspace_without_aspects_multitask: This example demonstrates the usage of the ip-stack without using a multitask system. The main loop is responsible for routing incoming and outgoing traffic to and from the ipstack and at the same time provide the application layer. We show how to use the IP::periodic() and IP::is_reachable(...) methods.
ciao_os: The ipstack originated as a research project and extension of the CiAO operating system for embedded systems. Therefore support and maintainance are best for this integration. CiAO implements AutoSar Events and Alarms and is multitasking capable. Usually there exists the system task where traffic is received and the user task where traffic is generated and consumed. The integration features IRQ-safeness, reschedules instead of inefficent waits and task sleep if waiting for a packet.
chibi_os: To showcase the ability of integrating this piece of software into another system, we decided to extend chibi os by another ip-stack. Efficient multitasking support is implemented and the provided network drivers are used for an Arm 32Bit ENC28J60 based test board.
To understand the project structure we provide some documentation as markdown readme files
within the code tree and in the doc directory. A good starting point is here.
We tried to organize source files in an intuitive manner, for example if you're looking for a detail of the IPv4
implementation, your first try should be the ipv4 subdir. Design decisions are mainly explained in the
research papers linked at the bottom of this text (in german). The best way to collaborate
is to use github via forks and the issue tracker.
The buildsystem, example and integration code is licensed under the terms of the BSL 2-clause license. The ipstack source code is GPL3 licensed. Please be aware of the implication: Because this software is usally build as static library, your code have to be GPL3 compatible code.
This software originated as a research project at the University of Dortmund, Germany and has been created mainly by Christoph Borchert and David Gräff.