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