Welcome to Libmac

Summary

The libmac library is designed for the NSF ​ORBIT Testbed Project. it is a user-space C library that provides applications with an API for,

• Injection and capture of MAC layer frames.
• Manipulation of a subset of wireless interface parameters at both aggregate and per-frame granularity levels.
• Communication of a subset of wireless interface parameters from one end of a network connection to the other, on a per-frame granularity level.

Manipulation and communication of wireless interface parameters, was achieved by modifying open-source Linux device drivers for Atheros and Intel a/b/g 802.11 cards.

Introduction

Network simulation tools, like ns-2 and OPNET have contributed substantially to the development of networking protocols over a number of years in both academia and industry. The validity of results from these tools is such that they are still the preferred way to determine a first approximation to the actual results. There are numerous publications and doctorate dissertations where simulation results, obtained using these tools, form the principal basis for the proposed solution. However, these tools were mainly developed for wired network scenarios where the physical layer is much more predictable and uncomplicated as compared to wireless networks. The use of these tools for such networks demands accurate physical-layer models and their subsequent integration. Although accurate mathematical models exist, it is very difficult to implement these in a simulator given the inherent random nature of every aspect of this physical layer. Implementation is further complicated by the additional facet of mobility of nodes, in such a network, and the random manner in which it occurs.

The OPNET simulator has an implementation of the wireless physical layer that has appreciable support for some aspects but is quite simplistic in other aspects. Additionally, being a commercial product, the complete source code is not available for modification or incremental addition, which is a fundamental requirement in this kind of research. For ns-2, the source code is freely available but the physical layer models are mostly deterministic, which in turn produce incomplete and biased results.

Emulation is seen as an alternative technique to study these networks, where the physical layer characteristics remain the same as in real-world wireless networks, except for mobility, which is the emulated feature. This is the approach adopted by the proposed ORBIT (Open Access Research Testbed for Next-Generation Wireless Networks) testbed. As the name suggests, this will be an open-access multi-user experimental (MXF) facility to support research on next-generation wireless networks.

As part of this effort, open-source software tools need to be developed to perform the fundamental functions of (a) setting up and conducting an experiment and (b) collecting and storing the results. In order to conduct an experiment, the basic functionalities, such as (a) transmission and reception of frames, (b) the ability to tune interface parameters and © the ability to control MAC level mechanisms, are required. Libmac, a user-level C library attempts to provide these features.

Design

Motivation

Currently, protocol development is a two-stage process where specific ideas for the modification of an existing protocol, or the development of a new one, are first implemented in a simulator and then, based on the results, implemented in an open-source kernel. This two-stage process is justified when the first stage provides results with an acceptable loss of accuracy, in a time frame which is smaller than what would be available if the first stage itself was kernel implementation. Simulator designers have to make this tradeoff so that implementors have a first approximation to the actual results as fast as possible, using which, they can decide whether or not they want to invest their time and effort in the second stage. In addition, protocol implementations in a simulator have the advantages of development ease and flexibility.

However, as discussed earlier, the loss of accuracy for wireless network scenarios, in the simulators that are currently available, is not acceptable. Therefore, we have to look at:

• either using just a single-stage protocol development process where we directly modify or implement the protocol in the kernel or
• replacing the first stage with a process that is more accurate than the existing one.

The advantages of the first approach are:

• kernel-level implementations of the protocol provide complete and accurate information about the performance,
• are efficient and
• take into account the interworking between the protocol and all the other system components.

The disadvantages are:

• the requirement of a high level of programming expertise,
• the lack of debugging tools,
• the presence of protection mechanisms,
• the requirement of low-level languages, like C and assembly,
• the high risk involved ('buggy' kernel code can bring down the entire system) and
• the strict layering approach of wired network protocols and their subsequent implementation, which implies that newer philosophies of cross-layer design will prove difficult, if not impossible, to implement in existing stable versions.

Thus, kernel-level implementations provide the real-basis for performance analysis but they are time-consuming and difficult. Additionally, the existing two-stage philosophy will be hard to replace by this single-stage approach because of the widespread acceptance and use of the former approach.

In keeping with the spirit of the two-stage philosophy, emulation is seen as acceptable replacement for the first-stage. It can be designed to provide the same advantages of simulators, namely,

• development ease and flexibility and
• speed of execution.

In addition, accuracy levels will be much more closer to real-world experiments.

Design Goal

Thus, our design goal can be stated as,

Design an emulator framework which will

• provide the development ease and flexibility of a simulator,
• provide more accurate results than those currently obtained and
• serve as common ground where results can be compared. \end{enumerate}}

Design choice I: Implement the emulator in user-space, in a modular manner

Keeping these requirements in mind, a decision was made to implement this emulator framework in user-space, in a modular fashion, built from the ground up so that the lowest module of the framework will communicate with the network device drivers. The figure below gives the general idea behind the framework. Protocol Modules (PM) at each level will provide implementations of the existing protocol stack (for e.g. TCP/IP). The framework will also allow a plug-and-play feature so that newer protocols can be tested and compared with existing ones

The goal is to provide implementations of existing protocol stacks (for e.g. TCP/IP), together with their source code, and allow for newer protocols to be developed and integrated into this framework in a plug-and-play manner (we are in fact, replicating the design of simulators here, which also provide implementations and source code of existing protocol stacks). This should allow protocol developers, at any layer, to concentrate on the performance of their protocol rather than the performance of particular lower or higher layer protocol implementations, since the same implementations will be used by all users.

Design choice II: Use publicly available source code in order to speed up implementation

To speed up the implementation and not rewrite software that already exists, an implicit design choice made was to re-use as much of the public domain source code as possible in order to speed up implementation of this framework.

Design choice III: Implement all modules in the framework as shared libraries that provide APIs

Given the plug-and-play requirement of the framework, in addition to the modularity requirement, a decision was made to implement each module as a shared library. Since shared libraries are linked at run-time instead of compile-time, they have the following advantages:

• All programs using the library need not be recompiled whenever a change is made.
• Each task shares the same memory space for the shared library. Thus, even if there are N programs using the library, there needs to be only one copy in main memory. In other words, not linking in the code into every task can save a lot of disk space.
• Less pages need to be in the main memory, cutting down paging and reducing the overall memory footprint.

Design choice IV: Using public-domain frame injection (libnet) and capture libraries (libpcap)

Quite obviously, the first stage of development of this framework is for the lowest module that needs to be able to transmit and capture raw MAC frames, in addition to providing APIs for interface parameter tuning. An additional requirement of the lowest module is that of appending parameter information to outgoing or incoming frames. The motivation for this requirement stems from the experimental nature of this work and from the interest shown by the research community in cross-layer protocol design. Within the framework, the following figure gives an idea of how the lowest module of the framework can capture raw MAC frames using the packet sockets API.

The architecture diagram is shown below - Libmac uses open-source libraries ​libpcap, for frame capture and ​libnet, for frame injection.

Starting Points

For Experimenters

Currently supported linux device drivers in the libmac package include ipw2200(version 1.0.8) and madwifi(old version-approx June 2005, NOT madwifi-ng). Supported parameters include RSSI, 802.11 PHY Bit-rate, MAC timestamp (all on the receive side).

For Developers

• Sample code and function specifications are available ​here
• Check out source using ​subversion at ​http://svn.orbit-lab.org/svn/orbit/libmac/trunk.