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 !Ainclude/net/cfg80211.h
  69     <bookinfo>
  70       <title>The cfg80211 subsystem</title>
  71
  72       <abstract>
  73 !Pinclude/net/cfg80211.h Introduction
  74       </abstract>
  75     </bookinfo>
  76       <chapter>
  77       <title>Device registration</title>
  78 !Pinclude/net/cfg80211.h Device registration
  79 !Finclude/net/cfg80211.h ieee80211_band
  80 !Finclude/net/cfg80211.h ieee80211_channel_flags
  81 !Finclude/net/cfg80211.h ieee80211_channel
  82 !Finclude/net/cfg80211.h ieee80211_rate_flags
  83 !Finclude/net/cfg80211.h ieee80211_rate
  84 !Finclude/net/cfg80211.h ieee80211_sta_ht_cap
  85 !Finclude/net/cfg80211.h ieee80211_supported_band
  86 !Finclude/net/cfg80211.h cfg80211_signal_type
  87 !Finclude/net/cfg80211.h wiphy_params_flags
  88 !Finclude/net/cfg80211.h wiphy_flags
  89 !Finclude/net/cfg80211.h wiphy
  90 !Finclude/net/cfg80211.h wireless_dev
  91 !Finclude/net/cfg80211.h wiphy_new
  92 !Finclude/net/cfg80211.h wiphy_register
  93 !Finclude/net/cfg80211.h wiphy_unregister
  94 !Finclude/net/cfg80211.h wiphy_free
  95
  96 !Finclude/net/cfg80211.h wiphy_name
  97 !Finclude/net/cfg80211.h wiphy_dev
  98 !Finclude/net/cfg80211.h wiphy_priv
  99 !Finclude/net/cfg80211.h priv_to_wiphy
 100 !Finclude/net/cfg80211.h set_wiphy_dev
 101 !Finclude/net/cfg80211.h wdev_priv
 102       </chapter>
 103       <chapter>
 104       <title>Actions and configuration</title>
 105 !Pinclude/net/cfg80211.h Actions and configuration
 106 !Finclude/net/cfg80211.h cfg80211_ops
 107 !Finclude/net/cfg80211.h vif_params
 108 !Finclude/net/cfg80211.h key_params
 109 !Finclude/net/cfg80211.h survey_info_flags
 110 !Finclude/net/cfg80211.h survey_info
 111 !Finclude/net/cfg80211.h beacon_parameters
 112 !Finclude/net/cfg80211.h plink_actions
 113 !Finclude/net/cfg80211.h station_parameters
 114 !Finclude/net/cfg80211.h station_info_flags
 115 !Finclude/net/cfg80211.h rate_info_flags
 116 !Finclude/net/cfg80211.h rate_info
 117 !Finclude/net/cfg80211.h station_info
 118 !Finclude/net/cfg80211.h monitor_flags
 119 !Finclude/net/cfg80211.h mpath_info_flags
 120 !Finclude/net/cfg80211.h mpath_info
 121 !Finclude/net/cfg80211.h bss_parameters
 122 !Finclude/net/cfg80211.h ieee80211_txq_params
 123 !Finclude/net/cfg80211.h cfg80211_crypto_settings
 124 !Finclude/net/cfg80211.h cfg80211_auth_request
 125 !Finclude/net/cfg80211.h cfg80211_assoc_request
 126 !Finclude/net/cfg80211.h cfg80211_deauth_request
 127 !Finclude/net/cfg80211.h cfg80211_disassoc_request
 128 !Finclude/net/cfg80211.h cfg80211_ibss_params
 129 !Finclude/net/cfg80211.h cfg80211_connect_params
 130 !Finclude/net/cfg80211.h cfg80211_pmksa
 131 !Finclude/net/cfg80211.h cfg80211_send_rx_auth
 132 !Finclude/net/cfg80211.h cfg80211_send_auth_timeout
 133 !Finclude/net/cfg80211.h __cfg80211_auth_canceled
 134 !Finclude/net/cfg80211.h cfg80211_send_rx_assoc
 135 !Finclude/net/cfg80211.h cfg80211_send_assoc_timeout
 136 !Finclude/net/cfg80211.h cfg80211_send_deauth
 137 !Finclude/net/cfg80211.h __cfg80211_send_deauth
 138 !Finclude/net/cfg80211.h cfg80211_send_disassoc
 139 !Finclude/net/cfg80211.h __cfg80211_send_disassoc
 140 !Finclude/net/cfg80211.h cfg80211_ibss_joined
 141 !Finclude/net/cfg80211.h cfg80211_connect_result
 142 !Finclude/net/cfg80211.h cfg80211_roamed
 143 !Finclude/net/cfg80211.h cfg80211_disconnected
 144 !Finclude/net/cfg80211.h cfg80211_ready_on_channel
 145 !Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired
 146 !Finclude/net/cfg80211.h cfg80211_new_sta
 147 !Finclude/net/cfg80211.h cfg80211_rx_mgmt
 148 !Finclude/net/cfg80211.h cfg80211_mgmt_tx_status
 149 !Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify
 150 !Finclude/net/cfg80211.h cfg80211_michael_mic_failure
 151       </chapter>
 152       <chapter>
 153       <title>Scanning and BSS list handling</title>
 154 !Pinclude/net/cfg80211.h Scanning and BSS list handling
 155 !Finclude/net/cfg80211.h cfg80211_ssid
 156 !Finclude/net/cfg80211.h cfg80211_scan_request
 157 !Finclude/net/cfg80211.h cfg80211_scan_done
 158 !Finclude/net/cfg80211.h cfg80211_bss
 159 !Finclude/net/cfg80211.h cfg80211_inform_bss_frame
 160 !Finclude/net/cfg80211.h cfg80211_inform_bss
 161 !Finclude/net/cfg80211.h cfg80211_unlink_bss
 162 !Finclude/net/cfg80211.h cfg80211_find_ie
 163 !Finclude/net/cfg80211.h ieee80211_bss_get_ie
 164       </chapter>
 165       <chapter>
 166       <title>Utility functions</title>
 167 !Pinclude/net/cfg80211.h Utility functions
 168 !Finclude/net/cfg80211.h ieee80211_channel_to_frequency
 169 !Finclude/net/cfg80211.h ieee80211_frequency_to_channel
 170 !Finclude/net/cfg80211.h ieee80211_get_channel
 171 !Finclude/net/cfg80211.h ieee80211_get_response_rate
 172 !Finclude/net/cfg80211.h ieee80211_hdrlen
 173 !Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb
 174 !Finclude/net/cfg80211.h ieee80211_radiotap_iterator
 175       </chapter>
 176       <chapter>
 177       <title>Data path helpers</title>
 178 !Pinclude/net/cfg80211.h Data path helpers
 179 !Finclude/net/cfg80211.h ieee80211_data_to_8023
 180 !Finclude/net/cfg80211.h ieee80211_data_from_8023
 181 !Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s
 182 !Finclude/net/cfg80211.h cfg80211_classify8021d
 183       </chapter>
 184       <chapter>
 185       <title>Regulatory enforcement infrastructure</title>
 186 !Pinclude/net/cfg80211.h Regulatory enforcement infrastructure
 187 !Finclude/net/cfg80211.h regulatory_hint
 188 !Finclude/net/cfg80211.h wiphy_apply_custom_regulatory
 189 !Finclude/net/cfg80211.h freq_reg_info
 190       </chapter>
 191       <chapter>
 192       <title>RFkill integration</title>
 193 !Pinclude/net/cfg80211.h RFkill integration
 194 !Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state
 195 !Finclude/net/cfg80211.h wiphy_rfkill_start_polling
 196 !Finclude/net/cfg80211.h wiphy_rfkill_stop_polling
 197       </chapter>
 198       <chapter>
 199       <title>Test mode</title>
 200 !Pinclude/net/cfg80211.h Test mode
 201 !Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb
 202 !Finclude/net/cfg80211.h cfg80211_testmode_reply
 203 !Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb
 204 !Finclude/net/cfg80211.h cfg80211_testmode_event
 205       </chapter>
 206   </book>
 207   <book id="mac80211-developers-guide">
 208     <bookinfo>
 209       <title>The mac80211 subsystem</title>
 210       <abstract>
 211 !Pinclude/net/mac80211.h Introduction
 212 !Pinclude/net/mac80211.h Warning
 213       </abstract>
 214     </bookinfo>
 215
 216     <toc></toc>
 217
 218   <!--
 219   Generally, this document shall be ordered by increasing complexity.
 220   It is important to note that readers should be able to read only
 221   the first few sections to get a working driver and only advanced
 222   usage should require reading the full document.
 223   -->
 224
 225     <part>
 226       <title>The basic mac80211 driver interface</title>
 227       <partintro>
 228         <para>
 229           You should read and understand the information contained
 230           within this part of the book while implementing a driver.
 231           In some chapters, advanced usage is noted, that may be
 232           skipped at first.
 233         </para>
 234         <para>
 235           This part of the book only covers station and monitor mode
 236           functionality, additional information required to implement
 237           the other modes is covered in the second part of the book.
 238         </para>
 239       </partintro>
 240
 241       <chapter id="basics">
 242         <title>Basic hardware handling</title>
 243         <para>TBD</para>
 244         <para>
 245           This chapter shall contain information on getting a hw
 246           struct allocated and registered with mac80211.
 247         </para>
 248         <para>
 249           Since it is required to allocate rates/modes before registering
 250           a hw struct, this chapter shall also contain information on setting
 251           up the rate/mode structs.
 252         </para>
 253         <para>
 254           Additionally, some discussion about the callbacks and
 255           the general programming model should be in here, including
 256           the definition of ieee80211_ops which will be referred to
 257           a lot.
 258         </para>
 259         <para>
 260           Finally, a discussion of hardware capabilities should be done
 261           with references to other parts of the book.
 262         </para>
 263   <!-- intentionally multiple !F lines to get proper order -->
 264 !Finclude/net/mac80211.h ieee80211_hw
 265 !Finclude/net/mac80211.h ieee80211_hw_flags
 266 !Finclude/net/mac80211.h SET_IEEE80211_DEV
 267 !Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR
 268 !Finclude/net/mac80211.h ieee80211_ops
 269 !Finclude/net/mac80211.h ieee80211_alloc_hw
 270 !Finclude/net/mac80211.h ieee80211_register_hw
 271 !Finclude/net/mac80211.h ieee80211_get_tx_led_name
 272 !Finclude/net/mac80211.h ieee80211_get_rx_led_name
 273 !Finclude/net/mac80211.h ieee80211_get_assoc_led_name
 274 !Finclude/net/mac80211.h ieee80211_get_radio_led_name
 275 !Finclude/net/mac80211.h ieee80211_unregister_hw
 276 !Finclude/net/mac80211.h ieee80211_free_hw
 277       </chapter>
 278
 279       <chapter id="phy-handling">
 280         <title>PHY configuration</title>
 281         <para>TBD</para>
 282         <para>
 283           This chapter should describe PHY handling including
 284           start/stop callbacks and the various structures used.
 285         </para>
 286 !Finclude/net/mac80211.h ieee80211_conf
 287 !Finclude/net/mac80211.h ieee80211_conf_flags
 288       </chapter>
 289
 290       <chapter id="iface-handling">
 291         <title>Virtual interfaces</title>
 292         <para>TBD</para>
 293         <para>
 294           This chapter should describe virtual interface basics
 295           that are relevant to the driver (VLANs, MGMT etc are not.)
 296           It should explain the use of the add_iface/remove_iface
 297           callbacks as well as the interface configuration callbacks.
 298         </para>
 299         <para>Things related to AP mode should be discussed there.</para>
 300         <para>
 301           Things related to supporting multiple interfaces should be
 302           in the appropriate chapter, a BIG FAT note should be here about
 303           this though and the recommendation to allow only a single
 304           interface in STA mode at first!
 305         </para>
 306 !Finclude/net/mac80211.h ieee80211_vif
 307       </chapter>
 308
 309       <chapter id="rx-tx">
 310         <title>Receive and transmit processing</title>
 311         <sect1>
 312           <title>what should be here</title>
 313           <para>TBD</para>
 314           <para>
 315             This should describe the receive and transmit
 316             paths in mac80211/the drivers as well as
 317             transmit status handling.
 318           </para>
 319         </sect1>
 320         <sect1>
 321           <title>Frame format</title>
 322 !Pinclude/net/mac80211.h Frame format
 323         </sect1>
 324         <sect1>
 325           <title>Packet alignment</title>
 326 !Pnet/mac80211/rx.c Packet alignment
 327         </sect1>
 328         <sect1>
 329           <title>Calling into mac80211 from interrupts</title>
 330 !Pinclude/net/mac80211.h Calling mac80211 from interrupts
 331         </sect1>
 332         <sect1>
 333           <title>functions/definitions</title>
 334 !Finclude/net/mac80211.h ieee80211_rx_status
 335 !Finclude/net/mac80211.h mac80211_rx_flags
 336 !Finclude/net/mac80211.h ieee80211_tx_info
 337 !Finclude/net/mac80211.h ieee80211_rx
 338 !Finclude/net/mac80211.h ieee80211_rx_irqsafe
 339 !Finclude/net/mac80211.h ieee80211_tx_status
 340 !Finclude/net/mac80211.h ieee80211_tx_status_irqsafe
 341 !Finclude/net/mac80211.h ieee80211_rts_get
 342 !Finclude/net/mac80211.h ieee80211_rts_duration
 343 !Finclude/net/mac80211.h ieee80211_ctstoself_get
 344 !Finclude/net/mac80211.h ieee80211_ctstoself_duration
 345 !Finclude/net/mac80211.h ieee80211_generic_frame_duration
 346 !Finclude/net/mac80211.h ieee80211_wake_queue
 347 !Finclude/net/mac80211.h ieee80211_stop_queue
 348 !Finclude/net/mac80211.h ieee80211_wake_queues
 349 !Finclude/net/mac80211.h ieee80211_stop_queues
 350         </sect1>
 351       </chapter>
 352
 353       <chapter id="filters">
 354         <title>Frame filtering</title>
 355 !Pinclude/net/mac80211.h Frame filtering
 356 !Finclude/net/mac80211.h ieee80211_filter_flags
 357       </chapter>
 358     </part>
 359
 360     <part id="advanced">
 361       <title>Advanced driver interface</title>
 362       <partintro>
 363         <para>
 364          Information contained within this part of the book is
 365          of interest only for advanced interaction of mac80211
 366          with drivers to exploit more hardware capabilities and
 367          improve performance.
 368         </para>
 369       </partintro>
 370
 371       <chapter id="hardware-crypto-offload">
 372         <title>Hardware crypto acceleration</title>
 373 !Pinclude/net/mac80211.h Hardware crypto acceleration
 374   <!-- intentionally multiple !F lines to get proper order -->
 375 !Finclude/net/mac80211.h set_key_cmd
 376 !Finclude/net/mac80211.h ieee80211_key_conf
 377 !Finclude/net/mac80211.h ieee80211_key_flags
 378       </chapter>
 379
 380       <chapter id="powersave">
 381         <title>Powersave support</title>
 382 !Pinclude/net/mac80211.h Powersave support
 383       </chapter>
 384
 385       <chapter id="beacon-filter">
 386         <title>Beacon filter support</title>
 387 !Pinclude/net/mac80211.h Beacon filter support
 388 !Finclude/net/mac80211.h ieee80211_beacon_loss
 389       </chapter>
 390
 391       <chapter id="qos">
 392         <title>Multiple queues and QoS support</title>
 393         <para>TBD</para>
 394 !Finclude/net/mac80211.h ieee80211_tx_queue_params
 395       </chapter>
 396
 397       <chapter id="AP">
 398         <title>Access point mode support</title>
 399         <para>TBD</para>
 400         <para>Some parts of the if_conf should be discussed here instead</para>
 401         <para>
 402           Insert notes about VLAN interfaces with hw crypto here or
 403           in the hw crypto chapter.
 404         </para>
 405 !Finclude/net/mac80211.h ieee80211_get_buffered_bc
 406 !Finclude/net/mac80211.h ieee80211_beacon_get
 407       </chapter>
 408
 409       <chapter id="multi-iface">
 410         <title>Supporting multiple virtual interfaces</title>
 411         <para>TBD</para>
 412         <para>
 413           Note: WDS with identical MAC address should almost always be OK
 414         </para>
 415         <para>
 416           Insert notes about having multiple virtual interfaces with
 417           different MAC addresses here, note which configurations are
 418           supported by mac80211, add notes about supporting hw crypto
 419           with it.
 420         </para>
 421       </chapter>
 422
 423       <chapter id="hardware-scan-offload">
 424         <title>Hardware scan offload</title>
 425         <para>TBD</para>
 426 !Finclude/net/mac80211.h ieee80211_scan_completed
 427       </chapter>
 428     </part>
 429
 430     <part id="rate-control">
 431       <title>Rate control interface</title>
 432       <partintro>
 433         <para>TBD</para>
 434         <para>
 435          This part of the book describes the rate control algorithm
 436          interface and how it relates to mac80211 and drivers.
 437         </para>
 438       </partintro>
 439       <chapter id="dummy">
 440         <title>dummy chapter</title>
 441         <para>TBD</para>
 442       </chapter>
 443     </part>
 444
 445     <part id="internal">
 446       <title>Internals</title>
 447       <partintro>
 448         <para>TBD</para>
 449         <para>
 450          This part of the book describes mac80211 internals.
 451         </para>
 452       </partintro>
 453
 454       <chapter id="key-handling">
 455         <title>Key handling</title>
 456         <sect1>
 457           <title>Key handling basics</title>
 458 !Pnet/mac80211/key.c Key handling basics
 459         </sect1>
 460         <sect1>
 461           <title>MORE TBD</title>
 462           <para>TBD</para>
 463         </sect1>
 464       </chapter>
 465
 466       <chapter id="rx-processing">
 467         <title>Receive processing</title>
 468         <para>TBD</para>
 469       </chapter>
 470
 471       <chapter id="tx-processing">
 472         <title>Transmit processing</title>
 473         <para>TBD</para>
 474       </chapter>
 475
 476       <chapter id="sta-info">
 477         <title>Station info handling</title>
 478         <sect1>
 479           <title>Programming information</title>
 480 !Fnet/mac80211/sta_info.h sta_info
 481 !Fnet/mac80211/sta_info.h ieee80211_sta_info_flags
 482         </sect1>
 483         <sect1>
 484           <title>STA information lifetime rules</title>
 485 !Pnet/mac80211/sta_info.c STA information lifetime rules
 486         </sect1>
 487       </chapter>
 488
 489       <chapter id="synchronisation">
 490         <title>Synchronisation</title>
 491         <para>TBD</para>
 492         <para>Locking, lots of RCU</para>
 493       </chapter>
 494     </part>
 495   </book>
 496 </set>