= Welcome to Libmac = == Summary == The '''libmac''' library is designed for the NSF '''[http://www.orbit-lab.org 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 (c) 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. The architecture diagram is shown below - Libmac uses open-source libraries [http://www.tcpdump.org/ libpcap], for frame capture and [http://www.packetfactory.net/libnet/ libnet], for frame injection. [[Image(libmac_layering.jpg)]] [[BR]] == 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 [http://www.winlab.rutgers.edu/~kishore/libmac_docs here] * Check out source using [http://www.subversion.org subversion] at http://svn.orbit-lab.org/svn/orbit/libmac/trunk.