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