Kickass for NS-3 - v. 1.0
Marcel Flores - marcel-flores@u.northwestern.edu

About
=====
This patch contains the implementation of RCP and Kickass for NS-3.

Kickass is a congestion control mechanism by Marcel Flores and Aleksandar
Kuzmanovic at the Northwestern Networks Group.

The RCP implementation is based on the original by Nandita Dukkipati, and is as
close to the NS-2 code found on her site as possible. More information on RCP 
and the original NS-2 implementaion can be found here:

http://yuba.stanford.edu/rcp/

In general, both implementations are a little hacked into NS-3. Since Kickass
requires special access to both TCP and IP stacks, it includes quite a bit of
copy-and-pasted code from the NS-3 core. While this is obviously not-optimal it
was the most doable at time of writing.

Requirements
============

The patch requires a clean version of NS-3.18.1. While it's mostly modular,
there are a few small adjustments to the NS core that means this patch is likely
not compatible with other things (hopefully this will change in the future!).

Installing
==========
1) Copy the patch into the ns-3.18.1 directory.

2) Apply it:

    patch -p0 < ns3-kickass.patch

3) Build NS-3 normally:

    ./waf

Running
=======

There are several ways to use kickass and rcp. A few examples have been placed in
ns-3.18.1/scratch

1) kickass_example.cc and rcp_example.cc

    These can be run with:

    ./waf --run kickass_example

    or 

    ./waf --run rcp_example

    They are essentially the same as the tcp_bulk_send.cc example from
    ns-3.18.1/examples/tcp/. They represent about the minimal use case for both
    schemes.

2) More complex scripts are available based on the tests run in the paper. In
   particular:

    a) base-experiment - The basic dumbbell with on-off senders, etc. Allows use
    of one protocol at a time, variable numbers of senders, nodes, etc.

    b) mixed-flows - Allows a mix of TCP and KA flows, to explore how they
    interact.

    c) non-ka-cong - Creates congestion at a non-KA router, modeling how
    a network responds when endpoints get incomplete information

    d) five-bottle - A multiple bottleneck experiment.

    Scripts demonstrating how to run each type of simulation, as well as a few
    additional scenarios are available in ns-3.18.1/scripts/. Each comes in tcp, 
    Kickass, and rcp versions to compare how the different methods perform in 
    the same situation.

    For all, the output specifies a bit more about the arguments, but in
    general:
        -Capacity is in Gbps
        -delay in MS
        -Queue size in packets

Acknowledgements
================
Kickass development team acknowledgements can be found on the project website.

Special thanks to Nandita Dukkipati and the team at Stanford who wrote the
original RCP implementation and the NS-3 team.

Contact
=======
Questions and comments should be directed to Marcel Flores at
marcel-flores@u.northwestern.edu


