Merge branch 'for-2.6.30' into for-2.6.31
[linux-2.6] / Documentation / DocBook / mac80211.tmpl
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5 <book id="mac80211-developers-guide">
6   <bookinfo>
7     <title>The mac80211 subsystem for kernel developers</title>
8
9     <authorgroup>
10       <author>
11         <firstname>Johannes</firstname>
12         <surname>Berg</surname>
13         <affiliation>
14           <address><email>johannes@sipsolutions.net</email></address>
15         </affiliation>
16       </author>
17     </authorgroup>
18
19     <copyright>
20       <year>2007-2009</year>
21       <holder>Johannes Berg</holder>
22     </copyright>
23
24     <legalnotice>
25       <para>
26         This documentation is free software; you can redistribute
27         it and/or modify it under the terms of the GNU General Public
28         License version 2 as published by the Free Software Foundation.
29       </para>
30
31       <para>
32         This documentation is distributed in the hope that it will be
33         useful, but WITHOUT ANY WARRANTY; without even the implied
34         warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
35         See the GNU General Public License for more details.
36       </para>
37
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
45       <para>
46         For more details see the file COPYING in the source
47         distribution of Linux.
48       </para>
49     </legalnotice>
50
51     <abstract>
52 !Pinclude/net/mac80211.h Introduction
53 !Pinclude/net/mac80211.h Warning
54     </abstract>
55   </bookinfo>
56
57   <toc></toc>
58
59 <!--
60 Generally, this document shall be ordered by increasing complexity.
61 It is important to note that readers should be able to read only
62 the first few sections to get a working driver and only advanced
63 usage should require reading the full document.
64 -->
65
66   <part>
67     <title>The basic mac80211 driver interface</title>
68     <partintro>
69       <para>
70         You should read and understand the information contained
71         within this part of the book while implementing a driver.
72         In some chapters, advanced usage is noted, that may be
73         skipped at first.
74       </para>
75       <para>
76         This part of the book only covers station and monitor mode
77         functionality, additional information required to implement
78         the other modes is covered in the second part of the book.
79       </para>
80     </partintro>
81
82     <chapter id="basics">
83       <title>Basic hardware handling</title>
84       <para>TBD</para>
85       <para>
86         This chapter shall contain information on getting a hw
87         struct allocated and registered with mac80211.
88       </para>
89       <para>
90         Since it is required to allocate rates/modes before registering
91         a hw struct, this chapter shall also contain information on setting
92         up the rate/mode structs.
93       </para>
94       <para>
95         Additionally, some discussion about the callbacks and
96         the general programming model should be in here, including
97         the definition of ieee80211_ops which will be referred to
98         a lot.
99       </para>
100       <para>
101         Finally, a discussion of hardware capabilities should be done
102         with references to other parts of the book.
103       </para>
104 <!-- intentionally multiple !F lines to get proper order -->
105 !Finclude/net/mac80211.h ieee80211_hw
106 !Finclude/net/mac80211.h ieee80211_hw_flags
107 !Finclude/net/mac80211.h SET_IEEE80211_DEV
108 !Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
109 !Finclude/net/mac80211.h ieee80211_ops
110 !Finclude/net/mac80211.h ieee80211_alloc_hw
111 !Finclude/net/mac80211.h ieee80211_register_hw
112 !Finclude/net/mac80211.h ieee80211_get_tx_led_name
113 !Finclude/net/mac80211.h ieee80211_get_rx_led_name
114 !Finclude/net/mac80211.h ieee80211_get_assoc_led_name
115 !Finclude/net/mac80211.h ieee80211_get_radio_led_name
116 !Finclude/net/mac80211.h ieee80211_unregister_hw
117 !Finclude/net/mac80211.h ieee80211_free_hw
118     </chapter>
119
120     <chapter id="phy-handling">
121       <title>PHY configuration</title>
122       <para>TBD</para>
123       <para>
124         This chapter should describe PHY handling including
125         start/stop callbacks and the various structures used.
126       </para>
127 !Finclude/net/mac80211.h ieee80211_conf
128 !Finclude/net/mac80211.h ieee80211_conf_flags
129     </chapter>
130
131     <chapter id="iface-handling">
132       <title>Virtual interfaces</title>
133       <para>TBD</para>
134       <para>
135         This chapter should describe virtual interface basics
136         that are relevant to the driver (VLANs, MGMT etc are not.)
137         It should explain the use of the add_iface/remove_iface
138         callbacks as well as the interface configuration callbacks.
139       </para>
140       <para>Things related to AP mode should be discussed there.</para>
141       <para>
142         Things related to supporting multiple interfaces should be
143         in the appropriate chapter, a BIG FAT note should be here about
144         this though and the recommendation to allow only a single
145         interface in STA mode at first!
146       </para>
147 !Finclude/net/mac80211.h ieee80211_if_init_conf
148 !Finclude/net/mac80211.h ieee80211_if_conf
149     </chapter>
150
151     <chapter id="rx-tx">
152       <title>Receive and transmit processing</title>
153       <sect1>
154         <title>what should be here</title>
155         <para>TBD</para>
156         <para>
157           This should describe the receive and transmit
158           paths in mac80211/the drivers as well as
159           transmit status handling.
160         </para>
161       </sect1>
162       <sect1>
163         <title>Frame format</title>
164 !Pinclude/net/mac80211.h Frame format
165       </sect1>
166       <sect1>
167         <title>Packet alignment</title>
168 !Pnet/mac80211/rx.c Packet alignment
169       </sect1>
170       <sect1>
171         <title>Calling into mac80211 from interrupts</title>
172 !Pinclude/net/mac80211.h Calling mac80211 from interrupts
173       </sect1>
174       <sect1>
175         <title>functions/definitions</title>
176 !Finclude/net/mac80211.h ieee80211_rx_status
177 !Finclude/net/mac80211.h mac80211_rx_flags
178 !Finclude/net/mac80211.h ieee80211_tx_info
179 !Finclude/net/mac80211.h ieee80211_rx
180 !Finclude/net/mac80211.h ieee80211_rx_irqsafe
181 !Finclude/net/mac80211.h ieee80211_tx_status
182 !Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
183 !Finclude/net/mac80211.h ieee80211_rts_get
184 !Finclude/net/mac80211.h ieee80211_rts_duration
185 !Finclude/net/mac80211.h ieee80211_ctstoself_get
186 !Finclude/net/mac80211.h ieee80211_ctstoself_duration
187 !Finclude/net/mac80211.h ieee80211_generic_frame_duration
188 !Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb
189 !Finclude/net/mac80211.h ieee80211_hdrlen
190 !Finclude/net/mac80211.h ieee80211_wake_queue
191 !Finclude/net/mac80211.h ieee80211_stop_queue
192 !Finclude/net/mac80211.h ieee80211_wake_queues
193 !Finclude/net/mac80211.h ieee80211_stop_queues
194       </sect1>
195     </chapter>
196
197     <chapter id="filters">
198       <title>Frame filtering</title>
199 !Pinclude/net/mac80211.h Frame filtering
200 !Finclude/net/mac80211.h ieee80211_filter_flags
201     </chapter>
202   </part>
203
204   <part id="advanced">
205     <title>Advanced driver interface</title>
206     <partintro>
207       <para>
208        Information contained within this part of the book is
209        of interest only for advanced interaction of mac80211
210        with drivers to exploit more hardware capabilities and
211        improve performance.
212       </para>
213     </partintro>
214
215     <chapter id="hardware-crypto-offload">
216       <title>Hardware crypto acceleration</title>
217 !Pinclude/net/mac80211.h Hardware crypto acceleration
218 <!-- intentionally multiple !F lines to get proper order -->
219 !Finclude/net/mac80211.h set_key_cmd
220 !Finclude/net/mac80211.h ieee80211_key_conf
221 !Finclude/net/mac80211.h ieee80211_key_alg
222 !Finclude/net/mac80211.h ieee80211_key_flags
223     </chapter>
224
225     <chapter id="powersave">
226       <title>Powersave support</title>
227 !Pinclude/net/mac80211.h Powersave support
228     </chapter>
229
230     <chapter id="beacon-filter">
231       <title>Beacon filter support</title>
232 !Pinclude/net/mac80211.h Beacon filter support
233 !Finclude/net/mac80211.h ieee80211_beacon_loss
234     </chapter>
235
236     <chapter id="qos">
237       <title>Multiple queues and QoS support</title>
238       <para>TBD</para>
239 !Finclude/net/mac80211.h ieee80211_tx_queue_params
240 !Finclude/net/mac80211.h ieee80211_tx_queue_stats
241     </chapter>
242
243     <chapter id="AP">
244       <title>Access point mode support</title>
245       <para>TBD</para>
246       <para>Some parts of the if_conf should be discussed here instead</para>
247       <para>
248         Insert notes about VLAN interfaces with hw crypto here or
249         in the hw crypto chapter.
250       </para>
251 !Finclude/net/mac80211.h ieee80211_get_buffered_bc
252 !Finclude/net/mac80211.h ieee80211_beacon_get
253     </chapter>
254
255     <chapter id="multi-iface">
256       <title>Supporting multiple virtual interfaces</title>
257       <para>TBD</para>
258       <para>
259         Note: WDS with identical MAC address should almost always be OK
260       </para>
261       <para>
262         Insert notes about having multiple virtual interfaces with
263         different MAC addresses here, note which configurations are
264         supported by mac80211, add notes about supporting hw crypto
265         with it.
266       </para>
267     </chapter>
268
269     <chapter id="hardware-scan-offload">
270       <title>Hardware scan offload</title>
271       <para>TBD</para>
272 !Finclude/net/mac80211.h ieee80211_scan_completed
273     </chapter>
274   </part>
275
276   <part id="rate-control">
277     <title>Rate control interface</title>
278     <partintro>
279       <para>TBD</para>
280       <para>
281        This part of the book describes the rate control algorithm
282        interface and how it relates to mac80211 and drivers.
283       </para>
284     </partintro>
285     <chapter id="dummy">
286       <title>dummy chapter</title>
287       <para>TBD</para>
288     </chapter>
289   </part>
290
291   <part id="internal">
292     <title>Internals</title>
293     <partintro>
294       <para>TBD</para>
295       <para>
296        This part of the book describes mac80211 internals.
297       </para>
298     </partintro>
299
300     <chapter id="key-handling">
301       <title>Key handling</title>
302       <sect1>
303         <title>Key handling basics</title>
304 !Pnet/mac80211/key.c Key handling basics
305       </sect1>
306       <sect1>
307         <title>MORE TBD</title>
308         <para>TBD</para>
309       </sect1>
310     </chapter>
311
312     <chapter id="rx-processing">
313       <title>Receive processing</title>
314       <para>TBD</para>
315     </chapter>
316
317     <chapter id="tx-processing">
318       <title>Transmit processing</title>
319       <para>TBD</para>
320     </chapter>
321
322     <chapter id="sta-info">
323       <title>Station info handling</title>
324       <sect1>
325         <title>Programming information</title>
326 !Fnet/mac80211/sta_info.h sta_info
327 !Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
328       </sect1>
329       <sect1>
330         <title>STA information lifetime rules</title>
331 !Pnet/mac80211/sta_info.c STA information lifetime rules
332       </sect1>
333     </chapter>
334
335     <chapter id="synchronisation">
336       <title>Synchronisation</title>
337       <para>TBD</para>
338       <para>Locking, lots of RCU</para>
339     </chapter>
340   </part>
341 </book>