diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 300e1707893f..9ebd1f00c6e7 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -11,7 +11,8 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ procfs-guide.xml writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml + genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ + mac80211.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/mac80211.tmpl b/Documentation/DocBook/mac80211.tmpl new file mode 100644 index 000000000000..b651e0a4b1c0 --- /dev/null +++ b/Documentation/DocBook/mac80211.tmpl @@ -0,0 +1,335 @@ + + + + + + The mac80211 subsystem for kernel developers + + + + Johannes + Berg + +
johannes@sipsolutions.net
+ + + + + + 2007 + 2008 + Johannes Berg + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + This documentation is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this documentation; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + +!Pinclude/net/mac80211.h Introduction +!Pinclude/net/mac80211.h Warning + + + + + + + + + The basic mac80211 driver interface + + + You should read and understand the information contained + within this part of the book while implementing a driver. + In some chapters, advanced usage is noted, that may be + skipped at first. + + + This part of the book only covers station and monitor mode + functionality, additional information required to implement + the other modes is covered in the second part of the book. + + + + + Basic hardware handling + TBD + + This chapter shall contain information on getting a hw + struct allocated and registered with mac80211. + + + Since it is required to allocate rates/modes before registering + a hw struct, this chapter shall also contain information on setting + up the rate/mode structs. + + + Additionally, some discussion about the callbacks and + the general programming model should be in here, including + the definition of ieee80211_ops which will be referred to + a lot. + + + Finally, a discussion of hardware capabilities should be done + with references to other parts of the book. + + +!Finclude/net/mac80211.h ieee80211_hw +!Finclude/net/mac80211.h ieee80211_hw_flags +!Finclude/net/mac80211.h SET_IEEE80211_DEV +!Finclude/net/mac80211.h SET_IEEE80211_PERM_ADDR +!Finclude/net/mac80211.h ieee80211_ops +!Finclude/net/mac80211.h ieee80211_alloc_hw +!Finclude/net/mac80211.h ieee80211_register_hw +!Finclude/net/mac80211.h ieee80211_get_tx_led_name +!Finclude/net/mac80211.h ieee80211_get_rx_led_name +!Finclude/net/mac80211.h ieee80211_get_assoc_led_name +!Finclude/net/mac80211.h ieee80211_get_radio_led_name +!Finclude/net/mac80211.h ieee80211_unregister_hw +!Finclude/net/mac80211.h ieee80211_free_hw + + + + PHY configuration + TBD + + This chapter should describe PHY handling including + start/stop callbacks and the various structures used. + +!Finclude/net/mac80211.h ieee80211_conf +!Finclude/net/mac80211.h ieee80211_conf_flags + + + + Virtual interfaces + TBD + + This chapter should describe virtual interface basics + that are relevant to the driver (VLANs, MGMT etc are not.) + It should explain the use of the add_iface/remove_iface + callbacks as well as the interface configuration callbacks. + + Things related to AP mode should be discussed there. + + Things related to supporting multiple interfaces should be + in the appropriate chapter, a BIG FAT note should be here about + this though and the recommendation to allow only a single + interface in STA mode at first! + +!Finclude/net/mac80211.h ieee80211_if_types +!Finclude/net/mac80211.h ieee80211_if_init_conf +!Finclude/net/mac80211.h ieee80211_if_conf + + + + Receive and transmit processing + + what should be here + TBD + + This should describe the receive and transmit + paths in mac80211/the drivers as well as + transmit status handling. + + + + Frame format +!Pinclude/net/mac80211.h Frame format + + + Alignment issues + TBD + + + Calling into mac80211 from interrupts +!Pinclude/net/mac80211.h Calling mac80211 from interrupts + + + functions/definitions +!Finclude/net/mac80211.h ieee80211_rx_status +!Finclude/net/mac80211.h mac80211_rx_flags +!Finclude/net/mac80211.h ieee80211_tx_control +!Finclude/net/mac80211.h ieee80211_tx_status_flags +!Finclude/net/mac80211.h ieee80211_rx +!Finclude/net/mac80211.h ieee80211_rx_irqsafe +!Finclude/net/mac80211.h ieee80211_tx_status +!Finclude/net/mac80211.h ieee80211_tx_status_irqsafe +!Finclude/net/mac80211.h ieee80211_rts_get +!Finclude/net/mac80211.h ieee80211_rts_duration +!Finclude/net/mac80211.h ieee80211_ctstoself_get +!Finclude/net/mac80211.h ieee80211_ctstoself_duration +!Finclude/net/mac80211.h ieee80211_generic_frame_duration +!Finclude/net/mac80211.h ieee80211_get_hdrlen_from_skb +!Finclude/net/mac80211.h ieee80211_get_hdrlen +!Finclude/net/mac80211.h ieee80211_wake_queue +!Finclude/net/mac80211.h ieee80211_stop_queue +!Finclude/net/mac80211.h ieee80211_start_queues +!Finclude/net/mac80211.h ieee80211_stop_queues +!Finclude/net/mac80211.h ieee80211_wake_queues + + + + + Frame filtering +!Pinclude/net/mac80211.h Frame filtering +!Finclude/net/mac80211.h ieee80211_filter_flags + + + + + Advanced driver interface + + + Information contained within this part of the book is + of interest only for advanced interaction of mac80211 + with drivers to exploit more hardware capabilities and + improve performance. + + + + + Hardware crypto acceleration +!Pinclude/net/mac80211.h Hardware crypto acceleration + +!Finclude/net/mac80211.h set_key_cmd +!Finclude/net/mac80211.h ieee80211_key_conf +!Finclude/net/mac80211.h ieee80211_key_alg +!Finclude/net/mac80211.h ieee80211_key_flags + + + + Multiple queues and QoS support + TBD +!Finclude/net/mac80211.h ieee80211_tx_queue_params +!Finclude/net/mac80211.h ieee80211_tx_queue_stats_data +!Finclude/net/mac80211.h ieee80211_tx_queue + + + + Access point mode support + TBD + Some parts of the if_conf should be discussed here instead + + Insert notes about VLAN interfaces with hw crypto here or + in the hw crypto chapter. + +!Finclude/net/mac80211.h ieee80211_get_buffered_bc +!Finclude/net/mac80211.h ieee80211_beacon_get + + + + Supporting multiple virtual interfaces + TBD + + Note: WDS with identical MAC address should almost always be OK + + + Insert notes about having multiple virtual interfaces with + different MAC addresses here, note which configurations are + supported by mac80211, add notes about supporting hw crypto + with it. + + + + + Hardware scan offload + TBD +!Finclude/net/mac80211.h ieee80211_scan_completed + + + + + Rate control interface + + TBD + + This part of the book describes the rate control algorithm + interface and how it relates to mac80211 and drivers. + + + + dummy chapter + TBD + + + + + Internals + + TBD + + This part of the book describes mac80211 internals. + + + + + Key handling + + Key handling basics +!Pnet/mac80211/key.c Key handling basics + + + MORE TBD + TBD + + + + + Receive processing + TBD + + + + Transmit processing + TBD + + + + Station info handling + + Programming information +!Fnet/mac80211/sta_info.h sta_info +!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags + + + STA information lifetime rules +!Pnet/mac80211/sta_info.c STA information lifetime rules + + + + + Synchronisation + TBD + Locking, lots of RCU + + + diff --git a/include/net/mac80211.h b/include/net/mac80211.h index 6aca472d7a02..d002b1c6e78e 100644 --- a/include/net/mac80211.h +++ b/include/net/mac80211.h @@ -407,7 +407,6 @@ enum ieee80211_conf_flags { * @channel: the channel to tune to */ struct ieee80211_conf { - unsigned int regulatory_domain; int radio_enabled; int beacon_int; @@ -437,6 +436,7 @@ struct ieee80211_conf { * @IEEE80211_IF_TYPE_WDS: interface in WDS mode. * @IEEE80211_IF_TYPE_VLAN: VLAN interface bound to an AP, drivers * will never see this type. + * @IEEE80211_IF_TYPE_MESH_POINT: 802.11s mesh point */ enum ieee80211_if_types { IEEE80211_IF_TYPE_INVALID, @@ -1096,8 +1096,9 @@ struct ieee80211_hw *ieee80211_alloc_hw(size_t priv_data_len, /** * ieee80211_register_hw - Register hardware device * - * You must call this function before any other functions - * except ieee80211_register_hwmode. + * You must call this function before any other functions in + * mac80211. Note that before a hardware can be registered, you + * need to fill the contained wiphy's information. * * @hw: the device to register as returned by ieee80211_alloc_hw() */ diff --git a/net/mac80211/key.c b/net/mac80211/key.c index df0c04cedbe4..166d0f00d135 100644 --- a/net/mac80211/key.c +++ b/net/mac80211/key.c @@ -20,8 +20,8 @@ #include "aes_ccm.h" -/* - * Key handling basics +/** + * DOC: Key handling basics * * Key handling in mac80211 is done based on per-interface (sub_if_data) * keys and per-station keys. Since each station belongs to an interface, diff --git a/net/mac80211/sta_info.c b/net/mac80211/sta_info.c index a767042ec4fd..42414b441592 100644 --- a/net/mac80211/sta_info.c +++ b/net/mac80211/sta_info.c @@ -31,10 +31,10 @@ * for faster lookup and a list for iteration. They are managed using * RCU, i.e. access to the list and hash table is protected by RCU. * - * Upon allocating a STA info structure with @sta_info_alloc() or + * Upon allocating a STA info structure with sta_info_alloc() or * mesh_plink_alloc(), the caller owns that structure. It must then either - * destroy it using @sta_info_destroy() (which is pretty useless) or insert - * it into the hash table using @sta_info_insert() which demotes the reference + * destroy it using sta_info_destroy() (which is pretty useless) or insert + * it into the hash table using sta_info_insert() which demotes the reference * from ownership to a regular RCU-protected reference; if the function * is called without protection by an RCU critical section the reference * is instantly invalidated. @@ -42,19 +42,19 @@ * Because there are debugfs entries for each station, and adding those * must be able to sleep, it is also possible to "pin" a station entry, * that means it can be removed from the hash table but not be freed. - * See the comment in @__sta_info_unlink() for more information. + * See the comment in __sta_info_unlink() for more information. * * In order to remove a STA info structure, the caller needs to first - * unlink it (@sta_info_unlink()) from the list and hash tables and + * unlink it (sta_info_unlink()) from the list and hash tables and * then wait for an RCU synchronisation before it can be freed. Due to * the pinning and the possibility of multiple callers trying to remove - * the same STA info at the same time, @sta_info_unlink() can clear the + * the same STA info at the same time, sta_info_unlink() can clear the * STA info pointer it is passed to indicate that the STA info is owned * by somebody else now. * - * If @sta_info_unlink() did not clear the pointer then the caller owns + * If sta_info_unlink() did not clear the pointer then the caller owns * the STA info structure now and is responsible of destroying it with - * a call to @sta_info_destroy(), not before RCU synchronisation, of + * a call to sta_info_destroy(), not before RCU synchronisation, of * course. Note that sta_info_destroy() must be protected by the RTNL. * * In all other cases, there is no concept of ownership on a STA entry,