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 &ndash; 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!Finclude/net/cfg80211.h ieee80211_iface_limit
102!Finclude/net/cfg80211.h ieee80211_iface_combination
103!Finclude/net/cfg80211.h cfg80211_check_combinations
104      </chapter>
105      <chapter>
106      <title>Actions and configuration</title>
107!Pinclude/net/cfg80211.h Actions and configuration
108!Finclude/net/cfg80211.h cfg80211_ops
109!Finclude/net/cfg80211.h vif_params
110!Finclude/net/cfg80211.h key_params
111!Finclude/net/cfg80211.h survey_info_flags
112!Finclude/net/cfg80211.h survey_info
113!Finclude/net/cfg80211.h cfg80211_beacon_data
114!Finclude/net/cfg80211.h cfg80211_ap_settings
115!Finclude/net/cfg80211.h station_parameters
116!Finclude/net/cfg80211.h rate_info_flags
117!Finclude/net/cfg80211.h rate_info
118!Finclude/net/cfg80211.h station_info
119!Finclude/net/cfg80211.h monitor_flags
120!Finclude/net/cfg80211.h mpath_info_flags
121!Finclude/net/cfg80211.h mpath_info
122!Finclude/net/cfg80211.h bss_parameters
123!Finclude/net/cfg80211.h ieee80211_txq_params
124!Finclude/net/cfg80211.h cfg80211_crypto_settings
125!Finclude/net/cfg80211.h cfg80211_auth_request
126!Finclude/net/cfg80211.h cfg80211_assoc_request
127!Finclude/net/cfg80211.h cfg80211_deauth_request
128!Finclude/net/cfg80211.h cfg80211_disassoc_request
129!Finclude/net/cfg80211.h cfg80211_ibss_params
130!Finclude/net/cfg80211.h cfg80211_connect_params
131!Finclude/net/cfg80211.h cfg80211_pmksa
132!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt
133!Finclude/net/cfg80211.h cfg80211_auth_timeout
134!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp
135!Finclude/net/cfg80211.h cfg80211_assoc_timeout
136!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt
137!Finclude/net/cfg80211.h cfg80211_ibss_joined
138!Finclude/net/cfg80211.h cfg80211_connect_result
139!Finclude/net/cfg80211.h cfg80211_roamed
140!Finclude/net/cfg80211.h cfg80211_disconnected
141!Finclude/net/cfg80211.h cfg80211_ready_on_channel
142!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired
143!Finclude/net/cfg80211.h cfg80211_new_sta
144!Finclude/net/cfg80211.h cfg80211_rx_mgmt
145!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status
146!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify
147!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify
148!Finclude/net/cfg80211.h cfg80211_michael_mic_failure
149      </chapter>
150      <chapter>
151      <title>Scanning and BSS list handling</title>
152!Pinclude/net/cfg80211.h Scanning and BSS list handling
153!Finclude/net/cfg80211.h cfg80211_ssid
154!Finclude/net/cfg80211.h cfg80211_scan_request
155!Finclude/net/cfg80211.h cfg80211_scan_done
156!Finclude/net/cfg80211.h cfg80211_bss
157!Finclude/net/cfg80211.h cfg80211_inform_bss_width_frame
158!Finclude/net/cfg80211.h cfg80211_inform_bss_width
159!Finclude/net/cfg80211.h cfg80211_unlink_bss
160!Finclude/net/cfg80211.h cfg80211_find_ie
161!Finclude/net/cfg80211.h ieee80211_bss_get_ie
162      </chapter>
163      <chapter>
164      <title>Utility functions</title>
165!Pinclude/net/cfg80211.h Utility functions
166!Finclude/net/cfg80211.h ieee80211_channel_to_frequency
167!Finclude/net/cfg80211.h ieee80211_frequency_to_channel
168!Finclude/net/cfg80211.h ieee80211_get_channel
169!Finclude/net/cfg80211.h ieee80211_get_response_rate
170!Finclude/net/cfg80211.h ieee80211_hdrlen
171!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb
172!Finclude/net/cfg80211.h ieee80211_radiotap_iterator
173      </chapter>
174      <chapter>
175      <title>Data path helpers</title>
176!Pinclude/net/cfg80211.h Data path helpers
177!Finclude/net/cfg80211.h ieee80211_data_to_8023
178!Finclude/net/cfg80211.h ieee80211_data_from_8023
179!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s
180!Finclude/net/cfg80211.h cfg80211_classify8021d
181      </chapter>
182      <chapter>
183      <title>Regulatory enforcement infrastructure</title>
184!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure
185!Finclude/net/cfg80211.h regulatory_hint
186!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory
187!Finclude/net/cfg80211.h freq_reg_info
188      </chapter>
189      <chapter>
190      <title>RFkill integration</title>
191!Pinclude/net/cfg80211.h RFkill integration
192!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state
193!Finclude/net/cfg80211.h wiphy_rfkill_start_polling
194!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling
195      </chapter>
196      <chapter>
197      <title>Test mode</title>
198!Pinclude/net/cfg80211.h Test mode
199!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb
200!Finclude/net/cfg80211.h cfg80211_testmode_reply
201!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb
202!Finclude/net/cfg80211.h cfg80211_testmode_event
203      </chapter>
204  </book>
205  <book id="mac80211-developers-guide">
206    <bookinfo>
207      <title>The mac80211 subsystem</title>
208      <abstract>
209!Pinclude/net/mac80211.h Introduction
210!Pinclude/net/mac80211.h Warning
211      </abstract>
212    </bookinfo>
213
214    <toc></toc>
215
216  <!--
217  Generally, this document shall be ordered by increasing complexity.
218  It is important to note that readers should be able to read only
219  the first few sections to get a working driver and only advanced
220  usage should require reading the full document.
221  -->
222
223    <part>
224      <title>The basic mac80211 driver interface</title>
225      <partintro>
226        <para>
227          You should read and understand the information contained
228          within this part of the book while implementing a driver.
229          In some chapters, advanced usage is noted, that may be
230          skipped at first.
231        </para>
232        <para>
233          This part of the book only covers station and monitor mode
234          functionality, additional information required to implement
235          the other modes is covered in the second part of the book.
236        </para>
237      </partintro>
238
239      <chapter id="basics">
240        <title>Basic hardware handling</title>
241        <para>TBD</para>
242        <para>
243          This chapter shall contain information on getting a hw
244          struct allocated and registered with mac80211.
245        </para>
246        <para>
247          Since it is required to allocate rates/modes before registering
248          a hw struct, this chapter shall also contain information on setting
249          up the rate/mode structs.
250        </para>
251        <para>
252          Additionally, some discussion about the callbacks and
253          the general programming model should be in here, including
254          the definition of ieee80211_ops which will be referred to
255          a lot.
256        </para>
257        <para>
258          Finally, a discussion of hardware capabilities should be done
259          with references to other parts of the book.
260        </para>
261  <!-- intentionally multiple !F lines to get proper order -->
262!Finclude/net/mac80211.h ieee80211_hw
263!Finclude/net/mac80211.h ieee80211_hw_flags
264!Finclude/net/mac80211.h SET_IEEE80211_DEV
265!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
266!Finclude/net/mac80211.h ieee80211_ops
267!Finclude/net/mac80211.h ieee80211_alloc_hw
268!Finclude/net/mac80211.h ieee80211_register_hw
269!Finclude/net/mac80211.h ieee80211_unregister_hw
270!Finclude/net/mac80211.h ieee80211_free_hw
271      </chapter>
272
273      <chapter id="phy-handling">
274        <title>PHY configuration</title>
275        <para>TBD</para>
276        <para>
277          This chapter should describe PHY handling including
278          start/stop callbacks and the various structures used.
279        </para>
280!Finclude/net/mac80211.h ieee80211_conf
281!Finclude/net/mac80211.h ieee80211_conf_flags
282      </chapter>
283
284      <chapter id="iface-handling">
285        <title>Virtual interfaces</title>
286        <para>TBD</para>
287        <para>
288          This chapter should describe virtual interface basics
289          that are relevant to the driver (VLANs, MGMT etc are not.)
290          It should explain the use of the add_iface/remove_iface
291          callbacks as well as the interface configuration callbacks.
292        </para>
293        <para>Things related to AP mode should be discussed there.</para>
294        <para>
295          Things related to supporting multiple interfaces should be
296          in the appropriate chapter, a BIG FAT note should be here about
297          this though and the recommendation to allow only a single
298          interface in STA mode at first!
299        </para>
300!Finclude/net/mac80211.h ieee80211_vif
301      </chapter>
302
303      <chapter id="rx-tx">
304        <title>Receive and transmit processing</title>
305        <sect1>
306          <title>what should be here</title>
307          <para>TBD</para>
308          <para>
309            This should describe the receive and transmit
310            paths in mac80211/the drivers as well as
311            transmit status handling.
312          </para>
313        </sect1>
314        <sect1>
315          <title>Frame format</title>
316!Pinclude/net/mac80211.h Frame format
317        </sect1>
318        <sect1>
319          <title>Packet alignment</title>
320!Pnet/mac80211/rx.c Packet alignment
321        </sect1>
322        <sect1>
323          <title>Calling into mac80211 from interrupts</title>
324!Pinclude/net/mac80211.h Calling mac80211 from interrupts
325        </sect1>
326        <sect1>
327          <title>functions/definitions</title>
328!Finclude/net/mac80211.h ieee80211_rx_status
329!Finclude/net/mac80211.h mac80211_rx_flags
330!Finclude/net/mac80211.h mac80211_tx_info_flags
331!Finclude/net/mac80211.h mac80211_tx_control_flags
332!Finclude/net/mac80211.h mac80211_rate_control_flags
333!Finclude/net/mac80211.h ieee80211_tx_rate
334!Finclude/net/mac80211.h ieee80211_tx_info
335!Finclude/net/mac80211.h ieee80211_tx_info_clear_status
336!Finclude/net/mac80211.h ieee80211_rx
337!Finclude/net/mac80211.h ieee80211_rx_ni
338!Finclude/net/mac80211.h ieee80211_rx_irqsafe
339!Finclude/net/mac80211.h ieee80211_tx_status
340!Finclude/net/mac80211.h ieee80211_tx_status_ni
341!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
342!Finclude/net/mac80211.h ieee80211_rts_get
343!Finclude/net/mac80211.h ieee80211_rts_duration
344!Finclude/net/mac80211.h ieee80211_ctstoself_get
345!Finclude/net/mac80211.h ieee80211_ctstoself_duration
346!Finclude/net/mac80211.h ieee80211_generic_frame_duration
347!Finclude/net/mac80211.h ieee80211_wake_queue
348!Finclude/net/mac80211.h ieee80211_stop_queue
349!Finclude/net/mac80211.h ieee80211_wake_queues
350!Finclude/net/mac80211.h ieee80211_stop_queues
351!Finclude/net/mac80211.h ieee80211_queue_stopped
352        </sect1>
353      </chapter>
354
355      <chapter id="filters">
356        <title>Frame filtering</title>
357!Pinclude/net/mac80211.h Frame filtering
358!Finclude/net/mac80211.h ieee80211_filter_flags
359      </chapter>
360
361      <chapter id="workqueue">
362        <title>The mac80211 workqueue</title>
363!Pinclude/net/mac80211.h mac80211 workqueue
364!Finclude/net/mac80211.h ieee80211_queue_work
365!Finclude/net/mac80211.h ieee80211_queue_delayed_work
366      </chapter>
367    </part>
368
369    <part id="advanced">
370      <title>Advanced driver interface</title>
371      <partintro>
372        <para>
373         Information contained within this part of the book is
374         of interest only for advanced interaction of mac80211
375         with drivers to exploit more hardware capabilities and
376         improve performance.
377        </para>
378      </partintro>
379
380      <chapter id="led-support">
381        <title>LED support</title>
382        <para>
383         Mac80211 supports various ways of blinking LEDs. Wherever possible,
384         device LEDs should be exposed as LED class devices and hooked up to
385         the appropriate trigger, which will then be triggered appropriately
386         by mac80211.
387        </para>
388!Finclude/net/mac80211.h ieee80211_get_tx_led_name
389!Finclude/net/mac80211.h ieee80211_get_rx_led_name
390!Finclude/net/mac80211.h ieee80211_get_assoc_led_name
391!Finclude/net/mac80211.h ieee80211_get_radio_led_name
392!Finclude/net/mac80211.h ieee80211_tpt_blink
393!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags
394!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger
395      </chapter>
396
397      <chapter id="hardware-crypto-offload">
398        <title>Hardware crypto acceleration</title>
399!Pinclude/net/mac80211.h Hardware crypto acceleration
400  <!-- intentionally multiple !F lines to get proper order -->
401!Finclude/net/mac80211.h set_key_cmd
402!Finclude/net/mac80211.h ieee80211_key_conf
403!Finclude/net/mac80211.h ieee80211_key_flags
404!Finclude/net/mac80211.h ieee80211_get_tkip_p1k
405!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv
406!Finclude/net/mac80211.h ieee80211_get_tkip_p2k
407      </chapter>
408
409      <chapter id="powersave">
410        <title>Powersave support</title>
411!Pinclude/net/mac80211.h Powersave support
412      </chapter>
413
414      <chapter id="beacon-filter">
415        <title>Beacon filter support</title>
416!Pinclude/net/mac80211.h Beacon filter support
417!Finclude/net/mac80211.h ieee80211_beacon_loss
418      </chapter>
419
420      <chapter id="qos">
421        <title>Multiple queues and QoS support</title>
422        <para>TBD</para>
423!Finclude/net/mac80211.h ieee80211_tx_queue_params
424      </chapter>
425
426      <chapter id="AP">
427        <title>Access point mode support</title>
428        <para>TBD</para>
429        <para>Some parts of the if_conf should be discussed here instead</para>
430        <para>
431          Insert notes about VLAN interfaces with hw crypto here or
432          in the hw crypto chapter.
433        </para>
434      <section id="ps-client">
435        <title>support for powersaving clients</title>
436!Pinclude/net/mac80211.h AP support for powersaving clients
437!Finclude/net/mac80211.h ieee80211_get_buffered_bc
438!Finclude/net/mac80211.h ieee80211_beacon_get
439!Finclude/net/mac80211.h ieee80211_sta_eosp
440!Finclude/net/mac80211.h ieee80211_frame_release_type
441!Finclude/net/mac80211.h ieee80211_sta_ps_transition
442!Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni
443!Finclude/net/mac80211.h ieee80211_sta_set_buffered
444!Finclude/net/mac80211.h ieee80211_sta_block_awake
445      </section>
446      </chapter>
447
448      <chapter id="multi-iface">
449        <title>Supporting multiple virtual interfaces</title>
450        <para>TBD</para>
451        <para>
452          Note: WDS with identical MAC address should almost always be OK
453        </para>
454        <para>
455          Insert notes about having multiple virtual interfaces with
456          different MAC addresses here, note which configurations are
457          supported by mac80211, add notes about supporting hw crypto
458          with it.
459        </para>
460!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces
461!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic
462      </chapter>
463
464      <chapter id="station-handling">
465        <title>Station handling</title>
466        <para>TODO</para>
467!Finclude/net/mac80211.h ieee80211_sta
468!Finclude/net/mac80211.h sta_notify_cmd
469!Finclude/net/mac80211.h ieee80211_find_sta
470!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr
471      </chapter>
472
473      <chapter id="hardware-scan-offload">
474        <title>Hardware scan offload</title>
475        <para>TBD</para>
476!Finclude/net/mac80211.h ieee80211_scan_completed
477      </chapter>
478
479      <chapter id="aggregation">
480        <title>Aggregation</title>
481        <sect1>
482          <title>TX A-MPDU aggregation</title>
483!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation
484!Cnet/mac80211/agg-tx.c
485        </sect1>
486        <sect1>
487          <title>RX A-MPDU aggregation</title>
488!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation
489!Cnet/mac80211/agg-rx.c
490!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action
491        </sect1>
492      </chapter>
493
494      <chapter id="smps">
495        <title>Spatial Multiplexing Powersave (SMPS)</title>
496!Pinclude/net/mac80211.h Spatial multiplexing power save
497!Finclude/net/mac80211.h ieee80211_request_smps
498!Finclude/net/mac80211.h ieee80211_smps_mode
499      </chapter>
500    </part>
501
502    <part id="rate-control">
503      <title>Rate control interface</title>
504      <partintro>
505        <para>TBD</para>
506        <para>
507         This part of the book describes the rate control algorithm
508         interface and how it relates to mac80211 and drivers.
509        </para>
510      </partintro>
511      <chapter id="ratecontrol-api">
512        <title>Rate Control API</title>
513        <para>TBD</para>
514!Finclude/net/mac80211.h ieee80211_start_tx_ba_session
515!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe
516!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session
517!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe
518!Finclude/net/mac80211.h ieee80211_rate_control_changed
519!Finclude/net/mac80211.h ieee80211_tx_rate_control
520!Finclude/net/mac80211.h rate_control_send_low
521      </chapter>
522    </part>
523
524    <part id="internal">
525      <title>Internals</title>
526      <partintro>
527        <para>TBD</para>
528        <para>
529         This part of the book describes mac80211 internals.
530        </para>
531      </partintro>
532
533      <chapter id="key-handling">
534        <title>Key handling</title>
535        <sect1>
536          <title>Key handling basics</title>
537!Pnet/mac80211/key.c Key handling basics
538        </sect1>
539        <sect1>
540          <title>MORE TBD</title>
541          <para>TBD</para>
542        </sect1>
543      </chapter>
544
545      <chapter id="rx-processing">
546        <title>Receive processing</title>
547        <para>TBD</para>
548      </chapter>
549
550      <chapter id="tx-processing">
551        <title>Transmit processing</title>
552        <para>TBD</para>
553      </chapter>
554
555      <chapter id="sta-info">
556        <title>Station info handling</title>
557        <sect1>
558          <title>Programming information</title>
559!Fnet/mac80211/sta_info.h sta_info
560!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
561        </sect1>
562        <sect1>
563          <title>STA information lifetime rules</title>
564!Pnet/mac80211/sta_info.c STA information lifetime rules
565        </sect1>
566      </chapter>
567
568      <chapter id="aggregation-internals">
569        <title>Aggregation</title>
570!Fnet/mac80211/sta_info.h sta_ampdu_mlme
571!Fnet/mac80211/sta_info.h tid_ampdu_tx
572!Fnet/mac80211/sta_info.h tid_ampdu_rx
573      </chapter>
574
575      <chapter id="synchronisation">
576        <title>Synchronisation</title>
577        <para>TBD</para>
578        <para>Locking, lots of RCU</para>
579      </chapter>
580    </part>
581  </book>
582</set>
583