SIMA

Network node implementations

Current version is 0.90
CONTENTS:
  1. Introduction to SIMA

  2. Node implementations

  3. Some utilities

  4. Configuration guide and examples

1. Introduction to SIMA

SIMA stands for Simple Integrated Media Access and is a way to provide QoS (Quality of Service) using Differentiated Services. The main idea in SIMA is to let access nodes stamp the TOS (Type of Service) field in every IP packet before forwarding it to the core network that can provide QoS.

Rest of the documentation and more detailed information can be downloaded from the official SIMA homepage.

The network node implementations are built in the Linux Traffic Control (DiffServ on Linux) framework, inside the Linux kernel.



2. Node implementations

Both of these node iplementations are under development and have been implemented into the Linux operating system. We are developing them under the newest stable kernels (2.2.x series), but propably will not merge them to the default distribution - at least not yet. In other words, you'll have to get the source code for the appropriate kernel version and apply the patch to it. After that you will be able to configure and compile the kernel with SIMA support. You need also some patched tools to operate the SIMA system (read the Chapter 3).

The reason to this kind of operation obvious: the code is more or less experimental. In other words - we can not give you any guarantees.

NEWS and VERSION HISTORY:


2.1 Requirements


2.2 Core node

The main function of core node is to schedule and buffer packets before transmission. The scheduler can drop incoming packets that do not have sufficient precedence level (DSCP) in the IP-headers TOS-field at the moment. The precedence level is marked by the access nodes that lie on the edges of the SIMA ("Differentiated Services") network.

Special features:

This implementation allows the core node operate with either packet based or byte based queue sizes. See Chapter 4 for configuration examples.

Core node should support now also most of the network interfaces. However only Ethernet and CIP (with both SVC and PVC connections) have been tested.

The new feature allows user to define the DPa table from 2 different tables - 12x12 and 24x24. This table can be chosen only during "queue" initialization/installation. It can not be changed with "tc qdisc change ..." command.

It has also 2 different filetypes under the proc filesystem. The availability of these special files depends on the given kernel configuration options. The core node specific files are:

/proc/net/sima =
Collects summary/counter information for each queue.
/proc/net/sima_<int> =
Collects statistics for the queue attached to the interface <int>. Read the sima documentation file (...linux/Documentation/networking/sima.txt) for more info and look to the Chapter 4 for proc file reading utility (logger.c).


2.3 Access node

The main tasks of access node include flow recognition, flow measuring and packet marking. Flows can be recognized by the 5-tuple and this implementation exploits the firewalling code in the Linux kernel. Flows are measured either with the "rate estimator" or with the hand-made piece of assembler code. Then the packet is stamped with the correct precedence value (into the TOS field) before forwarding.

Access node can process the RT flag in three different modes:

New SPECIAL EDGE mode allows access node to stamp packets from table, that is configurable by user. The table can hold upto 4096 different values and it loops when the end-of-file is reached. This allows user to assign pre-defined DP values (e.g. with statistical distribution) for processed packets.

This implementation is still in the beta stage, so no more implementation specific information is (yet) available.


2.4 Installation guide

  1. Download and install the kernel source code
  2. Read the kernel documentation and upgrade/install required programs
  3. Download the patch: sima-0.90.patch.gz
  4. Uncompress the patch file with gunzip.
  5. Apply the patch with following steps. 
        # cd /usr/src/linux (or wherever the new kernel is)
    # patch -p1 < [/path/to/the]/sima-0.90.patch
  6. After the patch has been applied you can read the implementation documentation from .../linux/Documentation/networking/sima.txt .
  7. Configure the kernel 
        # make xconfig (or "make menuconfig" or "make config")


    *** Required cofiguration options for CORE NODE are: ***

    Code maturity level options ->
        Prompt for development and/or incomplete code/drivers  [YES]

    Networking options ->
        Kernel/User netlink socket                             [YES]
        TCP/IP networking                                      [YES]

    QoS and/or fair queueing ->
	 QoS and/or fair queueing                              [YES]
	 SIMA queue                                            [YES | MODULE]
	 SIMA verbose messages                                 [NO]
	 SIMA statistics (VERY EXPERIMENTAL)                   [NO | YES]
	 Scheduler/Timer clock source (read the help!)         [GETTIMEOFDAY | CPU/RDTSC]
         --- Use GETTIMEOFDAY if this box operates also as ACCESS NODE ---


    *** Required cofiguration options for ACCESS NODE are: ***

    Code maturity level options ->
        Prompt for development and/or incomplete code/drivers  [YES]

    Networking options ->
        Kernel/User netlink socket                             [YES]
            Routing messages                                   [YES]
        Network firewalls                                      [YES]
        TCP/IP networking                                      [YES]
            IP: firewalling                                    [YES]
            IP: firewall packet netlink device                 [YES]

    QoS and/or fair queueing ->
         QoS and/or fair queueing                              [YES]
         Diffserv field marker                                 [YES | MODULE]
         QoS support                                           [YES]
         Rate estimator                                        [YES]
         Packet classifier API                                 [YES]
             Firewall based classifier                         [YES | MODULE]
             SIMA access node calculations                     [YES]
  8. Compile the kernel ("make dep; make clean; make bzImage")
  9. Compile and install the modules ("make modules; make modules_install")
  10. Install the kernel and update LILO
  11. Reboot the machine
  12. Install and patch the required programs (read the Chapter 3)
  13. If SIMA support was compiled as module insert it into the kernel ("insmod sch_sima")
  14. ...and you are ready to go!



3. Some utilities

IPTOOLS2 (required)

You will need this set of tools (iproute2) to operate the queues of every network interface. They are not distributed with the kernel, so you'll have to download them from other sources. After that, you'll have to patch them to add support for SIMA queues, compile and install them. Read the following chapter for step-by-step instructions howto get, install and apply them.

Installation and patching

  1. Download the tools. The package is called "iproute2" and can be downloaded from the official site or from one of the mirrors.
    Current patch is made against the version iproute2-2.2.4-now-ss990630.tar.gz.
  2. Uncompress the package (gtar -zxvf iproute2...tar.gz)
  3. Patch the source code with the sima-0.90-iproute2-990630.patch (patch -p1 < ...patch)
  4. Configure and compile the tools. You'll need configured kernel too (version 2.2.9 + SIMA patch), because these programs require some headers from the kernel source tree that are created automatically during kernel configuration/compilation.
  5. After successfull compilation you can install and utilize the tools.

logger.c

This small utility reads one of the core node specific proc filesystem files (which gather statistics) and writes out parsed data either to standard output or into file. This version is modified to work with core node version 0.85 (and higher). No more support provided (except by E-MAIL !).

The source code is available here: logger.c
Compile it with the following command: 'gcc -Wall -O2 -o logger logger.c'

rttst.c

This small program tries to read the RDTSC registers from the processor. If it succeeds it prints out the contents of the realtime registers during a short loop. If the output looks like list of numbers that have similar values your processor propably has the RDTSC register(s). I'm not sure (because I can not test it here) what happens if the processor does not have the RDTSC register(s), but it should report about invalid instructions or something like that...

The source code is available here: rttst.c
Compile it with the following command: 'gcc -Wall -O2 -o rttst rttst.c'

RUDE & CRUDE

These programs generate and log close to real-time type of UDP traffic. More information is available in the RUDE & CRUDE WWW-pages.



4. Configuration guide and examples

Some scripts, that might be usefull if you want to configure/view box configuration through WWW.

4.1 CORE NODE:

Here are the options that you can use to configure SIMA scheduler to your network interface: 
    # tc qdisc <CMD> dev <DEV> root [b|p]sima <OPTIONS>

    <CMD> = add - add the SIMA scheduler to the specified interface
            del - remove the SIMA scheduler
         change - change SIMA scheduler properties

    <DEV> = network interface name (e.g. eth0)
            CORE NODE should support now also non-Ethernet interfaces

    <OPTIONS> = reset | [hi <#>] [lo <#>] [normal | stats] [ 12x12 | 24x24 ]
	reset          - reset queue counters (/proc/net/sima)

        hi <#>         - HIGH priority queue size in bytes/packets
	lo <#>         - LOW priority queue size in bytes/packets
        normal | stats - Turn off/on the statistics measurements
        12x12 | 24x24  - Choose the DPa table (12x12 is the DEFAULT)

	Where <#> can be:
	  12-250000   for HIGH priority byte queue
	  12-1000000  for LOW priority byte queue

	  12-2500     for HIGH priority packet queue
	  12-10000    for LOW priority packet queue

        Other values will be neglected and the queues will be created
        with the default sizes 10000 bytes or 100 packets per queue.

Example 1: create SIMA queue for eth0, where high priority queue can hold 9800 bytes and low priority queue 24000 bytes. 
    # tc qdisc add dev eth0 root bsima hi 9800 lo 24000
Example 2: create SIMA queue for eth1 with statistics, where high priority queue can hold 50 packets and low priority queue 200 packets. 
    # tc qdisc add dev eth1 root psima hi 50 lo 200 stats
Example 3: read the status information. 
    # cat /proc/net/sima
Example 4: reset/clear SIMA queue counters for eth0. 
    # tc qdisc change dev eth0 root bsima reset
Example 5: remove SIMA queue from eth0. 
    # tc qdisc del dev eth0 root bsima


4.2 ACCESS NODE:

Examples under construction.

In the meantime you can find out the basic usage instructions from the downloadable script file(s):

The script(s) are well commented, so the operation should be self evident...

Authors:

Juha Laine , james@cs.tut.fi
Sampo Saaristo , sambo@cs.tut.fi