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_vif 148 </chapter> 149 150 <chapter id="rx-tx"> 151 <title>Receive and transmit processing</title> 152 <sect1> 153 <title>what should be here</title> 154 <para>TBD</para> 155 <para> 156 This should describe the receive and transmit 157 paths in mac80211/the drivers as well as 158 transmit status handling. 159 </para> 160 </sect1> 161 <sect1> 162 <title>Frame format</title> 163!Pinclude/net/mac80211.h Frame format 164 </sect1> 165 <sect1> 166 <title>Packet alignment</title> 167!Pnet/mac80211/rx.c Packet alignment 168 </sect1> 169 <sect1> 170 <title>Calling into mac80211 from interrupts</title> 171!Pinclude/net/mac80211.h Calling mac80211 from interrupts 172 </sect1> 173 <sect1> 174 <title>functions/definitions</title> 175!Finclude/net/mac80211.h ieee80211_rx_status 176!Finclude/net/mac80211.h mac80211_rx_flags 177!Finclude/net/mac80211.h ieee80211_tx_info 178!Finclude/net/mac80211.h ieee80211_rx 179!Finclude/net/mac80211.h ieee80211_rx_irqsafe 180!Finclude/net/mac80211.h ieee80211_tx_status 181!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe 182!Finclude/net/mac80211.h ieee80211_rts_get 183!Finclude/net/mac80211.h ieee80211_rts_duration 184!Finclude/net/mac80211.h ieee80211_ctstoself_get 185!Finclude/net/mac80211.h ieee80211_ctstoself_duration 186!Finclude/net/mac80211.h ieee80211_generic_frame_duration 187!Finclude/net/mac80211.h ieee80211_wake_queue 188!Finclude/net/mac80211.h ieee80211_stop_queue 189!Finclude/net/mac80211.h ieee80211_wake_queues 190!Finclude/net/mac80211.h ieee80211_stop_queues 191 </sect1> 192 </chapter> 193 194 <chapter id="filters"> 195 <title>Frame filtering</title> 196!Pinclude/net/mac80211.h Frame filtering 197!Finclude/net/mac80211.h ieee80211_filter_flags 198 </chapter> 199 </part> 200 201 <part id="advanced"> 202 <title>Advanced driver interface</title> 203 <partintro> 204 <para> 205 Information contained within this part of the book is 206 of interest only for advanced interaction of mac80211 207 with drivers to exploit more hardware capabilities and 208 improve performance. 209 </para> 210 </partintro> 211 212 <chapter id="hardware-crypto-offload"> 213 <title>Hardware crypto acceleration</title> 214!Pinclude/net/mac80211.h Hardware crypto acceleration 215<!-- intentionally multiple !F lines to get proper order --> 216!Finclude/net/mac80211.h set_key_cmd 217!Finclude/net/mac80211.h ieee80211_key_conf 218!Finclude/net/mac80211.h ieee80211_key_alg 219!Finclude/net/mac80211.h ieee80211_key_flags 220 </chapter> 221 222 <chapter id="powersave"> 223 <title>Powersave support</title> 224!Pinclude/net/mac80211.h Powersave support 225 </chapter> 226 227 <chapter id="beacon-filter"> 228 <title>Beacon filter support</title> 229!Pinclude/net/mac80211.h Beacon filter support 230!Finclude/net/mac80211.h ieee80211_beacon_loss 231 </chapter> 232 233 <chapter id="qos"> 234 <title>Multiple queues and QoS support</title> 235 <para>TBD</para> 236!Finclude/net/mac80211.h ieee80211_tx_queue_params 237 </chapter> 238 239 <chapter id="AP"> 240 <title>Access point mode support</title> 241 <para>TBD</para> 242 <para>Some parts of the if_conf should be discussed here instead</para> 243 <para> 244 Insert notes about VLAN interfaces with hw crypto here or 245 in the hw crypto chapter. 246 </para> 247!Finclude/net/mac80211.h ieee80211_get_buffered_bc 248!Finclude/net/mac80211.h ieee80211_beacon_get 249 </chapter> 250 251 <chapter id="multi-iface"> 252 <title>Supporting multiple virtual interfaces</title> 253 <para>TBD</para> 254 <para> 255 Note: WDS with identical MAC address should almost always be OK 256 </para> 257 <para> 258 Insert notes about having multiple virtual interfaces with 259 different MAC addresses here, note which configurations are 260 supported by mac80211, add notes about supporting hw crypto 261 with it. 262 </para> 263 </chapter> 264 265 <chapter id="hardware-scan-offload"> 266 <title>Hardware scan offload</title> 267 <para>TBD</para> 268!Finclude/net/mac80211.h ieee80211_scan_completed 269 </chapter> 270 </part> 271 272 <part id="rate-control"> 273 <title>Rate control interface</title> 274 <partintro> 275 <para>TBD</para> 276 <para> 277 This part of the book describes the rate control algorithm 278 interface and how it relates to mac80211 and drivers. 279 </para> 280 </partintro> 281 <chapter id="dummy"> 282 <title>dummy chapter</title> 283 <para>TBD</para> 284 </chapter> 285 </part> 286 287 <part id="internal"> 288 <title>Internals</title> 289 <partintro> 290 <para>TBD</para> 291 <para> 292 This part of the book describes mac80211 internals. 293 </para> 294 </partintro> 295 296 <chapter id="key-handling"> 297 <title>Key handling</title> 298 <sect1> 299 <title>Key handling basics</title> 300!Pnet/mac80211/key.c Key handling basics 301 </sect1> 302 <sect1> 303 <title>MORE TBD</title> 304 <para>TBD</para> 305 </sect1> 306 </chapter> 307 308 <chapter id="rx-processing"> 309 <title>Receive processing</title> 310 <para>TBD</para> 311 </chapter> 312 313 <chapter id="tx-processing"> 314 <title>Transmit processing</title> 315 <para>TBD</para> 316 </chapter> 317 318 <chapter id="sta-info"> 319 <title>Station info handling</title> 320 <sect1> 321 <title>Programming information</title> 322!Fnet/mac80211/sta_info.h sta_info 323!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags 324 </sect1> 325 <sect1> 326 <title>STA information lifetime rules</title> 327!Pnet/mac80211/sta_info.c STA information lifetime rules 328 </sect1> 329 </chapter> 330 331 <chapter id="synchronisation"> 332 <title>Synchronisation</title> 333 <para>TBD</para> 334 <para>Locking, lots of RCU</para> 335 </chapter> 336 </part> 337</book> 338