Page MenuHomeFreeBSD
Files F157383801

D56760.id177021.diff
No OneTemporary
Actions

D56760.id177021.diff
View Options

diff --git a/sys/net80211/DEBUG.md b/sys/net80211/DEBUG.md
new file mode 100644
--- /dev/null
+++ b/sys/net80211/DEBUG.md
@@ -0,0 +1,101 @@
+# Debugging in net80211
+
+This document describes how debugging is implemented in net80211.
+
+## Overview
+
+net80211 has run-time configurable debugging available. It is configured
+per-VAP. It is implemented as a bitmask which can be controlled via a
+sysctl at runtime.
+
+Debugging is compiled in when IEEE80211_DEBUG is defined.
+
+There is currently no global debugging API available; top-level net80211
+code is typically using printf() or some wrapper around it (eg
+net80211_printf).
+
+The debug API is defined in (ieee80211_var.h). This includes the
+debug field definitions and exported debugging API. The actual implementation
+of the debugging routines is currently in (ieee80211_input.c) - see
+(ieee80211_note) for an example.
+
+The bitmap of available debugging sections is in (ieee80211_var.h), prefixed
+with IEEE80211_MSG . See (IEEE80211_MSG_DEBUG) for an example.
+
+## Usage
+
+Calls to the debugging APIs should not include a terminating '\n' character.
+This will be added by the debug call.
+
+The simplest example is a call to IEEE80211_DPRINTF(). This takes a vap
+pointer, which debug option to log to, then the format string and optional
+arguments. For example:
+
+```
+IEEE80211_DPRINTF(vap, IEEE80211_MSG_11N, "%s: called!", __func__);
+```
+
+The debug flags can be combined together using bitwise OR so they are
+emitted if one or more debug options are set, for example:
+
+```
+IEEE80211_DPRINTF(vap, IEEE80211_MSG_11N | IEEE80211_MSG_ASSOC,
+ "%s: called!", __func__);
+```
+
+There are a number of different debugging calls that are designed to be
+used in different contexts. Although they all currently end up printing
+to the same debug output, keeping them separate allows for future
+behavioural changes whilst minimising rototilling the whole codebase (eg
+allowing non-DPRINTF to turn into event tracing.)
+
+ * Straight up debugging should be done through IEEE80211_DPRINTF() .
+ * Debugging that's related to a specific ieee80211_node (eg a state
+ change for a specific node) should be done via a call to IEEE80211_NOTE() .
+ * Debugging that's related to a specific ethernet MAC address (eg
+ scan results) should be done via a call to IEEE80211_NOTE_MAC() .
+ * Debugging that should include a frame header should be done via
+ a call to IEEE80211_NOTE_FRAME(). Note this takes a (struct ieee80211_frame \*)
+ pointer.
+ * Debugging involving discarding frames (eg invalid frames) should be
+ done via a call to IEEE80211_DISCARD() .
+ * Debugging involving discarding frames due to an invalid / bad IE should
+ be done via a call to IEEE80211_DISCARD_IE().
+ * Debugging involving discarding frames due to a MAC address (eg ACL failure)
+ should be done via a call to IEEE80211_DISCARD_MAC().
+
+## Usage Notes
+
+It's important that the debugging be compiled in/out purely by defining or not
+defining IEEE80211_DEBUG. This can often trip up unused variable warnings
+when debugging is disabled, so just double-check both configurations.
+
+It is important to ensure calls to the debugging (and any other logging API)
+do not change any state/variables. For example, do not call a function that
+updates some counter or some state variable inside a call to IEEE80211_DPRINTF().
+It won't be called at best and it will just be compiled out entirely at worst.
+
+## Configuration
+
+ * The 'vap->iv_debug' field is controlled by the OS specific module.
+ * In FreeBSD (ieee80211_freebsd.c) it is assigned a sysctl (net.wlan.X.debug)
+ during (ieee80211_sysctl_vattach).
+ * FreeBSD ships the wlandebug(8) tool to query and set this at runtime.
+
+## Implementation Details
+
+* The debug API goes out of its way to do the debug flag check before evaluating
+ function parameters and potentially assembling the logging output. See
+ (IEEE80211_DPRINTF) for an example.
+
+## Future work
+
+ * Top-level net80211 debugging APIs and control would be nice (for things
+ that are not specific to a VAP.)
+ * Drivers end up having to implement their own debugging API; it may be nice
+ to provide drivers a net80211 API to do their own driver specific logging.
+ * The debug macros should likely be refactored out to a new header file,
+ separate from ieee80211_var.h, so they can be more easily referenced.
+ * The debug fields should likely be refactored out into a new separate header
+ file that is designed to be consumed both by the kernel and by userland
+ utilities wishing to query/set the debug bitmask.
diff --git a/sys/net80211/PROTOCOL.md b/sys/net80211/PROTOCOL.md
new file mode 100644
--- /dev/null
+++ b/sys/net80211/PROTOCOL.md
@@ -0,0 +1,563 @@
+# 802.11 protocol overview
+
+This is a quick overview of the 802.11 protocol and where it intersects with
+net80211. It is not intended as a comprehensive deep dive into all of 802.11.
+
+TODO: link to appropriate sections in 802.11-2016 / 802.11-2020 depending upon
+which PDF is freely available.
+
+## 802.11 overview
+
+The 802.11 protocol / specification is a very large document which covers
+everything from the raw signals going out over the air up to how devices
+need to behave in different operating modes.
+
+The IEEE specification documents and amendments describe what devices should
+and must do in order to interoperate. It's important to note that the
+intersection of "what the standard says" and "what devices do" is not always
+fully aligned. The 802.11 specification has evolved over twenty-five years
+and for the most part this allows interoperability between the original 802.11b
+hardware and modern multi-band 802.11ax devices.
+
+It's also important to note that 802.11 is not just limited to the IEEE
+specifications. 802.11 devices are almost exclusively RF devices (if you
+read the specification you may find the old infrared / IR protocol definition!)
+and so need to operate inside of the radio regulatory rules defined by each
+country. These define a wide variety of RF environmental behaviours
+including frequencies can be used, when devices can transmit, what transmit
+power is allowed, interoperability with other devices (802.11 and non-802.11)
+and radar interoperability. For the purposes of this document these will
+be called "regulatory concerns" and will be covered elsewhere.
+
+The 802.11 specification breaks things up into a handful of top level areas:
+
+ * the PHY layer - how the device interfaces with the RF environment and
+ encodes/decodes RF transmissions into data streams.
+ * the MAC layer - defines how data is packetized into individual data frames,
+ exchanged with the upper layer (ethernet/bridge), deciding when and what
+ to transmit via the PHY layer.
+ * MLME - (MAC layer management entities) - defines all of the state methods
+ and transitions that underpin the 802.11 MAC state machine.
+ * Security - the cipher and key management components.
+ * PHY specifications - the specific implementations of PHYs - 2GHz DSSS
+ (spread spectrum), 2GHZ CCK, OFDM, ERP, 802.11n / HT, 802.11ac / VHT, etc.
+
+Most 802.11 implementations do not implement a 1:1 definition of each of these
+layers - notably implementing every single MLME state would be a huge amount
+of work.
+
+## 802.11 revisions
+
+There have been many revisions of the 802.11 specification. The specifications
+can be found online at https://www.ieee802.org/11/.
+
+The latest specification being implemented in net80211 is 802.11-2020, however
+net80211 is far from completely compliant. Generally new code which implements
+802.11 features / protocol handling should identify the specification and
+section which it is referencing.
+
+## 802.11 protocol and frame definitions
+
+net80211 keeps most 802.11 frame and protocol definitions in a single location
+(ieee80211.h).
+This contains descriptions of the 802.11 frame and field definitions, ranging
+from the lowest definition of the frame itself up through frame types/subtypes,
+individual field definitions, information elements, action frames, and
+anything else that can be found in the 802.11 specifications.
+
+The PHY definitions can be found in (ieee80211_phy.c) and (ieee80211_phy.h).
+Notably those include the frame timing information useful for rate control
+and frame duration calculations.
+
+## 802.11 Revisions
+
+(TBD)
+
+### Legacy 802.11
+
+The earliest 802.11 devices implement 1Mbit/s and 2Mbit/s direct spread spectrum
+frames. These include the earliest Wavelan devices. These are grandfathered
+into 802.11b. The PHY specification can be found in 802.11-2020 Section 15.)
+
+### 802.11b
+
+802.11b devices implement Section 15 (1Mbit/2Mbit) PHYs as well as the high
+rate DSSS specification (802.11-2020 Section 16) to provide 5.5Mbit and 11Mbit
+CCK rates. They interoperate with legacy 802.11 devices by using compatible
+PHY encodings and will limit their performance if said legacy devices are
+detected.
+
+### 802.11a
+
+802.11a devices implement OFDM rates from 6Mbit/s to 54Mbit/s on the 5GHz
+band. Among other features, it also defines 5MHz and 10MHz wide channel
+behaviour. This is covered in the OFDM PHY specification (802.11-2020
+Section 17.)
+
+### 802.11g
+
+802.11g devices implement OFDM rates from 802.11a, the CCK rates from 802.11b
+and the DSSS rates from legacy 802.11. These are covered in the ERP
+specification (802.11-2020 Section 18.) There are some MAC extensions for
+negotiating 802.11b / 802.11g interoperability and these are documented
+throughout the MAC specification. This also specifies support for 5MHz and
+10MHz wide channels.
+
+### 802.11n (HT)
+
+802.11n introduced a variety of high throughput rates and feature support
+(hence why it's called HT - high throughput). It introduces higher density
+OFDM rate encodings, 20 and 40MHz wide channels with interoperability for
+earlier devices, packet aggregation via A-MPDU and A-MSDU, MIMO (multiple input,
+multiple output spatial streams), some initial beamforming support, power
+saving extensions and more.
+
+The physical layer support is covered in the HT PHY specification (802.11-2020
+Section 19.) The rest of the MAC extensions are documented throughout the
+rest of the specification.
+
+### 802.11ac (VHT)
+
+802.11ac extends the 802.11n specification (hence why it's VHT - Very
+High Throughput) and boosts performance by adding higher density OFDM QAM
+encoding (256-QAM), wider channels (80MHz, 160MHz), split 80+80MHz channel
+support, much larger A-MSDU / A-MPDU frame sizes, support for MU-MIMO
+(multi-user MIMO) allowing APs to transmit to multiple STAs at the same time
+and various other extensions.
+
+It builds on top of the 802.11n MAC and PHY specification, so a lot of
+802.11n feature and MAC negotiation happens as part of 802.11ac negotiation.
+
+The PHY layer is covered in the VHT PHY Specification (802.11-2020 Section
+21.) Again, the rest of the MAC extensions are documented throughout the
+rest of the specification.
+
+### Greenfield versus backwards compatibility
+
+The various protocols supported by 802.11 build on top of earlier protocols.
+So typically you're not building a single implementation for each protocol -
+for example, you can't handle 802.11ac support without implementing a large
+amount of 802.11n support.
+
+(As a side note, the 802.11 frame has a protocol version field, and
+that actually changed in 802.11ah (900MHz and longer distance bands) -
+which changes a lot of what the fields do. No, net80211 currently does not
+support 802.11ah and will drop frames whose 802.11 protocol ID is not
+supported.)
+
+At the PHY layer, later model hardware can transmit data encodings which
+earlier model hardware just won't recognise. All they'll see is an increase
+in RF power on the channel at best and signals that will confuse the
+RX decoder / cause hardware issues at worst.)
+
+So each of the PHY specifications will lay out a few things:
+
+ * How frames should be encoded in the air in a way that earlier
+ hardware can decode them enough to know it's not for them;
+ * How devices can identify that earlier protocol devices are around and
+ change the configuration (eg STA changing its own configuration,
+ AP changing the configuration of the network it controls, etc)
+ to provide backwards compatibility.
+
+These come at a performance cost. For example, an 802.11g AP which
+supports 802.11b and 802.11 devices needs to notice that an 802.11b
+device wishes to associate, and when it sees this, change some of
+its configuration (notably "long preamble" so 802.11b devices can
+decode frames that are being transmitted, whether destined to it or not.)
+
+Various devices allow backwards compatbility to be configured.
+For example, an 802.11n AP may be configured to deny non-802.11n clients.
+This may improve performance but then earlier clients can't connect.
+
+In 802.11n deployments this was known as a "greenfield deployment".
+This typically disables any and all pre-11n interoperability at both
+a MAC and PHY layer. net80211 has some flags for this to specifically
+inform devices that they can configure the hardware for such a setup.
+Not all drivers implement it however, and in a lot of cases they will
+still handle pre-11n framing, even if the net80211 code will deny
+association.
+
+There are other components to backwards compatibility which are worth
+keeping in mind when reading through the 802.11 specification and
+net80211 stack / driver code. These include:
+
+ * short/long preamble - (vap_update_preamble)
+ * short/long slot time configuration - (vap_update_slot)
+ * 802.11g protection mode (vap_update_erp_protmode) -
+ whether to use CTS-to-self around each transmission
+ * 802.11n protection mode (vap_update_ht_protmode) -
+ whether to use RTS/CTS around each transmission
+ * 802.11n 20/40MHz BSS operation (whether an 802.11n AP sees other APs that
+ overlap its frequency range and need to reconfigure how to protect
+ transmissions)
+
+## How 802.11 (very briefly) works over the air
+
+This is a very brief and not at all comprehensive overview of how 802.11
+works over the air. The goal of this section is to provide enough background
+information to help de-mystify reading the net80211 stack and wireless
+driver source.
+
+### Why there's timing requirements in the first place
+
+Each of the PHY sections in the 802.11 specification describe what
+the PHY needs to do in order to transmit and receive data. It's not
+anywhere as easy as "toggle some bits on a wire".
+
+An important thing to understand is that hardware isn't immediate.
+All the state machines in your 802.11 devices take non-zero time
+to make decisions about when to transmit, when to receive, locking
+onto a signal, deciding it can be decoded, getting reset for the next
+frame, etc.
+
+So a lot of what you'll see in 802.11 negotiation and feature support
+is linked to the underlying hardware implementations and limitations
+of the time. For example the 802.11b specification defines the slot time
+as 20uS, but the 802.11g specification lowers it to 9uS. The "slot time"
+value defines the unit of time used for contention management / backoff, and
+it's defined partly by what the speed of light dictates (ie how big
+of a physical area you want to be able to "hear" in determining if the
+area is busy) and how quickly the hardware can guarantee to respond.
+It dropped to 9uS because hardware got better, but to interoperate
+with older devices without starting to transmit before they're
+ready to react, 802.11g devices will fall back to 20uS slot time when
+they detect an 802.11b device.
+
+This carries through everywhere in odd places that you're not necessarily
+aware of. For example, the 802.11n A-MPDU definition includes negotiated
+padding between frames and limits encryption ciphers (typically CCMP or
+GCMP.) This is due to hardware support - the MAC may be able to support
+much less padding when no encryption is used, but setting up / resetting
+the encryption / decryption blocks may take more time and thus larger
+A-MPDU padding values are negotiated.
+
+### Wait, the speed of light?
+
+Yes. The speed of light is roughly 300 metres for each microsecond of
+travel time.
+
+### Preambles, SIGs, PLCP, sending actual data and waiting / slot times
+
+There are a few things that are worth understanding at a high level.
+
+ * The first thing that a device needs to do is determine
+ whether the air is busy or free. There'll be some hardware
+ to determine the signal level versus noise floor and provide
+ a signal to the transmit hardware that the air is free,
+ and to the receiver that it may want to try start decoding
+ something.
+
+ * The receiver needs to get in synchronisation with the transmitter.
+ This is a one way operation - the transmitter needs to transmit
+ enough of a signal that the receiver can "lock onto" and get itself
+ ready for further data. This is called the "preamble" - it's
+ typically a low bitrate repeating pattern of data that gives
+ the receiver hardware time to lock onto, figure out the signal
+ level and be ready for the next phase.
+
+ * Note that the receiver may pick up the preamble at any point in its
+ transmission so it can't guarantee it will see exactly "x" bits of some
+ repeating pattern.
+
+ * Then there's other bits and pieces - eg look for L-SIG, HT-SIG
+ in the PHY documentation - which is used to further synchronise
+ what's about to happen.
+
+ * Finally it will start transmitting the PHY framing bits needed to
+ identify what the upcoming transmit rate and configuration is
+ (all the stuff leading up to the PLCP header, then the PLCP header.)
+
+Things get more complicated with MIMO, MU-MIMO, 802.11ax OFDM-A, etc but
+don't worry about those for now - they build on top of all of these
+ideas.
+
+Once the data is transmitted, there's some quiet time between frames
+before the receiver can ACK (and then a period of time where an ACK
+is expected.) The transmitter needs to finish transmitting, then
+reset its internal state back to idle to be ready to receive - and
+there's the pesky speed of light speed of 300m per microsecond -
+so there's some MAC (interframe spacing) and PHY (slot time) enforcing
+quiet so everyone has a chance to receive the frame and the reciver
+gets ready to receive. Then if there's an ACK, the ACK happens.
+
+### PLCP header
+
+Once all of the preamble, SIG/training stuff is done, the transmitter
+will send a PLCP header with information about the transmitter
+type and rate (and that's very handwaving it.) net80211 has definitions
+for the plcp header (ieee80211_plcp_hdr) but it's highly unlikely it will
+be relevant or available in modern devices.
+
+### How data is encoded - encoding rates, symbols, guard intervals
+
+Now, once the transmitter has sent all of that, it will start to send
+actual data encoded at the desired transmit rate. The data bits
+that you're transmitting go through a variety of encoding schemes
+before they're turned into bits that are clocked out at the 802.11
+physical layer (think "forward error correction" as an example),
+but they're turned into what are known as "symbols".
+
+A symbol can be thought of as a group of bits encoded in one specific
+RF representation. Explaining all the details isn't in scope of this
+document (and I encourage interested parties to do a quick dive
+into information theory!) but there are a couple of important higher
+level concepts to understand here that influence what happens
+later on in packet delivery.
+
+For OFDM encoding:
+
+ * Each symbol is preceded by a quiet time called a guard interval, to make
+ sure any reflections don't interfere with the upcoming symbol;
+ * Each symbol is then transmitted for a specific length of time to make sure
+ it's received by everyone inside the desired area (again light = 300m/sec
+ per microsecond);
+ * All symbols for a given 802.11 MPDU are sent at the exact same rate;
+ * This is repeated until all the symbols are transmitted.
+
+The higher the data rate used, the higher the signal level needs to be
+and lower the tolerance it has to interference. Forward error correction
+can only do so much, and the higher throughput rate encodings sacrifice
+FEC for throughput.
+
+Once an uncorrectable error occurs and the frame fails CRC, the whole MPDU is
+dropped by the receiver.
+
+Part of why A-MPDU is so important for high throughput is that the
+errors are limited to a single MPDU in the burst of MPDUs. Ie, if
+the transmitter sends ten MPDUs in a single A-MPDU, and five of them
+have uncorrectable errors, then five .. well, didn't. This means
+the receiver can ACK some but not all of the MPDUs, and the transmitter
+can re-send those with new MPDUs.
+
+The default guard interval is 800ns. 802.11n allows for negotiating
+shorter guard interval (400ns) which can be done per device in a BSS.
+An 800ns guard interval is a little short of 300 metres, and 400ns is
+a little short of 150 metres - so using short guard interval means
+you trade increased performance for potential decreased performance
+if you have reflections or stations more than 150 metres away.
+
+802.11ax adds support for 1.6us and 3.2us guard intervals for physically
+larger deployments.
+
+### MAC layer framing
+
+The MAC layer handles data that is encapsulated in the given transmit
+rate that was established in the PHY (PLCP) header. This includes
+the 802.11 MAC header, CRC trailer, any of the cipher processing that
+happens in between. In the case of 802.11n, it can encapsulate
+multiple frames being sent back to back in a single transmission.
+
+Devices which do partial / no offload will typically produce and
+consume 802.11 MAC layer frames to the driver and net80211.
+It's thus important to understand MAC framing and frame types.
+
+### MPDU versus MSDU
+
+An MSDU (MAC service data unit) is an individual frame (think "802.2/802.3
+ethernet") passed from the network stack into net80211.
+
+An MPDU (MAC protocol data unit) is one or more MSDU frames wrapped by an
+(ieee80211_frame) header and CRC trailer. It is what is eventually
+encapsulated inside the PHY framing (preambles, training symbols, PLCP
+header, etc) and sent over the air.
+
+Notably an 802.11 MPDU isn't just an IPv4/IPv6 frame with an 802.11
+header/trailer - it is a full ethernet frame that is being wrapped
+by 802.11 framing.
+
+### Tracking airtime with NAV
+
+802.11 devices have to interoperate in a shared medium. Earlier protocol
+definitions require one transmitter at a time. Later specification
+devices (MU-MIMO with 802.11ac, OFDM-A with 802.11ax, etc) introduce the
+ability for devices to transmit and receive simultaneously.
+
+The simplest way to track this is with NAV (network access vector.)
+The NAV implementation in pre-11ax devices is a single counter which
+counts down to zero. Once it is zero, the air is considered "available"
+to attempt to check to transmit on. The transmitter will also check
+whether the air is busy (ie can it detect any signals present) before
+it transmits - this is called CCA (clear channel access) and is
+typically implemented in hardware.
+
+The duration field in (ieee80211_frame) is a microsecond field which
+covers the whole duration of the frame being transmitted. Receivers
+that decode the frame - even if it's not destined to them! - will listen
+to the NAV and add it to their own NAV.
+
+All 802.11 frames have a duration field.
+
+### Fragmented frames
+
+(TBD)
+
+### Sequence counters and duplication detection
+
+(TBD)
+
+### EDCA and QoS
+
+(TBD)
+
+### Inter-frame spacing (IFS)
+
+(TBD)
+
+## 802.11 frame layout
+
+An individual 802.11 frame contains frame control (version, type, subtype),
+duration, addressing, sequence number and optional QoS information.
+The basic definition is available at (ieee80211_frame) but other definitions
+are also possible - (ieee80211_qosframe), (ieee80211_frame_addr4),
+(ieee80211_qosframe_addr4).
+
+It then has a 4 byte CRC32 trailer appended at the end.
+
+### Addressing types and traffic direction
+
+(TBD - 3addr, 4addr, each of the fields, etc)
+
+### QoS versus non-QoS frames
+
+(TBD)
+
+### RTS/CTS exchange and airtime
+
+(TBD)
+
+### CTS-to-self / OFDM protection
+
+CTS to self is a concept introduced in 802.11g. The general idea is that a
+transmitter can send a CTS to its own MAC address for the duration that it
+wishes to transmit for. Since the CTS frame is transmitted at a slower
+legacy rate, it both reserves airtime in any receiver in earshot, and
+it is understood by older 11b only devices which do not understand 11g.
+
+This ends up also being useful for 11n, 11ac etc to interoperate with
+earlier devices, but they typically rely on a normal RTS exchange.
+
+### Data frames
+
+(TBD)
+
+### Management frames
+
+(TBD)
+
+### Control frames
+
+(TBD)
+
+Notably, control frames do not have a sequence number and so can't be
+de-duplicated.
+
+### Action frames
+
+(TBD)
+
+## Frame combinations
+
+There are various ways that 802.11 frames are combined together to improve
+performance.
+
+### ACK, Delayed Block-ACK, Immediate Block-ACK
+
+(TBD)
+
+### Atheros Fast Frames
+
+(TBD)
+
+### A-MSDU
+
+(TBD)
+
+### A-MPDU
+
+(TBD)
+
+## Security / Encryption
+
+This is a much larger topic, however it's worth touching on the basics here to
+understand how frames are redirected into the security/encryption paths in
+net80211 and what devices may do with said frames.
+
+### WEP, IV header and keys
+
+WEP is an obsolete encryption method dating back to the earliest 802.11b
+specifications. It involves a 4 byte header which includes
+
+ * a 24 bit IV (initialisation vector);
+ * a 2 bit field indication which of four keys to use;
+ * A CRC at the end.
+
+It's relevant today because later cipher frame formats still use the IV
+header - they're just extended to include more information. Notably, the
+four key indexes are typically implemented and used in hardware, and have
+different meanings depending upon the kind of traffic being handled.
+
+### WPA/WPA2 management
+
+This is handled in userland. The 802.11 specification covers everything
+involved in key exchange and management but it's out of scope for this 802.11
+overview documentation.
+
+### CCMP, GCMP, TKIP frames
+
+These later ciphers still use the WEP header, but they then add extra bytes
+to it to include the larger sequence number space, other options needed
+for said ciphers, and a larger trailer for CRC and TKIP MIC.
+
+### IV duplication / tracking
+
+net80211 tracks the received IV / sequence number for each station indexed
+by QoS TID. Anything with an earlier IV is discarded as a stale packet or
+potential replay attack. See the ni_txseqs[] and ni_rxseqs[] field in
+(ieee80211_node).
+
+Note that the 802.11 layer sequence number field will apply /first/. Traffic
+which the 802.11 input layer thinks is old or retransmits will be discarded
+before handed to the net80211 crypto routines.
+
+### Unicast vs Group Keys
+
+WEP has four global keys which are shared between all devices wishing to
+communicate. The keys are provided in the WEP header.
+
+However for later ciphers the four key indexes start taking on new meanings.
+Notably key index 0 is the "unicast key" which handles traffic for a given
+station and is unique for that station, and keys 2 and 3 are used for
+group keys - shared keys for broadcast traffic that all stations need to be
+able to decrypt.
+
+(key 1 is also used for unicast station traffic for seamless station key
+updating, but net80211 currently doesn't support this extension/feature.)
+
+There's also upcoming work for encrypted management traffic and encrypted
+beacons which reuse the key indexes for their traffic, but then don't treat
+them as "global keys" - they start being treated as "global keys but only
+for this traffic type."
+
+It's important to understand the difference between global keys (WEP) versus
+group and unicast keys (everything else) when looking through the net80211
+data and encryption handling paths.
+
+## 802.11 Operating Modes
+
+(TBD)
+
+### Station
+
+(TBD)
+
+### Access Point
+
+(TBD)
+
+### IBSS / Ad-Hoc
+
+(TBD)
+
+### Mesh / 802.11s
+
+(TBD)
diff --git a/sys/net80211/README.md b/sys/net80211/README.md
new file mode 100644
--- /dev/null
+++ b/sys/net80211/README.md
@@ -0,0 +1,139 @@
+# net80211
+
+This is the 802.11 wireless stack for FreeBSD.
+
+## Introduction
+
+The net80211 subsystem implements the 802.11 protocol and support infrastructure.
+It supports a variety of device types, 802.11 protocols, operating modes and
+security extensions.
+
+net80211 handles the 802.11 state machine, interface management, node management,
+virtual interfaces, packet encapsulation and de-encapsulation and basic
+security key management.
+
+The userland ioctl() API provides control mechanisms for the above and is how
+management tooling (ifconfig, libifconfig) and management services (hostapd,
+wpa_supplicant) interfaces with the net80211 stack.
+
+The security state machine and key management (802.1x, WPA, etc) are handled
+by management services.
+
+Drivers can implement as much or as little of the 802.11 infrastructure as
+needed. net80211 support drivers from full-offload (ie, supplying ethernet
+encapsulated/de-encapsulated frames with management control via driver
+methods) down to fully software controlled devices (ie, the hardware
+is minimal and all 802.11 packet handling, state machine, reordering, security,
+etc is handled by net80211.)
+
+## Overview
+
+net80211 consists of a few top level design modules:
+
+ * The 802.11 device representation and functions (ieee80211com), used
+ in conjunction with an 802.11 device driver to represent the physical device.
+
+ * The 802.11 virtual interface representation and functions (ieee80211vap),
+ used to represent instances of virtual interfaces.
+
+ * A representation of 802.11 stations/nodes (ieee80211_node), which
+ keep the state of each 802.11 station/node that the stack knows about.
+
+ * Encryption handling (ieee80211_crypto), handling 802.11 frame encryption,
+ decryption and session/state tracking.
+
+ * Regulatory domain (ieee80211_regdomain), which implements the 802.11
+ regulatory domains, allowed frequencies, operating modes and transmit power.
+
+ * Radar detection (ieee80211_dfs.c), tracking the state of radar detection and
+ interoperability in the 5GHz frequency range.
+
+ * Transmit rate control (ieee80211_ratectl.c) implements software and
+ firmware based rate control for devices that don't implement full rate control
+ offload.
+
+ * Power save support (ieee82011_power.c) implements various power saving
+ mode features and support for devices which do not fully implement offloaded
+ power management.
+
+ * Operating system specific interfaces (ieee80211_freebsd.c) which implement
+ the bulk of the operating system specific glue (logging, memory allocation,
+ network interfaces, etc.)
+
+ * The configuration interface (ieee80211_ioctl.c) which implements the ioctl
+ API used by userland to configure and monitor the state of the 802.11 stack
+ and devices.
+
+In addition, each operating mode (adhoc, station, AP, WDS, mesh) have their own
+modules that implement the state machines and functionality required for 802.11.
+
+## Portability
+
+Although net80211 attempts to keep most OS specific components in a single file
+(ieee80211_freebsd.c), it is not currently perfect.
+
+Notably:
+
+ * There are still plenty of FreeBSD-isms located throughout the source code,
+ including BSD specific includes, network APIs, etc.
+
+ * The interface and networking model is still very BSD, including using the
+ system implementation of mbufs.
+
+When developing for net80211 please keep in mind that other operating systems
+(such as DragonflyBSD) and third parties do leverage this codebase.
+Try to keep all FreeBSD specific components in ieee80211_freebsd.[ch].
+
+## Protocol Overview
+
+A basic protocol overview is available at (@ref md_net80211_PROTOCOL).
+
+The most comprehensive overview is the 802.11 protocol document itself,
+but it is very large and implementations do not always correspond 1:1
+with the protocol definitions.
+
+## Functional Overview
+
+(TODO)
+
+ * Module layout
+ * Logging
+ * Debugging - (@ref md_net80211_DEBUG)
+ * Top-level device layout (ieee80211com)
+ * Data / Control Path Overview
+ * Deferred work
+ * Regulatory
+ * Virtual interfaces
+ * Operating Modes
+ * Nodes
+ * Node tables, node table iteration
+ * Device and VAP states
+ * Node states
+ * Operating modes
+ * Cipher management
+ * Radar detection
+ * ioctl interface
+ * ACL support
+ * Scanning, Scan Modules
+ * Power Management
+ * Transmit Path
+ * Receive Path
+ * A-MSDU Fast Frames
+ * A-MPDU
+ * Radiotap
+ * Monitor Mode
+
+## Driver Overview
+
+(TODO)
+
+ * Introduction
+ * Driver Structure
+ * Setup and Attach
+ * Virtual Interfaces
+ * Control Path
+ * Data Path
+ * VAP state
+ * Device State
+ * Suspend and Resume
+
diff --git a/tools/kerneldoc/subsys/Doxyfile-net80211 b/tools/kerneldoc/subsys/Doxyfile-net80211
--- a/tools/kerneldoc/subsys/Doxyfile-net80211
+++ b/tools/kerneldoc/subsys/Doxyfile-net80211
@@ -9,7 +9,8 @@
#--------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
-INPUT = $(DOXYGEN_SRC_PATH)/net80211/ $(NOTREVIEWED)
+INPUT = $(DOXYGEN_SRC_PATH)/net80211/
+USE_MDFILE_AS_MAINPAGE = $(DOXYGEN_SRC_PATH)/net80211/README.md
GENERATE_TAGFILE = net80211/net80211.tag

File Metadata

Mime Type
text/plain
Expires
Thu, May 21, 8:49 PM (8 h, 40 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
33404705
Default Alt Text
D56760.id177021.diff (33 KB)

Event Timeline