tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4<set>
5 <setinfo>
6 <title>The 802.11 subsystems – for kernel developers</title>
7 <subtitle>
8 Explaining wireless 802.11 networking in the Linux kernel
9 </subtitle>
10
11 <copyright>
12 <year>2007-2009</year>
13 <holder>Johannes Berg</holder>
14 </copyright>
15
16 <authorgroup>
17 <author>
18 <firstname>Johannes</firstname>
19 <surname>Berg</surname>
20 <affiliation>
21 <address><email>johannes@sipsolutions.net</email></address>
22 </affiliation>
23 </author>
24 </authorgroup>
25
26 <legalnotice>
27 <para>
28 This documentation is free software; you can redistribute
29 it and/or modify it under the terms of the GNU General Public
30 License version 2 as published by the Free Software Foundation.
31 </para>
32 <para>
33 This documentation is distributed in the hope that it will be
34 useful, but WITHOUT ANY WARRANTY; without even the implied
35 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
36 See the GNU General Public License for more details.
37 </para>
38 <para>
39 You should have received a copy of the GNU General Public
40 License along with this documentation; if not, write to the Free
41 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
42 MA 02111-1307 USA
43 </para>
44 <para>
45 For more details see the file COPYING in the source
46 distribution of Linux.
47 </para>
48 </legalnotice>
49
50 <abstract>
51 <para>
52 These books attempt to give a description of the
53 various subsystems that play a role in 802.11 wireless
54 networking in Linux. Since these books are for kernel
55 developers they attempts to document the structures
56 and functions used in the kernel as well as giving a
57 higher-level overview.
58 </para>
59 <para>
60 The reader is expected to be familiar with the 802.11
61 standard as published by the IEEE in 802.11-2007 (or
62 possibly later versions). References to this standard
63 will be given as "802.11-2007 8.1.5".
64 </para>
65 </abstract>
66 </setinfo>
67 <book id="cfg80211-developers-guide">
68 <bookinfo>
69 <title>The cfg80211 subsystem</title>
70
71 <abstract>
72!Pinclude/net/cfg80211.h Introduction
73 </abstract>
74 </bookinfo>
75 <chapter>
76 <title>Device registration</title>
77!Pinclude/net/cfg80211.h Device registration
78!Finclude/net/cfg80211.h ieee80211_band
79!Finclude/net/cfg80211.h ieee80211_channel_flags
80!Finclude/net/cfg80211.h ieee80211_channel
81!Finclude/net/cfg80211.h ieee80211_rate_flags
82!Finclude/net/cfg80211.h ieee80211_rate
83!Finclude/net/cfg80211.h ieee80211_sta_ht_cap
84!Finclude/net/cfg80211.h ieee80211_supported_band
85!Finclude/net/cfg80211.h cfg80211_signal_type
86!Finclude/net/cfg80211.h wiphy_params_flags
87!Finclude/net/cfg80211.h wiphy_flags
88!Finclude/net/cfg80211.h wiphy
89!Finclude/net/cfg80211.h wireless_dev
90!Finclude/net/cfg80211.h wiphy_new
91!Finclude/net/cfg80211.h wiphy_register
92!Finclude/net/cfg80211.h wiphy_unregister
93!Finclude/net/cfg80211.h wiphy_free
94
95!Finclude/net/cfg80211.h wiphy_name
96!Finclude/net/cfg80211.h wiphy_dev
97!Finclude/net/cfg80211.h wiphy_priv
98!Finclude/net/cfg80211.h priv_to_wiphy
99!Finclude/net/cfg80211.h set_wiphy_dev
100!Finclude/net/cfg80211.h wdev_priv
101 </chapter>
102 <chapter>
103 <title>Actions and configuration</title>
104!Pinclude/net/cfg80211.h Actions and configuration
105!Finclude/net/cfg80211.h cfg80211_ops
106!Finclude/net/cfg80211.h vif_params
107!Finclude/net/cfg80211.h key_params
108!Finclude/net/cfg80211.h survey_info_flags
109!Finclude/net/cfg80211.h survey_info
110!Finclude/net/cfg80211.h cfg80211_beacon_data
111!Finclude/net/cfg80211.h cfg80211_ap_settings
112!Finclude/net/cfg80211.h station_parameters
113!Finclude/net/cfg80211.h station_info_flags
114!Finclude/net/cfg80211.h rate_info_flags
115!Finclude/net/cfg80211.h rate_info
116!Finclude/net/cfg80211.h station_info
117!Finclude/net/cfg80211.h monitor_flags
118!Finclude/net/cfg80211.h mpath_info_flags
119!Finclude/net/cfg80211.h mpath_info
120!Finclude/net/cfg80211.h bss_parameters
121!Finclude/net/cfg80211.h ieee80211_txq_params
122!Finclude/net/cfg80211.h cfg80211_crypto_settings
123!Finclude/net/cfg80211.h cfg80211_auth_request
124!Finclude/net/cfg80211.h cfg80211_assoc_request
125!Finclude/net/cfg80211.h cfg80211_deauth_request
126!Finclude/net/cfg80211.h cfg80211_disassoc_request
127!Finclude/net/cfg80211.h cfg80211_ibss_params
128!Finclude/net/cfg80211.h cfg80211_connect_params
129!Finclude/net/cfg80211.h cfg80211_pmksa
130!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt
131!Finclude/net/cfg80211.h cfg80211_auth_timeout
132!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp
133!Finclude/net/cfg80211.h cfg80211_assoc_timeout
134!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt
135!Finclude/net/cfg80211.h cfg80211_ibss_joined
136!Finclude/net/cfg80211.h cfg80211_connect_result
137!Finclude/net/cfg80211.h cfg80211_roamed
138!Finclude/net/cfg80211.h cfg80211_disconnected
139!Finclude/net/cfg80211.h cfg80211_ready_on_channel
140!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired
141!Finclude/net/cfg80211.h cfg80211_new_sta
142!Finclude/net/cfg80211.h cfg80211_rx_mgmt
143!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status
144!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify
145!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify
146!Finclude/net/cfg80211.h cfg80211_michael_mic_failure
147 </chapter>
148 <chapter>
149 <title>Scanning and BSS list handling</title>
150!Pinclude/net/cfg80211.h Scanning and BSS list handling
151!Finclude/net/cfg80211.h cfg80211_ssid
152!Finclude/net/cfg80211.h cfg80211_scan_request
153!Finclude/net/cfg80211.h cfg80211_scan_done
154!Finclude/net/cfg80211.h cfg80211_bss
155!Finclude/net/cfg80211.h cfg80211_inform_bss_frame
156!Finclude/net/cfg80211.h cfg80211_inform_bss
157!Finclude/net/cfg80211.h cfg80211_unlink_bss
158!Finclude/net/cfg80211.h cfg80211_find_ie
159!Finclude/net/cfg80211.h ieee80211_bss_get_ie
160 </chapter>
161 <chapter>
162 <title>Utility functions</title>
163!Pinclude/net/cfg80211.h Utility functions
164!Finclude/net/cfg80211.h ieee80211_channel_to_frequency
165!Finclude/net/cfg80211.h ieee80211_frequency_to_channel
166!Finclude/net/cfg80211.h ieee80211_get_channel
167!Finclude/net/cfg80211.h ieee80211_get_response_rate
168!Finclude/net/cfg80211.h ieee80211_hdrlen
169!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb
170!Finclude/net/cfg80211.h ieee80211_radiotap_iterator
171 </chapter>
172 <chapter>
173 <title>Data path helpers</title>
174!Pinclude/net/cfg80211.h Data path helpers
175!Finclude/net/cfg80211.h ieee80211_data_to_8023
176!Finclude/net/cfg80211.h ieee80211_data_from_8023
177!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s
178!Finclude/net/cfg80211.h cfg80211_classify8021d
179 </chapter>
180 <chapter>
181 <title>Regulatory enforcement infrastructure</title>
182!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure
183!Finclude/net/cfg80211.h regulatory_hint
184!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory
185!Finclude/net/cfg80211.h freq_reg_info
186 </chapter>
187 <chapter>
188 <title>RFkill integration</title>
189!Pinclude/net/cfg80211.h RFkill integration
190!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state
191!Finclude/net/cfg80211.h wiphy_rfkill_start_polling
192!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling
193 </chapter>
194 <chapter>
195 <title>Test mode</title>
196!Pinclude/net/cfg80211.h Test mode
197!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb
198!Finclude/net/cfg80211.h cfg80211_testmode_reply
199!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb
200!Finclude/net/cfg80211.h cfg80211_testmode_event
201 </chapter>
202 </book>
203 <book id="mac80211-developers-guide">
204 <bookinfo>
205 <title>The mac80211 subsystem</title>
206 <abstract>
207!Pinclude/net/mac80211.h Introduction
208!Pinclude/net/mac80211.h Warning
209 </abstract>
210 </bookinfo>
211
212 <toc></toc>
213
214 <!--
215 Generally, this document shall be ordered by increasing complexity.
216 It is important to note that readers should be able to read only
217 the first few sections to get a working driver and only advanced
218 usage should require reading the full document.
219 -->
220
221 <part>
222 <title>The basic mac80211 driver interface</title>
223 <partintro>
224 <para>
225 You should read and understand the information contained
226 within this part of the book while implementing a driver.
227 In some chapters, advanced usage is noted, that may be
228 skipped at first.
229 </para>
230 <para>
231 This part of the book only covers station and monitor mode
232 functionality, additional information required to implement
233 the other modes is covered in the second part of the book.
234 </para>
235 </partintro>
236
237 <chapter id="basics">
238 <title>Basic hardware handling</title>
239 <para>TBD</para>
240 <para>
241 This chapter shall contain information on getting a hw
242 struct allocated and registered with mac80211.
243 </para>
244 <para>
245 Since it is required to allocate rates/modes before registering
246 a hw struct, this chapter shall also contain information on setting
247 up the rate/mode structs.
248 </para>
249 <para>
250 Additionally, some discussion about the callbacks and
251 the general programming model should be in here, including
252 the definition of ieee80211_ops which will be referred to
253 a lot.
254 </para>
255 <para>
256 Finally, a discussion of hardware capabilities should be done
257 with references to other parts of the book.
258 </para>
259 <!-- intentionally multiple !F lines to get proper order -->
260!Finclude/net/mac80211.h ieee80211_hw
261!Finclude/net/mac80211.h ieee80211_hw_flags
262!Finclude/net/mac80211.h SET_IEEE80211_DEV
263!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
264!Finclude/net/mac80211.h ieee80211_ops
265!Finclude/net/mac80211.h ieee80211_alloc_hw
266!Finclude/net/mac80211.h ieee80211_register_hw
267!Finclude/net/mac80211.h ieee80211_unregister_hw
268!Finclude/net/mac80211.h ieee80211_free_hw
269 </chapter>
270
271 <chapter id="phy-handling">
272 <title>PHY configuration</title>
273 <para>TBD</para>
274 <para>
275 This chapter should describe PHY handling including
276 start/stop callbacks and the various structures used.
277 </para>
278!Finclude/net/mac80211.h ieee80211_conf
279!Finclude/net/mac80211.h ieee80211_conf_flags
280 </chapter>
281
282 <chapter id="iface-handling">
283 <title>Virtual interfaces</title>
284 <para>TBD</para>
285 <para>
286 This chapter should describe virtual interface basics
287 that are relevant to the driver (VLANs, MGMT etc are not.)
288 It should explain the use of the add_iface/remove_iface
289 callbacks as well as the interface configuration callbacks.
290 </para>
291 <para>Things related to AP mode should be discussed there.</para>
292 <para>
293 Things related to supporting multiple interfaces should be
294 in the appropriate chapter, a BIG FAT note should be here about
295 this though and the recommendation to allow only a single
296 interface in STA mode at first!
297 </para>
298!Finclude/net/mac80211.h ieee80211_vif
299 </chapter>
300
301 <chapter id="rx-tx">
302 <title>Receive and transmit processing</title>
303 <sect1>
304 <title>what should be here</title>
305 <para>TBD</para>
306 <para>
307 This should describe the receive and transmit
308 paths in mac80211/the drivers as well as
309 transmit status handling.
310 </para>
311 </sect1>
312 <sect1>
313 <title>Frame format</title>
314!Pinclude/net/mac80211.h Frame format
315 </sect1>
316 <sect1>
317 <title>Packet alignment</title>
318!Pnet/mac80211/rx.c Packet alignment
319 </sect1>
320 <sect1>
321 <title>Calling into mac80211 from interrupts</title>
322!Pinclude/net/mac80211.h Calling mac80211 from interrupts
323 </sect1>
324 <sect1>
325 <title>functions/definitions</title>
326!Finclude/net/mac80211.h ieee80211_rx_status
327!Finclude/net/mac80211.h mac80211_rx_flags
328!Finclude/net/mac80211.h mac80211_tx_control_flags
329!Finclude/net/mac80211.h mac80211_rate_control_flags
330!Finclude/net/mac80211.h ieee80211_tx_rate
331!Finclude/net/mac80211.h ieee80211_tx_info
332!Finclude/net/mac80211.h ieee80211_tx_info_clear_status
333!Finclude/net/mac80211.h ieee80211_rx
334!Finclude/net/mac80211.h ieee80211_rx_ni
335!Finclude/net/mac80211.h ieee80211_rx_irqsafe
336!Finclude/net/mac80211.h ieee80211_tx_status
337!Finclude/net/mac80211.h ieee80211_tx_status_ni
338!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
339!Finclude/net/mac80211.h ieee80211_rts_get
340!Finclude/net/mac80211.h ieee80211_rts_duration
341!Finclude/net/mac80211.h ieee80211_ctstoself_get
342!Finclude/net/mac80211.h ieee80211_ctstoself_duration
343!Finclude/net/mac80211.h ieee80211_generic_frame_duration
344!Finclude/net/mac80211.h ieee80211_wake_queue
345!Finclude/net/mac80211.h ieee80211_stop_queue
346!Finclude/net/mac80211.h ieee80211_wake_queues
347!Finclude/net/mac80211.h ieee80211_stop_queues
348!Finclude/net/mac80211.h ieee80211_queue_stopped
349 </sect1>
350 </chapter>
351
352 <chapter id="filters">
353 <title>Frame filtering</title>
354!Pinclude/net/mac80211.h Frame filtering
355!Finclude/net/mac80211.h ieee80211_filter_flags
356 </chapter>
357
358 <chapter id="workqueue">
359 <title>The mac80211 workqueue</title>
360!Pinclude/net/mac80211.h mac80211 workqueue
361!Finclude/net/mac80211.h ieee80211_queue_work
362!Finclude/net/mac80211.h ieee80211_queue_delayed_work
363 </chapter>
364 </part>
365
366 <part id="advanced">
367 <title>Advanced driver interface</title>
368 <partintro>
369 <para>
370 Information contained within this part of the book is
371 of interest only for advanced interaction of mac80211
372 with drivers to exploit more hardware capabilities and
373 improve performance.
374 </para>
375 </partintro>
376
377 <chapter id="led-support">
378 <title>LED support</title>
379 <para>
380 Mac80211 supports various ways of blinking LEDs. Wherever possible,
381 device LEDs should be exposed as LED class devices and hooked up to
382 the appropriate trigger, which will then be triggered appropriately
383 by mac80211.
384 </para>
385!Finclude/net/mac80211.h ieee80211_get_tx_led_name
386!Finclude/net/mac80211.h ieee80211_get_rx_led_name
387!Finclude/net/mac80211.h ieee80211_get_assoc_led_name
388!Finclude/net/mac80211.h ieee80211_get_radio_led_name
389!Finclude/net/mac80211.h ieee80211_tpt_blink
390!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags
391!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger
392 </chapter>
393
394 <chapter id="hardware-crypto-offload">
395 <title>Hardware crypto acceleration</title>
396!Pinclude/net/mac80211.h Hardware crypto acceleration
397 <!-- intentionally multiple !F lines to get proper order -->
398!Finclude/net/mac80211.h set_key_cmd
399!Finclude/net/mac80211.h ieee80211_key_conf
400!Finclude/net/mac80211.h ieee80211_key_flags
401!Finclude/net/mac80211.h ieee80211_get_tkip_p1k
402!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv
403!Finclude/net/mac80211.h ieee80211_get_tkip_p2k
404 </chapter>
405
406 <chapter id="powersave">
407 <title>Powersave support</title>
408!Pinclude/net/mac80211.h Powersave support
409 </chapter>
410
411 <chapter id="beacon-filter">
412 <title>Beacon filter support</title>
413!Pinclude/net/mac80211.h Beacon filter support
414!Finclude/net/mac80211.h ieee80211_beacon_loss
415 </chapter>
416
417 <chapter id="qos">
418 <title>Multiple queues and QoS support</title>
419 <para>TBD</para>
420!Finclude/net/mac80211.h ieee80211_tx_queue_params
421 </chapter>
422
423 <chapter id="AP">
424 <title>Access point mode support</title>
425 <para>TBD</para>
426 <para>Some parts of the if_conf should be discussed here instead</para>
427 <para>
428 Insert notes about VLAN interfaces with hw crypto here or
429 in the hw crypto chapter.
430 </para>
431 <section id="ps-client">
432 <title>support for powersaving clients</title>
433!Pinclude/net/mac80211.h AP support for powersaving clients
434 </section>
435!Finclude/net/mac80211.h ieee80211_get_buffered_bc
436!Finclude/net/mac80211.h ieee80211_beacon_get
437!Finclude/net/mac80211.h ieee80211_sta_eosp
438!Finclude/net/mac80211.h ieee80211_frame_release_type
439!Finclude/net/mac80211.h ieee80211_sta_ps_transition
440!Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni
441!Finclude/net/mac80211.h ieee80211_sta_set_buffered
442!Finclude/net/mac80211.h ieee80211_sta_block_awake
443 </chapter>
444
445 <chapter id="multi-iface">
446 <title>Supporting multiple virtual interfaces</title>
447 <para>TBD</para>
448 <para>
449 Note: WDS with identical MAC address should almost always be OK
450 </para>
451 <para>
452 Insert notes about having multiple virtual interfaces with
453 different MAC addresses here, note which configurations are
454 supported by mac80211, add notes about supporting hw crypto
455 with it.
456 </para>
457!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces
458!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic
459 </chapter>
460
461 <chapter id="station-handling">
462 <title>Station handling</title>
463 <para>TODO</para>
464!Finclude/net/mac80211.h ieee80211_sta
465!Finclude/net/mac80211.h sta_notify_cmd
466!Finclude/net/mac80211.h ieee80211_find_sta
467!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr
468 </chapter>
469
470 <chapter id="hardware-scan-offload">
471 <title>Hardware scan offload</title>
472 <para>TBD</para>
473!Finclude/net/mac80211.h ieee80211_scan_completed
474 </chapter>
475
476 <chapter id="aggregation">
477 <title>Aggregation</title>
478 <sect1>
479 <title>TX A-MPDU aggregation</title>
480!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation
481!Cnet/mac80211/agg-tx.c
482 </sect1>
483 <sect1>
484 <title>RX A-MPDU aggregation</title>
485!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation
486!Cnet/mac80211/agg-rx.c
487 </sect1>
488!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action
489 </chapter>
490
491 <chapter id="smps">
492 <title>Spatial Multiplexing Powersave (SMPS)</title>
493!Pinclude/net/mac80211.h Spatial multiplexing power save
494!Finclude/net/mac80211.h ieee80211_request_smps
495!Finclude/net/mac80211.h ieee80211_smps_mode
496 </chapter>
497 </part>
498
499 <part id="rate-control">
500 <title>Rate control interface</title>
501 <partintro>
502 <para>TBD</para>
503 <para>
504 This part of the book describes the rate control algorithm
505 interface and how it relates to mac80211 and drivers.
506 </para>
507 </partintro>
508 <chapter id="ratecontrol-api">
509 <title>Rate Control API</title>
510 <para>TBD</para>
511!Finclude/net/mac80211.h ieee80211_start_tx_ba_session
512!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe
513!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session
514!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe
515!Finclude/net/mac80211.h ieee80211_rate_control_changed
516!Finclude/net/mac80211.h ieee80211_tx_rate_control
517!Finclude/net/mac80211.h rate_control_send_low
518 </chapter>
519 </part>
520
521 <part id="internal">
522 <title>Internals</title>
523 <partintro>
524 <para>TBD</para>
525 <para>
526 This part of the book describes mac80211 internals.
527 </para>
528 </partintro>
529
530 <chapter id="key-handling">
531 <title>Key handling</title>
532 <sect1>
533 <title>Key handling basics</title>
534!Pnet/mac80211/key.c Key handling basics
535 </sect1>
536 <sect1>
537 <title>MORE TBD</title>
538 <para>TBD</para>
539 </sect1>
540 </chapter>
541
542 <chapter id="rx-processing">
543 <title>Receive processing</title>
544 <para>TBD</para>
545 </chapter>
546
547 <chapter id="tx-processing">
548 <title>Transmit processing</title>
549 <para>TBD</para>
550 </chapter>
551
552 <chapter id="sta-info">
553 <title>Station info handling</title>
554 <sect1>
555 <title>Programming information</title>
556!Fnet/mac80211/sta_info.h sta_info
557!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
558 </sect1>
559 <sect1>
560 <title>STA information lifetime rules</title>
561!Pnet/mac80211/sta_info.c STA information lifetime rules
562 </sect1>
563 </chapter>
564
565 <chapter id="aggregation-internals">
566 <title>Aggregation</title>
567!Fnet/mac80211/sta_info.h sta_ampdu_mlme
568!Fnet/mac80211/sta_info.h tid_ampdu_tx
569!Fnet/mac80211/sta_info.h tid_ampdu_rx
570 </chapter>
571
572 <chapter id="synchronisation">
573 <title>Synchronisation</title>
574 <para>TBD</para>
575 <para>Locking, lots of RCU</para>
576 </chapter>
577 </part>
578 </book>
579</set>