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 </chapter> 102 <chapter> 103 <title>Actions and configuration</title> 104!Pinclude/net/cfg80211.h Actions and configuration 105!Finclude/net/cfg80211.h cfg80211_ops 106!Finclude/net/cfg80211.h vif_params 107!Finclude/net/cfg80211.h key_params 108!Finclude/net/cfg80211.h survey_info_flags 109!Finclude/net/cfg80211.h survey_info 110!Finclude/net/cfg80211.h cfg80211_beacon_data 111!Finclude/net/cfg80211.h cfg80211_ap_settings 112!Finclude/net/cfg80211.h station_parameters 113!Finclude/net/cfg80211.h station_info_flags 114!Finclude/net/cfg80211.h rate_info_flags 115!Finclude/net/cfg80211.h rate_info 116!Finclude/net/cfg80211.h station_info 117!Finclude/net/cfg80211.h monitor_flags 118!Finclude/net/cfg80211.h mpath_info_flags 119!Finclude/net/cfg80211.h mpath_info 120!Finclude/net/cfg80211.h bss_parameters 121!Finclude/net/cfg80211.h ieee80211_txq_params 122!Finclude/net/cfg80211.h cfg80211_crypto_settings 123!Finclude/net/cfg80211.h cfg80211_auth_request 124!Finclude/net/cfg80211.h cfg80211_assoc_request 125!Finclude/net/cfg80211.h cfg80211_deauth_request 126!Finclude/net/cfg80211.h cfg80211_disassoc_request 127!Finclude/net/cfg80211.h cfg80211_ibss_params 128!Finclude/net/cfg80211.h cfg80211_connect_params 129!Finclude/net/cfg80211.h cfg80211_pmksa 130!Finclude/net/cfg80211.h cfg80211_send_rx_auth 131!Finclude/net/cfg80211.h cfg80211_send_auth_timeout 132!Finclude/net/cfg80211.h cfg80211_send_rx_assoc 133!Finclude/net/cfg80211.h cfg80211_send_assoc_timeout 134!Finclude/net/cfg80211.h cfg80211_send_deauth 135!Finclude/net/cfg80211.h __cfg80211_send_deauth 136!Finclude/net/cfg80211.h cfg80211_send_disassoc 137!Finclude/net/cfg80211.h __cfg80211_send_disassoc 138!Finclude/net/cfg80211.h cfg80211_ibss_joined 139!Finclude/net/cfg80211.h cfg80211_connect_result 140!Finclude/net/cfg80211.h cfg80211_roamed 141!Finclude/net/cfg80211.h cfg80211_disconnected 142!Finclude/net/cfg80211.h cfg80211_ready_on_channel 143!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired 144!Finclude/net/cfg80211.h cfg80211_new_sta 145!Finclude/net/cfg80211.h cfg80211_rx_mgmt 146!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status 147!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify 148!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify 149!Finclude/net/cfg80211.h cfg80211_michael_mic_failure 150 </chapter> 151 <chapter> 152 <title>Scanning and BSS list handling</title> 153!Pinclude/net/cfg80211.h Scanning and BSS list handling 154!Finclude/net/cfg80211.h cfg80211_ssid 155!Finclude/net/cfg80211.h cfg80211_scan_request 156!Finclude/net/cfg80211.h cfg80211_scan_done 157!Finclude/net/cfg80211.h cfg80211_bss 158!Finclude/net/cfg80211.h cfg80211_inform_bss_frame 159!Finclude/net/cfg80211.h cfg80211_inform_bss 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_control_flags 332!Finclude/net/mac80211.h mac80211_rate_control_flags 333!Finclude/net/mac80211.h ieee80211_tx_rate 334!Finclude/net/mac80211.h ieee80211_tx_info 335!Finclude/net/mac80211.h ieee80211_tx_info_clear_status 336!Finclude/net/mac80211.h ieee80211_rx 337!Finclude/net/mac80211.h ieee80211_rx_ni 338!Finclude/net/mac80211.h ieee80211_rx_irqsafe 339!Finclude/net/mac80211.h ieee80211_tx_status 340!Finclude/net/mac80211.h ieee80211_tx_status_ni 341!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe 342!Finclude/net/mac80211.h ieee80211_rts_get 343!Finclude/net/mac80211.h ieee80211_rts_duration 344!Finclude/net/mac80211.h ieee80211_ctstoself_get 345!Finclude/net/mac80211.h ieee80211_ctstoself_duration 346!Finclude/net/mac80211.h ieee80211_generic_frame_duration 347!Finclude/net/mac80211.h ieee80211_wake_queue 348!Finclude/net/mac80211.h ieee80211_stop_queue 349!Finclude/net/mac80211.h ieee80211_wake_queues 350!Finclude/net/mac80211.h ieee80211_stop_queues 351!Finclude/net/mac80211.h ieee80211_queue_stopped 352 </sect1> 353 </chapter> 354 355 <chapter id="filters"> 356 <title>Frame filtering</title> 357!Pinclude/net/mac80211.h Frame filtering 358!Finclude/net/mac80211.h ieee80211_filter_flags 359 </chapter> 360 361 <chapter id="workqueue"> 362 <title>The mac80211 workqueue</title> 363!Pinclude/net/mac80211.h mac80211 workqueue 364!Finclude/net/mac80211.h ieee80211_queue_work 365!Finclude/net/mac80211.h ieee80211_queue_delayed_work 366 </chapter> 367 </part> 368 369 <part id="advanced"> 370 <title>Advanced driver interface</title> 371 <partintro> 372 <para> 373 Information contained within this part of the book is 374 of interest only for advanced interaction of mac80211 375 with drivers to exploit more hardware capabilities and 376 improve performance. 377 </para> 378 </partintro> 379 380 <chapter id="led-support"> 381 <title>LED support</title> 382 <para> 383 Mac80211 supports various ways of blinking LEDs. Wherever possible, 384 device LEDs should be exposed as LED class devices and hooked up to 385 the appropriate trigger, which will then be triggered appropriately 386 by mac80211. 387 </para> 388!Finclude/net/mac80211.h ieee80211_get_tx_led_name 389!Finclude/net/mac80211.h ieee80211_get_rx_led_name 390!Finclude/net/mac80211.h ieee80211_get_assoc_led_name 391!Finclude/net/mac80211.h ieee80211_get_radio_led_name 392!Finclude/net/mac80211.h ieee80211_tpt_blink 393!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags 394!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger 395 </chapter> 396 397 <chapter id="hardware-crypto-offload"> 398 <title>Hardware crypto acceleration</title> 399!Pinclude/net/mac80211.h Hardware crypto acceleration 400 <!-- intentionally multiple !F lines to get proper order --> 401!Finclude/net/mac80211.h set_key_cmd 402!Finclude/net/mac80211.h ieee80211_key_conf 403!Finclude/net/mac80211.h ieee80211_key_flags 404!Finclude/net/mac80211.h ieee80211_get_tkip_p1k 405!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv 406!Finclude/net/mac80211.h ieee80211_get_tkip_p2k 407 </chapter> 408 409 <chapter id="powersave"> 410 <title>Powersave support</title> 411!Pinclude/net/mac80211.h Powersave support 412 </chapter> 413 414 <chapter id="beacon-filter"> 415 <title>Beacon filter support</title> 416!Pinclude/net/mac80211.h Beacon filter support 417!Finclude/net/mac80211.h ieee80211_beacon_loss 418 </chapter> 419 420 <chapter id="qos"> 421 <title>Multiple queues and QoS support</title> 422 <para>TBD</para> 423!Finclude/net/mac80211.h ieee80211_tx_queue_params 424 </chapter> 425 426 <chapter id="AP"> 427 <title>Access point mode support</title> 428 <para>TBD</para> 429 <para>Some parts of the if_conf should be discussed here instead</para> 430 <para> 431 Insert notes about VLAN interfaces with hw crypto here or 432 in the hw crypto chapter. 433 </para> 434 <section id="ps-client"> 435 <title>support for powersaving clients</title> 436!Pinclude/net/mac80211.h AP support for powersaving clients 437 </section> 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 </chapter> 447 448 <chapter id="multi-iface"> 449 <title>Supporting multiple virtual interfaces</title> 450 <para>TBD</para> 451 <para> 452 Note: WDS with identical MAC address should almost always be OK 453 </para> 454 <para> 455 Insert notes about having multiple virtual interfaces with 456 different MAC addresses here, note which configurations are 457 supported by mac80211, add notes about supporting hw crypto 458 with it. 459 </para> 460!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces 461!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic 462 </chapter> 463 464 <chapter id="station-handling"> 465 <title>Station handling</title> 466 <para>TODO</para> 467!Finclude/net/mac80211.h ieee80211_sta 468!Finclude/net/mac80211.h sta_notify_cmd 469!Finclude/net/mac80211.h ieee80211_find_sta 470!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr 471 </chapter> 472 473 <chapter id="hardware-scan-offload"> 474 <title>Hardware scan offload</title> 475 <para>TBD</para> 476!Finclude/net/mac80211.h ieee80211_scan_completed 477 </chapter> 478 479 <chapter id="aggregation"> 480 <title>Aggregation</title> 481 <sect1> 482 <title>TX A-MPDU aggregation</title> 483!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation 484!Cnet/mac80211/agg-tx.c 485 </sect1> 486 <sect1> 487 <title>RX A-MPDU aggregation</title> 488!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation 489!Cnet/mac80211/agg-rx.c 490 </sect1> 491!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action 492 </chapter> 493 494 <chapter id="smps"> 495 <title>Spatial Multiplexing Powersave (SMPS)</title> 496!Pinclude/net/mac80211.h Spatial multiplexing power save 497!Finclude/net/mac80211.h ieee80211_request_smps 498!Finclude/net/mac80211.h ieee80211_smps_mode 499 </chapter> 500 </part> 501 502 <part id="rate-control"> 503 <title>Rate control interface</title> 504 <partintro> 505 <para>TBD</para> 506 <para> 507 This part of the book describes the rate control algorithm 508 interface and how it relates to mac80211 and drivers. 509 </para> 510 </partintro> 511 <chapter id="ratecontrol-api"> 512 <title>Rate Control API</title> 513 <para>TBD</para> 514!Finclude/net/mac80211.h ieee80211_start_tx_ba_session 515!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe 516!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session 517!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe 518!Finclude/net/mac80211.h ieee80211_rate_control_changed 519!Finclude/net/mac80211.h ieee80211_tx_rate_control 520!Finclude/net/mac80211.h rate_control_send_low 521 </chapter> 522 </part> 523 524 <part id="internal"> 525 <title>Internals</title> 526 <partintro> 527 <para>TBD</para> 528 <para> 529 This part of the book describes mac80211 internals. 530 </para> 531 </partintro> 532 533 <chapter id="key-handling"> 534 <title>Key handling</title> 535 <sect1> 536 <title>Key handling basics</title> 537!Pnet/mac80211/key.c Key handling basics 538 </sect1> 539 <sect1> 540 <title>MORE TBD</title> 541 <para>TBD</para> 542 </sect1> 543 </chapter> 544 545 <chapter id="rx-processing"> 546 <title>Receive processing</title> 547 <para>TBD</para> 548 </chapter> 549 550 <chapter id="tx-processing"> 551 <title>Transmit processing</title> 552 <para>TBD</para> 553 </chapter> 554 555 <chapter id="sta-info"> 556 <title>Station info handling</title> 557 <sect1> 558 <title>Programming information</title> 559!Fnet/mac80211/sta_info.h sta_info 560!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags 561 </sect1> 562 <sect1> 563 <title>STA information lifetime rules</title> 564!Pnet/mac80211/sta_info.c STA information lifetime rules 565 </sect1> 566 </chapter> 567 568 <chapter id="aggregation-internals"> 569 <title>Aggregation</title> 570!Fnet/mac80211/sta_info.h sta_ampdu_mlme 571!Fnet/mac80211/sta_info.h tid_ampdu_tx 572!Fnet/mac80211/sta_info.h tid_ampdu_rx 573 </chapter> 574 575 <chapter id="synchronisation"> 576 <title>Synchronisation</title> 577 <para>TBD</para> 578 <para>Locking, lots of RCU</para> 579 </chapter> 580 </part> 581 </book> 582</set> 583