Pileus Git - ~andy/linux/blob - 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         <para>
  73 MISSING
  74         </para>
  75       </abstract>
  76     </bookinfo>
  77     <part><chapter>
  78 !Finclude/net/cfg80211.h ieee80211_band
  79     </chapter></part>
  80   </book>
  81   <book id="mac80211-developers-guide">
  82     <bookinfo>
  83       <title>The mac80211 subsystem</title>
  84       <abstract>
  85 !Pinclude/net/mac80211.h Introduction
  86 !Pinclude/net/mac80211.h Warning
  87       </abstract>
  88     </bookinfo>
  89
  90     <toc></toc>
  91
  92   <!--
  93   Generally, this document shall be ordered by increasing complexity.
  94   It is important to note that readers should be able to read only
  95   the first few sections to get a working driver and only advanced
  96   usage should require reading the full document.
  97   -->
  98
  99     <part>
 100       <title>The basic mac80211 driver interface</title>
 101       <partintro>
 102         <para>
 103           You should read and understand the information contained
 104           within this part of the book while implementing a driver.
 105           In some chapters, advanced usage is noted, that may be
 106           skipped at first.
 107         </para>
 108         <para>
 109           This part of the book only covers station and monitor mode
 110           functionality, additional information required to implement
 111           the other modes is covered in the second part of the book.
 112         </para>
 113       </partintro>
 114
 115       <chapter id="basics">
 116         <title>Basic hardware handling</title>
 117         <para>TBD</para>
 118         <para>
 119           This chapter shall contain information on getting a hw
 120           struct allocated and registered with mac80211.
 121         </para>
 122         <para>
 123           Since it is required to allocate rates/modes before registering
 124           a hw struct, this chapter shall also contain information on setting
 125           up the rate/mode structs.
 126         </para>
 127         <para>
 128           Additionally, some discussion about the callbacks and
 129           the general programming model should be in here, including
 130           the definition of ieee80211_ops which will be referred to
 131           a lot.
 132         </para>
 133         <para>
 134           Finally, a discussion of hardware capabilities should be done
 135           with references to other parts of the book.
 136         </para>
 137   <!-- intentionally multiple !F lines to get proper order -->
 138 !Finclude/net/mac80211.h ieee80211_hw
 139 !Finclude/net/mac80211.h ieee80211_hw_flags
 140 !Finclude/net/mac80211.h SET_IEEE80211_DEV
 141 !Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
 142 !Finclude/net/mac80211.h ieee80211_ops
 143 !Finclude/net/mac80211.h ieee80211_alloc_hw
 144 !Finclude/net/mac80211.h ieee80211_register_hw
 145 !Finclude/net/mac80211.h ieee80211_get_tx_led_name
 146 !Finclude/net/mac80211.h ieee80211_get_rx_led_name
 147 !Finclude/net/mac80211.h ieee80211_get_assoc_led_name
 148 !Finclude/net/mac80211.h ieee80211_get_radio_led_name
 149 !Finclude/net/mac80211.h ieee80211_unregister_hw
 150 !Finclude/net/mac80211.h ieee80211_free_hw
 151       </chapter>
 152
 153       <chapter id="phy-handling">
 154         <title>PHY configuration</title>
 155         <para>TBD</para>
 156         <para>
 157           This chapter should describe PHY handling including
 158           start/stop callbacks and the various structures used.
 159         </para>
 160 !Finclude/net/mac80211.h ieee80211_conf
 161 !Finclude/net/mac80211.h ieee80211_conf_flags
 162       </chapter>
 163
 164       <chapter id="iface-handling">
 165         <title>Virtual interfaces</title>
 166         <para>TBD</para>
 167         <para>
 168           This chapter should describe virtual interface basics
 169           that are relevant to the driver (VLANs, MGMT etc are not.)
 170           It should explain the use of the add_iface/remove_iface
 171           callbacks as well as the interface configuration callbacks.
 172         </para>
 173         <para>Things related to AP mode should be discussed there.</para>
 174         <para>
 175           Things related to supporting multiple interfaces should be
 176           in the appropriate chapter, a BIG FAT note should be here about
 177           this though and the recommendation to allow only a single
 178           interface in STA mode at first!
 179         </para>
 180 !Finclude/net/mac80211.h ieee80211_vif
 181       </chapter>
 182
 183       <chapter id="rx-tx">
 184         <title>Receive and transmit processing</title>
 185         <sect1>
 186           <title>what should be here</title>
 187           <para>TBD</para>
 188           <para>
 189             This should describe the receive and transmit
 190             paths in mac80211/the drivers as well as
 191             transmit status handling.
 192           </para>
 193         </sect1>
 194         <sect1>
 195           <title>Frame format</title>
 196 !Pinclude/net/mac80211.h Frame format
 197         </sect1>
 198         <sect1>
 199           <title>Packet alignment</title>
 200 !Pnet/mac80211/rx.c Packet alignment
 201         </sect1>
 202         <sect1>
 203           <title>Calling into mac80211 from interrupts</title>
 204 !Pinclude/net/mac80211.h Calling mac80211 from interrupts
 205         </sect1>
 206         <sect1>
 207           <title>functions/definitions</title>
 208 !Finclude/net/mac80211.h ieee80211_rx_status
 209 !Finclude/net/mac80211.h mac80211_rx_flags
 210 !Finclude/net/mac80211.h ieee80211_tx_info
 211 !Finclude/net/mac80211.h ieee80211_rx
 212 !Finclude/net/mac80211.h ieee80211_rx_irqsafe
 213 !Finclude/net/mac80211.h ieee80211_tx_status
 214 !Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
 215 !Finclude/net/mac80211.h ieee80211_rts_get
 216 !Finclude/net/mac80211.h ieee80211_rts_duration
 217 !Finclude/net/mac80211.h ieee80211_ctstoself_get
 218 !Finclude/net/mac80211.h ieee80211_ctstoself_duration
 219 !Finclude/net/mac80211.h ieee80211_generic_frame_duration
 220 !Finclude/net/mac80211.h ieee80211_wake_queue
 221 !Finclude/net/mac80211.h ieee80211_stop_queue
 222 !Finclude/net/mac80211.h ieee80211_wake_queues
 223 !Finclude/net/mac80211.h ieee80211_stop_queues
 224         </sect1>
 225       </chapter>
 226
 227       <chapter id="filters">
 228         <title>Frame filtering</title>
 229 !Pinclude/net/mac80211.h Frame filtering
 230 !Finclude/net/mac80211.h ieee80211_filter_flags
 231       </chapter>
 232     </part>
 233
 234     <part id="advanced">
 235       <title>Advanced driver interface</title>
 236       <partintro>
 237         <para>
 238          Information contained within this part of the book is
 239          of interest only for advanced interaction of mac80211
 240          with drivers to exploit more hardware capabilities and
 241          improve performance.
 242         </para>
 243       </partintro>
 244
 245       <chapter id="hardware-crypto-offload">
 246         <title>Hardware crypto acceleration</title>
 247 !Pinclude/net/mac80211.h Hardware crypto acceleration
 248   <!-- intentionally multiple !F lines to get proper order -->
 249 !Finclude/net/mac80211.h set_key_cmd
 250 !Finclude/net/mac80211.h ieee80211_key_conf
 251 !Finclude/net/mac80211.h ieee80211_key_alg
 252 !Finclude/net/mac80211.h ieee80211_key_flags
 253       </chapter>
 254
 255       <chapter id="powersave">
 256         <title>Powersave support</title>
 257 !Pinclude/net/mac80211.h Powersave support
 258       </chapter>
 259
 260       <chapter id="beacon-filter">
 261         <title>Beacon filter support</title>
 262 !Pinclude/net/mac80211.h Beacon filter support
 263 !Finclude/net/mac80211.h ieee80211_beacon_loss
 264       </chapter>
 265
 266       <chapter id="qos">
 267         <title>Multiple queues and QoS support</title>
 268         <para>TBD</para>
 269 !Finclude/net/mac80211.h ieee80211_tx_queue_params
 270       </chapter>
 271
 272       <chapter id="AP">
 273         <title>Access point mode support</title>
 274         <para>TBD</para>
 275         <para>Some parts of the if_conf should be discussed here instead</para>
 276         <para>
 277           Insert notes about VLAN interfaces with hw crypto here or
 278           in the hw crypto chapter.
 279         </para>
 280 !Finclude/net/mac80211.h ieee80211_get_buffered_bc
 281 !Finclude/net/mac80211.h ieee80211_beacon_get
 282       </chapter>
 283
 284       <chapter id="multi-iface">
 285         <title>Supporting multiple virtual interfaces</title>
 286         <para>TBD</para>
 287         <para>
 288           Note: WDS with identical MAC address should almost always be OK
 289         </para>
 290         <para>
 291           Insert notes about having multiple virtual interfaces with
 292           different MAC addresses here, note which configurations are
 293           supported by mac80211, add notes about supporting hw crypto
 294           with it.
 295         </para>
 296       </chapter>
 297
 298       <chapter id="hardware-scan-offload">
 299         <title>Hardware scan offload</title>
 300         <para>TBD</para>
 301 !Finclude/net/mac80211.h ieee80211_scan_completed
 302       </chapter>
 303     </part>
 304
 305     <part id="rate-control">
 306       <title>Rate control interface</title>
 307       <partintro>
 308         <para>TBD</para>
 309         <para>
 310          This part of the book describes the rate control algorithm
 311          interface and how it relates to mac80211 and drivers.
 312         </para>
 313       </partintro>
 314       <chapter id="dummy">
 315         <title>dummy chapter</title>
 316         <para>TBD</para>
 317       </chapter>
 318     </part>
 319
 320     <part id="internal">
 321       <title>Internals</title>
 322       <partintro>
 323         <para>TBD</para>
 324         <para>
 325          This part of the book describes mac80211 internals.
 326         </para>
 327       </partintro>
 328
 329       <chapter id="key-handling">
 330         <title>Key handling</title>
 331         <sect1>
 332           <title>Key handling basics</title>
 333 !Pnet/mac80211/key.c Key handling basics
 334         </sect1>
 335         <sect1>
 336           <title>MORE TBD</title>
 337           <para>TBD</para>
 338         </sect1>
 339       </chapter>
 340
 341       <chapter id="rx-processing">
 342         <title>Receive processing</title>
 343         <para>TBD</para>
 344       </chapter>
 345
 346       <chapter id="tx-processing">
 347         <title>Transmit processing</title>
 348         <para>TBD</para>
 349       </chapter>
 350
 351       <chapter id="sta-info">
 352         <title>Station info handling</title>
 353         <sect1>
 354           <title>Programming information</title>
 355 !Fnet/mac80211/sta_info.h sta_info
 356 !Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
 357         </sect1>
 358         <sect1>
 359           <title>STA information lifetime rules</title>
 360 !Pnet/mac80211/sta_info.c STA information lifetime rules
 361         </sect1>
 362       </chapter>
 363
 364       <chapter id="synchronisation">
 365         <title>Synchronisation</title>
 366         <para>TBD</para>
 367         <para>Locking, lots of RCU</para>
 368       </chapter>
 369     </part>
 370   </book>
 371 </set>