Home

Awesome

_/\/\/\/\/\_________________________/\/\______/\/\_______________________
_/\/\____/\/\___/\/\/\_____/\/\/\/\_/\/\/\__/\/\/\___/\/\/\___/\/\/\/\___
_/\/\/\/\/\___/\/\/\/\/\_/\/\__/\/\_/\/\/\/\/\/\/\_/\/\__/\/\_/\/\__/\/\_
_/\/\__/\/\___/\/\_________/\/\/\/\_/\/\__/\__/\/\_/\/\__/\/\_/\/\__/\/\_
_/\/\____/\/\___/\/\/\/\_______/\/\_/\/\______/\/\___/\/\/\___/\/\__/\/\_
_________________________/\/\/\/\________________________________________

...provides a measurement tool set for wireless research with Atheros WiFi hardware

RegMon - in-Kernel MAC-Layer Monitoring

To perform the monitoring, we leverage the lightweight kernel-to-userspace debug file system (debugfs) This serves two purposes:

  1. it enables a simple file-based configuration of RegMon for its in-kernel operations from the userspace
  2. the actual trace-file from the kernel can be accessed via standard file read (e.g., with tail, cat) from the userspace.

For the actual measurements, it is possible to access Atheros control and status registers stored in the card memory through the PCI bus. Each of the Linux drivers (i.e., Madwifi, ath5k and ath9k) has its own C functions or macros to access the memory-mapped 32-bit register content, as shown at the bottom of the RegMon picture.

RegMon is implemented as a single kernel driver patch for each of the supported three drivers, without the need for additional modules, daemons or user-space applications. All main functions of RegMon and their interactions are:

alt tag

The trace-file generated by RegMon is currently formatted as space separated list of measurement values, which turned out to be a sufficient format to parse and process the trace file for further analysis.

How to install RegMon (under Linux OpenWrt [https://openwrt.org/])

  1. copy RegMon patches (ath5k and/or ath9k) into openwrt/package/kernel/mac80211/patches/ath
  2. re-build mac80211 subsystem by: make package/mac80211/{clean,compile} or re-build complete OpenWrt
  3. install new mac80211 package or flash full image to your router

How to show RegMon WiFi busy-state plots in your local routers web-interface

  1. point your Linux LEDE feeds.conf to our RegMon repository by adding the following line to your feeds.conf:
src-git regmon https://github.com/thuehn/RegMon
  1. trigger a feeds update
  2. select our luci_app_regmon from make menuconfig under menu LUCI
  3. rebuild your LEDE image
  4. flash a new image or install the luci_app_regmon with the help of opkg

Example of RegMons LUCI web interface view

alt tag

How to use RegMon sampling

This first 7 registers are hardcoded into RegMon, which are:

Specify you own register_7..11 via:

echo XY-REGISTER-VALUE > /sys/kernel//debug/ieee80211/phy0/regmon/reg7..11

echo 50000 > /sys/kernel//debug/ieee80211/phy0/regmon/sampling_interval

tail -f /sys/kernel/debug/ieee80211/phy0/regmon/register_log

For available Atheros registers take a look at:

- ath5k:
  drivers/net/wireless/ath/ath5k/reg.h
- ath9k:
  drivers/net/wireless/ath/ath9k/ath9k/ar5008_initvals.h
  drivers/net/wireless/ath/ath9k/ath9k/ar9001_initvals.h
  drivers/net/wireless/ath/ath9k/ath9k/ar9002_initvals.h

Example of RegMon's logging output

alt tag

Parse logging output of RegMon to prepare plotting

In order to plot your register values that were collected by RegMon, someone could parse and precalculate certain values of interest.

The provided awk script parse_default_RegMon-trace.awk is such an example of preprocessing the output of RegMon for proper plotting. It performs the following operations with RegMon default output:

You can use the provided awk parser script for ath5k by issuing:

cat register_log_ath5k | gawk --non-decimal-data -v header=1 -v clock=44 -f parse_ath5k_RegMon-trace.awk

or for ath9k by using:

cat register_log_ath9k | gawk --non-decimal-data -v header=1 -v clock=44 -f parse_ath9k_RegMon-trace.awk

this leads to the following output:

ktime d_tx d_rx d_idle d_others
10001664 0 1183 878139 697
19998464 0 54376 822493 2480
30000128 145059 0 731288 3673
39998720 0 27276 851241 1152
49999872 0 28473 849755 1721
59998976 0 206086 670238 3462
70001664 0 122591 752627 5002
80001024 0 0 879591 0
90002176 0 159969 719757 387

where:

... and now you can plot your mac busy state distribution over time. I prefer Rscript for plotting and so there is an example Rscript plot_MAC-states_from_RegMon.r which generates the output plot RegMon.png. For the Rscript to work you need R and the R packages: gglpot2, reshape2 and scales.

cat register_log | \
  gawk --non-decimal-data -v header=1 -v clock=44 -f parse_ath(5 or 9)k_RegMon-trace.awk | \
  ./plot_MAC-states_from_RegMon.r
  
open RegMon.png

alt tag

Best practice for experimentation with RegMon (but unsecure)

tail -f /sys/kernel/debug/ieee80211/phy0/regmon/register_log | lzop > /tmp/register_log.lzop

( while true; do netcat -l -p 1234 -e /bin/sh ; sleep 1; done ) &

START_REGMON="tail -n0 -F /sys/kernel/debug/ieee80211/phy0/regmon/register_log | lzop -1 -cf; exit"
echo "${START_REGMON}" | netcat $your_router_IP 1234 > /tmp/register_log.lzo

This RegMon git repo includes:

Do you want to contribute ?

Everybody can participate, and any help is highly appreciated. Feel free to send pull requests or open a new issue via GitHub.

Supporters and Developers

former contributors

How to reference to RegMon ?

Just use the following bibtex :

@PhdThesis{Huehn2013,
 author      = {Thomas H{\"u}hn},
 title       = {A Measurement-Based Joint Power and Rate Controller for IEEE 802.11 Networks},
 school      = {Technische Universit{\"a}t Berlin, FG INET Prof. Anja Feldmann},
 year        = 2013,
 month       = July,
 urn         = {urn:nbn:de:kobv:83-opus4-39397},
 url         = {http://opus4.kobv.de/opus4-tuberlin/frontdoor/index/index/docId/3939}
}

Where do I get the full description of RegMon ?

Have a look at chapter 4 of my dissertaion