Atheros driver/HAL debugging

| Driver | HAL | Supported Hardware | 802.11n support | Debugging |

This section will provide a basic overview of the various debugging tools and options available.

HAL debug sysctl

The HAL has a number of debug options. This required "AH_DEBUG" to be included in your kernel configuration.

The "hw.ath.debug" sysctl controls the debug bitmask for all ath(4) NICs in the system.

The "dev.ath.X.hal.debug" sysctl controls the debug bitmask for that specific NIC.

The specific debug bit names can be found in src/sys/dev/ath/ath_hal/ah_debug.h .

Driver debug sysctl

The driver also has a debug bitmask - this is a 64 bit bitmask. This requires "ATH_DEBUG" to be included in your kernel configuration.

The "dev.ath.X.debug" sysctl controls the debug bitmask.

athdebug

"athdebug" also controls the driver (ath(4)) debugging bitmask. It is in src/tools/tools/ath/athdebug/ .

The current list of available flags can be viewed by using '-?'. Here is an example output:

adrian@marilyn:~/work/freebsd/ath/head/src/tools/tools/ath/athstats]> athdebug '-?'
usage: athdebug [-i device] [flags]
where flags are:
xmit
xmit_desc
recv
recv_desc
rate
reset
mode
beacon
watchdog
intr
xmit_proc
recv_proc
beacon_proc
calibrate
keycache
state
node
led
ff
dfs
tdma
tdma_timer
regdomain
fatal

Tools

The ath(4) and HAL tools are available in src/tools/tools/ath/ . It's highly suggested that you compile these tools if you're using the Atheros hardware.

athstats

athstats is by far the most useful tool available for inspecting the current link behaviour. The tool has documentation (athstats -h).

The "-l" option lists all the available statistics. The "-o" option allows you to specify a set of statistics to output or to use one of the default statistics sets. If a time interval is provided (eg "athstats 1") then the tool reports a periodic set of changed values, rather than the current totals.

The default statistics sets are:

This requires "ATH_DIAGAPI" to be enabled in order for all the debugging to be available.

Here's an output from athsurvey on an 802.11n station. Yes, it's very detailed.

adrian@marilyn:~/work/freebsd/ath/head/src/tools/tools/ath/athstats]> ./athstats
69267046     data frames received
96332700     data frames transmit
133134       short on-chip tx retries
26721        long on-chip tx retries
483          tx failed 'cuz too many retries
1361         mib overflow interrupts
MCS14        current transmit rate
1            watchdog timeouts
8            beacon miss interrupts
2            tx stopped 'cuz no xmit buffer
19442        tx failed 'cuz destination filtered
10841        tx frames with short preamble
241561       rx failed 'cuz of bad CRC
347          rx failed 'cuz decryption
30           rx failed 'cuz of PHY err
    30           illegal service
604          periodic calibrations
-0/+0        TDMA slot adjust (usecs, smoothed)
46           rssi of last ack
68           avg recv rssi
-96          rx noise floor
2            phantom beacon misses
3847         tx frames through raw api
68021845     A-MPDU sub-frames received
69147166     Half-GI frames received
69156473     40MHz frames received
371683       CRC errors for non-last A-MPDU subframes
2280         CRC errors for last subframe in an A-MPDU
8705591      Frames transmitted with HT Protection
891343       Number of frames retransmitted in software
45660        Number of frames exceeding software retry
95070933     A-MPDU sub-frame TX attempt success
935966       A-MPDU sub-frame TX attempt failures
18761        A-MPDU TX frame failures
81           listen time
54           ANI increased spur immunity
50           ANI decrease spur immunity
3            ANI enabled OFDM weak signal detect
445          ANI disabled OFDM weak signal detect
443          ANI disabled CCK weak signal threshold
5            ANI increased first step level
1            ANI decreased first step level
14328248     cumulative OFDM phy error count
13076610     cumulative CCK phy error count
685          ANI forced listen time to zero
26689        missing ACK's
133134       RTS without CTS
4916670      successful RTS
435961       bad FCS
167363       beacons received
49           average rssi (beacons only)
36           average rssi (all rx'd frames)
76           average rssi (ACKs only)
Antenna profile:
[0] tx  4894039 rx      120
[1] tx        0 rx 69266926

And an example of live statistics, in this case ANI:

adrian@marilyn:~/work/freebsd/ath/head/src/tools/tools/ath/athstats]> athstats -o ani 1
BSI DSI TSI NI SI ST OWSD CWST  NI-  NI-  SI+  SI-     OFDM      CCK LISTEN
 46  36  76  0  0  0    0    0    0    0   54   50 14329126 13076610    328
 47  36  76  0  0  0    0    0    0    0    0    0        0        0    392
 46  36  76  0  0  0    0    0    0    0    0    0        8        0    404
 46  36  76  0  0  0    0    0    0    0    0    0       18        0    439
 46  36  76  0  0  0    0    0    0    0    0    0       19        0    439
 45  36  76  0  0  0    0    0    0    0    0    0        3        0    438
 45  36  76  0  0  0    0    0    0    0    0    0        6        0    425
 46  36  76  0  0  0    0    0    0    0    0    0       21        0    451
 46  36  76  0  0  0    0    0    0    0    0    0        9        0    495

athregs

athregs dumps a subset of the current registers for the NIC. It's useful for taking snapshots of the NIC state.

This requires "AH_DIAGAPI" to be enabled.

athpeek/athpoke

These tools allow individual registers to be read and written. Again, this requires "AH_DIAGAPI" to be enabled.

athaggrstats

Like athstats, athaggrstats displays link statistics. In this case however it displays TX aggregation specific statistics. This is useful for debugging 802.11n aggregation performance.

The following is an example output from the tool:

adrian@marilyn:~/work/freebsd/ath/head/src/tools/tools/ath/athstats]> athaggrstats
134885   single frames scheduled
10       frames outside of the BAW
3747636  aggregate frames scheduled
10253    single frames due to closed BAW
1074380  single frames scheduled due to low HWQ depth
48801    sched called with no frames

Aggregate size profile:

 0:            0  1:            0  2:        52559  3:        26210
 4:        37998  5:        18647  6:        18792  7:        17873
 8:        18772  9:       117355 10:        21017 11:        19879
12:        20176 13:        30960 14:        21223 15:        21834
16:        20748 17:        20457 18:       353735 19:        18101
20:        17295 21:        16785 22:        17534 23:        17239
24:        15690 25:        15426 26:        15767 27:       974124
28:        13688 29:        12383 30:        12139 31:        15191
32:      1748039 33:            0 34:            0 35:            0
36:            0 37:            0 38:            0 39:            0
40:            0 41:            0 42:            0 43:            0
44:            0 45:            0 46:            0 47:            0
48:            0 49:            0 50:            0 51:            0
52:            0 53:            0 54:            0 55:            0
56:            0 57:            0 58:            0 59:            0
60:            0 61:            0 62:            0 63:            0

athradar

Although not useful at the present moment (Except to Adrian), this allows the PHY radar register parameters to be tweaked.

athsurvey

Athsurvey will display the current channel utilisation. It doesn't currently support multiple channel survey information, so the channel survey state will be rather useless during scanning.

To use:

$ athsurvey <-i athX>

Example output:

adrian@marilyn:~/work/freebsd/ath/head/src/tools/tools/ath/athsurvey]> ./athsurvey
         min                   avg                   max
  tx%  rx%  bc%  ec%    tx%  rx%  bc%  ec%    tx%  rx%  bc%  ec%
(26.1 36.9 69.4  0.0) (32.6 48.7 81.2  0.0) (41.4 56.9 85.6  0.0)
(26.1 36.9 69.4  0.0) (33.1 48.6 81.7  0.0) (41.4 55.4 87.1  0.0)

dev/ath(4)/Debugging (last edited 2016-01-13T22:39:53+0000 by AdrianChadd)