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<!-- 60Generally, this document shall be ordered by increasing complexity. 61It is important to note that readers should be able to read only 62the first few sections to get a working driver and only advanced 63usage 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> 342