Please note: This project is no longer active. The website is kept online for historic purposes only.
If you´re looking for a Linux driver for your Atheros WLAN device, you should continue here .

How to use the debugging tools athdebug and 80211debug

MadWifi contains quite extensive debugging facilities, which are hidden to most people. The tools/ directory contains two programs which are also installed by default, called athdebug and 80211debug. These two programs can be used to control the amount of debugging output which appears in the kernel log (dmesg and /var/log/messages or /var/log/kern.log depending on the distribution).

The reason why there are two separate programs is that one controls the debugging output from the device (ath) specific part and the other one for the generic (80211) part. Remember: The 802.11 stack used by MadWifi (net80211) is derived from FreeBSD where it supports more wireless devices than just Atheros based.

Both programs have the same user interface and basically work by setting a bitmap in the driver enabling or disabling debugging output from various subsystems. Both also take an optional parameter -i device (e.g. -i wifi1) which can be omitted if you use wifi0.

So we have the basic usage:

athdebug [-i interface] bitmap
80211debug [-i interface] bitmap

You can enable all debugging output from the ath (device) specific subsystems (same for 80211) by typing

athdebug 0xffffffff

And disable it with

athdebug 0x0

Since it's quite tedious to remember the bitmaps, fortunately there is a user friendlier interface which can be used to enable (+) or disable (-) debugging output by giving the name of the component or subsystem

athdebug [-i interface] [+|-]name [[+|-]name]
80211debug [-i interface] [+|-]name [[+|-]name]

athdebug

athdebug controls the debugging output from the atheros device specific parts, or the parts closer to the hardware. It has the following flags:

xmit          - transmit of packets, just before they go out to the HW
xmit_desc     - transmit descriptors
recv          - received packets, directly from the HW
recv_desc     - receive descriptors
rate          - the rate control modules
reset         - reset processing and inititalization

mode          - mode changes
beacon        - beacon handling
watchdog      - watchdog timeout
intr          - interrupt processing
xmit_proc     - processing of transmit descriptors
recv_proc     - processing of receive descriptors
beacon_proc   - beacon processing
calibrate     - periodic re-calibration
keycache      - key cache management
state         - 802.11 state transitions
node          - node management
ff            - fast frame handling
fatal         - fatal errors

80211debug

80211debug controls the debugging output from the 802.11 stack. It has the following flags:

debug         - IFF_DEBUG equivalent (?)
dumppkts      - dump packets
crypto        - crypto modules
input         - packet input
xrate         - rate set handling
elemid        - element id parsing
node          - node management
assoc         - association handling
auth          - authentication handling
scan          - scanning
output        - packet output
state         - 802.11 state machine
power         - power save functions
dotx1         - 802.1x authenticator
dot1xsm       - 802.1x state machine
radius        - 802.1x radius client
raddump       - 802.1x radius packet dump
radkeys       - 802.1x key dump
wpa           - WPA/RSN protocol
acl           - ACL handling
wme           - WME protocol
superg        - super g turbo mode
doth          - 802.11h (DFS/TPC) handling
inact         - timeout of inactive nodes
roam          - station mode roaming

Dialog wrapper

UserDocs/Tools/ath+802_debug-wrapper provides a shell script that implements a dialog interface to the debug tools, making it a lot easier for users to work with the debug tools.

Examples and Tips

Example 1: Dump received packets

For example we can enable output from the xmit (transmit) functions with

athdebug +xmit

You will see dev.wifi0.debug: 0x0 => 0x1<xmit> - the 0x... stuff showing the bitmap which you could also use (especially interresting when you combine more flags). Then you will see every packet which is passed by the driver to the hardware in the kernel log. In this case:

ath_tx_start: Q1: (ds)a3110ea0 (lk)00000000 (d)033f95c0 (c0)033f0058 (c1)07000054 000b0000 0000001b
ath_tx_txqaddbuf: link[1] (a3110e40)=3110ea0 (a3110ea0)
ath_tx_start: skb0 8329bcc0 [data 833f9490 len 105] skbaddr 33f9490
NODS 00:02:6f:22:0a:87->00:60:1d:f0:b1:61(00:02:6f:22:0a:87) probe_resp 1M

50 00 3a 01 00 60 1d f0  b1 61 00 02 6f 22 0a 87
00 02 6f 22 0a 87 a0 01  00 00 00 00 00 00 00 00
64 00 01 00 00 07 62 72  31 74 65 73 74 01 04 82
84 8b 96 03 01 02 07 06  4e 41 49 01 0b 1b 20 01
00 2a 01 07 dd 18 00 50  f2 02 01 01 84 00 02 a3
40 00 27 a4 00 00 42 43  5e 00 62 32 2f 00 dd 09
00 03 7f 01 01 00 24 00  00

The lower part with the hex numbers is a full packet dump similar to the one you would get with tcpdump -x or ethereal.

Example 2: Show Special Input Packets

Another useful information is often to see which packets come in and which of them are discarded:

80211debug +input

This results for example in:

[ath0:00:60:b3:13:0c:56] discard frame, not to bss
[ath0:00:02:6f:09:51:90] discard frame, not to bss

Which is quite a normal condition when there are other WLAN networks in the same area.

Example 3: Show Associations

Now let's print information about associating stations (on the AP side)

80211debug +assoc

For Example:

ath0: [00:02:6f:2f:02:65] station associated at aid 1: short preamble, short slot time, QoS, fast-frames

Performance Impact

Attention: Enabling all debugging output on smaller systems can make them very slow and sometimes unresponsive. So it's usually better to only enable the output from the part you are interested in.

But sometimes you don't know in advance. So it might sometimes be useful to use a script or write all commands in one line to enable debugging output, issue a short command and disable it again. E.g:

athdebug 0xffffffff; iwpriv ath0 mode 1; athdebug 0x0;

or

80211debug 0xffffffff; athdebug 0xffffffff; \
ping -c 1 10.0.0.1; \
athdebug 0x0; 80211debug 0x0;