aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorJohannes Berg <johannes@sipsolutions.net>2008-02-26 08:34:06 -0500
committerJohn W. Linville <linville@tuxdriver.com>2008-03-06 15:30:47 -0500
commitdbbea6713d6096cd1c411cb453a6b71292c78b33 (patch)
tree6e824acc2b680350c4c4ebebaccf32b9b01c0e96 /Documentation/DocBook
parent7c8076bd8be3fd2a9a94f9687cf39e3505f0e4ec (diff)
mac80211: add documentation book
Quite a while ago I started this book. The required kernel-doc patches have since gone into the tree so it is now possible to build the book in mainline. The actual documentation is still rather incomplete and not all things are linked into the book, but this enables us to edit the documentation collaboratively, hopefully driver authors can add documentation based on their experience with mac80211. Signed-off-by: Johannes Berg <johannes@sipsolutions.net> Signed-off-by: John W. Linville <linville@tuxdriver.com>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/Makefile3
-rw-r--r--Documentation/DocBook/mac80211.tmpl335
2 files changed, 337 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 300e1707893f..9ebd1f00c6e7 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -11,7 +11,8 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
11 procfs-guide.xml writing_usb_driver.xml networking.xml \ 11 procfs-guide.xml writing_usb_driver.xml networking.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml \ 12 kernel-api.xml filesystems.xml lsm.xml usb.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ 13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 mac80211.xml
15 16
16### 17###
17# The build process is as follows (targets): 18# The build process is as follows (targets):
diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl
new file mode 100644
index 000000000000..b651e0a4b1c0
--- /dev/null
+++ b/Documentation/DocBook/mac80211.tmpl
@@ -0,0 +1,335 @@
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</year>
21 <year>2008</year>
22 <holder>Johannes Berg</holder>
23 </copyright>
24
25 <legalnotice>
26 <para>
27 This documentation is free software; you can redistribute
28 it and/or modify it under the terms of the GNU General Public
29 License version 2 as published by the Free Software Foundation.
30 </para>
31
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
39 <para>
40 You should have received a copy of the GNU General Public
41 License along with this documentation; if not, write to the Free
42 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
43 MA 02111-1307 USA
44 </para>
45
46 <para>
47 For more details see the file COPYING in the source
48 distribution of Linux.
49 </para>
50 </legalnotice>
51
52 <abstract>
53!Pinclude/net/mac80211.h Introduction
54!Pinclude/net/mac80211.h Warning
55 </abstract>
56 </bookinfo>
57
58 <toc></toc>
59
60<!--
61Generally, this document shall be ordered by increasing complexity.
62It is important to note that readers should be able to read only
63the first few sections to get a working driver and only advanced
64usage should require reading the full document.
65-->
66
67 <part>
68 <title>The basic mac80211 driver interface</title>
69 <partintro>
70 <para>
71 You should read and understand the information contained
72 within this part of the book while implementing a driver.
73 In some chapters, advanced usage is noted, that may be
74 skipped at first.
75 </para>
76 <para>
77 This part of the book only covers station and monitor mode
78 functionality, additional information required to implement
79 the other modes is covered in the second part of the book.
80 </para>
81 </partintro>
82
83 <chapter id="basics">
84 <title>Basic hardware handling</title>
85 <para>TBD</para>
86 <para>
87 This chapter shall contain information on getting a hw
88 struct allocated and registered with mac80211.
89 </para>
90 <para>
91 Since it is required to allocate rates/modes before registering
92 a hw struct, this chapter shall also contain information on setting
93 up the rate/mode structs.
94 </para>
95 <para>
96 Additionally, some discussion about the callbacks and
97 the general programming model should be in here, including
98 the definition of ieee80211_ops which will be referred to
99 a lot.
100 </para>
101 <para>
102 Finally, a discussion of hardware capabilities should be done
103 with references to other parts of the book.
104 </para>
105<!-- intentionally multiple !F lines to get proper order -->
106!Finclude/net/mac80211.h ieee80211_hw
107!Finclude/net/mac80211.h ieee80211_hw_flags
108!Finclude/net/mac80211.h SET_IEEE80211_DEV
109!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
110!Finclude/net/mac80211.h ieee80211_ops
111!Finclude/net/mac80211.h ieee80211_alloc_hw
112!Finclude/net/mac80211.h ieee80211_register_hw
113!Finclude/net/mac80211.h ieee80211_get_tx_led_name
114!Finclude/net/mac80211.h ieee80211_get_rx_led_name
115!Finclude/net/mac80211.h ieee80211_get_assoc_led_name
116!Finclude/net/mac80211.h ieee80211_get_radio_led_name
117!Finclude/net/mac80211.h ieee80211_unregister_hw
118!Finclude/net/mac80211.h ieee80211_free_hw
119 </chapter>
120
121 <chapter id="phy-handling">
122 <title>PHY configuration</title>
123 <para>TBD</para>
124 <para>
125 This chapter should describe PHY handling including
126 start/stop callbacks and the various structures used.
127 </para>
128!Finclude/net/mac80211.h ieee80211_conf
129!Finclude/net/mac80211.h ieee80211_conf_flags
130 </chapter>
131
132 <chapter id="iface-handling">
133 <title>Virtual interfaces</title>
134 <para>TBD</para>
135 <para>
136 This chapter should describe virtual interface basics
137 that are relevant to the driver (VLANs, MGMT etc are not.)
138 It should explain the use of the add_iface/remove_iface
139 callbacks as well as the interface configuration callbacks.
140 </para>
141 <para>Things related to AP mode should be discussed there.</para>
142 <para>
143 Things related to supporting multiple interfaces should be
144 in the appropriate chapter, a BIG FAT note should be here about
145 this though and the recommendation to allow only a single
146 interface in STA mode at first!
147 </para>
148!Finclude/net/mac80211.h ieee80211_if_types
149!Finclude/net/mac80211.h ieee80211_if_init_conf
150!Finclude/net/mac80211.h ieee80211_if_conf
151 </chapter>
152
153 <chapter id="rx-tx">
154 <title>Receive and transmit processing</title>
155 <sect1>
156 <title>what should be here</title>
157 <para>TBD</para>
158 <para>
159 This should describe the receive and transmit
160 paths in mac80211/the drivers as well as
161 transmit status handling.
162 </para>
163 </sect1>
164 <sect1>
165 <title>Frame format</title>
166!Pinclude/net/mac80211.h Frame format
167 </sect1>
168 <sect1>
169 <title>Alignment issues</title>
170 <para>TBD</para>
171 </sect1>
172 <sect1>
173 <title>Calling into mac80211 from interrupts</title>
174!Pinclude/net/mac80211.h Calling mac80211 from interrupts
175 </sect1>
176 <sect1>
177 <title>functions/definitions</title>
178!Finclude/net/mac80211.h ieee80211_rx_status
179!Finclude/net/mac80211.h mac80211_rx_flags
180!Finclude/net/mac80211.h ieee80211_tx_control
181!Finclude/net/mac80211.h ieee80211_tx_status_flags
182!Finclude/net/mac80211.h ieee80211_rx
183!Finclude/net/mac80211.h ieee80211_rx_irqsafe
184!Finclude/net/mac80211.h ieee80211_tx_status
185!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
186!Finclude/net/mac80211.h ieee80211_rts_get
187!Finclude/net/mac80211.h ieee80211_rts_duration
188!Finclude/net/mac80211.h ieee80211_ctstoself_get
189!Finclude/net/mac80211.h ieee80211_ctstoself_duration
190!Finclude/net/mac80211.h ieee80211_generic_frame_duration
191!Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb
192!Finclude/net/mac80211.h ieee80211_get_hdrlen
193!Finclude/net/mac80211.h ieee80211_wake_queue
194!Finclude/net/mac80211.h ieee80211_stop_queue
195!Finclude/net/mac80211.h ieee80211_start_queues
196!Finclude/net/mac80211.h ieee80211_stop_queues
197!Finclude/net/mac80211.h ieee80211_wake_queues
198 </sect1>
199 </chapter>
200
201 <chapter id="filters">
202 <title>Frame filtering</title>
203!Pinclude/net/mac80211.h Frame filtering
204!Finclude/net/mac80211.h ieee80211_filter_flags
205 </chapter>
206 </part>
207
208 <part id="advanced">
209 <title>Advanced driver interface</title>
210 <partintro>
211 <para>
212 Information contained within this part of the book is
213 of interest only for advanced interaction of mac80211
214 with drivers to exploit more hardware capabilities and
215 improve performance.
216 </para>
217 </partintro>
218
219 <chapter id="hardware-crypto-offload">
220 <title>Hardware crypto acceleration</title>
221!Pinclude/net/mac80211.h Hardware crypto acceleration
222<!-- intentionally multiple !F lines to get proper order -->
223!Finclude/net/mac80211.h set_key_cmd
224!Finclude/net/mac80211.h ieee80211_key_conf
225!Finclude/net/mac80211.h ieee80211_key_alg
226!Finclude/net/mac80211.h ieee80211_key_flags
227 </chapter>
228
229 <chapter id="qos">
230 <title>Multiple queues and QoS support</title>
231 <para>TBD</para>
232!Finclude/net/mac80211.h ieee80211_tx_queue_params
233!Finclude/net/mac80211.h ieee80211_tx_queue_stats_data
234!Finclude/net/mac80211.h ieee80211_tx_queue
235 </chapter>
236
237 <chapter id="AP">
238 <title>Access point mode support</title>
239 <para>TBD</para>
240 <para>Some parts of the if_conf should be discussed here instead</para>
241 <para>
242 Insert notes about VLAN interfaces with hw crypto here or
243 in the hw crypto chapter.
244 </para>
245!Finclude/net/mac80211.h ieee80211_get_buffered_bc
246!Finclude/net/mac80211.h ieee80211_beacon_get
247 </chapter>
248
249 <chapter id="multi-iface">
250 <title>Supporting multiple virtual interfaces</title>
251 <para>TBD</para>
252 <para>
253 Note: WDS with identical MAC address should almost always be OK
254 </para>
255 <para>
256 Insert notes about having multiple virtual interfaces with
257 different MAC addresses here, note which configurations are
258 supported by mac80211, add notes about supporting hw crypto
259 with it.
260 </para>
261 </chapter>
262
263 <chapter id="hardware-scan-offload">
264 <title>Hardware scan offload</title>
265 <para>TBD</para>
266!Finclude/net/mac80211.h ieee80211_scan_completed
267 </chapter>
268 </part>
269
270 <part id="rate-control">
271 <title>Rate control interface</title>
272 <partintro>
273 <para>TBD</para>
274 <para>
275 This part of the book describes the rate control algorithm
276 interface and how it relates to mac80211 and drivers.
277 </para>
278 </partintro>
279 <chapter id="dummy">
280 <title>dummy chapter</title>
281 <para>TBD</para>
282 </chapter>
283 </part>
284
285 <part id="internal">
286 <title>Internals</title>
287 <partintro>
288 <para>TBD</para>
289 <para>
290 This part of the book describes mac80211 internals.
291 </para>
292 </partintro>
293
294 <chapter id="key-handling">
295 <title>Key handling</title>
296 <sect1>
297 <title>Key handling basics</title>
298!Pnet/mac80211/key.c Key handling basics
299 </sect1>
300 <sect1>
301 <title>MORE TBD</title>
302 <para>TBD</para>
303 </sect1>
304 </chapter>
305
306 <chapter id="rx-processing">
307 <title>Receive processing</title>
308 <para>TBD</para>
309 </chapter>
310
311 <chapter id="tx-processing">
312 <title>Transmit processing</title>
313 <para>TBD</para>
314 </chapter>
315
316 <chapter id="sta-info">
317 <title>Station info handling</title>
318 <sect1>
319 <title>Programming information</title>
320!Fnet/mac80211/sta_info.h sta_info
321!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
322 </sect1>
323 <sect1>
324 <title>STA information lifetime rules</title>
325!Pnet/mac80211/sta_info.c STA information lifetime rules
326 </sect1>
327 </chapter>
328
329 <chapter id="synchronisation">
330 <title>Synchronisation</title>
331 <para>TBD</para>
332 <para>Locking, lots of RCU</para>
333 </chapter>
334 </part>
335</book>