UMTS RRC Emulation module

The UMTS Radio Resource Control (RRC) is a state machine that governs the transmission capabilities and power consumption state of a UMTS (i.e. 3G) modem. For a good reference on this state machine, read this paper.

The software available in this page is a Linux kernel module that emulates all the characteristics of UMTS networking by modeling the RRC state machine. With it, you can turn a regular host and network interface into an UMTS modem, and emulate cellular 3G networking for fun and for experiments.

The characteristics you can emulate are: upstream and downstream bandwidth, packet loss, latency, jitter, RLC FACH buffer thresholds, RRC state machine timers, RRC transition periods with average and standard deviation, and fast dormancy.

Who and what

This software was written entirely by Andres Lagar-Cavilla (andres at lagarcavilla dot org), whose page you're visiting. It was written while employed at AT&T Labs Research, who own the Intellectual Property and have graciously agreed to open source this code under the GPL license. The kernel module and iproute bindings are explicitly GPL v2, as indicated in the patches and code headers.

This work builds on the standard Linux Traffic Control infrastructure of qdiscs and classes. I don't dispute it could have been built in a more modular fashion, but what I offer here is quite powerful, and clean enough.

There are three main components to the software: the Linux Kernel module, the iproute tc modifications, and a set of convenience scripts.

Kernel module

The Linux Kernel module can be built applying these three patches in the order specified. If you don't know how to work with patches or patch queues, follow this or this reference.

series

00-rrc-tc-header.patch

01-rrc-tc-qdisc.patch

02-rrc-tc-plumb.patch

The patches apply against a 2.6.18 kernel, your mileage may vary (but hopefully not greatly) for newer kernels. As you'll see, patches are fairly trivial to rebase.

Once applied, 'make menuconfig', go to Networking -- Networking Options -- QoS and/or fair queueing -- UMTS RRC state machine emulator (RRC), and choose to build that as a module. Then you need to rebuild modules and install sch_rrc.ko where appropriate (make modules_install would do that with a big hammer).

User-space iproute bindings

The second step is to build the user-space support to interact with the kernel module. You need to get a recent source distribution for the iproute package. In a Debian environment, 'apt-get source iproute' will do this in the blink of an eye. Then, you apply this single patch:

iproute-20100519-rrc.patch

As the name implies, it applies to Debian's iproute 20100519 source. Althoug it's one single patch, it's trivial to split and rebase. Once applied, rebuild iproute and install the 'tc' binary.

Are we ready yet?

Now you're good to go, and you can actually start emulating UMTS. In terms of help, just ask tc

/usr/sbin/tc qdisc add dev eth0 root rrc help
Usage: ... rrc [ dchtail SECONDS (5) ]
[ fachtail SECONDS (12) ]
[ fachdchmu MILISECS (1500) ]
[ fachdchsigma MILISECS (500) ]
[ idlepromomu MILISECS (2000) ]
[ idlepromosigma MILISECS (1000) ]
[ rlcul BYTES (540) ]
[ rlcdl BYTES(475) ]
[ idletodch INTBOOL (yes) ]
[ inverted INTBOOL (yes) ]
[ delay MILISECS (30) ]
[ jitter MILISECS (10) ]
[ drop PERCENT (8) ]
[ dchdlrate MBPS (7) ]
[ dchulrate MBPS (1) ]

Units are in capital and defaults between parenthesis. idletodch means that state machine transitions out of IDLE into DCH -- otherwise it goes out of IDLE into FACH. inverted means that ingress packets are actually outbound and viceversa. This is useful because you might want to encapsulate the emulated machine in a VM: the VM network traffic usually emanates out of a virtual interface in the host machine, that is effectively inverted. Thus, you would attach this emulation module to the virtual nic in inverted mode. If, instead, you're attaching the module to the interface of your physical box, you'd disable this option by providing 'inverted 0' in the command line.

Convenience scripts

Best way to use this is through a set of scripts I've cooked. They all have a hardcoded path (/home/andres/src/cscripts/) you can sed (and a few other site-specific params like certain IP addresses):

vif sets general parameters for the virtual NIC (VM case) to which we will attach the emulation module.

filterio creates a set of iptables and ebtables rules that will prevent any Ethernet LAN-specific traffic from reaching the emulated NIC, thus more faithfully emulating an UMTS environment.

filterclean clears the filtering rules set by filterio.

redir_all_ifb the primary setup script, with a RULE statement you can suit to your liking. See comments and examples.

tcclear clears the rules that set up the emulation.

showoff shows all relevant stats out of the emulation and traffic control modules.

What do those stats look like?

DCH tail 5.0s FACH tail 12.0s
FACH to DCH promo 1.5s +- 500.0ms IDLE promo 2.0s +- 1.0s
RLC buffer threshold UL 540 DL 475
From IDLE to DCH -- interface inverted
DELAY 0us JITTER 10.0ms DROP 0%
DCH Rate DL 10000Kbit UL 10000Kbit
**** STATS ****
DCH (p/b) UL 277:1082192 DL 557:139321
FACH (p/b) UL 43:3824 DL 31:3123
DCH Time 59.9s FACH Time 78.6s
IDLE upswitches 6 DCH downswitches 7 FACH us 2 ds 4
Transition Time IDLE 10.6s FACH 2.7s
FD calls 2 Drops (p/b) 0:0 Time total 10.6s avg 5.3s

The first block is the current parameters, but the second block shows you the goods about what has been going on: number of packets and bytes sent in each direction and each mode, number of switches, time spent in each mode. And number of fast dormancy calls and their effects.

Fast Dormancy

Try 'tc qdisc change dev ifb0 root rrc fastdormancy'. This will emulate a fast dormancy call, which abruptly drops the state machine out of whatever state it was into IDLE. Useful for experimenting to see what the impact of that is on a traffic workload!

2011 Andres Lagar-Cavilla, andres at lagarcavilla dot org, licensed under GPL v2