diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/80211.tmpl | 584 | ||||
| -rw-r--r-- | Documentation/DocBook/Makefile | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/crypto-API.tmpl | 38 | ||||
| -rw-r--r-- | Documentation/DocBook/device-drivers.tmpl | 521 | ||||
| -rw-r--r-- | Documentation/DocBook/kernel-hacking.tmpl | 2 |
5 files changed, 37 insertions, 1120 deletions
diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl deleted file mode 100644 index 800fe7a9024c..000000000000 --- a/Documentation/DocBook/80211.tmpl +++ /dev/null @@ -1,584 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> -<set> - <setinfo> - <title>The 802.11 subsystems – for kernel developers</title> - <subtitle> - Explaining wireless 802.11 networking in the Linux kernel - </subtitle> - - <copyright> - <year>2007-2009</year> - <holder>Johannes Berg</holder> - </copyright> - - <authorgroup> - <author> - <firstname>Johannes</firstname> - <surname>Berg</surname> - <affiliation> - <address><email>johannes@sipsolutions.net</email></address> - </affiliation> - </author> - </authorgroup> - - <legalnotice> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - 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 - </para> - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - - <abstract> - <para> - These books attempt to give a description of the - various subsystems that play a role in 802.11 wireless - networking in Linux. Since these books are for kernel - developers they attempts to document the structures - and functions used in the kernel as well as giving a - higher-level overview. - </para> - <para> - The reader is expected to be familiar with the 802.11 - standard as published by the IEEE in 802.11-2007 (or - possibly later versions). References to this standard - will be given as "802.11-2007 8.1.5". - </para> - </abstract> - </setinfo> - <book id="cfg80211-developers-guide"> - <bookinfo> - <title>The cfg80211 subsystem</title> - - <abstract> -!Pinclude/net/cfg80211.h Introduction - </abstract> - </bookinfo> - <chapter> - <title>Device registration</title> -!Pinclude/net/cfg80211.h Device registration -!Finclude/net/cfg80211.h ieee80211_channel_flags -!Finclude/net/cfg80211.h ieee80211_channel -!Finclude/net/cfg80211.h ieee80211_rate_flags -!Finclude/net/cfg80211.h ieee80211_rate -!Finclude/net/cfg80211.h ieee80211_sta_ht_cap -!Finclude/net/cfg80211.h ieee80211_supported_band -!Finclude/net/cfg80211.h cfg80211_signal_type -!Finclude/net/cfg80211.h wiphy_params_flags -!Finclude/net/cfg80211.h wiphy_flags -!Finclude/net/cfg80211.h wiphy -!Finclude/net/cfg80211.h wireless_dev -!Finclude/net/cfg80211.h wiphy_new -!Finclude/net/cfg80211.h wiphy_register -!Finclude/net/cfg80211.h wiphy_unregister -!Finclude/net/cfg80211.h wiphy_free - -!Finclude/net/cfg80211.h wiphy_name -!Finclude/net/cfg80211.h wiphy_dev -!Finclude/net/cfg80211.h wiphy_priv -!Finclude/net/cfg80211.h priv_to_wiphy -!Finclude/net/cfg80211.h set_wiphy_dev -!Finclude/net/cfg80211.h wdev_priv -!Finclude/net/cfg80211.h ieee80211_iface_limit -!Finclude/net/cfg80211.h ieee80211_iface_combination -!Finclude/net/cfg80211.h cfg80211_check_combinations - </chapter> - <chapter> - <title>Actions and configuration</title> -!Pinclude/net/cfg80211.h Actions and configuration -!Finclude/net/cfg80211.h cfg80211_ops -!Finclude/net/cfg80211.h vif_params -!Finclude/net/cfg80211.h key_params -!Finclude/net/cfg80211.h survey_info_flags -!Finclude/net/cfg80211.h survey_info -!Finclude/net/cfg80211.h cfg80211_beacon_data -!Finclude/net/cfg80211.h cfg80211_ap_settings -!Finclude/net/cfg80211.h station_parameters -!Finclude/net/cfg80211.h rate_info_flags -!Finclude/net/cfg80211.h rate_info -!Finclude/net/cfg80211.h station_info -!Finclude/net/cfg80211.h monitor_flags -!Finclude/net/cfg80211.h mpath_info_flags -!Finclude/net/cfg80211.h mpath_info -!Finclude/net/cfg80211.h bss_parameters -!Finclude/net/cfg80211.h ieee80211_txq_params -!Finclude/net/cfg80211.h cfg80211_crypto_settings -!Finclude/net/cfg80211.h cfg80211_auth_request -!Finclude/net/cfg80211.h cfg80211_assoc_request -!Finclude/net/cfg80211.h cfg80211_deauth_request -!Finclude/net/cfg80211.h cfg80211_disassoc_request -!Finclude/net/cfg80211.h cfg80211_ibss_params -!Finclude/net/cfg80211.h cfg80211_connect_params -!Finclude/net/cfg80211.h cfg80211_pmksa -!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt -!Finclude/net/cfg80211.h cfg80211_auth_timeout -!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp -!Finclude/net/cfg80211.h cfg80211_assoc_timeout -!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt -!Finclude/net/cfg80211.h cfg80211_ibss_joined -!Finclude/net/cfg80211.h cfg80211_connect_result -!Finclude/net/cfg80211.h cfg80211_connect_bss -!Finclude/net/cfg80211.h cfg80211_connect_timeout -!Finclude/net/cfg80211.h cfg80211_roamed -!Finclude/net/cfg80211.h cfg80211_disconnected -!Finclude/net/cfg80211.h cfg80211_ready_on_channel -!Finclude/net/cfg80211.h cfg80211_remain_on_channel_expired -!Finclude/net/cfg80211.h cfg80211_new_sta -!Finclude/net/cfg80211.h cfg80211_rx_mgmt -!Finclude/net/cfg80211.h cfg80211_mgmt_tx_status -!Finclude/net/cfg80211.h cfg80211_cqm_rssi_notify -!Finclude/net/cfg80211.h cfg80211_cqm_pktloss_notify -!Finclude/net/cfg80211.h cfg80211_michael_mic_failure - </chapter> - <chapter> - <title>Scanning and BSS list handling</title> -!Pinclude/net/cfg80211.h Scanning and BSS list handling -!Finclude/net/cfg80211.h cfg80211_ssid -!Finclude/net/cfg80211.h cfg80211_scan_request -!Finclude/net/cfg80211.h cfg80211_scan_done -!Finclude/net/cfg80211.h cfg80211_bss -!Finclude/net/cfg80211.h cfg80211_inform_bss -!Finclude/net/cfg80211.h cfg80211_inform_bss_frame_data -!Finclude/net/cfg80211.h cfg80211_inform_bss_data -!Finclude/net/cfg80211.h cfg80211_unlink_bss -!Finclude/net/cfg80211.h cfg80211_find_ie -!Finclude/net/cfg80211.h ieee80211_bss_get_ie - </chapter> - <chapter> - <title>Utility functions</title> -!Pinclude/net/cfg80211.h Utility functions -!Finclude/net/cfg80211.h ieee80211_channel_to_frequency -!Finclude/net/cfg80211.h ieee80211_frequency_to_channel -!Finclude/net/cfg80211.h ieee80211_get_channel -!Finclude/net/cfg80211.h ieee80211_get_response_rate -!Finclude/net/cfg80211.h ieee80211_hdrlen -!Finclude/net/cfg80211.h ieee80211_get_hdrlen_from_skb -!Finclude/net/cfg80211.h ieee80211_radiotap_iterator - </chapter> - <chapter> - <title>Data path helpers</title> -!Pinclude/net/cfg80211.h Data path helpers -!Finclude/net/cfg80211.h ieee80211_data_to_8023 -!Finclude/net/cfg80211.h ieee80211_data_from_8023 -!Finclude/net/cfg80211.h ieee80211_amsdu_to_8023s -!Finclude/net/cfg80211.h cfg80211_classify8021d - </chapter> - <chapter> - <title>Regulatory enforcement infrastructure</title> -!Pinclude/net/cfg80211.h Regulatory enforcement infrastructure -!Finclude/net/cfg80211.h regulatory_hint -!Finclude/net/cfg80211.h wiphy_apply_custom_regulatory -!Finclude/net/cfg80211.h freq_reg_info - </chapter> - <chapter> - <title>RFkill integration</title> -!Pinclude/net/cfg80211.h RFkill integration -!Finclude/net/cfg80211.h wiphy_rfkill_set_hw_state -!Finclude/net/cfg80211.h wiphy_rfkill_start_polling -!Finclude/net/cfg80211.h wiphy_rfkill_stop_polling - </chapter> - <chapter> - <title>Test mode</title> -!Pinclude/net/cfg80211.h Test mode -!Finclude/net/cfg80211.h cfg80211_testmode_alloc_reply_skb -!Finclude/net/cfg80211.h cfg80211_testmode_reply -!Finclude/net/cfg80211.h cfg80211_testmode_alloc_event_skb -!Finclude/net/cfg80211.h cfg80211_testmode_event - </chapter> - </book> - <book id="mac80211-developers-guide"> - <bookinfo> - <title>The mac80211 subsystem</title> - <abstract> -!Pinclude/net/mac80211.h Introduction -!Pinclude/net/mac80211.h Warning - </abstract> - </bookinfo> - - <toc></toc> - - <!-- - Generally, this document shall be ordered by increasing complexity. - It is important to note that readers should be able to read only - the first few sections to get a working driver and only advanced - usage should require reading the full document. - --> - - <part> - <title>The basic mac80211 driver interface</title> - <partintro> - <para> - 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. - </para> - <para> - 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. - </para> - </partintro> - - <chapter id="basics"> - <title>Basic hardware handling</title> - <para>TBD</para> - <para> - This chapter shall contain information on getting a hw - struct allocated and registered with mac80211. - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - Finally, a discussion of hardware capabilities should be done - with references to other parts of the book. - </para> - <!-- intentionally multiple !F lines to get proper order --> -!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_unregister_hw -!Finclude/net/mac80211.h ieee80211_free_hw - </chapter> - - <chapter id="phy-handling"> - <title>PHY configuration</title> - <para>TBD</para> - <para> - This chapter should describe PHY handling including - start/stop callbacks and the various structures used. - </para> -!Finclude/net/mac80211.h ieee80211_conf -!Finclude/net/mac80211.h ieee80211_conf_flags - </chapter> - - <chapter id="iface-handling"> - <title>Virtual interfaces</title> - <para>TBD</para> - <para> - 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. - </para> - <para>Things related to AP mode should be discussed there.</para> - <para> - 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! - </para> -!Finclude/net/mac80211.h ieee80211_vif - </chapter> - - <chapter id="rx-tx"> - <title>Receive and transmit processing</title> - <sect1> - <title>what should be here</title> - <para>TBD</para> - <para> - This should describe the receive and transmit - paths in mac80211/the drivers as well as - transmit status handling. - </para> - </sect1> - <sect1> - <title>Frame format</title> -!Pinclude/net/mac80211.h Frame format - </sect1> - <sect1> - <title>Packet alignment</title> -!Pnet/mac80211/rx.c Packet alignment - </sect1> - <sect1> - <title>Calling into mac80211 from interrupts</title> -!Pinclude/net/mac80211.h Calling mac80211 from interrupts - </sect1> - <sect1> - <title>functions/definitions</title> -!Finclude/net/mac80211.h ieee80211_rx_status -!Finclude/net/mac80211.h mac80211_rx_flags -!Finclude/net/mac80211.h mac80211_tx_info_flags -!Finclude/net/mac80211.h mac80211_tx_control_flags -!Finclude/net/mac80211.h mac80211_rate_control_flags -!Finclude/net/mac80211.h ieee80211_tx_rate -!Finclude/net/mac80211.h ieee80211_tx_info -!Finclude/net/mac80211.h ieee80211_tx_info_clear_status -!Finclude/net/mac80211.h ieee80211_rx -!Finclude/net/mac80211.h ieee80211_rx_ni -!Finclude/net/mac80211.h ieee80211_rx_irqsafe -!Finclude/net/mac80211.h ieee80211_tx_status -!Finclude/net/mac80211.h ieee80211_tx_status_ni -!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_wake_queue -!Finclude/net/mac80211.h ieee80211_stop_queue -!Finclude/net/mac80211.h ieee80211_wake_queues -!Finclude/net/mac80211.h ieee80211_stop_queues -!Finclude/net/mac80211.h ieee80211_queue_stopped - </sect1> - </chapter> - - <chapter id="filters"> - <title>Frame filtering</title> -!Pinclude/net/mac80211.h Frame filtering -!Finclude/net/mac80211.h ieee80211_filter_flags - </chapter> - - <chapter id="workqueue"> - <title>The mac80211 workqueue</title> -!Pinclude/net/mac80211.h mac80211 workqueue -!Finclude/net/mac80211.h ieee80211_queue_work -!Finclude/net/mac80211.h ieee80211_queue_delayed_work - </chapter> - </part> - - <part id="advanced"> - <title>Advanced driver interface</title> - <partintro> - <para> - 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. - </para> - </partintro> - - <chapter id="led-support"> - <title>LED support</title> - <para> - Mac80211 supports various ways of blinking LEDs. Wherever possible, - device LEDs should be exposed as LED class devices and hooked up to - the appropriate trigger, which will then be triggered appropriately - by mac80211. - </para> -!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_tpt_blink -!Finclude/net/mac80211.h ieee80211_tpt_led_trigger_flags -!Finclude/net/mac80211.h ieee80211_create_tpt_led_trigger - </chapter> - - <chapter id="hardware-crypto-offload"> - <title>Hardware crypto acceleration</title> -!Pinclude/net/mac80211.h Hardware crypto acceleration - <!-- intentionally multiple !F lines to get proper order --> -!Finclude/net/mac80211.h set_key_cmd -!Finclude/net/mac80211.h ieee80211_key_conf -!Finclude/net/mac80211.h ieee80211_key_flags -!Finclude/net/mac80211.h ieee80211_get_tkip_p1k -!Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv -!Finclude/net/mac80211.h ieee80211_get_tkip_p2k - </chapter> - - <chapter id="powersave"> - <title>Powersave support</title> -!Pinclude/net/mac80211.h Powersave support - </chapter> - - <chapter id="beacon-filter"> - <title>Beacon filter support</title> -!Pinclude/net/mac80211.h Beacon filter support -!Finclude/net/mac80211.h ieee80211_beacon_loss - </chapter> - - <chapter id="qos"> - <title>Multiple queues and QoS support</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_tx_queue_params - </chapter> - - <chapter id="AP"> - <title>Access point mode support</title> - <para>TBD</para> - <para>Some parts of the if_conf should be discussed here instead</para> - <para> - Insert notes about VLAN interfaces with hw crypto here or - in the hw crypto chapter. - </para> - <section id="ps-client"> - <title>support for powersaving clients</title> -!Pinclude/net/mac80211.h AP support for powersaving clients -!Finclude/net/mac80211.h ieee80211_get_buffered_bc -!Finclude/net/mac80211.h ieee80211_beacon_get -!Finclude/net/mac80211.h ieee80211_sta_eosp -!Finclude/net/mac80211.h ieee80211_frame_release_type -!Finclude/net/mac80211.h ieee80211_sta_ps_transition -!Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni -!Finclude/net/mac80211.h ieee80211_sta_set_buffered -!Finclude/net/mac80211.h ieee80211_sta_block_awake - </section> - </chapter> - - <chapter id="multi-iface"> - <title>Supporting multiple virtual interfaces</title> - <para>TBD</para> - <para> - Note: WDS with identical MAC address should almost always be OK - </para> - <para> - 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. - </para> -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic - </chapter> - - <chapter id="station-handling"> - <title>Station handling</title> - <para>TODO</para> -!Finclude/net/mac80211.h ieee80211_sta -!Finclude/net/mac80211.h sta_notify_cmd -!Finclude/net/mac80211.h ieee80211_find_sta -!Finclude/net/mac80211.h ieee80211_find_sta_by_ifaddr - </chapter> - - <chapter id="hardware-scan-offload"> - <title>Hardware scan offload</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_scan_completed - </chapter> - - <chapter id="aggregation"> - <title>Aggregation</title> - <sect1> - <title>TX A-MPDU aggregation</title> -!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation -!Cnet/mac80211/agg-tx.c - </sect1> - <sect1> - <title>RX A-MPDU aggregation</title> -!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation -!Cnet/mac80211/agg-rx.c -!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action - </sect1> - </chapter> - - <chapter id="smps"> - <title>Spatial Multiplexing Powersave (SMPS)</title> -!Pinclude/net/mac80211.h Spatial multiplexing power save -!Finclude/net/mac80211.h ieee80211_request_smps -!Finclude/net/mac80211.h ieee80211_smps_mode - </chapter> - </part> - - <part id="rate-control"> - <title>Rate control interface</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes the rate control algorithm - interface and how it relates to mac80211 and drivers. - </para> - </partintro> - <chapter id="ratecontrol-api"> - <title>Rate Control API</title> - <para>TBD</para> -!Finclude/net/mac80211.h ieee80211_start_tx_ba_session -!Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe -!Finclude/net/mac80211.h ieee80211_stop_tx_ba_session -!Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe -!Finclude/net/mac80211.h ieee80211_rate_control_changed -!Finclude/net/mac80211.h ieee80211_tx_rate_control -!Finclude/net/mac80211.h rate_control_send_low - </chapter> - </part> - - <part id="internal"> - <title>Internals</title> - <partintro> - <para>TBD</para> - <para> - This part of the book describes mac80211 internals. - </para> - </partintro> - - <chapter id="key-handling"> - <title>Key handling</title> - <sect1> - <title>Key handling basics</title> -!Pnet/mac80211/key.c Key handling basics - </sect1> - <sect1> - <title>MORE TBD</title> - <para>TBD</para> - </sect1> - </chapter> - - <chapter id="rx-processing"> - <title>Receive processing</title> - <para>TBD</para> - </chapter> - - <chapter id="tx-processing"> - <title>Transmit processing</title> - <para>TBD</para> - </chapter> - - <chapter id="sta-info"> - <title>Station info handling</title> - <sect1> - <title>Programming information</title> -!Fnet/mac80211/sta_info.h sta_info -!Fnet/mac80211/sta_info.h ieee80211_sta_info_flags - </sect1> - <sect1> - <title>STA information lifetime rules</title> -!Pnet/mac80211/sta_info.c STA information lifetime rules - </sect1> - </chapter> - - <chapter id="aggregation-internals"> - <title>Aggregation</title> -!Fnet/mac80211/sta_info.h sta_ampdu_mlme -!Fnet/mac80211/sta_info.h tid_ampdu_tx -!Fnet/mac80211/sta_info.h tid_ampdu_rx - </chapter> - - <chapter id="synchronisation"> - <title>Synchronisation</title> - <para>TBD</para> - <para>Locking, lots of RCU</para> - </chapter> - </part> - </book> -</set> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 64460a897f56..fdf8232d0eeb 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,13 +6,13 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := z8530book.xml device-drivers.xml \ +DOCBOOKS := z8530book.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - 80211.xml debugobjects.xml sh.xml regulator.xml \ + debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ tracepoint.xml w1.xml \ writing_musb_glue_layer.xml crypto-API.xml iio.xml @@ -22,9 +22,15 @@ ifeq ($(DOCBOOKS),) # Skip DocBook build if the user explicitly requested no DOCBOOKS. .DEFAULT: @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." +else +ifneq ($(SPHINXDIRS),) +# Skip DocBook build if the user explicitly requested a sphinx dir +.DEFAULT: + @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." else + ### # The build process is as follows (targets): # (xmldocs) [by docproc] @@ -66,6 +72,7 @@ installmandocs: mandocs # no-op for the DocBook toolchain epubdocs: +latexdocs: ### #External programs used @@ -221,6 +228,7 @@ silent_gen_xml = : echo "</programlisting>") > $@ endif # DOCBOOKS="" +endif # SPHINDIR=... ### # Help targets as used by the top-level makefile diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl index fb2a1526f6ec..088b79c341ff 100644 --- a/Documentation/DocBook/crypto-API.tmpl +++ b/Documentation/DocBook/crypto-API.tmpl @@ -797,7 +797,8 @@ kernel crypto API | Caller include/linux/crypto.h and their definition can be seen below. The former function registers a single transformation, while the latter works on an array of transformation descriptions. - The latter is useful when registering transformations in bulk. + The latter is useful when registering transformations in bulk, + for example when a driver implements multiple transformations. </para> <programlisting> @@ -822,18 +823,31 @@ kernel crypto API | Caller </para> <para> - The bulk registration / unregistration functions require - that struct crypto_alg is an array of count size. These - functions simply loop over that array and register / - unregister each individual algorithm. If an error occurs, - the loop is terminated at the offending algorithm definition. - That means, the algorithms prior to the offending algorithm - are successfully registered. Note, the caller has no way of - knowing which cipher implementations have successfully - registered. If this is important to know, the caller should - loop through the different implementations using the single - instance *_alg functions for each individual implementation. + The bulk registration/unregistration functions + register/unregister each transformation in the given array of + length count. They handle errors as follows: </para> + <itemizedlist> + <listitem> + <para> + crypto_register_algs() succeeds if and only if it + successfully registers all the given transformations. If an + error occurs partway through, then it rolls back successful + registrations before returning the error code. Note that if + a driver needs to handle registration errors for individual + transformations, then it will need to use the non-bulk + function crypto_register_alg() instead. + </para> + </listitem> + <listitem> + <para> + crypto_unregister_algs() tries to unregister all the given + transformations, continuing on error. It logs errors and + always returns zero. + </para> + </listitem> + </itemizedlist> + </sect1> <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl deleted file mode 100644 index 9c10030eb2be..000000000000 --- a/Documentation/DocBook/device-drivers.tmpl +++ /dev/null @@ -1,521 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="LinuxDriversAPI"> - <bookinfo> - <title>Linux Device Drivers</title> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program 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. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="Basics"> - <title>Driver Basics</title> - <sect1><title>Driver Entry and Exit points</title> -!Iinclude/linux/init.h - </sect1> - - <sect1><title>Atomic and pointer manipulation</title> -!Iarch/x86/include/asm/atomic.h - </sect1> - - <sect1><title>Delaying, scheduling, and timer routines</title> -!Iinclude/linux/sched.h -!Ekernel/sched/core.c -!Ikernel/sched/cpupri.c -!Ikernel/sched/fair.c -!Iinclude/linux/completion.h -!Ekernel/time/timer.c - </sect1> - <sect1><title>Wait queues and Wake events</title> -!Iinclude/linux/wait.h -!Ekernel/sched/wait.c - </sect1> - <sect1><title>High-resolution timers</title> -!Iinclude/linux/ktime.h -!Iinclude/linux/hrtimer.h -!Ekernel/time/hrtimer.c - </sect1> - <sect1><title>Workqueues and Kevents</title> -!Iinclude/linux/workqueue.h -!Ekernel/workqueue.c - </sect1> - <sect1><title>Internal Functions</title> -!Ikernel/exit.c -!Ikernel/signal.c -!Iinclude/linux/kthread.h -!Ekernel/kthread.c - </sect1> - - <sect1><title>Kernel objects manipulation</title> -<!-- -X!Iinclude/linux/kobject.h ---> -!Elib/kobject.c - </sect1> - - <sect1><title>Kernel utility functions</title> -!Iinclude/linux/kernel.h -!Ekernel/printk/printk.c -!Ekernel/panic.c -!Ekernel/sys.c -!Ekernel/rcu/srcu.c -!Ekernel/rcu/tree.c -!Ekernel/rcu/tree_plugin.h -!Ekernel/rcu/update.c - </sect1> - - <sect1><title>Device Resource Management</title> -!Edrivers/base/devres.c - </sect1> - - </chapter> - - <chapter id="devdrivers"> - <title>Device drivers infrastructure</title> - <sect1><title>The Basic Device Driver-Model Structures </title> -!Iinclude/linux/device.h - </sect1> - <sect1><title>Device Drivers Base</title> -!Idrivers/base/init.c -!Edrivers/base/driver.c -!Edrivers/base/core.c -!Edrivers/base/syscore.c -!Edrivers/base/class.c -!Idrivers/base/node.c -!Edrivers/base/firmware_class.c -!Edrivers/base/transport_class.c -<!-- Cannot be included, because - attribute_container_add_class_device_adapter - and attribute_container_classdev_to_container - exceed allowed 44 characters maximum -X!Edrivers/base/attribute_container.c ---> -!Edrivers/base/dd.c -<!-- -X!Edrivers/base/interface.c ---> -!Iinclude/linux/platform_device.h -!Edrivers/base/platform.c -!Edrivers/base/bus.c - </sect1> - <sect1> - <title>Buffer Sharing and Synchronization</title> - <para> - The dma-buf subsystem provides the framework for sharing buffers - for hardware (DMA) access across multiple device drivers and - subsystems, and for synchronizing asynchronous hardware access. - </para> - <para> - This is used, for example, by drm "prime" multi-GPU support, but - is of course not limited to GPU use cases. - </para> - <para> - The three main components of this are: (1) dma-buf, representing - a sg_table and exposed to userspace as a file descriptor to allow - passing between devices, (2) fence, which provides a mechanism - to signal when one device as finished access, and (3) reservation, - which manages the shared or exclusive fence(s) associated with - the buffer. - </para> - <sect2><title>dma-buf</title> -!Edrivers/dma-buf/dma-buf.c -!Iinclude/linux/dma-buf.h - </sect2> - <sect2><title>reservation</title> -!Pdrivers/dma-buf/reservation.c Reservation Object Overview -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h - </sect2> - <sect2><title>fence</title> -!Edrivers/dma-buf/fence.c -!Iinclude/linux/fence.h -!Edrivers/dma-buf/seqno-fence.c -!Iinclude/linux/seqno-fence.h -!Edrivers/dma-buf/fence-array.c -!Iinclude/linux/fence-array.h -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h -!Edrivers/dma-buf/sync_file.c -!Iinclude/linux/sync_file.h - </sect2> - </sect1> - <sect1><title>Device Drivers DMA Management</title> -!Edrivers/base/dma-coherent.c -!Edrivers/base/dma-mapping.c - </sect1> - <sect1><title>Device Drivers Power Management</title> -!Edrivers/base/power/main.c - </sect1> - <sect1><title>Device Drivers ACPI Support</title> -<!-- Internal functions only -X!Edrivers/acpi/sleep/main.c -X!Edrivers/acpi/sleep/wakeup.c -X!Edrivers/acpi/motherboard.c -X!Edrivers/acpi/bus.c ---> -!Edrivers/acpi/scan.c -!Idrivers/acpi/scan.c -<!-- No correct structured comments -X!Edrivers/acpi/pci_bind.c ---> - </sect1> - <sect1><title>Device drivers PnP support</title> -!Idrivers/pnp/core.c -<!-- No correct structured comments -X!Edrivers/pnp/system.c - --> -!Edrivers/pnp/card.c -!Idrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - </sect1> - <sect1><title>Userspace IO devices</title> -!Edrivers/uio/uio.c -!Iinclude/linux/uio_driver.h - </sect1> - </chapter> - - <chapter id="parportdev"> - <title>Parallel Port Devices</title> -!Iinclude/linux/parport.h -!Edrivers/parport/ieee1284.c -!Edrivers/parport/share.c -!Idrivers/parport/daisy.c - </chapter> - - <chapter id="message_devices"> - <title>Message-based devices</title> - <sect1><title>Fusion message devices</title> -!Edrivers/message/fusion/mptbase.c -!Idrivers/message/fusion/mptbase.c -!Edrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptscsih.c -!Idrivers/message/fusion/mptctl.c -!Idrivers/message/fusion/mptspi.c -!Idrivers/message/fusion/mptfc.c -!Idrivers/message/fusion/mptlan.c - </sect1> - </chapter> - - <chapter id="snddev"> - <title>Sound Devices</title> -!Iinclude/sound/core.h -!Esound/sound_core.c -!Iinclude/sound/pcm.h -!Esound/core/pcm.c -!Esound/core/device.c -!Esound/core/info.c -!Esound/core/rawmidi.c -!Esound/core/sound.c -!Esound/core/memory.c -!Esound/core/pcm_memory.c -!Esound/core/init.c -!Esound/core/isadma.c -!Esound/core/control.c -!Esound/core/pcm_lib.c -!Esound/core/hwdep.c -!Esound/core/pcm_native.c -!Esound/core/memalloc.c -<!-- FIXME: Removed for now since no structured comments in source -X!Isound/sound_firmware.c ---> - </chapter> - - - <chapter id="uart16x50"> - <title>16x50 UART Driver</title> -!Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250/8250_core.c - </chapter> - - <chapter id="fbdev"> - <title>Frame Buffer Library</title> - - <para> - The frame buffer drivers depend heavily on four data structures. - These structures are declared in include/linux/fb.h. They are - fb_info, fb_var_screeninfo, fb_fix_screeninfo and fb_monospecs. - The last three can be made available to and from userland. - </para> - - <para> - fb_info defines the current state of a particular video card. - Inside fb_info, there exists a fb_ops structure which is a - collection of needed functions to make fbdev and fbcon work. - fb_info is only visible to the kernel. - </para> - - <para> - fb_var_screeninfo is used to describe the features of a video card - that are user defined. With fb_var_screeninfo, things such as - depth and the resolution may be defined. - </para> - - <para> - The next structure is fb_fix_screeninfo. This defines the - properties of a card that are created when a mode is set and can't - be changed otherwise. A good example of this is the start of the - frame buffer memory. This "locks" the address of the frame buffer - memory, so that it cannot be changed or moved. - </para> - - <para> - The last structure is fb_monospecs. In the old API, there was - little importance for fb_monospecs. This allowed for forbidden things - such as setting a mode of 800x600 on a fix frequency monitor. With - the new API, fb_monospecs prevents such things, and if used - correctly, can prevent a monitor from being cooked. fb_monospecs - will not be useful until kernels 2.5.x. - </para> - - <sect1><title>Frame Buffer Memory</title> -!Edrivers/video/fbdev/core/fbmem.c - </sect1> -<!-- - <sect1><title>Frame Buffer Console</title> -X!Edrivers/video/console/fbcon.c - </sect1> ---> - <sect1><title>Frame Buffer Colormap</title> -!Edrivers/video/fbdev/core/fbcmap.c - </sect1> -<!-- FIXME: - drivers/video/fbgen.c has no docs, which stuffs up the sgml. Comment - out until somebody adds docs. KAO - <sect1><title>Frame Buffer Generic Functions</title> -X!Idrivers/video/fbgen.c - </sect1> -KAO --> - <sect1><title>Frame Buffer Video Mode Database</title> -!Idrivers/video/fbdev/core/modedb.c -!Edrivers/video/fbdev/core/modedb.c - </sect1> - <sect1><title>Frame Buffer Macintosh Video Mode Database</title> -!Edrivers/video/fbdev/macmodes.c - </sect1> - <sect1><title>Frame Buffer Fonts</title> - <para> - Refer to the file lib/fonts/fonts.c for more information. - </para> -<!-- FIXME: Removed for now since no structured comments in source -X!Ilib/fonts/fonts.c ---> - </sect1> - </chapter> - - <chapter id="input_subsystem"> - <title>Input Subsystem</title> - <sect1><title>Input core</title> -!Iinclude/linux/input.h -!Edrivers/input/input.c -!Edrivers/input/ff-core.c -!Edrivers/input/ff-memless.c - </sect1> - <sect1><title>Multitouch Library</title> -!Iinclude/linux/input/mt.h -!Edrivers/input/input-mt.c - </sect1> - <sect1><title>Polled input devices</title> -!Iinclude/linux/input-polldev.h -!Edrivers/input/input-polldev.c - </sect1> - <sect1><title>Matrix keyboards/keypads</title> -!Iinclude/linux/input/matrix_keypad.h - </sect1> - <sect1><title>Sparse keymap support</title> -!Iinclude/linux/input/sparse-keymap.h -!Edrivers/input/sparse-keymap.c - </sect1> - </chapter> - - <chapter id="spi"> - <title>Serial Peripheral Interface (SPI)</title> - <para> - SPI is the "Serial Peripheral Interface", widely used with - embedded systems because it is a simple and efficient - interface: basically a multiplexed shift register. - Its three signal wires hold a clock (SCK, often in the range - of 1-20 MHz), a "Master Out, Slave In" (MOSI) data line, and - a "Master In, Slave Out" (MISO) data line. - SPI is a full duplex protocol; for each bit shifted out the - MOSI line (one per clock) another is shifted in on the MISO line. - Those bits are assembled into words of various sizes on the - way to and from system memory. - An additional chipselect line is usually active-low (nCS); - four signals are normally used for each peripheral, plus - sometimes an interrupt. - </para> - <para> - The SPI bus facilities listed here provide a generalized - interface to declare SPI busses and devices, manage them - according to the standard Linux driver model, and perform - input/output operations. - At this time, only "master" side interfaces are supported, - where Linux talks to SPI peripherals and does not implement - such a peripheral itself. - (Interfaces to support implementing SPI slaves would - necessarily look different.) - </para> - <para> - The programming interface is structured around two kinds of driver, - and two kinds of device. - A "Controller Driver" abstracts the controller hardware, which may - be as simple as a set of GPIO pins or as complex as a pair of FIFOs - connected to dual DMA engines on the other side of the SPI shift - register (maximizing throughput). Such drivers bridge between - whatever bus they sit on (often the platform bus) and SPI, and - expose the SPI side of their device as a - <structname>struct spi_master</structname>. - SPI devices are children of that master, represented as a - <structname>struct spi_device</structname> and manufactured from - <structname>struct spi_board_info</structname> descriptors which - are usually provided by board-specific initialization code. - A <structname>struct spi_driver</structname> is called a - "Protocol Driver", and is bound to a spi_device using normal - driver model calls. - </para> - <para> - The I/O model is a set of queued messages. Protocol drivers - submit one or more <structname>struct spi_message</structname> - objects, which are processed and completed asynchronously. - (There are synchronous wrappers, however.) Messages are - built from one or more <structname>struct spi_transfer</structname> - objects, each of which wraps a full duplex SPI transfer. - A variety of protocol tweaking options are needed, because - different chips adopt very different policies for how they - use the bits transferred with SPI. - </para> -!Iinclude/linux/spi/spi.h -!Fdrivers/spi/spi.c spi_register_board_info -!Edrivers/spi/spi.c - </chapter> - - <chapter id="i2c"> - <title>I<superscript>2</superscript>C and SMBus Subsystem</title> - - <para> - I<superscript>2</superscript>C (or without fancy typography, "I2C") - is an acronym for the "Inter-IC" bus, a simple bus protocol which is - widely used where low data rate communications suffice. - Since it's also a licensed trademark, some vendors use another - name (such as "Two-Wire Interface", TWI) for the same bus. - I2C only needs two signals (SCL for clock, SDA for data), conserving - board real estate and minimizing signal quality issues. - Most I2C devices use seven bit addresses, and bus speeds of up - to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet - found wide use. - I2C is a multi-master bus; open drain signaling is used to - arbitrate between masters, as well as to handshake and to - synchronize clocks from slower clients. - </para> - - <para> - The Linux I2C programming interfaces support only the master - side of bus interactions, not the slave side. - The programming interface is structured around two kinds of driver, - and two kinds of device. - An I2C "Adapter Driver" abstracts the controller hardware; it binds - to a physical device (perhaps a PCI device or platform_device) and - exposes a <structname>struct i2c_adapter</structname> representing - each I2C bus segment it manages. - On each I2C bus segment will be I2C devices represented by a - <structname>struct i2c_client</structname>. Those devices will - be bound to a <structname>struct i2c_driver</structname>, - which should follow the standard Linux driver model. - (At this writing, a legacy model is more widely used.) - There are functions to perform various I2C protocol operations; at - this writing all such functions are usable only from task context. - </para> - - <para> - The System Management Bus (SMBus) is a sibling protocol. Most SMBus - systems are also I2C conformant. The electrical constraints are - tighter for SMBus, and it standardizes particular protocol messages - and idioms. Controllers that support I2C can also support most - SMBus operations, but SMBus controllers don't support all the protocol - options that an I2C controller will. - There are functions to perform various SMBus protocol operations, - either using I2C primitives or by issuing SMBus commands to - i2c_adapter devices which don't support those I2C operations. - </para> - -!Iinclude/linux/i2c.h -!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info -!Edrivers/i2c/i2c-core.c - </chapter> - - <chapter id="hsi"> - <title>High Speed Synchronous Serial Interface (HSI)</title> - - <para> - High Speed Synchronous Serial Interface (HSI) is a - serial interface mainly used for connecting application - engines (APE) with cellular modem engines (CMT) in cellular - handsets. - - HSI provides multiplexing for up to 16 logical channels, - low-latency and full duplex communication. - </para> - -!Iinclude/linux/hsi/hsi.h -!Edrivers/hsi/hsi_core.c - </chapter> - - <chapter id="pwm"> - <title>Pulse-Width Modulation (PWM)</title> - <para> - Pulse-width modulation is a modulation technique primarily used to - control power supplied to electrical devices. - </para> - <para> - The PWM framework provides an abstraction for providers and consumers - of PWM signals. A controller that provides one or more PWM signals is - registered as <structname>struct pwm_chip</structname>. Providers are - expected to embed this structure in a driver-specific structure. This - structure contains fields that describe a particular chip. - </para> - <para> - A chip exposes one or more PWM signal sources, each of which exposed - as a <structname>struct pwm_device</structname>. Operations can be - performed on PWM devices to control the period, duty cycle, polarity - and active state of the signal. - </para> - <para> - Note that PWM devices are exclusive resources: they can always only be - used by one consumer at a time. - </para> -!Iinclude/linux/pwm.h -!Edrivers/pwm/core.c - </chapter> - -</book> diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index 589b40cc5eb5..2a272275c81b 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -483,7 +483,7 @@ printk(KERN_INFO "my ip: %pI4\n", &ipaddress); <function>get_user()</function> / <function>put_user()</function> - <filename class="headerfile">include/asm/uaccess.h</filename> + <filename class="headerfile">include/linux/uaccess.h</filename> </title> <para> |
