README.md
1# net80211
2
3This is the 802.11 wireless stack for FreeBSD.
4
5## Introduction
6
7The net80211 subsystem implements the 802.11 protocol and support infrastructure.
8It supports a variety of device types, 802.11 protocols, operating modes and
9security extensions.
10
11net80211 handles the 802.11 state machine, interface management, node management,
12virtual interfaces, packet encapsulation and de-encapsulation and basic
13security key management.
14
15The userland ioctl() API provides control mechanisms for the above and is how
16management tooling (ifconfig, libifconfig) and management services (hostapd,
17wpa_supplicant) interfaces with the net80211 stack.
18
19The security state machine and key management (802.1x, WPA, etc) are handled
20by management services.
21
22Drivers can implement as much or as little of the 802.11 infrastructure as
23needed. net80211 support drivers from full-offload (ie, supplying ethernet
24encapsulated/de-encapsulated frames with management control via driver
25methods) down to fully software controlled devices (ie, the hardware
26is minimal and all 802.11 packet handling, state machine, reordering, security,
27etc is handled by net80211.)
28
29## Overview
30
31net80211 consists of a few top level design modules:
32
33 * The 802.11 device representation and functions (ieee80211com), used
34 in conjunction with an 802.11 device driver to represent the physical device.
35
36 * The 802.11 virtual interface representation and functions (ieee80211vap),
37 used to represent instances of virtual interfaces.
38
39 * A representation of 802.11 stations/nodes (ieee80211_node), which
40 keep the state of each 802.11 station/node that the stack knows about.
41
42 * Encryption handling (ieee80211_crypto), handling 802.11 frame encryption,
43 decryption and session/state tracking.
44
45 * Regulatory domain (ieee80211_regdomain), which implements the 802.11
46 regulatory domains, allowed frequencies, operating modes and transmit power.
47
48 * Radar detection (ieee80211_dfs.c), tracking the state of radar detection and
49 interoperability in the 5GHz frequency range.
50
51 * Transmit rate control (ieee80211_ratectl.c) implements software and
52 firmware based rate control for devices that don't implement full rate control
53 offload.
54
55 * Power save support (ieee82011_power.c) implements various power saving
56 mode features and support for devices which do not fully implement offloaded
57 power management.
58
59 * Operating system specific interfaces (ieee80211_freebsd.c) which implement
60 the bulk of the operating system specific glue (logging, memory allocation,
61 network interfaces, etc.)
62
63 * The configuration interface (ieee80211_ioctl.c) which implements the ioctl
64 API used by userland to configure and monitor the state of the 802.11 stack
65 and devices.
66
67In addition, each operating mode (adhoc, station, AP, WDS, mesh) have their own
68modules that implement the state machines and functionality required for 802.11.
69
70## Portability
71
72Although net80211 attempts to keep most OS specific components in a single file
73(ieee80211_freebsd.c), it is not currently perfect.
74
75Notably:
76
77 * There are still plenty of FreeBSD-isms located throughout the source code,
78 including BSD specific includes, network APIs, etc.
79
80 * The interface and networking model is still very BSD, including using the
81 system implementation of mbufs.
82
83When developing for net80211 please keep in mind that other operating systems
84(such as DragonflyBSD) and third parties do leverage this codebase.
85Try to keep all FreeBSD specific components in ieee80211_freebsd.[ch].
86
87## Protocol Overview
88
89A basic protocol overview is available at (@ref md_net80211_PROTOCOL).
90
91The most comprehensive overview is the 802.11 protocol document itself,
92but it is very large and implementations do not always correspond 1:1
93with the protocol definitions.
94
95## Functional Overview
96
97(TODO)
98
99 * Module layout
100 * Logging
101 * Debugging - (@ref md_net80211_DEBUG)
102 * Top-level device layout (ieee80211com)
103 * Data / Control Path Overview (@ref md_net80211_DATAPATH_TRANSMIT), (@ref md_net80211_DATAPATH_RECEIVE)
104 * Deferred work (@ref md_net80211_DEFERRED_WORK)
105 * Regulatory
106 * Virtual interfaces
107 * Operating Modes
108 * Nodes
109 * Node tables, node table iteration
110 * Device and VAP states
111 * Node states
112 * Operating modes
113 * Cipher management
114 * Radar detection
115 * ioctl interface
116 * ACL support
117 * Scanning, Scan Modules
118 * Power Management
119 * Transmit Path
120 * Receive Path
121 * A-MSDU Fast Frames
122 * A-MPDU
123 * Radiotap
124 * Monitor Mode
125
126## Driver Overview
127
128(TODO)
129
130 * Introduction
131 * Driver Structure
132 * Setup and Attach
133 * Virtual Interfaces
134 * Control Path
135 * Data Path
136 * VAP state
137 * Device State
138 * Suspend and Resume
139
140