1# Debugging in net80211 2 3This document describes how debugging is implemented in net80211. 4 5## Overview 6 7net80211 has run-time configurable debugging available. It is configured 8per-VAP. It is implemented as a bitmask which can be controlled via a 9sysctl at runtime. 10 11Debugging is compiled in when IEEE80211_DEBUG is defined. 12 13There is currently no global debugging API available; top-level net80211 14code is typically using printf() or some wrapper around it (eg 15net80211_printf). 16 17The debug API is defined in (ieee80211_var.h). This includes the 18debug field definitions and exported debugging API. The actual implementation 19of the debugging routines is currently in (ieee80211_input.c) - see 20(ieee80211_note) for an example. 21 22The bitmap of available debugging sections is in (ieee80211_var.h), prefixed 23with IEEE80211_MSG . See (IEEE80211_MSG_DEBUG) for an example. 24 25## Usage 26 27Calls to the debugging APIs should not include a terminating '\n' character. 28This will be added by the debug call. 29 30The simplest example is a call to IEEE80211_DPRINTF(). This takes a vap 31pointer, which debug option to log to, then the format string and optional 32arguments. For example: 33 34``` 35IEEE80211_DPRINTF(vap, IEEE80211_MSG_11N, "%s: called!", __func__); 36``` 37 38The debug flags can be combined together using bitwise OR so they are 39emitted if one or more debug options are set, for example: 40 41``` 42IEEE80211_DPRINTF(vap, IEEE80211_MSG_11N | IEEE80211_MSG_ASSOC, 43 "%s: called!", __func__); 44``` 45 46There are a number of different debugging calls that are designed to be 47used in different contexts. Although they all currently end up printing 48to the same debug output, keeping them separate allows for future 49behavioural changes whilst minimising rototilling the whole codebase (eg 50allowing non-DPRINTF to turn into event tracing.) 51 52 * Straight up debugging should be done through IEEE80211_DPRINTF() . 53 * Debugging that's related to a specific ieee80211_node (eg a state 54 change for a specific node) should be done via a call to IEEE80211_NOTE() . 55 * Debugging that's related to a specific ethernet MAC address (eg 56 scan results) should be done via a call to IEEE80211_NOTE_MAC() . 57 * Debugging that should include a frame header should be done via 58 a call to IEEE80211_NOTE_FRAME(). Note this takes a (struct ieee80211_frame \*) 59 pointer. 60 * Debugging involving discarding frames (eg invalid frames) should be 61 done via a call to IEEE80211_DISCARD() . 62 * Debugging involving discarding frames due to an invalid / bad IE should 63 be done via a call to IEEE80211_DISCARD_IE(). 64 * Debugging involving discarding frames due to a MAC address (eg ACL failure) 65 should be done via a call to IEEE80211_DISCARD_MAC(). 66 67## Usage Notes 68 69 * It is required that the debugging be compiled in/out purely by defining or not 70 defining IEEE80211_DEBUG. This can often trip up unused variable warnings 71 when debugging is disabled, so just double-check both configurations. 72 73 * It is important to ensure calls to the debugging (and any other logging API) 74 do not change any state/variables. For example, do not call a function that 75 updates some counter or some state variable inside a call to IEEE80211_DPRINTF(). 76 It won't be called at best and it will just be compiled out entirely at worst. 77 78## Configuration 79 80 * The 'vap->iv_debug' field is controlled by the OS specific module. 81 * In FreeBSD (ieee80211_freebsd.c) it is assigned a sysctl (net.wlan.X.debug) 82 during (ieee80211_sysctl_vattach). 83 * FreeBSD ships the wlandebug(8) tool to query and set this at runtime. 84 85## Implementation Details 86 87* The debug API goes out of its way to do the debug flag check before evaluating 88 function parameters and potentially assembling the logging output. See 89 (IEEE80211_DPRINTF) for an example. 90 91## Future work 92 93 * Top-level net80211 debugging APIs and control would be nice (for things 94 that are not specific to a VAP.) 95 * Drivers end up having to implement their own debugging API; it may be nice 96 to provide drivers a net80211 API to do their own driver specific logging. 97 * The debug macros should likely be refactored out to a new header file, 98 separate from ieee80211_var.h, so they can be more easily referenced. 99 * The debug fields should likely be refactored out into a new separate header 100 file that is designed to be consumed both by the kernel and by userland 101 utilities wishing to query/set the debug bitmask. 102