System Documentation for FCM modules

Introduction
============

This document describes the structure of the FCM kernel modules and any
functionality in the Linux kernel they depend on.

There are two FCM kernel modules - Router and Receiver. The Router module is
intended to be run on a router which connects via a low-bandwidth link to many
hosts. These hosts then run the Receiver module. It then uses a different
algorithm to calculate the TCP window, which then affects the speed at which
they receive data.

Packet Modifications
====================

The two kernel modules interact in the following way:


         ------>        --p(q)->
Internet         Router          Receiver
         <------        <-------

As this diagram shows, the Router places into packets destined for the
Receiver, a value p(q). q is the size of the q on the interface which it uses
to send to the Receiver. p() is a special function of the queue size.

The value for p(q) is sent as a TCP option with the following characteristics:
Option Number: 92 (decimal)
Option Length: 4 (decimal - bytes)
The option value then occupies the following two bytes, in network byte order.
eg.  | 92 |  4 |   p(q)  |


Router Module
=============

The following options are accepted the Router module:

maxrate - The data rate of hte outgoing link in kbits/s
bval    - The value of the constant b used in calculating p(q)
q_min   - The length of the queue in packets upon which p(q) becomes non-zero
limit   - The length of the queue, int bytes

In order to use the Router module, the following kernel functionality is
required:
- QoS and/or Fair Queuing (found under Networking options)

Defined Constants
The following #defined constants are used in the Router module

#define FCM_BUFFER_SIZE         2048
        This is the size of the buffer used to generate the
        /proc/net/fcm_queue file. It must be large enough to produce the file,
        including the header line

#define FCM_MAX_INSTANCES       128
        This is the maximum number of times this module can be used at any
        given time. It is used each time tc is used to add the qdisc to a
        device.

#define TCPO_QSIZE              92
        The option number of the QSIZE TCP option

#define TCPOLEN_QSIZE           4
        The number of bytes which the QSIZE TCP option takes up
        

Receiver Module
===============

For details of the algorithm used to determine the TCP window, see the source
for this module.

Note that the TCP window is modified by this module by intercepting packets as
they leave the computer. This is done via the Netfilter hooks. Because of
this, connections must be independently tracked, so that state can be
maintained between packets of the same connection.

The following options are accepted by the Receiver module:

ps_thresh       - The value PS_THRESH used to determine when the prime start
                  phase ends
alpha           - The smoothing factor used to calculate the receiver rate.
                  Values between 1 and 100 are valid.
tau             - Determinse the rate at which the window size tries to
                  increase

In order to use the Receiver module, the following kernel functionality is
required:
- Network packet filtering (found under Networking options)
- Connection tracking (found under Networking options - IP: Netfilter
  Configuration)

Defined Constants
The following #defined constants are used int he Receiver module

#define TCPO_QSIZE      92
        The number of the QSIZE TCP option

#define TCPOLEN_QSIZE   4
        The length of the QSIZE TCP option, in bytes

#define FCM_HASH_SIZE   10240
        The size of the hash table which tracks TCP connections.
        This value should be more than sufficient.

#defone FALSE           0
#define TRUE            1

#define RAMI_MULTIPLIER 100
        The factor used when performing calculations which require real
        numbers, using only integers

#define ALPHA           100
        The smoothing factor used to calculate the received rate. Values
        between 1 and 100 are valid.

#define MINUTE          60*HZ
#define HOUR            60*MINUTE
#define DAY             24*HOUR
        The number of kernel jiffies in a minute, hour and day.