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