From: Rafael J. Wysocki Date: Thu, 20 Oct 2016 21:24:58 +0000 (+0200) Subject: Merge branch 'pm-cpufreq' X-Git-Tag: v4.9-rc2~19^2 X-Git-Url: http://git.cascardo.info/?p=cascardo%2Flinux.git;a=commitdiff_plain;h=350d32395bee1a21deec504a253b336e20d9f35a;hp=c6fe46a79ecd79606bb96fada4515f6b23f87b62 Merge branch 'pm-cpufreq' * pm-cpufreq: cpufreq: fix overflow in cpufreq_table_find_index_dl() --- diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000000..89c411b5ce6b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +*.c diff=cpp +*.h diff=cpp diff --git a/.mailmap b/.mailmap index 093a8ac9996e..02d261407683 100644 --- a/.mailmap +++ b/.mailmap @@ -69,11 +69,14 @@ James Bottomley James Bottomley James E Wilson James Ketrenos +Javi Merino Jean Tourrilhes Jeff Garzik Jens Axboe Jens Osterkamp +Johan Hovold +Johan Hovold John Paul Adrian Glaubitz John Stultz @@ -88,6 +91,7 @@ Kay Sievers Kenneth W Chen Konstantin Khlebnikov Koushik +Krzysztof Kozlowski Krzysztof Kozlowski Kuninori Morimoto Leonid I Ananiev @@ -123,6 +127,7 @@ Peter Oruba Peter Oruba Pratyush Anand Praveen BP +Qais Yousef Rajesh Shah Ralf Baechle Ralf Wildenhues @@ -158,6 +163,7 @@ Valdis Kletnieks Viresh Kumar Viresh Kumar Viresh Kumar +Vlad Dogaru Vladimir Davydov Vladimir Davydov Takashi YOSHII diff --git a/CREDITS b/CREDITS index 2a3fbcd229e6..513aaa3546bf 100644 --- a/CREDITS +++ b/CREDITS @@ -1090,6 +1090,10 @@ S: 6350 Stoneridge Mall Road S: Pleasanton, CA 94588 S: USA +N: Dmitry Eremin-Solenikov +E: dbaryshkov@gmail.com +D: Power Supply Maintainer from v3.14 - v3.15 + N: Doug Evans E: dje@cygnus.com D: Wrote Xenix FS (part of standard kernel since 0.99.15) @@ -1944,6 +1948,11 @@ E: kraxel@bytesex.org E: kraxel@suse.de D: video4linux, bttv, vesafb, some scsi, misc fixes +N: Hans J. Koch +D: USERSPACE I/O, MAX6650 +D: Hans passed away in June 2016, and will be greatly missed. +W: https://lwn.net/Articles/691000/ + N: Harald Koenig E: koenig@tat.physik.uni-tuebingen.de D: XFree86 (S3), DCF77, some kernel hacks and fixes @@ -2287,11 +2296,11 @@ D: Initial implementation of VC's, pty's and select() N: Pavel Machek E: pavel@ucw.cz -D: Softcursor for vga, hypertech cdrom support, vcsa bugfix, nbd +P: 4096R/92DFCE96 4FA7 9EEF FCD4 C44F C585 B8C7 C060 2241 92DF CE96 +D: Softcursor for vga, hypertech cdrom support, vcsa bugfix, nbd, D: sun4/330 port, capabilities for elf, speedup for rm on ext2, USB, -D: work on suspend-to-ram/disk, killing duplicates from ioctl32 -S: Volkova 1131 -S: 198 00 Praha 9 +D: work on suspend-to-ram/disk, killing duplicates from ioctl32, +D: Altera SoCFPGA and Nokia N900 support. S: Czech Republic N: Paul Mackerras @@ -3518,6 +3527,10 @@ S: 145 Howard St. S: Northborough, MA 01532 S: USA +N: Doug Thompson +E: dougthompson@xmission.com +D: EDAC + N: Tommy Thorn E: Tommy.Thorn@irisa.fr W: http://www.irisa.fr/prive/thorn/index.html @@ -3654,6 +3667,10 @@ S: Obere Heerbergstrasse 17 S: 97078 Wuerzburg S: Germany +N: Jason Uhlenkott +E: juhlenko@akamai.com +D: I3000 EDAC driver + N: Greg Ungerer E: gerg@snapgear.com D: uClinux kernel hacker @@ -3691,7 +3708,7 @@ S: Germany N: Geert Uytterhoeven E: geert@linux-m68k.org W: http://users.telenet.be/geertu/ -P: 1024/862678A6 C51D 361C 0BD1 4C90 B275 C553 6EEA 11BA 8626 78A6 +P: 4096R/4804B4BC3F55EEFB 750D 82B0 A781 5431 5E25 925B 4804 B4BC 3F55 EEFB D: m68k/Amiga and PPC/CHRP Longtrail coordinator D: Frame buffer device and XF68_FBDev maintainer D: m68k IDE maintainer diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index cb9a6c6fa83b..3acc4f1a6f84 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -46,7 +46,8 @@ IRQ.txt Intel-IOMMU.txt - basic info on the Intel IOMMU virtualization support. Makefile - - some files in Documentation dir are actually sample code to build + - This file does nothing. Removing it breaks make htmldocs and + make distclean. ManagementStyle - how to (attempt to) manage kernel hackers. RCU/ diff --git a/Documentation/80211/cfg80211.rst b/Documentation/80211/cfg80211.rst new file mode 100644 index 000000000000..b1e149ea6fee --- /dev/null +++ b/Documentation/80211/cfg80211.rst @@ -0,0 +1,345 @@ +================== +cfg80211 subsystem +================== + +Device registration +=================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Device registration + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_rate_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_rate + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_sta_ht_cap + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_supported_band + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_signal_type + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_params_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy + +.. kernel-doc:: include/net/cfg80211.h + :functions: wireless_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_new + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_register + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_unregister + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_free + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_name + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_priv + +.. kernel-doc:: include/net/cfg80211.h + :functions: priv_to_wiphy + +.. kernel-doc:: include/net/cfg80211.h + :functions: set_wiphy_dev + +.. kernel-doc:: include/net/cfg80211.h + :functions: wdev_priv + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_iface_limit + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_iface_combination + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_check_combinations + +Actions and configuration +========================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Actions and configuration + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ops + +.. kernel-doc:: include/net/cfg80211.h + :functions: vif_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: key_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: survey_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: survey_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_beacon_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ap_settings + +.. kernel-doc:: include/net/cfg80211.h + :functions: station_parameters + +.. kernel-doc:: include/net/cfg80211.h + :functions: rate_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: rate_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: station_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: monitor_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: mpath_info_flags + +.. kernel-doc:: include/net/cfg80211.h + :functions: mpath_info + +.. kernel-doc:: include/net/cfg80211.h + :functions: bss_parameters + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_txq_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_crypto_settings + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_auth_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_assoc_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_deauth_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_disassoc_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ibss_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_params + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_pmksa + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_mlme_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_auth_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_assoc_resp + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_assoc_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_tx_mlme_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ibss_joined + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_result + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_connect_timeout + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_roamed + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_disconnected + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ready_on_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_remain_on_channel_expired + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_new_sta + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_rx_mgmt + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_mgmt_tx_status + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_cqm_rssi_notify + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_cqm_pktloss_notify + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_michael_mic_failure + +Scanning and BSS list handling +============================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Scanning and BSS list handling + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_ssid + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_scan_request + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_scan_done + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss_frame_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_inform_bss_data + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_unlink_bss + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_find_ie + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_bss_get_ie + +Utility functions +================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Utility functions + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_channel_to_frequency + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_frequency_to_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_channel + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_response_rate + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_hdrlen + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_get_hdrlen_from_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_radiotap_iterator + +Data path helpers +================= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Data path helpers + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_data_to_8023 + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_data_from_8023 + +.. kernel-doc:: include/net/cfg80211.h + :functions: ieee80211_amsdu_to_8023s + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_classify8021d + +Regulatory enforcement infrastructure +===================================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: Regulatory enforcement infrastructure + +.. kernel-doc:: include/net/cfg80211.h + :functions: regulatory_hint + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_apply_custom_regulatory + +.. kernel-doc:: include/net/cfg80211.h + :functions: freq_reg_info + +RFkill integration +================== + +.. kernel-doc:: include/net/cfg80211.h + :doc: RFkill integration + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_set_hw_state + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_start_polling + +.. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_rfkill_stop_polling + +Test mode +========= + +.. kernel-doc:: include/net/cfg80211.h + :doc: Test mode + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_alloc_reply_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_reply + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_alloc_event_skb + +.. kernel-doc:: include/net/cfg80211.h + :functions: cfg80211_testmode_event diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py new file mode 100644 index 000000000000..20c7c275ef4a --- /dev/null +++ b/Documentation/80211/conf.py @@ -0,0 +1,5 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Linux 802.11 Driver Developer's Guide" + +tags.add("subproject") diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst new file mode 100644 index 000000000000..90bba476f442 --- /dev/null +++ b/Documentation/80211/index.rst @@ -0,0 +1,17 @@ +===================================== +Linux 802.11 Driver Developer's Guide +===================================== + +.. toctree:: + + introduction + cfg80211 + mac80211 + mac80211-advanced + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/80211/introduction.rst b/Documentation/80211/introduction.rst new file mode 100644 index 000000000000..4938fa87691c --- /dev/null +++ b/Documentation/80211/introduction.rst @@ -0,0 +1,17 @@ +============ +Introduction +============ + +Explaining wireless 802.11 networking in the Linux kernel + +Copyright 2007-2009 Johannes Berg + +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. + +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". diff --git a/Documentation/80211/mac80211-advanced.rst b/Documentation/80211/mac80211-advanced.rst new file mode 100644 index 000000000000..70a89b2163c2 --- /dev/null +++ b/Documentation/80211/mac80211-advanced.rst @@ -0,0 +1,295 @@ +============================= +mac80211 subsystem (advanced) +============================= + +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. + +LED support +=========== + +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. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tx_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_rx_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_assoc_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_radio_led_name + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tpt_blink + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tpt_led_trigger_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_create_tpt_led_trigger + +Hardware crypto acceleration +============================ + +.. kernel-doc:: include/net/mac80211.h + :doc: Hardware crypto acceleration + +.. kernel-doc:: include/net/mac80211.h + :functions: set_key_cmd + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_key_conf + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_key_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p1k + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p1k_iv + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_tkip_p2k + +Powersave support +================= + +.. kernel-doc:: include/net/mac80211.h + :doc: Powersave support + +Beacon filter support +===================== + +.. kernel-doc:: include/net/mac80211.h + :doc: Beacon filter support + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_beacon_loss + +Multiple queues and QoS support +=============================== + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_queue_params + +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. + +support for powersaving clients +------------------------------- + +.. kernel-doc:: include/net/mac80211.h + :doc: AP support for powersaving clients + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_get_buffered_bc + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_beacon_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_eosp + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_frame_release_type + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_ps_transition + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_ps_transition_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_set_buffered + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta_block_awake + +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. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_iterate_active_interfaces + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_iterate_active_interfaces_atomic + +Station handling +================ + +TODO + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_sta + +.. kernel-doc:: include/net/mac80211.h + :functions: sta_notify_cmd + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_find_sta + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_find_sta_by_ifaddr + +Hardware scan offload +===================== + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_scan_completed + +Aggregation +=========== + +TX A-MPDU aggregation +--------------------- + +.. kernel-doc:: net/mac80211/agg-tx.c + :doc: TX A-MPDU aggregation + +.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-tx.c + +RX A-MPDU aggregation +--------------------- + +.. kernel-doc:: net/mac80211/agg-rx.c + :doc: RX A-MPDU aggregation + +.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-rx.c + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ampdu_mlme_action + +Spatial Multiplexing Powersave (SMPS) +===================================== + +.. kernel-doc:: include/net/mac80211.h + :doc: Spatial multiplexing power save + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_request_smps + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_smps_mode + +TBD + +This part of the book describes the rate control algorithm interface and +how it relates to mac80211 and drivers. + +Rate Control API +================ + +TBD + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_start_tx_ba_session + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_start_tx_ba_cb_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_tx_ba_session + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_tx_ba_cb_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rate_control_changed + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_rate_control + +.. kernel-doc:: include/net/mac80211.h + :functions: rate_control_send_low + +TBD + +This part of the book describes mac80211 internals. + +Key handling +============ + +Key handling basics +------------------- + +.. kernel-doc:: net/mac80211/key.c + :doc: Key handling basics + +MORE TBD +-------- + +TBD + +Receive processing +================== + +TBD + +Transmit processing +=================== + +TBD + +Station info handling +===================== + +Programming information +----------------------- + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: sta_info + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: ieee80211_sta_info_flags + +STA information lifetime rules +------------------------------ + +.. kernel-doc:: net/mac80211/sta_info.c + :doc: STA information lifetime rules + +Aggregation +=========== + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: sta_ampdu_mlme + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: tid_ampdu_tx + +.. kernel-doc:: net/mac80211/sta_info.h + :functions: tid_ampdu_rx + +Synchronisation +=============== + +TBD + +Locking, lots of RCU diff --git a/Documentation/80211/mac80211.rst b/Documentation/80211/mac80211.rst new file mode 100644 index 000000000000..85a8335e80b6 --- /dev/null +++ b/Documentation/80211/mac80211.rst @@ -0,0 +1,216 @@ +=========================== +mac80211 subsystem (basics) +=========================== + +You should read and understand the information contained within this +part of the book while implementing a mac80211 driver. In some chapters, +advanced usage is noted, those may be skipped if this isn't needed. + +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. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_hw_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: SET_IEEE80211_DEV + +.. kernel-doc:: include/net/mac80211.h + :functions: SET_IEEE80211_PERM_ADDR + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ops + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_alloc_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_register_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_unregister_hw + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_free_hw + +PHY configuration +================= + +TBD + +This chapter should describe PHY handling including start/stop callbacks +and the various structures used. + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_conf + +.. kernel-doc:: include/net/mac80211.h + :functions: 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! + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_vif + +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 +------------ + +.. kernel-doc:: include/net/mac80211.h + :doc: Frame format + +Packet alignment +---------------- + +.. kernel-doc:: net/mac80211/rx.c + :doc: Packet alignment + +Calling into mac80211 from interrupts +------------------------------------- + +.. kernel-doc:: include/net/mac80211.h + :doc: Calling mac80211 from interrupts + +functions/definitions +--------------------- + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_status + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_rx_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_tx_info_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_tx_control_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: mac80211_rate_control_flags + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_rate + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_info + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_info_clear_status + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rx_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status_ni + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_tx_status_irqsafe + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rts_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_rts_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ctstoself_get + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_ctstoself_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_generic_frame_duration + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_wake_queue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_queue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_wake_queues + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_stop_queues + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_stopped + +Frame filtering +=============== + +.. kernel-doc:: include/net/mac80211.h + :doc: Frame filtering + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_filter_flags + +The mac80211 workqueue +====================== + +.. kernel-doc:: include/net/mac80211.h + :doc: mac80211 workqueue + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_work + +.. kernel-doc:: include/net/mac80211.h + :functions: ieee80211_queue_delayed_work diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd index 2ddd680929d8..f208ac58d613 100644 --- a/Documentation/ABI/testing/sysfs-bus-rbd +++ b/Documentation/ABI/testing/sysfs-bus-rbd @@ -6,7 +6,7 @@ Description: Being used for adding and removing rbd block devices. -Usage: [snap name] +Usage: [] $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add @@ -14,9 +14,13 @@ The snapshot name can be "-" or omitted to map the image read/write. A will be assigned for any registered block device. If snapshot is used, it will be mapped read-only. -Removal of a device: +Usage: [force] - $ echo > /sys/bus/rbd/remove + $ echo 2 > /sys/bus/rbd/remove + +Optional "force" argument which when passed will wait for running requests and +then unmap the image. Requests sent to the driver after initiating the removal +will be failed. (August 2016, since 4.9.) What: /sys/bus/rbd/add_single_major Date: December 2013 @@ -43,10 +47,25 @@ Description: Available only if rbd module is inserted with single_major Entries under /sys/bus/rbd/devices// -------------------------------------------- +client_addr + + The ceph unique client entity_addr_t (address + nonce). + The format is
:/: '1.2.3.4:1234/5678' or + '[1:2:3:4:5:6:7:8]:1234/5678'. (August 2016, since 4.9.) + client_id The ceph unique client id that was assigned for this specific session. +cluster_fsid + + The ceph cluster UUID. (August 2016, since 4.9.) + +config_info + + The string written into /sys/bus/rbd/add{,_single_major}. (August + 2016, since 4.9.) + features A hexadecimal encoding of the feature bits for this image. @@ -92,6 +111,10 @@ current_snap The current snapshot for which the device is mapped. +snap_id + + The current snapshot's id. (August 2016, since 4.9.) + parent Information identifying the chain of parent images in a layered rbd diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led index 3646ec85d513..86ace287d48b 100644 --- a/Documentation/ABI/testing/sysfs-class-led +++ b/Documentation/ABI/testing/sysfs-class-led @@ -24,7 +24,8 @@ Description: of led events. You can change triggers in a similar manner to the way an IO scheduler is chosen. Trigger specific parameters can appear in - /sys/class/leds/ once a given trigger is selected. + /sys/class/leds/ once a given trigger is selected. For + their documentation see sysfs-class-led-trigger-*. What: /sys/class/leds//inverted Date: January 2011 diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot new file mode 100644 index 000000000000..378a3a4df3c8 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot @@ -0,0 +1,36 @@ +What: /sys/class/leds//delay_on +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Specifies for how many milliseconds the LED has to stay at + LED_FULL brightness after it has been armed. + Defaults to 100 ms. + +What: /sys/class/leds//delay_off +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Specifies for how many milliseconds the LED has to stay at + LED_OFF brightness after it has been armed. + Defaults to 100 ms. + +What: /sys/class/leds//invert +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Reverse the blink logic. If set to 0 (default) blink on for + delay_on ms, then blink off for delay_off ms, leaving the LED + normally off. If set to 1, blink off for delay_off ms, then + blink on for delay_on ms, leaving the LED normally on. + Setting this value also immediately changes the LED state. + +What: /sys/class/leds//shot +Date: Jun 2012 +KernelVersion: 3.6 +Contact: linux-leds@vger.kernel.org +Description: + Write any non-empty string to signal an events, this starts a + blink sequence if not already running. diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport new file mode 100644 index 000000000000..f440e690daef --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport @@ -0,0 +1,12 @@ +What: /sys/class/leds//ports/ +Date: September 2016 +KernelVersion: 4.9 +Contact: linux-leds@vger.kernel.org + linux-usb@vger.kernel.org +Description: + Every dir entry represents a single USB port that can be + selected for the USB port trigger. Selecting ports makes trigger + observing them for any connected devices and lighting on LED if + there are any. + Echoing "1" value selects USB port. Echoing "0" unselects it. + Current state can be also read. diff --git a/Documentation/ABI/testing/sysfs-class-mic.txt b/Documentation/ABI/testing/sysfs-class-mic.txt index d45eed2bf128..6ef682603179 100644 --- a/Documentation/ABI/testing/sysfs-class-mic.txt +++ b/Documentation/ABI/testing/sysfs-class-mic.txt @@ -153,7 +153,7 @@ Description: What: /sys/class/mic/mic(x)/heartbeat_enable Date: March 2015 -KernelVersion: 3.20 +KernelVersion: 4.4 Contact: Ashutosh Dixit Description: The MIC drivers detect and inform user space about card crashes diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power index fa05719f9981..f85ce9e327b9 100644 --- a/Documentation/ABI/testing/sysfs-class-power +++ b/Documentation/ABI/testing/sysfs-class-power @@ -22,7 +22,7 @@ Description: What: /sys/class/power_supply/max14577-charger/device/fast_charge_timer Date: October 2014 KernelVersion: 3.18.0 -Contact: Krzysztof Kozlowski +Contact: Krzysztof Kozlowski Description: This entry shows and sets the maximum time the max14577 charger operates in fast-charge mode. When the timer expires @@ -36,7 +36,7 @@ Description: What: /sys/class/power_supply/max77693-charger/device/fast_charge_timer Date: January 2015 KernelVersion: 3.19.0 -Contact: Krzysztof Kozlowski +Contact: Krzysztof Kozlowski Description: This entry shows and sets the maximum time the max77693 charger operates in fast-charge mode. When the timer expires @@ -50,7 +50,7 @@ Description: What: /sys/class/power_supply/max77693-charger/device/top_off_threshold_current Date: January 2015 KernelVersion: 3.19.0 -Contact: Krzysztof Kozlowski +Contact: Krzysztof Kozlowski Description: This entry shows and sets the charging current threshold for entering top-off charging mode. When charging current in fast @@ -65,7 +65,7 @@ Description: What: /sys/class/power_supply/max77693-charger/device/top_off_timer Date: January 2015 KernelVersion: 3.19.0 -Contact: Krzysztof Kozlowski +Contact: Krzysztof Kozlowski Description: This entry shows and sets the maximum time the max77693 charger operates in top-off charge mode. When the timer expires diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff index db197a879580..305dffd229a8 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff @@ -35,6 +35,12 @@ Description: Displays a set of alternate modes supported by a wheel. Each DF-EX <*--------> G25 <-> G27 DF-EX <*----------------> G27 + G29: + DF-EX <*> DFP <-> G25 <-> G27 <-> G29 + DF-EX <*--------> G25 <-> G27 <-> G29 + DF-EX <*----------------> G27 <-> G29 + DF-EX <*------------------------> G29 + DFGT: DF-EX <*> DFP <-> DFGT DF-EX <*--------> DFGT @@ -50,3 +56,12 @@ Description: Displays the real model of the wheel regardless of any alternate mode the wheel might be switched to. It is a read-only value. This entry is not created for devices that have only one mode. + +What: /sys/bus/hid/drivers/logitech//combine_pedals +Date: Sep 2016 +KernelVersion: 4.9 +Contact: Simon Wood +Description: Controls whether a combined value of accelerator and brake is + reported on the Y axis of the controller. Useful for older games + which can do not work with separate accelerator/brake axis. + Off ('0') by default, enabled by setting '1'. diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom index dca429340772..2aa5503ee200 100644 --- a/Documentation/ABI/testing/sysfs-driver-wacom +++ b/Documentation/ABI/testing/sysfs-driver-wacom @@ -24,6 +24,7 @@ What: /sys/bus/hid/devices/::./wacom_led/status0_luminance Date: August 2014 Contact: linux-input@vger.kernel.org Description: + Writing to this file sets the status LED luminance (1..127) when the stylus does not touch the tablet surface, and no button is pressed on the stylus. This luminance level is @@ -33,6 +34,7 @@ What: /sys/bus/hid/devices/::./wacom_led/status1_luminance Date: August 2014 Contact: linux-input@vger.kernel.org Description: + Writing to this file sets the status LED luminance (1..127) when the stylus touches the tablet surface, or any button is pressed on the stylus. @@ -41,6 +43,7 @@ What: /sys/bus/hid/devices/::./wacom_led/status_led0_select Date: August 2014 Contact: linux-input@vger.kernel.org Description: + Writing to this file sets which one of the four (for Intuos 4 and Intuos 5) or of the right four (for Cintiq 21UX2 and Cintiq 24HD) status LEDs is active (0..3). The other three LEDs on the @@ -50,6 +53,7 @@ What: /sys/bus/hid/devices/::./wacom_led/status_led1_select Date: August 2014 Contact: linux-input@vger.kernel.org Description: + Writing to this file sets which one of the left four (for Cintiq 21UX2 and Cintiq 24HD) status LEDs is active (0..3). The other three LEDs on the left are always inactive. @@ -91,6 +95,7 @@ What: /sys/bus/hid/devices/::./wacom_remote//r Date: July 2015 Contact: linux-input@vger.kernel.org Description: + Reading from this file reports the mode status of the remote as indicated by the LED lights on the device. If no reports have been received from the paired device, reading diff --git a/Documentation/ABI/testing/sysfs-i2c-bmp085 b/Documentation/ABI/testing/sysfs-i2c-bmp085 deleted file mode 100644 index 585962ad0465..000000000000 --- a/Documentation/ABI/testing/sysfs-i2c-bmp085 +++ /dev/null @@ -1,31 +0,0 @@ -What: /sys/bus/i2c/devices/-/pressure0_input -Date: June 2010 -Contact: Christoph Mair -Description: Start a pressure measurement and read the result. Values - represent the ambient air pressure in pascal (0.01 millibar). - - Reading: returns the current air pressure. - - -What: /sys/bus/i2c/devices/-/temp0_input -Date: June 2010 -Contact: Christoph Mair -Description: Measure the ambient temperature. The returned value represents - the ambient temperature in units of 0.1 degree celsius. - - Reading: returns the current temperature. - - -What: /sys/bus/i2c/devices/-/oversampling -Date: June 2010 -Contact: Christoph Mair -Description: Tell the bmp085 to use more samples to calculate a pressure - value. When writing to this file the chip will use 2^x samples - to calculate the next pressure value with x being the value - written. Using this feature will decrease RMS noise and - increase the measurement time. - - Reading: returns the current oversampling setting. - - Writing: sets a new oversampling setting. - Accepted values: 0..3. diff --git a/Documentation/ABI/testing/sysfs-kernel-irq b/Documentation/ABI/testing/sysfs-kernel-irq new file mode 100644 index 000000000000..eb074b100986 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-irq @@ -0,0 +1,53 @@ +What: /sys/kernel/irq +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: Directory containing information about the system's IRQs. + Specifically, data from the associated struct irq_desc. + The information here is similar to that in /proc/interrupts + but in a more machine-friendly format. This directory contains + one subdirectory for each Linux IRQ number. + +What: /sys/kernel/irq//actions +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: The IRQ action chain. A comma-separated list of zero or more + device names associated with this interrupt. + +What: /sys/kernel/irq//chip_name +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: Human-readable chip name supplied by the associated device + driver. + +What: /sys/kernel/irq//hwirq +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: When interrupt translation domains are used, this file contains + the underlying hardware IRQ number used for this Linux IRQ. + +What: /sys/kernel/irq//name +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: Human-readable flow handler name as defined by the irq chip + driver. + +What: /sys/kernel/irq//per_cpu_count +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: The number of times the interrupt has fired since boot. This + is a comma-separated list of counters; one per CPU in CPU id + order. NOTE: This file consistently shows counters for all + CPU ids. This differs from the behavior of /proc/interrupts + which only shows counters for online CPUs. + +What: /sys/kernel/irq//type +Date: September 2016 +KernelVersion: 4.9 +Contact: Craig Gallek +Description: The type of the interrupt. Either the string 'level' or 'edge'. diff --git a/Documentation/Changes b/Documentation/Changes index ec97b77c8b00..22797a15dc24 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -1,8 +1,13 @@ +.. _changes: + +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + Intro ===== This document is designed to provide a list of the minimum levels of -software necessary to run the 3.0 kernels. +software necessary to run the 4.x kernels. This document is originally based on my "Changes" file for 2.0.x kernels and therefore owes credit to the same people as that file (Jared Mauch, @@ -10,9 +15,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the 'net). Current Minimal Requirements -============================ +**************************** -Upgrade to at *least* these software revisions before thinking you've +Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently running, the suggested command should tell you. @@ -21,34 +26,40 @@ running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o GNU C 3.2 # gcc --version -o GNU make 3.80 # make --version -o binutils 2.12 # ld -v -o util-linux 2.10o # fdformat --version -o module-init-tools 0.9.10 # depmod -V -o e2fsprogs 1.41.4 # e2fsck -V -o jfsutils 1.1.3 # fsck.jfs -V -o reiserfsprogs 3.6.3 # reiserfsck -V -o xfsprogs 2.6.0 # xfs_db -V -o squashfs-tools 4.0 # mksquashfs -version -o btrfs-progs 0.18 # btrfsck -o pcmciautils 004 # pccardctl -V -o quota-tools 3.09 # quota -V -o PPP 2.4.0 # pppd --version -o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version -o nfs-utils 1.0.5 # showmount --version -o procps 3.2.0 # ps --version -o oprofile 0.9 # oprofiled --version -o udev 081 # udevd --version -o grub 0.93 # grub --version || grub-install --version -o mcelog 0.6 # mcelog --version -o iptables 1.4.2 # iptables -V -o openssl & libcrypto 1.0.0 # openssl version -o bc 1.06.95 # bc --version - +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version +====================== =============== ======================================== + +.. [#f1] Sphinx is needed only to build the Kernel documentation Kernel compilation -================== +****************** GCC --- @@ -64,16 +75,16 @@ You will need GNU make 3.80 or later to build the kernel. Binutils -------- -Linux on IA-32 has recently switched from using as86 to using gas for -assembling the 16-bit boot code, removing the need for as86 to compile +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile your kernel. This change does, however, mean that you need a recent release of binutils. Perl ---- -You will need perl 5 and the following modules: Getopt::Long, Getopt::Std, -File::Basename, and File::Find to build the kernel. +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. BC -- @@ -93,7 +104,7 @@ and higher. System utilities -================ +**************** Architectural changes --------------------- @@ -115,7 +126,7 @@ well as the desired DocBook stylesheets. Util-linux ---------- -New versions of util-linux provide *fdisk support for larger disks, +New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition types, have a fdformat which works with 2.4 kernels, and similar goodies. You'll probably want to upgrade. @@ -125,54 +136,57 @@ Ksymoops If the unthinkable happens and your kernel oopses, you may need the ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with CONFIG_KALLSYMS so +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so that it produces readable dumps that can be used as-is (this also produces better output than ksymoops). If for some reason your kernel -is not build with CONFIG_KALLSYMS and you have no way to rebuild and +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and reproduce the Oops with that option, then you can still decode that Oops with ksymoops. Module-Init-Tools ----------------- -A new module loader is now in the kernel that requires module-init-tools +A new module loader is now in the kernel that requires ``module-init-tools`` to use. It is backward compatible with the 2.4.x series kernels. Mkinitrd -------- -These changes to the /lib/modules file tree layout also require that +These changes to the ``/lib/modules`` file tree layout also require that mkinitrd be upgraded. E2fsprogs --------- -The latest version of e2fsprogs fixes several bugs in fsck and +The latest version of ``e2fsprogs`` fixes several bugs in fsck and debugfs. Obviously, it's a good idea to upgrade. JFSutils -------- -The jfsutils package contains the utilities for the file system. +The ``jfsutils`` package contains the utilities for the file system. The following utilities are available: -o fsck.jfs - initiate replay of the transaction log, and check + +- ``fsck.jfs`` - initiate replay of the transaction log, and check and repair a JFS formatted partition. -o mkfs.jfs - create a JFS formatted partition. -o other file system utilities are also available in this package. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. Reiserfsprogs ------------- The reiserfsprogs package should be used for reiserfs-3.6.x (Linux kernels 2.4.x). It is a combined package and contains working -versions of mkreiserfs, resize_reiserfs, debugreiserfs and -reiserfsck. These utils work on both i386 and alpha platforms. +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. Xfsprogs -------- -The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the -xfs_repair utilities, among others, for the XFS filesystem. It is +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is architecture independent and any version from 2.0.0 onward should work correctly with this version of the XFS kernel code (2.6.0 or later is recommended, due to some significant improvements). @@ -180,7 +194,7 @@ later is recommended, due to some significant improvements). PCMCIAutils ----------- -PCMCIAutils replaces pcmcia-cs. It properly sets up +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up PCMCIA sockets at system startup and loads the appropriate modules for 16-bit PCMCIA devices if the kernel is modularized and the hotplug subsystem is used. @@ -198,19 +212,20 @@ Intel IA32 microcode A driver has been added to allow updating of Intel IA32 microcode, accessible as a normal (misc) character device. If you are not using -udev you may need to: +udev you may need to:: -mkdir /dev/cpu -mknod /dev/cpu/microcode c 10 184 -chmod 0644 /dev/cpu/microcode + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode as root before you can use this. You'll probably also want to get the user-space microcode_ctl utility to use with this. udev ---- -udev is a userspace application for populating /dev dynamically with -only entries for devices actually present. udev replaces the basic + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic functionality of devfs, while allowing persistent device naming for devices. @@ -218,10 +233,10 @@ FUSE ---- Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options 'direct_io' and 'kernel_cache' won't work. +options ``direct_io`` and ``kernel_cache`` won't work. Networking -========== +********** General changes --------------- @@ -243,9 +258,9 @@ enable it to operate over diverse media layers. If you use PPP, upgrade pppd to at least 2.4.0. If you are not using udev, you must have the device file /dev/ppp -which can be made by: +which can be made by:: -mknod /dev/ppp c 108 0 + mknod /dev/ppp c 108 0 as root. @@ -260,22 +275,22 @@ NFS-utils In ancient (2.4 and earlier) kernels, the nfs server needed to know about any client that expected to be able to access files via NFS. This -information would be given to the kernel by "mountd" when the client -mounted the filesystem, or by "exportfs" at system startup. exportfs -would take information about active clients from /var/lib/nfs/rmtab. +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. This approach is quite fragile as it depends on rmtab being correct which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, rmtab suffers from +fail-over. Even when the system is working well, ``rmtab`` suffers from getting lots of old entries that never get removed. With modern kernels we have the option of having the kernel tell mountd when it gets a request from an unknown host, and mountd can give appropriate export information to the kernel. This removes the -dependency on rmtab and means that the kernel only needs to know about +dependency on ``rmtab`` and means that the kernel only needs to know about currently active clients. -To enable this new functionality, you need to: +To enable this new functionality, you need to:: mount -t nfsd nfsd /proc/fs/nfsd @@ -287,8 +302,32 @@ mcelog ------ On x86 kernels the mcelog utility is needed to process and log machine check -events when CONFIG_X86_MCE is enabled. Machine check events are errors reported -by the CPU. Processing them is strongly encouraged. +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. + +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. Getting updated software ======================== @@ -298,114 +337,149 @@ Kernel compilation gcc --- -o + +- Make ---- -o + +- Binutils -------- -o + +- OpenSSL ------- -o + +- System utilities **************** Util-linux ---------- -o + +- Ksymoops -------- -o + +- Module-Init-Tools ----------------- -o + +- Mkinitrd -------- -o + +- E2fsprogs --------- -o + +- JFSutils -------- -o + +- Reiserfsprogs ------------- -o + +- Xfsprogs -------- -o + +- Pcmciautils ----------- -o + +- Quota-tools ----------- -o +----------- + +- DocBook Stylesheets ------------------- -o + +- XMLTO XSLT Frontend ------------------- -o + +- Intel P6 microcode ------------------ -o + +- udev ---- -o + +- FUSE ---- -o + +- mcelog ------ -o + +- Networking ********** PPP --- -o + +- Isdn4k-utils ------------ -o + +- NFS-utils --------- -o + +- Iptables -------- -o + +- Ip-route2 --------- -o + +- OProfile -------- -o + +- NFS-Utils --------- -o + +- + +Kernel documentation +******************** + +Sphinx +------ + +- diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict index 1684d0b4efa6..49a8ecc157a2 100644 --- a/Documentation/CodeOfConflict +++ b/Documentation/CodeOfConflict @@ -19,7 +19,7 @@ please contact the Linux Foundation's Technical Advisory Board at will work to resolve the issue to the best of their ability. For more information on who is on the Technical Advisory Board and what their role is, please see: - http://www.linuxfoundation.org/programs/advisory-councils/tab + http://www.linuxfoundation.org/projects/linux/tab As a reviewer of code, please strive to keep things civil and focused on the technical issues involved. We are all humans, and frustrations can diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index a096836723ca..9c61c039ccd9 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -1,8 +1,10 @@ +.. _codingstyle: - Linux kernel coding style +Linux kernel coding style +========================= This is a short document describing the preferred coding style for the -linux kernel. Coding style is very personal, and I won't _force_ my +linux kernel. Coding style is very personal, and I won't **force** my views on anybody, but this is what goes for anything that I have to be able to maintain, and I'd prefer it for most other things too. Please at least consider the points made here. @@ -13,7 +15,8 @@ and NOT read it. Burn them, it's a great symbolic gesture. Anyway, here goes: - Chapter 1: Indentation +1) Indentation +-------------- Tabs are 8 characters, and thus indentations are also 8 characters. There are heretic movements that try to make indentations 4 (or even 2!) @@ -36,8 +39,10 @@ benefit of warning you when you're nesting your functions too deep. Heed that warning. The preferred way to ease multiple indentation levels in a switch statement is -to align the "switch" and its subordinate "case" labels in the same column -instead of "double-indenting" the "case" labels. E.g.: +to align the ``switch`` and its subordinate ``case`` labels in the same column +instead of ``double-indenting`` the ``case`` labels. E.g.: + +.. code-block:: c switch (suffix) { case 'G': @@ -59,6 +64,8 @@ instead of "double-indenting" the "case" labels. E.g.: Don't put multiple statements on a single line unless you have something to hide: +.. code-block:: c + if (condition) do_this; do_something_everytime; @@ -71,7 +78,8 @@ used for indentation, and the above example is deliberately broken. Get a decent editor and don't leave whitespace at the end of lines. - Chapter 2: Breaking long lines and strings +2) Breaking long lines and strings +---------------------------------- Coding style is all about readability and maintainability using commonly available tools. @@ -87,7 +95,8 @@ with a long argument list. However, never break user-visible strings such as printk messages, because that breaks the ability to grep for them. - Chapter 3: Placing Braces and Spaces +3) Placing Braces and Spaces +---------------------------- The other issue that always comes up in C styling is the placement of braces. Unlike the indent size, there are few technical reasons to @@ -95,6 +104,8 @@ choose one placement strategy over the other, but the preferred way, as shown to us by the prophets Kernighan and Ritchie, is to put the opening brace last on the line, and put the closing brace first, thusly: +.. code-block:: c + if (x is true) { we do y } @@ -102,6 +113,8 @@ brace last on the line, and put the closing brace first, thusly: This applies to all non-function statement blocks (if, switch, for, while, do). E.g.: +.. code-block:: c + switch (action) { case KOBJ_ADD: return "add"; @@ -116,6 +129,8 @@ while, do). E.g.: However, there is one special case, namely functions: they have the opening brace at the beginning of the next line, thus: +.. code-block:: c + int function(int x) { body of function @@ -123,20 +138,24 @@ opening brace at the beginning of the next line, thus: Heretic people all over the world have claimed that this inconsistency is ... well ... inconsistent, but all right-thinking people know that -(a) K&R are _right_ and (b) K&R are right. Besides, functions are +(a) K&R are **right** and (b) K&R are right. Besides, functions are special anyway (you can't nest them in C). -Note that the closing brace is empty on a line of its own, _except_ in +Note that the closing brace is empty on a line of its own, **except** in the cases where it is followed by a continuation of the same statement, -ie a "while" in a do-statement or an "else" in an if-statement, like +ie a ``while`` in a do-statement or an ``else`` in an if-statement, like this: +.. code-block:: c + do { body of do-loop } while (condition); and +.. code-block:: c + if (x == y) { .. } else if (x > y) { @@ -155,11 +174,15 @@ comments on. Do not unnecessarily use braces where a single statement will do. +.. code-block:: c + if (condition) action(); and +.. code-block:: none + if (condition) do_this(); else @@ -168,6 +191,8 @@ and This does not apply if only one branch of a conditional statement is a single statement; in the latter case use braces in both branches: +.. code-block:: c + if (condition) { do_this(); do_that(); @@ -175,57 +200,67 @@ statement; in the latter case use braces in both branches: otherwise(); } - 3.1: Spaces +3.1) Spaces +*********** Linux kernel style for use of spaces depends (mostly) on function-versus-keyword usage. Use a space after (most) keywords. The notable exceptions are sizeof, typeof, alignof, and __attribute__, which look somewhat like functions (and are usually used with parentheses in Linux, -although they are not required in the language, as in: "sizeof info" after -"struct fileinfo info;" is declared). +although they are not required in the language, as in: ``sizeof info`` after +``struct fileinfo info;`` is declared). -So use a space after these keywords: +So use a space after these keywords:: if, switch, case, for, do, while but not with sizeof, typeof, alignof, or __attribute__. E.g., +.. code-block:: c + + s = sizeof(struct file); Do not add spaces around (inside) parenthesized expressions. This example is -*bad*: +**bad**: + +.. code-block:: c + s = sizeof( struct file ); When declaring pointer data or a function that returns a pointer type, the -preferred use of '*' is adjacent to the data name or function name and not +preferred use of ``*`` is adjacent to the data name or function name and not adjacent to the type name. Examples: +.. code-block:: c + + char *linux_banner; unsigned long long memparse(char *ptr, char **retptr); char *match_strdup(substring_t *s); Use one space around (on each side of) most binary and ternary operators, -such as any of these: +such as any of these:: = + - < > * / % | & ^ <= >= == != ? : -but no space after unary operators: +but no space after unary operators:: & * + - ~ ! sizeof typeof alignof __attribute__ defined -no space before the postfix increment & decrement unary operators: +no space before the postfix increment & decrement unary operators:: ++ -- -no space after the prefix increment & decrement unary operators: +no space after the prefix increment & decrement unary operators:: ++ -- -and no space around the '.' and "->" structure member operators. +and no space around the ``.`` and ``->`` structure member operators. Do not leave trailing whitespace at the ends of lines. Some editors with -"smart" indentation will insert whitespace at the beginning of new lines as +``smart`` indentation will insert whitespace at the beginning of new lines as appropriate, so you can start typing the next line of code right away. However, some such editors do not remove the whitespace if you end up not putting a line of code there, such as if you leave a blank line. As a result, @@ -237,22 +272,23 @@ of patches, this may make later patches in the series fail by changing their context lines. - Chapter 4: Naming +4) Naming +--------- C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that -variable "tmp", which is much easier to write, and not the least more +variable ``tmp``, which is much easier to write, and not the least more difficult to understand. HOWEVER, while mixed-case names are frowned upon, descriptive names for -global variables are a must. To call a global function "foo" is a +global variables are a must. To call a global function ``foo`` is a shooting offense. -GLOBAL variables (to be used only if you _really_ need them) need to +GLOBAL variables (to be used only if you **really** need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that -"count_active_users()" or similar, you should _not_ call it "cntusr()". +``count_active_users()`` or similar, you should **not** call it ``cntusr()``. Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged - the compiler knows the types anyway and can @@ -260,9 +296,9 @@ check those, and it only confuses the programmer. No wonder MicroSoft makes buggy programs. LOCAL variable names should be short, and to the point. If you have -some random integer loop counter, it should probably be called "i". -Calling it "loop_counter" is non-productive, if there is no chance of it -being mis-understood. Similarly, "tmp" can be just about any type of +some random integer loop counter, it should probably be called ``i``. +Calling it ``loop_counter`` is non-productive, if there is no chance of it +being mis-understood. Similarly, ``tmp`` can be just about any type of variable that is used to hold a temporary value. If you are afraid to mix up your local variable names, you have another @@ -270,59 +306,69 @@ problem, which is called the function-growth-hormone-imbalance syndrome. See chapter 6 (Functions). - Chapter 5: Typedefs +5) Typedefs +----------- + +Please don't use things like ``vps_t``. +It's a **mistake** to use typedef for structures and pointers. When you see a + +.. code-block:: c -Please don't use things like "vps_t". -It's a _mistake_ to use typedef for structures and pointers. When you see a vps_t a; in the source, what does it mean? In contrast, if it says +.. code-block:: c + struct virtual_container *a; -you can actually tell what "a" is. +you can actually tell what ``a`` is. -Lots of people think that typedefs "help readability". Not so. They are +Lots of people think that typedefs ``help readability``. Not so. They are useful only for: - (a) totally opaque objects (where the typedef is actively used to _hide_ + (a) totally opaque objects (where the typedef is actively used to **hide** what the object is). - Example: "pte_t" etc. opaque objects that you can only access using + Example: ``pte_t`` etc. opaque objects that you can only access using the proper accessor functions. - NOTE! Opaqueness and "accessor functions" are not good in themselves. - The reason we have them for things like pte_t etc. is that there - really is absolutely _zero_ portably accessible information there. + .. note:: + + Opaqueness and ``accessor functions`` are not good in themselves. + The reason we have them for things like pte_t etc. is that there + really is absolutely **zero** portably accessible information there. - (b) Clear integer types, where the abstraction _helps_ avoid confusion - whether it is "int" or "long". + (b) Clear integer types, where the abstraction **helps** avoid confusion + whether it is ``int`` or ``long``. u8/u16/u32 are perfectly fine typedefs, although they fit into category (d) better than here. - NOTE! Again - there needs to be a _reason_ for this. If something is - "unsigned long", then there's no reason to do + .. note:: + + Again - there needs to be a **reason** for this. If something is + ``unsigned long``, then there's no reason to do typedef unsigned long myflags_t; but if there is a clear reason for why it under certain circumstances - might be an "unsigned int" and under other configurations might be - "unsigned long", then by all means go ahead and use a typedef. + might be an ``unsigned int`` and under other configurations might be + ``unsigned long``, then by all means go ahead and use a typedef. - (c) when you use sparse to literally create a _new_ type for + (c) when you use sparse to literally create a **new** type for type-checking. (d) New types which are identical to standard C99 types, in certain exceptional circumstances. Although it would only take a short amount of time for the eyes and - brain to become accustomed to the standard types like 'uint32_t', + brain to become accustomed to the standard types like ``uint32_t``, some people object to their use anyway. - Therefore, the Linux-specific 'u8/u16/u32/u64' types and their + Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their signed equivalents which are identical to standard types are permitted -- although they are not mandatory in new code of your own. @@ -333,7 +379,7 @@ useful only for: (e) Types safe for use in userspace. In certain structures which are visible to userspace, we cannot - require C99 types and cannot use the 'u32' form above. Thus, we + require C99 types and cannot use the ``u32`` form above. Thus, we use __u32 and similar types in all structures which are shared with userspace. @@ -341,10 +387,11 @@ Maybe there are other cases too, but the rule should basically be to NEVER EVER use a typedef unless you can clearly match one of those rules. In general, a pointer, or a struct that has elements that can reasonably -be directly accessed should _never_ be a typedef. +be directly accessed should **never** be a typedef. - Chapter 6: Functions +6) Functions +------------ Functions should be short and sweet, and do just one thing. They should fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, @@ -372,8 +419,10 @@ and it gets confused. You know you're brilliant, but maybe you'd like to understand what you did 2 weeks from now. In source files, separate functions with one blank line. If the function is -exported, the EXPORT* macro for it should follow immediately after the closing -function brace line. E.g.: +exported, the **EXPORT** macro for it should follow immediately after the +closing function brace line. E.g.: + +.. code-block:: c int system_is_up(void) { @@ -386,7 +435,8 @@ Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader. - Chapter 7: Centralized exiting of functions +7) Centralized exiting of functions +----------------------------------- Albeit deprecated by some people, the equivalent of the goto statement is used frequently by compilers in form of the unconditional jump instruction. @@ -396,18 +446,21 @@ locations and some common work such as cleanup has to be done. If there is no cleanup needed then just return directly. Choose label names which say what the goto does or why the goto exists. An -example of a good name could be "out_buffer:" if the goto frees "buffer". Avoid -using GW-BASIC names like "err1:" and "err2:". Also don't name them after the -goto location like "err_kmalloc_failed:" +example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. +Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to +renumber them if you ever add or remove exit paths, and they make correctness +difficult to verify anyway. The rationale for using gotos is: - unconditional statements are easier to understand and follow - nesting is reduced - errors by not updating individual exit points when making - modifications are prevented + modifications are prevented - saves the compiler work to optimize redundant code away ;) +.. code-block:: c + int fun(int a) { int result = 0; @@ -425,27 +478,41 @@ The rationale for using gotos is: goto out_buffer; } ... - out_buffer: + out_free_buffer: kfree(buffer); return result; } -A common type of bug to be aware of is "one err bugs" which look like this: +A common type of bug to be aware of is ``one err bugs`` which look like this: + +.. code-block:: c err: kfree(foo->bar); kfree(foo); return ret; -The bug in this code is that on some exit paths "foo" is NULL. Normally the -fix for this is to split it up into two error labels "err_bar:" and "err_foo:". +The bug in this code is that on some exit paths ``foo`` is NULL. Normally the +fix for this is to split it up into two error labels ``err_free_bar:`` and +``err_free_foo:``: +.. code-block:: c - Chapter 8: Commenting + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Ideally you should simulate errors to test all exit paths. + + +8) Commenting +------------- Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to -write the code so that the _working_ is obvious, and it's a waste of +write the code so that the **working** is obvious, and it's a waste of time to explain badly written code. Generally, you want your comments to tell WHAT your code does, not HOW. @@ -461,11 +528,10 @@ When commenting the kernel API functions, please use the kernel-doc format. See the files Documentation/kernel-documentation.rst and scripts/kernel-doc for details. -Linux style for comments is the C89 "/* ... */" style. -Don't use C99-style "// ..." comments. - The preferred style for long (multi-line) comments is: +.. code-block:: c + /* * This is the preferred style for multi-line * comments in the Linux kernel source code. @@ -478,6 +544,8 @@ The preferred style for long (multi-line) comments is: For files in net/ and drivers/net/ the preferred style for long (multi-line) comments is a little different. +.. code-block:: c + /* The preferred comment style for files in net/ and drivers/net * looks like this. * @@ -491,10 +559,11 @@ multiple data declarations). This leaves you room for a small comment on each item, explaining its use. - Chapter 9: You've made a mess of it +9) You've made a mess of it +--------------------------- That's OK, we all do. You've probably been told by your long-time Unix -user helper that "GNU emacs" automatically formats the C sources for +user helper that ``GNU emacs`` automatically formats the C sources for you, and you've noticed that yes, it does do that, but the defaults it uses are less than desirable (in fact, they are worse than random typing - an infinite number of monkeys typing into GNU emacs would never @@ -503,63 +572,66 @@ make a good program). So, you can either get rid of GNU emacs, or change it to use saner values. To do the latter, you can stick the following in your .emacs file: -(defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - -(add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - -(add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + + (add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) This will make emacs go better with the kernel coding style for C -files below ~/src/linux-trees. +files below ``~/src/linux-trees``. But even if you fail in getting emacs to do sane formatting, not -everything is lost: use "indent". +everything is lost: use ``indent``. Now, again, GNU indent has the same brain-dead settings that GNU emacs has, which is why you need to give it a few command line options. However, that's not too bad, because even the makers of GNU indent recognize the authority of K&R (the GNU people aren't evil, they are just severely misguided in this matter), so you just give indent the -options "-kr -i8" (stands for "K&R, 8 character indents"), or use -"scripts/Lindent", which indents in the latest style. +options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use +``scripts/Lindent``, which indents in the latest style. -"indent" has a lot of options, and especially when it comes to comment +``indent`` has a lot of options, and especially when it comes to comment re-formatting you may want to take a look at the man page. But -remember: "indent" is not a fix for bad programming. +remember: ``indent`` is not a fix for bad programming. - Chapter 10: Kconfig configuration files +10) Kconfig configuration files +------------------------------- For all of the Kconfig* configuration files throughout the source tree, -the indentation is somewhat different. Lines under a "config" definition +the indentation is somewhat different. Lines under a ``config`` definition are indented with one tab, while help text is indented an additional two -spaces. Example: +spaces. Example:: -config AUDIT + config AUDIT bool "Auditing support" depends on NET help @@ -569,9 +641,9 @@ config AUDIT auditing without CONFIG_AUDITSYSCALL. Seriously dangerous features (such as write support for certain -filesystems) should advertise this prominently in their prompt string: +filesystems) should advertise this prominently in their prompt string:: -config ADFS_FS_RW + config ADFS_FS_RW bool "ADFS write support (DANGEROUS)" depends on ADFS_FS ... @@ -580,41 +652,45 @@ For full documentation on the configuration files, see the file Documentation/kbuild/kconfig-language.txt. - Chapter 11: Data structures +11) Data structures +------------------- Data structures that have visibility outside the single-threaded environment they are created and destroyed in should always have reference counts. In the kernel, garbage collection doesn't exist (and outside the kernel garbage collection is slow and inefficient), which -means that you absolutely _have_ to reference count all your uses. +means that you absolutely **have** to reference count all your uses. Reference counting means that you can avoid locking, and allows multiple users to have access to the data structure in parallel - and not having to worry about the structure suddenly going away from under them just because they slept or did something else for a while. -Note that locking is _not_ a replacement for reference counting. +Note that locking is **not** a replacement for reference counting. Locking is used to keep data structures coherent, while reference counting is a memory management technique. Usually both are needed, and they are not to be confused with each other. Many data structures can indeed have two levels of reference counting, -when there are users of different "classes". The subclass count counts +when there are users of different ``classes``. The subclass count counts the number of subclass users, and decrements the global count just once when the subclass count goes to zero. -Examples of this kind of "multi-level-reference-counting" can be found in -memory management ("struct mm_struct": mm_users and mm_count), and in -filesystem code ("struct super_block": s_count and s_active). +Examples of this kind of ``multi-level-reference-counting`` can be found in +memory management (``struct mm_struct``: mm_users and mm_count), and in +filesystem code (``struct super_block``: s_count and s_active). Remember: if another thread can find your data structure, and you don't have a reference count on it, you almost certainly have a bug. - Chapter 12: Macros, Enums and RTL +12) Macros, Enums and RTL +------------------------- Names of macros defining constants and labels in enums are capitalized. +.. code-block:: c + #define CONSTANT 0x12345 Enums are preferred when defining several related constants. @@ -626,7 +702,9 @@ Generally, inline functions are preferable to macros resembling functions. Macros with multiple statements should be enclosed in a do - while block: - #define macrofun(a, b, c) \ +.. code-block:: c + + #define macrofun(a, b, c) \ do { \ if (a == 5) \ do_this(b, c); \ @@ -636,17 +714,21 @@ Things to avoid when using macros: 1) macros that affect control flow: +.. code-block:: c + #define FOO(x) \ do { \ if (blah(x) < 0) \ return -EBUGGERED; \ } while (0) -is a _very_ bad idea. It looks like a function call but exits the "calling" +is a **very** bad idea. It looks like a function call but exits the ``calling`` function; don't break the internal parsers of those who will read the code. 2) macros that depend on having a local variable with a magic name: +.. code-block:: c + #define FOO(val) bar(index, val) might look like a good thing, but it's confusing as hell when one reads the @@ -659,18 +741,22 @@ bite you if somebody e.g. turns FOO into an inline function. must enclose the expression in parentheses. Beware of similar issues with macros using parameters. +.. code-block:: c + #define CONSTANT 0x4000 #define CONSTEXP (CONSTANT | 3) 5) namespace collisions when defining local variables in macros resembling functions: -#define FOO(x) \ -({ \ - typeof(x) ret; \ - ret = calc_ret(x); \ - (ret); \ -}) +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) ret is a common name for a local variable - __foo_ret is less likely to collide with an existing variable. @@ -679,11 +765,12 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also covers RTL which is used frequently with assembly language in the kernel. - Chapter 13: Printing kernel messages +13) Printing kernel messages +---------------------------- Kernel developers like to be seen as literate. Do mind the spelling of kernel messages to make a good impression. Do not use crippled -words like "dont"; use "do not" or "don't" instead. Make the messages +words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages concise, clear, and unambiguous. Kernel messages do not have to be terminated with a period. @@ -713,7 +800,8 @@ already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be used. - Chapter 14: Allocating memory +14) Allocating memory +--------------------- The kernel provides the following general purpose memory allocators: kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and @@ -722,6 +810,8 @@ about them. The preferred form for passing a size of a struct is the following: +.. code-block:: c + p = kmalloc(sizeof(*p), ...); The alternative form where struct name is spelled out hurts readability and @@ -734,20 +824,25 @@ language. The preferred form for allocating an array is the following: +.. code-block:: c + p = kmalloc_array(n, sizeof(...), ...); The preferred form for allocating a zeroed array is the following: +.. code-block:: c + p = kcalloc(n, sizeof(...), ...); Both forms check for overflow on the allocation size n * sizeof(...), and return NULL if that occurred. - Chapter 15: The inline disease +15) The inline disease +---------------------- There appears to be a common misperception that gcc has a magic "make me -faster" speedup option called "inline". While the use of inlines can be +faster" speedup option called ``inline``. While the use of inlines can be appropriate (for example as a means of replacing macros, see Chapter 12), it very often is not. Abundant use of the inline keyword leads to a much bigger kernel, which in turn slows the system as a whole down, due to a bigger @@ -771,26 +866,27 @@ appears outweighs the potential value of the hint that tells gcc to do something it would have done anyway. - Chapter 16: Function return values and names +16) Function return values and names +------------------------------------ Functions can return values of many different kinds, and one of the most common is a value indicating whether the function succeeded or failed. Such a value can be represented as an error-code integer -(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure, +(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, non-zero = success). Mixing up these two sorts of representations is a fertile source of difficult-to-find bugs. If the C language included a strong distinction between integers and booleans then the compiler would find these mistakes for us... but it doesn't. To help prevent such bugs, always follow this -convention: +convention:: If the name of a function is an action or an imperative command, the function should return an error-code integer. If the name is a predicate, the function should return a "succeeded" boolean. -For example, "add work" is a command, and the add_work() function returns 0 -for success or -EBUSY for failure. In the same way, "PCI device present" is +For example, ``add work`` is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, ``PCI device present`` is a predicate, and the pci_dev_present() function returns 1 if it succeeds in finding a matching device or 0 if it doesn't. @@ -805,17 +901,22 @@ result. Typical examples would be functions that return pointers; they use NULL or the ERR_PTR mechanism to report failure. - Chapter 17: Don't re-invent the kernel macros +17) Don't re-invent the kernel macros +------------------------------------- The header file include/linux/kernel.h contains a number of macros that you should use, rather than explicitly coding some variant of them yourself. For example, if you need to calculate the length of an array, take advantage of the macro +.. code-block:: c + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) Similarly, if you need to calculate the size of some structure member, use +.. code-block:: c + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) There are also min() and max() macros that do strict type checking if you @@ -823,16 +924,21 @@ need them. Feel free to peruse that header file to see what else is already defined that you shouldn't reproduce in your code. - Chapter 18: Editor modelines and other cruft +18) Editor modelines and other cruft +------------------------------------ Some editors can interpret configuration information embedded in source files, indicated with special markers. For example, emacs interprets lines marked like this: +.. code-block:: c + -*- mode: c -*- Or like this: +.. code-block:: c + /* Local Variables: compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" @@ -841,6 +947,8 @@ Or like this: Vim interprets markers that look like this: +.. code-block:: c + /* vim:set sw=8 noet */ Do not include any of these in source files. People have their own personal @@ -850,7 +958,8 @@ own custom mode, or may have some other magic method for making indentation work correctly. - Chapter 19: Inline assembly +19) Inline assembly +------------------- In architecture-specific code, you may need to use inline assembly to interface with CPU or platform functionality. Don't hesitate to do so when necessary. @@ -863,7 +972,7 @@ that inline assembly can use C parameters. Large, non-trivial assembly functions should go in .S files, with corresponding C prototypes defined in C header files. The C prototypes for assembly -functions should use "asmlinkage". +functions should use ``asmlinkage``. You may need to mark your asm statement as volatile, to prevent GCC from removing it if GCC doesn't notice any side effects. You don't always need to @@ -874,12 +983,15 @@ instructions, put each instruction on a separate line in a separate quoted string, and end each string except the last with \n\t to properly indent the next instruction in the assembly output: +.. code-block:: c + asm ("magic %reg1, #42\n\t" "more_magic %reg2, %reg3" : /* outputs */ : /* inputs */ : /* clobbers */); - Chapter 20: Conditional Compilation +20) Conditional Compilation +--------------------------- Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c files; doing so makes code harder to read and logic harder to follow. Instead, @@ -903,6 +1015,8 @@ unused, delete it.) Within code, where possible, use the IS_ENABLED macro to convert a Kconfig symbol into a C boolean expression, and use it in a normal C conditional: +.. code-block:: c + if (IS_ENABLED(CONFIG_SOMETHING)) { ... } @@ -918,12 +1032,15 @@ At the end of any non-trivial #if or #ifdef block (more than a few lines), place a comment after the #endif on the same line, noting the conditional expression used. For instance: +.. code-block:: c + #ifdef CONFIG_SOMETHING ... #endif /* CONFIG_SOMETHING */ - Appendix I: References +Appendix I) References +---------------------- The C Programming Language, Second Edition by Brian W. Kernighan and Dennis M. Ritchie. @@ -943,4 +1060,3 @@ language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ Kernel CodingStyle, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ - diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index 781024ef9050..979228bc9035 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -699,7 +699,7 @@ to use the dma_sync_*() interfaces. dma_addr_t mapping; mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); - if (dma_mapping_error(cp->dev, dma_handle)) { + if (dma_mapping_error(cp->dev, mapping)) { /* * reduce current DMA mapping usage, * delay and try again later or @@ -931,10 +931,8 @@ to "Closing". 1) Struct scatterlist requirements. - Don't invent the architecture specific struct scatterlist; just use - . You need to enable - CONFIG_NEED_SG_DMA_LENGTH if the architecture supports IOMMUs - (including software IOMMU). + You need to enable CONFIG_NEED_SG_DMA_LENGTH if the architecture + supports IOMMUs (including software IOMMU). 2) ARCH_DMA_MINALIGN diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index 1d26eeb6b5f6..6b20128fab8a 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -277,14 +277,26 @@ and parameters are provided to do partial page mapping, it is recommended that you never use these unless you really know what the cache width is. +dma_addr_t +dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size, + enum dma_data_direction dir, unsigned long attrs) + +void +dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size, + enum dma_data_direction dir, unsigned long attrs) + +API for mapping and unmapping for MMIO resources. All the notes and +warnings for the other mapping APIs apply here. The API should only be +used to map device MMIO resources, mapping of RAM is not permitted. + int dma_mapping_error(struct device *dev, dma_addr_t dma_addr) -In some circumstances dma_map_single() and dma_map_page() will fail to create -a mapping. A driver can check for these errors by testing the returned -DMA address with dma_mapping_error(). A non-zero return value means the mapping -could not be created and the driver should take appropriate action (e.g. -reduce current DMA mapping usage or delay and try again later). +In some circumstances dma_map_single(), dma_map_page() and dma_map_resource() +will fail to create a mapping. A driver can check for these errors by testing +the returned DMA address with dma_mapping_error(). A non-zero return value +means the mapping could not be created and the driver should take appropriate +action (e.g. reduce current DMA mapping usage or delay and try again later). int dma_map_sg(struct device *dev, struct scatterlist *sg, diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt index 2d455a5cf671..98bf7ac29aad 100644 --- a/Documentation/DMA-attributes.txt +++ b/Documentation/DMA-attributes.txt @@ -126,3 +126,20 @@ means that we won't try quite as hard to get them. NOTE: At the moment DMA_ATTR_ALLOC_SINGLE_PAGES is only implemented on ARM, though ARM64 patches will likely be posted soon. + +DMA_ATTR_NO_WARN +---------------- + +This tells the DMA-mapping subsystem to suppress allocation failure reports +(similarly to __GFP_NOWARN). + +On some architectures allocation failures are reported with error messages +to the system logs. Although this can help to identify and debug problems, +drivers which handle failures (eg, retry later) have no problems with them, +and can actually flood the system logs with error messages that aren't any +problem at all, depending on the implementation of the retry mechanism. + +So, this provides a way for drivers to avoid those error messages on calls +where allocation failures are not a problem, and shouldn't bother the logs. + +NOTE: At the moment DMA_ATTR_NO_WARN is only implemented on PowerPC. 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 @@ - - - - - The 802.11 subsystems – for kernel developers - - Explaining wireless 802.11 networking in the Linux kernel - - - - 2007-2009 - Johannes Berg - - - - - Johannes - Berg - -
johannes@sipsolutions.net
- - - - - - - 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. - - - - - - 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. - - - 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". - - - - - - The cfg80211 subsystem - - -!Pinclude/net/cfg80211.h Introduction - - - - Device registration -!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 - - - Actions and configuration -!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 - - - Scanning and BSS list handling -!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 - - - Utility functions -!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 - - - Data path helpers -!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 - - - Regulatory enforcement infrastructure -!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 - - - RFkill integration -!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 - - - Test mode -!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 - - - - - The mac80211 subsystem - -!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_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_vif - - - - 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 - - - Packet alignment -!Pnet/mac80211/rx.c Packet alignment - - - 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 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 - - - - - Frame filtering -!Pinclude/net/mac80211.h Frame filtering -!Finclude/net/mac80211.h ieee80211_filter_flags - - - - The mac80211 workqueue -!Pinclude/net/mac80211.h mac80211 workqueue -!Finclude/net/mac80211.h ieee80211_queue_work -!Finclude/net/mac80211.h ieee80211_queue_delayed_work - - - - - 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. - - - - - LED support - - 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. - -!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 - - - - 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_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 - - - - Powersave support -!Pinclude/net/mac80211.h Powersave support - - - - Beacon filter support -!Pinclude/net/mac80211.h Beacon filter support -!Finclude/net/mac80211.h ieee80211_beacon_loss - - - - Multiple queues and QoS support - TBD -!Finclude/net/mac80211.h ieee80211_tx_queue_params - - - - 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. - -
- support for powersaving clients -!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 -
- - - - 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. - -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces -!Finclude/net/mac80211.h ieee80211_iterate_active_interfaces_atomic - - - - Station handling - TODO -!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 - - - - Hardware scan offload - TBD -!Finclude/net/mac80211.h ieee80211_scan_completed - - - - Aggregation - - TX A-MPDU aggregation -!Pnet/mac80211/agg-tx.c TX A-MPDU aggregation -!Cnet/mac80211/agg-tx.c - - - RX A-MPDU aggregation -!Pnet/mac80211/agg-rx.c RX A-MPDU aggregation -!Cnet/mac80211/agg-rx.c -!Finclude/net/mac80211.h ieee80211_ampdu_mlme_action - - - - - Spatial Multiplexing Powersave (SMPS) -!Pinclude/net/mac80211.h Spatial multiplexing power save -!Finclude/net/mac80211.h ieee80211_request_smps -!Finclude/net/mac80211.h ieee80211_smps_mode - - - - - Rate control interface - - TBD - - This part of the book describes the rate control algorithm - interface and how it relates to mac80211 and drivers. - - - - Rate Control API - TBD -!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 - - - - - 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 - - - - - Aggregation -!Fnet/mac80211/sta_info.h sta_ampdu_mlme -!Fnet/mac80211/sta_info.h tid_ampdu_tx -!Fnet/mac80211/sta_info.h tid_ampdu_rx - - - - Synchronisation - TBD - Locking, lots of RCU - - - - 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 "") > $@ 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. @@ -822,18 +823,31 @@ kernel crypto API | Caller - 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: + + + + 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. + + + + + crypto_unregister_algs() tries to unregister all the given + transformations, continuing on error. It logs errors and + always returns zero. + + + + Single-Block Symmetric Ciphers [CIPHER] 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 @@ - - - - - - Linux Device Drivers - - - - 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. - - - - 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. - - - - 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 - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Driver Basics - Driver Entry and Exit points -!Iinclude/linux/init.h - - - Atomic and pointer manipulation -!Iarch/x86/include/asm/atomic.h - - - Delaying, scheduling, and timer routines -!Iinclude/linux/sched.h -!Ekernel/sched/core.c -!Ikernel/sched/cpupri.c -!Ikernel/sched/fair.c -!Iinclude/linux/completion.h -!Ekernel/time/timer.c - - Wait queues and Wake events -!Iinclude/linux/wait.h -!Ekernel/sched/wait.c - - High-resolution timers -!Iinclude/linux/ktime.h -!Iinclude/linux/hrtimer.h -!Ekernel/time/hrtimer.c - - Workqueues and Kevents -!Iinclude/linux/workqueue.h -!Ekernel/workqueue.c - - Internal Functions -!Ikernel/exit.c -!Ikernel/signal.c -!Iinclude/linux/kthread.h -!Ekernel/kthread.c - - - Kernel objects manipulation - -!Elib/kobject.c - - - Kernel utility functions -!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 - - - Device Resource Management -!Edrivers/base/devres.c - - - - - - Device drivers infrastructure - The Basic Device Driver-Model Structures -!Iinclude/linux/device.h - - Device Drivers Base -!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 - -!Edrivers/base/dd.c - -!Iinclude/linux/platform_device.h -!Edrivers/base/platform.c -!Edrivers/base/bus.c - - - Buffer Sharing and Synchronization - - 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. - - - This is used, for example, by drm "prime" multi-GPU support, but - is of course not limited to GPU use cases. - - - 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. - - dma-buf -!Edrivers/dma-buf/dma-buf.c -!Iinclude/linux/dma-buf.h - - reservation -!Pdrivers/dma-buf/reservation.c Reservation Object Overview -!Edrivers/dma-buf/reservation.c -!Iinclude/linux/reservation.h - - fence -!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 - - - Device Drivers DMA Management -!Edrivers/base/dma-coherent.c -!Edrivers/base/dma-mapping.c - - Device Drivers Power Management -!Edrivers/base/power/main.c - - Device Drivers ACPI Support - -!Edrivers/acpi/scan.c -!Idrivers/acpi/scan.c - - - Device drivers PnP support -!Idrivers/pnp/core.c - -!Edrivers/pnp/card.c -!Idrivers/pnp/driver.c -!Edrivers/pnp/manager.c -!Edrivers/pnp/support.c - - Userspace IO devices -!Edrivers/uio/uio.c -!Iinclude/linux/uio_driver.h - - - - - Parallel Port Devices -!Iinclude/linux/parport.h -!Edrivers/parport/ieee1284.c -!Edrivers/parport/share.c -!Idrivers/parport/daisy.c - - - - Message-based devices - Fusion message devices -!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 - - - - - Sound Devices -!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 - - - - - - 16x50 UART Driver -!Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250/8250_core.c - - - - Frame Buffer Library - - - 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. - - - - 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. - - - - 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. - - - - 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. - - - - 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. - - - Frame Buffer Memory -!Edrivers/video/fbdev/core/fbmem.c - - - Frame Buffer Colormap -!Edrivers/video/fbdev/core/fbcmap.c - - - Frame Buffer Video Mode Database -!Idrivers/video/fbdev/core/modedb.c -!Edrivers/video/fbdev/core/modedb.c - - Frame Buffer Macintosh Video Mode Database -!Edrivers/video/fbdev/macmodes.c - - Frame Buffer Fonts - - Refer to the file lib/fonts/fonts.c for more information. - - - - - - - Input Subsystem - Input core -!Iinclude/linux/input.h -!Edrivers/input/input.c -!Edrivers/input/ff-core.c -!Edrivers/input/ff-memless.c - - Multitouch Library -!Iinclude/linux/input/mt.h -!Edrivers/input/input-mt.c - - Polled input devices -!Iinclude/linux/input-polldev.h -!Edrivers/input/input-polldev.c - - Matrix keyboards/keypads -!Iinclude/linux/input/matrix_keypad.h - - Sparse keymap support -!Iinclude/linux/input/sparse-keymap.h -!Edrivers/input/sparse-keymap.c - - - - - Serial Peripheral Interface (SPI) - - 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. - - - 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.) - - - 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 - struct spi_master. - SPI devices are children of that master, represented as a - struct spi_device and manufactured from - struct spi_board_info descriptors which - are usually provided by board-specific initialization code. - A struct spi_driver is called a - "Protocol Driver", and is bound to a spi_device using normal - driver model calls. - - - The I/O model is a set of queued messages. Protocol drivers - submit one or more struct spi_message - objects, which are processed and completed asynchronously. - (There are synchronous wrappers, however.) Messages are - built from one or more struct spi_transfer - 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. - -!Iinclude/linux/spi/spi.h -!Fdrivers/spi/spi.c spi_register_board_info -!Edrivers/spi/spi.c - - - - I<superscript>2</superscript>C and SMBus Subsystem - - - I2C (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. - - - - 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 struct i2c_adapter representing - each I2C bus segment it manages. - On each I2C bus segment will be I2C devices represented by a - struct i2c_client. Those devices will - be bound to a struct i2c_driver, - 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. - - - - 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. - - -!Iinclude/linux/i2c.h -!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info -!Edrivers/i2c/i2c-core.c - - - - High Speed Synchronous Serial Interface (HSI) - - - 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. - - -!Iinclude/linux/hsi/hsi.h -!Edrivers/hsi/hsi_core.c - - - - Pulse-Width Modulation (PWM) - - Pulse-width modulation is a modulation technique primarily used to - control power supplied to electrical devices. - - - 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 struct pwm_chip. Providers are - expected to embed this structure in a driver-specific structure. This - structure contains fields that describe a particular chip. - - - A chip exposes one or more PWM signal sources, each of which exposed - as a struct pwm_device. Operations can be - performed on PWM devices to control the period, duty cycle, polarity - and active state of the signal. - - - Note that PWM devices are exclusive resources: they can always only be - used by one consumer at a time. - -!Iinclude/linux/pwm.h -!Edrivers/pwm/core.c - - - 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); get_user() / put_user() - include/asm/uaccess.h + include/linux/uaccess.h diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 1f345da28ec5..5f042349f987 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -1,5 +1,5 @@ HOWTO do Linux kernel development ---------------------------------- +================================= This is the be-all, end-all document on this topic. It contains instructions on how to become a Linux kernel developer and how to learn @@ -28,6 +28,7 @@ kernel development. Assembly (any architecture) is not required unless you plan to do low-level development for that architecture. Though they are not a good substitute for a solid C education and/or years of experience, the following books are good for, if anything, reference: + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] @@ -64,7 +65,8 @@ people on the mailing lists are not lawyers, and you should not rely on their statements on legal matters. For common questions and answers about the GPL, please see: - http://www.gnu.org/licenses/gpl-faq.html + + https://www.gnu.org/licenses/gpl-faq.html Documentation @@ -82,96 +84,118 @@ linux-api@vger.kernel.org. Here is a list of files that are in the kernel source tree that are required reading: + README This file gives a short background on the Linux kernel and describes what is necessary to do to configure and build the kernel. People who are new to the kernel should start here. - Documentation/Changes + :ref:`Documentation/Changes ` This file gives a list of the minimum levels of various software packages that are necessary to build and run the kernel successfully. - Documentation/CodingStyle + :ref:`Documentation/CodingStyle ` This describes the Linux kernel coding style, and some of the rationale behind it. All new code is expected to follow the guidelines in this document. Most maintainers will only accept patches if these rules are followed, and many people will only review code if it is in the proper style. - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` These files describe in explicit detail how to successfully create and send a patch, including (but not limited to): + - Email contents - Email format - Who to send it to + Following these rules will not guarantee success (as all patches are subject to scrutiny for content and style), but not following them will almost always prevent it. Other excellent descriptions of how to create patches properly are: + "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + :ref:`Documentation/stable_api_nonsense.txt ` This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like: + - Subsystem shim-layers (for compatibility?) - Driver portability between Operating Systems. - Mitigating rapid change within the kernel source tree (or preventing rapid change) + This document is crucial for understanding the Linux development philosophy and is very important for people moving to Linux from development on other Operating Systems. - Documentation/SecurityBugs + :ref:`Documentation/SecurityBugs ` If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue. - Documentation/ManagementStyle + :ref:`Documentation/ManagementStyle ` This document describes how Linux kernel maintainers operate and the shared ethos behind their methodologies. This is important reading for anyone new to kernel development (or anyone simply curious about it), as it resolves a lot of common misconceptions and confusion about the unique behavior of kernel maintainers. - Documentation/stable_kernel_rules.txt + :ref:`Documentation/stable_kernel_rules.txt ` This file describes the rules on how the stable kernel releases happen, and what to do if you want to get a change into one of these releases. - Documentation/kernel-docs.txt + :ref:`Documentation/kernel-docs.txt ` A list of external documentation that pertains to kernel development. Please consult this list if you do not find what you are looking for within the in-kernel documentation. - Documentation/applying-patches.txt + :ref:`Documentation/applying-patches.txt ` A good introduction describing exactly what a patch is and how to apply it to the different development branches of the kernel. The kernel also has a large number of documents that can be -automatically generated from the source code itself. This includes a +automatically generated from the source code itself or from +ReStructuredText markups (ReST), like this one. This includes a full description of the in-kernel API, and rules on how to handle -locking properly. The documents will be created in the -Documentation/DocBook/ directory and can be generated as PDF, -Postscript, HTML, and man pages by running: +locking properly. + +All such documents can be generated as PDF or HTML by running:: + make pdfdocs - make psdocs make htmldocs - make mandocs + respectively from the main kernel source directory. +The documents that uses ReST markup will be generated at Documentation/output. +They can also be generated on LaTeX and ePub formats with:: + + make latexdocs + make epubdocs + +Currently, there are some documents written on DocBook that are in +the process of conversion to ReST. Such documents will be created in the +Documentation/DocBook/ directory and can be generated also as +Postscript or man pages by running:: + + make psdocs + make mandocs Becoming A Kernel Developer --------------------------- If you do not know anything about Linux kernel development, you should look at the Linux KernelNewbies project: - http://kernelnewbies.org + + https://kernelnewbies.org + It consists of a helpful mailing list where you can ask almost any type of basic kernel development question (make sure to search the archives first, before asking something that has already been answered in the @@ -187,7 +211,9 @@ apply a patch. If you do not know where you want to start, but you want to look for some task to start doing to join into the kernel development community, go to the Linux Kernel Janitor's project: - http://kernelnewbies.org/KernelJanitors + + https://kernelnewbies.org/KernelJanitors + It is a great place to start. It describes a list of relatively simple problems that need to be cleaned up and fixed within the Linux kernel source tree. Working with the developers in charge of this project, you @@ -199,7 +225,8 @@ If you already have a chunk of code that you want to put into the kernel tree, but need some help getting it in the proper form, the kernel-mentors project was created to help you out with this. It is a mailing list, and can be found at: - http://selenic.com/mailman/listinfo/kernel-mentors + + https://selenic.com/mailman/listinfo/kernel-mentors Before making any actual modifications to the Linux kernel code, it is imperative to understand how the code in question works. For this @@ -209,6 +236,7 @@ tools. One such tool that is particularly recommended is the Linux Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at: + http://lxr.free-electrons.com/ @@ -218,6 +246,7 @@ The development process Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are: + - main 4.x kernel tree - 4.x.y -stable kernel tree - 4.x -git kernel patches @@ -227,14 +256,15 @@ branches. These different branches are: 4.x kernel tree ----------------- 4.x kernels are maintained by Linus Torvalds, and can be found on -kernel.org in the pub/linux/kernel/v4.x/ directory. Its development +https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development process is as follows: + - As soon as a new kernel is released a two weeks window is open, during this period of time maintainers can submit big diffs to Linus, usually the patches that have already been included in the -next kernel for a few weeks. The preferred way to submit big changes is using git (the kernel's source management tool, more information - can be found at http://git-scm.com/) but plain patches are also just + can be found at https://git-scm.com/) but plain patches are also just fine. - After two weeks a -rc1 kernel is released it is now possible to push only patches that do not include new features that could affect the @@ -253,9 +283,10 @@ process is as follows: It is worth mentioning what Andrew Morton wrote on the linux-kernel mailing list about kernel releases: - "Nobody knows when a kernel will be released, because it's + + *"Nobody knows when a kernel will be released, because it's released according to perceived bug status, not according to a - preconceived timeline." + preconceived timeline."* 4.x.y -stable kernel tree ------------------------- @@ -301,7 +332,7 @@ submission and other already ongoing work are avoided. Most of these repositories are git trees, but there are also other SCMs in use, or patch queues being published as quilt series. Addresses of these subsystem repositories are listed in the MAINTAINERS file. Many -of them can be browsed at http://git.kernel.org/. +of them can be browsed at https://git.kernel.org/. Before a proposed patch is committed to such a subsystem tree, it is subject to review which primarily happens on mailing lists (see the @@ -310,7 +341,7 @@ process is tracked with the tool patchwork. Patchwork offers a web interface which shows patch postings, any comments on a patch or revisions to it, and maintainers can mark patches as under review, accepted, or rejected. Most of these patchwork sites are listed at -http://patchwork.kernel.org/. +https://patchwork.kernel.org/. 4.x -next kernel tree for integration tests ------------------------------------------- @@ -318,7 +349,8 @@ Before updates from subsystem trees are merged into the mainline 4.x tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: - http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git This way, the -next kernel gives a summary outlook onto what will be expected to go into the mainline kernel at the next merge period. @@ -328,10 +360,11 @@ Adventurous testers are very welcome to runtime-test the -next kernel. Bug Reporting ------------- -bugzilla.kernel.org is where the Linux kernel developers track kernel +https://bugzilla.kernel.org is where the Linux kernel developers track kernel bugs. Users are encouraged to report all bugs that they find in this tool. For details on how to use the kernel bugzilla, please see: - http://bugzilla.kernel.org/page.cgi?id=faq.html + + https://bugzilla.kernel.org/page.cgi?id=faq.html The file REPORTING-BUGS in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind @@ -349,13 +382,14 @@ your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. -To work in the already reported bug reports, go to http://bugzilla.kernel.org. +To work in the already reported bug reports, go to https://bugzilla.kernel.org. If you want to be advised of the future bug reports, you can subscribe to the bugme-new mailing list (only new bug reports are mailed here) or to the bugme-janitor mailing list (every change in the bugzilla is mailed here) - http://lists.linux-foundation.org/mailman/listinfo/bugme-new - http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors @@ -365,10 +399,14 @@ Mailing lists As some of the above documents describe, the majority of the core kernel developers participate on the Linux Kernel Mailing list. Details on how to subscribe and unsubscribe from the list can be found at: + http://vger.kernel.org/vger-lists.html#linux-kernel + There are archives of the mailing list on the web in many different places. Use a search engine to find these archives. For example: + http://dir.gmane.org/gmane.linux.kernel + It is highly recommended that you search the archives about the topic you want to bring up, before you post it to the list. A lot of things already discussed in detail are only recorded at the mailing list @@ -381,11 +419,13 @@ groups. Many of the lists are hosted on kernel.org. Information on them can be found at: + http://vger.kernel.org/vger-lists.html Please remember to follow good behavioral habits when using the lists. Though a bit cheesy, the following URL has some simple guidelines for interacting with the list (or any list): + http://www.albion.com/netiquette/ If multiple people respond to your mail, the CC: list of recipients may @@ -400,13 +440,14 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. Kernel developers don't -want to deal with attachments or compressed patches; they may want -to comment on individual lines of your patch, which works only that way. -Make sure you use a mail program that does not mangle spaces and tab -characters. A good first test is to send the mail to yourself and try -to apply your own patch by yourself. If that doesn't work, get your -mail program fixed or change it until it works. +as stated in Documentation/SubmittingPatches. +Kernel developers don't want to deal with +attachments or compressed patches; they may want to comment on +individual lines of your patch, which works only that way. Make sure you +use a mail program that does not mangle spaces and tab characters. A +good first test is to send the mail to yourself and try to apply your +own patch by yourself. If that doesn't work, get your mail program fixed +or change it until it works. Above all, please remember to show respect to other subscribers. @@ -418,6 +459,7 @@ The goal of the kernel community is to provide the best possible kernel there is. When you submit a patch for acceptance, it will be reviewed on its technical merits and those alone. So, what should you be expecting? + - criticism - comments - requests for change @@ -432,6 +474,7 @@ If there are no responses to your posting, wait a few days and try again, sometimes things get lost in the huge volume. What should you not do? + - expect your patch to be accepted without question - become defensive - ignore comments @@ -445,8 +488,8 @@ Remember, being wrong is acceptable as long as you are willing to work toward a solution that is right. It is normal that the answers to your first patch might simply be a list -of a dozen things you should correct. This does _not_ imply that your -patch will not be accepted, and it is _not_ meant against you +of a dozen things you should correct. This does **not** imply that your +patch will not be accepted, and it is **not** meant against you personally. Simply correct all issues raised against your patch and resend it. @@ -457,7 +500,9 @@ Differences between the kernel community and corporate structures The kernel community works differently than most traditional corporate development environments. Here are a list of things that you can try to do to avoid problems: + Good things to say regarding your proposed changes: + - "This solves multiple problems." - "This deletes 2000 lines of code." - "Here is a patch that explains what I am trying to describe." @@ -466,6 +511,7 @@ do to avoid problems: - "This increases performance on typical machines..." Bad things you should avoid saying: + - "We did it this way in AIX/ptx/Solaris, so therefore it must be good..." - "I've being doing this for 20 years, so..." @@ -527,17 +573,18 @@ The reasons for breaking things up are the following: and simplify (or simply re-order) patches before submitting them. Here is an analogy from kernel developer Al Viro: - "Think of a teacher grading homework from a math student. The + + *"Think of a teacher grading homework from a math student. The teacher does not want to see the student's trials and errors before they came up with the solution. They want to see the cleanest, most elegant answer. A good student knows this, and would never submit her intermediate work before the final - solution." + solution.* - The same is true of kernel development. The maintainers and + *The same is true of kernel development. The maintainers and reviewers do not want to see the thought process behind the solution to the problem one is solving. They want to see a - simple and elegant solution." + simple and elegant solution."* It may be challenging to keep the balance between presenting an elegant solution and working together with the community and discussing your @@ -565,6 +612,7 @@ When sending in your patches, pay special attention to what you say in the text in your email. This information will become the ChangeLog information for the patch, and will be preserved for everyone to see for all time. It should describe the patch completely, containing: + - why the change is necessary - the overall design approach in the patch - implementation details @@ -572,12 +620,11 @@ all time. It should describe the patch completely, containing: For more details on what this should all look like, please see the ChangeLog section of the document: + "The Perfect Patch" http://www.ozlabs.org/~akpm/stuff/tpp.txt - - All of these things are sometimes very hard to do. It can take years to perfect these practices (if at all). It's a continuous process of improvement that requires a lot of patience and determination. But @@ -588,8 +635,9 @@ start exactly where you are now. ---------- + Thanks to Paolo Ciarrocchi who allowed the "Development Process" -(http://lwn.net/Articles/94386/) section +(https://lwn.net/Articles/94386/) section to be based on text he had written, and to Randy Dunlap and Gerrit Huizenga for some of the list of things you should and should not say. Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, diff --git a/Documentation/Makefile b/Documentation/Makefile index de955e151af8..c2a469112c37 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -1,3 +1 @@ -subdir-y := accounting auxdisplay blackfin \ - filesystems filesystems ia64 laptops mic misc-devices \ - networking pcmcia prctl ptp timers vDSO watchdog +subdir-y := diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 857f1e273418..92deea30b183 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -5,6 +5,9 @@ # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS = +SPHINXDIRS = . +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output @@ -25,38 +28,62 @@ else ifneq ($(DOCBOOKS),) else # HAVE_SPHINX -# User-friendly check for rst2pdf -HAVE_RST2PDF := $(shell if python -c "import rst2pdf" >/dev/null 2>&1; then echo 1; else echo 0; fi) +# User-friendly check for pdflatex +HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi) # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter KERNELDOC = $(srctree)/scripts/kernel-doc KERNELDOC_CONF = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC) -ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(BUILDDIR)/.doctrees $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) -c $(srctree)/$(src) $(SPHINXOPTS) $(srctree)/$(src) +ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -quiet_cmd_sphinx = SPHINX $@ - cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2 +# commands; the 'cmd' from scripts/Kbuild.include is not *loopable* +loop_cmd = $(echo-cmd) $(cmd_$(1)) + +# $2 sphinx builder e.g. "html" +# $3 name of the build subfolder / e.g. "media", used as: +# * dest folder relative to $(BUILDDIR) and +# * cache folder relative to $(BUILDDIR)/.doctrees +# $4 dest subfolder e.g. "man" for man pages at media/man +# $5 reST source folder relative to $(srctree)/$(src), +# e.g. "media" for the linux-tv book-set at ./Documentation/media + +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ + BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(SPHINXBUILD) \ + -b $2 \ + -c $(abspath $(srctree)/$(src)) \ + -d $(abspath $(BUILDDIR)/.doctrees/$3) \ + -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ + $(ALLSPHINXOPTS) \ + $(abspath $(srctree)/$(src)/$5) \ + $(abspath $(BUILDDIR)/$3/$4); htmldocs: - $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@ - $(call cmd,sphinx,html) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) -pdfdocs: -ifeq ($(HAVE_RST2PDF),0) - $(warning The Python 'rst2pdf' module was not found. Make sure you have the module installed to produce PDF output.) +latexdocs: +ifeq ($(HAVE_PDFLATEX),0) + $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." -else # HAVE_RST2PDF - $(call cmd,sphinx,pdf) -endif # HAVE_RST2PDF +else # HAVE_PDFLATEX + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) +endif # HAVE_PDFLATEX + +pdfdocs: latexdocs +ifneq ($(HAVE_PDFLATEX),0) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) +endif # HAVE_PDFLATEX epubdocs: - $(call cmd,sphinx,epub) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - $(call cmd,sphinx,xml) + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) # no-ops for the Sphinx toolchain sgmldocs: @@ -72,7 +99,14 @@ endif # HAVE_SPHINX dochelp: @echo ' Linux kernel internal documentation in different formats (Sphinx):' @echo ' htmldocs - HTML' + @echo ' latexdocs - LaTeX' @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' @echo ' cleandocs - clean all generated files' + @echo + @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' + @echo ' valid values for SPHINXDIRS are: $(_SPHINXDIRS)' + @echo + @echo ' make SPHINX_CONF={conf-file} [target] use *additional* sphinx-build' + @echo ' configuration. This is e.g. useful to build with nit-picking config.' diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle index a211ee8d8b44..dea2e66c9a10 100644 --- a/Documentation/ManagementStyle +++ b/Documentation/ManagementStyle @@ -1,10 +1,12 @@ +.. _managementstyle: - Linux kernel management style +Linux kernel management style +============================= This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to mirror the CodingStyle document to some degree, and mainly written to -avoid answering (*) the same (or similar) questions over and over again. +avoid answering [#f1]_ the same (or similar) questions over and over again. Management style is very personal and much harder to quantify than simple coding style rules, so this document may or may not have anything @@ -14,50 +16,52 @@ might not actually be true. You'll have to decide for yourself. Btw, when talking about "kernel manager", it's all about the technical lead persons, not the people who do traditional management inside companies. If you sign purchase orders or you have any clue about the -budget of your group, you're almost certainly not a kernel manager. -These suggestions may or may not apply to you. +budget of your group, you're almost certainly not a kernel manager. +These suggestions may or may not apply to you. First off, I'd suggest buying "Seven Habits of Highly Effective -People", and NOT read it. Burn it, it's a great symbolic gesture. +People", and NOT read it. Burn it, it's a great symbolic gesture. -(*) This document does so not so much by answering the question, but by -making it painfully obvious to the questioner that we don't have a clue -to what the answer is. +.. [#f1] This document does so not so much by answering the question, but by + making it painfully obvious to the questioner that we don't have a clue + to what the answer is. Anyway, here goes: +.. _decisions: - Chapter 1: Decisions +1) Decisions +------------ Everybody thinks managers make decisions, and that decision-making is important. The bigger and more painful the decision, the bigger the manager must be to make it. That's very deep and obvious, but it's not -actually true. +actually true. -The name of the game is to _avoid_ having to make a decision. In +The name of the game is to **avoid** having to make a decision. In particular, if somebody tells you "choose (a) or (b), we really need you to decide on this", you're in trouble as a manager. The people you manage had better know the details better than you, so if they come to you for a technical decision, you're screwed. You're clearly not -competent to make that decision for them. +competent to make that decision for them. (Corollary:if the people you manage don't know the details better than -you, you're also screwed, although for a totally different reason. -Namely that you are in the wrong job, and that _they_ should be managing -your brilliance instead). +you, you're also screwed, although for a totally different reason. +Namely that you are in the wrong job, and that **they** should be managing +your brilliance instead). -So the name of the game is to _avoid_ decisions, at least the big and +So the name of the game is to **avoid** decisions, at least the big and painful ones. Making small and non-consequential decisions is fine, and makes you look like you know what you're doing, so what a kernel manager needs to do is to turn the big and painful ones into small things where -nobody really cares. +nobody really cares. It helps to realize that the key difference between a big decision and a small one is whether you can fix your decision afterwards. Any decision can be made small by just always making sure that if you were wrong (and -you _will_ be wrong), you can always undo the damage later by +you **will** be wrong), you can always undo the damage later by backtracking. Suddenly, you get to be doubly managerial for making -_two_ inconsequential decisions - the wrong one _and_ the right one. +**two** inconsequential decisions - the wrong one **and** the right one. And people will even see that as true leadership (*cough* bullshit *cough*). @@ -65,10 +69,10 @@ And people will even see that as true leadership (*cough* bullshit Thus the key to avoiding big decisions becomes to just avoiding to do things that can't be undone. Don't get ushered into a corner from which you cannot escape. A cornered rat may be dangerous - a cornered manager -is just pitiful. +is just pitiful. It turns out that since nobody would be stupid enough to ever really let -a kernel manager have huge fiscal responsibility _anyway_, it's usually +a kernel manager have huge fiscal responsibility **anyway**, it's usually fairly easy to backtrack. Since you're not going to be able to waste huge amounts of money that you might not be able to repay, the only thing you can backtrack on is a technical decision, and there @@ -76,113 +80,118 @@ back-tracking is very easy: just tell everybody that you were an incompetent nincompoop, say you're sorry, and undo all the worthless work you had people work on for the last year. Suddenly the decision you made a year ago wasn't a big decision after all, since it could be -easily undone. +easily undone. It turns out that some people have trouble with this approach, for two reasons: + - admitting you were an idiot is harder than it looks. We all like to maintain appearances, and coming out in public to say that you were - wrong is sometimes very hard indeed. + wrong is sometimes very hard indeed. - having somebody tell you that what you worked on for the last year wasn't worthwhile after all can be hard on the poor lowly engineers - too, and while the actual _work_ was easy enough to undo by just + too, and while the actual **work** was easy enough to undo by just deleting it, you may have irrevocably lost the trust of that engineer. And remember: "irrevocable" was what we tried to avoid in the first place, and your decision ended up being a big one after - all. + all. Happily, both of these reasons can be mitigated effectively by just admitting up-front that you don't have a friggin' clue, and telling people ahead of the fact that your decision is purely preliminary, and might be the wrong thing. You should always reserve the right to change -your mind, and make people very _aware_ of that. And it's much easier -to admit that you are stupid when you haven't _yet_ done the really +your mind, and make people very **aware** of that. And it's much easier +to admit that you are stupid when you haven't **yet** done the really stupid thing. Then, when it really does turn out to be stupid, people just roll their -eyes and say "Oops, he did it again". +eyes and say "Oops, he did it again". This preemptive admission of incompetence might also make the people who actually do the work also think twice about whether it's worth doing or -not. After all, if _they_ aren't certain whether it's a good idea, you +not. After all, if **they** aren't certain whether it's a good idea, you sure as hell shouldn't encourage them by promising them that what they work on will be included. Make them at least think twice before they -embark on a big endeavor. +embark on a big endeavor. Remember: they'd better know more about the details than you do, and they usually already think they have the answer to everything. The best thing you can do as a manager is not to instill confidence, but rather a -healthy dose of critical thinking on what they do. +healthy dose of critical thinking on what they do. Btw, another way to avoid a decision is to plaintively just whine "can't we just do both?" and look pitiful. Trust me, it works. If it's not clear which approach is better, they'll eventually figure it out. The answer may end up being that both teams get so frustrated by the -situation that they just give up. +situation that they just give up. That may sound like a failure, but it's usually a sign that there was something wrong with both projects, and the reason the people involved couldn't decide was that they were both wrong. You end up coming up smelling like roses, and you avoided yet another decision that you could -have screwed up on. +have screwed up on. - Chapter 2: People +2) People +--------- Most people are idiots, and being a manager means you'll have to deal -with it, and perhaps more importantly, that _they_ have to deal with -_you_. +with it, and perhaps more importantly, that **they** have to deal with +**you**. It turns out that while it's easy to undo technical mistakes, it's not as easy to undo personality disorders. You just have to live with -theirs - and yours. +theirs - and yours. However, in order to prepare yourself as a kernel manager, it's best to remember not to burn any bridges, bomb any innocent villagers, or alienate too many kernel developers. It turns out that alienating people is fairly easy, and un-alienating them is hard. Thus "alienating" immediately falls under the heading of "not reversible", and becomes a -no-no according to Chapter 1. +no-no according to :ref:`decisions`. There's just a few simple rules here: + (1) don't call people d*ckheads (at least not in public) (2) learn how to apologize when you forgot rule (1) The problem with #1 is that it's very easy to do, since you can say -"you're a d*ckhead" in millions of different ways (*), sometimes without +"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without even realizing it, and almost always with a white-hot conviction that -you are right. +you are right. And the more convinced you are that you are right (and let's face it, -you can call just about _anybody_ a d*ckhead, and you often _will_ be -right), the harder it ends up being to apologize afterwards. +you can call just about **anybody** a d*ckhead, and you often **will** be +right), the harder it ends up being to apologize afterwards. To solve this problem, you really only have two options: + - get really good at apologies - spread the "love" out so evenly that nobody really ends up feeling like they get unfairly targeted. Make it inventive enough, and they - might even be amused. + might even be amused. The option of being unfailingly polite really doesn't exist. Nobody will trust somebody who is so clearly hiding his true character. -(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite -frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't -scan nearly as well. But I'm sure he thought about it. +.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite + frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't + scan nearly as well. But I'm sure he thought about it. - Chapter 3: People II - the Good Kind +3) People II - the Good Kind +---------------------------- While it turns out that most people are idiots, the corollary to that is sadly that you are one too, and that while we can all bask in the secure knowledge that we're better than the average person (let's face it, nobody ever believes that they're average or below-average), we should also admit that we're not the sharpest knife around, and there will be -other people that are less of an idiot than you are. +other people that are less of an idiot than you are. -Some people react badly to smart people. Others take advantage of them. +Some people react badly to smart people. Others take advantage of them. -Make sure that you, as a kernel maintainer, are in the second group. +Make sure that you, as a kernel maintainer, are in the second group. Suck up to them, because they are the people who will make your job easier. In particular, they'll be able to make your decisions for you, which is what the game is all about. @@ -191,7 +200,7 @@ So when you find somebody smarter than you are, just coast along. Your management responsibilities largely become ones of saying "Sounds like a good idea - go wild", or "That sounds good, but what about xxx?". The second version in particular is a great way to either learn something -new about "xxx" or seem _extra_ managerial by pointing out something the +new about "xxx" or seem **extra** managerial by pointing out something the smarter person hadn't thought about. In either case, you win. One thing to look out for is to realize that greatness in one area does @@ -199,47 +208,49 @@ not necessarily translate to other areas. So you might prod people in specific directions, but let's face it, they might be good at what they do, and suck at everything else. The good news is that people tend to naturally gravitate back to what they are good at, so it's not like you -are doing something irreversible when you _do_ prod them in some +are doing something irreversible when you **do** prod them in some direction, just don't push too hard. - Chapter 4: Placing blame +4) Placing blame +---------------- Things will go wrong, and people want somebody to blame. Tag, you're it. It's not actually that hard to accept the blame, especially if people -kind of realize that it wasn't _all_ your fault. Which brings us to the +kind of realize that it wasn't **all** your fault. Which brings us to the best way of taking the blame: do it for another guy. You'll feel good for taking the fall, he'll feel good about not getting blamed, and the guy who lost his whole 36GB porn-collection because of your incompetence will grudgingly admit that you at least didn't try to weasel out of it. Then make the developer who really screwed up (if you can find him) know -_in_private_ that he screwed up. Not just so he can avoid it in the +**in_private** that he screwed up. Not just so he can avoid it in the future, but so that he knows he owes you one. And, perhaps even more importantly, he's also likely the person who can fix it. Because, let's -face it, it sure ain't you. +face it, it sure ain't you. -Taking the blame is also why you get to be manager in the first place. +Taking the blame is also why you get to be manager in the first place. It's part of what makes people trust you, and allow you the potential glory, because you're the one who gets to say "I screwed up". And if you've followed the previous rules, you'll be pretty good at saying that -by now. +by now. - Chapter 5: Things to avoid +5) Things to avoid +------------------ There's one thing people hate even more than being called "d*ckhead", and that is being called a "d*ckhead" in a sanctimonious voice. The first you can apologize for, the second one you won't really get the chance. They likely will no longer be listening even if you otherwise -do a good job. +do a good job. We all think we're better than anybody else, which means that when -somebody else puts on airs, it _really_ rubs us the wrong way. You may +somebody else puts on airs, it **really** rubs us the wrong way. You may be morally and intellectually superior to everybody around you, but -don't try to make it too obvious unless you really _intend_ to irritate -somebody (*). +don't try to make it too obvious unless you really **intend** to irritate +somebody [#f3]_. Similarly, don't be too polite or subtle about things. Politeness easily ends up going overboard and hiding the problem, and as they say, "On the @@ -251,15 +262,16 @@ Some humor can help pad both the bluntness and the moralizing. Going overboard to the point of being ridiculous can drive a point home without making it painful to the recipient, who just thinks you're being silly. It can thus help get through the personal mental block we all -have about criticism. +have about criticism. -(*) Hint: internet newsgroups that are not directly related to your work -are great ways to take out your frustrations at other people. Write -insulting posts with a sneer just to get into a good flame every once in -a while, and you'll feel cleansed. Just don't crap too close to home. +.. [#f3] Hint: internet newsgroups that are not directly related to your work + are great ways to take out your frustrations at other people. Write + insulting posts with a sneer just to get into a good flame every once in + a while, and you'll feel cleansed. Just don't crap too close to home. - Chapter 6: Why me? +6) Why me? +---------- Since your main responsibility seems to be to take the blame for other peoples mistakes, and make it painfully obvious to everybody else that @@ -268,9 +280,9 @@ first place? First off, while you may or may not get screaming teenage girls (or boys, let's not be judgmental or sexist here) knocking on your dressing -room door, you _will_ get an immense feeling of personal accomplishment +room door, you **will** get an immense feeling of personal accomplishment for being "in charge". Never mind the fact that you're really leading by trying to keep up with everybody else and running after them as fast -as you can. Everybody will still think you're the person in charge. +as you can. Everybody will still think you're the person in charge. It's a great job if you can hack it. diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt index b4987c0bcb20..ea8cafba255c 100644 --- a/Documentation/PCI/pcieaer-howto.txt +++ b/Documentation/PCI/pcieaer-howto.txt @@ -49,25 +49,17 @@ depends on CONFIG_PCIEPORTBUS, so pls. set CONFIG_PCIEPORTBUS=y and CONFIG_PCIEAER = y. 2.2 Load PCI Express AER Root Driver -There is a case where a system has AER support in BIOS. Enabling the AER -Root driver and having AER support in BIOS may result unpredictable -behavior. To avoid this conflict, a successful load of the AER Root driver -requires ACPI _OSC support in the BIOS to allow the AER Root driver to -request for native control of AER. See the PCI FW 3.0 Specification for -details regarding OSC usage. Currently, lots of firmwares don't provide -_OSC support while they use PCI Express. To support such firmwares, -forceload, a parameter of type bool, could enable AER to continue to -be initiated although firmwares have no _OSC support. To enable the -walkaround, pls. add aerdriver.forceload=y to kernel boot parameter line -when booting kernel. Note that forceload=n by default. - -nosourceid, another parameter of type bool, can be used when broken -hardware (mostly chipsets) has root ports that cannot obtain the reporting -source ID. nosourceid=n by default. + +Some systems have AER support in firmware. Enabling Linux AER support at +the same time the firmware handles AER may result in unpredictable +behavior. Therefore, Linux does not handle AER events unless the firmware +grants AER control to the OS via the ACPI _OSC method. See the PCI FW 3.0 +Specification for details regarding _OSC usage. 2.3 AER error output -When a PCI-E AER error is captured, an error message will be outputted to -console. If it's a correctable error, it is outputted as a warning. + +When a PCIe AER error is captured, an error message will be output to +console. If it's a correctable error, it is output as a warning. Otherwise, it is printed as an error. So users could choose different log level to filter out correctable error messages. diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html index ece410f40436..a4d3838130e4 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.html +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -2493,6 +2493,28 @@ or some future “lazy” variant of call_rcu() that might one day be created for energy-efficiency purposes. +

+That said, there are limits. +RCU requires that the rcu_head structure be aligned to a +two-byte boundary, and passing a misaligned rcu_head +structure to one of the call_rcu() family of functions +will result in a splat. +It is therefore necessary to exercise caution when packing +structures containing fields of type rcu_head. +Why not a four-byte or even eight-byte alignment requirement? +Because the m68k architecture provides only two-byte alignment, +and thus acts as alignment's least common denominator. + +

+The reason for reserving the bottom bit of pointers to +rcu_head structures is to leave the door open to +“lazy” callbacks whose invocations can safely be deferred. +Deferring invocation could potentially have energy-efficiency +benefits, but only if the rate of non-lazy callbacks decreases +significantly for some important workload. +In the meantime, reserving the bottom bit keeps this option open +in case it one day becomes useful. +

Performance, Scalability, Response Time, and Reliability

diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.txt index bf9061142827..238e9f61352f 100644 --- a/Documentation/RCU/lockdep-splat.txt +++ b/Documentation/RCU/lockdep-splat.txt @@ -57,7 +57,7 @@ Call Trace: [] kernel_thread_helper+0x4/0x10 [] ? finish_task_switch+0x80/0x110 [] ? retint_restore_args+0xe/0xe - [] ? __init_kthread_worker+0x70/0x70 + [] ? __kthread_init_worker+0x70/0x70 [] ? gs_change+0xb/0xb Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows: diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt index 118e7c176ce7..278f6a9383b6 100644 --- a/Documentation/RCU/torture.txt +++ b/Documentation/RCU/torture.txt @@ -10,21 +10,6 @@ status messages via printk(), which can be examined via the dmesg command (perhaps grepping for "torture"). The test is started when the module is loaded, and stops when the module is unloaded. -CONFIG_RCU_TORTURE_TEST_RUNNABLE - -It is also possible to specify CONFIG_RCU_TORTURE_TEST=y, which will -result in the tests being loaded into the base kernel. In this case, -the CONFIG_RCU_TORTURE_TEST_RUNNABLE config option is used to specify -whether the RCU torture tests are to be started immediately during -boot or whether the /proc/sys/kernel/rcutorture_runnable file is used -to enable them. This /proc file can be used to repeatedly pause and -restart the tests, regardless of the initial state specified by the -CONFIG_RCU_TORTURE_TEST_RUNNABLE config option. - -You will normally -not- want to start the RCU torture tests during boot -(and thus the default is CONFIG_RCU_TORTURE_TEST_RUNNABLE=n), but doing -this can sometimes be useful in finding boot-time bugs. - MODULE PARAMETERS diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs index a660d494c8ed..342d769834f6 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/SecurityBugs @@ -1,9 +1,15 @@ +.. _securitybugs: + +Security bugs +============= + Linux kernel developers take security very seriously. As such, we'd like to know when a security bug is found so that it can be fixed and disclosed as quickly as possible. Please report security bugs to the Linux kernel security team. 1) Contact +---------- The Linux kernel security team can be contacted by email at . This is a private list of security officers @@ -18,6 +24,7 @@ Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. 2) Disclosure +------------- The goal of the Linux kernel security team is to work with the bug submitter to bug resolution as well as disclosure. We prefer @@ -33,6 +40,7 @@ to a few weeks. As a basic default policy, we expect report date to disclosure date to be on the order of 7 days. 3) Non-disclosure agreements +---------------------------- The Linux kernel security team is not a formal body and therefore unable to enter any non-disclosure agreements. diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist index 2b7e32dfe00d..894289b22b15 100644 --- a/Documentation/SubmitChecklist +++ b/Documentation/SubmitChecklist @@ -1,109 +1,120 @@ +.. _submitchecklist: + Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -Documentation/SubmittingPatches and elsewhere regarding submitting Linux -kernel patches. +:ref:`Documentation/SubmittingPatches ` +and elsewhere regarding submitting Linux kernel patches. -1: If you use a facility then #include the file that defines/declares +1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2: Builds cleanly with applicable or modified CONFIG options =y, =m, and - =n. No gcc warnings/errors, no linker warnings/errors. +2) Builds cleanly: + + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. -2b: Passes allnoconfig, allmodconfig + b) Passes ``allnoconfig``, ``allmodconfig`` -2c: Builds successfully when using O=builddir + c) Builds successfully when using ``O=builddir`` -3: Builds on multiple CPU architectures by using local cross-compile tools +3) Builds on multiple CPU architectures by using local cross-compile tools or some other build farm. -4: ppc64 is a good architecture for cross-compilation checking because it - tends to use `unsigned long' for 64-bit quantities. +4) ppc64 is a good architecture for cross-compilation checking because it + tends to use ``unsigned long`` for 64-bit quantities. -5: Check your patch for general style as detailed in - Documentation/CodingStyle. Check for trivial violations with the - patch style checker prior to submission (scripts/checkpatch.pl). +5) Check your patch for general style as detailed in + :ref:`Documentation/CodingStyle `. + Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in your patch. -6: Any new or modified CONFIG options don't muck up the config menu. +6) Any new or modified ``CONFIG`` options don't muck up the config menu. -7: All new Kconfig options have help text. +7) All new ``Kconfig`` options have help text. -8: Has been carefully reviewed with respect to relevant Kconfig +8) Has been carefully reviewed with respect to relevant ``Kconfig`` combinations. This is very hard to get right with testing -- brainpower pays off here. -9: Check cleanly with sparse. +9) Check cleanly with sparse. + +10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems + that they find. + + .. note:: -10: Use 'make checkstack' and 'make namespacecheck' and fix any problems - that they find. Note: checkstack does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. + ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. -11: Include kernel-doc to document global kernel APIs. (Not required for - static functions, but OK there also.) Use 'make htmldocs' or 'make - mandocs' to check the kernel-doc and fix any issues. +11) Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) Use + ``make htmldocs`` or ``make pdfdocs`` to check the + :ref:`kernel-doc ` and fix any issues. -12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, - CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, - CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU - and CONFIG_DEBUG_OBJECTS_RCU_HEAD all simultaneously enabled. +12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. -13: Has been build- and runtime tested with and without CONFIG_SMP and - CONFIG_PREEMPT. +13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` -14: If the patch affects IO/Disk, etc: has been tested with and without - CONFIG_LBDAF. +14) If the patch affects IO/Disk, etc: has been tested with and without + ``CONFIG_LBDAF.`` -15: All codepaths have been exercised with all lockdep features enabled. +15) All codepaths have been exercised with all lockdep features enabled. -16: All new /proc entries are documented under Documentation/ +16) All new ``/proc`` entries are documented under ``Documentation/`` -17: All new kernel boot parameters are documented in - Documentation/kernel-parameters.txt. +17) All new kernel boot parameters are documented in + ``Documentation/kernel-parameters.txt``. -18: All new module parameters are documented with MODULE_PARM_DESC() +18) All new module parameters are documented with ``MODULE_PARM_DESC()`` -19: All new userspace interfaces are documented in Documentation/ABI/. - See Documentation/ABI/README for more information. +19) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. -20: Check that it all passes `make headers_check'. +20) Check that it all passes ``make headers_check``. -21: Has been checked with injection of at least slab and page-allocation - failures. See Documentation/fault-injection/. +21) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. If the new code is substantial, addition of subsystem-specific fault injection might be appropriate. -22: Newly-added code has been compiled with `gcc -W' (use "make - EXTRA_CFLAGS=-W"). This will generate lots of noise, but is good for - finding bugs like "warning: comparison between signed and unsigned". +22) Newly-added code has been compiled with ``gcc -W`` (use + ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". -23: Tested after it has been merged into the -mm patchset to make sure +23) Tested after it has been merged into the -mm patchset to make sure that it still works with all of the other queued patches and various changes in the VM, VFS, and other subsystems. -24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the - source code that explains the logic of what they are doing and why. +24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. -25: If any ioctl's are added by the patch, then also update - Documentation/ioctl/ioctl-number.txt. +25) If any ioctl's are added by the patch, then also update + ``Documentation/ioctl/ioctl-number.txt``. -26: If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following kconfig symbols, - then test multiple builds with the related kconfig symbols disabled - and/or =m (if that option is available) [not all of these at the +26) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the same time, just various/random combinations of them]: - CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, - CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, - CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y) + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers index 31d372609ac0..252b77a23fad 100644 --- a/Documentation/SubmittingDrivers +++ b/Documentation/SubmittingDrivers @@ -1,5 +1,7 @@ +.. _submittingdrivers: + Submitting Drivers For The Linux Kernel ---------------------------------------- +======================================= This document is intended to explain how to submit device drivers to the various kernel trees. Note that if you are interested in video card drivers @@ -38,42 +40,48 @@ Linux 2.4: maintainer does not respond or you cannot find the appropriate maintainer then please contact Willy Tarreau . -Linux 2.6: +Linux 2.6 and upper: The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6 + to track changes in API's. The final contact point for Linux 2.6+ submissions is Andrew Morton. What Criteria Determine Acceptance ---------------------------------- -Licensing: The code must be released to us under the +Licensing: + The code must be released to us under the GNU General Public License. We don't insist on any kind of exclusive GPL licensing, and if you wish the driver to be useful to other communities such as BSD you may well wish to release under multiple licenses. See accepted licenses at include/linux/module.h -Copyright: The copyright owner must agree to use of GPL. +Copyright: + The copyright owner must agree to use of GPL. It's best if the submitter and copyright owner are the same person/entity. If not, the name of the person/entity authorizing use of GPL should be listed in case it's necessary to verify the will of the copyright owner. -Interfaces: If your driver uses existing interfaces and behaves like +Interfaces: + If your driver uses existing interfaces and behaves like other drivers in the same class it will be much more likely to be accepted than if it invents gratuitous new ones. If you need to implement a common API over Linux and NT drivers do it in userspace. -Code: Please use the Linux style of code formatting as documented - in Documentation/CodingStyle. If you have sections of code +Code: + Please use the Linux style of code formatting as documented + in :ref:`Documentation/CodingStyle `. + If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to maintain them just once separate them out nicely and note this fact. -Portability: Pointers are not always 32bits, not all computers are little +Portability: + Pointers are not always 32bits, not all computers are little endian, people do not all have floating point and you shouldn't use inline x86 assembler in your driver without careful thought. Pure x86 drivers generally are not popular. @@ -81,12 +89,14 @@ Portability: Pointers are not always 32bits, not all computers are little but it is easy to make sure the code can easily be made portable. -Clarity: It helps if anyone can see how to fix the driver. It helps +Clarity: + It helps if anyone can see how to fix the driver. It helps you because you get patches not bug reports. If you submit a driver that intentionally obfuscates how the hardware works it will go in the bitbucket. -PM support: Since Linux is used on many portable and desktop systems, your +PM support: + Since Linux is used on many portable and desktop systems, your driver is likely to be used on such a system and therefore it should support basic power management by implementing, if necessary, the .suspend and .resume methods used during the @@ -101,7 +111,8 @@ PM support: Since Linux is used on many portable and desktop systems, your complete overview of the power management issues related to drivers see Documentation/power/devices.txt . -Control: In general if there is active maintenance of a driver by +Control: + In general if there is active maintenance of a driver by the author then patches will be redirected to them unless they are totally obvious and without need of checking. If you want to be the contact and update point for the @@ -111,13 +122,15 @@ Control: In general if there is active maintenance of a driver by What Criteria Do Not Determine Acceptance ----------------------------------------- -Vendor: Being the hardware vendor and maintaining the driver is +Vendor: + Being the hardware vendor and maintaining the driver is often a good thing. If there is a stable working driver from other people already in the tree don't expect 'we are the vendor' to get your driver chosen. Ideally work with the existing driver author to build a single perfect driver. -Author: It doesn't matter if a large Linux company wrote the driver, +Author: + It doesn't matter if a large Linux company wrote the driver, or you did. Nobody has any special access to the kernel tree. Anyone who tells you otherwise isn't telling the whole story. @@ -127,8 +140,10 @@ Resources --------- Linux kernel master tree: - ftp.??.kernel.org:/pub/linux/kernel/... - ?? == your country code, such as "us", "uk", "fr", etc. + ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... + + where *country_code* == your country code, such as + **us**, **uk**, **fr**, etc. http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git @@ -141,14 +156,19 @@ Linux Device Drivers, Third Edition (covers 2.6.10): LWN.net: Weekly summary of kernel development activity - http://lwn.net/ + 2.6 API changes: + http://lwn.net/Articles/2.6-kernel-api/ + Porting drivers from prior kernels to 2.6: + http://lwn.net/Articles/driver-porting/ KernelNewbies: Documentation and assistance for new kernel programmers - http://kernelnewbies.org/ + + http://kernelnewbies.org/ Linux USB project: http://www.linux-usb.org/ diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 8c79f1d53731..36f1dedc944c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -1,9 +1,7 @@ +.. _submittingpatches: - How to Get Your Change Into the Linux Kernel - or - Care And Operation Of Your Linus Torvalds - - +How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds +========================================================================================= For a person or company who wishes to submit a change to the Linux kernel, the process can sometimes be daunting if you're not familiar @@ -12,57 +10,59 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process -works, see Documentation/development-process. Also, read -Documentation/SubmitChecklist for a list of items to check before +works, see :ref:`Documentation/development-process `. +Also, read :ref:`Documentation/SubmitChecklist ` +for a list of items to check before submitting code. If you are submitting a driver, also read -Documentation/SubmittingDrivers; for device tree binding patches, read +:ref:`Documentation/SubmittingDrivers `; +for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. -Many of these steps describe the default behavior of the git version -control system; if you use git to prepare your patches, you'll find much +Many of these steps describe the default behavior of the ``git`` version +control system; if you use ``git`` to prepare your patches, you'll find much of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. In general, use of git will make +and document a sensible set of patches. In general, use of ``git`` will make your life as a kernel developer easier. --------------------------------------------- -SECTION 1 - CREATING AND SENDING YOUR CHANGE --------------------------------------------- +Creating and Sending your Change +******************************** 0) Obtain a current source tree ------------------------------- If you do not have a repository with the current kernel source handy, use -git to obtain one. You'll want to start with the mainline repository, -which can be grabbed with: +``git`` to obtain one. You'll want to start with the mainline repository, +which can be grabbed with:: - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git Note, however, that you may not want to develop against the mainline tree directly. Most subsystem maintainers run their own trees and want to see -patches prepared against those trees. See the "T:" entry for the subsystem +patches prepared against those trees. See the **T:** entry for the subsystem in the MAINTAINERS file to find that tree, or simply ask the maintainer if the tree is not listed there. It is still possible to download kernel releases via tarballs (as described in the next section), but that is the hard way to do kernel development. -1) "diff -up" ------------- +1) ``diff -up`` +--------------- -If you must generate your patches by hand, use "diff -up" or "diff -uprN" +If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` to create patches. Git generates patches in this form by default; if -you're using git, you can skip this section entirely. +you're using ``git``, you can skip this section entirely. All changes to the Linux kernel occur in the form of patches, as -generated by diff(1). When creating your patch, make sure to create it -in "unified diff" format, as supplied by the '-u' argument to diff(1). -Also, please use the '-p' argument which shows which C function each -change is in - that makes the resultant diff a lot easier to read. +generated by :manpage:`diff(1)`. When creating your patch, make sure to +create it in "unified diff" format, as supplied by the ``-u`` argument +to :manpage:`diff(1)`. +Also, please use the ``-p`` argument which shows which C function each +change is in - that makes the resultant ``diff`` a lot easier to read. Patches should be based in the root kernel source directory, not in any lower subdirectory. -To create a patch for a single file, it is often sufficient to do: +To create a patch for a single file, it is often sufficient to do:: SRCTREE= linux MYFILE= drivers/net/mydriver.c @@ -74,8 +74,8 @@ To create a patch for a single file, it is often sufficient to do: diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a diff against your -own source tree. For example: +or unmodified kernel source tree, and generate a ``diff`` against your +own source tree. For example:: MYSRC= /devel/linux @@ -84,27 +84,27 @@ own source tree. For example: diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ linux-3.19-vanilla $MYSRC > /tmp/patch -"dontdiff" is a list of files which are generated by the kernel during -the build process, and should be ignored in any diff(1)-generated +``dontdiff`` is a list of files which are generated by the kernel during +the build process, and should be ignored in any :manpage:`diff(1)`-generated patch. Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch -after- -generating it with diff(1), to ensure accuracy. +generating it with :manpage:`diff(1)`, to ensure accuracy. If your changes produce a lot of deltas, you need to split them into -individual patches which modify things in logical stages; see section -#3. This will facilitate review by other kernel developers, +individual patches which modify things in logical stages; see +:ref:`split_changes`. This will facilitate review by other kernel developers, very important if you want your patch accepted. -If you're using git, "git rebase -i" can help you with this process. If -you're not using git, quilt +If you're using ``git``, ``git rebase -i`` can help you with this process. If +you're not using ``git``, ``quilt`` is another popular alternative. +.. _describe_changes: - -2) Describe your changes. -------------------------- +2) Describe your changes +------------------------ Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that @@ -137,11 +137,11 @@ as you intend it to. The maintainer will thank you if you write your patch description in a form which can be easily pulled into Linux's source code management -system, git, as a "commit log". See #15, below. +system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. Solve only one problem per patch. If your description starts to get long, that's a sign that you probably need to split up your patch. -See #3, next. +See :ref:`split_changes`. When you submit or resubmit a patch or patch series, include the complete patch description and justification for it. Don't just @@ -160,7 +160,7 @@ its behaviour. If the patch fixes a logged bug entry, refer to that bug entry by number and URL. If the patch follows from a mailing list discussion, give a URL to the mailing list archive; use the https://lkml.kernel.org/ -redirector with a Message-Id, to ensure that the links cannot become +redirector with a ``Message-Id``, to ensure that the links cannot become stale. However, try to make your explanation understandable without external @@ -171,7 +171,7 @@ patch as submitted. If you want to refer to a specific commit, don't just refer to the SHA-1 ID of the commit. Please also include the oneline summary of the commit, to make it easier for reviewers to know what it is about. -Example: +Example:: Commit e21d2170f36602ae2708 ("video: remove unnecessary platform_set_drvdata()") removed the unnecessary @@ -185,23 +185,25 @@ there is no collision with your six-character ID now, that condition may change five years from now. If your patch fixes a bug in a specific commit, e.g. you found an issue using -git-bisect, please use the 'Fixes:' tag with the first 12 characters of the -SHA-1 ID, and the one line summary. For example: +``git bisect``, please use the 'Fixes:' tag with the first 12 characters of +the SHA-1 ID, and the one line summary. For example:: Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") -The following git-config settings can be used to add a pretty format for -outputting the above style in the git log or git show commands +The following ``git config`` settings can be used to add a pretty format for +outputting the above style in the ``git log`` or ``git show`` commands:: [core] abbrev = 12 [pretty] fixes = Fixes: %h (\"%s\") -3) Separate your changes. -------------------------- +.. _split_changes: + +3) Separate your changes +------------------------ -Separate each _logical change_ into a separate patch. +Separate each **logical change** into a separate patch. For example, if your changes include both bug fixes and performance enhancements for a single driver, separate those changes into two @@ -217,12 +219,12 @@ change that can be verified by reviewers. Each patch should be justifiable on its own merits. If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note "this patch depends on patch X" +complete, that is OK. Simply note **"this patch depends on patch X"** in your patch description. When dividing your change into a series of patches, take special care to ensure that the kernel builds and runs properly after each patch in the -series. Developers using "git bisect" to track down a problem can end up +series. Developers using ``git bisect`` to track down a problem can end up splitting your patch series at any point; they will not thank you if you introduce bugs in the middle. @@ -231,11 +233,13 @@ then only post say 15 or so at a time and wait for review and integration. -4) Style-check your changes. ----------------------------- +4) Style-check your changes +--------------------------- Check your patch for basic style violations, details of which can be -found in Documentation/CodingStyle. Failure to do so simply wastes +found in +:ref:`Documentation/CodingStyle `. +Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. @@ -260,8 +264,8 @@ You should be able to justify all violations that remain in your patch. -5) Select the recipients for your patch. ----------------------------------------- +5) Select the recipients for your patch +--------------------------------------- You should always copy the appropriate subsystem maintainer(s) on any patch to code that they maintain; look through the MAINTAINERS file and the @@ -295,13 +299,14 @@ to allow distributors to get the patch out to users; in such cases, obviously, the patch should not be sent to any public lists. Patches that fix a severe bug in a released kernel should be directed -toward the stable maintainers by putting a line like this: +toward the stable maintainers by putting a line like this:: Cc: stable@vger.kernel.org into the sign-off area of your patch (note, NOT an email recipient). You -should also read Documentation/stable_kernel_rules.txt in addition to this -file. +should also read +:ref:`Documentation/stable_kernel_rules.txt ` +in addition to this file. Note, however, that some subsystem maintainers want to come to their own conclusions on which patches should go to the stable trees. The networking @@ -312,28 +317,30 @@ If changes affect userland-kernel interfaces, please send the MAN-PAGES maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at least a notification of the change, so that some information makes its way into the manual pages. User-space API changes should also be copied to -linux-api@vger.kernel.org. +linux-api@vger.kernel.org. For small patches you may want to CC the Trivial Patch Monkey trivial@kernel.org which collects "trivial" patches. Have a look into the MAINTAINERS file for its current manager. + Trivial patches must qualify for one of the following rules: - Spelling fixes in documentation - Spelling fixes for errors which could break grep(1) - Warning fixes (cluttering with useless warnings is bad) - Compilation fixes (only if they are actually correct) - Runtime fixes (only if they actually fix things) - Removing use of deprecated functions/macros - Contact detail and documentation fixes - Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) - Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) + +- Spelling fixes in documentation +- Spelling fixes for errors which could break :manpage:`grep(1)` +- Warning fixes (cluttering with useless warnings is bad) +- Compilation fixes (only if they are actually correct) +- Runtime fixes (only if they actually fix things) +- Removing use of deprecated functions/macros +- Contact detail and documentation fixes +- Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) +- Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) -6) No MIME, no links, no compression, no attachments. Just plain text. ------------------------------------------------------------------------ +6) No MIME, no links, no compression, no attachments. Just plain text +---------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel @@ -341,8 +348,11 @@ developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. For this reason, all patches should be submitted by e-mail "inline". -WARNING: Be wary of your editor's word-wrap corrupting your patch, -if you choose to cut-n-paste your patch. + +.. warning:: + + Be wary of your editor's word-wrap corrupting your patch, + if you choose to cut-n-paste your patch. Do not attach the patch as a MIME attachment, compressed or not. Many popular e-mail applications will not always transmit a MIME @@ -353,11 +363,12 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. -See Documentation/email-clients.txt for hints about configuring -your e-mail client so that it sends your patches untouched. +See :ref:`Documentation/email-clients.txt ` +for hints about configuring your e-mail client so that it sends your patches +untouched. -7) E-mail size. ---------------- +7) E-mail size +-------------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size, @@ -366,8 +377,8 @@ server, and provide instead a URL (link) pointing to your patch. But note that if your patch exceeds 300 kB, it almost certainly needs to be broken up anyway. -8) Respond to review comments. ------------------------------- +8) Respond to review comments +----------------------------- Your patch will almost certainly get comments from reviewers on ways in which the patch can be improved. You must respond to those comments; @@ -382,8 +393,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. -9) Don't get discouraged - or impatient. ----------------------------------------- +9) Don't get discouraged - or impatient +--------------------------------------- After you have submitted your change, be patient and wait. Reviewers are busy people and may not get to your patch right away. @@ -419,9 +430,10 @@ patch, which certifies that you wrote it or otherwise have the right to pass it on as an open-source patch. The rules are pretty simple: if you can certify the below: - Developer's Certificate of Origin 1.1 +Developer's Certificate of Origin 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - By making a contribution to this project, I certify that: +By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license @@ -445,7 +457,7 @@ can certify the below: maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. -then you just add a line saying +then you just add a line saying:: Signed-off-by: Random J Developer @@ -466,7 +478,7 @@ you add a line between the last Signed-off-by header and yours, indicating the nature of your changes. While there is nothing mandatory about this, it seems like prepending the description with your mail and/or name, all enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example : +you are responsible for last-minute changes. Example:: Signed-off-by: Random J Developer [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] @@ -481,15 +493,15 @@ which appears in the changelog. Special note to back-porters: It seems to be a common and useful practice to insert an indication of the origin of a patch at the top of the commit message (just after the subject line) to facilitate tracking. For instance, -here's what we see in a 3.x-stable release: +here's what we see in a 3.x-stable release:: -Date: Tue Oct 7 07:26:38 2014 -0400 + Date: Tue Oct 7 07:26:38 2014 -0400 libata: Un-break ATA blacklist commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. -And here's what might appear in an older kernel once a patch is backported: +And here's what might appear in an older kernel once a patch is backported:: Date: Tue May 13 22:12:27 2008 +0200 @@ -529,7 +541,7 @@ When in doubt people should refer to the original discussion in the mailing list archives. If a person has had the opportunity to comment on a patch, but has not -provided such comments, you may optionally add a "Cc:" tag to the patch. +provided such comments, you may optionally add a ``Cc:`` tag to the patch. This is the only tag which might be added without an explicit action by the person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties @@ -552,11 +564,12 @@ future patches, and ensures credit for the testers. Reviewed-by:, instead, indicates that the patch has been reviewed and found acceptable according to the Reviewer's Statement: - Reviewer's statement of oversight +Reviewer's statement of oversight +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - By offering my Reviewed-by: tag, I state that: +By offering my Reviewed-by: tag, I state that: - (a) I have carried out a technical review of this patch to + (a) I have carried out a technical review of this patch to evaluate its appropriateness and readiness for inclusion into the mainline kernel. @@ -594,24 +607,25 @@ A Fixes: tag indicates that the patch fixes an issue in a previous commit. It is used to make it easy to determine where a bug originated, which can help review a bug fix. This tag also assists the stable kernel team in determining which stable kernel versions should receive your fix. This is the preferred -method for indicating a bug fixed by the patch. See #2 above for more details. +method for indicating a bug fixed by the patch. See :ref:`describe_changes` +for more details. 14) The canonical patch format ------------------------------ This section describes how the patch itself should be formatted. Note -that, if you have your patches stored in a git repository, proper patch -formatting can be had with "git format-patch". The tools cannot create +that, if you have your patches stored in a ``git`` repository, proper patch +formatting can be had with ``git format-patch``. The tools cannot create the necessary text, though, so read the instructions below anyway. -The canonical patch subject line is: +The canonical patch subject line is:: Subject: [PATCH 001/123] subsystem: summary phrase The canonical patch message body contains the following: - - A "from" line specifying the patch author (only needed if the person + - A ``from`` line specifying the patch author (only needed if the person sending the patch is not the author). - An empty line. @@ -619,46 +633,46 @@ The canonical patch message body contains the following: - The body of the explanation, line wrapped at 75 columns, which will be copied to the permanent changelog to describe this patch. - - The "Signed-off-by:" lines, described above, which will + - The ``Signed-off-by:`` lines, described above, which will also go in the changelog. - - A marker line containing simply "---". + - A marker line containing simply ``---``. - Any additional comments not suitable for the changelog. - - The actual patch (diff output). + - The actual patch (``diff`` output). The Subject line format makes it very easy to sort the emails alphabetically by subject line - pretty much any email reader will support that - since because the sequence number is zero-padded, the numerical and alphabetic sort is the same. -The "subsystem" in the email's Subject should identify which +The ``subsystem`` in the email's Subject should identify which area or subsystem of the kernel is being patched. -The "summary phrase" in the email's Subject should concisely -describe the patch which that email contains. The "summary -phrase" should not be a filename. Do not use the same "summary -phrase" for every patch in a whole patch series (where a "patch -series" is an ordered sequence of multiple, related patches). +The ``summary phrase`` in the email's Subject should concisely +describe the patch which that email contains. The ``summary +phrase`` should not be a filename. Do not use the same ``summary +phrase`` for every patch in a whole patch series (where a ``patch +series`` is an ordered sequence of multiple, related patches). -Bear in mind that the "summary phrase" of your email becomes a +Bear in mind that the ``summary phrase`` of your email becomes a globally-unique identifier for that patch. It propagates all the way -into the git changelog. The "summary phrase" may later be used in +into the ``git`` changelog. The ``summary phrase`` may later be used in developer discussions which refer to the patch. People will want to -google for the "summary phrase" to read discussion regarding that +google for the ``summary phrase`` to read discussion regarding that patch. It will also be the only thing that people may quickly see when, two or three months later, they are going through perhaps -thousands of patches using tools such as "gitk" or "git log ---oneline". +thousands of patches using tools such as ``gitk`` or ``git log +--oneline``. -For these reasons, the "summary" must be no more than 70-75 +For these reasons, the ``summary`` must be no more than 70-75 characters, and it must describe both what the patch changes, as well as why the patch might be necessary. It is challenging to be both succinct and descriptive, but that is what a well-written summary should do. -The "summary phrase" may be prefixed by tags enclosed in square +The ``summary phrase`` may be prefixed by tags enclosed in square brackets: "Subject: [PATCH ...] ". The tags are not considered part of the summary phrase, but describe how the patch should be treated. Common tags might include a version descriptor if @@ -670,19 +684,19 @@ that developers understand the order in which the patches should be applied and that they have reviewed or applied all of the patches in the patch series. -A couple of example Subjects: +A couple of example Subjects:: Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching Subject: [PATCH v2 01/27] x86: fix eflags tracking -The "from" line must be the very first line in the message body, +The ``from`` line must be the very first line in the message body, and has the form: From: Original Author -The "from" line specifies who will be credited as the author of the -patch in the permanent changelog. If the "from" line is missing, -then the "From:" line from the email header will be used to determine +The ``from`` line specifies who will be credited as the author of the +patch in the permanent changelog. If the ``from`` line is missing, +then the ``From:`` line from the email header will be used to determine the patch author in the changelog. The explanation body will be committed to the permanent source @@ -694,35 +708,37 @@ especially useful for people who might be searching the commit logs looking for the applicable patch. If a patch fixes a compile failure, it may not be necessary to include _all_ of the compile failures; just enough that it is likely that someone searching for the patch can find -it. As in the "summary phrase", it is important to be both succinct as +it. As in the ``summary phrase``, it is important to be both succinct as well as descriptive. -The "---" marker line serves the essential purpose of marking for patch +The ``---`` marker line serves the essential purpose of marking for patch handling tools where the changelog message ends. -One good use for the additional comments after the "---" marker is for -a diffstat, to show what files have changed, and the number of -inserted and deleted lines per file. A diffstat is especially useful +One good use for the additional comments after the ``---`` marker is for +a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful on bigger patches. Other comments relevant only to the moment or the maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be "patch changelogs" +here. A good example of such comments might be ``patch changelogs`` which describe what has changed between the v1 and v2 version of the patch. -If you are going to include a diffstat after the "---" marker, please -use diffstat options "-p 1 -w 70" so that filenames are listed from +If you are going to include a ``diffstat`` after the ``---`` marker, please +use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (git +space (easily fit in 80 columns, maybe with some indentation). (``git`` generates appropriate diffstats by default.) See more details on the proper patch format in the following references. +.. _explicit_in_reply_to: + 15) Explicit In-Reply-To headers -------------------------------- It can be helpful to manually add In-Reply-To: headers to a patch -(e.g., when using "git send-email") to associate the patch with +(e.g., when using ``git send-email``) to associate the patch with previous relevant discussion, e.g. to link a bug fix to the email with the bug report. However, for a multi-patch series, it is generally best to avoid using In-Reply-To: to link to older versions of the @@ -732,12 +748,12 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in the cover email text) to link to an earlier version of the patch series. -16) Sending "git pull" requests -------------------------------- +16) Sending ``git pull`` requests +--------------------------------- If you have a series of patches, it may be most convenient to have the maintainer pull them directly into the subsystem repository with a -"git pull" operation. Note, however, that pulling patches from a developer +``git pull`` operation. Note, however, that pulling patches from a developer requires a higher degree of trust than taking patches from a mailing list. As a result, many subsystem maintainers are reluctant to take pull requests, especially from new, unknown developers. If in doubt you can use @@ -746,7 +762,7 @@ series, giving the maintainer the option of using either. A pull request should have [GIT] or [PULL] in the subject line. The request itself should include the repository name and the branch of -interest on a single line; it should look something like: +interest on a single line; it should look something like:: Please pull from @@ -755,10 +771,10 @@ interest on a single line; it should look something like: to get these changes: A pull request should also include an overall message saying what will be -included in the request, a "git shortlog" listing of the patches -themselves, and a diffstat showing the overall effect of the patch series. +included in the request, a ``git shortlog`` listing of the patches +themselves, and a ``diffstat`` showing the overall effect of the patch series. The easiest way to get all this information together is, of course, to let -git do it for you with the "git request-pull" command. +``git`` do it for you with the ``git request-pull`` command. Some maintainers (including Linus) want to see pull requests from signed commits; that increases their confidence that the request actually came @@ -770,8 +786,8 @@ signed by one or more core kernel developers. This step can be hard for new developers, but there is no way around it. Attending conferences can be a good way to find developers who can sign your key. -Once you have prepared a patch series in git that you wish to have somebody -pull, create a signed tag with "git tag -s". This will create a new tag +Once you have prepared a patch series in ``git`` that you wish to have somebody +pull, create a signed tag with ``git tag -s``. This will create a new tag identifying the last commit in the series and containing a signature created with your private key. You will also have the opportunity to add a changelog-style message to the tag; this is an ideal place to describe the @@ -782,14 +798,13 @@ are working from, don't forget to push the signed tag explicitly to the public tree. When generating your pull request, use the signed tag as the target. A -command like this will do the trick: +command like this will do the trick:: git request-pull master git://my.public.tree/linux.git my-signed-tag ----------------------- -SECTION 2 - REFERENCES ----------------------- +REFERENCES +********** Andrew Morton, "The perfect patch" (tpp). @@ -799,23 +814,28 @@ Jeff Garzik, "Linux kernel patch submission format". Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! Kernel Documentation/CodingStyle: - + :ref:`Documentation/CodingStyle ` Linus Torvalds's mail on the canonical patch format: Andi Kleen, "On submitting kernel patches" Some strategies to get difficult or controversial changes in. + http://halobates.de/on-submitting-patches.pdf --- diff --git a/Documentation/accounting/.gitignore b/Documentation/accounting/.gitignore deleted file mode 100644 index 86485203c4ae..000000000000 --- a/Documentation/accounting/.gitignore +++ /dev/null @@ -1 +0,0 @@ -getdelays diff --git a/Documentation/accounting/Makefile b/Documentation/accounting/Makefile deleted file mode 100644 index 7e232cb6fd7d..000000000000 --- a/Documentation/accounting/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# List of programs to build -hostprogs-y := getdelays - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -HOSTCFLAGS_getdelays.o += -I$(objtree)/usr/include diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.txt index 8a12f0730c94..042ea59b5853 100644 --- a/Documentation/accounting/delay-accounting.txt +++ b/Documentation/accounting/delay-accounting.txt @@ -54,9 +54,9 @@ are sent to userspace without requiring a command. If it is the last exiting task of a thread group, the per-tgid statistics are also sent. More details are given in the taskstats interface description. -The getdelays.c userspace utility in this directory allows simple commands to -be run and the corresponding delay statistics to be displayed. It also serves -as an example of using the taskstats interface. +The getdelays.c userspace utility in tools/accounting directory allows simple +commands to be run and the corresponding delay statistics to be displayed. It +also serves as an example of using the taskstats interface. Usage ----- diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c deleted file mode 100644 index b5ca536e56a8..000000000000 --- a/Documentation/accounting/getdelays.c +++ /dev/null @@ -1,550 +0,0 @@ -/* getdelays.c - * - * Utility to get per-pid and per-tgid delay accounting statistics - * Also illustrates usage of the taskstats interface - * - * Copyright (C) Shailabh Nagar, IBM Corp. 2005 - * Copyright (C) Balbir Singh, IBM Corp. 2006 - * Copyright (c) Jay Lan, SGI. 2006 - * - * Compile with - * gcc -I/usr/src/linux/include getdelays.c -o getdelays - */ - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#include -#include -#include - -/* - * Generic macros for dealing with netlink sockets. Might be duplicated - * elsewhere. It is recommended that commercial grade applications use - * libnl or libnetlink and use the interfaces provided by the library - */ -#define GENLMSG_DATA(glh) ((void *)(NLMSG_DATA(glh) + GENL_HDRLEN)) -#define GENLMSG_PAYLOAD(glh) (NLMSG_PAYLOAD(glh, 0) - GENL_HDRLEN) -#define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN)) -#define NLA_PAYLOAD(len) (len - NLA_HDRLEN) - -#define err(code, fmt, arg...) \ - do { \ - fprintf(stderr, fmt, ##arg); \ - exit(code); \ - } while (0) - -int done; -int rcvbufsz; -char name[100]; -int dbg; -int print_delays; -int print_io_accounting; -int print_task_context_switch_counts; - -#define PRINTF(fmt, arg...) { \ - if (dbg) { \ - printf(fmt, ##arg); \ - } \ - } - -/* Maximum size of response requested or message sent */ -#define MAX_MSG_SIZE 1024 -/* Maximum number of cpus expected to be specified in a cpumask */ -#define MAX_CPUS 32 - -struct msgtemplate { - struct nlmsghdr n; - struct genlmsghdr g; - char buf[MAX_MSG_SIZE]; -}; - -char cpumask[100+6*MAX_CPUS]; - -static void usage(void) -{ - fprintf(stderr, "getdelays [-dilv] [-w logfile] [-r bufsize] " - "[-m cpumask] [-t tgid] [-p pid]\n"); - fprintf(stderr, " -d: print delayacct stats\n"); - fprintf(stderr, " -i: print IO accounting (works only with -p)\n"); - fprintf(stderr, " -l: listen forever\n"); - fprintf(stderr, " -v: debug on\n"); - fprintf(stderr, " -C: container path\n"); -} - -/* - * Create a raw netlink socket and bind - */ -static int create_nl_socket(int protocol) -{ - int fd; - struct sockaddr_nl local; - - fd = socket(AF_NETLINK, SOCK_RAW, protocol); - if (fd < 0) - return -1; - - if (rcvbufsz) - if (setsockopt(fd, SOL_SOCKET, SO_RCVBUF, - &rcvbufsz, sizeof(rcvbufsz)) < 0) { - fprintf(stderr, "Unable to set socket rcv buf size to %d\n", - rcvbufsz); - goto error; - } - - memset(&local, 0, sizeof(local)); - local.nl_family = AF_NETLINK; - - if (bind(fd, (struct sockaddr *) &local, sizeof(local)) < 0) - goto error; - - return fd; -error: - close(fd); - return -1; -} - - -static int send_cmd(int sd, __u16 nlmsg_type, __u32 nlmsg_pid, - __u8 genl_cmd, __u16 nla_type, - void *nla_data, int nla_len) -{ - struct nlattr *na; - struct sockaddr_nl nladdr; - int r, buflen; - char *buf; - - struct msgtemplate msg; - - msg.n.nlmsg_len = NLMSG_LENGTH(GENL_HDRLEN); - msg.n.nlmsg_type = nlmsg_type; - msg.n.nlmsg_flags = NLM_F_REQUEST; - msg.n.nlmsg_seq = 0; - msg.n.nlmsg_pid = nlmsg_pid; - msg.g.cmd = genl_cmd; - msg.g.version = 0x1; - na = (struct nlattr *) GENLMSG_DATA(&msg); - na->nla_type = nla_type; - na->nla_len = nla_len + 1 + NLA_HDRLEN; - memcpy(NLA_DATA(na), nla_data, nla_len); - msg.n.nlmsg_len += NLMSG_ALIGN(na->nla_len); - - buf = (char *) &msg; - buflen = msg.n.nlmsg_len ; - memset(&nladdr, 0, sizeof(nladdr)); - nladdr.nl_family = AF_NETLINK; - while ((r = sendto(sd, buf, buflen, 0, (struct sockaddr *) &nladdr, - sizeof(nladdr))) < buflen) { - if (r > 0) { - buf += r; - buflen -= r; - } else if (errno != EAGAIN) - return -1; - } - return 0; -} - - -/* - * Probe the controller in genetlink to find the family id - * for the TASKSTATS family - */ -static int get_family_id(int sd) -{ - struct { - struct nlmsghdr n; - struct genlmsghdr g; - char buf[256]; - } ans; - - int id = 0, rc; - struct nlattr *na; - int rep_len; - - strcpy(name, TASKSTATS_GENL_NAME); - rc = send_cmd(sd, GENL_ID_CTRL, getpid(), CTRL_CMD_GETFAMILY, - CTRL_ATTR_FAMILY_NAME, (void *)name, - strlen(TASKSTATS_GENL_NAME)+1); - if (rc < 0) - return 0; /* sendto() failure? */ - - rep_len = recv(sd, &ans, sizeof(ans), 0); - if (ans.n.nlmsg_type == NLMSG_ERROR || - (rep_len < 0) || !NLMSG_OK((&ans.n), rep_len)) - return 0; - - na = (struct nlattr *) GENLMSG_DATA(&ans); - na = (struct nlattr *) ((char *) na + NLA_ALIGN(na->nla_len)); - if (na->nla_type == CTRL_ATTR_FAMILY_ID) { - id = *(__u16 *) NLA_DATA(na); - } - return id; -} - -#define average_ms(t, c) (t / 1000000ULL / (c ? c : 1)) - -static void print_delayacct(struct taskstats *t) -{ - printf("\n\nCPU %15s%15s%15s%15s%15s\n" - " %15llu%15llu%15llu%15llu%15.3fms\n" - "IO %15s%15s%15s\n" - " %15llu%15llu%15llums\n" - "SWAP %15s%15s%15s\n" - " %15llu%15llu%15llums\n" - "RECLAIM %12s%15s%15s\n" - " %15llu%15llu%15llums\n", - "count", "real total", "virtual total", - "delay total", "delay average", - (unsigned long long)t->cpu_count, - (unsigned long long)t->cpu_run_real_total, - (unsigned long long)t->cpu_run_virtual_total, - (unsigned long long)t->cpu_delay_total, - average_ms((double)t->cpu_delay_total, t->cpu_count), - "count", "delay total", "delay average", - (unsigned long long)t->blkio_count, - (unsigned long long)t->blkio_delay_total, - average_ms(t->blkio_delay_total, t->blkio_count), - "count", "delay total", "delay average", - (unsigned long long)t->swapin_count, - (unsigned long long)t->swapin_delay_total, - average_ms(t->swapin_delay_total, t->swapin_count), - "count", "delay total", "delay average", - (unsigned long long)t->freepages_count, - (unsigned long long)t->freepages_delay_total, - average_ms(t->freepages_delay_total, t->freepages_count)); -} - -static void task_context_switch_counts(struct taskstats *t) -{ - printf("\n\nTask %15s%15s\n" - " %15llu%15llu\n", - "voluntary", "nonvoluntary", - (unsigned long long)t->nvcsw, (unsigned long long)t->nivcsw); -} - -static void print_cgroupstats(struct cgroupstats *c) -{ - printf("sleeping %llu, blocked %llu, running %llu, stopped %llu, " - "uninterruptible %llu\n", (unsigned long long)c->nr_sleeping, - (unsigned long long)c->nr_io_wait, - (unsigned long long)c->nr_running, - (unsigned long long)c->nr_stopped, - (unsigned long long)c->nr_uninterruptible); -} - - -static void print_ioacct(struct taskstats *t) -{ - printf("%s: read=%llu, write=%llu, cancelled_write=%llu\n", - t->ac_comm, - (unsigned long long)t->read_bytes, - (unsigned long long)t->write_bytes, - (unsigned long long)t->cancelled_write_bytes); -} - -int main(int argc, char *argv[]) -{ - int c, rc, rep_len, aggr_len, len2; - int cmd_type = TASKSTATS_CMD_ATTR_UNSPEC; - __u16 id; - __u32 mypid; - - struct nlattr *na; - int nl_sd = -1; - int len = 0; - pid_t tid = 0; - pid_t rtid = 0; - - int fd = 0; - int count = 0; - int write_file = 0; - int maskset = 0; - char *logfile = NULL; - int loop = 0; - int containerset = 0; - char *containerpath = NULL; - int cfd = 0; - int forking = 0; - sigset_t sigset; - - struct msgtemplate msg; - - while (!forking) { - c = getopt(argc, argv, "qdiw:r:m:t:p:vlC:c:"); - if (c < 0) - break; - - switch (c) { - case 'd': - printf("print delayacct stats ON\n"); - print_delays = 1; - break; - case 'i': - printf("printing IO accounting\n"); - print_io_accounting = 1; - break; - case 'q': - printf("printing task/process context switch rates\n"); - print_task_context_switch_counts = 1; - break; - case 'C': - containerset = 1; - containerpath = optarg; - break; - case 'w': - logfile = strdup(optarg); - printf("write to file %s\n", logfile); - write_file = 1; - break; - case 'r': - rcvbufsz = atoi(optarg); - printf("receive buf size %d\n", rcvbufsz); - if (rcvbufsz < 0) - err(1, "Invalid rcv buf size\n"); - break; - case 'm': - strncpy(cpumask, optarg, sizeof(cpumask)); - cpumask[sizeof(cpumask) - 1] = '\0'; - maskset = 1; - printf("cpumask %s maskset %d\n", cpumask, maskset); - break; - case 't': - tid = atoi(optarg); - if (!tid) - err(1, "Invalid tgid\n"); - cmd_type = TASKSTATS_CMD_ATTR_TGID; - break; - case 'p': - tid = atoi(optarg); - if (!tid) - err(1, "Invalid pid\n"); - cmd_type = TASKSTATS_CMD_ATTR_PID; - break; - case 'c': - - /* Block SIGCHLD for sigwait() later */ - if (sigemptyset(&sigset) == -1) - err(1, "Failed to empty sigset"); - if (sigaddset(&sigset, SIGCHLD)) - err(1, "Failed to set sigchld in sigset"); - sigprocmask(SIG_BLOCK, &sigset, NULL); - - /* fork/exec a child */ - tid = fork(); - if (tid < 0) - err(1, "Fork failed\n"); - if (tid == 0) - if (execvp(argv[optind - 1], - &argv[optind - 1]) < 0) - exit(-1); - - /* Set the command type and avoid further processing */ - cmd_type = TASKSTATS_CMD_ATTR_PID; - forking = 1; - break; - case 'v': - printf("debug on\n"); - dbg = 1; - break; - case 'l': - printf("listen forever\n"); - loop = 1; - break; - default: - usage(); - exit(-1); - } - } - - if (write_file) { - fd = open(logfile, O_WRONLY | O_CREAT | O_TRUNC, - S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH); - if (fd == -1) { - perror("Cannot open output file\n"); - exit(1); - } - } - - nl_sd = create_nl_socket(NETLINK_GENERIC); - if (nl_sd < 0) - err(1, "error creating Netlink socket\n"); - - - mypid = getpid(); - id = get_family_id(nl_sd); - if (!id) { - fprintf(stderr, "Error getting family id, errno %d\n", errno); - goto err; - } - PRINTF("family id %d\n", id); - - if (maskset) { - rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET, - TASKSTATS_CMD_ATTR_REGISTER_CPUMASK, - &cpumask, strlen(cpumask) + 1); - PRINTF("Sent register cpumask, retval %d\n", rc); - if (rc < 0) { - fprintf(stderr, "error sending register cpumask\n"); - goto err; - } - } - - if (tid && containerset) { - fprintf(stderr, "Select either -t or -C, not both\n"); - goto err; - } - - /* - * If we forked a child, wait for it to exit. Cannot use waitpid() - * as all the delicious data would be reaped as part of the wait - */ - if (tid && forking) { - int sig_received; - sigwait(&sigset, &sig_received); - } - - if (tid) { - rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET, - cmd_type, &tid, sizeof(__u32)); - PRINTF("Sent pid/tgid, retval %d\n", rc); - if (rc < 0) { - fprintf(stderr, "error sending tid/tgid cmd\n"); - goto done; - } - } - - if (containerset) { - cfd = open(containerpath, O_RDONLY); - if (cfd < 0) { - perror("error opening container file"); - goto err; - } - rc = send_cmd(nl_sd, id, mypid, CGROUPSTATS_CMD_GET, - CGROUPSTATS_CMD_ATTR_FD, &cfd, sizeof(__u32)); - if (rc < 0) { - perror("error sending cgroupstats command"); - goto err; - } - } - if (!maskset && !tid && !containerset) { - usage(); - goto err; - } - - do { - rep_len = recv(nl_sd, &msg, sizeof(msg), 0); - PRINTF("received %d bytes\n", rep_len); - - if (rep_len < 0) { - fprintf(stderr, "nonfatal reply error: errno %d\n", - errno); - continue; - } - if (msg.n.nlmsg_type == NLMSG_ERROR || - !NLMSG_OK((&msg.n), rep_len)) { - struct nlmsgerr *err = NLMSG_DATA(&msg); - fprintf(stderr, "fatal reply error, errno %d\n", - err->error); - goto done; - } - - PRINTF("nlmsghdr size=%zu, nlmsg_len=%d, rep_len=%d\n", - sizeof(struct nlmsghdr), msg.n.nlmsg_len, rep_len); - - - rep_len = GENLMSG_PAYLOAD(&msg.n); - - na = (struct nlattr *) GENLMSG_DATA(&msg); - len = 0; - while (len < rep_len) { - len += NLA_ALIGN(na->nla_len); - switch (na->nla_type) { - case TASKSTATS_TYPE_AGGR_TGID: - /* Fall through */ - case TASKSTATS_TYPE_AGGR_PID: - aggr_len = NLA_PAYLOAD(na->nla_len); - len2 = 0; - /* For nested attributes, na follows */ - na = (struct nlattr *) NLA_DATA(na); - done = 0; - while (len2 < aggr_len) { - switch (na->nla_type) { - case TASKSTATS_TYPE_PID: - rtid = *(int *) NLA_DATA(na); - if (print_delays) - printf("PID\t%d\n", rtid); - break; - case TASKSTATS_TYPE_TGID: - rtid = *(int *) NLA_DATA(na); - if (print_delays) - printf("TGID\t%d\n", rtid); - break; - case TASKSTATS_TYPE_STATS: - count++; - if (print_delays) - print_delayacct((struct taskstats *) NLA_DATA(na)); - if (print_io_accounting) - print_ioacct((struct taskstats *) NLA_DATA(na)); - if (print_task_context_switch_counts) - task_context_switch_counts((struct taskstats *) NLA_DATA(na)); - if (fd) { - if (write(fd, NLA_DATA(na), na->nla_len) < 0) { - err(1,"write error\n"); - } - } - if (!loop) - goto done; - break; - case TASKSTATS_TYPE_NULL: - break; - default: - fprintf(stderr, "Unknown nested" - " nla_type %d\n", - na->nla_type); - break; - } - len2 += NLA_ALIGN(na->nla_len); - na = (struct nlattr *)((char *)na + - NLA_ALIGN(na->nla_len)); - } - break; - - case CGROUPSTATS_TYPE_CGROUP_STATS: - print_cgroupstats(NLA_DATA(na)); - break; - default: - fprintf(stderr, "Unknown nla_type %d\n", - na->nla_type); - case TASKSTATS_TYPE_NULL: - break; - } - na = (struct nlattr *) (GENLMSG_DATA(&msg) + len); - } - } while (loop); -done: - if (maskset) { - rc = send_cmd(nl_sd, id, mypid, TASKSTATS_CMD_GET, - TASKSTATS_CMD_ATTR_DEREGISTER_CPUMASK, - &cpumask, strlen(cpumask) + 1); - printf("Sent deregister mask, retval %d\n", rc); - if (rc < 0) - err(rc, "error sending deregister cpumask\n"); - } -err: - close(nl_sd); - if (fd) - close(fd); - if (cfd) - close(cfd); - return 0; -} diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt new file mode 100644 index 000000000000..effe7af3a5af --- /dev/null +++ b/Documentation/acpi/acpi-lid.txt @@ -0,0 +1,96 @@ +Special Usage Model of the ACPI Control Method Lid Device + +Copyright (C) 2016, Intel Corporation +Author: Lv Zheng + + +Abstract: + +Platforms containing lids convey lid state (open/close) to OSPMs using a +control method lid device. To implement this, the AML tables issue +Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has +changed. The _LID control method for the lid device must be implemented to +report the "current" state of the lid as either "opened" or "closed". + +For most platforms, both the _LID method and the lid notifications are +reliable. However, there are exceptions. In order to work with these +exceptional buggy platforms, special restrictions and expections should be +taken into account. This document describes the restrictions and the +expections of the Linux ACPI lid device driver. + + +1. Restrictions of the returning value of the _LID control method + +The _LID control method is described to return the "current" lid state. +However the word of "current" has ambiguity, some buggy AML tables return +the lid state upon the last lid notification instead of returning the lid +state upon the last _LID evaluation. There won't be difference when the +_LID control method is evaluated during the runtime, the problem is its +initial returning value. When the AML tables implement this control method +with cached value, the initial returning value is likely not reliable. +There are platforms always retun "closed" as initial lid state. + +2. Restrictions of the lid state change notifications + +There are buggy AML tables never notifying when the lid device state is +changed to "opened". Thus the "opened" notification is not guaranteed. But +it is guaranteed that the AML tables always notify "closed" when the lid +state is changed to "closed". The "closed" notification is normally used to +trigger some system power saving operations on Windows. Since it is fully +tested, it is reliable from all AML tables. + +3. Expections for the userspace users of the ACPI lid device driver + +The ACPI button driver exports the lid state to the userspace via the +following file: + /proc/acpi/button/lid/LID0/state +This file actually calls the _LID control method described above. And given +the previous explanation, it is not reliable enough on some platforms. So +it is advised for the userspace program to not to solely rely on this file +to determine the actual lid state. + +The ACPI button driver emits the following input event to the userspace: + SW_LID +The ACPI lid device driver is implemented to try to deliver the platform +triggered events to the userspace. However, given the fact that the buggy +firmware cannot make sure "opened"/"closed" events are paired, the ACPI +button driver uses the following 3 modes in order not to trigger issues. + +If the userspace hasn't been prepared to ignore the unreliable "opened" +events and the unreliable initial state notification, Linux users can use +the following kernel parameters to handle the possible issues: +A. button.lid_init_state=method: + When this option is specified, the ACPI button driver reports the + initial lid state using the returning value of the _LID control method + and whether the "opened"/"closed" events are paired fully relies on the + firmware implementation. + This option can be used to fix some platforms where the returning value + of the _LID control method is reliable but the initial lid state + notification is missing. + This option is the default behavior during the period the userspace + isn't ready to handle the buggy AML tables. +B. button.lid_init_state=open: + When this option is specified, the ACPI button driver always reports the + initial lid state as "opened" and whether the "opened"/"closed" events + are paired fully relies on the firmware implementation. + This may fix some platforms where the returning value of the _LID + control method is not reliable and the initial lid state notification is + missing. + +If the userspace has been prepared to ignore the unreliable "opened" events +and the unreliable initial state notification, Linux users should always +use the following kernel parameter: +C. button.lid_init_state=ignore: + When this option is specified, the ACPI button driver never reports the + initial lid state and there is a compensation mechanism implemented to + ensure that the reliable "closed" notifications can always be delievered + to the userspace by always pairing "closed" input events with complement + "opened" input events. But there is still no guarantee that the "opened" + notifications can be delivered to the userspace when the lid is actually + opens given that some AML tables do not send "opened" notifications + reliably. + In this mode, if everything is correctly implemented by the platform + firmware, the old userspace programs should still work. Otherwise, the + new userspace programs are required to work with the ACPI button driver. + This option will be the default behavior after the userspace is ready to + handle the buggy AML tables. diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt index f35dad11f0de..5aafe0b351a1 100644 --- a/Documentation/acpi/gpio-properties.txt +++ b/Documentation/acpi/gpio-properties.txt @@ -28,8 +28,8 @@ index, like the ASL example below shows: ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () {"reset-gpio", Package() {^BTH, 1, 1, 0 }}, - Package () {"shutdown-gpio", Package() {^BTH, 0, 0, 0 }}, + Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }}, + Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }}, } }) } @@ -48,7 +48,7 @@ Since ACPI GpioIo() resource does not have a field saying whether it is active low or high, the "active_low" argument can be used here. Setting it to 1 marks the GPIO as active low. -In our Bluetooth example the "reset-gpio" refers to the second GpioIo() +In our Bluetooth example the "reset-gpios" refers to the second GpioIo() resource, second pin in that resource with the GPIO number of 31. ACPI GPIO Mappings Provided by Drivers @@ -83,8 +83,8 @@ static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { - { "reset-gpio", &reset_gpio, 1 }, - { "shutdown-gpio", &shutdown_gpio, 1 }, + { "reset-gpios", &reset_gpio, 1 }, + { "shutdown-gpios", &shutdown_gpio, 1 }, { }, }; diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 77df55b0225a..02ce4924468e 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -1,9 +1,13 @@ +.. _applying_patches: - Applying Patches To The Linux Kernel - ------------------------------------ +Applying Patches To The Linux Kernel +++++++++++++++++++++++++++++++++++++ - Original by: Jesper Juhl, August 2005 - Last update: 2006-01-05 +Original by: + Jesper Juhl, August 2005 + +Last update: + 2016-09-14 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -17,10 +21,12 @@ their specific patches) is also provided. What is a patch? ---- - A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the `diff' +================ + +A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the ``diff`` program. + To correctly apply a patch you need to know what base it was generated from and what new version the patch will change the source tree into. These should both be present in the patch file metadata or be possible to deduce @@ -28,8 +34,9 @@ from the filename. How do I apply or revert a patch? ---- - You apply a patch with the `patch' program. The patch program reads a diff +================================= + +You apply a patch with the ``patch`` program. The patch program reads a diff (or patch) file and makes the changes to the source tree described in it. Patches for the Linux kernel are generated relative to the parent directory @@ -38,26 +45,33 @@ holding the kernel source dir. This means that paths to files inside the patch file contain the name of the kernel source directories it was generated against (or some other directory names like "a/" and "b/"). + Since this is unlikely to match the name of the kernel source dir on your local machine (but is often useful info to see what version an otherwise unlabeled patch was generated against) you should change into your kernel source directory and then strip the first element of the path from filenames -in the patch file when applying it (the -p1 argument to `patch' does this). +in the patch file when applying it (the ``-p1`` argument to ``patch`` does +this). To revert a previously applied patch, use the -R argument to patch. -So, if you applied a patch like this: +So, if you applied a patch like this:: + patch -p1 < ../patch-x.y.z -You can revert (undo) it like this: +You can revert (undo) it like this:: + patch -R -p1 < ../patch-x.y.z -How do I feed a patch/diff file to `patch'? ---- - This (as usual with Linux and other UNIX like operating systems) can be +How do I feed a patch/diff file to ``patch``? +============================================= + +This (as usual with Linux and other UNIX like operating systems) can be done in several different ways. + In all the examples below I feed the file (in uncompressed form) to patch -via stdin using the following syntax: +via stdin using the following syntax:: + patch -p1 < path/to/patch-x.y.z If you just want to be able to follow the examples below and don't want to @@ -65,35 +79,40 @@ know of more than one way to use patch, then you can stop reading this section here. Patch can also get the name of the file to use via the -i argument, like -this: +this:: + patch -p1 -i path/to/patch-x.y.z -If your patch file is compressed with gzip or bzip2 and you don't want to +If your patch file is compressed with gzip or xz and you don't want to uncompress it before applying it, then you can feed it to patch like this -instead: - zcat path/to/patch-x.y.z.gz | patch -p1 - bzcat path/to/patch-x.y.z.bz2 | patch -p1 +instead:: + + xzcat path/to/patch-x.y.z.xz | patch -p1 + bzcat path/to/patch-x.y.z.gz | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run -gunzip or bunzip2 on the file -- like this: +gunzip or xz on the file -- like this:: + gunzip patch-x.y.z.gz - bunzip2 patch-x.y.z.bz2 + xz -d patch-x.y.z.xz Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the -i argument, as you prefer. +patch via stdin or the ``-i`` argument, as you prefer. -A few other nice arguments for patch are -s which causes patch to be silent +A few other nice arguments for patch are ``-s`` which causes patch to be silent except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and --dry-run which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally --verbose +screen too fast, and ``--dry-run`` which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally ``--verbose`` tells patch to print more information about the work being done. Common errors when patching ---- - When patch applies a patch file it attempts to verify the sanity of the +=========================== + +When patch applies a patch file it attempts to verify the sanity of the file in different ways. + Checking that the file looks like a valid patch file and checking the code around the bits being modified matches the context provided in the patch are just two of the basic sanity checks patch does. @@ -111,13 +130,13 @@ everything looks good it has just moved up or down a bit, and patch will usually adjust the line numbers and apply the patch. Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with 'fuzz'. +it'll tell you about it by saying the patch applied with **fuzz**. You should be wary of such changes since even though patch probably got it right it doesn't /always/ get it right, and the result will sometimes be wrong. When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a .rej extension (a reject file). You can +outright and leaves a file with a ``.rej`` extension (a reject file). You can read this file to see exactly what change couldn't be applied, so you can go fix it up by hand if you wish. @@ -132,43 +151,47 @@ to start with a fresh tree downloaded in full from kernel.org. Let's look a bit more at some of the messages patch can produce. -If patch stops and presents a "File to patch:" prompt, then patch could not +If patch stops and presents a ``File to patch:`` prompt, then patch could not find a file to be patched. Most likely you forgot to specify -p1 or you are in the wrong directory. Less often, you'll find patches that need to be -applied with -p0 instead of -p1 (reading the patch file should reveal if +applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if this is the case -- if so, then this is an error by the person who created the patch but is not fatal). -If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a +If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a message similar to that, then it means that patch had to adjust the location of the change (in this example it needed to move 7 lines from where it expected to make the change to make it fit). + The resulting file may or may not be OK, depending on the reason the file was different than expected. + This often happens if you try to apply a patch that was generated against a different kernel version than the one you are trying to patch. -If you get a message like "Hunk #3 FAILED at 2387.", then it means that the +If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a .rej file with the change that -caused the patch to fail and also a .orig file showing you the original +fuzz its way through. This will generate a ``.rej`` file with the change that +caused the patch to fail and also a ``.orig`` file showing you the original content that couldn't be changed. -If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" +If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` then patch detected that the change contained in the patch seems to have already been made. + If you actually did apply this patch previously and you just re-applied it in error, then just say [n]o and abort this patch. If you applied this patch previously and actually intended to revert it, but forgot to specify -R, -then you can say [y]es here to make patch revert it for you. +then you can say [**y**]es here to make patch revert it for you. + This can also happen if the creator of the patch reversed the source and destination directories when creating the patch, and in that case reverting the patch will in fact apply it. -A message similar to "patch: **** unexpected end of file in patch" or "patch -unexpectedly ends in middle of line" means that patch could make no sense of -the file you fed to it. Either your download is broken, you tried to feed -patch a compressed patch file without uncompressing it first, or the patch +A message similar to ``patch: **** unexpected end of file in patch`` or +``patch unexpectedly ends in middle of line`` means that patch could make no +sense of the file you fed to it. Either your download is broken, you tried to +feed patch a compressed patch file without uncompressing it first, or the patch file that you are using has been mangled by a mail client or mail transfer agent along the way somewhere, e.g., by splitting a long line into two lines. Often these warnings can easily be fixed by joining (concatenating) the @@ -182,28 +205,32 @@ to start over with a fresh download of a full kernel tree and the patch you wish to apply. -Are there any alternatives to `patch'? ---- - Yes there are alternatives. +Are there any alternatives to ``patch``? +======================================== - You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to + +Yes there are alternatives. + +You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. -This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single + +This will let you move from something like 4.7.2 to 4.7.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: - interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 +Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: + + interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. - Another alternative is `ketchup', which is a python script for automatic +Another alternative is ``ketchup``, which is a python script for automatic downloading and applying of patches (http://www.selenic.com/ketchup/). - Other nice tools are diffstat, which shows a summary of changes made by a +Other nice tools are diffstat, which shows a summary of changes made by a patch; lsdiff, which displays a short listing of affected files in a patch file, along with (optionally) the line numbers of the start of each patch; and grepdiff, which displays a list of the files modified by a patch where @@ -211,99 +238,103 @@ the patch contains a given regular expression. Where can I download the patches? ---- - The patches are available at http://kernel.org/ +================================= + +The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. -The 2.6.x.y (-stable) and 2.6.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ +The 4.x.y (-stable) and 4.x patches live at -The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ -The -git patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ +The -rc patches live at -The -mm kernels live at - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ -In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a +In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a country code. This way you'll be downloading from a mirror site that's most likely geographically closer to you, resulting in faster downloads for you, less bandwidth used globally and less load on the main kernel.org servers -- these are good things, so do use mirrors when possible. -The 2.6.x kernels ---- - These are the base stable releases released by Linus. The highest numbered +The 4.x kernels +=============== + +These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 2.6.x base +will be released (see below) on top of this base. Once a new 4.x base kernel is released, a patch is made available that is a delta between the -previous 2.6.x kernel and the new one. +previous 4.x kernel and the new one. + +To apply a patch moving from 4.6 to 4.7, you'd do the following (note +that such patches do **NOT** apply on top of 4.x.y kernels but on top of the +base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to +first revert the 4.x.y patch). + +Here are some examples:: -To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the -base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to -first revert the 2.6.x.y patch). + # moving from 4.6 to 4.7 -Here are some examples: + $ cd ~/linux-4.6 # change to kernel source dir + $ patch -p1 < ../patch-4.7 # apply the 4.7 patch + $ cd .. + $ mv linux-4.6 linux-4.7 # rename source dir -# moving from 2.6.11 to 2.6.12 -$ cd ~/linux-2.6.11 # change to kernel source dir -$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch -$ cd .. -$ mv linux-2.6.11 linux-2.6.12 # rename source dir + # moving from 4.6.1 to 4.7 -# moving from 2.6.11.1 to 2.6.12 -$ cd ~/linux-2.6.11.1 # change to kernel source dir -$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 -$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch -$ cd .. -$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + $ cd ~/linux-4.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch + # source dir is now 4.6 + $ patch -p1 < ../patch-4.7 # apply new 4.7 patch + $ cd .. + $ mv linux-4.6.1 linux-4.7 # rename source dir -The 2.6.x.y kernels ---- - Kernels with 4-digit versions are -stable kernels. They contain small(ish) +The 4.x.y kernels +================= + +Kernels with 3-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered -in a given 2.6.x kernel. +in a given 4.x kernel. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is the current stable kernel. - note: the -stable team usually do make incremental patches available as well +.. note:: + + The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ -These patches are not incremental, meaning that for example the 2.6.12.3 -patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source . -So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel -source you have to first back out the 2.6.12.2 patch (so you are left with a -base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. +These patches are not incremental, meaning that for example the 4.7.3 +patch does not apply on top of the 4.7.2 kernel source, but rather on top +of the base 4.7 kernel source. -Here's a small example: +So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel +source you have to first back out the 4.7.2 patch (so you are left with a +base 4.7 kernel source) and then apply the new 4.7.3 patch. -$ cd ~/linux-2.6.12.2 # change into the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch -$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch -$ cd .. -$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir +Here's a small example:: + $ cd ~/linux-4.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch + $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch + $ cd .. + $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir The -rc kernels ---- - These are release-candidate kernels. These are development kernels released +=============== + +These are release-candidate kernels. These are development kernels released by Linus whenever he deems the current git (the kernel's source management tool) tree to be in a reasonably sane state adequate for testing. @@ -317,39 +348,44 @@ This is a good branch to run for people who want to help out testing development kernels but do not want to run some of the really experimental stuff (such people should see the sections about -git and -mm kernels below). -The -rc patches are not incremental, they apply to a base 2.6.x kernel, just -like the 2.6.x.y patches described above. The kernel version before the -rcN +The -rc patches are not incremental, they apply to a base 4.x kernel, just +like the 4.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. -So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 -kernel and the patch should be applied on top of the 2.6.12 kernel source. -Here are 3 examples of how to apply these patches: +So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 +kernel and the patch should be applied on top of the 4.7 kernel source. -# first an example of moving from 2.6.12 to 2.6.13-rc3 -$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir +Here are 3 examples of how to apply these patches:: -# now let's move from 2.6.13-rc3 to 2.6.13-rc5 -$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir -$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + # first an example of moving from 4.7 to 4.8-rc3 -# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 -$ cd ~/linux-2.6.12.3 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + $ cd ~/linux-4.7 # change to the 4.7 source dir + $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch + $ cd .. + $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + + # now let's move from 4.8-rc3 to 4.8-rc5 + + $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir + $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch + $ cd .. + $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + + # finally let's try and move from 4.7.3 to 4.8-rc5 + + $ cd ~/linux-4.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd .. + $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir The -git kernels ---- - These are daily snapshots of Linus' kernel tree (managed in a git +================ + +These are daily snapshots of Linus' kernel tree (managed in a git repository, hence the name). These patches are usually released daily and represent the current state of @@ -357,91 +393,66 @@ Linus's tree. They are more experimental than -rc kernels since they are generated automatically without even a cursory glance to see if they are sane. --git patches are not incremental and apply either to a base 2.6.x kernel or -a base 2.6.x-rc kernel -- you can see which from their name. -A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch -named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. - -Here are some examples of how to apply these patches: - -# moving from 2.6.12 to 2.6.12-git1 -$ cd ~/linux-2.6.12 # change to the kernel source dir -$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir - -# moving from 2.6.12-git1 to 2.6.13-rc2-git3 -$ cd ~/linux-2.6.12-git1 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel -$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 -$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 -$ cd .. -$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir - - -The -mm kernels ---- - These are experimental kernels released by Andrew Morton. - -The -mm tree serves as a sort of proving ground for new features and other -experimental patches. -Once a patch has proved its worth in -mm for a while Andrew pushes it on to -Linus for inclusion in mainline. - -Although it's encouraged that patches flow to Linus via the -mm tree, this -is not always enforced. -Subsystem maintainers (or individuals) sometimes push their patches directly -to Linus, even though (or after) they have been merged and tested in -mm (or -sometimes even without prior testing in -mm). - -You should generally strive to get your patches into mainline via -mm to -ensure maximum testing. - -This branch is in constant flux and contains many experimental features, a +-git patches are not incremental and apply either to a base 4.x kernel or +a base 4.x-rc kernel -- you can see which from their name. +A patch named 4.7-git1 applies to the 4.7 kernel source and a patch +named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. + +Here are some examples of how to apply these patches:: + + # moving from 4.7 to 4.7-git1 + + $ cd ~/linux-4.7 # change to the kernel source dir + $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch + $ cd .. + $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir + + # moving from 4.7-git1 to 4.8-rc2-git3 + + $ cd ~/linux-4.7-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch + # we now have a 4.7 kernel + $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch + # the kernel is now 4.8-rc2 + $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch + # the kernel is now 4.8-rc2-git3 + $ cd .. + $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir + + +The -mm patches and the linux-next tree +======================================= + +The -mm patches are experimental patches released by Andrew Morton. + +In the past, -mm tree were used to also test subsystem patches, but this +function is now done via the +:ref:`linux-next ` +tree. The Subsystem maintainers push their patches first to linux-next, +and, during the merge window, sends them directly to Linus. + +The -mm patches serve as a sort of proving ground for new features and other +experimental patches that aren't merged via a subsystem tree. +Once such patches has proved its worth in -mm for a while Andrew pushes +it on to Linus for inclusion in mainline. + +The linux-next tree is daily updated, and includes the -mm patches. +Both are in constant flux and contains many experimental features, a lot of debugging patches not appropriate for mainline etc., and is the most experimental of the branches described in this document. -These kernels are not appropriate for use on systems that are supposed to be +These patches are not appropriate for use on systems that are supposed to be stable and they are more risky to run than any of the other branches (make sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm kernels). - -These kernels in addition to all the other experimental patches they contain -usually also contain any changes in the mainline -git kernels available at -the time of release. - -Testing of -mm kernels is greatly appreciated since the whole point of the -tree is to weed out regressions, crashes, data corruption bugs, build -breakage (and any other bug in general) before changes are merged into the -more stable mainline Linus tree. -But testers of -mm should be aware that breakage in this tree is more common -than in any other tree. - -The -mm kernels are not released on a fixed schedule, but usually a few -mm -kernels are released in between each -rc kernel (1 to 3 is common). -The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels -have been released yet) or to a Linus -rc kernel. - -Here are some examples of applying the -mm patches: - -# moving from 2.6.12 to 2.6.12-mm1 -$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir -$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately - -# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 -$ cd ~/linux-2.6.12-mm1 -$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source -$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch -$ cd .. -$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir +even more so for -mm patches or using a Kernel from the linux-next tree). + +Testing of -mm patches and linux-next is greatly appreciated since the whole +point of those are to weed out regressions, crashes, data corruption bugs, +build breakage (and any other bug in general) before changes are merged into +the more stable mainline Linus tree. + +But testers of -mm and linux-next should be aware that breakages are +more common than in any other tree. This concludes this list of explanations of the various kernel trees. diff --git a/Documentation/arm/00-INDEX b/Documentation/arm/00-INDEX index dea011c8d7c7..b6e69fd371c4 100644 --- a/Documentation/arm/00-INDEX +++ b/Documentation/arm/00-INDEX @@ -8,8 +8,6 @@ Interrupts - ARM Interrupt subsystem documentation IXP4xx - Intel IXP4xx Network processor. -Makefile - - Build sourcefiles as part of the Documentation-build for arm Netwinder - Netwinder specific documentation Porting diff --git a/Documentation/arm/CCN.txt b/Documentation/arm/CCN.txt index ffca443a19b4..15cdb7bc57c3 100644 --- a/Documentation/arm/CCN.txt +++ b/Documentation/arm/CCN.txt @@ -18,13 +18,17 @@ and config2 fields of the perf_event_attr structure. The "events" directory provides configuration templates for all documented events, that can be used with perf tool. For example "xp_valid_flit" is an equivalent of "type=0x8,event=0x4". Other parameters must be -explicitly specified. For events originating from device, "node" -defines its index. All crosspoint events require "xp" (index), -"port" (device port number) and "vc" (virtual channel ID) and -"dir" (direction). Watchpoints (special "event" value 0xfe) also -require comparator values ("cmp_l" and "cmp_h") and "mask", being -index of the comparator mask. +explicitly specified. +For events originating from device, "node" defines its index. + +Crosspoint PMU events require "xp" (index), "bus" (bus number) +and "vc" (virtual channel ID). + +Crosspoint watchpoint-based events (special "event" value 0xfe) +require "xp" and "vc" as as above plus "port" (device port index), +"dir" (transmit/receive direction), comparator values ("cmp_l" +and "cmp_h") and "mask", being index of the comparator mask. Masks are defined separately from the event description (due to limited number of the config values) in the "cmp_mask" directory, with first 8 configurable by user and additional diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index e5a115f24471..cd0243302bc1 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -31,6 +31,8 @@ SunXi family + User Manual http://dl.linux-sunxi.org/A13/A13%20User%20Manual%20-%20v1.2%20%282013-01-08%29.pdf + - Next Thing Co GR8 (sun5i) + * Dual ARM Cortex-A7 based SoCs - Allwinner A20 (sun7i) + User Manual @@ -73,4 +75,13 @@ SunXi family * Octa ARM Cortex-A7 based SoCs - Allwinner A83T + Datasheet - http://dl.linux-sunxi.org/A83T/A83T_datasheet_Revision_1.1.pdf + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf + + User Manual + https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf + + * Quad ARM Cortex-A53 based SoCs + - Allwinner A64 + + Datasheet + http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf + + User Manual + http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index ccc60324e738..405da11fc3e4 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -61,3 +61,5 @@ stable kernels. | Cavium | ThunderX GICv3 | #23154 | CAVIUM_ERRATUM_23154 | | Cavium | ThunderX Core | #27456 | CAVIUM_ERRATUM_27456 | | Cavium | ThunderX SMMUv2 | #27704 | N/A | +| | | | | +| Freescale/NXP | LS2080A/LS1043A | A-008585 | FSL_ERRATUM_A008585 | diff --git a/Documentation/auxdisplay/.gitignore b/Documentation/auxdisplay/.gitignore deleted file mode 100644 index 7af222860a96..000000000000 --- a/Documentation/auxdisplay/.gitignore +++ /dev/null @@ -1 +0,0 @@ -cfag12864b-example diff --git a/Documentation/auxdisplay/Makefile b/Documentation/auxdisplay/Makefile deleted file mode 100644 index ada4dac99ef4..000000000000 --- a/Documentation/auxdisplay/Makefile +++ /dev/null @@ -1,7 +0,0 @@ -# List of programs to build -hostprogs-y := cfag12864b-example - -# Tell kbuild to always build the programs -always := $(hostprogs-y) - -HOSTCFLAGS_cfag12864b-example.o += -I$(objtree)/usr/include diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b index eb7be393a510..12fd51b8de75 100644 --- a/Documentation/auxdisplay/cfag12864b +++ b/Documentation/auxdisplay/cfag12864b @@ -101,5 +101,5 @@ Although the LCD won't get updated until the next refresh time arrives. Also, you can mmap the framebuffer: open & mmap, munmap & close... which is the best option for most uses. -Check Documentation/auxdisplay/cfag12864b-example.c +Check samples/auxdisplay/cfag12864b-example.c for a real working userspace complete program with usage examples. diff --git a/Documentation/auxdisplay/cfag12864b-example.c b/Documentation/auxdisplay/cfag12864b-example.c deleted file mode 100644 index e7823ffb1ca0..000000000000 --- a/Documentation/auxdisplay/cfag12864b-example.c +++ /dev/null @@ -1,281 +0,0 @@ -/* - * Filename: cfag12864b-example.c - * Version: 0.1.0 - * Description: cfag12864b LCD userspace example program - * License: GPLv2 - * - * Author: Copyright (C) Miguel Ojeda Sandonis - * Date: 2006-10-31 - * - * This program 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 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. - * - * 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 - * - */ - -/* - * ------------------------ - * start of cfag12864b code - * ------------------------ - */ - -#include -#include -#include -#include -#include -#include - -#define CFAG12864B_WIDTH (128) -#define CFAG12864B_HEIGHT (64) -#define CFAG12864B_SIZE (128 * 64 / 8) -#define CFAG12864B_BPB (8) -#define CFAG12864B_ADDRESS(x, y) ((y) * CFAG12864B_WIDTH / \ - CFAG12864B_BPB + (x) / CFAG12864B_BPB) -#define CFAG12864B_BIT(n) (((unsigned char) 1) << (n)) - -#undef CFAG12864B_DOCHECK -#ifdef CFAG12864B_DOCHECK - #define CFAG12864B_CHECK(x, y) ((x) < CFAG12864B_WIDTH && \ - (y) < CFAG12864B_HEIGHT) -#else - #define CFAG12864B_CHECK(x, y) (1) -#endif - -int cfag12864b_fd; -unsigned char * cfag12864b_mem; -unsigned char cfag12864b_buffer[CFAG12864B_SIZE]; - -/* - * init a cfag12864b framebuffer device - * - * No error: return = 0 - * Unable to open: return = -1 - * Unable to mmap: return = -2 - */ -static int cfag12864b_init(char *path) -{ - cfag12864b_fd = open(path, O_RDWR); - if (cfag12864b_fd == -1) - return -1; - - cfag12864b_mem = mmap(0, CFAG12864B_SIZE, PROT_READ | PROT_WRITE, - MAP_SHARED, cfag12864b_fd, 0); - if (cfag12864b_mem == MAP_FAILED) { - close(cfag12864b_fd); - return -2; - } - - return 0; -} - -/* - * exit a cfag12864b framebuffer device - */ -static void cfag12864b_exit(void) -{ - munmap(cfag12864b_mem, CFAG12864B_SIZE); - close(cfag12864b_fd); -} - -/* - * set (x, y) pixel - */ -static void cfag12864b_set(unsigned char x, unsigned char y) -{ - if (CFAG12864B_CHECK(x, y)) - cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] |= - CFAG12864B_BIT(x % CFAG12864B_BPB); -} - -/* - * unset (x, y) pixel - */ -static void cfag12864b_unset(unsigned char x, unsigned char y) -{ - if (CFAG12864B_CHECK(x, y)) - cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] &= - ~CFAG12864B_BIT(x % CFAG12864B_BPB); -} - -/* - * is set (x, y) pixel? - * - * Pixel off: return = 0 - * Pixel on: return = 1 - */ -static unsigned char cfag12864b_isset(unsigned char x, unsigned char y) -{ - if (CFAG12864B_CHECK(x, y)) - if (cfag12864b_buffer[CFAG12864B_ADDRESS(x, y)] & - CFAG12864B_BIT(x % CFAG12864B_BPB)) - return 1; - - return 0; -} - -/* - * not (x, y) pixel - */ -static void cfag12864b_not(unsigned char x, unsigned char y) -{ - if (cfag12864b_isset(x, y)) - cfag12864b_unset(x, y); - else - cfag12864b_set(x, y); -} - -/* - * fill (set all pixels) - */ -static void cfag12864b_fill(void) -{ - unsigned short i; - - for (i = 0; i < CFAG12864B_SIZE; i++) - cfag12864b_buffer[i] = 0xFF; -} - -/* - * clear (unset all pixels) - */ -static void cfag12864b_clear(void) -{ - unsigned short i; - - for (i = 0; i < CFAG12864B_SIZE; i++) - cfag12864b_buffer[i] = 0; -} - -/* - * format a [128*64] matrix - * - * Pixel off: src[i] = 0 - * Pixel on: src[i] > 0 - */ -static void cfag12864b_format(unsigned char * matrix) -{ - unsigned char i, j, n; - - for (i = 0; i < CFAG12864B_HEIGHT; i++) - for (j = 0; j < CFAG12864B_WIDTH / CFAG12864B_BPB; j++) { - cfag12864b_buffer[i * CFAG12864B_WIDTH / CFAG12864B_BPB + - j] = 0; - for (n = 0; n < CFAG12864B_BPB; n++) - if (matrix[i * CFAG12864B_WIDTH + - j * CFAG12864B_BPB + n]) - cfag12864b_buffer[i * CFAG12864B_WIDTH / - CFAG12864B_BPB + j] |= - CFAG12864B_BIT(n); - } -} - -/* - * blit buffer to lcd - */ -static void cfag12864b_blit(void) -{ - memcpy(cfag12864b_mem, cfag12864b_buffer, CFAG12864B_SIZE); -} - -/* - * ---------------------- - * end of cfag12864b code - * ---------------------- - */ - -#include - -#define EXAMPLES 6 - -static void example(unsigned char n) -{ - unsigned short i, j; - unsigned char matrix[CFAG12864B_WIDTH * CFAG12864B_HEIGHT]; - - if (n > EXAMPLES) - return; - - printf("Example %i/%i - ", n, EXAMPLES); - - switch (n) { - case 1: - printf("Draw points setting bits"); - cfag12864b_clear(); - for (i = 0; i < CFAG12864B_WIDTH; i += 2) - for (j = 0; j < CFAG12864B_HEIGHT; j += 2) - cfag12864b_set(i, j); - break; - - case 2: - printf("Clear the LCD"); - cfag12864b_clear(); - break; - - case 3: - printf("Draw rows formatting a [128*64] matrix"); - memset(matrix, 0, CFAG12864B_WIDTH * CFAG12864B_HEIGHT); - for (i = 0; i < CFAG12864B_WIDTH; i++) - for (j = 0; j < CFAG12864B_HEIGHT; j += 2) - matrix[j * CFAG12864B_WIDTH + i] = 1; - cfag12864b_format(matrix); - break; - - case 4: - printf("Fill the lcd"); - cfag12864b_fill(); - break; - - case 5: - printf("Draw columns unsetting bits"); - for (i = 0; i < CFAG12864B_WIDTH; i += 2) - for (j = 0; j < CFAG12864B_HEIGHT; j++) - cfag12864b_unset(i, j); - break; - - case 6: - printf("Do negative not-ing all bits"); - for (i = 0; i < CFAG12864B_WIDTH; i++) - for (j = 0; j < CFAG12864B_HEIGHT; j ++) - cfag12864b_not(i, j); - break; - } - - puts(" - [Press Enter]"); -} - -int main(int argc, char *argv[]) -{ - unsigned char n; - - if (argc != 2) { - printf( - "Sintax: %s fbdev\n" - "Usually: /dev/fb0, /dev/fb1...\n", argv[0]); - return -1; - } - - if (cfag12864b_init(argv[1])) { - printf("Can't init %s fbdev\n", argv[1]); - return -2; - } - - for (n = 1; n <= EXAMPLES; n++) { - example(n); - cfag12864b_blit(); - while (getchar() != '\n'); - } - - cfag12864b_exit(); - - return 0; -} diff --git a/Documentation/blackfin/00-INDEX b/Documentation/blackfin/00-INDEX index c54fcdd4ae9f..265a1effebde 100644 --- a/Documentation/blackfin/00-INDEX +++ b/Documentation/blackfin/00-INDEX @@ -1,10 +1,6 @@ 00-INDEX - This file -Makefile - - Makefile for gptimers example file. bfin-gpio-notes.txt - Notes in developing/using bfin-gpio driver. bfin-spi-notes.txt - Notes for using bfin spi bus driver. -gptimers-example.c - - gptimers example diff --git a/Documentation/blackfin/Makefile b/Documentation/blackfin/Makefile deleted file mode 100644 index 6782c58fbc29..000000000000 --- a/Documentation/blackfin/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -ifneq ($(CONFIG_BLACKFIN),) -ifneq ($(CONFIG_BFIN_GPTIMERS),) -obj-m := gptimers-example.o -endif -endif diff --git a/Documentation/blackfin/gptimers-example.c b/Documentation/blackfin/gptimers-example.c deleted file mode 100644 index 283eba993d9d..000000000000 --- a/Documentation/blackfin/gptimers-example.c +++ /dev/null @@ -1,91 +0,0 @@ -/* - * Simple gptimers example - * http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:gptimers - * - * Copyright 2007-2009 Analog Devices Inc. - * - * Licensed under the GPL-2 or later. - */ - -#include -#include - -#include -#include - -/* ... random driver includes ... */ - -#define DRIVER_NAME "gptimer_example" - -#ifdef IRQ_TIMER5 -#define SAMPLE_IRQ_TIMER IRQ_TIMER5 -#else -#define SAMPLE_IRQ_TIMER IRQ_TIMER2 -#endif - -struct gptimer_data { - uint32_t period, width; -}; -static struct gptimer_data data; - -/* ... random driver state ... */ - -static irqreturn_t gptimer_example_irq(int irq, void *dev_id) -{ - struct gptimer_data *data = dev_id; - - /* make sure it was our timer which caused the interrupt */ - if (!get_gptimer_intr(TIMER5_id)) - return IRQ_NONE; - - /* read the width/period values that were captured for the waveform */ - data->width = get_gptimer_pwidth(TIMER5_id); - data->period = get_gptimer_period(TIMER5_id); - - /* acknowledge the interrupt */ - clear_gptimer_intr(TIMER5_id); - - /* tell the upper layers we took care of things */ - return IRQ_HANDLED; -} - -/* ... random driver code ... */ - -static int __init gptimer_example_init(void) -{ - int ret; - - /* grab the peripheral pins */ - ret = peripheral_request(P_TMR5, DRIVER_NAME); - if (ret) { - printk(KERN_NOTICE DRIVER_NAME ": peripheral request failed\n"); - return ret; - } - - /* grab the IRQ for the timer */ - ret = request_irq(SAMPLE_IRQ_TIMER, gptimer_example_irq, - IRQF_SHARED, DRIVER_NAME, &data); - if (ret) { - printk(KERN_NOTICE DRIVER_NAME ": IRQ request failed\n"); - peripheral_free(P_TMR5); - return ret; - } - - /* setup the timer and enable it */ - set_gptimer_config(TIMER5_id, - WDTH_CAP | PULSE_HI | PERIOD_CNT | IRQ_ENA); - enable_gptimers(TIMER5bit); - - return 0; -} -module_init(gptimer_example_init); - -static void __exit gptimer_example_exit(void) -{ - disable_gptimers(TIMER5bit); - free_irq(SAMPLE_IRQ_TIMER, &data); - peripheral_free(P_TMR5); -} -module_exit(gptimer_example_exit); - -MODULE_LICENSE("BSD"); diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index bcdb2b4c1f12..918e1e0d0e78 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -115,7 +115,7 @@ i. Per-queue limits/values exported to the generic layer by the driver Various parameters that the generic i/o scheduler logic uses are set at a per-queue level (e.g maximum request size, maximum number of segments in -a scatter-gather list, hardsect size) +a scatter-gather list, logical block size) Some parameters that were earlier available as global arrays indexed by major/minor are now directly associated with the queue. Some of these may @@ -156,7 +156,7 @@ Some new queue property settings: blk_queue_max_segment_size(q, max_seg_size) Maximum size of a clustered segment, 64kB default. - blk_queue_hardsect_size(q, hardsect_size) + blk_queue_logical_block_size(q, logical_block_size) Lowest possible sector size that the hardware can operate on, 512 bytes default. diff --git a/Documentation/cec.txt b/Documentation/cec.txt deleted file mode 100644 index 75155fe37153..000000000000 --- a/Documentation/cec.txt +++ /dev/null @@ -1,267 +0,0 @@ -CEC Kernel Support -================== - -The CEC framework provides a unified kernel interface for use with HDMI CEC -hardware. It is designed to handle a multiple types of hardware (receivers, -transmitters, USB dongles). The framework also gives the option to decide -what to do in the kernel driver and what should be handled by userspace -applications. In addition it integrates the remote control passthrough -feature into the kernel's remote control framework. - - -The CEC Protocol ----------------- - -The CEC protocol enables consumer electronic devices to communicate with each -other through the HDMI connection. The protocol uses logical addresses in the -communication. The logical address is strictly connected with the functionality -provided by the device. The TV acting as the communication hub is always -assigned address 0. The physical address is determined by the physical -connection between devices. - -The CEC framework described here is up to date with the CEC 2.0 specification. -It is documented in the HDMI 1.4 specification with the new 2.0 bits documented -in the HDMI 2.0 specification. But for most of the features the freely available -HDMI 1.3a specification is sufficient: - -http://www.microprocessor.org/HDMISpecification13a.pdf - - -The Kernel Interface -==================== - -CEC Adapter ------------ - -The struct cec_adapter represents the CEC adapter hardware. It is created by -calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): - -struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, - void *priv, const char *name, u32 caps, u8 available_las, - struct device *parent); -void cec_delete_adapter(struct cec_adapter *adap); - -To create an adapter you need to pass the following information: - -ops: adapter operations which are called by the CEC framework and that you -have to implement. - -priv: will be stored in adap->priv and can be used by the adapter ops. - -name: the name of the CEC adapter. Note: this name will be copied. - -caps: capabilities of the CEC adapter. These capabilities determine the - capabilities of the hardware and which parts are to be handled - by userspace and which parts are handled by kernelspace. The - capabilities are returned by CEC_ADAP_G_CAPS. - -available_las: the number of simultaneous logical addresses that this - adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. - -parent: the parent device. - - -To register the /dev/cecX device node and the remote control device (if -CEC_CAP_RC is set) you call: - -int cec_register_adapter(struct cec_adapter *adap); - -To unregister the devices call: - -void cec_unregister_adapter(struct cec_adapter *adap); - -Note: if cec_register_adapter() fails, then call cec_delete_adapter() to -clean up. But if cec_register_adapter() succeeded, then only call -cec_unregister_adapter() to clean up, never cec_delete_adapter(). The -unregister function will delete the adapter automatically once the last user -of that /dev/cecX device has closed its file handle. - - -Implementing the Low-Level CEC Adapter --------------------------------------- - -The following low-level adapter operations have to be implemented in -your driver: - -struct cec_adap_ops { - /* Low-level callbacks */ - int (*adap_enable)(struct cec_adapter *adap, bool enable); - int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); - int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); - int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, - u32 signal_free_time, struct cec_msg *msg); - void (*adap_log_status)(struct cec_adapter *adap); - - /* High-level callbacks */ - ... -}; - -The three low-level ops deal with various aspects of controlling the CEC adapter -hardware: - - -To enable/disable the hardware: - - int (*adap_enable)(struct cec_adapter *adap, bool enable); - -This callback enables or disables the CEC hardware. Enabling the CEC hardware -means powering it up in a state where no logical addresses are claimed. This -op assumes that the physical address (adap->phys_addr) is valid when enable is -true and will not change while the CEC adapter remains enabled. The initial -state of the CEC adapter after calling cec_allocate_adapter() is disabled. - -Note that adap_enable must return 0 if enable is false. - - -To enable/disable the 'monitor all' mode: - - int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); - -If enabled, then the adapter should be put in a mode to also monitor messages -that not for us. Not all hardware supports this and this function is only -called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional -(some hardware may always be in 'monitor all' mode). - -Note that adap_monitor_all_enable must return 0 if enable is false. - - -To program a new logical address: - - int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); - -If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses -are to be erased. Otherwise the given logical address should be programmed. -If the maximum number of available logical addresses is exceeded, then it -should return -ENXIO. Once a logical address is programmed the CEC hardware -can receive directed messages to that address. - -Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. - - -To transmit a new message: - - int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, - u32 signal_free_time, struct cec_msg *msg); - -This transmits a new message. The attempts argument is the suggested number of -attempts for the transmit. - -The signal_free_time is the number of data bit periods that the adapter should -wait when the line is free before attempting to send a message. This value -depends on whether this transmit is a retry, a message from a new initiator or -a new message for the same initiator. Most hardware will handle this -automatically, but in some cases this information is needed. - -The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to -microseconds (one data bit period is 2.4 ms). - - -To log the current CEC hardware status: - - void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); - -This optional callback can be used to show the status of the CEC hardware. -The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status - - -Your adapter driver will also have to react to events (typically interrupt -driven) by calling into the framework in the following situations: - -When a transmit finished (successfully or otherwise): - -void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, - u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); - -The status can be one of: - -CEC_TX_STATUS_OK: the transmit was successful. -CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator -took control of the CEC line and you lost the arbitration. -CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or -acked (for a broadcast message). A retransmission is needed. -CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This -indicates that a follower detected an error on the bus and requested a -retransmission. -CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of -the previous two if the hardware cannot differentiate or something else -entirely. -CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after -trying multiple times. Should only be set by the driver if it has hardware -support for retrying messages. If set, then the framework assumes that it -doesn't have to make another attempt to transmit the message since the -hardware did that already. - -The *_cnt arguments are the number of error conditions that were seen. -This may be 0 if no information is available. Drivers that do not support -hardware retry can just set the counter corresponding to the transmit error -to 1, if the hardware does support retry then either set these counters to -0 if the hardware provides no feedback of which errors occurred and how many -times, or fill in the correct values as reported by the hardware. - -When a CEC message was received: - -void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); - -Speaks for itself. - -Implementing the High-Level CEC Adapter ---------------------------------------- - -The low-level operations drive the hardware, the high-level operations are -CEC protocol driven. The following high-level callbacks are available: - -struct cec_adap_ops { - /* Low-level callbacks */ - ... - - /* High-level CEC message callback */ - int (*received)(struct cec_adapter *adap, struct cec_msg *msg); -}; - -The received() callback allows the driver to optionally handle a newly -received CEC message - - int (*received)(struct cec_adapter *adap, struct cec_msg *msg); - -If the driver wants to process a CEC message, then it can implement this -callback. If it doesn't want to handle this message, then it should return --ENOMSG, otherwise the CEC framework assumes it processed this message and -it will not no anything with it. - - -CEC framework functions ------------------------ - -CEC Adapter drivers can call the following CEC framework functions: - -int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, - bool block); - -Transmit a CEC message. If block is true, then wait until the message has been -transmitted, otherwise just queue it and return. - -void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); - -Change the physical address. This function will set adap->phys_addr and -send an event if it has changed. If cec_s_log_addrs() has been called and -the physical address has become valid, then the CEC framework will start -claiming the logical addresses. If block is true, then this function won't -return until this process has finished. - -When the physical address is set to a valid value the CEC adapter will -be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, -then the CEC adapter will be disabled. If you change a valid physical address -to another valid physical address, then this function will first set the -address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. - -int cec_s_log_addrs(struct cec_adapter *adap, - struct cec_log_addrs *log_addrs, bool block); - -Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS -is set. If block is true, then wait until the logical addresses have been -claimed, otherwise just queue it and return. To unconfigure all logical -addresses call this function with log_addrs set to NULL or with -log_addrs->num_log_addrs set to 0. The block argument is ignored when -unconfiguring. This function will just return if the physical address is -invalid. Once the physical address becomes valid, then the framework will -attempt to claim these logical addresses. diff --git a/Documentation/clk.txt b/Documentation/clk.txt index 5c4bc4d01d0c..22f026aa2f34 100644 --- a/Documentation/clk.txt +++ b/Documentation/clk.txt @@ -31,24 +31,25 @@ serve as a convenient shorthand for the implementation of the hardware-specific bits for the hypothetical "foo" hardware. Tying the two halves of this interface together is struct clk_hw, which -is defined in struct clk_foo and pointed to within struct clk. This +is defined in struct clk_foo and pointed to within struct clk_core. This allows for easy navigation between the two discrete halves of the common clock interface. Part 2 - common data structures and api -Below is the common struct clk definition from -include/linux/clk-private.h, modified for brevity: +Below is the common struct clk_core definition from +drivers/clk/clk.c, modified for brevity: - struct clk { + struct clk_core { const char *name; const struct clk_ops *ops; struct clk_hw *hw; - char **parent_names; - struct clk **parents; - struct clk *parent; - struct hlist_head children; - struct hlist_node child_node; + struct module *owner; + struct clk_core *parent; + const char **parent_names; + struct clk_core **parents; + u8 num_parents; + u8 new_parent_index; ... }; @@ -56,16 +57,19 @@ The members above make up the core of the clk tree topology. The clk api itself defines several driver-facing functions which operate on struct clk. That api is documented in include/linux/clk.h. -Platforms and devices utilizing the common struct clk use the struct -clk_ops pointer in struct clk to perform the hardware-specific parts of -the operations defined in clk.h: +Platforms and devices utilizing the common struct clk_core use the struct +clk_ops pointer in struct clk_core to perform the hardware-specific parts of +the operations defined in clk-provider.h: struct clk_ops { int (*prepare)(struct clk_hw *hw); void (*unprepare)(struct clk_hw *hw); + int (*is_prepared)(struct clk_hw *hw); + void (*unprepare_unused)(struct clk_hw *hw); int (*enable)(struct clk_hw *hw); void (*disable)(struct clk_hw *hw); int (*is_enabled)(struct clk_hw *hw); + void (*disable_unused)(struct clk_hw *hw); unsigned long (*recalc_rate)(struct clk_hw *hw, unsigned long parent_rate); long (*round_rate)(struct clk_hw *hw, @@ -84,6 +88,8 @@ the operations defined in clk.h: u8 index); unsigned long (*recalc_accuracy)(struct clk_hw *hw, unsigned long parent_accuracy); + int (*get_phase)(struct clk_hw *hw); + int (*set_phase)(struct clk_hw *hw, int degrees); void (*init)(struct clk_hw *hw); int (*debug_init)(struct clk_hw *hw, struct dentry *dentry); @@ -91,7 +97,7 @@ the operations defined in clk.h: Part 3 - hardware clk implementations -The strength of the common struct clk comes from its .ops and .hw pointers +The strength of the common struct clk_core comes from its .ops and .hw pointers which abstract the details of struct clk from the hardware-specific bits, and vice versa. To illustrate consider the simple gateable clk implementation in drivers/clk/clk-gate.c: @@ -107,7 +113,7 @@ struct clk_gate contains struct clk_hw hw as well as hardware-specific knowledge about which register and bit controls this clk's gating. Nothing about clock topology or accounting, such as enable_count or notifier_count, is needed here. That is all handled by the common -framework code and struct clk. +framework code and struct clk_core. Let's walk through enabling this clk from driver code: @@ -139,22 +145,18 @@ static void clk_gate_set_bit(struct clk_gate *gate) Note that to_clk_gate is defined as: -#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, clk) +#define to_clk_gate(_hw) container_of(_hw, struct clk_gate, hw) This pattern of abstraction is used for every clock hardware representation. Part 4 - supporting your own clk hardware -When implementing support for a new type of clock it only necessary to +When implementing support for a new type of clock it is only necessary to include the following header: #include -include/linux/clk.h is included within that header and clk-private.h -must never be included from the code which implements the operations for -a clock. More on that below in Part 5. - To construct a clk hardware structure for your platform you must define the following: diff --git a/Documentation/coccinelle.txt b/Documentation/coccinelle.txt deleted file mode 100644 index 01fb1dae3163..000000000000 --- a/Documentation/coccinelle.txt +++ /dev/null @@ -1,470 +0,0 @@ -Copyright 2010 Nicolas Palix -Copyright 2010 Julia Lawall -Copyright 2010 Gilles Muller - - - Getting Coccinelle -~~~~~~~~~~~~~~~~~~~~ - -The semantic patches included in the kernel use features and options -which are provided by Coccinelle version 1.0.0-rc11 and above. -Using earlier versions will fail as the option names used by -the Coccinelle files and coccicheck have been updated. - -Coccinelle is available through the package manager -of many distributions, e.g. : - - - Debian - - Fedora - - Ubuntu - - OpenSUSE - - Arch Linux - - NetBSD - - FreeBSD - - -You can get the latest version released from the Coccinelle homepage at -http://coccinelle.lip6.fr/ - -Information and tips about Coccinelle are also provided on the wiki -pages at http://cocci.ekstranet.diku.dk/wiki/doku.php - -Once you have it, run the following command: - - ./configure - make - -as a regular user, and install it with - - sudo make install - - Supplemental documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For supplemental documentation refer to the wiki: - -https://bottest.wiki.kernel.org/coccicheck - -The wiki documentation always refers to the linux-next version of the script. - - Using Coccinelle on the Linux kernel -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A Coccinelle-specific target is defined in the top level -Makefile. This target is named 'coccicheck' and calls the 'coccicheck' -front-end in the 'scripts' directory. - -Four basic modes are defined: patch, report, context, and org. The mode to -use is specified by setting the MODE variable with 'MODE='. - -'patch' proposes a fix, when possible. - -'report' generates a list in the following format: - file:line:column-column: message - -'context' highlights lines of interest and their context in a -diff-like style.Lines of interest are indicated with '-'. - -'org' generates a report in the Org mode format of Emacs. - -Note that not all semantic patches implement all modes. For easy use -of Coccinelle, the default mode is "report". - -Two other modes provide some common combinations of these modes. - -'chain' tries the previous modes in the order above until one succeeds. - -'rep+ctxt' runs successively the report mode and the context mode. - It should be used with the C option (described later) - which checks the code on a file basis. - -Examples: - To make a report for every semantic patch, run the following command: - - make coccicheck MODE=report - - To produce patches, run: - - make coccicheck MODE=patch - - -The coccicheck target applies every semantic patch available in the -sub-directories of 'scripts/coccinelle' to the entire Linux kernel. - -For each semantic patch, a commit message is proposed. It gives a -description of the problem being checked by the semantic patch, and -includes a reference to Coccinelle. - -As any static code analyzer, Coccinelle produces false -positives. Thus, reports must be carefully checked, and patches -reviewed. - -To enable verbose messages set the V= variable, for example: - - make coccicheck MODE=report V=1 - - Coccinelle parallelization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, coccicheck tries to run as parallel as possible. To change -the parallelism, set the J= variable. For example, to run across 4 CPUs: - - make coccicheck MODE=report J=4 - -As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, -if support for this is detected you will benefit from parmap parallelization. - -When parmap is enabled coccicheck will enable dynamic load balancing by using -'--chunksize 1' argument, this ensures we keep feeding threads with work -one by one, so that we avoid the situation where most work gets done by only -a few threads. With dynamic load balancing, if a thread finishes early we keep -feeding it more work. - -When parmap is enabled, if an error occurs in Coccinelle, this error -value is propagated back, the return value of the 'make coccicheck' -captures this return value. - - Using Coccinelle with a single semantic patch -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The optional make variable COCCI can be used to check a single -semantic patch. In that case, the variable must be initialized with -the name of the semantic patch to apply. - -For instance: - - make coccicheck COCCI= MODE=patch -or - make coccicheck COCCI= MODE=report - - - Controlling Which Files are Processed by Coccinelle -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default the entire kernel source tree is checked. - -To apply Coccinelle to a specific directory, M= can be used. -For example, to check drivers/net/wireless/ one may write: - - make coccicheck M=drivers/net/wireless/ - -To apply Coccinelle on a file basis, instead of a directory basis, the -following command may be used: - - make C=1 CHECK="scripts/coccicheck" - -To check only newly edited code, use the value 2 for the C flag, i.e. - - make C=2 CHECK="scripts/coccicheck" - -In these modes, which works on a file basis, there is no information -about semantic patches displayed, and no commit message proposed. - -This runs every semantic patch in scripts/coccinelle by default. The -COCCI variable may additionally be used to only apply a single -semantic patch as shown in the previous section. - -The "report" mode is the default. You can select another one with the -MODE variable explained above. - - Debugging Coccinelle SmPL patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Using coccicheck is best as it provides in the spatch command line -include options matching the options used when we compile the kernel. -You can learn what these options are by using V=1, you could then -manually run Coccinelle with debug options added. - -Alternatively you can debug running Coccinelle against SmPL patches -by asking for stderr to be redirected to stderr, by default stderr -is redirected to /dev/null, if you'd like to capture stderr you -can specify the DEBUG_FILE="file.txt" option to coccicheck. For -instance: - - rm -f cocci.err - make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err - cat cocci.err - -You can use SPFLAGS to add debugging flags, for instance you may want to -add both --profile --show-trying to SPFLAGS when debugging. For instance -you may want to use: - - rm -f err.log - export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci - make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c - -err.log will now have the profiling information, while stdout will -provide some progress information as Coccinelle moves forward with -work. - -DEBUG_FILE support is only supported when using coccinelle >= 1.2. - - .cocciconfig support -~~~~~~~~~~~~~~~~~~~~~~ - -Coccinelle supports reading .cocciconfig for default Coccinelle options that -should be used every time spatch is spawned, the order of precedence for -variables for .cocciconfig is as follows: - - o Your current user's home directory is processed first - o Your directory from which spatch is called is processed next - o The directory provided with the --dir option is processed last, if used - -Since coccicheck runs through make, it naturally runs from the kernel -proper dir, as such the second rule above would be implied for picking up a -.cocciconfig when using 'make coccicheck'. - -'make coccicheck' also supports using M= targets.If you do not supply -any M= target, it is assumed you want to target the entire kernel. -The kernel coccicheck script has: - - if [ "$KBUILD_EXTMOD" = "" ] ; then - OPTIONS="--dir $srctree $COCCIINCLUDE" - else - OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" - fi - -KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases -the spatch --dir argument is used, as such third rule applies when whether M= -is used or not, and when M= is used the target directory can have its own -.cocciconfig file. When M= is not passed as an argument to coccicheck the -target directory is the same as the directory from where spatch was called. - -If not using the kernel's coccicheck target, keep the above precedence -order logic of .cocciconfig reading. If using the kernel's coccicheck target, -override any of the kernel's .coccicheck's settings using SPFLAGS. - -We help Coccinelle when used against Linux with a set of sensible defaults -options for Linux with our own Linux .cocciconfig. This hints to coccinelle -git can be used for 'git grep' queries over coccigrep. A timeout of 200 -seconds should suffice for now. - -The options picked up by coccinelle when reading a .cocciconfig do not appear -as arguments to spatch processes running on your system, to confirm what -options will be used by Coccinelle run: - - spatch --print-options-only - -You can override with your own preferred index option by using SPFLAGS. Take -note that when there are conflicting options Coccinelle takes precedence for -the last options passed. Using .cocciconfig is possible to use idutils, however -given the order of precedence followed by Coccinelle, since the kernel now -carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if -desired. See below section "Additional flags" for more details on how to use -idutils. - - Additional flags -~~~~~~~~~~~~~~~~~~ - -Additional flags can be passed to spatch through the SPFLAGS -variable. This works as Coccinelle respects the last flags -given to it when options are in conflict. - - make SPFLAGS=--use-glimpse coccicheck - -Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. -When no ID file is specified coccinelle assumes your ID database file -is in the file .id-utils.index on the top level of the kernel, coccinelle -carries a script scripts/idutils_index.sh which creates the database with - - mkid -i C --output .id-utils.index - -If you have another database filename you can also just symlink with this -name. - - make SPFLAGS=--use-idutils coccicheck - -Alternatively you can specify the database filename explicitly, for -instance: - - make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck - -See spatch --help to learn more about spatch options. - -Note that the '--use-glimpse' and '--use-idutils' options -require external tools for indexing the code. None of them is -thus active by default. However, by indexing the code with -one of these tools, and according to the cocci file used, -spatch could proceed the entire code base more quickly. - - SmPL patch specific options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -SmPL patches can have their own requirements for options passed -to Coccinelle. SmPL patch specific options can be provided by -providing them at the top of the SmPL patch, for instance: - -// Options: --no-includes --include-headers - - SmPL patch Coccinelle requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As Coccinelle features get added some more advanced SmPL patches -may require newer versions of Coccinelle. If an SmPL patch requires -at least a version of Coccinelle, this can be specified as follows, -as an example if requiring at least Coccinelle >= 1.0.5: - -// Requires: 1.0.5 - - Proposing new semantic patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New semantic patches can be proposed and submitted by kernel -developers. For sake of clarity, they should be organized in the -sub-directories of 'scripts/coccinelle/'. - - - Detailed description of the 'report' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -'report' generates a list in the following format: - file:line:column-column: message - -Example: - -Running - - make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci - -will execute the following part of the SmPL script. - - -@r depends on !context && !patch && (org || report)@ -expression x; -position p; -@@ - - ERR_PTR@p(PTR_ERR(x)) - -@script:python depends on report@ -p << r.p; -x << r.x; -@@ - -msg="ERR_CAST can be used with %s" % (x) -coccilib.report.print_report(p[0], msg) - - -This SmPL excerpt generates entries on the standard output, as -illustrated below: - -/home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg -/home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth -/home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg - - - Detailed description of the 'patch' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When the 'patch' mode is available, it proposes a fix for each problem -identified. - -Example: - -Running - make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci - -will execute the following part of the SmPL script. - - -@ depends on !context && patch && !org && !report @ -expression x; -@@ - -- ERR_PTR(PTR_ERR(x)) -+ ERR_CAST(x) - - -This SmPL excerpt generates patch hunks on the standard output, as -illustrated below: - -diff -u -p a/crypto/ctr.c b/crypto/ctr.c ---- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 -+++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 -@@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct - alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, - CRYPTO_ALG_TYPE_MASK); - if (IS_ERR(alg)) -- return ERR_PTR(PTR_ERR(alg)); -+ return ERR_CAST(alg); - - /* Block size must be >= 4 bytes. */ - err = -EINVAL; - - Detailed description of the 'context' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -'context' highlights lines of interest and their context -in a diff-like style. - -NOTE: The diff-like output generated is NOT an applicable patch. The - intent of the 'context' mode is to highlight the important lines - (annotated with minus, '-') and gives some surrounding context - lines around. This output can be used with the diff mode of - Emacs to review the code. - -Example: - -Running - make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci - -will execute the following part of the SmPL script. - - -@ depends on context && !patch && !org && !report@ -expression x; -@@ - -* ERR_PTR(PTR_ERR(x)) - - -This SmPL excerpt generates diff hunks on the standard output, as -illustrated below: - -diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing ---- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 -+++ /tmp/nothing -@@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct - alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, - CRYPTO_ALG_TYPE_MASK); - if (IS_ERR(alg)) -- return ERR_PTR(PTR_ERR(alg)); - - /* Block size must be >= 4 bytes. */ - err = -EINVAL; - - Detailed description of the 'org' mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -'org' generates a report in the Org mode format of Emacs. - -Example: - -Running - make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci - -will execute the following part of the SmPL script. - - -@r depends on !context && !patch && (org || report)@ -expression x; -position p; -@@ - - ERR_PTR@p(PTR_ERR(x)) - -@script:python depends on org@ -p << r.p; -x << r.x; -@@ - -msg="ERR_CAST can be used with %s" % (x) -msg_safe=msg.replace("[","@(").replace("]",")") -coccilib.org.print_todo(p[0], msg_safe) - - -This SmPL excerpt generates Org entries on the standard output, as -illustrated below: - -* TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] -* TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] -* TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/Documentation/conf.py b/Documentation/conf.py index 106ae9c740b9..bf6f310e5170 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -14,11 +14,17 @@ import sys import os +import sphinx + +# Get Sphinx version +major, minor, patch = map(int, sphinx.__version__.split(".")) + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('sphinx')) +from load_config import loadConfig # -- General configuration ------------------------------------------------ @@ -28,14 +34,13 @@ sys.path.insert(0, os.path.abspath('sphinx')) # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include'] +extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include', 'cdomain'] -# Gracefully handle missing rst2pdf. -try: - import rst2pdf - extensions += ['rst2pdf.pdfbuilder'] -except ImportError: - pass +# The name of the math extension changed on Sphinx 1.4 +if minor > 3: + extensions.append("sphinx.ext.imgmath") +else: + extensions.append("sphinx.ext.pngmath") # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -252,23 +257,92 @@ htmlhelp_basename = 'TheLinuxKerneldoc' latex_elements = { # The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', +'papersize': 'a4paper', # The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', +'pointsize': '8pt', # Latex figure (float) alignment #'figure_align': 'htbp', + +# Don't mangle with UTF-8 chars +'inputenc': '', +'utf8extra': '', + +# Additional stuff for the LaTeX preamble. + 'preamble': ''' + % Adjust margins + \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry} + + % Allow generate some pages in landscape + \\usepackage{lscape} + + % Put notes in color and let them be inside a table + \\definecolor{NoteColor}{RGB}{204,255,255} + \\definecolor{WarningColor}{RGB}{255,204,204} + \\definecolor{AttentionColor}{RGB}{255,255,204} + \\definecolor{OtherColor}{RGB}{204,204,204} + \\newlength{\\mynoticelength} + \\makeatletter\\newenvironment{coloredbox}[1]{% + \\setlength{\\fboxrule}{1pt} + \\setlength{\\fboxsep}{7pt} + \\setlength{\\mynoticelength}{\\linewidth} + \\addtolength{\\mynoticelength}{-2\\fboxsep} + \\addtolength{\\mynoticelength}{-2\\fboxrule} + \\begin{lrbox}{\\@tempboxa}\\begin{minipage}{\\mynoticelength}}{\\end{minipage}\\end{lrbox}% + \\ifthenelse% + {\\equal{\\py@noticetype}{note}}% + {\\colorbox{NoteColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{warning}}% + {\\colorbox{WarningColor}{\\usebox{\\@tempboxa}}}% + {% + \\ifthenelse% + {\\equal{\\py@noticetype}{attention}}% + {\\colorbox{AttentionColor}{\\usebox{\\@tempboxa}}}% + {\\colorbox{OtherColor}{\\usebox{\\@tempboxa}}}% + }% + }% + }\\makeatother + + \\makeatletter + \\renewenvironment{notice}[2]{% + \\def\\py@noticetype{#1} + \\begin{coloredbox}{#1} + \\bf\\it + \\par\\strong{#2} + \\csname py@noticestart@#1\\endcsname + } + { + \\csname py@noticeend@\\py@noticetype\\endcsname + \\end{coloredbox} + } + \\makeatother + + % Use some font with UTF-8 support with XeLaTeX + \\usepackage{fontspec} + \\setsansfont{DejaVu Serif} + \\setromanfont{DejaVu Sans} + \\setmonofont{DejaVu Sans Mono} + + % To allow adjusting table sizes + \\usepackage{adjustbox} + + ''' } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'TheLinuxKernel.tex', 'The Linux Kernel Documentation', + ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', + 'The kernel development community', 'manual'), + ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), + ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', + 'The kernel development community', 'manual'), + ('media/index', 'media.tex', 'Linux Media Subsystem Documentation', 'The kernel development community', 'manual'), ] @@ -419,3 +493,9 @@ pdf_documents = [ # line arguments. kerneldoc_bin = '../scripts/kernel-doc' kerneldoc_srctree = '..' + +# ------------------------------------------------------------------------------ +# Since loadConfig overwrites settings from the global namespace, it has to be +# the last statement in the conf.py file +# ------------------------------------------------------------------------------ +loadConfig(globals()) diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst new file mode 100644 index 000000000000..4a64b4c69d3f --- /dev/null +++ b/Documentation/dev-tools/coccinelle.rst @@ -0,0 +1,491 @@ +.. Copyright 2010 Nicolas Palix +.. Copyright 2010 Julia Lawall +.. Copyright 2010 Gilles Muller + +.. highlight:: none + +Coccinelle +========== + +Coccinelle is a tool for pattern matching and text transformation that has +many uses in kernel development, including the application of complex, +tree-wide patches and detection of problematic programming patterns. + +Getting Coccinelle +------------------- + +The semantic patches included in the kernel use features and options +which are provided by Coccinelle version 1.0.0-rc11 and above. +Using earlier versions will fail as the option names used by +the Coccinelle files and coccicheck have been updated. + +Coccinelle is available through the package manager +of many distributions, e.g. : + + - Debian + - Fedora + - Ubuntu + - OpenSUSE + - Arch Linux + - NetBSD + - FreeBSD + +You can get the latest version released from the Coccinelle homepage at +http://coccinelle.lip6.fr/ + +Information and tips about Coccinelle are also provided on the wiki +pages at http://cocci.ekstranet.diku.dk/wiki/doku.php + +Once you have it, run the following command:: + + ./configure + make + +as a regular user, and install it with:: + + sudo make install + +Supplemental documentation +--------------------------- + +For supplemental documentation refer to the wiki: + +https://bottest.wiki.kernel.org/coccicheck + +The wiki documentation always refers to the linux-next version of the script. + +Using Coccinelle on the Linux kernel +------------------------------------ + +A Coccinelle-specific target is defined in the top level +Makefile. This target is named ``coccicheck`` and calls the ``coccicheck`` +front-end in the ``scripts`` directory. + +Four basic modes are defined: ``patch``, ``report``, ``context``, and +``org``. The mode to use is specified by setting the MODE variable with +``MODE=``. + +- ``patch`` proposes a fix, when possible. + +- ``report`` generates a list in the following format: + file:line:column-column: message + +- ``context`` highlights lines of interest and their context in a + diff-like style.Lines of interest are indicated with ``-``. + +- ``org`` generates a report in the Org mode format of Emacs. + +Note that not all semantic patches implement all modes. For easy use +of Coccinelle, the default mode is "report". + +Two other modes provide some common combinations of these modes. + +- ``chain`` tries the previous modes in the order above until one succeeds. + +- ``rep+ctxt`` runs successively the report mode and the context mode. + It should be used with the C option (described later) + which checks the code on a file basis. + +Examples +~~~~~~~~ + +To make a report for every semantic patch, run the following command:: + + make coccicheck MODE=report + +To produce patches, run:: + + make coccicheck MODE=patch + + +The coccicheck target applies every semantic patch available in the +sub-directories of ``scripts/coccinelle`` to the entire Linux kernel. + +For each semantic patch, a commit message is proposed. It gives a +description of the problem being checked by the semantic patch, and +includes a reference to Coccinelle. + +As any static code analyzer, Coccinelle produces false +positives. Thus, reports must be carefully checked, and patches +reviewed. + +To enable verbose messages set the V= variable, for example:: + + make coccicheck MODE=report V=1 + +Coccinelle parallelization +--------------------------- + +By default, coccicheck tries to run as parallel as possible. To change +the parallelism, set the J= variable. For example, to run across 4 CPUs:: + + make coccicheck MODE=report J=4 + +As of Coccinelle 1.0.2 Coccinelle uses Ocaml parmap for parallelization, +if support for this is detected you will benefit from parmap parallelization. + +When parmap is enabled coccicheck will enable dynamic load balancing by using +``--chunksize 1`` argument, this ensures we keep feeding threads with work +one by one, so that we avoid the situation where most work gets done by only +a few threads. With dynamic load balancing, if a thread finishes early we keep +feeding it more work. + +When parmap is enabled, if an error occurs in Coccinelle, this error +value is propagated back, the return value of the ``make coccicheck`` +captures this return value. + +Using Coccinelle with a single semantic patch +--------------------------------------------- + +The optional make variable COCCI can be used to check a single +semantic patch. In that case, the variable must be initialized with +the name of the semantic patch to apply. + +For instance:: + + make coccicheck COCCI= MODE=patch + +or:: + + make coccicheck COCCI= MODE=report + + +Controlling Which Files are Processed by Coccinelle +--------------------------------------------------- + +By default the entire kernel source tree is checked. + +To apply Coccinelle to a specific directory, ``M=`` can be used. +For example, to check drivers/net/wireless/ one may write:: + + make coccicheck M=drivers/net/wireless/ + +To apply Coccinelle on a file basis, instead of a directory basis, the +following command may be used:: + + make C=1 CHECK="scripts/coccicheck" + +To check only newly edited code, use the value 2 for the C flag, i.e.:: + + make C=2 CHECK="scripts/coccicheck" + +In these modes, which works on a file basis, there is no information +about semantic patches displayed, and no commit message proposed. + +This runs every semantic patch in scripts/coccinelle by default. The +COCCI variable may additionally be used to only apply a single +semantic patch as shown in the previous section. + +The "report" mode is the default. You can select another one with the +MODE variable explained above. + +Debugging Coccinelle SmPL patches +--------------------------------- + +Using coccicheck is best as it provides in the spatch command line +include options matching the options used when we compile the kernel. +You can learn what these options are by using V=1, you could then +manually run Coccinelle with debug options added. + +Alternatively you can debug running Coccinelle against SmPL patches +by asking for stderr to be redirected to stderr, by default stderr +is redirected to /dev/null, if you'd like to capture stderr you +can specify the ``DEBUG_FILE="file.txt"`` option to coccicheck. For +instance:: + + rm -f cocci.err + make coccicheck COCCI=scripts/coccinelle/free/kfree.cocci MODE=report DEBUG_FILE=cocci.err + cat cocci.err + +You can use SPFLAGS to add debugging flags, for instance you may want to +add both --profile --show-trying to SPFLAGS when debugging. For instance +you may want to use:: + + rm -f err.log + export COCCI=scripts/coccinelle/misc/irqf_oneshot.cocci + make coccicheck DEBUG_FILE="err.log" MODE=report SPFLAGS="--profile --show-trying" M=./drivers/mfd/arizona-irq.c + +err.log will now have the profiling information, while stdout will +provide some progress information as Coccinelle moves forward with +work. + +DEBUG_FILE support is only supported when using coccinelle >= 1.2. + +.cocciconfig support +-------------------- + +Coccinelle supports reading .cocciconfig for default Coccinelle options that +should be used every time spatch is spawned, the order of precedence for +variables for .cocciconfig is as follows: + +- Your current user's home directory is processed first +- Your directory from which spatch is called is processed next +- The directory provided with the --dir option is processed last, if used + +Since coccicheck runs through make, it naturally runs from the kernel +proper dir, as such the second rule above would be implied for picking up a +.cocciconfig when using ``make coccicheck``. + +``make coccicheck`` also supports using M= targets.If you do not supply +any M= target, it is assumed you want to target the entire kernel. +The kernel coccicheck script has:: + + if [ "$KBUILD_EXTMOD" = "" ] ; then + OPTIONS="--dir $srctree $COCCIINCLUDE" + else + OPTIONS="--dir $KBUILD_EXTMOD $COCCIINCLUDE" + fi + +KBUILD_EXTMOD is set when an explicit target with M= is used. For both cases +the spatch --dir argument is used, as such third rule applies when whether M= +is used or not, and when M= is used the target directory can have its own +.cocciconfig file. When M= is not passed as an argument to coccicheck the +target directory is the same as the directory from where spatch was called. + +If not using the kernel's coccicheck target, keep the above precedence +order logic of .cocciconfig reading. If using the kernel's coccicheck target, +override any of the kernel's .coccicheck's settings using SPFLAGS. + +We help Coccinelle when used against Linux with a set of sensible defaults +options for Linux with our own Linux .cocciconfig. This hints to coccinelle +git can be used for ``git grep`` queries over coccigrep. A timeout of 200 +seconds should suffice for now. + +The options picked up by coccinelle when reading a .cocciconfig do not appear +as arguments to spatch processes running on your system, to confirm what +options will be used by Coccinelle run:: + + spatch --print-options-only + +You can override with your own preferred index option by using SPFLAGS. Take +note that when there are conflicting options Coccinelle takes precedence for +the last options passed. Using .cocciconfig is possible to use idutils, however +given the order of precedence followed by Coccinelle, since the kernel now +carries its own .cocciconfig, you will need to use SPFLAGS to use idutils if +desired. See below section "Additional flags" for more details on how to use +idutils. + +Additional flags +---------------- + +Additional flags can be passed to spatch through the SPFLAGS +variable. This works as Coccinelle respects the last flags +given to it when options are in conflict. :: + + make SPFLAGS=--use-glimpse coccicheck + +Coccinelle supports idutils as well but requires coccinelle >= 1.0.6. +When no ID file is specified coccinelle assumes your ID database file +is in the file .id-utils.index on the top level of the kernel, coccinelle +carries a script scripts/idutils_index.sh which creates the database with:: + + mkid -i C --output .id-utils.index + +If you have another database filename you can also just symlink with this +name. :: + + make SPFLAGS=--use-idutils coccicheck + +Alternatively you can specify the database filename explicitly, for +instance:: + + make SPFLAGS="--use-idutils /full-path/to/ID" coccicheck + +See ``spatch --help`` to learn more about spatch options. + +Note that the ``--use-glimpse`` and ``--use-idutils`` options +require external tools for indexing the code. None of them is +thus active by default. However, by indexing the code with +one of these tools, and according to the cocci file used, +spatch could proceed the entire code base more quickly. + +SmPL patch specific options +--------------------------- + +SmPL patches can have their own requirements for options passed +to Coccinelle. SmPL patch specific options can be provided by +providing them at the top of the SmPL patch, for instance:: + + // Options: --no-includes --include-headers + +SmPL patch Coccinelle requirements +---------------------------------- + +As Coccinelle features get added some more advanced SmPL patches +may require newer versions of Coccinelle. If an SmPL patch requires +at least a version of Coccinelle, this can be specified as follows, +as an example if requiring at least Coccinelle >= 1.0.5:: + + // Requires: 1.0.5 + +Proposing new semantic patches +------------------------------- + +New semantic patches can be proposed and submitted by kernel +developers. For sake of clarity, they should be organized in the +sub-directories of ``scripts/coccinelle/``. + + +Detailed description of the ``report`` mode +------------------------------------------- + +``report`` generates a list in the following format:: + + file:line:column-column: message + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=report COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on report@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + coccilib.report.print_report(p[0], msg) + + +This SmPL excerpt generates entries on the standard output, as +illustrated below:: + + /home/user/linux/crypto/ctr.c:188:9-16: ERR_CAST can be used with alg + /home/user/linux/crypto/authenc.c:619:9-16: ERR_CAST can be used with auth + /home/user/linux/crypto/xts.c:227:9-16: ERR_CAST can be used with alg + + +Detailed description of the ``patch`` mode +------------------------------------------ + +When the ``patch`` mode is available, it proposes a fix for each problem +identified. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=patch COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + + @ depends on !context && patch && !org && !report @ + expression x; + @@ + + - ERR_PTR(PTR_ERR(x)) + + ERR_CAST(x) + + +This SmPL excerpt generates patch hunks on the standard output, as +illustrated below:: + + diff -u -p a/crypto/ctr.c b/crypto/ctr.c + --- a/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ b/crypto/ctr.c 2010-06-03 23:44:49.000000000 +0200 + @@ -185,7 +185,7 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + return ERR_CAST(alg); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``context`` mode +-------------------------------------------- + +``context`` highlights lines of interest and their context +in a diff-like style. + + **NOTE**: The diff-like output generated is NOT an applicable patch. The + intent of the ``context`` mode is to highlight the important lines + (annotated with minus, ``-``) and gives some surrounding context + lines around. This output can be used with the diff mode of + Emacs to review the code. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=context COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + + @ depends on context && !patch && !org && !report@ + expression x; + @@ + + * ERR_PTR(PTR_ERR(x)) + + +This SmPL excerpt generates diff hunks on the standard output, as +illustrated below:: + + diff -u -p /home/user/linux/crypto/ctr.c /tmp/nothing + --- /home/user/linux/crypto/ctr.c 2010-05-26 10:49:38.000000000 +0200 + +++ /tmp/nothing + @@ -185,7 +185,6 @@ static struct crypto_instance *crypto_ct + alg = crypto_attr_alg(tb[1], CRYPTO_ALG_TYPE_CIPHER, + CRYPTO_ALG_TYPE_MASK); + if (IS_ERR(alg)) + - return ERR_PTR(PTR_ERR(alg)); + + /* Block size must be >= 4 bytes. */ + err = -EINVAL; + +Detailed description of the ``org`` mode +---------------------------------------- + +``org`` generates a report in the Org mode format of Emacs. + +Example +~~~~~~~ + +Running:: + + make coccicheck MODE=org COCCI=scripts/coccinelle/api/err_cast.cocci + +will execute the following part of the SmPL script:: + + + @r depends on !context && !patch && (org || report)@ + expression x; + position p; + @@ + + ERR_PTR@p(PTR_ERR(x)) + + @script:python depends on org@ + p << r.p; + x << r.x; + @@ + + msg="ERR_CAST can be used with %s" % (x) + msg_safe=msg.replace("[","@(").replace("]",")") + coccilib.org.print_todo(p[0], msg_safe) + + +This SmPL excerpt generates Org entries on the standard output, as +illustrated below:: + + * TODO [[view:/home/user/linux/crypto/ctr.c::face=ovl-face1::linb=188::colb=9::cole=16][ERR_CAST can be used with alg]] + * TODO [[view:/home/user/linux/crypto/authenc.c::face=ovl-face1::linb=619::colb=9::cole=16][ERR_CAST can be used with auth]] + * TODO [[view:/home/user/linux/crypto/xts.c::face=ovl-face1::linb=227::colb=9::cole=16][ERR_CAST can be used with alg]] diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst new file mode 100644 index 000000000000..19eedfea8800 --- /dev/null +++ b/Documentation/dev-tools/gcov.rst @@ -0,0 +1,256 @@ +Using gcov with the Linux kernel +================================ + +gcov profiling kernel support enables the use of GCC's coverage testing +tool gcov_ with the Linux kernel. Coverage data of a running kernel +is exported in gcov-compatible format via the "gcov" debugfs directory. +To get coverage data for a specific file, change to the kernel build +directory and use gcov with the ``-o`` option as follows (requires root):: + + # cd /tmp/linux-out + # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c + +This will create source code files annotated with execution counts +in the current directory. In addition, graphical gcov front-ends such +as lcov_ can be used to automate the process of collecting data +for the entire kernel and provide coverage overviews in HTML format. + +Possible uses: + +* debugging (has this line been reached at all?) +* test improvement (how do I change my test to cover these lines?) +* minimizing kernel configurations (do I need this option if the + associated code is never run?) + +.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php + + +Preparation +----------- + +Configure the kernel with:: + + CONFIG_DEBUG_FS=y + CONFIG_GCOV_KERNEL=y + +select the gcc's gcov format, default is autodetect based on gcc version:: + + CONFIG_GCOV_FORMAT_AUTODETECT=y + +and to get coverage data for the entire kernel:: + + CONFIG_GCOV_PROFILE_ALL=y + +Note that kernels compiled with profiling flags will be significantly +larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported +on all architectures. + +Profiling data will only become accessible once debugfs has been +mounted:: + + mount -t debugfs none /sys/kernel/debug + + +Customization +------------- + +To enable profiling for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + +- For a single file (e.g. main.o):: + + GCOV_PROFILE_main.o := y + +- For all files in one directory:: + + GCOV_PROFILE := y + +To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL +is specified, use:: + + GCOV_PROFILE_main.o := n + +and:: + + GCOV_PROFILE := n + +Only files which are linked to the main kernel image or are compiled as +kernel modules are supported by this mechanism. + + +Files +----- + +The gcov kernel support creates the following files in debugfs: + +``/sys/kernel/debug/gcov`` + Parent directory for all gcov-related files. + +``/sys/kernel/debug/gcov/reset`` + Global reset file: resets all coverage data to zero when + written to. + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` + The actual gcov data file as understood by the gcov + tool. Resets file coverage data to zero when written to. + +``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` + Symbolic link to a static data file required by the gcov + tool. This file is generated by gcc when compiling with + option ``-ftest-coverage``. + + +Modules +------- + +Kernel modules may contain cleanup code which is only run during +module unload time. The gcov mechanism provides a means to collect +coverage data for such code by keeping a copy of the data associated +with the unloaded module. This data remains available through debugfs. +Once the module is loaded again, the associated coverage counters are +initialized with the data from its previous instantiation. + +This behavior can be deactivated by specifying the gcov_persist kernel +parameter:: + + gcov_persist=0 + +At run-time, a user can also choose to discard data for an unloaded +module by writing to its data file or the global reset file. + + +Separated build and test machines +--------------------------------- + +The gcov kernel profiling infrastructure is designed to work out-of-the +box for setups where kernels are built and run on the same machine. In +cases where the kernel runs on a separate machine, special preparations +must be made, depending on where the gcov tool is used: + +a) gcov is run on the TEST machine + + The gcov tool version on the test machine must be compatible with the + gcc version used for kernel build. Also the following files need to be + copied from build to test machine: + + from the source tree: + - all C source files + headers + + from the build tree: + - all C source files + headers + - all .gcda and .gcno files + - all links to directories + + It is important to note that these files need to be placed into the + exact same file system location on the test machine as on the build + machine. If any of the path components is symbolic link, the actual + directory needs to be used instead (due to make's CURDIR handling). + +b) gcov is run on the BUILD machine + + The following files need to be copied after each test case from test + to build machine: + + from the gcov directory in sysfs: + - all .gcda files + - all links to .gcno files + + These files can be copied to any location on the build machine. gcov + must then be called with the -o option pointing to that directory. + + Example directory setup on the build machine:: + + /tmp/linux: kernel source tree + /tmp/out: kernel build directory as specified by make O= + /tmp/coverage: location of the files copied from the test machine + + [user@build] cd /tmp/out + [user@build] gcov -o /tmp/coverage/tmp/out/init main.c + + +Troubleshooting +--------------- + +Problem + Compilation aborts during linker step. + +Cause + Profiling flags are specified for source files which are not + linked to the main kernel or which are linked by a custom + linker procedure. + +Solution + Exclude affected source files from profiling by specifying + ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the + corresponding Makefile. + +Problem + Files copied from sysfs appear empty or incomplete. + +Cause + Due to the way seq_file works, some tools such as cp or tar + may not correctly copy files from sysfs. + +Solution + Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links. + Alternatively use the mechanism shown in Appendix B. + + +Appendix A: gather_on_build.sh +------------------------------ + +Sample script to gather coverage meta files on the build machine +(see 6a):: + + #!/bin/bash + + KSRC=$1 + KOBJ=$2 + DEST=$3 + + if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then + echo "Usage: $0 " >&2 + exit 1 + fi + + KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) + + find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ + -perm /u+r,g+r | tar cfz $DEST -P -T - + + if [ $? -eq 0 ] ; then + echo "$DEST successfully created, copy to test system and unpack with:" + echo " tar xfz $DEST -P" + else + echo "Could not create file $DEST" + fi + + +Appendix B: gather_on_test.sh +----------------------------- + +Sample script to gather coverage data files on the test machine +(see 6b):: + + #!/bin/bash -e + + DEST=$1 + GCDA=/sys/kernel/debug/gcov + + if [ -z "$DEST" ] ; then + echo "Usage: $0 " >&2 + exit 1 + fi + + TEMPDIR=$(mktemp -d) + echo Collecting data.. + find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; + find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; + find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; + tar czf $DEST -C $TEMPDIR sys + rm -rf $TEMPDIR + + echo "$DEST successfully created, copy to build system and unpack with:" + echo " tar xfz $DEST" diff --git a/Documentation/dev-tools/gdb-kernel-debugging.rst b/Documentation/dev-tools/gdb-kernel-debugging.rst new file mode 100644 index 000000000000..5e93c9bc6619 --- /dev/null +++ b/Documentation/dev-tools/gdb-kernel-debugging.rst @@ -0,0 +1,173 @@ +.. highlight:: none + +Debugging kernel and modules via gdb +==================================== + +The kernel debugger kgdb, hypervisors like QEMU or JTAG-based hardware +interfaces allow to debug the Linux kernel and its modules during runtime +using gdb. Gdb comes with a powerful scripting interface for python. The +kernel provides a collection of helper scripts that can simplify typical +kernel debugging steps. This is a short tutorial about how to enable and use +them. It focuses on QEMU/KVM virtual machines as target, but the examples can +be transferred to the other gdb stubs as well. + + +Requirements +------------ + +- gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true + for distributions) + + +Setup +----- + +- Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and + www.qemu.org for more details). For cross-development, + http://landley.net/aboriginal/bin keeps a pool of machine images and + toolchains that can be helpful to start from. + +- Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave + CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports + CONFIG_FRAME_POINTER, keep it enabled. + +- Install that kernel on the guest. + Alternatively, QEMU allows to boot the kernel directly using -kernel, + -append, -initrd command line switches. This is generally only useful if + you do not depend on modules. See QEMU documentation for more details on + this mode. + +- Enable the gdb stub of QEMU/KVM, either + + - at VM startup time by appending "-s" to the QEMU command line + + or + + - during runtime by issuing "gdbserver" from the QEMU monitor + console + +- cd /path/to/linux-build + +- Start gdb: gdb vmlinux + + Note: Some distros may restrict auto-loading of gdb scripts to known safe + directories. In case gdb reports to refuse loading vmlinux-gdb.py, add:: + + add-auto-load-safe-path /path/to/linux-build + + to ~/.gdbinit. See gdb help for more details. + +- Attach to the booted guest:: + + (gdb) target remote :1234 + + +Examples of using the Linux-provided gdb helpers +------------------------------------------------ + +- Load module (and main kernel) symbols:: + + (gdb) lx-symbols + loading vmlinux + scanning for modules in /home/user/linux/build + loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko + loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko + loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko + loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko + loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko + ... + loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko + +- Set a breakpoint on some not yet loaded module function, e.g.:: + + (gdb) b btrfs_init_sysfs + Function "btrfs_init_sysfs" not defined. + Make breakpoint pending on future shared library load? (y or [n]) y + Breakpoint 1 (btrfs_init_sysfs) pending. + +- Continue the target:: + + (gdb) c + +- Load the module on the target and watch the symbols being loaded as well as + the breakpoint hit:: + + loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko + loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko + loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko + loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko + + Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 + 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); + +- Dump the log buffer of the target kernel:: + + (gdb) lx-dmesg + [ 0.000000] Initializing cgroup subsys cpuset + [ 0.000000] Initializing cgroup subsys cpu + [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... + [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 + [ 0.000000] e820: BIOS-provided physical RAM map: + [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable + [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved + .... + +- Examine fields of the current task struct:: + + (gdb) p $lx_current().pid + $1 = 4998 + (gdb) p $lx_current().comm + $2 = "modprobe\000\000\000\000\000\000\000" + +- Make use of the per-cpu function for the current or a specified CPU:: + + (gdb) p $lx_per_cpu("runqueues").nr_running + $3 = 1 + (gdb) p $lx_per_cpu("runqueues", 2).nr_running + $4 = 0 + +- Dig into hrtimers using the container_of helper:: + + (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next + (gdb) p *$container_of($next, "struct hrtimer", "node") + $5 = { + node = { + node = { + __rb_parent_color = 18446612133355256072, + rb_right = 0x0 , + rb_left = 0x0 + }, + expires = { + tv64 = 1835268000000 + } + }, + _softexpires = { + tv64 = 1835268000000 + }, + function = 0xffffffff81078232 , + base = 0xffff88003fd0d6f0, + state = 1, + start_pid = 0, + start_site = 0xffffffff81055c1f , + start_comm = "swapper/2\000\000\000\000\000\000" + } + + +List of commands and functions +------------------------------ + +The number of commands and convenience functions may evolve over the time, +this is just a snapshot of the initial version:: + + (gdb) apropos lx + function lx_current -- Return current task + function lx_module -- Find module by name and return the module variable + function lx_per_cpu -- Return per-cpu variable + function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable + function lx_thread_info -- Calculate Linux thread_info from task variable + lx-dmesg -- Print Linux kernel log buffer + lx-lsmod -- List currently loaded modules + lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules + +Detailed help can be obtained via "help " for commands and "help +function " for convenience functions. diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst new file mode 100644 index 000000000000..f7a18f274357 --- /dev/null +++ b/Documentation/dev-tools/kasan.rst @@ -0,0 +1,173 @@ +The Kernel Address Sanitizer (KASAN) +==================================== + +Overview +-------- + +KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides +a fast and comprehensive solution for finding use-after-free and out-of-bounds +bugs. + +KASAN uses compile-time instrumentation for checking every memory access, +therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is +required for detection of out-of-bounds accesses to stack or global variables. + +Currently KASAN is supported only for the x86_64 and arm64 architectures. + +Usage +----- + +To enable KASAN configure kernel with:: + + CONFIG_KASAN = y + +and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and +inline are compiler instrumentation types. The former produces smaller binary +the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC +version 5.0 or later. + +KASAN works with both SLUB and SLAB memory allocators. +For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. + +To disable instrumentation for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + +- For a single file (e.g. main.o):: + + KASAN_SANITIZE_main.o := n + +- For all files in one directory:: + + KASAN_SANITIZE := n + +Error reports +~~~~~~~~~~~~~ + +A typical out of bounds access report looks like this:: + + ================================================================== + BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 + Write of size 1 by task modprobe/1689 + ============================================================================= + BUG kmalloc-128 (Not tainted): kasan error + ----------------------------------------------------------------------------- + + Disabling lock debugging due to kernel taint + INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 + __slab_alloc+0x4b4/0x4f0 + kmem_cache_alloc_trace+0x10b/0x190 + kmalloc_oob_right+0x3d/0x75 [test_kasan] + init_module+0x9/0x47 [test_kasan] + do_one_initcall+0x99/0x200 + load_module+0x2cb3/0x3b20 + SyS_finit_module+0x76/0x80 + system_call_fastpath+0x12/0x17 + INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 + INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 + + Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ + Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk + Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. + Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ + Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ + CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 + ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 + ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 + ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 + Call Trace: + [] dump_stack+0x46/0x58 + [] print_trailer+0xf8/0x160 + [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [] object_err+0x35/0x40 + [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [] kasan_report_error+0x38a/0x3f0 + [] ? kasan_poison_shadow+0x2f/0x40 + [] ? kasan_unpoison_shadow+0x14/0x40 + [] ? kasan_poison_shadow+0x2f/0x40 + [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] + [] __asan_store1+0x75/0xb0 + [] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] + [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] + [] kmalloc_oob_right+0x65/0x75 [test_kasan] + [] init_module+0x9/0x47 [test_kasan] + [] do_one_initcall+0x99/0x200 + [] ? __vunmap+0xec/0x160 + [] load_module+0x2cb3/0x3b20 + [] ? m_show+0x240/0x240 + [] SyS_finit_module+0x76/0x80 + [] system_call_fastpath+0x12/0x17 + Memory state around the buggy address: + ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc + ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 + >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc + ^ + ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc + ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ================================================================== + +The header of the report discribe what kind of bug happened and what kind of +access caused it. It's followed by the description of the accessed slub object +(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and +the description of the accessed memory page. + +In the last section the report shows memory state around the accessed address. +Reading this part requires some understanding of how KASAN works. + +The state of each 8 aligned bytes of memory is encoded in one shadow byte. +Those 8 bytes can be accessible, partially accessible, freed or be a redzone. +We use the following encoding for each shadow byte: 0 means that all 8 bytes +of the corresponding memory region are accessible; number N (1 <= N <= 7) means +that the first N bytes are accessible, and other (8 - N) bytes are not; +any negative value indicates that the entire 8-byte word is inaccessible. +We use different negative values to distinguish between different kinds of +inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). + +In the report above the arrows point to the shadow byte 03, which means that +the accessed address is partially accessible. + + +Implementation details +---------------------- + +From a high level, our approach to memory error detection is similar to that +of kmemcheck: use shadow memory to record whether each byte of memory is safe +to access, and use compile-time instrumentation to check shadow memory on each +memory access. + +AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory +(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and +offset to translate a memory address to its corresponding shadow address. + +Here is the function which translates an address to its corresponding shadow +address:: + + static inline void *kasan_mem_to_shadow(const void *addr) + { + return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) + + KASAN_SHADOW_OFFSET; + } + +where ``KASAN_SHADOW_SCALE_SHIFT = 3``. + +Compile-time instrumentation used for checking memory accesses. Compiler inserts +function calls (__asan_load*(addr), __asan_store*(addr)) before each memory +access of size 1, 2, 4, 8 or 16. These functions check whether memory access is +valid or not by checking corresponding shadow memory. + +GCC 5.0 has possibility to perform inline instrumentation. Instead of making +function calls GCC directly inserts the code to check the shadow memory. +This option significantly enlarges kernel but it gives x1.1-x2 performance +boost over outline instrumented kernel. diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst new file mode 100644 index 000000000000..aca0e27ca197 --- /dev/null +++ b/Documentation/dev-tools/kcov.rst @@ -0,0 +1,111 @@ +kcov: code coverage for fuzzing +=============================== + +kcov exposes kernel code coverage information in a form suitable for coverage- +guided fuzzing (randomized testing). Coverage data of a running kernel is +exported via the "kcov" debugfs file. Coverage collection is enabled on a task +basis, and thus it can capture precise coverage of a single system call. + +Note that kcov does not aim to collect as much coverage as possible. It aims +to collect more or less stable coverage that is function of syscall inputs. +To achieve this goal it does not collect coverage in soft/hard interrupts +and instrumentation of some inherently non-deterministic parts of kernel is +disbled (e.g. scheduler, locking). + +Usage +----- + +Configure the kernel with:: + + CONFIG_KCOV=y + +CONFIG_KCOV requires gcc built on revision 231296 or later. +Profiling data will only become accessible once debugfs has been mounted:: + + mount -t debugfs none /sys/kernel/debug + +The following program demonstrates kcov usage from within a test program:: + + #include + #include + #include + #include + #include + #include + #include + #include + #include + #include + + #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) + #define KCOV_ENABLE _IO('c', 100) + #define KCOV_DISABLE _IO('c', 101) + #define COVER_SIZE (64<<10) + + int main(int argc, char **argv) + { + int fd; + unsigned long *cover, n, i; + + /* A single fd descriptor allows coverage collection on a single + * thread. + */ + fd = open("/sys/kernel/debug/kcov", O_RDWR); + if (fd == -1) + perror("open"), exit(1); + /* Setup trace mode and trace size. */ + if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE)) + perror("ioctl"), exit(1); + /* Mmap buffer shared between kernel- and user-space. */ + cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); + if ((void*)cover == MAP_FAILED) + perror("mmap"), exit(1); + /* Enable coverage collection on the current thread. */ + if (ioctl(fd, KCOV_ENABLE, 0)) + perror("ioctl"), exit(1); + /* Reset coverage from the tail of the ioctl() call. */ + __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED); + /* That's the target syscal call. */ + read(-1, NULL, 0); + /* Read number of PCs collected. */ + n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); + for (i = 0; i < n; i++) + printf("0x%lx\n", cover[i + 1]); + /* Disable coverage collection for the current thread. After this call + * coverage can be enabled for a different thread. + */ + if (ioctl(fd, KCOV_DISABLE, 0)) + perror("ioctl"), exit(1); + /* Free resources. */ + if (munmap(cover, COVER_SIZE * sizeof(unsigned long))) + perror("munmap"), exit(1); + if (close(fd)) + perror("close"), exit(1); + return 0; + } + +After piping through addr2line output of the program looks as follows:: + + SyS_read + fs/read_write.c:562 + __fdget_pos + fs/file.c:774 + __fget_light + fs/file.c:746 + __fget_light + fs/file.c:750 + __fget_light + fs/file.c:760 + __fdget_pos + fs/file.c:784 + SyS_read + fs/read_write.c:562 + +If a program needs to collect coverage from several threads (independently), +it needs to open /sys/kernel/debug/kcov in each thread separately. + +The interface is fine-grained to allow efficient forking of test processes. +That is, a parent process opens /sys/kernel/debug/kcov, enables trace mode, +mmaps coverage buffer and then forks child processes in a loop. Child processes +only need to enable coverage (disable happens automatically on thread end). diff --git a/Documentation/dev-tools/kmemcheck.rst b/Documentation/dev-tools/kmemcheck.rst new file mode 100644 index 000000000000..7f3d1985de74 --- /dev/null +++ b/Documentation/dev-tools/kmemcheck.rst @@ -0,0 +1,733 @@ +Getting started with kmemcheck +============================== + +Vegard Nossum + + +Introduction +------------ + +kmemcheck is a debugging feature for the Linux Kernel. More specifically, it +is a dynamic checker that detects and warns about some uses of uninitialized +memory. + +Userspace programmers might be familiar with Valgrind's memcheck. The main +difference between memcheck and kmemcheck is that memcheck works for userspace +programs only, and kmemcheck works for the kernel only. The implementations +are of course vastly different. Because of this, kmemcheck is not as accurate +as memcheck, but it turns out to be good enough in practice to discover real +programmer errors that the compiler is not able to find through static +analysis. + +Enabling kmemcheck on a kernel will probably slow it down to the extent that +the machine will not be usable for normal workloads such as e.g. an +interactive desktop. kmemcheck will also cause the kernel to use about twice +as much memory as normal. For this reason, kmemcheck is strictly a debugging +feature. + + +Downloading +----------- + +As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. + + +Configuring and compiling +------------------------- + +kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of +configuration variables must have specific settings in order for the kmemcheck +menu to even appear in "menuconfig". These are: + +- ``CONFIG_CC_OPTIMIZE_FOR_SIZE=n`` + This option is located under "General setup" / "Optimize for size". + + Without this, gcc will use certain optimizations that usually lead to + false positive warnings from kmemcheck. An example of this is a 16-bit + field in a struct, where gcc may load 32 bits, then discard the upper + 16 bits. kmemcheck sees only the 32-bit load, and may trigger a + warning for the upper 16 bits (if they're uninitialized). + +- ``CONFIG_SLAB=y`` or ``CONFIG_SLUB=y`` + This option is located under "General setup" / "Choose SLAB + allocator". + +- ``CONFIG_FUNCTION_TRACER=n`` + This option is located under "Kernel hacking" / "Tracers" / "Kernel + Function Tracer" + + When function tracing is compiled in, gcc emits a call to another + function at the beginning of every function. This means that when the + page fault handler is called, the ftrace framework will be called + before kmemcheck has had a chance to handle the fault. If ftrace then + modifies memory that was tracked by kmemcheck, the result is an + endless recursive page fault. + +- ``CONFIG_DEBUG_PAGEALLOC=n`` + This option is located under "Kernel hacking" / "Memory Debugging" + / "Debug page memory allocations". + +In addition, I highly recommend turning on ``CONFIG_DEBUG_INFO=y``. This is also +located under "Kernel hacking". With this, you will be able to get line number +information from the kmemcheck warnings, which is extremely valuable in +debugging a problem. This option is not mandatory, however, because it slows +down the compilation process and produces a much bigger kernel image. + +Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory +Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows +a description of the kmemcheck configuration variables: + +- ``CONFIG_KMEMCHECK`` + This must be enabled in order to use kmemcheck at all... + +- ``CONFIG_KMEMCHECK_``[``DISABLED`` | ``ENABLED`` | ``ONESHOT``]``_BY_DEFAULT`` + This option controls the status of kmemcheck at boot-time. "Enabled" + will enable kmemcheck right from the start, "disabled" will boot the + kernel as normal (but with the kmemcheck code compiled in, so it can + be enabled at run-time after the kernel has booted), and "one-shot" is + a special mode which will turn kmemcheck off automatically after + detecting the first use of uninitialized memory. + + If you are using kmemcheck to actively debug a problem, then you + probably want to choose "enabled" here. + + The one-shot mode is mostly useful in automated test setups because it + can prevent floods of warnings and increase the chances of the machine + surviving in case something is really wrong. In other cases, the one- + shot mode could actually be counter-productive because it would turn + itself off at the very first error -- in the case of a false positive + too -- and this would come in the way of debugging the specific + problem you were interested in. + + If you would like to use your kernel as normal, but with a chance to + enable kmemcheck in case of some problem, it might be a good idea to + choose "disabled" here. When kmemcheck is disabled, most of the run- + time overhead is not incurred, and the kernel will be almost as fast + as normal. + +- ``CONFIG_KMEMCHECK_QUEUE_SIZE`` + Select the maximum number of error reports to store in an internal + (fixed-size) buffer. Since errors can occur virtually anywhere and in + any context, we need a temporary storage area which is guaranteed not + to generate any other page faults when accessed. The queue will be + emptied as soon as a tasklet may be scheduled. If the queue is full, + new error reports will be lost. + + The default value of 64 is probably fine. If some code produces more + than 64 errors within an irqs-off section, then the code is likely to + produce many, many more, too, and these additional reports seldom give + any more information (the first report is usually the most valuable + anyway). + + This number might have to be adjusted if you are not using serial + console or similar to capture the kernel log. If you are using the + "dmesg" command to save the log, then getting a lot of kmemcheck + warnings might overflow the kernel log itself, and the earlier reports + will get lost in that way instead. Try setting this to 10 or so on + such a setup. + +- ``CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT`` + Select the number of shadow bytes to save along with each entry of the + error-report queue. These bytes indicate what parts of an allocation + are initialized, uninitialized, etc. and will be displayed when an + error is detected to help the debugging of a particular problem. + + The number entered here is actually the logarithm of the number of + bytes that will be saved. So if you pick for example 5 here, kmemcheck + will save 2^5 = 32 bytes. + + The default value should be fine for debugging most problems. It also + fits nicely within 80 columns. + +- ``CONFIG_KMEMCHECK_PARTIAL_OK`` + This option (when enabled) works around certain GCC optimizations that + produce 32-bit reads from 16-bit variables where the upper 16 bits are + thrown away afterwards. + + The default value (enabled) is recommended. This may of course hide + some real errors, but disabling it would probably produce a lot of + false positives. + +- ``CONFIG_KMEMCHECK_BITOPS_OK`` + This option silences warnings that would be generated for bit-field + accesses where not all the bits are initialized at the same time. This + may also hide some real bugs. + + This option is probably obsolete, or it should be replaced with + the kmemcheck-/bitfield-annotations for the code in question. The + default value is therefore fine. + +Now compile the kernel as usual. + + +How to use +---------- + +Booting +~~~~~~~ + +First some information about the command-line options. There is only one +option specific to kmemcheck, and this is called "kmemcheck". It can be used +to override the default mode as chosen by the ``CONFIG_KMEMCHECK_*_BY_DEFAULT`` +option. Its possible settings are: + +- ``kmemcheck=0`` (disabled) +- ``kmemcheck=1`` (enabled) +- ``kmemcheck=2`` (one-shot mode) + +If SLUB debugging has been enabled in the kernel, it may take precedence over +kmemcheck in such a way that the slab caches which are under SLUB debugging +will not be tracked by kmemcheck. In order to ensure that this doesn't happen +(even though it shouldn't by default), use SLUB's boot option ``slub_debug``, +like this: ``slub_debug=-`` + +In fact, this option may also be used for fine-grained control over SLUB vs. +kmemcheck. For example, if the command line includes +``kmemcheck=1 slub_debug=,dentry``, then SLUB debugging will be used only +for the "dentry" slab cache, and with kmemcheck tracking all the other +caches. This is advanced usage, however, and is not generally recommended. + + +Run-time enable/disable +~~~~~~~~~~~~~~~~~~~~~~~ + +When the kernel has booted, it is possible to enable or disable kmemcheck at +run-time. WARNING: This feature is still experimental and may cause false +positive warnings to appear. Therefore, try not to use this. If you find that +it doesn't work properly (e.g. you see an unreasonable amount of warnings), I +will be happy to take bug reports. + +Use the file ``/proc/sys/kernel/kmemcheck`` for this purpose, e.g.:: + + $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck + +The numbers are the same as for the ``kmemcheck=`` command-line option. + + +Debugging +~~~~~~~~~ + +A typical report will look something like this:: + + WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + ^ + + Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A + RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 + RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 + RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 + RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 + RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 + R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e + R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 + FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 + CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 + CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 + DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 + DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 + [] dequeue_signal+0x8e/0x170 + [] get_signal_to_deliver+0x98/0x390 + [] do_notify_resume+0xad/0x7d0 + [] int_signal+0x12/0x17 + [] 0xffffffffffffffff + +The single most valuable information in this report is the RIP (or EIP on 32- +bit) value. This will help us pinpoint exactly which instruction that caused +the warning. + +If your kernel was compiled with ``CONFIG_DEBUG_INFO=y``, then all we have to do +is give this address to the addr2line program, like this:: + + $ addr2line -e vmlinux -i ffffffff8104ede8 + arch/x86/include/asm/string_64.h:12 + include/asm-generic/siginfo.h:287 + kernel/signal.c:380 + kernel/signal.c:410 + +The "``-e vmlinux``" tells addr2line which file to look in. **IMPORTANT:** +This must be the vmlinux of the kernel that produced the warning in the +first place! If not, the line number information will almost certainly be +wrong. + +The "``-i``" tells addr2line to also print the line numbers of inlined +functions. In this case, the flag was very important, because otherwise, +it would only have printed the first line, which is just a call to +``memcpy()``, which could be called from a thousand places in the kernel, and +is therefore not very useful. These inlined functions would not show up in +the stack trace above, simply because the kernel doesn't load the extra +debugging information. This technique can of course be used with ordinary +kernel oopses as well. + +In this case, it's the caller of ``memcpy()`` that is interesting, and it can be +found in ``include/asm-generic/siginfo.h``, line 287:: + + 281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) + 282 { + 283 if (from->si_code < 0) + 284 memcpy(to, from, sizeof(*to)); + 285 else + 286 /* _sigchld is currently the largest know union member */ + 287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); + 288 } + +Since this was a read (kmemcheck usually warns about reads only, though it can +warn about writes to unallocated or freed memory as well), it was probably the +"from" argument which contained some uninitialized bytes. Following the chain +of calls, we move upwards to see where "from" was allocated or initialized, +``kernel/signal.c``, line 380:: + + 359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) + 360 { + ... + 367 list_for_each_entry(q, &list->list, list) { + 368 if (q->info.si_signo == sig) { + 369 if (first) + 370 goto still_pending; + 371 first = q; + ... + 377 if (first) { + 378 still_pending: + 379 list_del_init(&first->list); + 380 copy_siginfo(info, &first->info); + 381 __sigqueue_free(first); + ... + 392 } + 393 } + +Here, it is ``&first->info`` that is being passed on to ``copy_siginfo()``. The +variable ``first`` was found on a list -- passed in as the second argument to +``collect_signal()``. We continue our journey through the stack, to figure out +where the item on "list" was allocated or initialized. We move to line 410:: + + 395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, + 396 siginfo_t *info) + 397 { + ... + 410 collect_signal(sig, pending, info); + ... + 414 } + +Now we need to follow the ``pending`` pointer, since that is being passed on to +``collect_signal()`` as ``list``. At this point, we've run out of lines from the +"addr2line" output. Not to worry, we just paste the next addresses from the +kmemcheck stack dump, i.e.:: + + [] dequeue_signal+0x8e/0x170 + [] get_signal_to_deliver+0x98/0x390 + [] do_notify_resume+0xad/0x7d0 + [] int_signal+0x12/0x17 + + $ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \ + ffffffff8100b87d ffffffff8100c7b5 + kernel/signal.c:446 + kernel/signal.c:1806 + arch/x86/kernel/signal.c:805 + arch/x86/kernel/signal.c:871 + arch/x86/kernel/entry_64.S:694 + +Remember that since these addresses were found on the stack and not as the +RIP value, they actually point to the _next_ instruction (they are return +addresses). This becomes obvious when we look at the code for line 446:: + + 422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) + 423 { + ... + 431 signr = __dequeue_signal(&tsk->signal->shared_pending, + 432 mask, info); + 433 /* + 434 * itimer signal ? + 435 * + 436 * itimers are process shared and we restart periodic + 437 * itimers in the signal delivery path to prevent DoS + 438 * attacks in the high resolution timer case. This is + 439 * compliant with the old way of self restarting + 440 * itimers, as the SIGALRM is a legacy signal and only + 441 * queued once. Changing the restart behaviour to + 442 * restart the timer in the signal dequeue path is + 443 * reducing the timer noise on heavy loaded !highres + 444 * systems too. + 445 */ + 446 if (unlikely(signr == SIGALRM)) { + ... + 489 } + +So instead of looking at 446, we should be looking at 431, which is the line +that executes just before 446. Here we see that what we are looking for is +``&tsk->signal->shared_pending``. + +Our next task is now to figure out which function that puts items on this +``shared_pending`` list. A crude, but efficient tool, is ``git grep``:: + + $ git grep -n 'shared_pending' kernel/ + ... + kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending; + kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending; + ... + +There were more results, but none of them were related to list operations, +and these were the only assignments. We inspect the line numbers more closely +and find that this is indeed where items are being added to the list:: + + 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, + 817 int group) + 818 { + ... + 828 pending = group ? &t->signal->shared_pending : &t->pending; + ... + 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && + 852 (is_si_special(info) || + 853 info->si_code >= 0))); + 854 if (q) { + 855 list_add_tail(&q->list, &pending->list); + ... + 890 } + +and:: + + 1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) + 1310 { + .... + 1339 pending = group ? &t->signal->shared_pending : &t->pending; + 1340 list_add_tail(&q->list, &pending->list); + .... + 1347 } + +In the first case, the list element we are looking for, ``q``, is being +returned from the function ``__sigqueue_alloc()``, which looks like an +allocation function. Let's take a look at it:: + + 187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, + 188 int override_rlimit) + 189 { + 190 struct sigqueue *q = NULL; + 191 struct user_struct *user; + 192 + 193 /* + 194 * We won't get problems with the target's UID changing under us + 195 * because changing it requires RCU be used, and if t != current, the + 196 * caller must be holding the RCU readlock (by way of a spinlock) and + 197 * we use RCU protection here + 198 */ + 199 user = get_uid(__task_cred(t)->user); + 200 atomic_inc(&user->sigpending); + 201 if (override_rlimit || + 202 atomic_read(&user->sigpending) <= + 203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) + 204 q = kmem_cache_alloc(sigqueue_cachep, flags); + 205 if (unlikely(q == NULL)) { + 206 atomic_dec(&user->sigpending); + 207 free_uid(user); + 208 } else { + 209 INIT_LIST_HEAD(&q->list); + 210 q->flags = 0; + 211 q->user = user; + 212 } + 213 + 214 return q; + 215 } + +We see that this function initializes ``q->list``, ``q->flags``, and +``q->user``. It seems that now is the time to look at the definition of +``struct sigqueue``, e.g.:: + + 14 struct sigqueue { + 15 struct list_head list; + 16 int flags; + 17 siginfo_t info; + 18 struct user_struct *user; + 19 }; + +And, you might remember, it was a ``memcpy()`` on ``&first->info`` that +caused the warning, so this makes perfect sense. It also seems reasonable +to assume that it is the caller of ``__sigqueue_alloc()`` that has the +responsibility of filling out (initializing) this member. + +But just which fields of the struct were uninitialized? Let's look at +kmemcheck's report again:: + + WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + ^ + +These first two lines are the memory dump of the memory object itself, and +the shadow bytemap, respectively. The memory object itself is in this case +``&first->info``. Just beware that the start of this dump is NOT the start +of the object itself! The position of the caret (^) corresponds with the +address of the read (ffff88003e4a2024). + +The shadow bytemap dump legend is as follows: + +- i: initialized +- u: uninitialized +- a: unallocated (memory has been allocated by the slab layer, but has not + yet been handed off to anybody) +- f: freed (memory has been allocated by the slab layer, but has been freed + by the previous owner) + +In order to figure out where (relative to the start of the object) the +uninitialized memory was located, we have to look at the disassembly. For +that, we'll need the RIP address again:: + + RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 + + $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: + ffffffff8104edc8: mov %r8,0x8(%r8) + ffffffff8104edcc: test %r10d,%r10d + ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168> + ffffffff8104edd5: mov %rax,%rdx + ffffffff8104edd8: mov $0xc,%ecx + ffffffff8104eddd: mov %r13,%rdi + ffffffff8104ede0: mov $0x30,%eax + ffffffff8104ede5: mov %rdx,%rsi + ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi) + ffffffff8104edea: test $0x2,%al + ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0> + ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi) + ffffffff8104edf0: test $0x1,%al + ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5> + ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi) + ffffffff8104edf5: mov %r8,%rdi + ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> + +As expected, it's the "``rep movsl``" instruction from the ``memcpy()`` +that causes the warning. We know about ``REP MOVSL`` that it uses the register +``RCX`` to count the number of remaining iterations. By taking a look at the +register dump again (from the kmemcheck report), we can figure out how many +bytes were left to copy:: + + RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 + +By looking at the disassembly, we also see that ``%ecx`` is being loaded +with the value ``$0xc`` just before (ffffffff8104edd8), so we are very +lucky. Keep in mind that this is the number of iterations, not bytes. And +since this is a "long" operation, we need to multiply by 4 to get the +number of bytes. So this means that the uninitialized value was encountered +at 4 * (0xc - 0x9) = 12 bytes from the start of the object. + +We can now try to figure out which field of the "``struct siginfo``" that +was not initialized. This is the beginning of the struct:: + + 40 typedef struct siginfo { + 41 int si_signo; + 42 int si_errno; + 43 int si_code; + 44 + 45 union { + .. + 92 } _sifields; + 93 } siginfo_t; + +On 64-bit, the int is 4 bytes long, so it must the union member that has +not been initialized. We can verify this using gdb:: + + $ gdb vmlinux + ... + (gdb) p &((struct siginfo *) 0)->_sifields + $1 = (union {...} *) 0x10 + +Actually, it seems that the union member is located at offset 0x10 -- which +means that gcc has inserted 4 bytes of padding between the members ``si_code`` +and ``_sifields``. We can now get a fuller picture of the memory dump:: + + _----------------------------=> si_code + / _--------------------=> (padding) + | / _------------=> _sifields(._kill._pid) + | | / _----=> _sifields(._kill._uid) + | | | / + -------|-------|-------|-------| + 80000000000000000000000000000000000000000088ffff0000000000000000 + i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u + +This allows us to realize another important fact: ``si_code`` contains the +value 0x80. Remember that x86 is little endian, so the first 4 bytes +"80000000" are really the number 0x00000080. With a bit of research, we +find that this is actually the constant ``SI_KERNEL`` defined in +``include/asm-generic/siginfo.h``:: + + 144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */ + +This macro is used in exactly one place in the x86 kernel: In ``send_signal()`` +in ``kernel/signal.c``:: + + 816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, + 817 int group) + 818 { + ... + 828 pending = group ? &t->signal->shared_pending : &t->pending; + ... + 851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && + 852 (is_si_special(info) || + 853 info->si_code >= 0))); + 854 if (q) { + 855 list_add_tail(&q->list, &pending->list); + 856 switch ((unsigned long) info) { + ... + 865 case (unsigned long) SEND_SIG_PRIV: + 866 q->info.si_signo = sig; + 867 q->info.si_errno = 0; + 868 q->info.si_code = SI_KERNEL; + 869 q->info.si_pid = 0; + 870 q->info.si_uid = 0; + 871 break; + ... + 890 } + +Not only does this match with the ``.si_code`` member, it also matches the place +we found earlier when looking for where siginfo_t objects are enqueued on the +``shared_pending`` list. + +So to sum up: It seems that it is the padding introduced by the compiler +between two struct fields that is uninitialized, and this gets reported when +we do a ``memcpy()`` on the struct. This means that we have identified a false +positive warning. + +Normally, kmemcheck will not report uninitialized accesses in ``memcpy()`` calls +when both the source and destination addresses are tracked. (Instead, we copy +the shadow bytemap as well). In this case, the destination address clearly +was not tracked. We can dig a little deeper into the stack trace from above:: + + arch/x86/kernel/signal.c:805 + arch/x86/kernel/signal.c:871 + arch/x86/kernel/entry_64.S:694 + +And we clearly see that the destination siginfo object is located on the +stack:: + + 782 static void do_signal(struct pt_regs *regs) + 783 { + 784 struct k_sigaction ka; + 785 siginfo_t info; + ... + 804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); + ... + 854 } + +And this ``&info`` is what eventually gets passed to ``copy_siginfo()`` as the +destination argument. + +Now, even though we didn't find an actual error here, the example is still a +good one, because it shows how one would go about to find out what the report +was all about. + + +Annotating false positives +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are a few different ways to make annotations in the source code that +will keep kmemcheck from checking and reporting certain allocations. Here +they are: + +- ``__GFP_NOTRACK_FALSE_POSITIVE`` + This flag can be passed to ``kmalloc()`` or ``kmem_cache_alloc()`` + (therefore also to other functions that end up calling one of + these) to indicate that the allocation should not be tracked + because it would lead to a false positive report. This is a "big + hammer" way of silencing kmemcheck; after all, even if the false + positive pertains to particular field in a struct, for example, we + will now lose the ability to find (real) errors in other parts of + the same struct. + + Example:: + + /* No warnings will ever trigger on accessing any part of x */ + x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); + +- ``kmemcheck_bitfield_begin(name)``/``kmemcheck_bitfield_end(name)`` and + ``kmemcheck_annotate_bitfield(ptr, name)`` + The first two of these three macros can be used inside struct + definitions to signal, respectively, the beginning and end of a + bitfield. Additionally, this will assign the bitfield a name, which + is given as an argument to the macros. + + Having used these markers, one can later use + kmemcheck_annotate_bitfield() at the point of allocation, to indicate + which parts of the allocation is part of a bitfield. + + Example:: + + struct foo { + int x; + + kmemcheck_bitfield_begin(flags); + int flag_a:1; + int flag_b:1; + kmemcheck_bitfield_end(flags); + + int y; + }; + + struct foo *x = kmalloc(sizeof *x); + + /* No warnings will trigger on accessing the bitfield of x */ + kmemcheck_annotate_bitfield(x, flags); + + Note that ``kmemcheck_annotate_bitfield()`` can be used even before the + return value of ``kmalloc()`` is checked -- in other words, passing NULL + as the first argument is legal (and will do nothing). + + +Reporting errors +---------------- + +As we have seen, kmemcheck will produce false positive reports. Therefore, it +is not very wise to blindly post kmemcheck warnings to mailing lists and +maintainers. Instead, I encourage maintainers and developers to find errors +in their own code. If you get a warning, you can try to work around it, try +to figure out if it's a real error or not, or simply ignore it. Most +developers know their own code and will quickly and efficiently determine the +root cause of a kmemcheck report. This is therefore also the most efficient +way to work with kmemcheck. + +That said, we (the kmemcheck maintainers) will always be on the lookout for +false positives that we can annotate and silence. So whatever you find, +please drop us a note privately! Kernel configs and steps to reproduce (if +available) are of course a great help too. + +Happy hacking! + + +Technical description +--------------------- + +kmemcheck works by marking memory pages non-present. This means that whenever +somebody attempts to access the page, a page fault is generated. The page +fault handler notices that the page was in fact only hidden, and so it calls +on the kmemcheck code to make further investigations. + +When the investigations are completed, kmemcheck "shows" the page by marking +it present (as it would be under normal circumstances). This way, the +interrupted code can continue as usual. + +But after the instruction has been executed, we should hide the page again, so +that we can catch the next access too! Now kmemcheck makes use of a debugging +feature of the processor, namely single-stepping. When the processor has +finished the one instruction that generated the memory access, a debug +exception is raised. From here, we simply hide the page again and continue +execution, this time with the single-stepping feature turned off. + +kmemcheck requires some assistance from the memory allocator in order to work. +The memory allocator needs to + + 1. Tell kmemcheck about newly allocated pages and pages that are about to + be freed. This allows kmemcheck to set up and tear down the shadow memory + for the pages in question. The shadow memory stores the status of each + byte in the allocation proper, e.g. whether it is initialized or + uninitialized. + + 2. Tell kmemcheck which parts of memory should be marked uninitialized. + There are actually a few more states, such as "not yet allocated" and + "recently freed". + +If a slab cache is set up using the SLAB_NOTRACK flag, it will never return +memory that can take page faults because of kmemcheck. + +If a slab cache is NOT set up using the SLAB_NOTRACK flag, callers can still +request memory with the __GFP_NOTRACK or __GFP_NOTRACK_FALSE_POSITIVE flags. +This does not prevent the page faults from occurring, however, but marks the +object in question as being initialized so that no warnings will ever be +produced for this object. + +Currently, the SLAB and SLUB allocators are supported by kmemcheck. diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst new file mode 100644 index 000000000000..b2391b829169 --- /dev/null +++ b/Documentation/dev-tools/kmemleak.rst @@ -0,0 +1,219 @@ +Kernel Memory Leak Detector +=========================== + +Kmemleak provides a way of detecting possible kernel memory leaks in a +way similar to a tracing garbage collector +(https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), +with the difference that the orphan objects are not freed but only +reported via /sys/kernel/debug/kmemleak. A similar method is used by the +Valgrind tool (``memcheck --leak-check``) to detect the memory leaks in +user-space applications. +Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. + +Usage +----- + +CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel +thread scans the memory every 10 minutes (by default) and prints the +number of new unreferenced objects found. To display the details of all +the possible memory leaks:: + + # mount -t debugfs nodev /sys/kernel/debug/ + # cat /sys/kernel/debug/kmemleak + +To trigger an intermediate memory scan:: + + # echo scan > /sys/kernel/debug/kmemleak + +To clear the list of all current possible memory leaks:: + + # echo clear > /sys/kernel/debug/kmemleak + +New leaks will then come up upon reading ``/sys/kernel/debug/kmemleak`` +again. + +Note that the orphan objects are listed in the order they were allocated +and one object at the beginning of the list may cause other subsequent +objects to be reported as orphan. + +Memory scanning parameters can be modified at run-time by writing to the +``/sys/kernel/debug/kmemleak`` file. The following parameters are supported: + +- off + disable kmemleak (irreversible) +- stack=on + enable the task stacks scanning (default) +- stack=off + disable the tasks stacks scanning +- scan=on + start the automatic memory scanning thread (default) +- scan=off + stop the automatic memory scanning thread +- scan= + set the automatic memory scanning period in seconds + (default 600, 0 to stop the automatic scanning) +- scan + trigger a memory scan +- clear + clear list of current memory leak suspects, done by + marking all current reported unreferenced objects grey, + or free all kmemleak objects if kmemleak has been disabled. +- dump= + dump information about the object found at + +Kmemleak can also be disabled at boot-time by passing ``kmemleak=off`` on +the kernel command line. + +Memory may be allocated or freed before kmemleak is initialised and +these actions are stored in an early log buffer. The size of this buffer +is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. + +If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is +disabled by default. Passing ``kmemleak=on`` on the kernel command +line enables the function. + +Basic Algorithm +--------------- + +The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`, +:c:func:`kmem_cache_alloc` and +friends are traced and the pointers, together with additional +information like size and stack trace, are stored in a rbtree. +The corresponding freeing function calls are tracked and the pointers +removed from the kmemleak data structures. + +An allocated block of memory is considered orphan if no pointer to its +start address or to any location inside the block can be found by +scanning the memory (including saved registers). This means that there +might be no way for the kernel to pass the address of the allocated +block to a freeing function and therefore the block is considered a +memory leak. + +The scanning algorithm steps: + + 1. mark all objects as white (remaining white objects will later be + considered orphan) + 2. scan the memory starting with the data section and stacks, checking + the values against the addresses stored in the rbtree. If + a pointer to a white object is found, the object is added to the + gray list + 3. scan the gray objects for matching addresses (some white objects + can become gray and added at the end of the gray list) until the + gray set is finished + 4. the remaining white objects are considered orphan and reported via + /sys/kernel/debug/kmemleak + +Some allocated memory blocks have pointers stored in the kernel's +internal data structures and they cannot be detected as orphans. To +avoid this, kmemleak can also store the number of values pointing to an +address inside the block address range that need to be found so that the +block is not considered a leak. One example is __vmalloc(). + +Testing specific sections with kmemleak +--------------------------------------- + +Upon initial bootup your /sys/kernel/debug/kmemleak output page may be +quite extensive. This can also be the case if you have very buggy code +when doing development. To work around these situations you can use the +'clear' command to clear all reported unreferenced objects from the +/sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' +you can find new unreferenced objects; this should help with testing +specific sections of code. + +To test a critical section on demand with a clean kmemleak do:: + + # echo clear > /sys/kernel/debug/kmemleak + ... test your kernel or modules ... + # echo scan > /sys/kernel/debug/kmemleak + +Then as usual to get your report with:: + + # cat /sys/kernel/debug/kmemleak + +Freeing kmemleak internal objects +--------------------------------- + +To allow access to previously found memory leaks after kmemleak has been +disabled by the user or due to an fatal error, internal kmemleak objects +won't be freed when kmemleak is disabled, and those objects may occupy +a large part of physical memory. + +In this situation, you may reclaim memory with:: + + # echo clear > /sys/kernel/debug/kmemleak + +Kmemleak API +------------ + +See the include/linux/kmemleak.h header for the functions prototype. + +- ``kmemleak_init`` - initialize kmemleak +- ``kmemleak_alloc`` - notify of a memory block allocation +- ``kmemleak_alloc_percpu`` - notify of a percpu memory block allocation +- ``kmemleak_free`` - notify of a memory block freeing +- ``kmemleak_free_part`` - notify of a partial memory block freeing +- ``kmemleak_free_percpu`` - notify of a percpu memory block freeing +- ``kmemleak_update_trace`` - update object allocation stack trace +- ``kmemleak_not_leak`` - mark an object as not a leak +- ``kmemleak_ignore`` - do not scan or report an object as leak +- ``kmemleak_scan_area`` - add scan areas inside a memory block +- ``kmemleak_no_scan`` - do not scan a memory block +- ``kmemleak_erase`` - erase an old value in a pointer variable +- ``kmemleak_alloc_recursive`` - as kmemleak_alloc but checks the recursiveness +- ``kmemleak_free_recursive`` - as kmemleak_free but checks the recursiveness + +The following functions take a physical address as the object pointer +and only perform the corresponding action if the address has a lowmem +mapping: + +- ``kmemleak_alloc_phys`` +- ``kmemleak_free_part_phys`` +- ``kmemleak_not_leak_phys`` +- ``kmemleak_ignore_phys`` + +Dealing with false positives/negatives +-------------------------------------- + +The false negatives are real memory leaks (orphan objects) but not +reported by kmemleak because values found during the memory scanning +point to such objects. To reduce the number of false negatives, kmemleak +provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and +kmemleak_erase functions (see above). The task stacks also increase the +amount of false negatives and their scanning is not enabled by default. + +The false positives are objects wrongly reported as being memory leaks +(orphan). For objects known not to be leaks, kmemleak provides the +kmemleak_not_leak function. The kmemleak_ignore could also be used if +the memory block is known not to contain other pointers and it will no +longer be scanned. + +Some of the reported leaks are only transient, especially on SMP +systems, because of pointers temporarily stored in CPU registers or +stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing +the minimum age of an object to be reported as a memory leak. + +Limitations and Drawbacks +------------------------- + +The main drawback is the reduced performance of memory allocation and +freeing. To avoid other penalties, the memory scanning is only performed +when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is +intended for debugging purposes where the performance might not be the +most important requirement. + +To keep the algorithm simple, kmemleak scans for values pointing to any +address inside a block's address range. This may lead to an increased +number of false negatives. However, it is likely that a real memory leak +will eventually become visible. + +Another source of false negatives is the data stored in non-pointer +values. In a future version, kmemleak could only scan the pointer +members in the allocated structures. This feature would solve many of +the false negative cases described above. + +The tool can report false positives. These are cases where an allocated +block doesn't need to be freed (some cases in the init_call functions), +the pointer is calculated by other methods than the usual container_of +macro or the pointer is stored in a location not scanned by kmemleak. + +Page allocations and ioremap are not tracked. diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst new file mode 100644 index 000000000000..8c250e8a2105 --- /dev/null +++ b/Documentation/dev-tools/sparse.rst @@ -0,0 +1,117 @@ +.. Copyright 2004 Linus Torvalds +.. Copyright 2004 Pavel Machek +.. Copyright 2006 Bob Copeland + +Sparse +====== + +Sparse is a semantic checker for C programs; it can be used to find a +number of potential problems with kernel code. See +https://lwn.net/Articles/689907/ for an overview of sparse; this document +contains some kernel-specific sparse information. + + +Using sparse for typechecking +----------------------------- + +"__bitwise" is a type attribute, so you have to do something like this:: + + typedef int __bitwise pm_request_t; + + enum pm_request { + PM_SUSPEND = (__force pm_request_t) 1, + PM_RESUME = (__force pm_request_t) 2 + }; + +which makes PM_SUSPEND and PM_RESUME "bitwise" integers (the "__force" is +there because sparse will complain about casting to/from a bitwise type, +but in this case we really _do_ want to force the conversion). And because +the enum values are all the same type, now "enum pm_request" will be that +type too. + +And with gcc, all the "__bitwise"/"__force stuff" goes away, and it all +ends up looking just like integers to gcc. + +Quite frankly, you don't need the enum there. The above all really just +boils down to one special "int __bitwise" type. + +So the simpler way is to just do:: + + typedef int __bitwise pm_request_t; + + #define PM_SUSPEND ((__force pm_request_t) 1) + #define PM_RESUME ((__force pm_request_t) 2) + +and you now have all the infrastructure needed for strict typechecking. + +One small note: the constant integer "0" is special. You can use a +constant zero as a bitwise integer type without sparse ever complaining. +This is because "bitwise" (as the name implies) was designed for making +sure that bitwise types don't get mixed up (little-endian vs big-endian +vs cpu-endian vs whatever), and there the constant "0" really _is_ +special. + +__bitwise__ - to be used for relatively compact stuff (gfp_t, etc.) that +is mostly warning-free and is supposed to stay that way. Warnings will +be generated without __CHECK_ENDIAN__. + +__bitwise - noisy stuff; in particular, __le*/__be* are that. We really +don't want to drown in noise unless we'd explicitly asked for it. + +Using sparse for lock checking +------------------------------ + +The following macros are undefined for gcc and defined during a sparse +run to use the "context" tracking feature of sparse, applied to +locking. These annotations tell sparse when a lock is held, with +regard to the annotated function's entry and exit. + +__must_hold - The specified lock is held on function entry and exit. + +__acquires - The specified lock is held on function exit, but not entry. + +__releases - The specified lock is held on function entry, but not exit. + +If the function enters and exits without the lock held, acquiring and +releasing the lock inside the function in a balanced way, no +annotation is needed. The tree annotations above are for cases where +sparse would otherwise report a context imbalance. + +Getting sparse +-------------- + +You can get latest released versions from the Sparse homepage at +https://sparse.wiki.kernel.org/index.php/Main_Page + +Alternatively, you can get snapshots of the latest development version +of sparse using git to clone:: + + git://git.kernel.org/pub/scm/devel/sparse/sparse.git + +DaveJ has hourly generated tarballs of the git tree available at:: + + http://www.codemonkey.org.uk/projects/git-snapshots/sparse/ + + +Once you have it, just do:: + + make + make install + +as a regular user, and it will install sparse in your ~/bin directory. + +Using sparse +------------ + +Do a kernel make with "make C=1" to run sparse on all the C files that get +recompiled, or use "make C=2" to run sparse on the files whether they need to +be recompiled or not. The latter is a fast way to check the whole tree if you +have already built it. + +The optional make variable CF can be used to pass arguments to sparse. The +build system passes -Wbitwise to sparse automatically. To perform endianness +checks, you may define __CHECK_ENDIAN__:: + + make C=2 CF="-D__CHECK_ENDIAN__" + +These checks are disabled by default as they generate a host of warnings. diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst new file mode 100644 index 000000000000..824ae8e54dd5 --- /dev/null +++ b/Documentation/dev-tools/tools.rst @@ -0,0 +1,25 @@ +================================ +Development tools for the kernel +================================ + +This document is a collection of documents about development tools that can +be used to work on the kernel. For now, the documents have been pulled +together without any significant effot to integrate them into a coherent +whole; patches welcome! + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + coccinelle + sparse + kcov + gcov + kasan + ubsan + kmemleak + kmemcheck + gdb-kernel-debugging diff --git a/Documentation/dev-tools/ubsan.rst b/Documentation/dev-tools/ubsan.rst new file mode 100644 index 000000000000..655e6b63c227 --- /dev/null +++ b/Documentation/dev-tools/ubsan.rst @@ -0,0 +1,88 @@ +The Undefined Behavior Sanitizer - UBSAN +======================================== + +UBSAN is a runtime undefined behaviour checker. + +UBSAN uses compile-time instrumentation to catch undefined behavior (UB). +Compiler inserts code that perform certain kinds of checks before operations +that may cause UB. If check fails (i.e. UB detected) __ubsan_handle_* +function called to print error message. + +GCC has that feature since 4.9.x [1_] (see ``-fsanitize=undefined`` option and +its suboptions). GCC 5.x has more checkers implemented [2_]. + +Report example +-------------- + +:: + + ================================================================================ + UBSAN: Undefined behaviour in ../include/linux/bitops.h:110:33 + shift exponent 32 is to large for 32-bit type 'unsigned int' + CPU: 0 PID: 0 Comm: swapper Not tainted 4.4.0-rc1+ #26 + 0000000000000000 ffffffff82403cc8 ffffffff815e6cd6 0000000000000001 + ffffffff82403cf8 ffffffff82403ce0 ffffffff8163a5ed 0000000000000020 + ffffffff82403d78 ffffffff8163ac2b ffffffff815f0001 0000000000000002 + Call Trace: + [] dump_stack+0x45/0x5f + [] ubsan_epilogue+0xd/0x40 + [] __ubsan_handle_shift_out_of_bounds+0xeb/0x130 + [] ? radix_tree_gang_lookup_slot+0x51/0x150 + [] _mix_pool_bytes+0x1e6/0x480 + [] ? dmi_walk_early+0x48/0x5c + [] add_device_randomness+0x61/0x130 + [] ? dmi_save_one_device+0xaa/0xaa + [] dmi_walk_early+0x48/0x5c + [] dmi_scan_machine+0x278/0x4b4 + [] ? vprintk_default+0x1a/0x20 + [] ? early_idt_handler_array+0x120/0x120 + [] setup_arch+0x405/0xc2c + [] ? early_idt_handler_array+0x120/0x120 + [] start_kernel+0x83/0x49a + [] ? early_idt_handler_array+0x120/0x120 + [] x86_64_start_reservations+0x2a/0x2c + [] x86_64_start_kernel+0x16b/0x17a + ================================================================================ + +Usage +----- + +To enable UBSAN configure kernel with:: + + CONFIG_UBSAN=y + +and to check the entire kernel:: + + CONFIG_UBSAN_SANITIZE_ALL=y + +To enable instrumentation for specific files or directories, add a line +similar to the following to the respective kernel Makefile: + +- For a single file (e.g. main.o):: + + UBSAN_SANITIZE_main.o := y + +- For all files in one directory:: + + UBSAN_SANITIZE := y + +To exclude files from being instrumented even if +``CONFIG_UBSAN_SANITIZE_ALL=y``, use:: + + UBSAN_SANITIZE_main.o := n + +and:: + + UBSAN_SANITIZE := n + +Detection of unaligned accesses controlled through the separate option - +CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support +unaligned accesses (CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS=y). One could +still enable it in config, just note that it will produce a lot of UBSAN +reports. + +References +---------- + +.. _1: https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/Debugging-Options.html +.. _2: https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro deleted file mode 100644 index 9b614480aa84..000000000000 --- a/Documentation/development-process/1.Intro +++ /dev/null @@ -1,274 +0,0 @@ -1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS - -The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is -accessible to those who are not intimately familiar with Linux kernel -development (or, indeed, free software development in general). While -there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to -understand. - - -1.1: EXECUTIVE SUMMARY - -The rest of this section covers the scope of the kernel development process -and the kinds of frustrations that developers and their employers can -encounter there. There are a great many reasons why kernel code should be -merged into the official ("mainline") kernel, including automatic -availability to users, community support in many forms, and the ability to -influence the direction of kernel development. Code contributed to the -Linux kernel must be made available under a GPL-compatible license. - -Section 2 introduces the development process, the kernel release cycle, and -the mechanics of the merge window. The various phases in the patch -development, review, and merging cycle are covered. There is some -discussion of tools and mailing lists. Developers wanting to get started -with kernel development are encouraged to track down and fix bugs as an -initial exercise. - -Section 3 covers early-stage project planning, with an emphasis on -involving the development community as soon as possible. - -Section 4 is about the coding process; several pitfalls which have been -encountered by other developers are discussed. Some requirements for -patches are covered, and there is an introduction to some of the tools -which can help to ensure that kernel patches are correct. - -Section 5 talks about the process of posting patches for review. To be -taken seriously by the development community, patches must be properly -formatted and described, and they must be sent to the right place. -Following the advice in this section should help to ensure the best -possible reception for your work. - -Section 6 covers what happens after posting patches; the job is far from -done at that point. Working with reviewers is a crucial part of the -development process; this section offers a number of tips on how to avoid -problems at this important stage. Developers are cautioned against -assuming that the job is done when a patch is merged into the mainline. - -Section 7 introduces a couple of "advanced" topics: managing patches with -git and reviewing patches posted by others. - -Section 8 concludes the document with pointers to sources for more -information on kernel development. - - -1.2: WHAT THIS DOCUMENT IS ABOUT - -The Linux kernel, at over 8 million lines of code and well over 1000 -contributors to each release, is one of the largest and most active free -software projects in existence. Since its humble beginning in 1991, this -kernel has evolved into a best-of-breed operating system component which -runs on pocket-sized digital music players, desktop PCs, the largest -supercomputers in existence, and all types of systems in between. It is a -robust, efficient, and scalable solution for almost any situation. - -With the growth of Linux has come an increase in the number of developers -(and companies) wishing to participate in its development. Hardware -vendors want to ensure that Linux supports their products well, making -those products attractive to Linux users. Embedded systems vendors, who -use Linux as a component in an integrated product, want Linux to be as -capable and well-suited to the task at hand as possible. Distributors and -other software vendors who base their products on Linux have a clear -interest in the capabilities, performance, and reliability of the Linux -kernel. And end users, too, will often wish to change Linux to make it -better suit their needs. - -One of the most compelling features of Linux is that it is accessible to -these developers; anybody with the requisite skills can improve Linux and -influence the direction of its development. Proprietary products cannot -offer this kind of openness, which is a characteristic of the free software -process. But, if anything, the kernel is even more open than most other -free software projects. A typical three-month kernel development cycle can -involve over 1000 developers working for more than 100 different companies -(or for no company at all). - -Working with the kernel development community is not especially hard. But, -that notwithstanding, many potential contributors have experienced -difficulties when trying to do kernel work. The kernel community has -evolved its own distinct ways of operating which allow it to function -smoothly (and produce a high-quality product) in an environment where -thousands of lines of code are being changed every day. So it is not -surprising that Linux kernel development process differs greatly from -proprietary development methods. - -The kernel's development process may come across as strange and -intimidating to new developers, but there are good reasons and solid -experience behind it. A developer who does not understand the kernel -community's ways (or, worse, who tries to flout or circumvent them) will -have a frustrating experience in store. The development community, while -being helpful to those who are trying to learn, has little time for those -who will not listen or who do not care about the development process. - -It is hoped that those who read this document will be able to avoid that -frustrating experience. There is a lot of material here, but the effort -involved in reading it will be repaid in short order. The development -community is always in need of developers who will help to make the kernel -better; the following text should help you - or those who work for you - -join our community. - - -1.3: CREDITS - -This document was written by Jonathan Corbet, corbet@lwn.net. It has been -improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland -Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, -Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and -Jochen Voß. - -This work was supported by the Linux Foundation; thanks especially to -Amanda McPherson, who saw the value of this effort and made it all happen. - - -1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE - -Some companies and developers occasionally wonder why they should bother -learning how to work with the kernel community and get their code into the -mainline kernel (the "mainline" being the kernel maintained by Linus -Torvalds and used as a base by Linux distributors). In the short term, -contributing code can look like an avoidable expense; it seems easier to -just keep the code separate and support users directly. The truth of the -matter is that keeping code separate ("out of tree") is a false economy. - -As a way of illustrating the costs of out-of-tree code, here are a few -relevant aspects of the kernel development process; most of these will be -discussed in greater detail later in this document. Consider: - -- Code which has been merged into the mainline kernel is available to all - Linux users. It will automatically be present on all distributions which - enable it. There is no need for driver disks, downloads, or the hassles - of supporting multiple versions of multiple distributions; it all just - works, for the developer and for the user. Incorporation into the - mainline solves a large number of distribution and support problems. - -- While kernel developers strive to maintain a stable interface to user - space, the internal kernel API is in constant flux. The lack of a stable - internal interface is a deliberate design decision; it allows fundamental - improvements to be made at any time and results in higher-quality code. - But one result of that policy is that any out-of-tree code requires - constant upkeep if it is to work with new kernels. Maintaining - out-of-tree code requires significant amounts of work just to keep that - code working. - - Code which is in the mainline, instead, does not require this work as the - result of a simple rule requiring any developer who makes an API change - to also fix any code that breaks as the result of that change. So code - which has been merged into the mainline has significantly lower - maintenance costs. - -- Beyond that, code which is in the kernel will often be improved by other - developers. Surprising results can come from empowering your user - community and customers to improve your product. - -- Kernel code is subjected to review, both before and after merging into - the mainline. No matter how strong the original developer's skills are, - this review process invariably finds ways in which the code can be - improved. Often review finds severe bugs and security problems. This is - especially true for code which has been developed in a closed - environment; such code benefits strongly from review by outside - developers. Out-of-tree code is lower-quality code. - -- Participation in the development process is your way to influence the - direction of kernel development. Users who complain from the sidelines - are heard, but active developers have a stronger voice - and the ability - to implement changes which make the kernel work better for their needs. - -- When code is maintained separately, the possibility that a third party - will contribute a different implementation of a similar feature always - exists. Should that happen, getting your code merged will become much - harder - to the point of impossibility. Then you will be faced with the - unpleasant alternatives of either (1) maintaining a nonstandard feature - out of tree indefinitely, or (2) abandoning your code and migrating your - users over to the in-tree version. - -- Contribution of code is the fundamental action which makes the whole - process work. By contributing your code you can add new functionality to - the kernel and provide capabilities and examples which are of use to - other kernel developers. If you have developed code for Linux (or are - thinking about doing so), you clearly have an interest in the continued - success of this platform; contributing code is one of the best ways to - help ensure that success. - -All of the reasoning above applies to any out-of-tree kernel code, -including code which is distributed in proprietary, binary-only form. -There are, however, additional factors which should be taken into account -before considering any sort of binary-only kernel code distribution. These -include: - -- The legal issues around the distribution of proprietary kernel modules - are cloudy at best; quite a few kernel copyright holders believe that - most binary-only modules are derived products of the kernel and that, as - a result, their distribution is a violation of the GNU General Public - license (about which more will be said below). Your author is not a - lawyer, and nothing in this document can possibly be considered to be - legal advice. The true legal status of closed-source modules can only be - determined by the courts. But the uncertainty which haunts those modules - is there regardless. - -- Binary modules greatly increase the difficulty of debugging kernel - problems, to the point that most kernel developers will not even try. So - the distribution of binary-only modules will make it harder for your - users to get support from the community. - -- Support is also harder for distributors of binary-only modules, who must - provide a version of the module for every distribution and every kernel - version they wish to support. Dozens of builds of a single module can - be required to provide reasonably comprehensive coverage, and your users - will have to upgrade your module separately every time they upgrade their - kernel. - -- Everything that was said above about code review applies doubly to - closed-source code. Since this code is not available at all, it cannot - have been reviewed by the community and will, beyond doubt, have serious - problems. - -Makers of embedded systems, in particular, may be tempted to disregard much -of what has been said in this section in the belief that they are shipping -a self-contained product which uses a frozen kernel version and requires no -more development after its release. This argument misses the value of -widespread code review and the value of allowing your users to add -capabilities to your product. But these products, too, have a limited -commercial life, after which a new version must be released. At that -point, vendors whose code is in the mainline and well maintained will be -much better positioned to get the new product ready for market quickly. - - -1.5: LICENSING - -Code is contributed to the Linux kernel under a number of licenses, but all -code must be compatible with version 2 of the GNU General Public License -(GPLv2), which is the license covering the kernel distribution as a whole. -In practice, that means that all code contributions are covered either by -GPLv2 (with, optionally, language allowing distribution under later -versions of the GPL) or the three-clause BSD license. Any contributions -which are not covered by a compatible license will not be accepted into the -kernel. - -Copyright assignments are not required (or requested) for code contributed -to the kernel. All code merged into the mainline kernel retains its -original ownership; as a result, the kernel now has thousands of owners. - -One implication of this ownership structure is that any attempt to change -the licensing of the kernel is doomed to almost certain failure. There are -few practical scenarios where the agreement of all copyright holders could -be obtained (or their code removed from the kernel). So, in particular, -there is no prospect of a migration to version 3 of the GPL in the -foreseeable future. - -It is imperative that all code contributed to the kernel be legitimately -free software. For that reason, code from anonymous (or pseudonymous) -contributors will not be accepted. All contributors are required to "sign -off" on their code, stating that the code can be distributed with the -kernel under the GPL. Code which has not been licensed as free software by -its owner, or which risks creating copyright-related problems for the -kernel (such as code which derives from reverse-engineering efforts lacking -proper safeguards) cannot be contributed. - -Questions about copyright-related issues are common on Linux development -mailing lists. Such questions will normally receive no shortage of -answers, but one should bear in mind that the people answering those -questions are not lawyers and cannot provide legal advice. If you have -legal questions relating to Linux source code, there is no substitute for -talking with a lawyer who understands this field. Relying on answers -obtained on technical mailing lists is a risky affair. diff --git a/Documentation/development-process/1.Intro.rst b/Documentation/development-process/1.Intro.rst new file mode 100644 index 000000000000..22642b3fe903 --- /dev/null +++ b/Documentation/development-process/1.Intro.rst @@ -0,0 +1,266 @@ +Introdution +=========== + +Executive summary +----------------- + +The rest of this section covers the scope of the kernel development process +and the kinds of frustrations that developers and their employers can +encounter there. There are a great many reasons why kernel code should be +merged into the official ("mainline") kernel, including automatic +availability to users, community support in many forms, and the ability to +influence the direction of kernel development. Code contributed to the +Linux kernel must be made available under a GPL-compatible license. + +:ref:`development_process` introduces the development process, the kernel +release cycle, and the mechanics of the merge window. The various phases in +the patch development, review, and merging cycle are covered. There is some +discussion of tools and mailing lists. Developers wanting to get started +with kernel development are encouraged to track down and fix bugs as an +initial exercise. + +:ref:`development_early_stage` covers early-stage project planning, with an +emphasis on involving the development community as soon as possible. + +:ref:`development_coding` is about the coding process; several pitfalls which +have been encountered by other developers are discussed. Some requirements for +patches are covered, and there is an introduction to some of the tools +which can help to ensure that kernel patches are correct. + +:ref:`development_posting` talks about the process of posting patches for +review. To be taken seriously by the development community, patches must be +properly formatted and described, and they must be sent to the right place. +Following the advice in this section should help to ensure the best +possible reception for your work. + +:ref:`development_followthrough` covers what happens after posting patches; the +job is far from done at that point. Working with reviewers is a crucial part +of the development process; this section offers a number of tips on how to +avoid problems at this important stage. Developers are cautioned against +assuming that the job is done when a patch is merged into the mainline. + +:ref:`development_advancedtopics` introduces a couple of "advanced" topics: +managing patches with git and reviewing patches posted by others. + +:ref:`development_conclusion` concludes the document with pointers to sources +for more information on kernel development. + +What this document is about +--------------------------- + +The Linux kernel, at over 8 million lines of code and well over 1000 +contributors to each release, is one of the largest and most active free +software projects in existence. Since its humble beginning in 1991, this +kernel has evolved into a best-of-breed operating system component which +runs on pocket-sized digital music players, desktop PCs, the largest +supercomputers in existence, and all types of systems in between. It is a +robust, efficient, and scalable solution for almost any situation. + +With the growth of Linux has come an increase in the number of developers +(and companies) wishing to participate in its development. Hardware +vendors want to ensure that Linux supports their products well, making +those products attractive to Linux users. Embedded systems vendors, who +use Linux as a component in an integrated product, want Linux to be as +capable and well-suited to the task at hand as possible. Distributors and +other software vendors who base their products on Linux have a clear +interest in the capabilities, performance, and reliability of the Linux +kernel. And end users, too, will often wish to change Linux to make it +better suit their needs. + +One of the most compelling features of Linux is that it is accessible to +these developers; anybody with the requisite skills can improve Linux and +influence the direction of its development. Proprietary products cannot +offer this kind of openness, which is a characteristic of the free software +process. But, if anything, the kernel is even more open than most other +free software projects. A typical three-month kernel development cycle can +involve over 1000 developers working for more than 100 different companies +(or for no company at all). + +Working with the kernel development community is not especially hard. But, +that notwithstanding, many potential contributors have experienced +difficulties when trying to do kernel work. The kernel community has +evolved its own distinct ways of operating which allow it to function +smoothly (and produce a high-quality product) in an environment where +thousands of lines of code are being changed every day. So it is not +surprising that Linux kernel development process differs greatly from +proprietary development methods. + +The kernel's development process may come across as strange and +intimidating to new developers, but there are good reasons and solid +experience behind it. A developer who does not understand the kernel +community's ways (or, worse, who tries to flout or circumvent them) will +have a frustrating experience in store. The development community, while +being helpful to those who are trying to learn, has little time for those +who will not listen or who do not care about the development process. + +It is hoped that those who read this document will be able to avoid that +frustrating experience. There is a lot of material here, but the effort +involved in reading it will be repaid in short order. The development +community is always in need of developers who will help to make the kernel +better; the following text should help you - or those who work for you - +join our community. + +Credits +------- + +This document was written by Jonathan Corbet, corbet@lwn.net. It has been +improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland +Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, +Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and +Jochen Voß. + +This work was supported by the Linux Foundation; thanks especially to +Amanda McPherson, who saw the value of this effort and made it all happen. + +The importance of getting code into the mainline +------------------------------------------------ + +Some companies and developers occasionally wonder why they should bother +learning how to work with the kernel community and get their code into the +mainline kernel (the "mainline" being the kernel maintained by Linus +Torvalds and used as a base by Linux distributors). In the short term, +contributing code can look like an avoidable expense; it seems easier to +just keep the code separate and support users directly. The truth of the +matter is that keeping code separate ("out of tree") is a false economy. + +As a way of illustrating the costs of out-of-tree code, here are a few +relevant aspects of the kernel development process; most of these will be +discussed in greater detail later in this document. Consider: + +- Code which has been merged into the mainline kernel is available to all + Linux users. It will automatically be present on all distributions which + enable it. There is no need for driver disks, downloads, or the hassles + of supporting multiple versions of multiple distributions; it all just + works, for the developer and for the user. Incorporation into the + mainline solves a large number of distribution and support problems. + +- While kernel developers strive to maintain a stable interface to user + space, the internal kernel API is in constant flux. The lack of a stable + internal interface is a deliberate design decision; it allows fundamental + improvements to be made at any time and results in higher-quality code. + But one result of that policy is that any out-of-tree code requires + constant upkeep if it is to work with new kernels. Maintaining + out-of-tree code requires significant amounts of work just to keep that + code working. + + Code which is in the mainline, instead, does not require this work as the + result of a simple rule requiring any developer who makes an API change + to also fix any code that breaks as the result of that change. So code + which has been merged into the mainline has significantly lower + maintenance costs. + +- Beyond that, code which is in the kernel will often be improved by other + developers. Surprising results can come from empowering your user + community and customers to improve your product. + +- Kernel code is subjected to review, both before and after merging into + the mainline. No matter how strong the original developer's skills are, + this review process invariably finds ways in which the code can be + improved. Often review finds severe bugs and security problems. This is + especially true for code which has been developed in a closed + environment; such code benefits strongly from review by outside + developers. Out-of-tree code is lower-quality code. + +- Participation in the development process is your way to influence the + direction of kernel development. Users who complain from the sidelines + are heard, but active developers have a stronger voice - and the ability + to implement changes which make the kernel work better for their needs. + +- When code is maintained separately, the possibility that a third party + will contribute a different implementation of a similar feature always + exists. Should that happen, getting your code merged will become much + harder - to the point of impossibility. Then you will be faced with the + unpleasant alternatives of either (1) maintaining a nonstandard feature + out of tree indefinitely, or (2) abandoning your code and migrating your + users over to the in-tree version. + +- Contribution of code is the fundamental action which makes the whole + process work. By contributing your code you can add new functionality to + the kernel and provide capabilities and examples which are of use to + other kernel developers. If you have developed code for Linux (or are + thinking about doing so), you clearly have an interest in the continued + success of this platform; contributing code is one of the best ways to + help ensure that success. + +All of the reasoning above applies to any out-of-tree kernel code, +including code which is distributed in proprietary, binary-only form. +There are, however, additional factors which should be taken into account +before considering any sort of binary-only kernel code distribution. These +include: + +- The legal issues around the distribution of proprietary kernel modules + are cloudy at best; quite a few kernel copyright holders believe that + most binary-only modules are derived products of the kernel and that, as + a result, their distribution is a violation of the GNU General Public + license (about which more will be said below). Your author is not a + lawyer, and nothing in this document can possibly be considered to be + legal advice. The true legal status of closed-source modules can only be + determined by the courts. But the uncertainty which haunts those modules + is there regardless. + +- Binary modules greatly increase the difficulty of debugging kernel + problems, to the point that most kernel developers will not even try. So + the distribution of binary-only modules will make it harder for your + users to get support from the community. + +- Support is also harder for distributors of binary-only modules, who must + provide a version of the module for every distribution and every kernel + version they wish to support. Dozens of builds of a single module can + be required to provide reasonably comprehensive coverage, and your users + will have to upgrade your module separately every time they upgrade their + kernel. + +- Everything that was said above about code review applies doubly to + closed-source code. Since this code is not available at all, it cannot + have been reviewed by the community and will, beyond doubt, have serious + problems. + +Makers of embedded systems, in particular, may be tempted to disregard much +of what has been said in this section in the belief that they are shipping +a self-contained product which uses a frozen kernel version and requires no +more development after its release. This argument misses the value of +widespread code review and the value of allowing your users to add +capabilities to your product. But these products, too, have a limited +commercial life, after which a new version must be released. At that +point, vendors whose code is in the mainline and well maintained will be +much better positioned to get the new product ready for market quickly. + +Licensing +--------- + +Code is contributed to the Linux kernel under a number of licenses, but all +code must be compatible with version 2 of the GNU General Public License +(GPLv2), which is the license covering the kernel distribution as a whole. +In practice, that means that all code contributions are covered either by +GPLv2 (with, optionally, language allowing distribution under later +versions of the GPL) or the three-clause BSD license. Any contributions +which are not covered by a compatible license will not be accepted into the +kernel. + +Copyright assignments are not required (or requested) for code contributed +to the kernel. All code merged into the mainline kernel retains its +original ownership; as a result, the kernel now has thousands of owners. + +One implication of this ownership structure is that any attempt to change +the licensing of the kernel is doomed to almost certain failure. There are +few practical scenarios where the agreement of all copyright holders could +be obtained (or their code removed from the kernel). So, in particular, +there is no prospect of a migration to version 3 of the GPL in the +foreseeable future. + +It is imperative that all code contributed to the kernel be legitimately +free software. For that reason, code from anonymous (or pseudonymous) +contributors will not be accepted. All contributors are required to "sign +off" on their code, stating that the code can be distributed with the +kernel under the GPL. Code which has not been licensed as free software by +its owner, or which risks creating copyright-related problems for the +kernel (such as code which derives from reverse-engineering efforts lacking +proper safeguards) cannot be contributed. + +Questions about copyright-related issues are common on Linux development +mailing lists. Such questions will normally receive no shortage of +answers, but one should bear in mind that the people answering those +questions are not lawyers and cannot provide legal advice. If you have +legal questions relating to Linux source code, there is no substitute for +talking with a lawyer who understands this field. Relying on answers +obtained on technical mailing lists is a risky affair. diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process deleted file mode 100644 index c24e156a6118..000000000000 --- a/Documentation/development-process/2.Process +++ /dev/null @@ -1,478 +0,0 @@ -2: HOW THE DEVELOPMENT PROCESS WORKS - -Linux kernel development in the early 1990's was a pretty loose affair, -with relatively small numbers of users and developers involved. With a -user base in the millions and with some 2,000 developers involved over the -course of one year, the kernel has since had to evolve a number of -processes to keep development happening smoothly. A solid understanding of -how the process works is required in order to be an effective part of it. - - -2.1: THE BIG PICTURE - -The kernel developers use a loosely time-based release process, with a new -major kernel release happening every two or three months. The recent -release history looks like this: - - 2.6.38 March 14, 2011 - 2.6.37 January 4, 2011 - 2.6.36 October 20, 2010 - 2.6.35 August 1, 2010 - 2.6.34 May 15, 2010 - 2.6.33 February 24, 2010 - -Every 2.6.x release is a major kernel release with new features, internal -API changes, and more. A typical 2.6 release can contain nearly 10,000 -changesets with changes to several hundred thousand lines of code. 2.6 is -thus the leading edge of Linux kernel development; the kernel uses a -rolling development model which is continually integrating major changes. - -A relatively straightforward discipline is followed with regard to the -merging of patches for each release. At the beginning of each development -cycle, the "merge window" is said to be open. At that time, code which is -deemed to be sufficiently stable (and which is accepted by the development -community) is merged into the mainline kernel. The bulk of changes for a -new development cycle (and all of the major changes) will be merged during -this time, at a rate approaching 1,000 changes ("patches," or "changesets") -per day. - -(As an aside, it is worth noting that the changes integrated during the -merge window do not come out of thin air; they have been collected, tested, -and staged ahead of time. How that process works will be described in -detail later on). - -The merge window lasts for approximately two weeks. At the end of this -time, Linus Torvalds will declare that the window is closed and release the -first of the "rc" kernels. For the kernel which is destined to be 2.6.40, -for example, the release which happens at the end of the merge window will -be called 2.6.40-rc1. The -rc1 release is the signal that the time to -merge new features has passed, and that the time to stabilize the next -kernel has begun. - -Over the next six to ten weeks, only patches which fix problems should be -submitted to the mainline. On occasion a more significant change will be -allowed, but such occasions are rare; developers who try to merge new -features outside of the merge window tend to get an unfriendly reception. -As a general rule, if you miss the merge window for a given feature, the -best thing to do is to wait for the next development cycle. (An occasional -exception is made for drivers for previously-unsupported hardware; if they -touch no in-tree code, they cannot cause regressions and should be safe to -add at any time). - -As fixes make their way into the mainline, the patch rate will slow over -time. Linus releases new -rc kernels about once a week; a normal series -will get up to somewhere between -rc6 and -rc9 before the kernel is -considered to be sufficiently stable and the final 2.6.x release is made. -At that point the whole process starts over again. - -As an example, here is how the 2.6.38 development cycle went (all dates in -2011): - - January 4 2.6.37 stable release - January 18 2.6.38-rc1, merge window closes - January 21 2.6.38-rc2 - February 1 2.6.38-rc3 - February 7 2.6.38-rc4 - February 15 2.6.38-rc5 - February 21 2.6.38-rc6 - March 1 2.6.38-rc7 - March 7 2.6.38-rc8 - March 14 2.6.38 stable release - -How do the developers decide when to close the development cycle and create -the stable release? The most significant metric used is the list of -regressions from previous releases. No bugs are welcome, but those which -break systems which worked in the past are considered to be especially -serious. For this reason, patches which cause regressions are looked upon -unfavorably and are quite likely to be reverted during the stabilization -period. - -The developers' goal is to fix all known regressions before the stable -release is made. In the real world, this kind of perfection is hard to -achieve; there are just too many variables in a project of this size. -There comes a point where delaying the final release just makes the problem -worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 2.6.x -kernels go out with a handful of known regressions though, hopefully, none -of them are serious. - -Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently consisting of Greg Kroah-Hartman. The stable team -will release occasional updates to the stable release using the 2.6.x.y -numbering scheme. To be considered for an update release, a patch must (1) -fix a significant bug, and (2) already be merged into the mainline for the -next development kernel. Kernels will typically receive stable updates for -a little more than one development cycle past their initial release. So, -for example, the 2.6.36 kernel's history looked like: - - October 10 2.6.36 stable release - November 22 2.6.36.1 - December 9 2.6.36.2 - January 7 2.6.36.3 - February 17 2.6.36.4 - -2.6.36.4 was the final stable update for the 2.6.36 release. - -Some kernels are designated "long term" kernels; they will receive support -for a longer period. As of this writing, the current long term kernels -and their maintainers are: - - 2.6.27 Willy Tarreau (Deep-frozen stable kernel) - 2.6.32 Greg Kroah-Hartman - 2.6.35 Andi Kleen (Embedded flag kernel) - -The selection of a kernel for long-term support is purely a matter of a -maintainer having the need and the time to maintain that release. There -are no known plans for long-term support for any specific upcoming -release. - - -2.2: THE LIFECYCLE OF A PATCH - -Patches do not go directly from the developer's keyboard into the mainline -kernel. There is, instead, a somewhat involved (if somewhat informal) -process designed to ensure that each patch is reviewed for quality and that -each patch implements a change which is desirable to have in the mainline. -This process can happen quickly for minor fixes, or, in the case of large -and controversial changes, go on for years. Much developer frustration -comes from a lack of understanding of this process or from attempts to -circumvent it. - -In the hopes of reducing that frustration, this document will describe how -a patch gets into the kernel. What follows below is an introduction which -describes the process in a somewhat idealized way. A much more detailed -treatment will come in later sections. - -The stages that a patch goes through are, generally: - - - Design. This is where the real requirements for the patch - and the way - those requirements will be met - are laid out. Design work is often - done without involving the community, but it is better to do this work - in the open if at all possible; it can save a lot of time redesigning - things later. - - - Early review. Patches are posted to the relevant mailing list, and - developers on that list reply with any comments they may have. This - process should turn up any major problems with a patch if all goes - well. - - - Wider review. When the patch is getting close to ready for mainline - inclusion, it should be accepted by a relevant subsystem maintainer - - though this acceptance is not a guarantee that the patch will make it - all the way to the mainline. The patch will show up in the maintainer's - subsystem tree and into the -next trees (described below). When the - process works, this step leads to more extensive review of the patch and - the discovery of any problems resulting from the integration of this - patch with work being done by others. - -- Please note that most maintainers also have day jobs, so merging - your patch may not be their highest priority. If your patch is - getting feedback about changes that are needed, you should either - make those changes or justify why they should not be made. If your - patch has no review complaints but is not being merged by its - appropriate subsystem or driver maintainer, you should be persistent - in updating the patch to the current kernel so that it applies cleanly - and keep sending it for review and merging. - - - Merging into the mainline. Eventually, a successful patch will be - merged into the mainline repository managed by Linus Torvalds. More - comments and/or problems may surface at this time; it is important that - the developer be responsive to these and fix any issues which arise. - - - Stable release. The number of users potentially affected by the patch - is now large, so, once again, new problems may arise. - - - Long-term maintenance. While it is certainly possible for a developer - to forget about code after merging it, that sort of behavior tends to - leave a poor impression in the development community. Merging code - eliminates some of the maintenance burden, in that others will fix - problems caused by API changes. But the original developer should - continue to take responsibility for the code if it is to remain useful - in the longer term. - -One of the largest mistakes made by kernel developers (or their employers) -is to try to cut the process down to a single "merging into the mainline" -step. This approach invariably leads to frustration for everybody -involved. - - -2.3: HOW PATCHES GET INTO THE KERNEL - -There is exactly one person who can merge patches into the mainline kernel -repository: Linus Torvalds. But, of the over 9,500 patches which went -into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus -himself. The kernel project has long since grown to a size where no single -developer could possibly inspect and select every patch unassisted. The -way the kernel developers have addressed this growth is through the use of -a lieutenant system built around a chain of trust. - -The kernel code base is logically broken down into a set of subsystems: -networking, specific architecture support, memory management, video -devices, etc. Most subsystems have a designated maintainer, a developer -who has overall responsibility for the code within that subsystem. These -subsystem maintainers are the gatekeepers (in a loose way) for the portion -of the kernel they manage; they are the ones who will (usually) accept a -patch for inclusion into the mainline kernel. - -Subsystem maintainers each manage their own version of the kernel source -tree, usually (but certainly not always) using the git source management -tool. Tools like git (and related tools like quilt or mercurial) allow -maintainers to track a list of patches, including authorship information -and other metadata. At any given time, the maintainer can identify which -patches in his or her repository are not found in the mainline. - -When the merge window opens, top-level maintainers will ask Linus to "pull" -the patches they have selected for merging from their repositories. If -Linus agrees, the stream of patches will flow up into his repository, -becoming part of the mainline kernel. The amount of attention that Linus -pays to specific patches received in a pull operation varies. It is clear -that, sometimes, he looks quite closely. But, as a general rule, Linus -trusts the subsystem maintainers to not send bad patches upstream. - -Subsystem maintainers, in turn, can pull patches from other maintainers. -For example, the networking tree is built from patches which accumulated -first in trees dedicated to network device drivers, wireless networking, -etc. This chain of repositories can be arbitrarily long, though it rarely -exceeds two or three links. Since each maintainer in the chain trusts -those managing lower-level trees, this process is known as the "chain of -trust." - -Clearly, in a system like this, getting patches into the kernel depends on -finding the right maintainer. Sending patches directly to Linus is not -normally the right way to go. - - -2.4: NEXT TREES - -The chain of subsystem trees guides the flow of patches into the kernel, -but it also raises an interesting question: what if somebody wants to look -at all of the patches which are being prepared for the next merge window? -Developers will be interested in what other changes are pending to see -whether there are any conflicts to worry about; a patch which changes a -core kernel function prototype, for example, will conflict with any other -patches which use the older form of that function. Reviewers and testers -want access to the changes in their integrated form before all of those -changes land in the mainline kernel. One could pull changes from all of -the interesting subsystem trees, but that would be a big and error-prone -job. - -The answer comes in the form of -next trees, where subsystem trees are -collected for testing and review. The older of these trees, maintained by -Andrew Morton, is called "-mm" (for memory management, which is how it got -started). The -mm tree integrates patches from a long list of subsystem -trees; it also has some patches aimed at helping with debugging. - -Beyond that, -mm contains a significant collection of patches which have -been selected by Andrew directly. These patches may have been posted on a -mailing list, or they may apply to a part of the kernel for which there is -no designated subsystem tree. As a result, -mm operates as a sort of -subsystem tree of last resort; if there is no other obvious path for a -patch into the mainline, it is likely to end up in -mm. Miscellaneous -patches which accumulate in -mm will eventually either be forwarded on to -an appropriate subsystem tree or be sent directly to Linus. In a typical -development cycle, approximately 5-10% of the patches going into the -mainline get there via -mm. - -The current -mm patch is available in the "mmotm" (-mm of the moment) -directory at: - - http://www.ozlabs.org/~akpm/mmotm/ - -Use of the MMOTM tree is likely to be a frustrating experience, though; -there is a definite chance that it will not even compile. - -The primary tree for next-cycle patch merging is linux-next, maintained by -Stephen Rothwell. The linux-next tree is, by design, a snapshot of what -the mainline is expected to look like after the next merge window closes. -Linux-next trees are announced on the linux-kernel and linux-next mailing -lists when they are assembled; they can be downloaded from: - - http://www.kernel.org/pub/linux/kernel/next/ - -Linux-next has become an integral part of the kernel development process; -all patches merged during a given merge window should really have found -their way into linux-next some time before the merge window opens. - - -2.4.1: STAGING TREES - -The kernel source tree contains the drivers/staging/ directory, where -many sub-directories for drivers or filesystems that are on their way to -being added to the kernel tree live. They remain in drivers/staging while -they still need more work; once complete, they can be moved into the -kernel proper. This is a way to keep track of drivers that aren't -up to Linux kernel coding or quality standards, but people may want to use -them and track development. - -Greg Kroah-Hartman currently maintains the staging tree. Drivers that -still need work are sent to him, with each driver having its own -subdirectory in drivers/staging/. Along with the driver source files, a -TODO file should be present in the directory as well. The TODO file lists -the pending work that the driver needs for acceptance into the kernel -proper, as well as a list of people that should be Cc'd for any patches to -the driver. Current rules require that drivers contributed to staging -must, at a minimum, compile properly. - -Staging can be a relatively easy way to get new drivers into the mainline -where, with luck, they will come to the attention of other developers and -improve quickly. Entry into staging is not the end of the story, though; -code in staging which is not seeing regular progress will eventually be -removed. Distributors also tend to be relatively reluctant to enable -staging drivers. So staging is, at best, a stop on the way toward becoming -a proper mainline driver. - - -2.5: TOOLS - -As can be seen from the above text, the kernel development process depends -heavily on the ability to herd collections of patches in various -directions. The whole thing would not work anywhere near as well as it -does without suitably powerful tools. Tutorials on how to use these tools -are well beyond the scope of this document, but there is space for a few -pointers. - -By far the dominant source code management system used by the kernel -community is git. Git is one of a number of distributed version control -systems being developed in the free software community. It is well tuned -for kernel development, in that it performs quite well when dealing with -large repositories and large numbers of patches. It also has a reputation -for being difficult to learn and use, though it has gotten better over -time. Some sort of familiarity with git is almost a requirement for kernel -developers; even if they do not use it for their own work, they'll need git -to keep up with what other developers (and the mainline) are doing. - -Git is now packaged by almost all Linux distributions. There is a home -page at: - - http://git-scm.com/ - -That page has pointers to documentation and tutorials. - -Among the kernel developers who do not use git, the most popular choice is -almost certainly Mercurial: - - http://www.selenic.com/mercurial/ - -Mercurial shares many features with git, but it provides an interface which -many find easier to use. - -The other tool worth knowing about is Quilt: - - http://savannah.nongnu.org/projects/quilt/ - -Quilt is a patch management system, rather than a source code management -system. It does not track history over time; it is, instead, oriented -toward tracking a specific set of changes against an evolving code base. -Some major subsystem maintainers use quilt to manage patches intended to go -upstream. For the management of certain kinds of trees (-mm, for example), -quilt is the best tool for the job. - - -2.6: MAILING LISTS - -A great deal of Linux kernel development work is done by way of mailing -lists. It is hard to be a fully-functioning member of the community -without joining at least one list somewhere. But Linux mailing lists also -represent a potential hazard to developers, who risk getting buried under a -load of electronic mail, running afoul of the conventions used on the Linux -lists, or both. - -Most kernel mailing lists are run on vger.kernel.org; the master list can -be found at: - - http://vger.kernel.org/vger-lists.html - -There are lists hosted elsewhere, though; a number of them are at -lists.redhat.com. - -The core mailing list for kernel development is, of course, linux-kernel. -This list is an intimidating place to be; volume can reach 500 messages per -day, the amount of noise is high, the conversation can be severely -technical, and participants are not always concerned with showing a high -degree of politeness. But there is no other place where the kernel -development community comes together as a whole; developers who avoid this -list will miss important information. - -There are a few hints which can help with linux-kernel survival: - -- Have the list delivered to a separate folder, rather than your main - mailbox. One must be able to ignore the stream for sustained periods of - time. - -- Do not try to follow every conversation - nobody else does. It is - important to filter on both the topic of interest (though note that - long-running conversations can drift away from the original subject - without changing the email subject line) and the people who are - participating. - -- Do not feed the trolls. If somebody is trying to stir up an angry - response, ignore them. - -- When responding to linux-kernel email (or that on other lists) preserve - the Cc: header for all involved. In the absence of a strong reason (such - as an explicit request), you should never remove recipients. Always make - sure that the person you are responding to is in the Cc: list. This - convention also makes it unnecessary to explicitly ask to be copied on - replies to your postings. - -- Search the list archives (and the net as a whole) before asking - questions. Some developers can get impatient with people who clearly - have not done their homework. - -- Avoid top-posting (the practice of putting your answer above the quoted - text you are responding to). It makes your response harder to read and - makes a poor impression. - -- Ask on the correct mailing list. Linux-kernel may be the general meeting - point, but it is not the best place to find developers from all - subsystems. - -The last point - finding the correct mailing list - is a common place for -beginning developers to go wrong. Somebody who asks a networking-related -question on linux-kernel will almost certainly receive a polite suggestion -to ask on the netdev list instead, as that is the list frequented by most -networking developers. Other lists exist for the SCSI, video4linux, IDE, -filesystem, etc. subsystems. The best place to look for mailing lists is -in the MAINTAINERS file packaged with the kernel source. - - -2.7: GETTING STARTED WITH KERNEL DEVELOPMENT - -Questions about how to get started with the kernel development process are -common - from both individuals and companies. Equally common are missteps -which make the beginning of the relationship harder than it has to be. - -Companies often look to hire well-known developers to get a development -group started. This can, in fact, be an effective technique. But it also -tends to be expensive and does not do much to grow the pool of experienced -kernel developers. It is possible to bring in-house developers up to speed -on Linux kernel development, given the investment of a bit of time. Taking -this time can endow an employer with a group of developers who understand -the kernel and the company both, and who can help to train others as well. -Over the medium term, this is often the more profitable approach. - -Individual developers are often, understandably, at a loss for a place to -start. Beginning with a large project can be intimidating; one often wants -to test the waters with something smaller first. This is the point where -some developers jump into the creation of patches fixing spelling errors or -minor coding style issues. Unfortunately, such patches create a level of -noise which is distracting for the development community as a whole, so, -increasingly, they are looked down upon. New developers wishing to -introduce themselves to the community will not get the sort of reception -they wish for by these means. - -Andrew Morton gives this advice for aspiring kernel developers - - The #1 project for all kernel beginners should surely be "make sure - that the kernel runs perfectly at all times on all machines which - you can lay your hands on". Usually the way to do this is to work - with others on getting things fixed up (this can require - persistence!) but that's fine - it's a part of kernel development. - -(http://lwn.net/Articles/283982/). - -In the absence of obvious problems to fix, developers are advised to look -at the current lists of regressions and open bugs in general. There is -never any shortage of issues in need of fixing; by addressing these issues, -developers will gain experience with the process while, at the same time, -building respect with the rest of the development community. diff --git a/Documentation/development-process/2.Process.rst b/Documentation/development-process/2.Process.rst new file mode 100644 index 000000000000..ce5561bb3f8e --- /dev/null +++ b/Documentation/development-process/2.Process.rst @@ -0,0 +1,497 @@ +.. _development_process: + +How the development process works +================================= + +Linux kernel development in the early 1990's was a pretty loose affair, +with relatively small numbers of users and developers involved. With a +user base in the millions and with some 2,000 developers involved over the +course of one year, the kernel has since had to evolve a number of +processes to keep development happening smoothly. A solid understanding of +how the process works is required in order to be an effective part of it. + +The big picture +--------------- + +The kernel developers use a loosely time-based release process, with a new +major kernel release happening every two or three months. The recent +release history looks like this: + + ====== ================= + 2.6.38 March 14, 2011 + 2.6.37 January 4, 2011 + 2.6.36 October 20, 2010 + 2.6.35 August 1, 2010 + 2.6.34 May 15, 2010 + 2.6.33 February 24, 2010 + ====== ================= + +Every 2.6.x release is a major kernel release with new features, internal +API changes, and more. A typical 2.6 release can contain nearly 10,000 +changesets with changes to several hundred thousand lines of code. 2.6 is +thus the leading edge of Linux kernel development; the kernel uses a +rolling development model which is continually integrating major changes. + +A relatively straightforward discipline is followed with regard to the +merging of patches for each release. At the beginning of each development +cycle, the "merge window" is said to be open. At that time, code which is +deemed to be sufficiently stable (and which is accepted by the development +community) is merged into the mainline kernel. The bulk of changes for a +new development cycle (and all of the major changes) will be merged during +this time, at a rate approaching 1,000 changes ("patches," or "changesets") +per day. + +(As an aside, it is worth noting that the changes integrated during the +merge window do not come out of thin air; they have been collected, tested, +and staged ahead of time. How that process works will be described in +detail later on). + +The merge window lasts for approximately two weeks. At the end of this +time, Linus Torvalds will declare that the window is closed and release the +first of the "rc" kernels. For the kernel which is destined to be 2.6.40, +for example, the release which happens at the end of the merge window will +be called 2.6.40-rc1. The -rc1 release is the signal that the time to +merge new features has passed, and that the time to stabilize the next +kernel has begun. + +Over the next six to ten weeks, only patches which fix problems should be +submitted to the mainline. On occasion a more significant change will be +allowed, but such occasions are rare; developers who try to merge new +features outside of the merge window tend to get an unfriendly reception. +As a general rule, if you miss the merge window for a given feature, the +best thing to do is to wait for the next development cycle. (An occasional +exception is made for drivers for previously-unsupported hardware; if they +touch no in-tree code, they cannot cause regressions and should be safe to +add at any time). + +As fixes make their way into the mainline, the patch rate will slow over +time. Linus releases new -rc kernels about once a week; a normal series +will get up to somewhere between -rc6 and -rc9 before the kernel is +considered to be sufficiently stable and the final 2.6.x release is made. +At that point the whole process starts over again. + +As an example, here is how the 2.6.38 development cycle went (all dates in +2011): + + ============== =============================== + January 4 2.6.37 stable release + January 18 2.6.38-rc1, merge window closes + January 21 2.6.38-rc2 + February 1 2.6.38-rc3 + February 7 2.6.38-rc4 + February 15 2.6.38-rc5 + February 21 2.6.38-rc6 + March 1 2.6.38-rc7 + March 7 2.6.38-rc8 + March 14 2.6.38 stable release + ============== =============================== + +How do the developers decide when to close the development cycle and create +the stable release? The most significant metric used is the list of +regressions from previous releases. No bugs are welcome, but those which +break systems which worked in the past are considered to be especially +serious. For this reason, patches which cause regressions are looked upon +unfavorably and are quite likely to be reverted during the stabilization +period. + +The developers' goal is to fix all known regressions before the stable +release is made. In the real world, this kind of perfection is hard to +achieve; there are just too many variables in a project of this size. +There comes a point where delaying the final release just makes the problem +worse; the pile of changes waiting for the next merge window will grow +larger, creating even more regressions the next time around. So most 2.6.x +kernels go out with a handful of known regressions though, hopefully, none +of them are serious. + +Once a stable release is made, its ongoing maintenance is passed off to the +"stable team," currently consisting of Greg Kroah-Hartman. The stable team +will release occasional updates to the stable release using the 2.6.x.y +numbering scheme. To be considered for an update release, a patch must (1) +fix a significant bug, and (2) already be merged into the mainline for the +next development kernel. Kernels will typically receive stable updates for +a little more than one development cycle past their initial release. So, +for example, the 2.6.36 kernel's history looked like: + + ============== =============================== + October 10 2.6.36 stable release + November 22 2.6.36.1 + December 9 2.6.36.2 + January 7 2.6.36.3 + February 17 2.6.36.4 + ============== =============================== + +2.6.36.4 was the final stable update for the 2.6.36 release. + +Some kernels are designated "long term" kernels; they will receive support +for a longer period. As of this writing, the current long term kernels +and their maintainers are: + + ====== ====================== =========================== + 2.6.27 Willy Tarreau (Deep-frozen stable kernel) + 2.6.32 Greg Kroah-Hartman + 2.6.35 Andi Kleen (Embedded flag kernel) + ====== ====================== =========================== + +The selection of a kernel for long-term support is purely a matter of a +maintainer having the need and the time to maintain that release. There +are no known plans for long-term support for any specific upcoming +release. + + +The lifecycle of a patch +------------------------ + +Patches do not go directly from the developer's keyboard into the mainline +kernel. There is, instead, a somewhat involved (if somewhat informal) +process designed to ensure that each patch is reviewed for quality and that +each patch implements a change which is desirable to have in the mainline. +This process can happen quickly for minor fixes, or, in the case of large +and controversial changes, go on for years. Much developer frustration +comes from a lack of understanding of this process or from attempts to +circumvent it. + +In the hopes of reducing that frustration, this document will describe how +a patch gets into the kernel. What follows below is an introduction which +describes the process in a somewhat idealized way. A much more detailed +treatment will come in later sections. + +The stages that a patch goes through are, generally: + + - Design. This is where the real requirements for the patch - and the way + those requirements will be met - are laid out. Design work is often + done without involving the community, but it is better to do this work + in the open if at all possible; it can save a lot of time redesigning + things later. + + - Early review. Patches are posted to the relevant mailing list, and + developers on that list reply with any comments they may have. This + process should turn up any major problems with a patch if all goes + well. + + - Wider review. When the patch is getting close to ready for mainline + inclusion, it should be accepted by a relevant subsystem maintainer - + though this acceptance is not a guarantee that the patch will make it + all the way to the mainline. The patch will show up in the maintainer's + subsystem tree and into the -next trees (described below). When the + process works, this step leads to more extensive review of the patch and + the discovery of any problems resulting from the integration of this + patch with work being done by others. + +- Please note that most maintainers also have day jobs, so merging + your patch may not be their highest priority. If your patch is + getting feedback about changes that are needed, you should either + make those changes or justify why they should not be made. If your + patch has no review complaints but is not being merged by its + appropriate subsystem or driver maintainer, you should be persistent + in updating the patch to the current kernel so that it applies cleanly + and keep sending it for review and merging. + + - Merging into the mainline. Eventually, a successful patch will be + merged into the mainline repository managed by Linus Torvalds. More + comments and/or problems may surface at this time; it is important that + the developer be responsive to these and fix any issues which arise. + + - Stable release. The number of users potentially affected by the patch + is now large, so, once again, new problems may arise. + + - Long-term maintenance. While it is certainly possible for a developer + to forget about code after merging it, that sort of behavior tends to + leave a poor impression in the development community. Merging code + eliminates some of the maintenance burden, in that others will fix + problems caused by API changes. But the original developer should + continue to take responsibility for the code if it is to remain useful + in the longer term. + +One of the largest mistakes made by kernel developers (or their employers) +is to try to cut the process down to a single "merging into the mainline" +step. This approach invariably leads to frustration for everybody +involved. + +How patches get into the Kernel +------------------------------- + +There is exactly one person who can merge patches into the mainline kernel +repository: Linus Torvalds. But, of the over 9,500 patches which went +into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus +himself. The kernel project has long since grown to a size where no single +developer could possibly inspect and select every patch unassisted. The +way the kernel developers have addressed this growth is through the use of +a lieutenant system built around a chain of trust. + +The kernel code base is logically broken down into a set of subsystems: +networking, specific architecture support, memory management, video +devices, etc. Most subsystems have a designated maintainer, a developer +who has overall responsibility for the code within that subsystem. These +subsystem maintainers are the gatekeepers (in a loose way) for the portion +of the kernel they manage; they are the ones who will (usually) accept a +patch for inclusion into the mainline kernel. + +Subsystem maintainers each manage their own version of the kernel source +tree, usually (but certainly not always) using the git source management +tool. Tools like git (and related tools like quilt or mercurial) allow +maintainers to track a list of patches, including authorship information +and other metadata. At any given time, the maintainer can identify which +patches in his or her repository are not found in the mainline. + +When the merge window opens, top-level maintainers will ask Linus to "pull" +the patches they have selected for merging from their repositories. If +Linus agrees, the stream of patches will flow up into his repository, +becoming part of the mainline kernel. The amount of attention that Linus +pays to specific patches received in a pull operation varies. It is clear +that, sometimes, he looks quite closely. But, as a general rule, Linus +trusts the subsystem maintainers to not send bad patches upstream. + +Subsystem maintainers, in turn, can pull patches from other maintainers. +For example, the networking tree is built from patches which accumulated +first in trees dedicated to network device drivers, wireless networking, +etc. This chain of repositories can be arbitrarily long, though it rarely +exceeds two or three links. Since each maintainer in the chain trusts +those managing lower-level trees, this process is known as the "chain of +trust." + +Clearly, in a system like this, getting patches into the kernel depends on +finding the right maintainer. Sending patches directly to Linus is not +normally the right way to go. + + +Next trees +---------- + +The chain of subsystem trees guides the flow of patches into the kernel, +but it also raises an interesting question: what if somebody wants to look +at all of the patches which are being prepared for the next merge window? +Developers will be interested in what other changes are pending to see +whether there are any conflicts to worry about; a patch which changes a +core kernel function prototype, for example, will conflict with any other +patches which use the older form of that function. Reviewers and testers +want access to the changes in their integrated form before all of those +changes land in the mainline kernel. One could pull changes from all of +the interesting subsystem trees, but that would be a big and error-prone +job. + +The answer comes in the form of -next trees, where subsystem trees are +collected for testing and review. The older of these trees, maintained by +Andrew Morton, is called "-mm" (for memory management, which is how it got +started). The -mm tree integrates patches from a long list of subsystem +trees; it also has some patches aimed at helping with debugging. + +Beyond that, -mm contains a significant collection of patches which have +been selected by Andrew directly. These patches may have been posted on a +mailing list, or they may apply to a part of the kernel for which there is +no designated subsystem tree. As a result, -mm operates as a sort of +subsystem tree of last resort; if there is no other obvious path for a +patch into the mainline, it is likely to end up in -mm. Miscellaneous +patches which accumulate in -mm will eventually either be forwarded on to +an appropriate subsystem tree or be sent directly to Linus. In a typical +development cycle, approximately 5-10% of the patches going into the +mainline get there via -mm. + +The current -mm patch is available in the "mmotm" (-mm of the moment) +directory at: + + http://www.ozlabs.org/~akpm/mmotm/ + +Use of the MMOTM tree is likely to be a frustrating experience, though; +there is a definite chance that it will not even compile. + +The primary tree for next-cycle patch merging is linux-next, maintained by +Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +the mainline is expected to look like after the next merge window closes. +Linux-next trees are announced on the linux-kernel and linux-next mailing +lists when they are assembled; they can be downloaded from: + + http://www.kernel.org/pub/linux/kernel/next/ + +Linux-next has become an integral part of the kernel development process; +all patches merged during a given merge window should really have found +their way into linux-next some time before the merge window opens. + + +Staging trees +------------- + +The kernel source tree contains the drivers/staging/ directory, where +many sub-directories for drivers or filesystems that are on their way to +being added to the kernel tree live. They remain in drivers/staging while +they still need more work; once complete, they can be moved into the +kernel proper. This is a way to keep track of drivers that aren't +up to Linux kernel coding or quality standards, but people may want to use +them and track development. + +Greg Kroah-Hartman currently maintains the staging tree. Drivers that +still need work are sent to him, with each driver having its own +subdirectory in drivers/staging/. Along with the driver source files, a +TODO file should be present in the directory as well. The TODO file lists +the pending work that the driver needs for acceptance into the kernel +proper, as well as a list of people that should be Cc'd for any patches to +the driver. Current rules require that drivers contributed to staging +must, at a minimum, compile properly. + +Staging can be a relatively easy way to get new drivers into the mainline +where, with luck, they will come to the attention of other developers and +improve quickly. Entry into staging is not the end of the story, though; +code in staging which is not seeing regular progress will eventually be +removed. Distributors also tend to be relatively reluctant to enable +staging drivers. So staging is, at best, a stop on the way toward becoming +a proper mainline driver. + + +Tools +----- + +As can be seen from the above text, the kernel development process depends +heavily on the ability to herd collections of patches in various +directions. The whole thing would not work anywhere near as well as it +does without suitably powerful tools. Tutorials on how to use these tools +are well beyond the scope of this document, but there is space for a few +pointers. + +By far the dominant source code management system used by the kernel +community is git. Git is one of a number of distributed version control +systems being developed in the free software community. It is well tuned +for kernel development, in that it performs quite well when dealing with +large repositories and large numbers of patches. It also has a reputation +for being difficult to learn and use, though it has gotten better over +time. Some sort of familiarity with git is almost a requirement for kernel +developers; even if they do not use it for their own work, they'll need git +to keep up with what other developers (and the mainline) are doing. + +Git is now packaged by almost all Linux distributions. There is a home +page at: + + http://git-scm.com/ + +That page has pointers to documentation and tutorials. + +Among the kernel developers who do not use git, the most popular choice is +almost certainly Mercurial: + + http://www.selenic.com/mercurial/ + +Mercurial shares many features with git, but it provides an interface which +many find easier to use. + +The other tool worth knowing about is Quilt: + + http://savannah.nongnu.org/projects/quilt/ + +Quilt is a patch management system, rather than a source code management +system. It does not track history over time; it is, instead, oriented +toward tracking a specific set of changes against an evolving code base. +Some major subsystem maintainers use quilt to manage patches intended to go +upstream. For the management of certain kinds of trees (-mm, for example), +quilt is the best tool for the job. + + +Mailing lists +------------- + +A great deal of Linux kernel development work is done by way of mailing +lists. It is hard to be a fully-functioning member of the community +without joining at least one list somewhere. But Linux mailing lists also +represent a potential hazard to developers, who risk getting buried under a +load of electronic mail, running afoul of the conventions used on the Linux +lists, or both. + +Most kernel mailing lists are run on vger.kernel.org; the master list can +be found at: + + http://vger.kernel.org/vger-lists.html + +There are lists hosted elsewhere, though; a number of them are at +lists.redhat.com. + +The core mailing list for kernel development is, of course, linux-kernel. +This list is an intimidating place to be; volume can reach 500 messages per +day, the amount of noise is high, the conversation can be severely +technical, and participants are not always concerned with showing a high +degree of politeness. But there is no other place where the kernel +development community comes together as a whole; developers who avoid this +list will miss important information. + +There are a few hints which can help with linux-kernel survival: + +- Have the list delivered to a separate folder, rather than your main + mailbox. One must be able to ignore the stream for sustained periods of + time. + +- Do not try to follow every conversation - nobody else does. It is + important to filter on both the topic of interest (though note that + long-running conversations can drift away from the original subject + without changing the email subject line) and the people who are + participating. + +- Do not feed the trolls. If somebody is trying to stir up an angry + response, ignore them. + +- When responding to linux-kernel email (or that on other lists) preserve + the Cc: header for all involved. In the absence of a strong reason (such + as an explicit request), you should never remove recipients. Always make + sure that the person you are responding to is in the Cc: list. This + convention also makes it unnecessary to explicitly ask to be copied on + replies to your postings. + +- Search the list archives (and the net as a whole) before asking + questions. Some developers can get impatient with people who clearly + have not done their homework. + +- Avoid top-posting (the practice of putting your answer above the quoted + text you are responding to). It makes your response harder to read and + makes a poor impression. + +- Ask on the correct mailing list. Linux-kernel may be the general meeting + point, but it is not the best place to find developers from all + subsystems. + +The last point - finding the correct mailing list - is a common place for +beginning developers to go wrong. Somebody who asks a networking-related +question on linux-kernel will almost certainly receive a polite suggestion +to ask on the netdev list instead, as that is the list frequented by most +networking developers. Other lists exist for the SCSI, video4linux, IDE, +filesystem, etc. subsystems. The best place to look for mailing lists is +in the MAINTAINERS file packaged with the kernel source. + + +Getting started with Kernel development +--------------------------------------- + +Questions about how to get started with the kernel development process are +common - from both individuals and companies. Equally common are missteps +which make the beginning of the relationship harder than it has to be. + +Companies often look to hire well-known developers to get a development +group started. This can, in fact, be an effective technique. But it also +tends to be expensive and does not do much to grow the pool of experienced +kernel developers. It is possible to bring in-house developers up to speed +on Linux kernel development, given the investment of a bit of time. Taking +this time can endow an employer with a group of developers who understand +the kernel and the company both, and who can help to train others as well. +Over the medium term, this is often the more profitable approach. + +Individual developers are often, understandably, at a loss for a place to +start. Beginning with a large project can be intimidating; one often wants +to test the waters with something smaller first. This is the point where +some developers jump into the creation of patches fixing spelling errors or +minor coding style issues. Unfortunately, such patches create a level of +noise which is distracting for the development community as a whole, so, +increasingly, they are looked down upon. New developers wishing to +introduce themselves to the community will not get the sort of reception +they wish for by these means. + +Andrew Morton gives this advice for aspiring kernel developers + +:: + + The #1 project for all kernel beginners should surely be "make sure + that the kernel runs perfectly at all times on all machines which + you can lay your hands on". Usually the way to do this is to work + with others on getting things fixed up (this can require + persistence!) but that's fine - it's a part of kernel development. + +(http://lwn.net/Articles/283982/). + +In the absence of obvious problems to fix, developers are advised to look +at the current lists of regressions and open bugs in general. There is +never any shortage of issues in need of fixing; by addressing these issues, +developers will gain experience with the process while, at the same time, +building respect with the rest of the development community. diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage deleted file mode 100644 index f87ba7b3fbac..000000000000 --- a/Documentation/development-process/3.Early-stage +++ /dev/null @@ -1,212 +0,0 @@ -3: EARLY-STAGE PLANNING - -When contemplating a Linux kernel development project, it can be tempting -to jump right in and start coding. As with any significant project, -though, much of the groundwork for success is best laid before the first -line of code is written. Some time spent in early planning and -communication can save far more time later on. - - -3.1: SPECIFYING THE PROBLEM - -Like any engineering project, a successful kernel enhancement starts with a -clear description of the problem to be solved. In some cases, this step is -easy: when a driver is needed for a specific piece of hardware, for -example. In others, though, it is tempting to confuse the real problem -with the proposed solution, and that can lead to difficulties. - -Consider an example: some years ago, developers working with Linux audio -sought a way to run applications without dropouts or other artifacts caused -by excessive latency in the system. The solution they arrived at was a -kernel module intended to hook into the Linux Security Module (LSM) -framework; this module could be configured to give specific applications -access to the realtime scheduler. This module was implemented and sent to -the linux-kernel mailing list, where it immediately ran into problems. - -To the audio developers, this security module was sufficient to solve their -immediate problem. To the wider kernel community, though, it was seen as a -misuse of the LSM framework (which is not intended to confer privileges -onto processes which they would not otherwise have) and a risk to system -stability. Their preferred solutions involved realtime scheduling access -via the rlimit mechanism for the short term, and ongoing latency reduction -work in the long term. - -The audio community, however, could not see past the particular solution -they had implemented; they were unwilling to accept alternatives. The -resulting disagreement left those developers feeling disillusioned with the -entire kernel development process; one of them went back to an audio list -and posted this: - - There are a number of very good Linux kernel developers, but they - tend to get outshouted by a large crowd of arrogant fools. Trying - to communicate user requirements to these people is a waste of - time. They are much too "intelligent" to listen to lesser mortals. - -(http://lwn.net/Articles/131776/). - -The reality of the situation was different; the kernel developers were far -more concerned about system stability, long-term maintenance, and finding -the right solution to the problem than they were with a specific module. -The moral of the story is to focus on the problem - not a specific solution -- and to discuss it with the development community before investing in the -creation of a body of code. - -So, when contemplating a kernel development project, one should obtain -answers to a short set of questions: - - - What, exactly, is the problem which needs to be solved? - - - Who are the users affected by this problem? Which use cases should the - solution address? - - - How does the kernel fall short in addressing that problem now? - -Only then does it make sense to start considering possible solutions. - - -3.2: EARLY DISCUSSION - -When planning a kernel development project, it makes great sense to hold -discussions with the community before launching into implementation. Early -communication can save time and trouble in a number of ways: - - - It may well be that the problem is addressed by the kernel in ways which - you have not understood. The Linux kernel is large and has a number of - features and capabilities which are not immediately obvious. Not all - kernel capabilities are documented as well as one might like, and it is - easy to miss things. Your author has seen the posting of a complete - driver which duplicated an existing driver that the new author had been - unaware of. Code which reinvents existing wheels is not only wasteful; - it will also not be accepted into the mainline kernel. - - - There may be elements of the proposed solution which will not be - acceptable for mainline merging. It is better to find out about - problems like this before writing the code. - - - It's entirely possible that other developers have thought about the - problem; they may have ideas for a better solution, and may be willing - to help in the creation of that solution. - -Years of experience with the kernel development community have taught a -clear lesson: kernel code which is designed and developed behind closed -doors invariably has problems which are only revealed when the code is -released into the community. Sometimes these problems are severe, -requiring months or years of effort before the code can be brought up to -the kernel community's standards. Some examples include: - - - The Devicescape network stack was designed and implemented for - single-processor systems. It could not be merged into the mainline - until it was made suitable for multiprocessor systems. Retrofitting - locking and such into code is a difficult task; as a result, the merging - of this code (now called mac80211) was delayed for over a year. - - - The Reiser4 filesystem included a number of capabilities which, in the - core kernel developers' opinion, should have been implemented in the - virtual filesystem layer instead. It also included features which could - not easily be implemented without exposing the system to user-caused - deadlocks. The late revelation of these problems - and refusal to - address some of them - has caused Reiser4 to stay out of the mainline - kernel. - - - The AppArmor security module made use of internal virtual filesystem - data structures in ways which were considered to be unsafe and - unreliable. This concern (among others) kept AppArmor out of the - mainline for years. - -In each of these cases, a great deal of pain and extra work could have been -avoided with some early discussion with the kernel developers. - - -3.3: WHO DO YOU TALK TO? - -When developers decide to take their plans public, the next question will -be: where do we start? The answer is to find the right mailing list(s) and -the right maintainer. For mailing lists, the best approach is to look in -the MAINTAINERS file for a relevant place to post. If there is a suitable -subsystem list, posting there is often preferable to posting on -linux-kernel; you are more likely to reach developers with expertise in the -relevant subsystem and the environment may be more supportive. - -Finding maintainers can be a bit harder. Again, the MAINTAINERS file is -the place to start. That file tends to not always be up to date, though, -and not all subsystems are represented there. The person listed in the -MAINTAINERS file may, in fact, not be the person who is actually acting in -that role currently. So, when there is doubt about who to contact, a -useful trick is to use git (and "git log" in particular) to see who is -currently active within the subsystem of interest. Look at who is writing -patches, and who, if anybody, is attaching Signed-off-by lines to those -patches. Those are the people who will be best placed to help with a new -development project. - -The task of finding the right maintainer is sometimes challenging enough -that the kernel developers have added a script to ease the process: - - .../scripts/get_maintainer.pl - -This script will return the current maintainer(s) for a given file or -directory when given the "-f" option. If passed a patch on the -command line, it will list the maintainers who should probably receive -copies of the patch. There are a number of options regulating how hard -get_maintainer.pl will search for maintainers; please be careful about -using the more aggressive options as you may end up including developers -who have no real interest in the code you are modifying. - -If all else fails, talking to Andrew Morton can be an effective way to -track down a maintainer for a specific piece of code. - - -3.4: WHEN TO POST? - -If possible, posting your plans during the early stages can only be -helpful. Describe the problem being solved and any plans that have been -made on how the implementation will be done. Any information you can -provide can help the development community provide useful input on the -project. - -One discouraging thing which can happen at this stage is not a hostile -reaction, but, instead, little or no reaction at all. The sad truth of the -matter is (1) kernel developers tend to be busy, (2) there is no shortage -of people with grand plans and little code (or even prospect of code) to -back them up, and (3) nobody is obligated to review or comment on ideas -posted by others. Beyond that, high-level designs often hide problems -which are only reviewed when somebody actually tries to implement those -designs; for that reason, kernel developers would rather see the code. - -If a request-for-comments posting yields little in the way of comments, do -not assume that it means there is no interest in the project. -Unfortunately, you also cannot assume that there are no problems with your -idea. The best thing to do in this situation is to proceed, keeping the -community informed as you go. - - -3.5: GETTING OFFICIAL BUY-IN - -If your work is being done in a corporate environment - as most Linux -kernel work is - you must, obviously, have permission from suitably -empowered managers before you can post your company's plans or code to a -public mailing list. The posting of code which has not been cleared for -release under a GPL-compatible license can be especially problematic; the -sooner that a company's management and legal staff can agree on the posting -of a kernel development project, the better off everybody involved will be. - -Some readers may be thinking at this point that their kernel work is -intended to support a product which does not yet have an officially -acknowledged existence. Revealing their employer's plans on a public -mailing list may not be a viable option. In cases like this, it is worth -considering whether the secrecy is really necessary; there is often no real -need to keep development plans behind closed doors. - -That said, there are also cases where a company legitimately cannot -disclose its plans early in the development process. Companies with -experienced kernel developers may choose to proceed in an open-loop manner -on the assumption that they will be able to avoid serious integration -problems later. For companies without that sort of in-house expertise, the -best option is often to hire an outside developer to review the plans under -a non-disclosure agreement. The Linux Foundation operates an NDA program -designed to help with this sort of situation; more information can be found -at: - - http://www.linuxfoundation.org/en/NDA_program - -This kind of review is often enough to avoid serious problems later on -without requiring public disclosure of the project. diff --git a/Documentation/development-process/3.Early-stage.rst b/Documentation/development-process/3.Early-stage.rst new file mode 100644 index 000000000000..af2c0af931d6 --- /dev/null +++ b/Documentation/development-process/3.Early-stage.rst @@ -0,0 +1,222 @@ +.. _development_early_stage: + +Early-stage planning +==================== + +When contemplating a Linux kernel development project, it can be tempting +to jump right in and start coding. As with any significant project, +though, much of the groundwork for success is best laid before the first +line of code is written. Some time spent in early planning and +communication can save far more time later on. + + +Specifying the problem +---------------------- + +Like any engineering project, a successful kernel enhancement starts with a +clear description of the problem to be solved. In some cases, this step is +easy: when a driver is needed for a specific piece of hardware, for +example. In others, though, it is tempting to confuse the real problem +with the proposed solution, and that can lead to difficulties. + +Consider an example: some years ago, developers working with Linux audio +sought a way to run applications without dropouts or other artifacts caused +by excessive latency in the system. The solution they arrived at was a +kernel module intended to hook into the Linux Security Module (LSM) +framework; this module could be configured to give specific applications +access to the realtime scheduler. This module was implemented and sent to +the linux-kernel mailing list, where it immediately ran into problems. + +To the audio developers, this security module was sufficient to solve their +immediate problem. To the wider kernel community, though, it was seen as a +misuse of the LSM framework (which is not intended to confer privileges +onto processes which they would not otherwise have) and a risk to system +stability. Their preferred solutions involved realtime scheduling access +via the rlimit mechanism for the short term, and ongoing latency reduction +work in the long term. + +The audio community, however, could not see past the particular solution +they had implemented; they were unwilling to accept alternatives. The +resulting disagreement left those developers feeling disillusioned with the +entire kernel development process; one of them went back to an audio list +and posted this: + + There are a number of very good Linux kernel developers, but they + tend to get outshouted by a large crowd of arrogant fools. Trying + to communicate user requirements to these people is a waste of + time. They are much too "intelligent" to listen to lesser mortals. + +(http://lwn.net/Articles/131776/). + +The reality of the situation was different; the kernel developers were far +more concerned about system stability, long-term maintenance, and finding +the right solution to the problem than they were with a specific module. +The moral of the story is to focus on the problem - not a specific solution +- and to discuss it with the development community before investing in the +creation of a body of code. + +So, when contemplating a kernel development project, one should obtain +answers to a short set of questions: + + - What, exactly, is the problem which needs to be solved? + + - Who are the users affected by this problem? Which use cases should the + solution address? + + - How does the kernel fall short in addressing that problem now? + +Only then does it make sense to start considering possible solutions. + + +Early discussion +---------------- + +When planning a kernel development project, it makes great sense to hold +discussions with the community before launching into implementation. Early +communication can save time and trouble in a number of ways: + + - It may well be that the problem is addressed by the kernel in ways which + you have not understood. The Linux kernel is large and has a number of + features and capabilities which are not immediately obvious. Not all + kernel capabilities are documented as well as one might like, and it is + easy to miss things. Your author has seen the posting of a complete + driver which duplicated an existing driver that the new author had been + unaware of. Code which reinvents existing wheels is not only wasteful; + it will also not be accepted into the mainline kernel. + + - There may be elements of the proposed solution which will not be + acceptable for mainline merging. It is better to find out about + problems like this before writing the code. + + - It's entirely possible that other developers have thought about the + problem; they may have ideas for a better solution, and may be willing + to help in the creation of that solution. + +Years of experience with the kernel development community have taught a +clear lesson: kernel code which is designed and developed behind closed +doors invariably has problems which are only revealed when the code is +released into the community. Sometimes these problems are severe, +requiring months or years of effort before the code can be brought up to +the kernel community's standards. Some examples include: + + - The Devicescape network stack was designed and implemented for + single-processor systems. It could not be merged into the mainline + until it was made suitable for multiprocessor systems. Retrofitting + locking and such into code is a difficult task; as a result, the merging + of this code (now called mac80211) was delayed for over a year. + + - The Reiser4 filesystem included a number of capabilities which, in the + core kernel developers' opinion, should have been implemented in the + virtual filesystem layer instead. It also included features which could + not easily be implemented without exposing the system to user-caused + deadlocks. The late revelation of these problems - and refusal to + address some of them - has caused Reiser4 to stay out of the mainline + kernel. + + - The AppArmor security module made use of internal virtual filesystem + data structures in ways which were considered to be unsafe and + unreliable. This concern (among others) kept AppArmor out of the + mainline for years. + +In each of these cases, a great deal of pain and extra work could have been +avoided with some early discussion with the kernel developers. + + +Who do you talk to? +------------------- + +When developers decide to take their plans public, the next question will +be: where do we start? The answer is to find the right mailing list(s) and +the right maintainer. For mailing lists, the best approach is to look in +the MAINTAINERS file for a relevant place to post. If there is a suitable +subsystem list, posting there is often preferable to posting on +linux-kernel; you are more likely to reach developers with expertise in the +relevant subsystem and the environment may be more supportive. + +Finding maintainers can be a bit harder. Again, the MAINTAINERS file is +the place to start. That file tends to not always be up to date, though, +and not all subsystems are represented there. The person listed in the +MAINTAINERS file may, in fact, not be the person who is actually acting in +that role currently. So, when there is doubt about who to contact, a +useful trick is to use git (and "git log" in particular) to see who is +currently active within the subsystem of interest. Look at who is writing +patches, and who, if anybody, is attaching Signed-off-by lines to those +patches. Those are the people who will be best placed to help with a new +development project. + +The task of finding the right maintainer is sometimes challenging enough +that the kernel developers have added a script to ease the process: + +:: + + .../scripts/get_maintainer.pl + +This script will return the current maintainer(s) for a given file or +directory when given the "-f" option. If passed a patch on the +command line, it will list the maintainers who should probably receive +copies of the patch. There are a number of options regulating how hard +get_maintainer.pl will search for maintainers; please be careful about +using the more aggressive options as you may end up including developers +who have no real interest in the code you are modifying. + +If all else fails, talking to Andrew Morton can be an effective way to +track down a maintainer for a specific piece of code. + + +When to post? +------------- + +If possible, posting your plans during the early stages can only be +helpful. Describe the problem being solved and any plans that have been +made on how the implementation will be done. Any information you can +provide can help the development community provide useful input on the +project. + +One discouraging thing which can happen at this stage is not a hostile +reaction, but, instead, little or no reaction at all. The sad truth of the +matter is (1) kernel developers tend to be busy, (2) there is no shortage +of people with grand plans and little code (or even prospect of code) to +back them up, and (3) nobody is obligated to review or comment on ideas +posted by others. Beyond that, high-level designs often hide problems +which are only reviewed when somebody actually tries to implement those +designs; for that reason, kernel developers would rather see the code. + +If a request-for-comments posting yields little in the way of comments, do +not assume that it means there is no interest in the project. +Unfortunately, you also cannot assume that there are no problems with your +idea. The best thing to do in this situation is to proceed, keeping the +community informed as you go. + + +Getting official buy-in +----------------------- + +If your work is being done in a corporate environment - as most Linux +kernel work is - you must, obviously, have permission from suitably +empowered managers before you can post your company's plans or code to a +public mailing list. The posting of code which has not been cleared for +release under a GPL-compatible license can be especially problematic; the +sooner that a company's management and legal staff can agree on the posting +of a kernel development project, the better off everybody involved will be. + +Some readers may be thinking at this point that their kernel work is +intended to support a product which does not yet have an officially +acknowledged existence. Revealing their employer's plans on a public +mailing list may not be a viable option. In cases like this, it is worth +considering whether the secrecy is really necessary; there is often no real +need to keep development plans behind closed doors. + +That said, there are also cases where a company legitimately cannot +disclose its plans early in the development process. Companies with +experienced kernel developers may choose to proceed in an open-loop manner +on the assumption that they will be able to avoid serious integration +problems later. For companies without that sort of in-house expertise, the +best option is often to hire an outside developer to review the plans under +a non-disclosure agreement. The Linux Foundation operates an NDA program +designed to help with this sort of situation; more information can be found +at: + + http://www.linuxfoundation.org/en/NDA_program + +This kind of review is often enough to avoid serious problems later on +without requiring public disclosure of the project. diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding deleted file mode 100644 index 9a3ee77cefb1..000000000000 --- a/Documentation/development-process/4.Coding +++ /dev/null @@ -1,399 +0,0 @@ -4: GETTING THE CODE RIGHT - -While there is much to be said for a solid and community-oriented design -process, the proof of any kernel development project is in the resulting -code. It is the code which will be examined by other developers and merged -(or not) into the mainline tree. So it is the quality of this code which -will determine the ultimate success of the project. - -This section will examine the coding process. We'll start with a look at a -number of ways in which kernel developers can go wrong. Then the focus -will shift toward doing things right and the tools which can help in that -quest. - - -4.1: PITFALLS - -* Coding style - -The kernel has long had a standard coding style, described in -Documentation/CodingStyle. For much of that time, the policies described -in that file were taken as being, at most, advisory. As a result, there is -a substantial amount of code in the kernel which does not meet the coding -style guidelines. The presence of that code leads to two independent -hazards for kernel developers. - -The first of these is to believe that the kernel coding standards do not -matter and are not enforced. The truth of the matter is that adding new -code to the kernel is very difficult if that code is not coded according to -the standard; many developers will request that the code be reformatted -before they will even review it. A code base as large as the kernel -requires some uniformity of code to make it possible for developers to -quickly understand any part of it. So there is no longer room for -strangely-formatted code. - -Occasionally, the kernel's coding style will run into conflict with an -employer's mandated style. In such cases, the kernel's style will have to -win before the code can be merged. Putting code into the kernel means -giving up a degree of control in a number of ways - including control over -how the code is formatted. - -The other trap is to assume that code which is already in the kernel is -urgently in need of coding style fixes. Developers may start to generate -reformatting patches as a way of gaining familiarity with the process, or -as a way of getting their name into the kernel changelogs - or both. But -pure coding style fixes are seen as noise by the development community; -they tend to get a chilly reception. So this type of patch is best -avoided. It is natural to fix the style of a piece of code while working -on it for other reasons, but coding style changes should not be made for -their own sake. - -The coding style document also should not be read as an absolute law which -can never be transgressed. If there is a good reason to go against the -style (a line which becomes far less readable if split to fit within the -80-column limit, for example), just do it. - - -* Abstraction layers - -Computer Science professors teach students to make extensive use of -abstraction layers in the name of flexibility and information hiding. -Certainly the kernel makes extensive use of abstraction; no project -involving several million lines of code could do otherwise and survive. -But experience has shown that excessive or premature abstraction can be -just as harmful as premature optimization. Abstraction should be used to -the level required and no further. - -At a simple level, consider a function which has an argument which is -always passed as zero by all callers. One could retain that argument just -in case somebody eventually needs to use the extra flexibility that it -provides. By that time, though, chances are good that the code which -implements this extra argument has been broken in some subtle way which was -never noticed - because it has never been used. Or, when the need for -extra flexibility arises, it does not do so in a way which matches the -programmer's early expectation. Kernel developers will routinely submit -patches to remove unused arguments; they should, in general, not be added -in the first place. - -Abstraction layers which hide access to hardware - often to allow the bulk -of a driver to be used with multiple operating systems - are especially -frowned upon. Such layers obscure the code and may impose a performance -penalty; they do not belong in the Linux kernel. - -On the other hand, if you find yourself copying significant amounts of code -from another kernel subsystem, it is time to ask whether it would, in fact, -make sense to pull out some of that code into a separate library or to -implement that functionality at a higher level. There is no value in -replicating the same code throughout the kernel. - - -* #ifdef and preprocessor use in general - -The C preprocessor seems to present a powerful temptation to some C -programmers, who see it as a way to efficiently encode a great deal of -flexibility into a source file. But the preprocessor is not C, and heavy -use of it results in code which is much harder for others to read and -harder for the compiler to check for correctness. Heavy preprocessor use -is almost always a sign of code which needs some cleanup work. - -Conditional compilation with #ifdef is, indeed, a powerful feature, and it -is used within the kernel. But there is little desire to see code which is -sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use -should be confined to header files whenever possible. -Conditionally-compiled code can be confined to functions which, if the code -is not to be present, simply become empty. The compiler will then quietly -optimize out the call to the empty function. The result is far cleaner -code which is easier to follow. - -C preprocessor macros present a number of hazards, including possible -multiple evaluation of expressions with side effects and no type safety. -If you are tempted to define a macro, consider creating an inline function -instead. The code which results will be the same, but inline functions are -easier to read, do not evaluate their arguments multiple times, and allow -the compiler to perform type checking on the arguments and return value. - - -* Inline functions - -Inline functions present a hazard of their own, though. Programmers can -become enamored of the perceived efficiency inherent in avoiding a function -call and fill a source file with inline functions. Those functions, -however, can actually reduce performance. Since their code is replicated -at each call site, they end up bloating the size of the compiled kernel. -That, in turn, creates pressure on the processor's memory caches, which can -slow execution dramatically. Inline functions, as a rule, should be quite -small and relatively rare. The cost of a function call, after all, is not -that high; the creation of large numbers of inline functions is a classic -example of premature optimization. - -In general, kernel programmers ignore cache effects at their peril. The -classic time/space tradeoff taught in beginning data structures classes -often does not apply to contemporary hardware. Space *is* time, in that a -larger program will run slower than one which is more compact. - -More recent compilers take an increasingly active role in deciding whether -a given function should actually be inlined or not. So the liberal -placement of "inline" keywords may not just be excessive; it could also be -irrelevant. - - -* Locking - -In May, 2006, the "Devicescape" networking stack was, with great -fanfare, released under the GPL and made available for inclusion in the -mainline kernel. This donation was welcome news; support for wireless -networking in Linux was considered substandard at best, and the Devicescape -stack offered the promise of fixing that situation. Yet, this code did not -actually make it into the mainline until June, 2007 (2.6.22). What -happened? - -This code showed a number of signs of having been developed behind -corporate doors. But one large problem in particular was that it was not -designed to work on multiprocessor systems. Before this networking stack -(now called mac80211) could be merged, a locking scheme needed to be -retrofitted onto it. - -Once upon a time, Linux kernel code could be developed without thinking -about the concurrency issues presented by multiprocessor systems. Now, -however, this document is being written on a dual-core laptop. Even on -single-processor systems, work being done to improve responsiveness will -raise the level of concurrency within the kernel. The days when kernel -code could be written without thinking about locking are long past. - -Any resource (data structures, hardware registers, etc.) which could be -accessed concurrently by more than one thread must be protected by a lock. -New code should be written with this requirement in mind; retrofitting -locking after the fact is a rather more difficult task. Kernel developers -should take the time to understand the available locking primitives well -enough to pick the right tool for the job. Code which shows a lack of -attention to concurrency will have a difficult path into the mainline. - - -* Regressions - -One final hazard worth mentioning is this: it can be tempting to make a -change (which may bring big improvements) which causes something to break -for existing users. This kind of change is called a "regression," and -regressions have become most unwelcome in the mainline kernel. With few -exceptions, changes which cause regressions will be backed out if the -regression cannot be fixed in a timely manner. Far better to avoid the -regression in the first place. - -It is often argued that a regression can be justified if it causes things -to work for more people than it creates problems for. Why not make a -change if it brings new functionality to ten systems for each one it -breaks? The best answer to this question was expressed by Linus in July, -2007: - - So we don't fix bugs by introducing new problems. That way lies - madness, and nobody ever knows if you actually make any real - progress at all. Is it two steps forwards, one step back, or one - step forward and two steps back? - -(http://lwn.net/Articles/243460/). - -An especially unwelcome type of regression is any sort of change to the -user-space ABI. Once an interface has been exported to user space, it must -be supported indefinitely. This fact makes the creation of user-space -interfaces particularly challenging: since they cannot be changed in -incompatible ways, they must be done right the first time. For this -reason, a great deal of thought, clear documentation, and wide review for -user-space interfaces is always required. - - - -4.2: CODE CHECKING TOOLS - -For now, at least, the writing of error-free code remains an ideal that few -of us can reach. What we can hope to do, though, is to catch and fix as -many of those errors as possible before our code goes into the mainline -kernel. To that end, the kernel developers have put together an impressive -array of tools which can catch a wide variety of obscure problems in an -automated way. Any problem caught by the computer is a problem which will -not afflict a user later on, so it stands to reason that the automated -tools should be used whenever possible. - -The first step is simply to heed the warnings produced by the compiler. -Contemporary versions of gcc can detect (and warn about) a large number of -potential errors. Quite often, these warnings point to real problems. -Code submitted for review should, as a rule, not produce any compiler -warnings. When silencing warnings, take care to understand the real cause -and try to avoid "fixes" which make the warning go away without addressing -its cause. - -Note that not all compiler warnings are enabled by default. Build the -kernel with "make EXTRA_CFLAGS=-W" to get the full set. - -The kernel provides several configuration options which turn on debugging -features; most of these are found in the "kernel hacking" submenu. Several -of these options should be turned on for any kernel used for development or -testing purposes. In particular, you should turn on: - - - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an - extra set of warnings for problems like the use of deprecated interfaces - or ignoring an important return value from a function. The output - generated by these warnings can be verbose, but one need not worry about - warnings from other parts of the kernel. - - - DEBUG_OBJECTS will add code to track the lifetime of various objects - created by the kernel and warn when things are done out of order. If - you are adding a subsystem which creates (and exports) complex objects - of its own, consider adding support for the object debugging - infrastructure. - - - DEBUG_SLAB can find a variety of memory allocation and use errors; it - should be used on most development kernels. - - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a - number of common locking errors. - -There are quite a few other debugging options, some of which will be -discussed below. Some of them have a significant performance impact and -should not be used all of the time. But some time spent learning the -available options will likely be paid back many times over in short order. - -One of the heavier debugging tools is the locking checker, or "lockdep." -This tool will track the acquisition and release of every lock (spinlock or -mutex) in the system, the order in which locks are acquired relative to -each other, the current interrupt environment, and more. It can then -ensure that locks are always acquired in the same order, that the same -interrupt assumptions apply in all situations, and so on. In other words, -lockdep can find a number of scenarios in which the system could, on rare -occasion, deadlock. This kind of problem can be painful (for both -developers and users) in a deployed system; lockdep allows them to be found -in an automated manner ahead of time. Code with any sort of non-trivial -locking should be run with lockdep enabled before being submitted for -inclusion. - -As a diligent kernel programmer, you will, beyond doubt, check the return -status of any operation (such as a memory allocation) which can fail. The -fact of the matter, though, is that the resulting failure recovery paths -are, probably, completely untested. Untested code tends to be broken code; -you could be much more confident of your code if all those error-handling -paths had been exercised a few times. - -The kernel provides a fault injection framework which can do exactly that, -especially where memory allocations are involved. With fault injection -enabled, a configurable percentage of memory allocations will be made to -fail; these failures can be restricted to a specific range of code. -Running with fault injection enabled allows the programmer to see how the -code responds when things go badly. See -Documentation/fault-injection/fault-injection.txt for more information on -how to use this facility. - -Other kinds of errors can be found with the "sparse" static analysis tool. -With sparse, the programmer can be warned about confusion between -user-space and kernel-space addresses, mixture of big-endian and -small-endian quantities, the passing of integer values where a set of bit -flags is expected, and so on. Sparse must be installed separately (it can -be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your -distributor does not package it); it can then be run on the code by adding -"C=1" to your make command. - -The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide -variety of potential coding problems; it can also propose fixes for those -problems. Quite a few "semantic patches" for the kernel have been packaged -under the scripts/coccinelle directory; running "make coccicheck" will run -through those semantic patches and report on any problems found. See -Documentation/coccinelle.txt for more information. - -Other kinds of portability errors are best found by compiling your code for -other architectures. If you do not happen to have an S/390 system or a -Blackfin development board handy, you can still perform the compilation -step. A large set of cross compilers for x86 systems can be found at - - http://www.kernel.org/pub/tools/crosstool/ - -Some time spent installing and using these compilers will help avoid -embarrassment later. - - -4.3: DOCUMENTATION - -Documentation has often been more the exception than the rule with kernel -development. Even so, adequate documentation will help to ease the merging -of new code into the kernel, make life easier for other developers, and -will be helpful for your users. In many cases, the addition of -documentation has become essentially mandatory. - -The first piece of documentation for any patch is its associated -changelog. Log entries should describe the problem being solved, the form -of the solution, the people who worked on the patch, any relevant -effects on performance, and anything else that might be needed to -understand the patch. Be sure that the changelog says *why* the patch is -worth applying; a surprising number of developers fail to provide that -information. - -Any code which adds a new user-space interface - including new sysfs or -/proc files - should include documentation of that interface which enables -user-space developers to know what they are working with. See -Documentation/ABI/README for a description of how this documentation should -be formatted and what information needs to be provided. - -The file Documentation/kernel-parameters.txt describes all of the kernel's -boot-time parameters. Any patch which adds new parameters should add the -appropriate entries to this file. - -Any new configuration options must be accompanied by help text which -clearly explains the options and when the user might want to select them. - -Internal API information for many subsystems is documented by way of -specially-formatted comments; these comments can be extracted and formatted -in a number of ways by the "kernel-doc" script. If you are working within -a subsystem which has kerneldoc comments, you should maintain them and add -them, as appropriate, for externally-available functions. Even in areas -which have not been so documented, there is no harm in adding kerneldoc -comments for the future; indeed, this can be a useful activity for -beginning kernel developers. The format of these comments, along with some -information on how to create kerneldoc templates can be found in the file -Documentation/kernel-documentation.rst. - -Anybody who reads through a significant amount of existing kernel code will -note that, often, comments are most notable by their absence. Once again, -the expectations for new code are higher than they were in the past; -merging uncommented code will be harder. That said, there is little desire -for verbosely-commented code. The code should, itself, be readable, with -comments explaining the more subtle aspects. - -Certain things should always be commented. Uses of memory barriers should -be accompanied by a line explaining why the barrier is necessary. The -locking rules for data structures generally need to be explained somewhere. -Major data structures need comprehensive documentation in general. -Non-obvious dependencies between separate bits of code should be pointed -out. Anything which might tempt a code janitor to make an incorrect -"cleanup" needs a comment saying why it is done the way it is. And so on. - - -4.4: INTERNAL API CHANGES - -The binary interface provided by the kernel to user space cannot be broken -except under the most severe circumstances. The kernel's internal -programming interfaces, instead, are highly fluid and can be changed when -the need arises. If you find yourself having to work around a kernel API, -or simply not using a specific functionality because it does not meet your -needs, that may be a sign that the API needs to change. As a kernel -developer, you are empowered to make such changes. - -There are, of course, some catches. API changes can be made, but they need -to be well justified. So any patch making an internal API change should be -accompanied by a description of what the change is and why it is -necessary. This kind of change should also be broken out into a separate -patch, rather than buried within a larger patch. - -The other catch is that a developer who changes an internal API is -generally charged with the task of fixing any code within the kernel tree -which is broken by the change. For a widely-used function, this duty can -lead to literally hundreds or thousands of changes - many of which are -likely to conflict with work being done by other developers. Needless to -say, this can be a large job, so it is best to be sure that the -justification is solid. Note that the Coccinelle tool can help with -wide-ranging API changes. - -When making an incompatible API change, one should, whenever possible, -ensure that code which has not been updated is caught by the compiler. -This will help you to be sure that you have found all in-tree uses of that -interface. It will also alert developers of out-of-tree code that there is -a change that they need to respond to. Supporting out-of-tree code is not -something that kernel developers need to be worried about, but we also do -not have to make life harder for out-of-tree developers than it needs to -be. diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/development-process/4.Coding.rst new file mode 100644 index 000000000000..9d5cef996f7f --- /dev/null +++ b/Documentation/development-process/4.Coding.rst @@ -0,0 +1,413 @@ +.. _development_coding: + +Getting the code right +====================== + +While there is much to be said for a solid and community-oriented design +process, the proof of any kernel development project is in the resulting +code. It is the code which will be examined by other developers and merged +(or not) into the mainline tree. So it is the quality of this code which +will determine the ultimate success of the project. + +This section will examine the coding process. We'll start with a look at a +number of ways in which kernel developers can go wrong. Then the focus +will shift toward doing things right and the tools which can help in that +quest. + + +Pitfalls +--------- + +Coding style +************ + +The kernel has long had a standard coding style, described in +Documentation/CodingStyle. For much of that time, the policies described +in that file were taken as being, at most, advisory. As a result, there is +a substantial amount of code in the kernel which does not meet the coding +style guidelines. The presence of that code leads to two independent +hazards for kernel developers. + +The first of these is to believe that the kernel coding standards do not +matter and are not enforced. The truth of the matter is that adding new +code to the kernel is very difficult if that code is not coded according to +the standard; many developers will request that the code be reformatted +before they will even review it. A code base as large as the kernel +requires some uniformity of code to make it possible for developers to +quickly understand any part of it. So there is no longer room for +strangely-formatted code. + +Occasionally, the kernel's coding style will run into conflict with an +employer's mandated style. In such cases, the kernel's style will have to +win before the code can be merged. Putting code into the kernel means +giving up a degree of control in a number of ways - including control over +how the code is formatted. + +The other trap is to assume that code which is already in the kernel is +urgently in need of coding style fixes. Developers may start to generate +reformatting patches as a way of gaining familiarity with the process, or +as a way of getting their name into the kernel changelogs - or both. But +pure coding style fixes are seen as noise by the development community; +they tend to get a chilly reception. So this type of patch is best +avoided. It is natural to fix the style of a piece of code while working +on it for other reasons, but coding style changes should not be made for +their own sake. + +The coding style document also should not be read as an absolute law which +can never be transgressed. If there is a good reason to go against the +style (a line which becomes far less readable if split to fit within the +80-column limit, for example), just do it. + + +Abstraction layers +****************** + +Computer Science professors teach students to make extensive use of +abstraction layers in the name of flexibility and information hiding. +Certainly the kernel makes extensive use of abstraction; no project +involving several million lines of code could do otherwise and survive. +But experience has shown that excessive or premature abstraction can be +just as harmful as premature optimization. Abstraction should be used to +the level required and no further. + +At a simple level, consider a function which has an argument which is +always passed as zero by all callers. One could retain that argument just +in case somebody eventually needs to use the extra flexibility that it +provides. By that time, though, chances are good that the code which +implements this extra argument has been broken in some subtle way which was +never noticed - because it has never been used. Or, when the need for +extra flexibility arises, it does not do so in a way which matches the +programmer's early expectation. Kernel developers will routinely submit +patches to remove unused arguments; they should, in general, not be added +in the first place. + +Abstraction layers which hide access to hardware - often to allow the bulk +of a driver to be used with multiple operating systems - are especially +frowned upon. Such layers obscure the code and may impose a performance +penalty; they do not belong in the Linux kernel. + +On the other hand, if you find yourself copying significant amounts of code +from another kernel subsystem, it is time to ask whether it would, in fact, +make sense to pull out some of that code into a separate library or to +implement that functionality at a higher level. There is no value in +replicating the same code throughout the kernel. + + +#ifdef and preprocessor use in general +************************************** + +The C preprocessor seems to present a powerful temptation to some C +programmers, who see it as a way to efficiently encode a great deal of +flexibility into a source file. But the preprocessor is not C, and heavy +use of it results in code which is much harder for others to read and +harder for the compiler to check for correctness. Heavy preprocessor use +is almost always a sign of code which needs some cleanup work. + +Conditional compilation with #ifdef is, indeed, a powerful feature, and it +is used within the kernel. But there is little desire to see code which is +sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use +should be confined to header files whenever possible. +Conditionally-compiled code can be confined to functions which, if the code +is not to be present, simply become empty. The compiler will then quietly +optimize out the call to the empty function. The result is far cleaner +code which is easier to follow. + +C preprocessor macros present a number of hazards, including possible +multiple evaluation of expressions with side effects and no type safety. +If you are tempted to define a macro, consider creating an inline function +instead. The code which results will be the same, but inline functions are +easier to read, do not evaluate their arguments multiple times, and allow +the compiler to perform type checking on the arguments and return value. + + +Inline functions +**************** + +Inline functions present a hazard of their own, though. Programmers can +become enamored of the perceived efficiency inherent in avoiding a function +call and fill a source file with inline functions. Those functions, +however, can actually reduce performance. Since their code is replicated +at each call site, they end up bloating the size of the compiled kernel. +That, in turn, creates pressure on the processor's memory caches, which can +slow execution dramatically. Inline functions, as a rule, should be quite +small and relatively rare. The cost of a function call, after all, is not +that high; the creation of large numbers of inline functions is a classic +example of premature optimization. + +In general, kernel programmers ignore cache effects at their peril. The +classic time/space tradeoff taught in beginning data structures classes +often does not apply to contemporary hardware. Space *is* time, in that a +larger program will run slower than one which is more compact. + +More recent compilers take an increasingly active role in deciding whether +a given function should actually be inlined or not. So the liberal +placement of "inline" keywords may not just be excessive; it could also be +irrelevant. + + +Locking +******* + +In May, 2006, the "Devicescape" networking stack was, with great +fanfare, released under the GPL and made available for inclusion in the +mainline kernel. This donation was welcome news; support for wireless +networking in Linux was considered substandard at best, and the Devicescape +stack offered the promise of fixing that situation. Yet, this code did not +actually make it into the mainline until June, 2007 (2.6.22). What +happened? + +This code showed a number of signs of having been developed behind +corporate doors. But one large problem in particular was that it was not +designed to work on multiprocessor systems. Before this networking stack +(now called mac80211) could be merged, a locking scheme needed to be +retrofitted onto it. + +Once upon a time, Linux kernel code could be developed without thinking +about the concurrency issues presented by multiprocessor systems. Now, +however, this document is being written on a dual-core laptop. Even on +single-processor systems, work being done to improve responsiveness will +raise the level of concurrency within the kernel. The days when kernel +code could be written without thinking about locking are long past. + +Any resource (data structures, hardware registers, etc.) which could be +accessed concurrently by more than one thread must be protected by a lock. +New code should be written with this requirement in mind; retrofitting +locking after the fact is a rather more difficult task. Kernel developers +should take the time to understand the available locking primitives well +enough to pick the right tool for the job. Code which shows a lack of +attention to concurrency will have a difficult path into the mainline. + + +Regressions +*********** + +One final hazard worth mentioning is this: it can be tempting to make a +change (which may bring big improvements) which causes something to break +for existing users. This kind of change is called a "regression," and +regressions have become most unwelcome in the mainline kernel. With few +exceptions, changes which cause regressions will be backed out if the +regression cannot be fixed in a timely manner. Far better to avoid the +regression in the first place. + +It is often argued that a regression can be justified if it causes things +to work for more people than it creates problems for. Why not make a +change if it brings new functionality to ten systems for each one it +breaks? The best answer to this question was expressed by Linus in July, +2007: + +:: + + So we don't fix bugs by introducing new problems. That way lies + madness, and nobody ever knows if you actually make any real + progress at all. Is it two steps forwards, one step back, or one + step forward and two steps back? + +(http://lwn.net/Articles/243460/). + +An especially unwelcome type of regression is any sort of change to the +user-space ABI. Once an interface has been exported to user space, it must +be supported indefinitely. This fact makes the creation of user-space +interfaces particularly challenging: since they cannot be changed in +incompatible ways, they must be done right the first time. For this +reason, a great deal of thought, clear documentation, and wide review for +user-space interfaces is always required. + + +Code checking tools +------------------- + +For now, at least, the writing of error-free code remains an ideal that few +of us can reach. What we can hope to do, though, is to catch and fix as +many of those errors as possible before our code goes into the mainline +kernel. To that end, the kernel developers have put together an impressive +array of tools which can catch a wide variety of obscure problems in an +automated way. Any problem caught by the computer is a problem which will +not afflict a user later on, so it stands to reason that the automated +tools should be used whenever possible. + +The first step is simply to heed the warnings produced by the compiler. +Contemporary versions of gcc can detect (and warn about) a large number of +potential errors. Quite often, these warnings point to real problems. +Code submitted for review should, as a rule, not produce any compiler +warnings. When silencing warnings, take care to understand the real cause +and try to avoid "fixes" which make the warning go away without addressing +its cause. + +Note that not all compiler warnings are enabled by default. Build the +kernel with "make EXTRA_CFLAGS=-W" to get the full set. + +The kernel provides several configuration options which turn on debugging +features; most of these are found in the "kernel hacking" submenu. Several +of these options should be turned on for any kernel used for development or +testing purposes. In particular, you should turn on: + + - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an + extra set of warnings for problems like the use of deprecated interfaces + or ignoring an important return value from a function. The output + generated by these warnings can be verbose, but one need not worry about + warnings from other parts of the kernel. + + - DEBUG_OBJECTS will add code to track the lifetime of various objects + created by the kernel and warn when things are done out of order. If + you are adding a subsystem which creates (and exports) complex objects + of its own, consider adding support for the object debugging + infrastructure. + + - DEBUG_SLAB can find a variety of memory allocation and use errors; it + should be used on most development kernels. + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a + number of common locking errors. + +There are quite a few other debugging options, some of which will be +discussed below. Some of them have a significant performance impact and +should not be used all of the time. But some time spent learning the +available options will likely be paid back many times over in short order. + +One of the heavier debugging tools is the locking checker, or "lockdep." +This tool will track the acquisition and release of every lock (spinlock or +mutex) in the system, the order in which locks are acquired relative to +each other, the current interrupt environment, and more. It can then +ensure that locks are always acquired in the same order, that the same +interrupt assumptions apply in all situations, and so on. In other words, +lockdep can find a number of scenarios in which the system could, on rare +occasion, deadlock. This kind of problem can be painful (for both +developers and users) in a deployed system; lockdep allows them to be found +in an automated manner ahead of time. Code with any sort of non-trivial +locking should be run with lockdep enabled before being submitted for +inclusion. + +As a diligent kernel programmer, you will, beyond doubt, check the return +status of any operation (such as a memory allocation) which can fail. The +fact of the matter, though, is that the resulting failure recovery paths +are, probably, completely untested. Untested code tends to be broken code; +you could be much more confident of your code if all those error-handling +paths had been exercised a few times. + +The kernel provides a fault injection framework which can do exactly that, +especially where memory allocations are involved. With fault injection +enabled, a configurable percentage of memory allocations will be made to +fail; these failures can be restricted to a specific range of code. +Running with fault injection enabled allows the programmer to see how the +code responds when things go badly. See +Documentation/fault-injection/fault-injection.txt for more information on +how to use this facility. + +Other kinds of errors can be found with the "sparse" static analysis tool. +With sparse, the programmer can be warned about confusion between +user-space and kernel-space addresses, mixture of big-endian and +small-endian quantities, the passing of integer values where a set of bit +flags is expected, and so on. Sparse must be installed separately (it can +be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your +distributor does not package it); it can then be run on the code by adding +"C=1" to your make command. + +The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide +variety of potential coding problems; it can also propose fixes for those +problems. Quite a few "semantic patches" for the kernel have been packaged +under the scripts/coccinelle directory; running "make coccicheck" will run +through those semantic patches and report on any problems found. See +Documentation/coccinelle.txt for more information. + +Other kinds of portability errors are best found by compiling your code for +other architectures. If you do not happen to have an S/390 system or a +Blackfin development board handy, you can still perform the compilation +step. A large set of cross compilers for x86 systems can be found at + + http://www.kernel.org/pub/tools/crosstool/ + +Some time spent installing and using these compilers will help avoid +embarrassment later. + + +Documentation +------------- + +Documentation has often been more the exception than the rule with kernel +development. Even so, adequate documentation will help to ease the merging +of new code into the kernel, make life easier for other developers, and +will be helpful for your users. In many cases, the addition of +documentation has become essentially mandatory. + +The first piece of documentation for any patch is its associated +changelog. Log entries should describe the problem being solved, the form +of the solution, the people who worked on the patch, any relevant +effects on performance, and anything else that might be needed to +understand the patch. Be sure that the changelog says *why* the patch is +worth applying; a surprising number of developers fail to provide that +information. + +Any code which adds a new user-space interface - including new sysfs or +/proc files - should include documentation of that interface which enables +user-space developers to know what they are working with. See +Documentation/ABI/README for a description of how this documentation should +be formatted and what information needs to be provided. + +The file Documentation/kernel-parameters.txt describes all of the kernel's +boot-time parameters. Any patch which adds new parameters should add the +appropriate entries to this file. + +Any new configuration options must be accompanied by help text which +clearly explains the options and when the user might want to select them. + +Internal API information for many subsystems is documented by way of +specially-formatted comments; these comments can be extracted and formatted +in a number of ways by the "kernel-doc" script. If you are working within +a subsystem which has kerneldoc comments, you should maintain them and add +them, as appropriate, for externally-available functions. Even in areas +which have not been so documented, there is no harm in adding kerneldoc +comments for the future; indeed, this can be a useful activity for +beginning kernel developers. The format of these comments, along with some +information on how to create kerneldoc templates can be found in the file +Documentation/kernel-documentation.rst. + +Anybody who reads through a significant amount of existing kernel code will +note that, often, comments are most notable by their absence. Once again, +the expectations for new code are higher than they were in the past; +merging uncommented code will be harder. That said, there is little desire +for verbosely-commented code. The code should, itself, be readable, with +comments explaining the more subtle aspects. + +Certain things should always be commented. Uses of memory barriers should +be accompanied by a line explaining why the barrier is necessary. The +locking rules for data structures generally need to be explained somewhere. +Major data structures need comprehensive documentation in general. +Non-obvious dependencies between separate bits of code should be pointed +out. Anything which might tempt a code janitor to make an incorrect +"cleanup" needs a comment saying why it is done the way it is. And so on. + + +Internal API changes +-------------------- + +The binary interface provided by the kernel to user space cannot be broken +except under the most severe circumstances. The kernel's internal +programming interfaces, instead, are highly fluid and can be changed when +the need arises. If you find yourself having to work around a kernel API, +or simply not using a specific functionality because it does not meet your +needs, that may be a sign that the API needs to change. As a kernel +developer, you are empowered to make such changes. + +There are, of course, some catches. API changes can be made, but they need +to be well justified. So any patch making an internal API change should be +accompanied by a description of what the change is and why it is +necessary. This kind of change should also be broken out into a separate +patch, rather than buried within a larger patch. + +The other catch is that a developer who changes an internal API is +generally charged with the task of fixing any code within the kernel tree +which is broken by the change. For a widely-used function, this duty can +lead to literally hundreds or thousands of changes - many of which are +likely to conflict with work being done by other developers. Needless to +say, this can be a large job, so it is best to be sure that the +justification is solid. Note that the Coccinelle tool can help with +wide-ranging API changes. + +When making an incompatible API change, one should, whenever possible, +ensure that code which has not been updated is caught by the compiler. +This will help you to be sure that you have found all in-tree uses of that +interface. It will also alert developers of out-of-tree code that there is +a change that they need to respond to. Supporting out-of-tree code is not +something that kernel developers need to be worried about, but we also do +not have to make life harder for out-of-tree developers than it needs to +be. diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting deleted file mode 100644 index 8a48c9b62864..000000000000 --- a/Documentation/development-process/5.Posting +++ /dev/null @@ -1,307 +0,0 @@ -5: POSTING PATCHES - -Sooner or later, the time comes when your work is ready to be presented to -the community for review and, eventually, inclusion into the mainline -kernel. Unsurprisingly, the kernel development community has evolved a set -of conventions and procedures which are used in the posting of patches; -following them will make life much easier for everybody involved. This -document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files SubmittingPatches, -SubmittingDrivers, and SubmitChecklist in the kernel documentation -directory. - - -5.1: WHEN TO POST - -There is a constant temptation to avoid posting patches before they are -completely "ready." For simple patches, that is not a problem. If the -work being done is complex, though, there is a lot to be gained by getting -feedback from the community before the work is complete. So you should -consider posting in-progress work, or even making a git tree available so -that interested developers can catch up with your work at any time. - -When posting code which is not yet considered ready for inclusion, it is a -good idea to say so in the posting itself. Also mention any major work -which remains to be done and any known problems. Fewer people will look at -patches which are known to be half-baked, but those who do will come in -with the idea that they can help you drive the work in the right direction. - - -5.2: BEFORE CREATING PATCHES - -There are a number of things which should be done before you consider -sending patches to the development community. These include: - - - Test the code to the extent that you can. Make use of the kernel's - debugging tools, ensure that the kernel will build with all reasonable - combinations of configuration options, use cross-compilers to build for - different architectures, etc. - - - Make sure your code is compliant with the kernel coding style - guidelines. - - - Does your change have performance implications? If so, you should run - benchmarks showing what the impact (or benefit) of your change is; a - summary of the results should be included with the patch. - - - Be sure that you have the right to post the code. If this work was done - for an employer, the employer likely has a right to the work and must be - agreeable with its release under the GPL. - -As a general rule, putting in some extra thought before posting code almost -always pays back the effort in short order. - - -5.3: PATCH PREPARATION - -The preparation of patches for posting can be a surprising amount of work, -but, once again, attempting to save time here is not generally advisable -even in the short term. - -Patches must be prepared against a specific version of the kernel. As a -general rule, a patch should be based on the current mainline as found in -Linus's git tree. When basing on mainline, start with a well-known release -point - a stable or -rc release - rather than branching off the mainline at -an arbitrary spot. - -It may become necessary to make versions against -mm, linux-next, or a -subsystem tree, though, to facilitate wider testing and review. Depending -on the area of your patch and what is going on elsewhere, basing a patch -against these other trees can require a significant amount of work -resolving conflicts and dealing with API changes. - -Only the most simple changes should be formatted as a single patch; -everything else should be made as a logical series of changes. Splitting -up patches is a bit of an art; some developers spend a long time figuring -out how to do it in the way that the community expects. There are a few -rules of thumb, however, which can help considerably: - - - The patch series you post will almost certainly not be the series of - changes found in your working revision control system. Instead, the - changes you have made need to be considered in their final form, then - split apart in ways which make sense. The developers are interested in - discrete, self-contained changes, not the path you took to get to those - changes. - - - Each logically independent change should be formatted as a separate - patch. These changes can be small ("add a field to this structure") or - large (adding a significant new driver, for example), but they should be - conceptually small and amenable to a one-line description. Each patch - should make a specific change which can be reviewed on its own and - verified to do what it says it does. - - - As a way of restating the guideline above: do not mix different types of - changes in the same patch. If a single patch fixes a critical security - bug, rearranges a few structures, and reformats the code, there is a - good chance that it will be passed over and the important fix will be - lost. - - - Each patch should yield a kernel which builds and runs properly; if your - patch series is interrupted in the middle, the result should still be a - working kernel. Partial application of a patch series is a common - scenario when the "git bisect" tool is used to find regressions; if the - result is a broken kernel, you will make life harder for developers and - users who are engaging in the noble work of tracking down problems. - - - Do not overdo it, though. One developer once posted a set of edits - to a single file as 500 separate patches - an act which did not make him - the most popular person on the kernel mailing list. A single patch can - be reasonably large as long as it still contains a single *logical* - change. - - - It can be tempting to add a whole new infrastructure with a series of - patches, but to leave that infrastructure unused until the final patch - in the series enables the whole thing. This temptation should be - avoided if possible; if that series adds regressions, bisection will - finger the last patch as the one which caused the problem, even though - the real bug is elsewhere. Whenever possible, a patch which adds new - code should make that code active immediately. - -Working to create the perfect patch series can be a frustrating process -which takes quite a bit of time and thought after the "real work" has been -done. When done properly, though, it is time well spent. - - -5.4: PATCH FORMATTING AND CHANGELOGS - -So now you have a perfect series of patches for posting, but the work is -not done quite yet. Each patch needs to be formatted into a message which -quickly and clearly communicates its purpose to the rest of the world. To -that end, each patch will be composed of the following: - - - An optional "From" line naming the author of the patch. This line is - only necessary if you are passing on somebody else's patch via email, - but it never hurts to add it when in doubt. - - - A one-line description of what the patch does. This message should be - enough for a reader who sees it with no other context to figure out the - scope of the patch; it is the line that will show up in the "short form" - changelogs. This message is usually formatted with the relevant - subsystem name first, followed by the purpose of the patch. For - example: - - gpio: fix build on CONFIG_GPIO_SYSFS=n - - - A blank line followed by a detailed description of the contents of the - patch. This description can be as long as is required; it should say - what the patch does and why it should be applied to the kernel. - - - One or more tag lines, with, at a minimum, one Signed-off-by: line from - the author of the patch. Tags will be described in more detail below. - -The items above, together, form the changelog for the patch. Writing good -changelogs is a crucial but often-neglected art; it's worth spending -another moment discussing this issue. When writing a changelog, you should -bear in mind that a number of different people will be reading your words. -These include subsystem maintainers and reviewers who need to decide -whether the patch should be included, distributors and other maintainers -trying to decide whether a patch should be backported to other kernels, bug -hunters wondering whether the patch is responsible for a problem they are -chasing, users who want to know how the kernel has changed, and more. A -good changelog conveys the needed information to all of these people in the -most direct and concise way possible. - -To that end, the summary line should describe the effects of and motivation -for the change as well as possible given the one-line constraint. The -detailed description can then amplify on those topics and provide any -needed additional information. If the patch fixes a bug, cite the commit -which introduced the bug if possible (and please provide both the commit ID -and the title when citing commits). If a problem is associated with -specific log or compiler output, include that output to help others -searching for a solution to the same problem. If the change is meant to -support other changes coming in later patch, say so. If internal APIs are -changed, detail those changes and how other developers should respond. In -general, the more you can put yourself into the shoes of everybody who will -be reading your changelog, the better that changelog (and the kernel as a -whole) will be. - -Needless to say, the changelog should be the text used when committing the -change to a revision control system. It will be followed by: - - - The patch itself, in the unified ("-u") patch format. Using the "-p" - option to diff will associate function names with changes, making the - resulting patch easier for others to read. - -You should avoid including changes to irrelevant files (those generated by -the build process, for example, or editor backup files) in the patch. The -file "dontdiff" in the Documentation directory can help in this regard; -pass it to diff with the "-X" option. - -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in the SubmittingPatches document; what follows here is a brief -summary. Each of these lines has the format: - - tag: Full Name optional-other-stuff - -The tags in common use are: - - - Signed-off-by: this is a developer's certification that he or she has - the right to submit the patch for inclusion into the kernel. It is an - agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/SubmittingPatches. Code without a - proper signoff cannot be merged into the mainline. - - - Acked-by: indicates an agreement by another developer (often a - maintainer of the relevant code) that the patch is appropriate for - inclusion into the kernel. - - - Tested-by: states that the named person has tested the patch and found - it to work. - - - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/SubmittingPatches for more - detail. - - - Reported-by: names a user who reported a problem which is fixed by this - patch; this tag is used to give credit to the (often underappreciated) - people who test our code and let us know when things do not work - correctly. - - - Cc: the named person received a copy of the patch and had the - opportunity to comment on it. - -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. - - -5.5: SENDING THE PATCH - -Before you mail your patches, there are a couple of other things you should -take care of: - - - Are you sure that your mailer will not corrupt the patches? Patches - which have had gratuitous white-space changes or line wrapping performed - by the mail client will not apply at the other end, and often will not - be examined in any detail. If there is any doubt at all, mail the patch - to yourself and convince yourself that it shows up intact. - - Documentation/email-clients.txt has some helpful hints on making - specific mail clients work for sending patches. - - - Are you sure your patch is free of silly mistakes? You should always - run patches through scripts/checkpatch.pl and address the complaints it - comes up with. Please bear in mind that checkpatch.pl, while being the - embodiment of a fair amount of thought about what kernel patches should - look like, is not smarter than you. If fixing a checkpatch.pl complaint - would make the code worse, don't do it. - -Patches should always be sent as plain text. Please do not send them as -attachments; that makes it much harder for reviewers to quote sections of -the patch in their replies. Instead, just put the patch directly into your -message. - -When mailing patches, it is important to send copies to anybody who might -be interested in it. Unlike some other projects, the kernel encourages -people to err on the side of sending too many copies; don't assume that the -relevant people will see your posting on the mailing lists. In particular, -copies should go to: - - - The maintainer(s) of the affected subsystem(s). As described earlier, - the MAINTAINERS file is the first place to look for these people. - - - Other developers who have been working in the same area - especially - those who might be working there now. Using git to see who else has - modified the files you are working on can be helpful. - - - If you are responding to a bug report or a feature request, copy the - original poster as well. - - - Send a copy to the relevant mailing list, or, if nothing else applies, - the linux-kernel list. - - - If you are fixing a bug, think about whether the fix should go into the - next stable update. If so, stable@vger.kernel.org should get a copy of - the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within - the patch itself; that will cause the stable team to get a notification - when your fix goes into the mainline. - -When selecting recipients for a patch, it is good to have an idea of who -you think will eventually accept the patch and get it merged. While it -is possible to send patches directly to Linus Torvalds and have him merge -them, things are not normally done that way. Linus is busy, and there are -subsystem maintainers who watch over specific parts of the kernel. Usually -you will be wanting that maintainer to merge your patches. If there is no -obvious maintainer, Andrew Morton is often the patch target of last resort. - -Patches need good subject lines. The canonical format for a patch line is -something like: - - [PATCH nn/mm] subsys: one-line description of the patch - -where "nn" is the ordinal number of the patch, "mm" is the total number of -patches in the series, and "subsys" is the name of the affected subsystem. -Clearly, nn/mm can be omitted for a single, standalone patch. - -If you have a significant series of patches, it is customary to send an -introductory description as part zero. This convention is not universally -followed though; if you use it, remember that information in the -introduction does not make it into the kernel changelogs. So please ensure -that the patches, themselves, have complete changelog information. - -In general, the second and following parts of a multi-part patch should be -sent as a reply to the first part so that they all thread together at the -receiving end. Tools like git and quilt have commands to mail out a set of -patches with the proper threading. If you have a long series, though, and -are using git, please stay away from the --chain-reply-to option to avoid -creating exceptionally deep nesting. diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst new file mode 100644 index 000000000000..b511ddf7e82a --- /dev/null +++ b/Documentation/development-process/5.Posting.rst @@ -0,0 +1,321 @@ +.. _development_posting: + +Posting patches +=============== + +Sooner or later, the time comes when your work is ready to be presented to +the community for review and, eventually, inclusion into the mainline +kernel. Unsurprisingly, the kernel development community has evolved a set +of conventions and procedures which are used in the posting of patches; +following them will make life much easier for everybody involved. This +document will attempt to cover these expectations in reasonable detail; +more information can also be found in the files SubmittingPatches, +SubmittingDrivers, and SubmitChecklist in the kernel documentation +directory. + + +When to post +------------ + +There is a constant temptation to avoid posting patches before they are +completely "ready." For simple patches, that is not a problem. If the +work being done is complex, though, there is a lot to be gained by getting +feedback from the community before the work is complete. So you should +consider posting in-progress work, or even making a git tree available so +that interested developers can catch up with your work at any time. + +When posting code which is not yet considered ready for inclusion, it is a +good idea to say so in the posting itself. Also mention any major work +which remains to be done and any known problems. Fewer people will look at +patches which are known to be half-baked, but those who do will come in +with the idea that they can help you drive the work in the right direction. + + +Before creating patches +----------------------- + +There are a number of things which should be done before you consider +sending patches to the development community. These include: + + - Test the code to the extent that you can. Make use of the kernel's + debugging tools, ensure that the kernel will build with all reasonable + combinations of configuration options, use cross-compilers to build for + different architectures, etc. + + - Make sure your code is compliant with the kernel coding style + guidelines. + + - Does your change have performance implications? If so, you should run + benchmarks showing what the impact (or benefit) of your change is; a + summary of the results should be included with the patch. + + - Be sure that you have the right to post the code. If this work was done + for an employer, the employer likely has a right to the work and must be + agreeable with its release under the GPL. + +As a general rule, putting in some extra thought before posting code almost +always pays back the effort in short order. + + +Patch preparation +----------------- + +The preparation of patches for posting can be a surprising amount of work, +but, once again, attempting to save time here is not generally advisable +even in the short term. + +Patches must be prepared against a specific version of the kernel. As a +general rule, a patch should be based on the current mainline as found in +Linus's git tree. When basing on mainline, start with a well-known release +point - a stable or -rc release - rather than branching off the mainline at +an arbitrary spot. + +It may become necessary to make versions against -mm, linux-next, or a +subsystem tree, though, to facilitate wider testing and review. Depending +on the area of your patch and what is going on elsewhere, basing a patch +against these other trees can require a significant amount of work +resolving conflicts and dealing with API changes. + +Only the most simple changes should be formatted as a single patch; +everything else should be made as a logical series of changes. Splitting +up patches is a bit of an art; some developers spend a long time figuring +out how to do it in the way that the community expects. There are a few +rules of thumb, however, which can help considerably: + + - The patch series you post will almost certainly not be the series of + changes found in your working revision control system. Instead, the + changes you have made need to be considered in their final form, then + split apart in ways which make sense. The developers are interested in + discrete, self-contained changes, not the path you took to get to those + changes. + + - Each logically independent change should be formatted as a separate + patch. These changes can be small ("add a field to this structure") or + large (adding a significant new driver, for example), but they should be + conceptually small and amenable to a one-line description. Each patch + should make a specific change which can be reviewed on its own and + verified to do what it says it does. + + - As a way of restating the guideline above: do not mix different types of + changes in the same patch. If a single patch fixes a critical security + bug, rearranges a few structures, and reformats the code, there is a + good chance that it will be passed over and the important fix will be + lost. + + - Each patch should yield a kernel which builds and runs properly; if your + patch series is interrupted in the middle, the result should still be a + working kernel. Partial application of a patch series is a common + scenario when the "git bisect" tool is used to find regressions; if the + result is a broken kernel, you will make life harder for developers and + users who are engaging in the noble work of tracking down problems. + + - Do not overdo it, though. One developer once posted a set of edits + to a single file as 500 separate patches - an act which did not make him + the most popular person on the kernel mailing list. A single patch can + be reasonably large as long as it still contains a single *logical* + change. + + - It can be tempting to add a whole new infrastructure with a series of + patches, but to leave that infrastructure unused until the final patch + in the series enables the whole thing. This temptation should be + avoided if possible; if that series adds regressions, bisection will + finger the last patch as the one which caused the problem, even though + the real bug is elsewhere. Whenever possible, a patch which adds new + code should make that code active immediately. + +Working to create the perfect patch series can be a frustrating process +which takes quite a bit of time and thought after the "real work" has been +done. When done properly, though, it is time well spent. + + +Patch formatting and changelogs +------------------------------- + +So now you have a perfect series of patches for posting, but the work is +not done quite yet. Each patch needs to be formatted into a message which +quickly and clearly communicates its purpose to the rest of the world. To +that end, each patch will be composed of the following: + + - An optional "From" line naming the author of the patch. This line is + only necessary if you are passing on somebody else's patch via email, + but it never hurts to add it when in doubt. + + - A one-line description of what the patch does. This message should be + enough for a reader who sees it with no other context to figure out the + scope of the patch; it is the line that will show up in the "short form" + changelogs. This message is usually formatted with the relevant + subsystem name first, followed by the purpose of the patch. For + example: + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - A blank line followed by a detailed description of the contents of the + patch. This description can be as long as is required; it should say + what the patch does and why it should be applied to the kernel. + + - One or more tag lines, with, at a minimum, one Signed-off-by: line from + the author of the patch. Tags will be described in more detail below. + +The items above, together, form the changelog for the patch. Writing good +changelogs is a crucial but often-neglected art; it's worth spending +another moment discussing this issue. When writing a changelog, you should +bear in mind that a number of different people will be reading your words. +These include subsystem maintainers and reviewers who need to decide +whether the patch should be included, distributors and other maintainers +trying to decide whether a patch should be backported to other kernels, bug +hunters wondering whether the patch is responsible for a problem they are +chasing, users who want to know how the kernel has changed, and more. A +good changelog conveys the needed information to all of these people in the +most direct and concise way possible. + +To that end, the summary line should describe the effects of and motivation +for the change as well as possible given the one-line constraint. The +detailed description can then amplify on those topics and provide any +needed additional information. If the patch fixes a bug, cite the commit +which introduced the bug if possible (and please provide both the commit ID +and the title when citing commits). If a problem is associated with +specific log or compiler output, include that output to help others +searching for a solution to the same problem. If the change is meant to +support other changes coming in later patch, say so. If internal APIs are +changed, detail those changes and how other developers should respond. In +general, the more you can put yourself into the shoes of everybody who will +be reading your changelog, the better that changelog (and the kernel as a +whole) will be. + +Needless to say, the changelog should be the text used when committing the +change to a revision control system. It will be followed by: + + - The patch itself, in the unified ("-u") patch format. Using the "-p" + option to diff will associate function names with changes, making the + resulting patch easier for others to read. + +You should avoid including changes to irrelevant files (those generated by +the build process, for example, or editor backup files) in the patch. The +file "dontdiff" in the Documentation directory can help in this regard; +pass it to diff with the "-X" option. + +The tags mentioned above are used to describe how various developers have +been associated with the development of this patch. They are described in +detail in the SubmittingPatches document; what follows here is a brief +summary. Each of these lines has the format: + +:: + + tag: Full Name optional-other-stuff + +The tags in common use are: + + - Signed-off-by: this is a developer's certification that he or she has + the right to submit the patch for inclusion into the kernel. It is an + agreement to the Developer's Certificate of Origin, the full text of + which can be found in Documentation/SubmittingPatches. Code without a + proper signoff cannot be merged into the mainline. + + - Acked-by: indicates an agreement by another developer (often a + maintainer of the relevant code) that the patch is appropriate for + inclusion into the kernel. + + - Tested-by: states that the named person has tested the patch and found + it to work. + + - Reviewed-by: the named developer has reviewed the patch for correctness; + see the reviewer's statement in Documentation/SubmittingPatches for more + detail. + + - Reported-by: names a user who reported a problem which is fixed by this + patch; this tag is used to give credit to the (often underappreciated) + people who test our code and let us know when things do not work + correctly. + + - Cc: the named person received a copy of the patch and had the + opportunity to comment on it. + +Be careful in the addition of tags to your patches: only Cc: is appropriate +for addition without the explicit permission of the person named. + + +Sending the patch +----------------- + +Before you mail your patches, there are a couple of other things you should +take care of: + + - Are you sure that your mailer will not corrupt the patches? Patches + which have had gratuitous white-space changes or line wrapping performed + by the mail client will not apply at the other end, and often will not + be examined in any detail. If there is any doubt at all, mail the patch + to yourself and convince yourself that it shows up intact. + + Documentation/email-clients.txt has some helpful hints on making + specific mail clients work for sending patches. + + - Are you sure your patch is free of silly mistakes? You should always + run patches through scripts/checkpatch.pl and address the complaints it + comes up with. Please bear in mind that checkpatch.pl, while being the + embodiment of a fair amount of thought about what kernel patches should + look like, is not smarter than you. If fixing a checkpatch.pl complaint + would make the code worse, don't do it. + +Patches should always be sent as plain text. Please do not send them as +attachments; that makes it much harder for reviewers to quote sections of +the patch in their replies. Instead, just put the patch directly into your +message. + +When mailing patches, it is important to send copies to anybody who might +be interested in it. Unlike some other projects, the kernel encourages +people to err on the side of sending too many copies; don't assume that the +relevant people will see your posting on the mailing lists. In particular, +copies should go to: + + - The maintainer(s) of the affected subsystem(s). As described earlier, + the MAINTAINERS file is the first place to look for these people. + + - Other developers who have been working in the same area - especially + those who might be working there now. Using git to see who else has + modified the files you are working on can be helpful. + + - If you are responding to a bug report or a feature request, copy the + original poster as well. + + - Send a copy to the relevant mailing list, or, if nothing else applies, + the linux-kernel list. + + - If you are fixing a bug, think about whether the fix should go into the + next stable update. If so, stable@vger.kernel.org should get a copy of + the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within + the patch itself; that will cause the stable team to get a notification + when your fix goes into the mainline. + +When selecting recipients for a patch, it is good to have an idea of who +you think will eventually accept the patch and get it merged. While it +is possible to send patches directly to Linus Torvalds and have him merge +them, things are not normally done that way. Linus is busy, and there are +subsystem maintainers who watch over specific parts of the kernel. Usually +you will be wanting that maintainer to merge your patches. If there is no +obvious maintainer, Andrew Morton is often the patch target of last resort. + +Patches need good subject lines. The canonical format for a patch line is +something like: + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +where "nn" is the ordinal number of the patch, "mm" is the total number of +patches in the series, and "subsys" is the name of the affected subsystem. +Clearly, nn/mm can be omitted for a single, standalone patch. + +If you have a significant series of patches, it is customary to send an +introductory description as part zero. This convention is not universally +followed though; if you use it, remember that information in the +introduction does not make it into the kernel changelogs. So please ensure +that the patches, themselves, have complete changelog information. + +In general, the second and following parts of a multi-part patch should be +sent as a reply to the first part so that they all thread together at the +receiving end. Tools like git and quilt have commands to mail out a set of +patches with the proper threading. If you have a long series, though, and +are using git, please stay away from the --chain-reply-to option to avoid +creating exceptionally deep nesting. diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough deleted file mode 100644 index 41d324a9420d..000000000000 --- a/Documentation/development-process/6.Followthrough +++ /dev/null @@ -1,206 +0,0 @@ -6: FOLLOWTHROUGH - -At this point, you have followed the guidelines given so far and, with the -addition of your own engineering skills, have posted a perfect series of -patches. One of the biggest mistakes that even experienced kernel -developers can make is to conclude that their work is now done. In truth, -posting patches indicates a transition into the next stage of the process, -with, possibly, quite a bit of work yet to be done. - -It is a rare patch which is so good at its first posting that there is no -room for improvement. The kernel development process recognizes this fact, -and, as a result, is heavily oriented toward the improvement of posted -code. You, as the author of that code, will be expected to work with the -kernel community to ensure that your code is up to the kernel's quality -standards. A failure to participate in this process is quite likely to -prevent the inclusion of your patches into the mainline. - - -6.1: WORKING WITH REVIEWERS - -A patch of any significance will result in a number of comments from other -developers as they review the code. Working with reviewers can be, for -many developers, the most intimidating part of the kernel development -process. Life can be made much easier, though, if you keep a few things in -mind: - - - If you have explained your patch well, reviewers will understand its - value and why you went to the trouble of writing it. But that value - will not keep them from asking a fundamental question: what will it be - like to maintain a kernel with this code in it five or ten years later? - Many of the changes you may be asked to make - from coding style tweaks - to substantial rewrites - come from the understanding that Linux will - still be around and under development a decade from now. - - - Code review is hard work, and it is a relatively thankless occupation; - people remember who wrote kernel code, but there is little lasting fame - for those who reviewed it. So reviewers can get grumpy, especially when - they see the same mistakes being made over and over again. If you get a - review which seems angry, insulting, or outright offensive, resist the - impulse to respond in kind. Code review is about the code, not about - the people, and code reviewers are not attacking you personally. - - - Similarly, code reviewers are not trying to promote their employers' - agendas at the expense of your own. Kernel developers often expect to - be working on the kernel years from now, but they understand that their - employer could change. They truly are, almost without exception, - working toward the creation of the best kernel they can; they are not - trying to create discomfort for their employers' competitors. - -What all of this comes down to is that, when reviewers send you comments, -you need to pay attention to the technical observations that they are -making. Do not let their form of expression or your own pride keep that -from happening. When you get review comments on a patch, take the time to -understand what the reviewer is trying to say. If possible, fix the things -that the reviewer is asking you to fix. And respond back to the reviewer: -thank them, and describe how you will answer their questions. - -Note that you do not have to agree with every change suggested by -reviewers. If you believe that the reviewer has misunderstood your code, -explain what is really going on. If you have a technical objection to a -suggested change, describe it and justify your solution to the problem. If -your explanations make sense, the reviewer will accept them. Should your -explanation not prove persuasive, though, especially if others start to -agree with the reviewer, take some time to think things over again. It can -be easy to become blinded by your own solution to a problem to the point -that you don't realize that something is fundamentally wrong or, perhaps, -you're not even solving the right problem. - -Andrew Morton has suggested that every review comment which does not result -in a code change should result in an additional code comment instead; that -can help future reviewers avoid the questions which came up the first time -around. - -One fatal mistake is to ignore review comments in the hope that they will -go away. They will not go away. If you repost code without having -responded to the comments you got the time before, you're likely to find -that your patches go nowhere. - -Speaking of reposting code: please bear in mind that reviewers are not -going to remember all the details of the code you posted the last time -around. So it is always a good idea to remind reviewers of previously -raised issues and how you dealt with them; the patch changelog is a good -place for this kind of information. Reviewers should not have to search -through list archives to familiarize themselves with what was said last -time; if you help them get a running start, they will be in a better mood -when they revisit your code. - -What if you've tried to do everything right and things still aren't going -anywhere? Most technical disagreements can be resolved through discussion, -but there are times when somebody simply has to make a decision. If you -honestly believe that this decision is going against you wrongly, you can -always try appealing to a higher power. As of this writing, that higher -power tends to be Andrew Morton. Andrew has a great deal of respect in the -kernel development community; he can often unjam a situation which seems to -be hopelessly blocked. Appealing to Andrew should not be done lightly, -though, and not before all other alternatives have been explored. And bear -in mind, of course, that he may not agree with you either. - - -6.2: WHAT HAPPENS NEXT - -If a patch is considered to be a good thing to add to the kernel, and once -most of the review issues have been resolved, the next step is usually -entry into a subsystem maintainer's tree. How that works varies from one -subsystem to the next; each maintainer has his or her own way of doing -things. In particular, there may be more than one tree - one, perhaps, -dedicated to patches planned for the next merge window, and another for -longer-term work. - -For patches applying to areas for which there is no obvious subsystem tree -(memory management patches, for example), the default tree often ends up -being -mm. Patches which affect multiple subsystems can also end up going -through the -mm tree. - -Inclusion into a subsystem tree can bring a higher level of visibility to a -patch. Now other developers working with that tree will get the patch by -default. Subsystem trees typically feed linux-next as well, making their -contents visible to the development community as a whole. At this point, -there's a good chance that you will get more comments from a new set of -reviewers; these comments need to be answered as in the previous round. - -What may also happen at this point, depending on the nature of your patch, -is that conflicts with work being done by others turn up. In the worst -case, heavy patch conflicts can result in some work being put on the back -burner so that the remaining patches can be worked into shape and merged. -Other times, conflict resolution will involve working with the other -developers and, possibly, moving some patches between trees to ensure that -everything applies cleanly. This work can be a pain, but count your -blessings: before the advent of the linux-next tree, these conflicts often -only turned up during the merge window and had to be addressed in a hurry. -Now they can be resolved at leisure, before the merge window opens. - -Some day, if all goes well, you'll log on and see that your patch has been -merged into the mainline kernel. Congratulations! Once the celebration is -complete (and you have added yourself to the MAINTAINERS file), though, it -is worth remembering an important little fact: the job still is not done. -Merging into the mainline brings its own challenges. - -To begin with, the visibility of your patch has increased yet again. There -may be a new round of comments from developers who had not been aware of -the patch before. It may be tempting to ignore them, since there is no -longer any question of your code being merged. Resist that temptation, -though; you still need to be responsive to developers who have questions or -suggestions. - -More importantly, though: inclusion into the mainline puts your code into -the hands of a much larger group of testers. Even if you have contributed -a driver for hardware which is not yet available, you will be surprised by -how many people will build your code into their kernels. And, of course, -where there are testers, there will be bug reports. - -The worst sort of bug reports are regressions. If your patch causes a -regression, you'll find an uncomfortable number of eyes upon you; -regressions need to be fixed as soon as possible. If you are unwilling or -unable to fix the regression (and nobody else does it for you), your patch -will almost certainly be removed during the stabilization period. Beyond -negating all of the work you have done to get your patch into the mainline, -having a patch pulled as the result of a failure to fix a regression could -well make it harder for you to get work merged in the future. - -After any regressions have been dealt with, there may be other, ordinary -bugs to deal with. The stabilization period is your best opportunity to -fix these bugs and ensure that your code's debut in a mainline kernel -release is as solid as possible. So, please, answer bug reports, and fix -the problems if at all possible. That's what the stabilization period is -for; you can start creating cool new patches once any problems with the old -ones have been taken care of. - -And don't forget that there are other milestones which may also create bug -reports: the next mainline stable release, when prominent distributors pick -up a version of the kernel containing your patch, etc. Continuing to -respond to these reports is a matter of basic pride in your work. If that -is insufficient motivation, though, it's also worth considering that the -development community remembers developers who lose interest in their code -after it's merged. The next time you post a patch, they will be evaluating -it with the assumption that you will not be around to maintain it -afterward. - - -6.3: OTHER THINGS THAT CAN HAPPEN - -One day, you may open your mail client and see that somebody has mailed you -a patch to your code. That is one of the advantages of having your code -out there in the open, after all. If you agree with the patch, you can -either forward it on to the subsystem maintainer (be sure to include a -proper From: line so that the attribution is correct, and add a signoff of -your own), or send an Acked-by: response back and let the original poster -send it upward. - -If you disagree with the patch, send a polite response explaining why. If -possible, tell the author what changes need to be made to make the patch -acceptable to you. There is a certain resistance to merging patches which -are opposed by the author and maintainer of the code, but it only goes so -far. If you are seen as needlessly blocking good work, those patches will -eventually flow around you and get into the mainline anyway. In the Linux -kernel, nobody has absolute veto power over any code. Except maybe Linus. - -On very rare occasion, you may see something completely different: another -developer posts a different solution to your problem. At that point, -chances are that one of the two patches will not be merged, and "mine was -here first" is not considered to be a compelling technical argument. If -somebody else's patch displaces yours and gets into the mainline, there is -really only one way to respond: be pleased that your problem got solved and -get on with your work. Having one's work shoved aside in this manner can -be hurtful and discouraging, but the community will remember your reaction -long after they have forgotten whose patch actually got merged. diff --git a/Documentation/development-process/6.Followthrough.rst b/Documentation/development-process/6.Followthrough.rst new file mode 100644 index 000000000000..a173cd5f93d2 --- /dev/null +++ b/Documentation/development-process/6.Followthrough.rst @@ -0,0 +1,212 @@ +.. _development_followthrough: + +Followthrough +============= + +At this point, you have followed the guidelines given so far and, with the +addition of your own engineering skills, have posted a perfect series of +patches. One of the biggest mistakes that even experienced kernel +developers can make is to conclude that their work is now done. In truth, +posting patches indicates a transition into the next stage of the process, +with, possibly, quite a bit of work yet to be done. + +It is a rare patch which is so good at its first posting that there is no +room for improvement. The kernel development process recognizes this fact, +and, as a result, is heavily oriented toward the improvement of posted +code. You, as the author of that code, will be expected to work with the +kernel community to ensure that your code is up to the kernel's quality +standards. A failure to participate in this process is quite likely to +prevent the inclusion of your patches into the mainline. + + +Working with reviewers +---------------------- + +A patch of any significance will result in a number of comments from other +developers as they review the code. Working with reviewers can be, for +many developers, the most intimidating part of the kernel development +process. Life can be made much easier, though, if you keep a few things in +mind: + + - If you have explained your patch well, reviewers will understand its + value and why you went to the trouble of writing it. But that value + will not keep them from asking a fundamental question: what will it be + like to maintain a kernel with this code in it five or ten years later? + Many of the changes you may be asked to make - from coding style tweaks + to substantial rewrites - come from the understanding that Linux will + still be around and under development a decade from now. + + - Code review is hard work, and it is a relatively thankless occupation; + people remember who wrote kernel code, but there is little lasting fame + for those who reviewed it. So reviewers can get grumpy, especially when + they see the same mistakes being made over and over again. If you get a + review which seems angry, insulting, or outright offensive, resist the + impulse to respond in kind. Code review is about the code, not about + the people, and code reviewers are not attacking you personally. + + - Similarly, code reviewers are not trying to promote their employers' + agendas at the expense of your own. Kernel developers often expect to + be working on the kernel years from now, but they understand that their + employer could change. They truly are, almost without exception, + working toward the creation of the best kernel they can; they are not + trying to create discomfort for their employers' competitors. + +What all of this comes down to is that, when reviewers send you comments, +you need to pay attention to the technical observations that they are +making. Do not let their form of expression or your own pride keep that +from happening. When you get review comments on a patch, take the time to +understand what the reviewer is trying to say. If possible, fix the things +that the reviewer is asking you to fix. And respond back to the reviewer: +thank them, and describe how you will answer their questions. + +Note that you do not have to agree with every change suggested by +reviewers. If you believe that the reviewer has misunderstood your code, +explain what is really going on. If you have a technical objection to a +suggested change, describe it and justify your solution to the problem. If +your explanations make sense, the reviewer will accept them. Should your +explanation not prove persuasive, though, especially if others start to +agree with the reviewer, take some time to think things over again. It can +be easy to become blinded by your own solution to a problem to the point +that you don't realize that something is fundamentally wrong or, perhaps, +you're not even solving the right problem. + +Andrew Morton has suggested that every review comment which does not result +in a code change should result in an additional code comment instead; that +can help future reviewers avoid the questions which came up the first time +around. + +One fatal mistake is to ignore review comments in the hope that they will +go away. They will not go away. If you repost code without having +responded to the comments you got the time before, you're likely to find +that your patches go nowhere. + +Speaking of reposting code: please bear in mind that reviewers are not +going to remember all the details of the code you posted the last time +around. So it is always a good idea to remind reviewers of previously +raised issues and how you dealt with them; the patch changelog is a good +place for this kind of information. Reviewers should not have to search +through list archives to familiarize themselves with what was said last +time; if you help them get a running start, they will be in a better mood +when they revisit your code. + +What if you've tried to do everything right and things still aren't going +anywhere? Most technical disagreements can be resolved through discussion, +but there are times when somebody simply has to make a decision. If you +honestly believe that this decision is going against you wrongly, you can +always try appealing to a higher power. As of this writing, that higher +power tends to be Andrew Morton. Andrew has a great deal of respect in the +kernel development community; he can often unjam a situation which seems to +be hopelessly blocked. Appealing to Andrew should not be done lightly, +though, and not before all other alternatives have been explored. And bear +in mind, of course, that he may not agree with you either. + + +What happens next +----------------- + +If a patch is considered to be a good thing to add to the kernel, and once +most of the review issues have been resolved, the next step is usually +entry into a subsystem maintainer's tree. How that works varies from one +subsystem to the next; each maintainer has his or her own way of doing +things. In particular, there may be more than one tree - one, perhaps, +dedicated to patches planned for the next merge window, and another for +longer-term work. + +For patches applying to areas for which there is no obvious subsystem tree +(memory management patches, for example), the default tree often ends up +being -mm. Patches which affect multiple subsystems can also end up going +through the -mm tree. + +Inclusion into a subsystem tree can bring a higher level of visibility to a +patch. Now other developers working with that tree will get the patch by +default. Subsystem trees typically feed linux-next as well, making their +contents visible to the development community as a whole. At this point, +there's a good chance that you will get more comments from a new set of +reviewers; these comments need to be answered as in the previous round. + +What may also happen at this point, depending on the nature of your patch, +is that conflicts with work being done by others turn up. In the worst +case, heavy patch conflicts can result in some work being put on the back +burner so that the remaining patches can be worked into shape and merged. +Other times, conflict resolution will involve working with the other +developers and, possibly, moving some patches between trees to ensure that +everything applies cleanly. This work can be a pain, but count your +blessings: before the advent of the linux-next tree, these conflicts often +only turned up during the merge window and had to be addressed in a hurry. +Now they can be resolved at leisure, before the merge window opens. + +Some day, if all goes well, you'll log on and see that your patch has been +merged into the mainline kernel. Congratulations! Once the celebration is +complete (and you have added yourself to the MAINTAINERS file), though, it +is worth remembering an important little fact: the job still is not done. +Merging into the mainline brings its own challenges. + +To begin with, the visibility of your patch has increased yet again. There +may be a new round of comments from developers who had not been aware of +the patch before. It may be tempting to ignore them, since there is no +longer any question of your code being merged. Resist that temptation, +though; you still need to be responsive to developers who have questions or +suggestions. + +More importantly, though: inclusion into the mainline puts your code into +the hands of a much larger group of testers. Even if you have contributed +a driver for hardware which is not yet available, you will be surprised by +how many people will build your code into their kernels. And, of course, +where there are testers, there will be bug reports. + +The worst sort of bug reports are regressions. If your patch causes a +regression, you'll find an uncomfortable number of eyes upon you; +regressions need to be fixed as soon as possible. If you are unwilling or +unable to fix the regression (and nobody else does it for you), your patch +will almost certainly be removed during the stabilization period. Beyond +negating all of the work you have done to get your patch into the mainline, +having a patch pulled as the result of a failure to fix a regression could +well make it harder for you to get work merged in the future. + +After any regressions have been dealt with, there may be other, ordinary +bugs to deal with. The stabilization period is your best opportunity to +fix these bugs and ensure that your code's debut in a mainline kernel +release is as solid as possible. So, please, answer bug reports, and fix +the problems if at all possible. That's what the stabilization period is +for; you can start creating cool new patches once any problems with the old +ones have been taken care of. + +And don't forget that there are other milestones which may also create bug +reports: the next mainline stable release, when prominent distributors pick +up a version of the kernel containing your patch, etc. Continuing to +respond to these reports is a matter of basic pride in your work. If that +is insufficient motivation, though, it's also worth considering that the +development community remembers developers who lose interest in their code +after it's merged. The next time you post a patch, they will be evaluating +it with the assumption that you will not be around to maintain it +afterward. + + +Other things that can happen +----------------------------- + +One day, you may open your mail client and see that somebody has mailed you +a patch to your code. That is one of the advantages of having your code +out there in the open, after all. If you agree with the patch, you can +either forward it on to the subsystem maintainer (be sure to include a +proper From: line so that the attribution is correct, and add a signoff of +your own), or send an Acked-by: response back and let the original poster +send it upward. + +If you disagree with the patch, send a polite response explaining why. If +possible, tell the author what changes need to be made to make the patch +acceptable to you. There is a certain resistance to merging patches which +are opposed by the author and maintainer of the code, but it only goes so +far. If you are seen as needlessly blocking good work, those patches will +eventually flow around you and get into the mainline anyway. In the Linux +kernel, nobody has absolute veto power over any code. Except maybe Linus. + +On very rare occasion, you may see something completely different: another +developer posts a different solution to your problem. At that point, +chances are that one of the two patches will not be merged, and "mine was +here first" is not considered to be a compelling technical argument. If +somebody else's patch displaces yours and gets into the mainline, there is +really only one way to respond: be pleased that your problem got solved and +get on with your work. Having one's work shoved aside in this manner can +be hurtful and discouraging, but the community will remember your reaction +long after they have forgotten whose patch actually got merged. diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics deleted file mode 100644 index 26dc3fa196e4..000000000000 --- a/Documentation/development-process/7.AdvancedTopics +++ /dev/null @@ -1,173 +0,0 @@ -7: ADVANCED TOPICS - -At this point, hopefully, you have a handle on how the development process -works. There is still more to learn, however! This section will cover a -number of topics which can be helpful for developers wanting to become a -regular part of the Linux kernel development process. - -7.1: MANAGING PATCHES WITH GIT - -The use of distributed version control for the kernel began in early 2002, -when Linus first started playing with the proprietary BitKeeper -application. While BitKeeper was controversial, the approach to software -version management it embodied most certainly was not. Distributed version -control enabled an immediate acceleration of the kernel development -project. In current times, there are several free alternatives to -BitKeeper. For better or for worse, the kernel project has settled on git -as its tool of choice. - -Managing patches with git can make life much easier for the developer, -especially as the volume of those patches grows. Git also has its rough -edges and poses certain hazards; it is a young and powerful tool which is -still being civilized by its developers. This document will not attempt to -teach the reader how to use git; that would be sufficient material for a -long document in its own right. Instead, the focus here will be on how git -fits into the kernel development process in particular. Developers who -wish to come up to speed with git will find more information at: - - http://git-scm.com/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - -and on various tutorials found on the web. - -The first order of business is to read the above sites and get a solid -understanding of how git works before trying to use it to make patches -available to others. A git-using developer should be able to obtain a copy -of the mainline repository, explore the revision history, commit changes to -the tree, use branches, etc. An understanding of git's tools for the -rewriting of history (such as rebase) is also useful. Git comes with its -own terminology and concepts; a new user of git should know about refs, -remote branches, the index, fast-forward merges, pushes and pulls, detached -heads, etc. It can all be a little intimidating at the outset, but the -concepts are not that hard to grasp with a bit of study. - -Using git to generate patches for submission by email can be a good -exercise while coming up to speed. - -When you are ready to start putting up git trees for others to look at, you -will, of course, need a server that can be pulled from. Setting up such a -server with git-daemon is relatively straightforward if you have a system -which is accessible to the Internet. Otherwise, free, public hosting sites -(Github, for example) are starting to appear on the net. Established -developers can get an account on kernel.org, but those are not easy to come -by; see http://kernel.org/faq/ for more information. - -The normal git workflow involves the use of a lot of branches. Each line -of development can be separated into a separate "topic branch" and -maintained independently. Branches in git are cheap, there is no reason to -not make free use of them. And, in any case, you should not do your -development in any branch which you intend to ask others to pull from. -Publicly-available branches should be created with care; merge in patches -from development branches when they are in complete form and ready to go - -not before. - -Git provides some powerful tools which can allow you to rewrite your -development history. An inconvenient patch (one which breaks bisection, -say, or which has some other sort of obvious bug) can be fixed in place or -made to disappear from the history entirely. A patch series can be -rewritten as if it had been written on top of today's mainline, even though -you have been working on it for months. Changes can be transparently -shifted from one branch to another. And so on. Judicious use of git's -ability to revise history can help in the creation of clean patch sets with -fewer problems. - -Excessive use of this capability can lead to other problems, though, beyond -a simple obsession for the creation of the perfect project history. -Rewriting history will rewrite the changes contained in that history, -turning a tested (hopefully) kernel tree into an untested one. But, beyond -that, developers cannot easily collaborate if they do not have a shared -view of the project history; if you rewrite history which other developers -have pulled into their repositories, you will make life much more difficult -for those developers. So a simple rule of thumb applies here: history -which has been exported to others should generally be seen as immutable -thereafter. - -So, once you push a set of changes to your publicly-available server, those -changes should not be rewritten. Git will attempt to enforce this rule if -you try to push changes which do not result in a fast-forward merge -(i.e. changes which do not share the same history). It is possible to -override this check, and there may be times when it is necessary to rewrite -an exported tree. Moving changesets between trees to avoid conflicts in -linux-next is one example. But such actions should be rare. This is one -of the reasons why development should be done in private branches (which -can be rewritten if necessary) and only moved into public branches when -it's in a reasonably advanced state. - -As the mainline (or other tree upon which a set of changes is based) -advances, it is tempting to merge with that tree to stay on the leading -edge. For a private branch, rebasing can be an easy way to keep up with -another tree, but rebasing is not an option once a tree is exported to the -world. Once that happens, a full merge must be done. Merging occasionally -makes good sense, but overly frequent merges can clutter the history -needlessly. Suggested technique in this case is to merge infrequently, and -generally only at specific release points (such as a mainline -rc -release). If you are nervous about specific changes, you can always -perform test merges in a private branch. The git "rerere" tool can be -useful in such situations; it remembers how merge conflicts were resolved -so that you don't have to do the same work twice. - -One of the biggest recurring complaints about tools like git is this: the -mass movement of patches from one repository to another makes it easy to -slip in ill-advised changes which go into the mainline below the review -radar. Kernel developers tend to get unhappy when they see that kind of -thing happening; putting up a git tree with unreviewed or off-topic patches -can affect your ability to get trees pulled in the future. Quoting Linus: - - You can send me patches, but for me to pull a git patch from you, I - need to know that you know what you're doing, and I need to be able - to trust things *without* then having to go and check every - individual change by hand. - -(http://lwn.net/Articles/224135/). - -To avoid this kind of situation, ensure that all patches within a given -branch stick closely to the associated topic; a "driver fixes" branch -should not be making changes to the core memory management code. And, most -importantly, do not use a git tree to bypass the review process. Post an -occasional summary of the tree to the relevant list, and, when the time is -right, request that the tree be included in linux-next. - -If and when others start to send patches for inclusion into your tree, -don't forget to review them. Also ensure that you maintain the correct -authorship information; the git "am" tool does its best in this regard, but -you may have to add a "From:" line to the patch if it has been relayed to -you via a third party. - -When requesting a pull, be sure to give all the relevant information: where -your tree is, what branch to pull, and what changes will result from the -pull. The git request-pull command can be helpful in this regard; it will -format the request as other developers expect, and will also check to be -sure that you have remembered to push those changes to the public server. - - -7.2: REVIEWING PATCHES - -Some readers will certainly object to putting this section with "advanced -topics" on the grounds that even beginning kernel developers should be -reviewing patches. It is certainly true that there is no better way to -learn how to program in the kernel environment than by looking at code -posted by others. In addition, reviewers are forever in short supply; by -looking at code you can make a significant contribution to the process as a -whole. - -Reviewing code can be an intimidating prospect, especially for a new kernel -developer who may well feel nervous about questioning code - in public - -which has been posted by those with more experience. Even code written by -the most experienced developers can be improved, though. Perhaps the best -piece of advice for reviewers (all reviewers) is this: phrase review -comments as questions rather than criticisms. Asking "how does the lock -get released in this path?" will always work better than stating "the -locking here is wrong." - -Different developers will review code from different points of view. Some -are mostly concerned with coding style and whether code lines have trailing -white space. Others will focus primarily on whether the change implemented -by the patch as a whole is a good thing for the kernel or not. Yet others -will check for problematic locking, excessive stack usage, possible -security issues, duplication of code found elsewhere, adequate -documentation, adverse effects on performance, user-space ABI changes, etc. -All types of review, if they lead to better code going into the kernel, are -welcome and worthwhile. - - diff --git a/Documentation/development-process/7.AdvancedTopics.rst b/Documentation/development-process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..81d61c5d62dd --- /dev/null +++ b/Documentation/development-process/7.AdvancedTopics.rst @@ -0,0 +1,180 @@ +.. _development_advancedtopics: + +Advanced topics +=============== + +At this point, hopefully, you have a handle on how the development process +works. There is still more to learn, however! This section will cover a +number of topics which can be helpful for developers wanting to become a +regular part of the Linux kernel development process. + +Managing patches with git +------------------------- + +The use of distributed version control for the kernel began in early 2002, +when Linus first started playing with the proprietary BitKeeper +application. While BitKeeper was controversial, the approach to software +version management it embodied most certainly was not. Distributed version +control enabled an immediate acceleration of the kernel development +project. In current times, there are several free alternatives to +BitKeeper. For better or for worse, the kernel project has settled on git +as its tool of choice. + +Managing patches with git can make life much easier for the developer, +especially as the volume of those patches grows. Git also has its rough +edges and poses certain hazards; it is a young and powerful tool which is +still being civilized by its developers. This document will not attempt to +teach the reader how to use git; that would be sufficient material for a +long document in its own right. Instead, the focus here will be on how git +fits into the kernel development process in particular. Developers who +wish to come up to speed with git will find more information at: + + http://git-scm.com/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +and on various tutorials found on the web. + +The first order of business is to read the above sites and get a solid +understanding of how git works before trying to use it to make patches +available to others. A git-using developer should be able to obtain a copy +of the mainline repository, explore the revision history, commit changes to +the tree, use branches, etc. An understanding of git's tools for the +rewriting of history (such as rebase) is also useful. Git comes with its +own terminology and concepts; a new user of git should know about refs, +remote branches, the index, fast-forward merges, pushes and pulls, detached +heads, etc. It can all be a little intimidating at the outset, but the +concepts are not that hard to grasp with a bit of study. + +Using git to generate patches for submission by email can be a good +exercise while coming up to speed. + +When you are ready to start putting up git trees for others to look at, you +will, of course, need a server that can be pulled from. Setting up such a +server with git-daemon is relatively straightforward if you have a system +which is accessible to the Internet. Otherwise, free, public hosting sites +(Github, for example) are starting to appear on the net. Established +developers can get an account on kernel.org, but those are not easy to come +by; see http://kernel.org/faq/ for more information. + +The normal git workflow involves the use of a lot of branches. Each line +of development can be separated into a separate "topic branch" and +maintained independently. Branches in git are cheap, there is no reason to +not make free use of them. And, in any case, you should not do your +development in any branch which you intend to ask others to pull from. +Publicly-available branches should be created with care; merge in patches +from development branches when they are in complete form and ready to go - +not before. + +Git provides some powerful tools which can allow you to rewrite your +development history. An inconvenient patch (one which breaks bisection, +say, or which has some other sort of obvious bug) can be fixed in place or +made to disappear from the history entirely. A patch series can be +rewritten as if it had been written on top of today's mainline, even though +you have been working on it for months. Changes can be transparently +shifted from one branch to another. And so on. Judicious use of git's +ability to revise history can help in the creation of clean patch sets with +fewer problems. + +Excessive use of this capability can lead to other problems, though, beyond +a simple obsession for the creation of the perfect project history. +Rewriting history will rewrite the changes contained in that history, +turning a tested (hopefully) kernel tree into an untested one. But, beyond +that, developers cannot easily collaborate if they do not have a shared +view of the project history; if you rewrite history which other developers +have pulled into their repositories, you will make life much more difficult +for those developers. So a simple rule of thumb applies here: history +which has been exported to others should generally be seen as immutable +thereafter. + +So, once you push a set of changes to your publicly-available server, those +changes should not be rewritten. Git will attempt to enforce this rule if +you try to push changes which do not result in a fast-forward merge +(i.e. changes which do not share the same history). It is possible to +override this check, and there may be times when it is necessary to rewrite +an exported tree. Moving changesets between trees to avoid conflicts in +linux-next is one example. But such actions should be rare. This is one +of the reasons why development should be done in private branches (which +can be rewritten if necessary) and only moved into public branches when +it's in a reasonably advanced state. + +As the mainline (or other tree upon which a set of changes is based) +advances, it is tempting to merge with that tree to stay on the leading +edge. For a private branch, rebasing can be an easy way to keep up with +another tree, but rebasing is not an option once a tree is exported to the +world. Once that happens, a full merge must be done. Merging occasionally +makes good sense, but overly frequent merges can clutter the history +needlessly. Suggested technique in this case is to merge infrequently, and +generally only at specific release points (such as a mainline -rc +release). If you are nervous about specific changes, you can always +perform test merges in a private branch. The git "rerere" tool can be +useful in such situations; it remembers how merge conflicts were resolved +so that you don't have to do the same work twice. + +One of the biggest recurring complaints about tools like git is this: the +mass movement of patches from one repository to another makes it easy to +slip in ill-advised changes which go into the mainline below the review +radar. Kernel developers tend to get unhappy when they see that kind of +thing happening; putting up a git tree with unreviewed or off-topic patches +can affect your ability to get trees pulled in the future. Quoting Linus: + +:: + + You can send me patches, but for me to pull a git patch from you, I + need to know that you know what you're doing, and I need to be able + to trust things *without* then having to go and check every + individual change by hand. + +(http://lwn.net/Articles/224135/). + +To avoid this kind of situation, ensure that all patches within a given +branch stick closely to the associated topic; a "driver fixes" branch +should not be making changes to the core memory management code. And, most +importantly, do not use a git tree to bypass the review process. Post an +occasional summary of the tree to the relevant list, and, when the time is +right, request that the tree be included in linux-next. + +If and when others start to send patches for inclusion into your tree, +don't forget to review them. Also ensure that you maintain the correct +authorship information; the git "am" tool does its best in this regard, but +you may have to add a "From:" line to the patch if it has been relayed to +you via a third party. + +When requesting a pull, be sure to give all the relevant information: where +your tree is, what branch to pull, and what changes will result from the +pull. The git request-pull command can be helpful in this regard; it will +format the request as other developers expect, and will also check to be +sure that you have remembered to push those changes to the public server. + + +Reviewing patches +----------------- + +Some readers will certainly object to putting this section with "advanced +topics" on the grounds that even beginning kernel developers should be +reviewing patches. It is certainly true that there is no better way to +learn how to program in the kernel environment than by looking at code +posted by others. In addition, reviewers are forever in short supply; by +looking at code you can make a significant contribution to the process as a +whole. + +Reviewing code can be an intimidating prospect, especially for a new kernel +developer who may well feel nervous about questioning code - in public - +which has been posted by those with more experience. Even code written by +the most experienced developers can be improved, though. Perhaps the best +piece of advice for reviewers (all reviewers) is this: phrase review +comments as questions rather than criticisms. Asking "how does the lock +get released in this path?" will always work better than stating "the +locking here is wrong." + +Different developers will review code from different points of view. Some +are mostly concerned with coding style and whether code lines have trailing +white space. Others will focus primarily on whether the change implemented +by the patch as a whole is a good thing for the kernel or not. Yet others +will check for problematic locking, excessive stack usage, possible +security issues, duplication of code found elsewhere, adequate +documentation, adverse effects on performance, user-space ABI changes, etc. +All types of review, if they lead to better code going into the kernel, are +welcome and worthwhile. + + diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion deleted file mode 100644 index caef69022e9c..000000000000 --- a/Documentation/development-process/8.Conclusion +++ /dev/null @@ -1,70 +0,0 @@ -8: FOR MORE INFORMATION - -There are numerous sources of information on Linux kernel development and -related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level HOWTO -file is an important starting point; SubmittingPatches and -SubmittingDrivers are also something which all kernel developers should -read. Many internal kernel APIs are documented using the kerneldoc -mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those -documents in HTML or PDF format (though the version of TeX shipped by some -distributions runs into internal limits and fails to process the documents -properly). - -Various web sites discuss kernel development at all levels of detail. Your -author would like to humbly suggest http://lwn.net/ as a source; -information on many specific kernel topics can be found via the LWN kernel -index at: - - http://lwn.net/Kernel/Index/ - -Beyond that, a valuable resource for kernel developers is: - - http://kernelnewbies.org/ - -And, of course, one should not forget http://kernel.org/, the definitive -location for kernel release information. - -There are a number of books on kernel development: - - Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro - Rubini, and Greg Kroah-Hartman). Online at - http://lwn.net/Kernel/LDD3/. - - Linux Kernel Development (Robert Love). - - Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). - -All of these books suffer from a common fault, though: they tend to be -somewhat obsolete by the time they hit the shelves, and they have been on -the shelves for a while now. Still, there is quite a bit of good -information to be found there. - -Documentation for git can be found at: - - http://www.kernel.org/pub/software/scm/git/docs/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - - -9: CONCLUSION - -Congratulations to anybody who has made it through this long-winded -document. Hopefully it has provided a helpful understanding of how the -Linux kernel is developed and how you can participate in that process. - -In the end, it's the participation that matters. Any open source software -project is no more than the sum of what its contributors put into it. The -Linux kernel has progressed as quickly and as well as it has because it has -been helped by an impressively large group of developers, all of whom are -working to make it better. The kernel is a premier example of what can be -done when thousands of people work together toward a common goal. - -The kernel can always benefit from a larger developer base, though. There -is always more work to do. But, just as importantly, most other -participants in the Linux ecosystem can benefit through contributing to the -kernel. Getting code into the mainline is the key to higher code quality, -lower maintenance and distribution costs, a higher level of influence over -the direction of kernel development, and more. It is a situation where -everybody involved wins. Fire up your editor and come join us; you will be -more than welcome. diff --git a/Documentation/development-process/8.Conclusion.rst b/Documentation/development-process/8.Conclusion.rst new file mode 100644 index 000000000000..23ec7cbc2d2b --- /dev/null +++ b/Documentation/development-process/8.Conclusion.rst @@ -0,0 +1,74 @@ +.. _development_conclusion: + +For more information +==================== + +There are numerous sources of information on Linux kernel development and +related topics. First among those will always be the Documentation +directory found in the kernel source distribution. The top-level HOWTO +file is an important starting point; SubmittingPatches and +SubmittingDrivers are also something which all kernel developers should +read. Many internal kernel APIs are documented using the kerneldoc +mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those +documents in HTML or PDF format (though the version of TeX shipped by some +distributions runs into internal limits and fails to process the documents +properly). + +Various web sites discuss kernel development at all levels of detail. Your +author would like to humbly suggest http://lwn.net/ as a source; +information on many specific kernel topics can be found via the LWN kernel +index at: + + http://lwn.net/Kernel/Index/ + +Beyond that, a valuable resource for kernel developers is: + + http://kernelnewbies.org/ + +And, of course, one should not forget http://kernel.org/, the definitive +location for kernel release information. + +There are a number of books on kernel development: + + Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro + Rubini, and Greg Kroah-Hartman). Online at + http://lwn.net/Kernel/LDD3/. + + Linux Kernel Development (Robert Love). + + Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). + +All of these books suffer from a common fault, though: they tend to be +somewhat obsolete by the time they hit the shelves, and they have been on +the shelves for a while now. Still, there is quite a bit of good +information to be found there. + +Documentation for git can be found at: + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + + +Conclusion +========== + +Congratulations to anybody who has made it through this long-winded +document. Hopefully it has provided a helpful understanding of how the +Linux kernel is developed and how you can participate in that process. + +In the end, it's the participation that matters. Any open source software +project is no more than the sum of what its contributors put into it. The +Linux kernel has progressed as quickly and as well as it has because it has +been helped by an impressively large group of developers, all of whom are +working to make it better. The kernel is a premier example of what can be +done when thousands of people work together toward a common goal. + +The kernel can always benefit from a larger developer base, though. There +is always more work to do. But, just as importantly, most other +participants in the Linux ecosystem can benefit through contributing to the +kernel. Getting code into the mainline is the key to higher code quality, +lower maintenance and distribution costs, a higher level of influence over +the direction of kernel development, and more. It is a situation where +everybody involved wins. Fire up your editor and come join us; you will be +more than welcome. diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py new file mode 100644 index 000000000000..4b4a12dace02 --- /dev/null +++ b/Documentation/development-process/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'development-process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst new file mode 100644 index 000000000000..bd1399f7202a --- /dev/null +++ b/Documentation/development-process/development-process.rst @@ -0,0 +1,29 @@ +.. _development_process_main: + +A guide to the Kernel Development Process +========================================= + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. + diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst new file mode 100644 index 000000000000..c37475d91090 --- /dev/null +++ b/Documentation/development-process/index.rst @@ -0,0 +1,9 @@ +Linux Kernel Development Documentation +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + development-process diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt b/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt index b545856a444f..4a1714f96bab 100644 --- a/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt +++ b/Documentation/devicetree/bindings/arm/altera/socfpga-eccmgr.txt @@ -90,6 +90,47 @@ Required Properties: - interrupts : Should be single bit error interrupt, then double bit error interrupt, in this order. +NAND FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-nand-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent NAND node. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order. + +DMA FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-dma-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent DMA node. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order. + +USB FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-usb-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent USB node. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order. + +QSPI FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-qspi-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent QSPI node. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order. + +SDMMC FIFO ECC +Required Properties: +- compatible : Should be "altr,socfpga-sdmmc-ecc" +- reg : Address and size for ECC block registers. +- altr,ecc-parent : phandle to parent SD/MMC node. +- interrupts : Should be single bit error interrupt, then double bit error + interrupt, in this order for port A, and then single bit error interrupt, + then double bit error interrupt in this order for port B. + Example: eccmgr: eccmgr@ffd06000 { @@ -132,4 +173,61 @@ Example: interrupts = <5 IRQ_TYPE_LEVEL_HIGH>, <37 IRQ_TYPE_LEVEL_HIGH>; }; + + nand-buf-ecc@ff8c2000 { + compatible = "altr,socfpga-nand-ecc"; + reg = <0xff8c2000 0x400>; + altr,ecc-parent = <&nand>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>, + <43 IRQ_TYPE_LEVEL_HIGH>; + }; + + nand-rd-ecc@ff8c2400 { + compatible = "altr,socfpga-nand-ecc"; + reg = <0xff8c2400 0x400>; + altr,ecc-parent = <&nand>; + interrupts = <13 IRQ_TYPE_LEVEL_HIGH>, + <45 IRQ_TYPE_LEVEL_HIGH>; + }; + + nand-wr-ecc@ff8c2800 { + compatible = "altr,socfpga-nand-ecc"; + reg = <0xff8c2800 0x400>; + altr,ecc-parent = <&nand>; + interrupts = <12 IRQ_TYPE_LEVEL_HIGH>, + <44 IRQ_TYPE_LEVEL_HIGH>; + }; + + dma-ecc@ff8c8000 { + compatible = "altr,socfpga-dma-ecc"; + reg = <0xff8c8000 0x400>; + altr,ecc-parent = <&pdma>; + interrupts = <10 IRQ_TYPE_LEVEL_HIGH>, + <42 IRQ_TYPE_LEVEL_HIGH>; + + usb0-ecc@ff8c8800 { + compatible = "altr,socfpga-usb-ecc"; + reg = <0xff8c8800 0x400>; + altr,ecc-parent = <&usb0>; + interrupts = <2 IRQ_TYPE_LEVEL_HIGH>, + <34 IRQ_TYPE_LEVEL_HIGH>; + }; + + qspi-ecc@ff8c8400 { + compatible = "altr,socfpga-qspi-ecc"; + reg = <0xff8c8400 0x400>; + altr,ecc-parent = <&qspi>; + interrupts = <14 IRQ_TYPE_LEVEL_HIGH>, + <46 IRQ_TYPE_LEVEL_HIGH>; + }; + + sdmmc-ecc@ff8c2c00 { + compatible = "altr,socfpga-sdmmc-ecc"; + reg = <0xff8c2c00 0x400>; + altr,ecc-parent = <&mmc>; + interrupts = <15 IRQ_TYPE_LEVEL_HIGH>, + <47 IRQ_TYPE_LEVEL_HIGH>, + <16 IRQ_TYPE_LEVEL_HIGH>, + <48 IRQ_TYPE_LEVEL_HIGH>; + }; }; diff --git a/Documentation/devicetree/bindings/arm/arch_timer.txt b/Documentation/devicetree/bindings/arm/arch_timer.txt index e774128935d5..ef5fbe9a77c7 100644 --- a/Documentation/devicetree/bindings/arm/arch_timer.txt +++ b/Documentation/devicetree/bindings/arm/arch_timer.txt @@ -25,6 +25,12 @@ to deliver its interrupts via SPIs. - always-on : a boolean property. If present, the timer is powered through an always-on power domain, therefore it never loses context. +- fsl,erratum-a008585 : A boolean property. Indicates the presence of + QorIQ erratum A-008585, which says that reading the counter is + unreliable unless the same value is returned by back-to-back reads. + This also affects writes to the tval register, due to the implicit + counter read. + ** Optional properties: - arm,cpu-registers-not-fw-configured : Firmware does not initialize diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt index 6ffe08778465..9c97de23919a 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt @@ -38,6 +38,10 @@ Raspberry Pi Compute Module Required root node properties: compatible = "raspberrypi,compute-module", "brcm,bcm2835"; +Raspberry Pi Zero +Required root node properties: +compatible = "raspberrypi,model-zero", "brcm,bcm2835"; + Generic BCM2835 board Required root node properties: compatible = "brcm,bcm2835"; diff --git a/Documentation/devicetree/bindings/arm/davinci.txt b/Documentation/devicetree/bindings/arm/davinci.txt index cfaeda4274e6..f0841ce725b5 100644 --- a/Documentation/devicetree/bindings/arm/davinci.txt +++ b/Documentation/devicetree/bindings/arm/davinci.txt @@ -5,6 +5,10 @@ DA850/OMAP-L138/AM18x Evaluation Module (EVM) board Required root node properties: - compatible = "ti,da850-evm", "ti,da850"; +DA850/OMAP-L138/AM18x L138/C6748 Development Kit (LCDK) board +Required root node properties: + - compatible = "ti,da850-lcdk", "ti,da850"; + EnBW AM1808 based CMC board Required root node properties: - compatible = "enbw,cmc", "ti,da850; diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index 83fe816ae050..3f81575aa6be 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -175,38 +175,55 @@ Example: }; ----------------------------------------------------------------------- -Hisilicon HiP05 PCIe-SAS system controller +Hisilicon HiP05/HiP06 PCIe-SAS sub system controller Required properties: - compatible : "hisilicon,pcie-sas-subctrl", "syscon"; - reg : Register address and size -The HiP05 PCIe-SAS system controller is shared by PCIe and SAS controllers in -HiP05 Soc to implement some basic configurations. +The PCIe-SAS sub system controller is shared by PCIe and SAS controllers in +HiP05 or HiP06 Soc to implement some basic configurations. Example: - /* for HiP05 PCIe-SAS system */ - pcie_sas: system_controller@0xb0000000 { + /* for HiP05 PCIe-SAS sub system */ + pcie_sas: system_controller@b0000000 { compatible = "hisilicon,pcie-sas-subctrl", "syscon"; reg = <0xb0000000 0x10000>; }; -Hisilicon HiP05 PERISUB system controller +Hisilicon HiP05/HiP06 PERI sub system controller Required properties: -- compatible : "hisilicon,hip05-perisubc", "syscon"; +- compatible : "hisilicon,peri-subctrl", "syscon"; - reg : Register address and size -The HiP05 PERISUB system controller is shared by peripheral controllers in -HiP05 Soc to implement some basic configurations. The peripheral +The PERI sub system controller is shared by peripheral controllers in +HiP05 or HiP06 Soc to implement some basic configurations. The peripheral controllers include mdio, ddr, iic, uart, timer and so on. Example: - /* for HiP05 perisub-ctrl-c system */ + /* for HiP05 sub peri system */ peri_c_subctrl: syscon@80000000 { - compatible = "hisilicon,hip05-perisubc", "syscon"; + compatible = "hisilicon,peri-subctrl", "syscon"; reg = <0x0 0x80000000 0x0 0x10000>; }; + +Hisilicon HiP05/HiP06 DSA sub system controller + +Required properties: +- compatible : "hisilicon,dsa-subctrl", "syscon"; +- reg : Register address and size + +The DSA sub system controller is shared by peripheral controllers in +HiP05 or HiP06 Soc to implement some basic configurations. + +Example: + /* for HiP05 dsa sub system */ + pcie_sas: system_controller@a0000000 { + compatible = "hisilicon,dsa-subctrl", "syscon"; + reg = <0xa0000000 0x10000>; + }; + ----------------------------------------------------------------------- Hisilicon CPU controller diff --git a/Documentation/devicetree/bindings/arm/marvell/armada-39x.txt b/Documentation/devicetree/bindings/arm/marvell/armada-39x.txt index 53d4ff9ea8ad..89468664f6ea 100644 --- a/Documentation/devicetree/bindings/arm/marvell/armada-39x.txt +++ b/Documentation/devicetree/bindings/arm/marvell/armada-39x.txt @@ -8,8 +8,19 @@ Required root node property: - compatible: must contain "marvell,armada390" -In addition, boards using the Marvell Armada 398 SoC shall have the -following property before the previous one: +In addition, boards using the Marvell Armada 395 SoC shall have the +following property before the common "marvell,armada390" one: + +Required root node property: + +compatible: must contain "marvell,armada395" + +Example: + +compatible = "marvell,a395-gp", "marvell,armada395", "marvell,armada390"; + +Boards using the Marvell Armada 398 SoC shall have the following +property before the common "marvell,armada390" one: Required root node property: diff --git a/Documentation/devicetree/bindings/arm/marvell/marvell,orion5x.txt b/Documentation/devicetree/bindings/arm/marvell/marvell,orion5x.txt new file mode 100644 index 000000000000..748a8f287462 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/marvell/marvell,orion5x.txt @@ -0,0 +1,25 @@ +Marvell Orion SoC Family Device Tree Bindings +--------------------------------------------- + +Boards with a SoC of the Marvell Orion family, eg 88f5181 + +* Required root node properties: +compatible: must contain "marvell,orion5x" + +In addition, the above compatible shall be extended with the specific +SoC. Currently known SoC compatibles are: + +"marvell,orion5x-88f5181" +"marvell,orion5x-88f5182" + +And in addition, the compatible shall be extended with the specific +board. Currently known boards are: + +"buffalo,lsgl" +"buffalo,lswsgl" +"buffalo,lswtgl" +"lacie,ethernet-disk-mini-v2" +"lacie,d2-network" +"marvell,rd-88f5182-nas" +"maxtor,shared-storage-2" +"netgear,wnr854t" diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index 936166fbee09..cb0054ac7121 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -5,7 +5,8 @@ The Mediatek apmixedsys controller provides the PLLs to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-apmixedsys" - "mediatek,mt8135-apmixedsys" - "mediatek,mt8173-apmixedsys" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt new file mode 100644 index 000000000000..4137196dd686 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt @@ -0,0 +1,22 @@ +Mediatek bdpsys controller +============================ + +The Mediatek bdpsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt2701-bdpsys", "syscon" +- #clock-cells: Must be 1 + +The bdpsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +bdpsys: clock-controller@1c000000 { + compatible = "mediatek,mt2701-bdpsys", "syscon"; + reg = <0 0x1c000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt new file mode 100644 index 000000000000..768f3a5bc055 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt @@ -0,0 +1,22 @@ +Mediatek ethsys controller +============================ + +The Mediatek ethsys controller provides various clocks to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt2701-ethsys", "syscon" +- #clock-cells: Must be 1 + +The ethsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +ethsys: clock-controller@1b000000 { + compatible = "mediatek,mt2701-ethsys", "syscon"; + reg = <0 0x1b000000 0 0x1000>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt new file mode 100644 index 000000000000..beed7b594cea --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt @@ -0,0 +1,24 @@ +Mediatek hifsys controller +============================ + +The Mediatek hifsys controller provides various clocks and reset +outputs to the system. + +Required Properties: + +- compatible: Should be: + - "mediatek,mt2701-hifsys", "syscon" +- #clock-cells: Must be 1 + +The hifsys controller uses the common clk binding from +Documentation/devicetree/bindings/clock/clock-bindings.txt +The available clocks are defined in dt-bindings/clock/mt*-clk.h. + +Example: + +hifsys: clock-controller@1a000000 { + compatible = "mediatek,mt2701-hifsys", "syscon"; + reg = <0 0x1a000000 0 0x1000>; + #clock-cells = <1>; + #reset-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt index b1f2ce17dff8..f6a916686f4c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -5,7 +5,8 @@ The Mediatek imgsys controller provides various clocks to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-imgsys", "syscon" - "mediatek,mt8173-imgsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index aaf8d1460c4d..1620ec2a5a3f 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -6,7 +6,8 @@ outputs to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-infracfg", "syscon" - "mediatek,mt8135-infracfg", "syscon" - "mediatek,mt8173-infracfg", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index 4385946eadef..67dd2e473d25 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -5,7 +5,8 @@ The Mediatek mmsys controller provides various clocks to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-mmsys", "syscon" - "mediatek,mt8173-mmsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt index 2f6ff86df49f..e494366782aa 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt @@ -6,7 +6,8 @@ outputs to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-pericfg", "syscon" - "mediatek,mt8135-pericfg", "syscon" - "mediatek,mt8173-pericfg", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index f9e917994ced..9f2fe7860114 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -5,7 +5,8 @@ The Mediatek topckgen controller provides various clocks to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-topckgen" - "mediatek,mt8135-topckgen" - "mediatek,mt8173-topckgen" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt index 1faacf1c1b25..2440f73450c3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt @@ -5,7 +5,8 @@ The Mediatek vdecsys controller provides various clocks to the system. Required Properties: -- compatible: Should be: +- compatible: Should be one of: + - "mediatek,mt2701-vdecsys", "syscon" - "mediatek,mt8173-vdecsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index 94b57f247615..f53e2ee65e35 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -180,3 +180,9 @@ Boards: - DRA722 EVM: Software Development Board for DRA722 compatible = "ti,dra72-evm", "ti,dra722", "ti,dra72", "ti,dra7" + +- DM3730 Logic PD Torpedo + Wireless: Commercial System on Module with WiFi and Bluetooth + compatible = "logicpd,dm3730-torpedo-devkit", "ti,omap3630", "ti,omap3" + +- DM3730 Logic PD SOM-LV: Commercial System on Module with WiFi and Bluetooth + compatible = "logicpd,dm3730-som-lv-devkit", "ti,omap3630", "ti,omap3" diff --git a/Documentation/devicetree/bindings/arm/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt index 666864517069..55f388f954de 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ b/Documentation/devicetree/bindings/arm/rockchip.txt @@ -31,6 +31,10 @@ Rockchip platforms device tree bindings or - compatible = "firefly,firefly-rk3288-beta", "rockchip,rk3288"; +- Firefly Firefly-RK3288 Reload board: + Required root node properties: + - compatible = "firefly,firefly-rk3288-reload", "rockchip,rk3288"; + - ChipSPARK PopMetal-RK3288 board: Required root node properties: - compatible = "chipspark,popmetal-rk3288", "rockchip,rk3288"; @@ -110,6 +114,14 @@ Rockchip platforms device tree bindings - Rockchip RK3229 Evaluation board: - compatible = "rockchip,rk3229-evb", "rockchip,rk3229"; +- Rockchip RK3288 Fennec board: + Required root node properties: + - compatible = "rockchip,rk3288-fennec", "rockchip,rk3288"; + - Rockchip RK3399 evb: Required root node properties: - compatible = "rockchip,rk3399-evb", "rockchip,rk3399"; + +- Tronsmart Orion R68 Meta + Required root node properties: + - compatible = "tronsmart,orion-r68-meta", "rockchip,rk3368"; diff --git a/Documentation/devicetree/bindings/arm/samsung/pmu.txt b/Documentation/devicetree/bindings/arm/samsung/pmu.txt index 2d6356d8daf4..bf5fc59a6938 100644 --- a/Documentation/devicetree/bindings/arm/samsung/pmu.txt +++ b/Documentation/devicetree/bindings/arm/samsung/pmu.txt @@ -10,6 +10,7 @@ Properties: - "samsung,exynos5260-pmu" - for Exynos5260 SoC. - "samsung,exynos5410-pmu" - for Exynos5410 SoC, - "samsung,exynos5420-pmu" - for Exynos5420 SoC. + - "samsung,exynos5433-pmu" - for Exynos5433 SoC. - "samsung,exynos7-pmu" - for Exynos7 SoC. second value must be always "syscon". diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 1df32d339da5..2f0b7169f132 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -49,6 +49,8 @@ Boards: compatible = "renesas,genmai", "renesas,r7s72100" - Gose compatible = "renesas,gose", "renesas,r8a7793" + - H3ULCB (RTP0RC7795SKB00010S) + compatible = "renesas,h3ulcb", "renesas,r8a7795"; - Henninger compatible = "renesas,henninger", "renesas,r8a7791" - Koelsch (RTP0RC7791SEB00010S) @@ -63,9 +65,13 @@ Boards: compatible = "renesas,marzen", "renesas,r8a7779" - Porter (M2-LCDP) compatible = "renesas,porter", "renesas,r8a7791" + - RSKRZA1 (YR0K77210C000BE) + compatible = "renesas,rskrza1", "renesas,r7s72100" - Salvator-X (RTP0RC7795SIPB0010S) compatible = "renesas,salvator-x", "renesas,r8a7795"; - Salvator-X compatible = "renesas,salvator-x", "renesas,r8a7796"; - SILK (RTP0RC7794LCB00011S) compatible = "renesas,silk", "renesas,r8a7794" + - Wheat + compatible = "renesas,wheat", "renesas,r8a7792" diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt index 7e79fcc36b0d..3975d0a0e4c2 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.txt +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -14,3 +14,4 @@ using one of the following compatible strings: allwinner,sun8i-a83t allwinner,sun8i-h3 allwinner,sun9i-a80 + nextthing,gr8 diff --git a/Documentation/devicetree/bindings/arm/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt index 842298894cf0..33797acad846 100644 --- a/Documentation/devicetree/bindings/arm/technologic.txt +++ b/Documentation/devicetree/bindings/arm/technologic.txt @@ -4,3 +4,9 @@ Technologic Systems Platforms Device Tree Bindings TS-4800 board Required root node properties: - compatible = "technologic,imx51-ts4800", "fsl,imx51"; + +TS-4900 is a System-on-Module based on the Freescale i.MX6 System-on-Chip. +It can be mounted on a carrier board providing additional peripheral connectors. +Required root node properties: + - compatible = "technologic,imx6dl-ts4900", "fsl,imx6dl" + - compatible = "technologic,imx6q-ts4900", "fsl,imx6q" diff --git a/Documentation/devicetree/bindings/arm/zte.txt b/Documentation/devicetree/bindings/arm/zte.txt index 3ff5c9e85c1c..83369785d29c 100644 --- a/Documentation/devicetree/bindings/arm/zte.txt +++ b/Documentation/devicetree/bindings/arm/zte.txt @@ -13,3 +13,27 @@ Low power management required properties: Bus matrix required properties: - compatible = "zte,zx-bus-matrix" + + +--------------------------------------- +- ZX296718 SoC: + Required root node properties: + - compatible = "zte,zx296718" + +ZX296718 EVB board: + - "zte,zx296718-evb" + +System management required properties: + - compatible = "zte,zx296718-aon-sysctrl" + - compatible = "zte,zx296718-sysctrl" + +Example: +aon_sysctrl: aon-sysctrl@116000 { + compatible = "zte,zx296718-aon-sysctrl", "syscon"; + reg = <0x116000 0x1000>; +}; + +sysctrl: sysctrl@1463000 { + compatible = "zte,zx296718-sysctrl", "syscon"; + reg = <0x1463000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt b/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt new file mode 100644 index 000000000000..b69bb68992fd --- /dev/null +++ b/Documentation/devicetree/bindings/auxdisplay/img-ascii-lcd.txt @@ -0,0 +1,17 @@ +Binding for ASCII LCD displays on Imagination Technologies boards + +Required properties: +- compatible : should be one of: + "img,boston-lcd" + "mti,malta-lcd" + "mti,sead3-lcd" + +Required properties for "img,boston-lcd": +- reg : memory region locating the device registers + +Required properties for "mti,malta-lcd" or "mti,sead3-lcd": +- regmap: phandle of the system controller containing the LCD registers +- offset: offset in bytes to the LCD registers within the system controller + +The layout of the registers & properties of the display are determined +from the compatible string, making this binding somewhat trivial. diff --git a/Documentation/devicetree/bindings/bus/qcom,ebi2.txt b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt new file mode 100644 index 000000000000..920681f552db --- /dev/null +++ b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt @@ -0,0 +1,138 @@ +Qualcomm External Bus Interface 2 (EBI2) + +The EBI2 contains two peripheral blocks: XMEM and LCDC. The XMEM handles any +external memory (such as NAND or other memory-mapped peripherals) whereas +LCDC handles LCD displays. + +As it says it connects devices to an external bus interface, meaning address +lines (up to 9 address lines so can only address 1KiB external memory space), +data lines (16 bits), OE (output enable), ADV (address valid, used on some +NOR flash memories), WE (write enable). This on top of 6 different chip selects +(CS0 thru CS5) so that in theory 6 different devices can be connected. + +Apparently this bus is clocked at 64MHz. It has dedicated pins on the package +and the bus can only come out on these pins, however if some of the pins are +unused they can be left unconnected or remuxed to be used as GPIO or in some +cases other orthogonal functions as well. + +Also CS1 and CS2 has -A and -B signals. Why they have that is unclear to me. + +The chip selects have the following memory range assignments. This region of +memory is referred to as "Chip Peripheral SS FPB0" and is 168MB big. + +Chip Select Physical address base +CS0 GPIO134 0x1a800000-0x1b000000 (8MB) +CS1 GPIO39 (A) / GPIO123 (B) 0x1b000000-0x1b800000 (8MB) +CS2 GPIO40 (A) / GPIO124 (B) 0x1b800000-0x1c000000 (8MB) +CS3 GPIO133 0x1d000000-0x25000000 (128 MB) +CS4 GPIO132 0x1c800000-0x1d000000 (8MB) +CS5 GPIO131 0x1c000000-0x1c800000 (8MB) + +The APQ8060 Qualcomm Application Processor User Guide, 80-N7150-14 Rev. A, +August 6, 2012 contains some incomplete documentation of the EBI2. + +FIXME: the manual mentions "write precharge cycles" and "precharge cycles". +We have not been able to figure out which bit fields these correspond to +in the hardware, or what valid values exist. The current hypothesis is that +this is something just used on the FAST chip selects and that the SLOW +chip selects are understood fully. There is also a "byte device enable" +flag somewhere for 8bit memories. + +FIXME: The chipselects have SLOW and FAST configuration registers. It's a bit +unclear what this means, if they are mutually exclusive or can be used +together, or if some chip selects are hardwired to be FAST and others are SLOW +by design. + +The XMEM registers are totally undocumented but could be partially decoded +because the Cypress AN49576 Antioch Westbridge apparently has suspiciously +similar register layout, see: http://www.cypress.com/file/105771/download + +Required properties: +- compatible: should be one of: + "qcom,msm8660-ebi2" + "qcom,apq8060-ebi2" +- #address-cells: shoule be <2>: the first cell is the chipselect, + the second cell is the offset inside the memory range +- #size-cells: should be <1> +- ranges: should be set to: + ranges = <0 0x0 0x1a800000 0x00800000>, + <1 0x0 0x1b000000 0x00800000>, + <2 0x0 0x1b800000 0x00800000>, + <3 0x0 0x1d000000 0x08000000>, + <4 0x0 0x1c800000 0x00800000>, + <5 0x0 0x1c000000 0x00800000>; +- reg: two ranges of registers: EBI2 config and XMEM config areas +- reg-names: should be "ebi2", "xmem" +- clocks: two clocks, EBI_2X and EBI +- clock-names: shoule be "ebi2x", "ebi2" + +Optional subnodes: +- Nodes inside the EBI2 will be considered device nodes. + +The following optional properties are properties that can be tagged onto +any device subnode. We are assuming that there can be only ONE device per +chipselect subnode, else the properties will become ambigous. + +Optional properties arrays for SLOW chip selects: +- qcom,xmem-recovery-cycles: recovery cycles is the time the memory continues to + drive the data bus after OE is de-asserted, in order to avoid contention on + the data bus. They are inserted when reading one CS and switching to another + CS or read followed by write on the same CS. Valid values 0 thru 15. Minimum + value is actually 1, so a value of 0 will still yield 1 recovery cycle. +- qcom,xmem-write-hold-cycles: write hold cycles, these are extra cycles + inserted after every write minimum 1. The data out is driven from the time + WE is asserted until CS is asserted. With a hold of 1 (value = 0), the CS + stays active for 1 extra cycle etc. Valid values 0 thru 15. +- qcom,xmem-write-delta-cycles: initial latency for write cycles inserted for + the first write to a page or burst memory. Valid values 0 thru 255. +- qcom,xmem-read-delta-cycles: initial latency for read cycles inserted for the + first read to a page or burst memory. Valid values 0 thru 255. +- qcom,xmem-write-wait-cycles: number of wait cycles for every write access, 0=1 + cycle. Valid values 0 thru 15. +- qcom,xmem-read-wait-cycles: number of wait cycles for every read access, 0=1 + cycle. Valid values 0 thru 15. + +Optional properties arrays for FAST chip selects: +- qcom,xmem-address-hold-enable: this is a boolean property stating that we + shall hold the address for an extra cycle to meet hold time requirements + with ADV assertion. +- qcom,xmem-adv-to-oe-recovery-cycles: the number of cycles elapsed before an OE + assertion, with respect to the cycle where ADV (address valid) is asserted. + 2 means 2 cycles between ADV and OE. Valid values 0, 1, 2 or 3. +- qcom,xmem-read-hold-cycles: the length in cycles of the first segment of a + read transfer. For a single read trandfer this will be the time from CS + assertion to OE assertion. Valid values 0 thru 15. + + +Example: + +ebi2@1a100000 { + compatible = "qcom,apq8060-ebi2"; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0 0x0 0x1a800000 0x00800000>, + <1 0x0 0x1b000000 0x00800000>, + <2 0x0 0x1b800000 0x00800000>, + <3 0x0 0x1d000000 0x08000000>, + <4 0x0 0x1c800000 0x00800000>, + <5 0x0 0x1c000000 0x00800000>; + reg = <0x1a100000 0x1000>, <0x1a110000 0x1000>; + reg-names = "ebi2", "xmem"; + clocks = <&gcc EBI2_2X_CLK>, <&gcc EBI2_CLK>; + clock-names = "ebi2x", "ebi2"; + /* Make sure to set up the pin control for the EBI2 */ + pinctrl-names = "default"; + pinctrl-0 = <&foo_ebi2_pins>; + + foo-ebi2@2,0 { + compatible = "foo"; + reg = <2 0x0 0x100>; + (...) + qcom,xmem-recovery-cycles = <0>; + qcom,xmem-write-hold-cycles = <3>; + qcom,xmem-write-delta-cycles = <31>; + qcom,xmem-read-delta-cycles = <28>; + qcom,xmem-write-wait-cycles = <9>; + qcom,xmem-read-wait-cycles = <9>; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt new file mode 100644 index 000000000000..a55d31b48d6e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt @@ -0,0 +1,45 @@ +* Amlogic GXBB AO Clock and Reset Unit + +The Amlogic GXBB AO clock controller generates and supplies clock to various +controllers within the Always-On part of the SoC. + +Required Properties: + +- compatible: should be "amlogic,gxbb-aoclkc" +- reg: physical base address of the clock controller and length of memory + mapped region. + +- #clock-cells: should be 1. + +Each clock is assigned an identifier and client nodes can use this identifier +to specify the clock which they consume. All available clocks are defined as +preprocessor macros in the dt-bindings/clock/gxbb-aoclkc.h header and can be +used in device tree sources. + +- #reset-cells: should be 1. + +Each reset is assigned an identifier and client nodes can use this identifier +to specify the reset which they consume. All available resets are defined as +preprocessor macros in the dt-bindings/reset/gxbb-aoclkc.h header and can be +used in device tree sources. + +Example: AO Clock controller node: + + clkc_AO: clock-controller@040 { + compatible = "amlogic,gxbb-aoclkc"; + reg = <0x0 0x040 0x0 0x4>; + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock and reset generated + by the clock controller: + + uart_AO: serial@4c0 { + compatible = "amlogic,meson-uart"; + reg = <0x4c0 0x14>; + interrupts = <0 90 1>; + clocks = <&clkc_AO CLKID_AO_UART1>; + resets = <&clkc_AO RESET_AO_UART1>; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt b/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt index 8b7177cecb36..27468119fd94 100644 --- a/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt +++ b/Documentation/devicetree/bindings/clock/arm-syscon-icst.txt @@ -5,20 +5,50 @@ Technology (IDT). ARM integrated these oscillators deeply into their reference designs by adding special control registers that manage such oscillators to their system controllers. -The ARM system controller contains logic to serialize and initialize +The various ARM system controllers contain logic to serialize and initialize an ICST clock request after a write to the 32 bit register at an offset into the system controller. Furthermore, to even be able to alter one of these frequencies, the system controller must first be unlocked by writing a special token to another offset in the system controller. +Some ARM hardware contain special versions of the serial interface that only +connects the low 8 bits of the VDW (missing one bit), hardwires RDW to +different values and sometimes also hardwire the output divider. They +therefore have special compatible strings as per this table (the OD value is +the value on the pins, not the resulting output divider): + +Hardware variant: RDW OD VDW + +Integrator/AP 22 1 Bit 8 0, rest variable +integratorap-cm + +Integrator/AP 46 3 Bit 8 0, rest variable +integratorap-sys + +Integrator/AP 22 or 1 17 or (33 or 25 MHz) +integratorap-pci 14 1 14 + +Integrator/CP 22 variable Bit 8 0, rest variable +integratorcp-cm-core + +Integrator/CP 22 variable Bit 8 0, rest variable +integratorcp-cm-mem + The ICST oscillator must be provided inside a system controller node. Required properties: +- compatible: must be one of + "arm,syscon-icst525" + "arm,syscon-icst307" + "arm,syscon-icst525-integratorap-cm" + "arm,syscon-icst525-integratorap-sys" + "arm,syscon-icst525-integratorap-pci" + "arm,syscon-icst525-integratorcp-cm-core" + "arm,syscon-icst525-integratorcp-cm-mem" - lock-offset: the offset address into the system controller where the unlocking register is located - vco-offset: the offset address into the system controller where the ICST control register is located (even 32 bit address) -- compatible: must be one of "arm,syscon-icst525" or "arm,syscon-icst307" - #clock-cells: must be <0> - clocks: parent clock, since the ICST needs a parent clock to derive its frequency from, this attribute is compulsory. diff --git a/Documentation/devicetree/bindings/clock/armada3700-periph-clock.txt b/Documentation/devicetree/bindings/clock/armada3700-periph-clock.txt new file mode 100644 index 000000000000..1e3370ba189f --- /dev/null +++ b/Documentation/devicetree/bindings/clock/armada3700-periph-clock.txt @@ -0,0 +1,70 @@ +* Peripheral Clock bindings for Marvell Armada 37xx SoCs + +Marvell Armada 37xx SoCs provide peripheral clocks which are +used as clock source for the peripheral of the SoC. + +There are two different blocks associated to north bridge and south +bridge. + +The peripheral clock consumer should specify the desired clock by +having the clock ID in its "clocks" phandle cell. + +The following is a list of provided IDs for Armada 370 North bridge clocks: +ID Clock name Description +----------------------------------- +0 mmc MMC controller +1 sata_host Sata Host +2 sec_at Security AT +3 sac_dap Security DAP +4 tsecm Security Engine +5 setm_tmx Serial Embedded Trace Module +6 avs Adaptive Voltage Scaling +7 sqf SPI +8 pwm PWM +9 i2c_2 I2C 2 +10 i2c_1 I2C 1 +11 ddr_phy DDR PHY +12 ddr_fclk DDR F clock +13 trace Trace +14 counter Counter +15 eip97 EIP 97 +16 cpu CPU + +The following is a list of provided IDs for Armada 370 South bridge clocks: +ID Clock name Description +----------------------------------- +0 gbe-50 50 MHz parent clock for Gigabit Ethernet +1 gbe-core parent clock for Gigabit Ethernet core +2 gbe-125 125 MHz parent clock for Gigabit Ethernet +3 gbe1-50 50 MHz clock for Gigabit Ethernet port 1 +4 gbe0-50 50 MHz clock for Gigabit Ethernet port 0 +5 gbe1-125 125 MHz clock for Gigabit Ethernet port 1 +6 gbe0-125 125 MHz clock for Gigabit Ethernet port 0 +7 gbe1-core Gigabit Ethernet core port 1 +8 gbe0-core Gigabit Ethernet core port 0 +9 gbe-bm Gigabit Ethernet Buffer Manager +10 sdio SDIO +11 usb32-sub2-sys USB 2 clock +12 usb32-ss-sys USB 3 clock + +Required properties: + +- compatible : shall be "marvell,armada-3700-periph-clock-nb" for the + north bridge block, or + "marvell,armada-3700-periph-clock-sb" for the south bridge block +- reg : must be the register address of North/South Bridge Clock register +- #clock-cells : from common clock binding; shall be set to 1 + +- clocks : list of the parent clock phandle in the following order: + TBG-A P, TBG-B P, TBG-A S, TBG-B S and finally the xtal clock. + + +Example: + +nb_perih_clk: nb-periph-clk@13000{ + compatible = "marvell,armada-3700-periph-clock-nb"; + reg = <0x13000 0x1000>; + clocks = <&tbg 0>, <&tbg 1>, <&tbg 2>, + <&tbg 3>, <&xtalclk>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt b/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt new file mode 100644 index 000000000000..0ba1d83ff363 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/armada3700-tbg-clock.txt @@ -0,0 +1,27 @@ +* Time Base Generator Clock bindings for Marvell Armada 37xx SoCs + +Marvell Armada 37xx SoCs provde Time Base Generator clocks which are +used as parent clocks for the peripheral clocks. + +The TBG clock consumer should specify the desired clock by having the +clock ID in its "clocks" phandle cell. + +The following is a list of provided IDs and clock names on Armada 3700: + 0 = TBG A P + 1 = TBG B P + 2 = TBG A S + 3 = TBG B S + +Required properties: +- compatible : shall be "marvell,armada-3700-tbg-clock" +- reg : must be the register address of North Bridge PLL register +- #clock-cells : from common clock binding; shall be set to 1 + +Example: + +tbg: tbg@13200 { + compatible = "marvell,armada-3700-tbg-clock"; + reg = <0x13200 0x1000>; + clocks = <&xtalclk>; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt b/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt new file mode 100644 index 000000000000..a88f1f05fbd6 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/armada3700-xtal-clock.txt @@ -0,0 +1,28 @@ +* Xtal Clock bindings for Marvell Armada 37xx SoCs + +Marvell Armada 37xx SoCs allow to determine the xtal clock frequencies by +reading the gpio latch register. + +This node must be a subnode of the node exposing the register address +of the GPIO block where the gpio latch is located. + +Required properties: +- compatible : shall be one of the following: + "marvell,armada-3700-xtal-clock" +- #clock-cells : from common clock binding; shall be set to 0 + +Optional properties: +- clock-output-names : from common clock binding; allows overwrite default clock + output names ("xtal") + +Example: +gpio1: gpio@13800 { + compatible = "marvell,armada-3700-gpio", "syscon", "simple-mfd"; + reg = <0x13800 0x1000>; + + xtalclk: xtal-clk { + compatible = "marvell,armada-3700-xtal-clock"; + clock-output-names = "xtal"; + #clock-cells = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index 181bc8ac4e3a..5f3ad65daf69 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -6,7 +6,8 @@ This binding uses the common clock binding[1]. Required properties: - compatible : shall be one of the following: - "atmel,at91sam9x5-sckc": + "atmel,at91sam9x5-sckc" or + "atmel,sama5d4-sckc": at91 SCKC (Slow Clock Controller) This node contains the slow clock definitions. diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm53573-ilp.txt b/Documentation/devicetree/bindings/clock/brcm,bcm53573-ilp.txt new file mode 100644 index 000000000000..2ebb107331dd --- /dev/null +++ b/Documentation/devicetree/bindings/clock/brcm,bcm53573-ilp.txt @@ -0,0 +1,36 @@ +Broadcom BCM53573 ILP clock +=========================== + +This binding uses the common clock binding: + Documentation/devicetree/bindings/clock/clock-bindings.txt + +This binding is used for ILP clock (sometimes referred as "slow clock") +on Broadcom BCM53573 devices using Cortex-A7 CPU. + +ILP's rate has to be calculated on runtime and it depends on ALP clock +which has to be referenced. + +This clock is part of PMU (Power Management Unit), a Broadcom's device +handing power-related aspects. Its node must be sub-node of the PMU +device. + +Required properties: +- compatible: "brcm,bcm53573-ilp" +- clocks: has to reference an ALP clock +- #clock-cells: should be <0> +- clock-output-names: from common clock bindings, should contain clock + name + +Example: + +pmu@18012000 { + compatible = "simple-mfd", "syscon"; + reg = <0x18012000 0x00001000>; + + ilp { + compatible = "brcm,bcm53573-ilp"; + clocks = <&alp>; + #clock-cells = <0>; + clock-output-names = "ilp"; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt b/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt index 180e8835569e..0c3d6015868d 100644 --- a/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt +++ b/Documentation/devicetree/bindings/clock/clk-exynos-audss.txt @@ -10,6 +10,8 @@ Required Properties: - "samsung,exynos4210-audss-clock" - controller compatible with all Exynos4 SoCs. - "samsung,exynos5250-audss-clock" - controller compatible with Exynos5250 SoCs. + - "samsung,exynos5410-audss-clock" - controller compatible with Exynos5410 + SoCs. - "samsung,exynos5420-audss-clock" - controller compatible with Exynos5420 SoCs. - reg: physical base address and length of the controller's register set. @@ -91,5 +93,5 @@ i2s0: i2s@03830000 { <&clock_audss EXYNOS_MOUT_AUDSS>, <&clock_audss EXYNOS_MOUT_I2S>; clock-names = "iis", "i2s_opclk0", "i2s_opclk1", - "mout_audss", "mout_i2s"; + "mout_audss", "mout_i2s"; }; diff --git a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt index aeab635b07b5..4527de3ea205 100644 --- a/Documentation/devicetree/bindings/clock/exynos5410-clock.txt +++ b/Documentation/devicetree/bindings/clock/exynos5410-clock.txt @@ -12,24 +12,29 @@ Required Properties: - #clock-cells: should be 1. +- clocks: should contain an entry specifying the root clock from external + oscillator supplied through XXTI or XusbXTI pin. This clock should be + defined using standard clock bindings with "fin_pll" clock-output-name. + That clock is being passed internally to the 9 PLLs. + All available clocks are defined as preprocessor macros in dt-bindings/clock/exynos5410.h header and can be used in device tree sources. -External clock: - -There is clock that is generated outside the SoC. It -is expected that it is defined using standard clock bindings -with following clock-output-name: - - - "fin_pll" - PLL input clock from XXTI - Example 1: An example of a clock controller node is listed below. + fin_pll: xxti { + compatible = "fixed-clock"; + clock-frequency = <24000000>; + clock-output-names = "fin_pll"; + #clock-cells = <0>; + }; + clock: clock-controller@0x10010000 { compatible = "samsung,exynos5410-clock"; reg = <0x10010000 0x30000>; #clock-cells = <1>; + clocks = <&fin_pll>; }; Example 2: UART controller node that consumes the clock generated by the clock diff --git a/Documentation/devicetree/bindings/clock/maxim,max77686.txt b/Documentation/devicetree/bindings/clock/maxim,max77686.txt index 9c40739a661a..8398a3a5e106 100644 --- a/Documentation/devicetree/bindings/clock/maxim,max77686.txt +++ b/Documentation/devicetree/bindings/clock/maxim,max77686.txt @@ -1,10 +1,24 @@ -Binding for Maxim MAX77686 32k clock generator block +Binding for Maxim MAX77686/MAX77802/MAX77620 32k clock generator block -This is a part of device tree bindings of MAX77686 multi-function device. -More information can be found in bindings/mfd/max77686.txt file. +This is a part of device tree bindings of MAX77686/MAX77802/MAX77620 +multi-function device. More information can be found in MFD DT binding +doc as follows: + bindings/mfd/max77686.txt for MAX77686 and + bindings/mfd/max77802.txt for MAX77802 and + bindings/mfd/max77620.txt for MAX77620. The MAX77686 contains three 32.768khz clock outputs that can be controlled -(gated/ungated) over I2C. +(gated/ungated) over I2C. Clocks are defined as preprocessor macros in +dt-bindings/clock/maxim,max77686.h. + + +The MAX77802 contains two 32.768khz clock outputs that can be controlled +(gated/ungated) over I2C. Clocks are defined as preprocessor macros in +dt-bindings/clock/maxim,max77802.h. + +The MAX77686 contains one 32.768khz clock outputs that can be controlled +(gated/ungated) over I2C. Clocks are defined as preprocessor macros in +dt-bindings/clock/maxim,max77620.h. Following properties should be presend in main device node of the MFD chip. @@ -17,30 +31,84 @@ Optional properties: Each clock is assigned an identifier and client nodes can use this identifier to specify the clock which they consume. Following indices are allowed: - - 0: 32khz_ap clock, - - 1: 32khz_cp clock, - - 2: 32khz_pmic clock. + - 0: 32khz_ap clock (max77686, max77802), 32khz_out0 (max77620) + - 1: 32khz_cp clock (max77686, max77802), + - 2: 32khz_pmic clock (max77686). + +Clocks are defined as preprocessor macros in above dt-binding header for +respective chips. + +Example: + +1. With MAX77686: + +#include +/* ... */ + + Node of the MFD chip + max77686: max77686@09 { + compatible = "maxim,max77686"; + interrupt-parent = <&wakeup_eint>; + interrupts = <26 0>; + reg = <0x09>; + #clock-cells = <1>; + + /* ... */ + }; + + Clock consumer node + + foo@0 { + compatible = "bar,foo"; + /* ... */ + clock-names = "my-clock"; + clocks = <&max77686 MAX77686_CLK_PMIC>; + }; + +2. With MAX77802: + +#include +/* ... */ + + Node of the MFD chip + max77802: max77802@09 { + compatible = "maxim,max77802"; + interrupt-parent = <&wakeup_eint>; + interrupts = <26 0>; + reg = <0x09>; + #clock-cells = <1>; + + /* ... */ + }; + + Clock consumer node + + foo@0 { + compatible = "bar,foo"; + /* ... */ + clock-names = "my-clock"; + clocks = <&max77802 MAX77802_CLK_32K_AP>; + }; -Clocks are defined as preprocessor macros in dt-bindings/clock/maxim,max77686.h -header and can be used in device tree sources. -Example: Node of the MFD chip +3. With MAX77620: - max77686: max77686@09 { - compatible = "maxim,max77686"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 0>; - reg = <0x09>; - #clock-cells = <1>; +#include +/* ... */ - /* ... */ - }; + Node of the MFD chip + max77620: max77620@3c { + compatible = "maxim,max77620"; + reg = <0x3c>; + #clock-cells = <1>; + /* ... */ + }; -Example: Clock consumer node + Clock consumer node - foo@0 { - compatible = "bar,foo"; - /* ... */ - clock-names = "my-clock"; - clocks = <&max77686 MAX77686_CLK_PMIC>; - }; + foo@0 { + compatible = "bar,foo"; + /* ... */ + clock-names = "my-clock"; + clocks = <&max77620 MAX77620_CLK_32K_OUT0>; + }; diff --git a/Documentation/devicetree/bindings/clock/maxim,max77802.txt b/Documentation/devicetree/bindings/clock/maxim,max77802.txt deleted file mode 100644 index c6dc7835f06c..000000000000 --- a/Documentation/devicetree/bindings/clock/maxim,max77802.txt +++ /dev/null @@ -1,44 +0,0 @@ -Binding for Maxim MAX77802 32k clock generator block - -This is a part of device tree bindings of MAX77802 multi-function device. -More information can be found in bindings/mfd/max77802.txt file. - -The MAX77802 contains two 32.768khz clock outputs that can be controlled -(gated/ungated) over I2C. - -Following properties should be present in main device node of the MFD chip. - -Required properties: -- #clock-cells: From common clock binding; shall be set to 1. - -Optional properties: -- clock-output-names: From common clock binding. - -Each clock is assigned an identifier and client nodes can use this identifier -to specify the clock which they consume. Following indices are allowed: - - 0: 32khz_ap clock, - - 1: 32khz_cp clock. - -Clocks are defined as preprocessor macros in dt-bindings/clock/maxim,max77802.h -header and can be used in device tree sources. - -Example: Node of the MFD chip - - max77802: max77802@09 { - compatible = "maxim,max77802"; - interrupt-parent = <&wakeup_eint>; - interrupts = <26 0>; - reg = <0x09>; - #clock-cells = <1>; - - /* ... */ - }; - -Example: Clock consumer node - - foo@0 { - compatible = "bar,foo"; - /* ... */ - clock-names = "my-clock"; - clocks = <&max77802 MAX77802_CLK_32K_AP>; - }; diff --git a/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt index 670c2af3e931..eb985a633d59 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-core-clock.txt @@ -52,6 +52,7 @@ Required properties: "marvell,dove-core-clock" - for Dove SoC core clocks "marvell,kirkwood-core-clock" - for Kirkwood SoC (except mv88f6180) "marvell,mv88f6180-core-clock" - for Kirkwood MV88f6180 SoC + "marvell,mv88f5181-core-clock" - for Orion MV88F5181 SoC "marvell,mv88f5182-core-clock" - for Orion MV88F5182 SoC "marvell,mv88f5281-core-clock" - for Orion MV88F5281 SoC "marvell,mv88f6183-core-clock" - for Orion MV88F6183 SoC diff --git a/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt index 660e64912cce..cb8542d910b3 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt @@ -86,6 +86,8 @@ ID Clock Peripheral 7 pex3 PCIe 3 8 pex0 PCIe 0 9 usb3h0 USB3 Host 0 +10 usb3h1 USB3 Host 1 +15 sata0 SATA 0 17 sdio SDIO 22 xor0 XOR 0 28 xor1 XOR 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.txt b/Documentation/devicetree/bindings/clock/qcom,gcc.txt index 9a60fde32b02..3cf44217068e 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.txt @@ -15,6 +15,7 @@ Required properties : "qcom,gcc-msm8974pro" "qcom,gcc-msm8974pro-ac" "qcom,gcc-msm8996" + "qcom,gcc-mdm9615" - reg : shall contain base register location and length - #clock-cells : shall contain 1 @@ -22,6 +23,11 @@ Required properties : Optional properties : - #power-domain-cells : shall contain 1 +- Qualcomm TSENS (thermal sensor device) on some devices can +be part of GCC and hence the TSENS properties can also be +part of the GCC/clock-controller node. +For more details on the TSENS properties please refer +Documentation/devicetree/bindings/thermal/qcom-tsens.txt Example: clock-controller@900000 { @@ -31,3 +37,14 @@ Example: #reset-cells = <1>; #power-domain-cells = <1>; }; + +Example of GCC with TSENS properties: + clock-controller@900000 { + compatible = "qcom,gcc-apq8064"; + reg = <0x00900000 0x4000>; + nvmem-cells = <&tsens_calib>, <&tsens_backup>; + nvmem-cell-names = "calib", "calib_backup"; + #clock-cells = <1>; + #reset-cells = <1>; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,lcc.txt b/Documentation/devicetree/bindings/clock/qcom,lcc.txt index dd755be63a01..a3c78aa88038 100644 --- a/Documentation/devicetree/bindings/clock/qcom,lcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,lcc.txt @@ -7,6 +7,7 @@ Required properties : "qcom,lcc-msm8960" "qcom,lcc-apq8064" "qcom,lcc-ipq8064" + "qcom,lcc-mdm9615" - reg : shall contain base register location and length - #clock-cells : shall contain 1 diff --git a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt index fee3205cdff9..c209de6cfadb 100644 --- a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt +++ b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt @@ -1,16 +1,16 @@ STMicroelectronics STM32 Reset and Clock Controller =================================================== -The RCC IP is both a reset and a clock controller. This documentation only -describes the clock part. +The RCC IP is both a reset and a clock controller. -Please also refer to clock-bindings.txt in this directory for common clock -controller binding usage. +Please refer to clock-bindings.txt for common clock controller binding usage. +Please also refer to reset.txt for common reset controller binding usage. Required properties: - compatible: Should be "st,stm32f42xx-rcc" - reg: should be register base and length as documented in the datasheet +- #reset-cells: 1, see below - #clock-cells: 2, device nodes should specify the clock in their "clocks" property, containing a phandle to the clock device node, an index selecting between gated clocks and other clocks and an index specifying the clock to @@ -19,6 +19,7 @@ Required properties: Example: rcc: rcc@40023800 { + #reset-cells = <1>; #clock-cells = <2> compatible = "st,stm32f42xx-rcc", "st,stm32-rcc"; reg = <0x40023800 0x400>; @@ -35,16 +36,23 @@ from the first RCC clock enable register (RCC_AHB1ENR, address offset 0x30). It is calculated as: index = register_offset / 4 * 32 + bit_offset. Where bit_offset is the bit offset within the register (LSB is 0, MSB is 31). +To simplify the usage and to share bit definition with the reset and clock +drivers of the RCC IP, macros are available to generate the index in +human-readble format. + +For STM32F4 series, the macro are available here: + - include/dt-bindings/mfd/stm32f4-rcc.h + Example: /* Gated clock, AHB1 bit 0 (GPIOA) */ ... { - clocks = <&rcc 0 0> + clocks = <&rcc 0 STM32F4_AHB1_CLOCK(GPIOA)> }; /* Gated clock, AHB2 bit 4 (CRYP) */ ... { - clocks = <&rcc 0 36> + clocks = <&rcc 0 STM32F4_AHB2_CLOCK(CRYP)> }; Specifying other clocks @@ -61,5 +69,25 @@ Example: /* Misc clock, FCLK */ ... { - clocks = <&rcc 1 1> + clocks = <&rcc 1 STM32F4_APB1_CLOCK(TIM2)> + }; + + +Specifying softreset control of devices +======================================= + +Device nodes should specify the reset channel required in their "resets" +property, containing a phandle to the reset device node and an index specifying +which channel to use. +The index is the bit number within the RCC registers bank, starting from RCC +base address. +It is calculated as: index = register_offset / 4 * 32 + bit_offset. +Where bit_offset is the bit offset within the register. +For example, for CRC reset: + crc = AHB1RSTR_offset / 4 * 32 + CRCRST_bit_offset = 0x10 / 4 * 32 + 12 = 140 + +example: + + timer2 { + resets = <&rcc STM32F4_APB1_RESET(TIM2)>; }; diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-divmux.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-divmux.txt deleted file mode 100644 index 6247652044a0..000000000000 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-divmux.txt +++ /dev/null @@ -1,49 +0,0 @@ -Binding for a ST divider and multiplexer clock driver. - -This binding uses the common clock binding[1]. -Base address is located to the parent node. See clock binding[2] - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/clock/st/st,clkgen.txt - -Required properties: - -- compatible : shall be: - "st,clkgena-divmux-c65-hs", "st,clkgena-divmux" - "st,clkgena-divmux-c65-ls", "st,clkgena-divmux" - "st,clkgena-divmux-c32-odf0", "st,clkgena-divmux" - "st,clkgena-divmux-c32-odf1", "st,clkgena-divmux" - "st,clkgena-divmux-c32-odf2", "st,clkgena-divmux" - "st,clkgena-divmux-c32-odf3", "st,clkgena-divmux" - -- #clock-cells : From common clock binding; shall be set to 1. - -- clocks : From common clock binding - -- clock-output-names : From common clock binding. - -Example: - - clockgen-a@fd345000 { - reg = <0xfd345000 0xb50>; - - clk_m_a1_div1: clk-m-a1-div1 { - #clock-cells = <1>; - compatible = "st,clkgena-divmux-c32-odf1", - "st,clkgena-divmux"; - - clocks = <&clk_m_a1_osc_prediv>, - <&clk_m_a1_pll0 1>, /* PLL0 PHI1 */ - <&clk_m_a1_pll1 1>; /* PLL1 PHI1 */ - - clock-output-names = "clk-m-rx-icn-ts", - "clk-m-rx-icn-vdp-0", - "", /* unused */ - "clk-m-prv-t1-bus", - "clk-m-icn-reg-12", - "clk-m-icn-reg-10", - "", /* unused */ - "clk-m-icn-st231"; - }; - }; - diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-mux.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-mux.txt index f1fa91c68768..9a46cb1d7a04 100644 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-mux.txt +++ b/Documentation/devicetree/bindings/clock/st/st,clkgen-mux.txt @@ -10,14 +10,7 @@ This binding uses the common clock binding[1]. Required properties: - compatible : shall be: - "st,stih416-clkgenc-vcc-hd", "st,clkgen-mux" - "st,stih416-clkgenf-vcc-fvdp", "st,clkgen-mux" - "st,stih416-clkgenf-vcc-hva", "st,clkgen-mux" - "st,stih416-clkgenf-vcc-hd", "st,clkgen-mux" - "st,stih416-clkgenf-vcc-sd", "st,clkgen-mux" - "st,stih415-clkgen-a9-mux", "st,clkgen-mux" - "st,stih416-clkgen-a9-mux", "st,clkgen-mux" - "st,stih407-clkgen-a9-mux", "st,clkgen-mux" + "st,stih407-clkgen-a9-mux" - #clock-cells : from common clock binding; shall be set to 0. @@ -27,10 +20,13 @@ Required properties: Example: - clk_m_hva: clk-m-hva@fd690868 { + clk_m_a9: clk-m-a9@92b0000 { #clock-cells = <0>; - compatible = "st,stih416-clkgenf-vcc-hva", "st,clkgen-mux"; - reg = <0xfd690868 4>; + compatible = "st,stih407-clkgen-a9-mux"; + reg = <0x92b0000 0x10000>; - clocks = <&clockgen_f 1>, <&clk_m_a1_div0 3>; + clocks = <&clockgen_a9_pll 0>, + <&clockgen_a9_pll 0>, + <&clk_s_c0_flexgen 13>, + <&clk_m_a9_ext2f_div2>; }; diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt index 844b3a0976bf..f207053e0550 100644 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt +++ b/Documentation/devicetree/bindings/clock/st/st,clkgen-pll.txt @@ -9,24 +9,10 @@ Base address is located to the parent node. See clock binding[2] Required properties: - compatible : shall be: - "st,clkgena-prediv-c65", "st,clkgena-prediv" - "st,clkgena-prediv-c32", "st,clkgena-prediv" - - "st,clkgena-plls-c65" - "st,plls-c32-a1x-0", "st,clkgen-plls-c32" - "st,plls-c32-a1x-1", "st,clkgen-plls-c32" - "st,stih415-plls-c32-a9", "st,clkgen-plls-c32" - "st,stih415-plls-c32-ddr", "st,clkgen-plls-c32" - "st,stih416-plls-c32-a9", "st,clkgen-plls-c32" - "st,stih416-plls-c32-ddr", "st,clkgen-plls-c32" - "st,stih407-plls-c32-a0", "st,clkgen-plls-c32" - "st,stih407-plls-c32-a9", "st,clkgen-plls-c32" - "sst,plls-c32-cx_0", "st,clkgen-plls-c32" - "sst,plls-c32-cx_1", "st,clkgen-plls-c32" - "st,stih418-plls-c28-a9", "st,clkgen-plls-c32" - - "st,stih415-gpu-pll-c32", "st,clkgengpu-pll-c32" - "st,stih416-gpu-pll-c32", "st,clkgengpu-pll-c32" + "st,clkgen-pll0" + "st,clkgen-pll1" + "st,stih407-clkgen-plla9" + "st,stih418-clkgen-plla9" - #clock-cells : From common clock binding; shall be set to 1. @@ -36,17 +22,16 @@ Required properties: Example: - clockgen-a@fee62000 { - reg = <0xfee62000 0xb48>; + clockgen-a9@92b0000 { + compatible = "st,clkgen-c32"; + reg = <0x92b0000 0xffff>; - clk_s_a0_pll: clk-s-a0-pll { + clockgen_a9_pll: clockgen-a9-pll { #clock-cells = <1>; - compatible = "st,clkgena-plls-c65"; + compatible = "st,stih407-clkgen-plla9"; clocks = <&clk_sysin>; - clock-output-names = "clk-s-a0-pll0-hs", - "clk-s-a0-pll0-ls", - "clk-s-a0-pll1"; + clock-output-names = "clockgen-a9-pll-odf"; }; }; diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-prediv.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-prediv.txt deleted file mode 100644 index 604766c2619e..000000000000 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-prediv.txt +++ /dev/null @@ -1,36 +0,0 @@ -Binding for a ST pre-divider clock driver. - -This binding uses the common clock binding[1]. -Base address is located to the parent node. See clock binding[2] - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/clock/st/st,clkgen.txt - -Required properties: - -- compatible : shall be: - "st,clkgena-prediv-c65", "st,clkgena-prediv" - "st,clkgena-prediv-c32", "st,clkgena-prediv" - -- #clock-cells : From common clock binding; shall be set to 0. - -- clocks : From common clock binding - -- clock-output-names : From common clock binding. - -Example: - - clockgen-a@fd345000 { - reg = <0xfd345000 0xb50>; - - clk_m_a2_osc_prediv: clk-m-a2-osc-prediv { - #clock-cells = <0>; - compatible = "st,clkgena-prediv-c32", - "st,clkgena-prediv"; - - clocks = <&clk_sysin>; - - clock-output-names = "clk-m-a2-osc-prediv"; - }; - }; - diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen-vcc.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen-vcc.txt deleted file mode 100644 index 109b3eddcb17..000000000000 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen-vcc.txt +++ /dev/null @@ -1,61 +0,0 @@ -Binding for a type of STMicroelectronics clock crossbar (VCC). - -The crossbar can take up to 4 input clocks and control up to 16 -output clocks. Not all inputs or outputs have to be in use in a -particular instantiation. Each output can be individually enabled, -select any of the input clocks and apply a divide (by 1,2,4 or 8) to -that selected clock. - -This binding uses the common clock binding[1]. - -[1] Documentation/devicetree/bindings/clock/clock-bindings.txt - -Required properties: - -- compatible : shall be: - "st,stih416-clkgenc", "st,vcc" - "st,stih416-clkgenf", "st,vcc" - -- #clock-cells : from common clock binding; shall be set to 1. - -- reg : A Base address and length of the register set. - -- clocks : from common clock binding - -- clock-output-names : From common clock binding. The block has 16 - clock outputs but not all of them in a specific instance - have to be used in the SoC. If a clock name is left as - an empty string then no clock will be created for the - output associated with that string index. If fewer than - 16 strings are provided then no clocks will be created - for the remaining outputs. - -Example: - - clockgen_c_vcc: clockgen-c-vcc@0xfe8308ac { - #clock-cells = <1>; - compatible = "st,stih416-clkgenc", "st,clkgen-vcc"; - reg = <0xfe8308ac 12>; - - clocks = <&clk_s_vcc_hd>, - <&clockgen_c 1>, - <&clk_s_tmds_fromphy>, - <&clockgen_c 2>; - - clock-output-names = "clk-s-pix-hdmi", - "clk-s-pix-dvo", - "clk-s-out-dvo", - "clk-s-pix-hd", - "clk-s-hddac", - "clk-s-denc", - "clk-s-sddac", - "clk-s-pix-main", - "clk-s-pix-aux", - "clk-s-stfe-frc-0", - "clk-s-ref-mcru", - "clk-s-slave-mcru", - "clk-s-tmds-hdmi", - "clk-s-hdmi-reject-pll", - "clk-s-thsens"; - }; - diff --git a/Documentation/devicetree/bindings/clock/st/st,clkgen.txt b/Documentation/devicetree/bindings/clock/st/st,clkgen.txt index b18bf86f926f..c35390f60545 100644 --- a/Documentation/devicetree/bindings/clock/st/st,clkgen.txt +++ b/Documentation/devicetree/bindings/clock/st/st,clkgen.txt @@ -13,14 +13,6 @@ address is common of all subnode. ... }; - prediv_node { - ... - }; - - divmux_node { - ... - }; - quadfs_node { ... }; @@ -29,10 +21,6 @@ address is common of all subnode. ... }; - vcc_node { - ... - }; - flexgen_node { ... }; @@ -43,11 +31,8 @@ This binding uses the common clock binding[1]. Each subnode should use the binding described in [2]..[7] [1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] Documentation/devicetree/bindings/clock/st,clkgen-divmux.txt [3] Documentation/devicetree/bindings/clock/st,clkgen-mux.txt [4] Documentation/devicetree/bindings/clock/st,clkgen-pll.txt -[5] Documentation/devicetree/bindings/clock/st,clkgen-prediv.txt -[6] Documentation/devicetree/bindings/clock/st,vcc.txt [7] Documentation/devicetree/bindings/clock/st,quadfs.txt [8] Documentation/devicetree/bindings/clock/st,flexgen.txt @@ -57,44 +42,27 @@ Required properties: Example: - clockgen-a@fee62000 { - - reg = <0xfee62000 0xb48>; + clockgen-a@090ff000 { + compatible = "st,clkgen-c32"; + reg = <0x90ff000 0x1000>; clk_s_a0_pll: clk-s-a0-pll { #clock-cells = <1>; - compatible = "st,clkgena-plls-c65"; - - clocks = <&clk-sysin>; - - clock-output-names = "clk-s-a0-pll0-hs", - "clk-s-a0-pll0-ls", - "clk-s-a0-pll1"; - }; - - clk_s_a0_osc_prediv: clk-s-a0-osc-prediv { - #clock-cells = <0>; - compatible = "st,clkgena-prediv-c65", - "st,clkgena-prediv"; + compatible = "st,clkgen-pll0"; clocks = <&clk_sysin>; - clock-output-names = "clk-s-a0-osc-prediv"; + clock-output-names = "clk-s-a0-pll-ofd-0"; }; - clk_s_a0_hs: clk-s-a0-hs { + clk_s_a0_flexgen: clk-s-a0-flexgen { + compatible = "st,flexgen"; + #clock-cells = <1>; - compatible = "st,clkgena-divmux-c65-hs", - "st,clkgena-divmux"; - clocks = <&clk-s_a0_osc_prediv>, - <&clk-s_a0_pll 0>, /* pll0 hs */ - <&clk-s_a0_pll 2>; /* pll1 */ + clocks = <&clk_s_a0_pll 0>, + <&clk_sysin>; - clock-output-names = "clk-s-fdma-0", - "clk-s-fdma-1", - ""; /* clk-s-jit-sense */ - /* fourth output unused */ + clock-output-names = "clk-ic-lmi0"; }; }; - diff --git a/Documentation/devicetree/bindings/clock/st/st,flexgen.txt b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt index b7ee5c7e0f75..7ff77fc57dff 100644 --- a/Documentation/devicetree/bindings/clock/st/st,flexgen.txt +++ b/Documentation/devicetree/bindings/clock/st/st,flexgen.txt @@ -60,6 +60,10 @@ This binding uses the common clock binding[2]. Required properties: - compatible : shall be: "st,flexgen" + "st,flexgen-audio", "st,flexgen" (enable clock propagation on parent for + audio use case) + "st,flexgen-video", "st,flexgen" (enable clock propagation on parent + and activate synchronous mode) - #clock-cells : from common clock binding; shall be set to 1 (multiple clock outputs). diff --git a/Documentation/devicetree/bindings/clock/st/st,quadfs.txt b/Documentation/devicetree/bindings/clock/st/st,quadfs.txt index cedeb9cc8208..d93d49342e60 100644 --- a/Documentation/devicetree/bindings/clock/st/st,quadfs.txt +++ b/Documentation/devicetree/bindings/clock/st/st,quadfs.txt @@ -11,12 +11,8 @@ This binding uses the common clock binding[1]. Required properties: - compatible : shall be: - "st,stih416-quadfs216", "st,quadfs" - "st,stih416-quadfs432", "st,quadfs" - "st,stih416-quadfs660-E", "st,quadfs" - "st,stih416-quadfs660-F", "st,quadfs" - "st,stih407-quadfs660-C", "st,quadfs" - "st,stih407-quadfs660-D", "st,quadfs" + "st,quadfs" + "st,quadfs-pll" - #clock-cells : from common clock binding; shall be set to 1. @@ -35,14 +31,15 @@ Required properties: Example: - clockgen_e: clockgen-e@fd3208bc { - #clock-cells = <1>; - compatible = "st,stih416-quadfs660-E", "st,quadfs"; - reg = <0xfd3208bc 0xB0>; - - clocks = <&clk_sysin>; - clock-output-names = "clk-m-pix-mdtp-0", - "clk-m-pix-mdtp-1", - "clk-m-pix-mdtp-2", - "clk-m-mpelpc"; - }; + clk_s_c0_quadfs: clk-s-c0-quadfs@9103000 { + #clock-cells = <1>; + compatible = "st,quadfs-pll"; + reg = <0x9103000 0x1000>; + + clocks = <&clk_sysin>; + + clock-output-names = "clk-s-c0-fs0-ch0", + "clk-s-c0-fs0-ch1", + "clk-s-c0-fs0-ch2", + "clk-s-c0-fs0-ch3"; + }; diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt index cb91507ffb1e..3868458a5feb 100644 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt @@ -2,7 +2,10 @@ Allwinner Clock Control Unit Binding ------------------------------------ Required properties : -- compatible: must contain one of the following compatible: +- compatible: must contain one of the following compatibles: + - "allwinner,sun6i-a31-ccu" + - "allwinner,sun8i-a23-ccu" + - "allwinner,sun8i-a33-ccu" - "allwinner,sun8i-h3-ccu" - reg: Must contain the registers base address and length diff --git a/Documentation/devicetree/bindings/clock/uniphier-clock.txt b/Documentation/devicetree/bindings/clock/uniphier-clock.txt new file mode 100644 index 000000000000..c7179d3b5c33 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/uniphier-clock.txt @@ -0,0 +1,134 @@ +UniPhier clock controller + + +System clock +------------ + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-sld3-clock" - for sLD3 SoC. + "socionext,uniphier-ld4-clock" - for LD4 SoC. + "socionext,uniphier-pro4-clock" - for Pro4 SoC. + "socionext,uniphier-sld8-clock" - for sLD8 SoC. + "socionext,uniphier-pro5-clock" - for Pro5 SoC. + "socionext,uniphier-pxs2-clock" - for PXs2/LD6b SoC. + "socionext,uniphier-ld11-clock" - for LD11 SoC. + "socionext,uniphier-ld20-clock" - for LD20 SoC. +- #clock-cells: should be 1. + +Example: + + sysctrl@61840000 { + compatible = "socionext,uniphier-sysctrl", + "simple-mfd", "syscon"; + reg = <0x61840000 0x4000>; + + clock { + compatible = "socionext,uniphier-ld20-clock"; + #clock-cells = <1>; + }; + + other nodes ... + }; + +Provided clocks: + + 8: ST DMAC +12: GIO (Giga bit stream I/O) +14: USB3 ch0 host +15: USB3 ch1 host +16: USB3 ch0 PHY0 +17: USB3 ch0 PHY1 +20: USB3 ch1 PHY0 +21: USB3 ch1 PHY1 + + +Media I/O (MIO) clock +--------------------- + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-sld3-mio-clock" - for sLD3 SoC. + "socionext,uniphier-ld4-mio-clock" - for LD4 SoC. + "socionext,uniphier-pro4-mio-clock" - for Pro4 SoC. + "socionext,uniphier-sld8-mio-clock" - for sLD8 SoC. + "socionext,uniphier-pro5-mio-clock" - for Pro5 SoC. + "socionext,uniphier-pxs2-mio-clock" - for PXs2/LD6b SoC. + "socionext,uniphier-ld11-mio-clock" - for LD11 SoC. + "socionext,uniphier-ld20-mio-clock" - for LD20 SoC. +- #clock-cells: should be 1. + +Example: + + mioctrl@59810000 { + compatible = "socionext,uniphier-mioctrl", + "simple-mfd", "syscon"; + reg = <0x59810000 0x800>; + + clock { + compatible = "socionext,uniphier-ld20-mio-clock"; + #clock-cells = <1>; + }; + + other nodes ... + }; + +Provided clocks: + + 0: SD ch0 host + 1: eMMC host + 2: SD ch1 host + 7: MIO DMAC + 8: USB2 ch0 host + 9: USB2 ch1 host +10: USB2 ch2 host +11: USB2 ch3 host +12: USB2 ch0 PHY +13: USB2 ch1 PHY +14: USB2 ch2 PHY +15: USB2 ch3 PHY + + +Peripheral clock +---------------- + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-sld3-peri-clock" - for sLD3 SoC. + "socionext,uniphier-ld4-peri-clock" - for LD4 SoC. + "socionext,uniphier-pro4-peri-clock" - for Pro4 SoC. + "socionext,uniphier-sld8-peri-clock" - for sLD8 SoC. + "socionext,uniphier-pro5-peri-clock" - for Pro5 SoC. + "socionext,uniphier-pxs2-peri-clock" - for PXs2/LD6b SoC. + "socionext,uniphier-ld11-peri-clock" - for LD11 SoC. + "socionext,uniphier-ld20-peri-clock" - for LD20 SoC. +- #clock-cells: should be 1. + +Example: + + perictrl@59820000 { + compatible = "socionext,uniphier-perictrl", + "simple-mfd", "syscon"; + reg = <0x59820000 0x200>; + + clock { + compatible = "socionext,uniphier-ld20-peri-clock"; + #clock-cells = <1>; + }; + + other nodes ... + }; + +Provided clocks: + + 0: UART ch0 + 1: UART ch1 + 2: UART ch2 + 3: UART ch3 + 4: I2C ch0 + 5: I2C ch1 + 6: I2C ch2 + 7: I2C ch3 + 8: I2C ch4 + 9: I2C ch5 +10: I2C ch6 diff --git a/Documentation/devicetree/bindings/clock/xgene.txt b/Documentation/devicetree/bindings/clock/xgene.txt index 82f9638121db..8233e771711b 100644 --- a/Documentation/devicetree/bindings/clock/xgene.txt +++ b/Documentation/devicetree/bindings/clock/xgene.txt @@ -8,6 +8,7 @@ Required properties: - compatible : shall be one of the following: "apm,xgene-socpll-clock" - for a X-Gene SoC PLL clock "apm,xgene-pcppll-clock" - for a X-Gene PCP PLL clock + "apm,xgene-pmd-clock" - for a X-Gene PMD clock "apm,xgene-device-clock" - for a X-Gene device clock "apm,xgene-socpll-v2-clock" - for a X-Gene SoC PLL v2 clock "apm,xgene-pcppll-v2-clock" - for a X-Gene PCP PLL v2 clock @@ -22,6 +23,15 @@ Required properties for SoC or PCP PLL clocks: Optional properties for PLL clocks: - clock-names : shall be the name of the PLL. If missing, use the device name. +Required properties for PMD clocks: +- reg : shall be the physical register address for the pmd clock. +- clocks : shall be the input parent clock phandle for the clock. +- #clock-cells : shall be set to 1. +- clock-output-names : shall be the name of the clock referenced by derive + clock. +Optional properties for PLL clocks: +- clock-names : shall be the name of the clock. If missing, use the device name. + Required properties for device clocks: - reg : shall be a list of address and length pairs describing the CSR reset and/or the divider. Either may be omitted, but at least @@ -59,6 +69,14 @@ For example: type = <0>; }; + pmd0clk: pmd0clk@7e200200 { + compatible = "apm,xgene-pmd-clock"; + #clock-cells = <1>; + clocks = <&pmdpll 0>; + reg = <0x0 0x7e200200 0x0 0x10>; + clock-output-names = "pmd0clk"; + }; + socpll: socpll@17000120 { compatible = "apm,xgene-socpll-clock"; #clock-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/zx296718-clk.txt b/Documentation/devicetree/bindings/clock/zx296718-clk.txt new file mode 100644 index 000000000000..8c18b7b237bf --- /dev/null +++ b/Documentation/devicetree/bindings/clock/zx296718-clk.txt @@ -0,0 +1,35 @@ +Device Tree Clock bindings for ZTE zx296718 + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +Required properties: +- compatible : shall be one of the following: + "zte,zx296718-topcrm": + zx296718 top clock selection, divider and gating + + "zte,zx296718-lsp0crm" and + "zte,zx296718-lsp1crm": + zx296718 device level clock selection and gating + +- reg: Address and length of the register set + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. See include/dt-bindings/clock/zx296718-clock.h +for the full list of zx296718 clock IDs. + + +topclk: topcrm@1461000 { + compatible = "zte,zx296718-topcrm-clk"; + reg = <0x01461000 0x1000>; + #clock-cells = <1>; +}; + +usbphy0:usb-phy0 { + compatible = "zte,zx296718-usb-phy"; + #phy-cells = <0>; + clocks = <&topclk USB20_PHY_CLK>; + clock-names = "phyclk"; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt new file mode 100644 index 000000000000..f2233138eba9 --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/event/rockchip-dfi.txt @@ -0,0 +1,19 @@ + +* Rockchip rk3399 DFI device + +Required properties: +- compatible: Must be "rockchip,rk3399-dfi". +- reg: physical base address of each DFI and length of memory mapped region +- rockchip,pmu: phandle to the syscon managing the "pmu general register files" +- clocks: phandles for clock specified in "clock-names" property +- clock-names : the name of clock used by the DFI, must be "pclk_ddr_mon"; + +Example: + dfi: dfi@0xff630000 { + compatible = "rockchip,rk3399-dfi"; + reg = <0x00 0xff630000 0x00 0x4000>; + rockchip,pmu = <&pmugrf>; + clocks = <&cru PCLK_DDR_MON>; + clock-names = "pclk_ddr_mon"; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt new file mode 100644 index 000000000000..7a9e8603c150 --- /dev/null +++ b/Documentation/devicetree/bindings/devfreq/rk3399_dmc.txt @@ -0,0 +1,209 @@ +* Rockchip rk3399 DMC(Dynamic Memory Controller) device + +Required properties: +- compatible: Must be "rockchip,rk3399-dmc". +- devfreq-events: Node to get DDR loading, Refer to + Documentation/devicetree/bindings/devfreq/ + rockchip-dfi.txt +- interrupts: The interrupt number to the CPU. The interrupt + specifier format depends on the interrupt controller. + It should be DCF interrupts, when DDR dvfs finish, + it will happen. +- clocks: Phandles for clock specified in "clock-names" property +- clock-names : The name of clock used by the DFI, must be + "pclk_ddr_mon"; +- operating-points-v2: Refer to Documentation/devicetree/bindings/power/opp.txt + for details. +- center-supply: DMC supply node. +- status: Marks the node enabled/disabled. + +Following properties are ddr timing: + +- rockchip,dram_speed_bin : Value reference include/dt-bindings/clock/ddr.h, + it select ddr3 cl-trp-trcd type, default value + "DDR3_DEFAULT".it must selected according to + "Speed Bin" in ddr3 datasheet, DO NOT use + smaller "Speed Bin" than ddr3 exactly is. + +- rockchip,pd_idle : Config the PD_IDLE value, defined the power-down + idle period, memories are places into power-down + mode if bus is idle for PD_IDLE DFI clocks. + +- rockchip,sr_idle : Configure the SR_IDLE value, defined the + selfrefresh idle period, memories are places + into self-refresh mode if bus is idle for + SR_IDLE*1024 DFI clocks (DFI clocks freq is + half of dram's clocks), defaule value is "0". + +- rockchip,sr_mc_gate_idle : Defined the self-refresh with memory and + controller clock gating idle period, memories + are places into self-refresh mode and memory + controller clock arg gating if bus is idle for + sr_mc_gate_idle*1024 DFI clocks. + +- rockchip,srpd_lite_idle : Defined the self-refresh power down idle + period, memories are places into self-refresh + power down mode if bus is idle for + srpd_lite_idle*1024 DFI clocks. This parameter + is for LPDDR4 only. + +- rockchip,standby_idle : Defined the standby idle period, memories are + places into self-refresh than controller, pi, + phy and dram clock will gating if bus is idle + for standby_idle * DFI clocks. + +- rockchip,dram_dll_disb_freq : It's defined the DDR3 dll bypass frequency in + MHz, when ddr freq less than DRAM_DLL_DISB_FREQ, + ddr3 dll will bypssed note: if dll was bypassed, + the odt also stop working. + +- rockchip,phy_dll_disb_freq : Defined the PHY dll bypass frequency in + MHz (Mega Hz), when ddr freq less than + DRAM_DLL_DISB_FREQ, phy dll will bypssed. + note: phy dll and phy odt are independent. + +- rockchip,ddr3_odt_disb_freq : When dram type is DDR3, this parameter defined + the odt disable frequency in MHz (Mega Hz), + when ddr frequency less then ddr3_odt_disb_freq, + the odt on dram side and controller side are + both disabled. + +- rockchip,ddr3_drv : When dram type is DDR3, this parameter define + the dram side driver stength in ohm, default + value is DDR3_DS_40ohm. + +- rockchip,ddr3_odt : When dram type is DDR3, this parameter define + the dram side ODT stength in ohm, default value + is DDR3_ODT_120ohm. + +- rockchip,phy_ddr3_ca_drv : When dram type is DDR3, this parameter define + the phy side CA line(incluing command line, + address line and clock line) driver strength. + Default value is PHY_DRV_ODT_40. + +- rockchip,phy_ddr3_dq_drv : When dram type is DDR3, this parameter define + the phy side DQ line(incluing DQS/DQ/DM line) + driver strength. default value is PHY_DRV_ODT_40. + +- rockchip,phy_ddr3_odt : When dram type is DDR3, this parameter define the + phy side odt strength, default value is + PHY_DRV_ODT_240. + +- rockchip,lpddr3_odt_disb_freq : When dram type is LPDDR3, this parameter defined + then odt disable frequency in MHz (Mega Hz), + when ddr frequency less then ddr3_odt_disb_freq, + the odt on dram side and controller side are + both disabled. + +- rockchip,lpddr3_drv : When dram type is LPDDR3, this parameter define + the dram side driver stength in ohm, default + value is LP3_DS_34ohm. + +- rockchip,lpddr3_odt : When dram type is LPDDR3, this parameter define + the dram side ODT stength in ohm, default value + is LP3_ODT_240ohm. + +- rockchip,phy_lpddr3_ca_drv : When dram type is LPDDR3, this parameter define + the phy side CA line(incluing command line, + address line and clock line) driver strength. + default value is PHY_DRV_ODT_40. + +- rockchip,phy_lpddr3_dq_drv : When dram type is LPDDR3, this parameter define + the phy side DQ line(incluing DQS/DQ/DM line) + driver strength. default value is + PHY_DRV_ODT_40. + +- rockchip,phy_lpddr3_odt : When dram type is LPDDR3, this parameter define + the phy side odt strength, default value is + PHY_DRV_ODT_240. + +- rockchip,lpddr4_odt_disb_freq : When dram type is LPDDR4, this parameter + defined the odt disable frequency in + MHz (Mega Hz), when ddr frequency less then + ddr3_odt_disb_freq, the odt on dram side and + controller side are both disabled. + +- rockchip,lpddr4_drv : When dram type is LPDDR4, this parameter define + the dram side driver stength in ohm, default + value is LP4_PDDS_60ohm. + +- rockchip,lpddr4_dq_odt : When dram type is LPDDR4, this parameter define + the dram side ODT on dqs/dq line stength in ohm, + default value is LP4_DQ_ODT_40ohm. + +- rockchip,lpddr4_ca_odt : When dram type is LPDDR4, this parameter define + the dram side ODT on ca line stength in ohm, + default value is LP4_CA_ODT_40ohm. + +- rockchip,phy_lpddr4_ca_drv : When dram type is LPDDR4, this parameter define + the phy side CA line(incluing command address + line) driver strength. default value is + PHY_DRV_ODT_40. + +- rockchip,phy_lpddr4_ck_cs_drv : When dram type is LPDDR4, this parameter define + the phy side clock line and cs line driver + strength. default value is PHY_DRV_ODT_80. + +- rockchip,phy_lpddr4_dq_drv : When dram type is LPDDR4, this parameter define + the phy side DQ line(incluing DQS/DQ/DM line) + driver strength. default value is PHY_DRV_ODT_80. + +- rockchip,phy_lpddr4_odt : When dram type is LPDDR4, this parameter define + the phy side odt strength, default value is + PHY_DRV_ODT_60. + +Example: + dmc_opp_table: dmc_opp_table { + compatible = "operating-points-v2"; + + opp00 { + opp-hz = /bits/ 64 <300000000>; + opp-microvolt = <900000>; + }; + opp01 { + opp-hz = /bits/ 64 <666000000>; + opp-microvolt = <900000>; + }; + }; + + dmc: dmc { + compatible = "rockchip,rk3399-dmc"; + devfreq-events = <&dfi>; + interrupts = ; + clocks = <&cru SCLK_DDRCLK>; + clock-names = "dmc_clk"; + operating-points-v2 = <&dmc_opp_table>; + center-supply = <&ppvar_centerlogic>; + upthreshold = <15>; + downdifferential = <10>; + rockchip,ddr3_speed_bin = <21>; + rockchip,pd_idle = <0x40>; + rockchip,sr_idle = <0x2>; + rockchip,sr_mc_gate_idle = <0x3>; + rockchip,srpd_lite_idle = <0x4>; + rockchip,standby_idle = <0x2000>; + rockchip,dram_dll_dis_freq = <300>; + rockchip,phy_dll_dis_freq = <125>; + rockchip,auto_pd_dis_freq = <666>; + rockchip,ddr3_odt_dis_freq = <333>; + rockchip,ddr3_drv = ; + rockchip,ddr3_odt = ; + rockchip,phy_ddr3_ca_drv = ; + rockchip,phy_ddr3_dq_drv = ; + rockchip,phy_ddr3_odt = ; + rockchip,lpddr3_odt_dis_freq = <333>; + rockchip,lpddr3_drv = ; + rockchip,lpddr3_odt = ; + rockchip,phy_lpddr3_ca_drv = ; + rockchip,phy_lpddr3_dq_drv = ; + rockchip,phy_lpddr3_odt = ; + rockchip,lpddr4_odt_dis_freq = <333>; + rockchip,lpddr4_drv = ; + rockchip,lpddr4_dq_odt = ; + rockchip,lpddr4_ca_odt = ; + rockchip,phy_lpddr4_ca_drv = ; + rockchip,phy_lpddr4_ck_cs_drv = ; + rockchip,phy_lpddr4_dq_drv = ; + rockchip,phy_lpddr4_odt = ; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/dumb-vga-dac.txt b/Documentation/devicetree/bindings/display/bridge/dumb-vga-dac.txt new file mode 100644 index 000000000000..003bc246a270 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/dumb-vga-dac.txt @@ -0,0 +1,48 @@ +Dumb RGB to VGA DAC bridge +--------------------------- + +This binding is aimed for dumb RGB to VGA DAC based bridges that do not require +any configuration. + +Required properties: + +- compatible: Must be "dumb-vga-dac" + +Required nodes: + +This device has two video ports. Their connections are modelled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for RGB input +- Video port 1 for VGA output + + +Example +------- + +bridge { + compatible = "dumb-vga-dac"; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + vga_bridge_in: endpoint { + remote-endpoint = <&tcon0_out_vga>; + }; + }; + + port@1 { + reg = <1>; + + vga_bridge_out: endpoint { + remote-endpoint = <&vga_con_in>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/bridge/tda998x.txt b/Documentation/devicetree/bindings/display/bridge/tda998x.txt index e178e6b9f9ee..24cc2466185a 100644 --- a/Documentation/devicetree/bindings/display/bridge/tda998x.txt +++ b/Documentation/devicetree/bindings/display/bridge/tda998x.txt @@ -21,8 +21,19 @@ Optional properties: - video-ports: 24 bits value which defines how the video controller output is wired to the TDA998x input - default: <0x230145> + - audio-ports: array of 8-bit values, 2 values per one DAI[1]. + The first value defines the DAI type: TDA998x_SPDIF or TDA998x_I2S[2]. + The second value defines the tda998x AP_ENA reg content when the DAI + in question is used. The implementation allows one or two DAIs. If two + DAIs are defined, they must be of different type. + +[1] Documentation/sound/alsa/soc/DAI.txt +[2] include/dt-bindings/display/tda998x.h + Example: +#include + tda998x: hdmi-encoder { compatible = "nxp,tda998x"; reg = <0x70>; @@ -30,4 +41,11 @@ Example: interrupts = <27 2>; /* falling edge */ pinctrl-0 = <&pmx_camera>; pinctrl-names = "default"; + video-ports = <0x230145>; + + #sound-dai-cells = <2>; + /* DAI-format AP_ENA reg value */ + audio-ports = < TDA998x_SPDIF 0x04 + TDA998x_I2S 0x03>; + }; diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt index a2ec4c1c9382..6394ea9e3b9e 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_hdmi.txt @@ -9,7 +9,7 @@ Required properties: - reg: physical base address of the hdmi and length of memory mapped region. - interrupts: interrupt number to the cpu. -- hpd-gpio: following information about the hotplug gpio pin. +- hpd-gpios: following information about the hotplug gpio pin. a) phandle of the gpio controller node. b) pin number within the gpio controller. c) optional flags and pull up/down. @@ -56,7 +56,7 @@ Example: compatible = "samsung,exynos4212-hdmi"; reg = <0x14530000 0x100000>; interrupts = <0 95 0>; - hpd-gpio = <&gpx3 7 1>; + hpd-gpios = <&gpx3 7 1>; ddc = <&hdmi_ddc_node>; phy = <&hdmi_phy_node>; samsung,syscon-phandle = <&pmu_system_controller>; diff --git a/Documentation/devicetree/bindings/display/msm/hdmi.txt b/Documentation/devicetree/bindings/display/msm/hdmi.txt index b63f614e0c04..2ad578984fcf 100644 --- a/Documentation/devicetree/bindings/display/msm/hdmi.txt +++ b/Documentation/devicetree/bindings/display/msm/hdmi.txt @@ -14,17 +14,16 @@ Required properties: - power-domains: Should be <&mmcc MDSS_GDSC>. - clocks: device clocks See ../clocks/clock-bindings.txt for details. -- qcom,hdmi-tx-ddc-clk-gpio: ddc clk pin -- qcom,hdmi-tx-ddc-data-gpio: ddc data pin -- qcom,hdmi-tx-hpd-gpio: hpd pin - core-vdda-supply: phandle to supply regulator - hdmi-mux-supply: phandle to mux regulator - phys: the phandle for the HDMI PHY device - phy-names: the name of the corresponding PHY device Optional properties: -- qcom,hdmi-tx-mux-en-gpio: hdmi mux enable pin -- qcom,hdmi-tx-mux-sel-gpio: hdmi mux select pin +- hpd-gpios: hpd pin +- qcom,hdmi-tx-mux-en-gpios: hdmi mux enable pin +- qcom,hdmi-tx-mux-sel-gpios: hdmi mux select pin +- qcom,hdmi-tx-mux-lpm-gpios: hdmi mux lpm pin - power-domains: reference to the power domain(s), if available. - pinctrl-names: the pin control state names; should contain "default" - pinctrl-0: the default pinctrl state (active) diff --git a/Documentation/devicetree/bindings/display/panel/innolux,g101ice-l01.txt b/Documentation/devicetree/bindings/display/panel/innolux,g101ice-l01.txt new file mode 100644 index 000000000000..9e7590465227 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/innolux,g101ice-l01.txt @@ -0,0 +1,7 @@ +Innolux Corporation 10.1" G101ICE-L01 WXGA (1280x800) LVDS panel + +Required properties: +- compatible: should be "innolux,g101ice-l01" + +This binding is compatible with the simple-panel binding, which is specified +in simple-panel.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.txt b/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.txt new file mode 100644 index 000000000000..4989c91d505f --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/jdi,lt070me05000.txt @@ -0,0 +1,31 @@ +JDI model LT070ME05000 1200x1920 7" DSI Panel + +Required properties: +- compatible: should be "jdi,lt070me05000" +- vddp-supply: phandle of the regulator that provides the supply voltage + Power IC supply (3-5V) +- iovcc-supply: phandle of the regulator that provides the supply voltage + IOVCC , power supply for LCM (1.8V) +- enable-gpios: phandle of gpio for enable line + LED_EN, LED backlight enable, High active +- reset-gpios: phandle of gpio for reset line + This should be 8mA, gpio can be configured using mux, pinctrl, pinctrl-names + XRES, Reset, Low active +- dcdc-en-gpios: phandle of the gpio for power ic line + Power IC supply enable, High active + +Example: + + dsi0: qcom,mdss_dsi@4700000 { + panel@0 { + compatible = "jdi,lt070me05000"; + reg = <0>; + + vddp-supply = <&pm8921_l17>; + iovcc-supply = <&pm8921_lvs7>; + + enable-gpios = <&pm8921_gpio 36 GPIO_ACTIVE_HIGH>; + reset-gpios = <&tlmm_pinmux 54 GPIO_ACTIVE_LOW>; + dcdc-en-gpios = <&pm8921_gpio 23 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt new file mode 100644 index 000000000000..f5e3c6f2095a --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt @@ -0,0 +1,47 @@ +TPO TPG110 Panel +================ + +This binding builds on the DPI bindings, adding a few properties +as a superset of a DPI. See panel-dpi.txt for the required DPI +bindings. + +Required properties: +- compatible : "tpo,tpg110" +- grestb-gpios : panel reset GPIO +- scen-gpios : serial control enable GPIO +- scl-gpios : serial control clock line GPIO +- sda-gpios : serial control data line GPIO + +Required nodes: +- Video port for DPI input, see panel-dpi.txt +- Panel timing for DPI setup, see panel-dpi.txt + +Example +------- + +panel { + compatible = "tpo,tpg110", "panel-dpi"; + grestb-gpios = <&stmpe_gpio44 5 GPIO_ACTIVE_LOW>; + scen-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>; + scl-gpios = <&gpio0 5 GPIO_ACTIVE_HIGH>; + sda-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>; + backlight = <&bl>; + + port { + nomadik_clcd_panel: endpoint { + remote-endpoint = <&nomadik_clcd_pads>; + }; + }; + + panel-timing { + clock-frequency = <33200000>; + hactive = <800>; + hback-porch = <216>; + hfront-porch = <40>; + hsync-len = <1>; + vactive = <480>; + vback-porch = <35>; + vfront-porch = <10>; + vsync-len = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt index 5489b59e3d41..9eb3f0a2a078 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt @@ -6,8 +6,10 @@ buffer to an external LCD interface. Required properties: - compatible: value should be one of the following - "rockchip,rk3288-vop"; "rockchip,rk3036-vop"; + "rockchip,rk3288-vop"; + "rockchip,rk3399-vop-big"; + "rockchip,rk3399-vop-lit"; - interrupts: should contain a list of all VOP IP block interrupts in the order: VSYNC, LCD_SYSTEM. The interrupt specifier diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt index df8f4aeefe4c..b95696d748c7 100644 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt @@ -26,13 +26,14 @@ TCON The TCON acts as a timing controller for RGB, LVDS and TV interfaces. Required properties: - - compatible: value should be "allwinner,sun5i-a13-tcon". + - compatible: value must be either: + * allwinner,sun5i-a13-tcon + * allwinner,sun8i-a33-tcon - reg: base address and size of memory-mapped region - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the TCON. Three are needed: - 'ahb': the interface clocks - 'tcon-ch0': The clock driving the TCON channel 0 - - 'tcon-ch1': The clock driving the TCON channel 1 - resets: phandles to the reset controllers driving the encoder - "lcd": the reset line for the TCON channel 0 @@ -49,6 +50,33 @@ Required properties: second the block connected to the TCON channel 1 (usually the TV encoder) +On the A13, there is one more clock required: + - 'tcon-ch1': The clock driving the TCON channel 1 + +DRC +--- + +The DRC (Dynamic Range Controller), found in the latest Allwinner SoCs +(A31, A23, A33), allows to dynamically adjust pixel +brightness/contrast based on histogram measurements for LCD content +adaptive backlight control. + + +Required properties: + - compatible: value must be one of: + * allwinner,sun8i-a33-drc + - reg: base address and size of the memory-mapped region. + - interrupts: interrupt associated to this IP + - clocks: phandles to the clocks feeding the DRC + * ahb: the DRC interface clock + * mod: the DRC module clock + * ram: the DRC DRAM clock + - clock-names: the clock names mentioned above + - resets: phandles to the reset line driving the DRC + +- ports: A ports node with endpoint definitions as defined in + Documentation/devicetree/bindings/media/video-interfaces.txt. The + first port should be the input endpoints, the second one the outputs Display Engine Backend ---------------------- @@ -59,6 +87,7 @@ system. Required properties: - compatible: value must be one of: * allwinner,sun5i-a13-display-backend + * allwinner,sun8i-a33-display-backend - reg: base address and size of the memory-mapped region. - clocks: phandles to the clocks feeding the frontend and backend * ahb: the backend interface clock @@ -71,6 +100,14 @@ Required properties: Documentation/devicetree/bindings/media/video-interfaces.txt. The first port should be the input endpoints, the second one the output +On the A33, some additional properties are required: + - reg needs to have an additional region corresponding to the SAT + - reg-names need to be set, with "be" and "sat" + - clocks and clock-names need to have a phandle to the SAT bus + clocks, whose name will be "sat" + - resets and reset-names need to have a phandle to the SAT bus + resets, whose name will be "sat" + Display Engine Frontend ----------------------- @@ -80,6 +117,7 @@ deinterlacing and color space conversion. Required properties: - compatible: value must be one of: * allwinner,sun5i-a13-display-frontend + * allwinner,sun8i-a33-display-frontend - reg: base address and size of the memory-mapped region. - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the frontend and backend @@ -104,6 +142,7 @@ extra node. Required properties: - compatible: value must be one of: * allwinner,sun5i-a13-display-engine + * allwinner,sun8i-a33-display-engine - allwinner,pipelines: list of phandle to the display engine frontends available. diff --git a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt index 2136ee81e061..a83abd79c55c 100644 --- a/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/tilcdc.txt @@ -17,6 +17,18 @@ Optional properties: the lcd controller. - max-pixelclock: The maximum pixel clock that can be supported by the lcd controller in KHz. + - blue-and-red-wiring: Recognized values "straight" or "crossed". + This property deals with the LCDC revision 2 (found on AM335x) + color errata [1]. + - "straight" indicates normal wiring that supports RGB565, + BGR888, and XBGR8888 color formats. + - "crossed" indicates wiring that has blue and red wires + crossed. This setup supports BGR565, RGB888 and XRGB8888 + formats. + - If the property is not present or its value is not recognized + the legacy mode is assumed. This configuration supports RGB565, + RGB888 and XRGB8888 formats. However, depending on wiring, the red + and blue colors are swapped in either 16 or 24-bit color modes. Optional nodes: @@ -24,6 +36,18 @@ Optional nodes: binding follows Documentation/devicetree/bindings/graph.txt and suppors a single port with a single endpoint. + - See also Documentation/devicetree/bindings/display/tilcdc/panel.txt and + Documentation/devicetree/bindings/display/tilcdc/tfp410.txt for connecting + tfp410 DVI encoder or lcd panel to lcdc + +[1] There is an errata about AM335x color wiring. For 16-bit color mode + the wires work as they should (LCD_DATA[0:4] is for Blue[3:7]), + but for 24 bit color modes the wiring of blue and red components is + crossed and LCD_DATA[0:4] is for Red[3:7] and LCD_DATA[11:15] is + for Blue[3-7]. For more details see section 3.1.1 in AM335x + Silicon Errata: + http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=sprz360 + Example: fb: fb@4830e000 { @@ -33,6 +57,8 @@ Example: interrupts = <36>; ti,hwmods = "lcdc"; + blue-and-red-wiring = "crossed"; + port { lcdc_0: endpoint@0 { remote-endpoint = <&hdmi_0>; diff --git a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt index 175f0e44ed85..3c9a57a8443b 100644 --- a/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt +++ b/Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt @@ -8,6 +8,7 @@ Required properties: "fsl,imx51-sdma" "fsl,imx53-sdma" "fsl,imx6q-sdma" + "fsl,imx7d-sdma" The -to variants should be preferred since they allow to determine the correct ROM script addresses needed for the driver to work without additional firmware. diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index 5b902ac8d97e..5f2ce669789a 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -1,4 +1,4 @@ -* Renesas R-Car DMA Controller Device Tree bindings +* Renesas R-Car (RZ/G) DMA Controller Device Tree bindings Renesas R-Car Generation 2 SoCs have multiple multi-channel DMA controller instances named DMAC capable of serving multiple clients. Channels @@ -16,6 +16,8 @@ Required Properties: - compatible: "renesas,dmac-", "renesas,rcar-dmac" as fallback. Examples with soctypes are: + - "renesas,dmac-r8a7743" (RZ/G1M) + - "renesas,dmac-r8a7745" (RZ/G1E) - "renesas,dmac-r8a7790" (R-Car H2) - "renesas,dmac-r8a7791" (R-Car M2-W) - "renesas,dmac-r8a7792" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/dma/sun6i-dma.txt b/Documentation/devicetree/bindings/dma/sun6i-dma.txt index d13c136cef8c..6b267045f522 100644 --- a/Documentation/devicetree/bindings/dma/sun6i-dma.txt +++ b/Documentation/devicetree/bindings/dma/sun6i-dma.txt @@ -7,6 +7,7 @@ Required properties: - compatible: Must be one of "allwinner,sun6i-a31-dma" "allwinner,sun8i-a23-dma" + "allwinner,sun8i-a83t-dma" "allwinner,sun8i-h3-dma" - reg: Should contain the registers base address and length - interrupts: Should contain a reference to the interrupt used by this device diff --git a/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt new file mode 100644 index 000000000000..35383adb10f1 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/qcom,pm8941-misc.txt @@ -0,0 +1,41 @@ +Qualcomm's PM8941 USB ID Extcon device + +Some Qualcomm PMICs have a "misc" module that can be used to detect when +the USB ID pin has been pulled low or high. + +PROPERTIES + +- compatible: + Usage: required + Value type: + Definition: Should contain "qcom,pm8941-misc"; + +- reg: + Usage: required + Value type: + Definition: Should contain the offset to the misc address space + +- interrupts: + Usage: required + Value type: + Definition: Should contain the usb id interrupt + +- interrupt-names: + Usage: required + Value type: + Definition: Should contain the string "usb_id" for the usb id interrupt + +Example: + + pmic { + usb_id: misc@900 { + compatible = "qcom,pm8941-misc"; + reg = <0x900>; + interrupts = <0x0 0x9 0 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "usb_id"; + }; + } + + usb-controller { + extcon = <&usb_id>; + }; diff --git a/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt b/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt new file mode 100644 index 000000000000..c248cd44f727 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/meson/meson_sm.txt @@ -0,0 +1,15 @@ +* Amlogic Secure Monitor + +In the Amlogic SoCs the Secure Monitor code is used to provide access to the +NVMEM, enable JTAG, set USB boot, etc... + +Required properties for the secure monitor node: +- compatible: Should be "amlogic,meson-gxbb-sm" + +Example: + + firmware { + sm: secure-monitor { + compatible = "amlogic,meson-gxbb-sm"; + }; + }; diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt new file mode 100644 index 000000000000..e7853143fa42 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.txt @@ -0,0 +1,46 @@ +Bindings for the Broadcom's brcm,bcm6345-gpio memory-mapped GPIO controllers. + +These bindings can be used on any BCM63xx SoC. However, BCM6338 and BCM6345 +are the only ones which don't need a pinctrl driver. +BCM6338 have 8-bit data and dirout registers, where GPIO state can be read +and/or written, and the direction changed from input to output. +BCM6345 have 16-bit data and dirout registers, where GPIO state can be read +and/or written, and the direction changed from input to output. + +Required properties: + - compatible: should be "brcm,bcm6345-gpio" + - reg-names: must contain + "dat" - data register + "dirout" - direction (output) register + - reg: address + size pairs describing the GPIO register sets; + order must correspond with the order of entries in reg-names + - #gpio-cells: must be set to 2. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low + - gpio-controller: Marks the device node as a gpio controller. + +Optional properties: + - native-endian: use native endian memory. + +Examples: + - BCM6338: + gpio: gpio-controller@fffe0407 { + compatible = "brcm,bcm6345-gpio"; + reg-names = "dirout", "dat"; + reg = <0xfffe0407 1>, <0xfffe040f 1>; + + #gpio-cells = <2>; + gpio-controller; + }; + + - BCM6345: + gpio: gpio-controller@fffe0406 { + compatible = "brcm,bcm6345-gpio"; + reg-names = "dirout", "dat"; + reg = <0xfffe0406 2>, <0xfffe040a 2>; + native-endian; + + #gpio-cells = <2>; + gpio-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt new file mode 100644 index 000000000000..393bb2ed8a77 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-aspeed.txt @@ -0,0 +1,36 @@ +Aspeed GPIO controller Device Tree Bindings +------------------------------------------- + +Required properties: +- compatible : Either "aspeed,ast2400-gpio" or "aspeed,ast2500-gpio" + +- #gpio-cells : Should be two + - First cell is the GPIO line number + - Second cell is used to specify optional + parameters (unused) + +- reg : Address and length of the register set for the device +- gpio-controller : Marks the device node as a GPIO controller. +- interrupts : Interrupt specifier (see interrupt bindings for + details) +- interrupt-controller : Mark the GPIO controller as an interrupt-controller + +Optional properties: + +- interrupt-parent : The parent interrupt controller, optional if inherited + +The gpio and interrupt properties are further described in their respective +bindings documentation: + +- Documentation/devicetree/bindings/gpio/gpio.txt +- Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + + Example: + gpio@1e780000 { + #gpio-cells = <2>; + compatible = "aspeed,ast2400-gpio"; + gpio-controller; + interrupts = <20>; + reg = <0x1e780000 0x1000>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-axp209.txt b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt new file mode 100644 index 000000000000..a6611304dd3c --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-axp209.txt @@ -0,0 +1,30 @@ +AXP209 GPIO controller + +This driver follows the usual GPIO bindings found in +Documentation/devicetree/bindings/gpio/gpio.txt + +Required properties: +- compatible: Should be "x-powers,axp209-gpio" +- #gpio-cells: Should be two. The first cell is the pin number and the + second is the GPIO flags. +- gpio-controller: Marks the device node as a GPIO controller. + +This node must be a subnode of the axp20x PMIC, documented in +Documentation/devicetree/bindings/mfd/axp20x.txt + +Example: + +axp209: pmic@34 { + compatible = "x-powers,axp209"; + reg = <0x34>; + interrupt-parent = <&nmi_intc>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <1>; + + axp_gpio: gpio { + compatible = "x-powers,axp209-gpio"; + gpio-controller; + #gpio-cells = <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt b/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt new file mode 100644 index 000000000000..1afc2de7a537 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-tpic2810.txt @@ -0,0 +1,16 @@ +TPIC2810 GPIO controller bindings + +Required properties: + - compatible : Should be "ti,tpic2810". + - reg : The I2C address of the device + - gpio-controller : Marks the device node as a GPIO controller. + - #gpio-cells : Should be two. For consumer use see gpio.txt. + +Example: + + gpio@60 { + compatible = "ti,tpic2810"; + reg = <0x60>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt b/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt deleted file mode 100644 index ba051074bedc..000000000000 --- a/Documentation/devicetree/bindings/gpio/gpio-tps65086.txt +++ /dev/null @@ -1,16 +0,0 @@ -* TPS65086 GPO Controller bindings - -Required properties: - - compatible : Should be "ti,tps65086-gpio". - - gpio-controller : Marks the device node as a GPIO Controller. - - #gpio-cells : Should be two. The first cell is the pin number - and the second cell is used to specify flags. - See ../gpio/gpio.txt for possible values. - -Example: - - gpio4: gpio { - compatible = "ti,tps65086-gpio"; - gpio-controller; - #gpio-cells = <2>; - }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt b/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt new file mode 100644 index 000000000000..3f8e71b1ab2a --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-ts4900.txt @@ -0,0 +1,30 @@ +* Technologic Systems I2C-FPGA's GPIO controller bindings + +This bindings describes the GPIO controller for Technologic's FPGA core. +TS-4900's FPGA encodes the GPIO state on 3 bits, whereas the TS-7970's FPGA +uses 2 bits: it doesn't use a dedicated input bit. + +Required properties: +- compatible: Should be one of the following + "technologic,ts4900-gpio" + "technologic,ts7970-gpio" +- reg: Physical base address of the controller and length + of memory mapped region. +- #gpio-cells: Should be two. The first cell is the pin number. +- gpio-controller: Marks the device node as a gpio controller. + +Optional property: +- ngpios: Number of GPIOs this controller is instantiated with, + the default is 32. See gpio.txt for more details. + +Example: + +&i2c2 { + gpio8: gpio@28 { + compatible = "technologic,ts4900-gpio"; + reg = <0x28>; + #gpio-cells = <2>; + gpio-controller; + ngpios = <32>; + }; +}; diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt index 98d198396956..c3d016532d8e 100644 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.txt @@ -44,26 +44,3 @@ Example for a PXA3xx platform: interrupt-controller; #interrupt-cells = <0x2>; }; - -* Marvell Orion GPIO Controller - -Required properties: -- compatible : Should be "marvell,orion-gpio" -- reg : Address and length of the register set for controller. -- gpio-controller : So we know this is a gpio controller. -- ngpio : How many gpios this controller has. -- interrupts : Up to 4 Interrupts for the controller. - -Optional properties: -- mask-offset : For SMP Orions, offset for Nth CPU - -Example: - - gpio0: gpio@10100 { - compatible = "marvell,orion-gpio"; - #gpio-cells = <2>; - gpio-controller; - reg = <0x10100 0x40>; - ngpio = <32>; - interrupts = <35>, <36>, <37>, <38>; - }; diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 8da26b35b5c3..7c1ab3b3254f 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -11,6 +11,7 @@ Required Properties: - "renesas,gpio-r8a7793": for R8A7793 (R-Car M2-N) compatible GPIO controller. - "renesas,gpio-r8a7794": for R8A7794 (R-Car E2) compatible GPIO controller. - "renesas,gpio-r8a7795": for R8A7795 (R-Car H3) compatible GPIO controller. + - "renesas,gpio-r8a7796": for R8A7796 (R-Car M3-W) compatible GPIO controller. - "renesas,gpio-rcar": for generic R-Car GPIO controller. - reg: Base address and length of each memory resource used by the GPIO diff --git a/Documentation/devicetree/bindings/hwmon/ltc4151.txt b/Documentation/devicetree/bindings/hwmon/ltc4151.txt new file mode 100644 index 000000000000..d008a5ef525a --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ltc4151.txt @@ -0,0 +1,18 @@ +LTC4151 High Voltage I2C Current and Voltage Monitor + +Required properties: +- compatible: Must be "lltc,ltc4151" +- reg: I2C address + +Optional properties: +- shunt-resistor-micro-ohms + Shunt resistor value in micro-Ohms + Defaults to <1000> if unset. + +Example: + +ltc4151@6e { + compatible = "lltc,ltc4151"; + reg = <0x6e>; + shunt-resistor-micro-ohms = <1500>; +}; diff --git a/Documentation/devicetree/bindings/hwmon/max6650.txt b/Documentation/devicetree/bindings/hwmon/max6650.txt new file mode 100644 index 000000000000..f6bd87d8e284 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/max6650.txt @@ -0,0 +1,28 @@ +Bindings for MAX6651 and MAX6650 I2C fan controllers + +Reference: +[1] https://datasheets.maximintegrated.com/en/ds/MAX6650-MAX6651.pdf + +Required properties: +- compatible : One of "maxim,max6650" or "maxim,max6651" +- reg : I2C address, one of 0x1b, 0x1f, 0x4b, 0x48. + +Optional properties, default is to retain the chip's current setting: +- maxim,fan-microvolt : The supply voltage of the fan, either 5000000 uV or + 12000000 uV. +- maxim,fan-prescale : Pre-scaling value, as per datasheet [1]. Lower values + allow more fine-grained control of slower fans. + Valid: 1, 2, 4, 8, 16. +- maxim,fan-target-rpm: Initial requested fan rotation speed. If specified, the + driver selects closed-loop mode and the requested speed. + This ensures the fan is already running before userspace + takes over. + +Example: + fan-max6650: max6650@1b { + reg = <0x1b>; + compatible = "maxim,max6650"; + maxim,fan-microvolt = <12000000>; + maxim,fan-prescale = <4>; + maxim,fan-target-rpm = <1200>; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt index 71191ff0e781..248a155414c2 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-arb-gpio-challenge.txt @@ -44,8 +44,7 @@ Required properties: - our-claim-gpio: The GPIO that we use to claim the bus. - their-claim-gpios: The GPIOs that the other sides use to claim the bus. Note that some implementations may only support a single other master. -- Standard I2C mux properties. See i2c-mux.txt in this directory. -- Single I2C child bus node at reg 0. See i2c-mux.txt in this directory. +- I2C arbitration bus node. See i2c-arb.txt in this directory. Optional properties: - slew-delay-us: microseconds to wait for a GPIO to go high. Default is 10 us. @@ -63,8 +62,6 @@ Example: i2c-arbitrator { compatible = "i2c-arb-gpio-challenge"; - #address-cells = <1>; - #size-cells = <0>; i2c-parent = <&{/i2c@12CA0000}>; @@ -74,8 +71,7 @@ Example: wait-retry-us = <3000>; wait-free-us = <50000>; - i2c@0 { - reg = <0>; + i2c-arb { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-arb.txt b/Documentation/devicetree/bindings/i2c/i2c-arb.txt new file mode 100644 index 000000000000..59abf9277bdc --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-arb.txt @@ -0,0 +1,35 @@ +Common i2c arbitration bus properties. + +- i2c-arb child node + +Required properties for the i2c-arb child node: +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties for i2c-arb child node: +- Child nodes conforming to i2c bus binding + + +Example : + + /* + An NXP pca9541 I2C bus master selector at address 0x74 + with a NXP pca8574 GPIO expander attached. + */ + + arb@74 { + compatible = "nxp,pca9541"; + reg = <0x74>; + + i2c-arb { + #address-cells = <1>; + #size-cells = <0>; + + gpio@38 { + compatible = "nxp,pca8574"; + reg = <0x38>; + #gpio-cells = <2>; + gpio-controller; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-gate.txt b/Documentation/devicetree/bindings/i2c/i2c-gate.txt new file mode 100644 index 000000000000..1846d236e656 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-gate.txt @@ -0,0 +1,41 @@ +An i2c gate is useful to e.g. reduce the digital noise for RF tuners connected +to the i2c bus. Gates are similar to arbitrators in that you need to perform +some kind of operation to access the i2c bus past the arbitrator/gate, but +there are no competing masters to consider for gates and therefore there is +no arbitration happening for gates. + +Common i2c gate properties. + +- i2c-gate child node + +Required properties for the i2c-gate child node: +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties for i2c-gate child node: +- Child nodes conforming to i2c bus binding + + +Example : + + /* + An Invensense mpu9150 at address 0x68 featuring an on-chip Asahi + Kasei ak8975 compass behind a gate. + */ + + mpu9150@68 { + compatible = "invensense,mpu9150"; + reg = <0x68>; + interrupt-parent = <&gpio1>; + interrupts = <18 1>; + + i2c-gate { + #address-cells = <1>; + #size-cells = <0>; + + ax8975@c { + compatible = "ak,ak8975"; + reg = <0x0c>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-meson.txt b/Documentation/devicetree/bindings/i2c/i2c-meson.txt index 682f9a6f766e..386357d1aab0 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-meson.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-meson.txt @@ -1,7 +1,7 @@ Amlogic Meson I2C controller Required properties: - - compatible: must be "amlogic,meson6-i2c" + - compatible: must be "amlogic,meson6-i2c" or "amlogic,meson-gxbb-i2c" - reg: physical address and length of the device registers - interrupts: a single interrupt specifier - clocks: clock for the device diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux.txt index af84cce5cd7b..212e6779dc5c 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux.txt @@ -2,19 +2,32 @@ Common i2c bus multiplexer/switch properties. An i2c bus multiplexer/switch will have several child busses that are numbered uniquely in a device dependent manner. The nodes for an i2c bus -multiplexer/switch will have one child node for each child -bus. +multiplexer/switch will have one child node for each child bus. -Required properties: +Optional properties: +- #address-cells = <1>; + This property is required is the i2c-mux child node does not exist. + +- #size-cells = <0>; + This property is required is the i2c-mux child node does not exist. + +- i2c-mux + For i2c multiplexers/switches that have child nodes that are a mixture + of both i2c child busses and other child nodes, the 'i2c-mux' subnode + can be used for populating the i2c child busses. If an 'i2c-mux' + subnode is present, only subnodes of this will be considered as i2c + child busses. + +Required properties for the i2c-mux child node: - #address-cells = <1>; - #size-cells = <0>; -Required properties for child nodes: +Required properties for i2c child bus nodes: - #address-cells = <1>; - #size-cells = <0>; - reg : The sub-bus number. -Optional properties for child nodes: +Optional properties for i2c child bus nodes: - Other properties specific to the multiplexer/switch hardware. - Child nodes conforming to i2c bus binding diff --git a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt index 5f0cb502b1db..239632a0d709 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt @@ -11,6 +11,7 @@ Required properties: "renesas,i2c-r8a7793" "renesas,i2c-r8a7794" "renesas,i2c-r8a7795" + "renesas,i2c-r8a7796" - reg: physical base address of the controller and length of memory mapped region. - interrupts: interrupt specifier. diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt index f31b2ad1552b..5fa691e6f638 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -32,6 +32,14 @@ wants to support one of the below features, it should adapt the bindings below. - clock-frequency frequency of bus clock in Hz. +- i2c-bus + For I2C adapters that have child nodes that are a mixture of both I2C + devices and non-I2C devices, the 'i2c-bus' subnode can be used for + populating I2C devices. If the 'i2c-bus' subnode is present, only + subnodes of this will be considered as I2C slaves. The properties, + '#address-cells' and '#size-cells' must be defined under this subnode + if present. + - i2c-scl-falling-time-ns Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C specification. diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt new file mode 100644 index 000000000000..0fbbc6970ec5 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt @@ -0,0 +1,29 @@ +* NXP PCA9541 I2C bus master selector + +Required Properties: + + - compatible: Must be "nxp,pca9541" + + - reg: The I2C address of the device. + + The following required properties are defined externally: + + - I2C arbitration bus node. See i2c-arb.txt in this directory. + + +Example: + + i2c-arbitrator@74 { + compatible = "nxp,pca9541"; + reg = <0x74>; + + i2c-arb { + #address-cells = <1>; + #size-cells = <0>; + + eeprom@54 { + compatible = "at,24c08"; + reg = <0x54>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index 5c70ce9c1954..fbbad6446741 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -38,6 +38,7 @@ dallas,ds4510 CPU Supervisor with Nonvolatile Memory and Programmable I/O dallas,ds75 Digital Thermometer and Thermostat dlg,da9053 DA9053: flexible system level PMIC with multicore support dlg,da9063 DA9063: system PMIC for quad-core application processors +domintech,dmard09 DMARD09: 3-axis Accelerometer epson,rx8010 I2C-BUS INTERFACE REAL TIME CLOCK MODULE epson,rx8025 High-Stability. I2C-Bus INTERFACE REAL TIME CLOCK MODULE epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE @@ -50,12 +51,12 @@ fsl,sgtl5000 SGTL5000: Ultra Low-Power Audio Codec gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) -isil,isl12057 Intersil ISL12057 I2C RTC Chip isil,isl29028 Intersil ISL29028 Ambient Light and Proximity Sensor maxim,ds1050 5 Bit Programmable, Pulse-Width Modulator maxim,max1237 Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs maxim,max6625 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface mc,rv3029c2 Real Time Clock Module with I2C-Bus +mcube,mc3230 mCube 3-axis 8-bit digital accelerometer microchip,mcp4531-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) microchip,mcp4531-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) microchip,mcp4531-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) diff --git a/Documentation/devicetree/bindings/iio/accel/dmard06.txt b/Documentation/devicetree/bindings/iio/accel/dmard06.txt new file mode 100644 index 000000000000..ce105a12c645 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/dmard06.txt @@ -0,0 +1,19 @@ +Device tree bindings for Domintech DMARD05, DMARD06, DMARD07 accelerometers + +Required properties: + - compatible : Should be "domintech,dmard05" + or "domintech,dmard06" + or "domintech,dmard07" + - reg : I2C address of the chip. Should be 0x1c + +Example: + &i2c1 { + /* ... */ + + accelerometer@1c { + compatible = "domintech,dmard06"; + reg = <0x1c>; + }; + + /* ... */ + }; diff --git a/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt new file mode 100644 index 000000000000..b25bf3a77e0f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/kionix,kxsd9.txt @@ -0,0 +1,22 @@ +Kionix KXSD9 Accelerometer device tree bindings + +Required properties: + - compatible: should be set to "kionix,kxsd9" + - reg: i2c slave address + +Optional properties: + - vdd-supply: The input supply for VDD + - iovdd-supply: The input supply for IOVDD + - interrupts: The movement detection interrupt + - mount-matrix: See mount-matrix.txt + +Example: + +kxsd9@18 { + compatible = "kionix,kxsd9"; + reg = <0x18>; + interrupt-parent = <&foo>; + interrupts = <57 IRQ_TYPE_EDGE_FALLING>; + iovdd-supply = <&bar>; + vdd-supply = <&baz>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/mt6577_auxadc.txt b/Documentation/devicetree/bindings/iio/adc/mt6577_auxadc.txt new file mode 100644 index 000000000000..68c45cbbe3d9 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/mt6577_auxadc.txt @@ -0,0 +1,29 @@ +* Mediatek AUXADC - Analog to Digital Converter on Mediatek mobile soc (mt65xx/mt81xx/mt27xx) +=============== + +The Auxiliary Analog/Digital Converter (AUXADC) is an ADC found +in some Mediatek SoCs which among other things measures the temperatures +in the SoC. It can be used directly with register accesses, but it is also +used by thermal controller which reads the temperatures from the AUXADC +directly via its own bus interface. See +Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +for the Thermal Controller which holds a phandle to the AUXADC. + +Required properties: + - compatible: Should be one of: + - "mediatek,mt2701-auxadc": For MT2701 family of SoCs + - "mediatek,mt8173-auxadc": For MT8173 family of SoCs + - reg: Address range of the AUXADC unit. + - clocks: Should contain a clock specifier for each entry in clock-names + - clock-names: Should contain "main". + - #io-channel-cells: Should be 1, see ../iio-bindings.txt + +Example: + +auxadc: adc@11001000 { + compatible = "mediatek,mt2701-auxadc"; + reg = <0 0x11001000 0 0x1000>; + clocks = <&pericfg CLK_PERI_AUXADC>; + clock-names = "main"; + #io-channel-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-adc12138.txt b/Documentation/devicetree/bindings/iio/adc/ti-adc12138.txt new file mode 100644 index 000000000000..049a1d36f013 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-adc12138.txt @@ -0,0 +1,37 @@ +* Texas Instruments' ADC12130/ADC12132/ADC12138 + +Required properties: + - compatible: Should be one of + * "ti,adc12130" + * "ti,adc12132" + * "ti,adc12138" + - reg: SPI chip select number for the device + - interrupts: Should contain interrupt for EOC (end of conversion) + - clocks: phandle to conversion clock input + - spi-max-frequency: Definision as per + Documentation/devicetree/bindings/spi/spi-bus.txt + - vref-p-supply: The regulator supply for positive analog voltage reference + +Optional properties: + - vref-n-supply: The regulator supply for negative analog voltage reference + (Note that this must not go below GND or exceed vref-p) + If not specified, this is assumed to be analog ground. + - ti,acquisition-time: The number of conversion clock periods for the S/H's + acquisition time. Should be one of 6, 10, 18, 34. If not specified, + default value of 10 is used. + For high source impedances, this value can be increased to 18 or 34. + For less ADC accuracy and/or slower CCLK frequencies this value may be + decreased to 6. See section 6.0 INPUT SOURCE RESISTANCE in the + datasheet for details. + +Example: +adc@0 { + compatible = "ti,adc12138"; + reg = <0>; + interrupts = <28 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&gpio1>; + clocks = <&cclk>; + vref-p-supply = <&ldo4_reg>; + spi-max-frequency = <5000000>; + ti,acquisition-time = <6>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-adc161s626.txt b/Documentation/devicetree/bindings/iio/adc/ti-adc161s626.txt new file mode 100644 index 000000000000..9ed2315781e4 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-adc161s626.txt @@ -0,0 +1,16 @@ +* Texas Instruments ADC141S626 and ADC161S626 chips + +Required properties: + - compatible: Should be "ti,adc141s626" or "ti,adc161s626" + - reg: spi chip select number for the device + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: +adc@0 { + compatible = "ti,adc161s626"; + reg = <0>; + spi-max-frequency = <4300000>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/atlas,orp-sm.txt b/Documentation/devicetree/bindings/iio/chemical/atlas,orp-sm.txt new file mode 100644 index 000000000000..5d8b687d5edc --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/atlas,orp-sm.txt @@ -0,0 +1,22 @@ +* Atlas Scientific ORP-SM OEM sensor + +https://www.atlas-scientific.com/_files/_datasheets/_oem/ORP_oem_datasheet.pdf + +Required properties: + + - compatible: must be "atlas,orp-sm" + - reg: the I2C address of the sensor + - interrupt-parent: should be the phandle for the interrupt controller + - interrupts: the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + +Example: + +atlas@66 { + compatible = "atlas,orp-sm"; + reg = <0x66>; + interrupt-parent = <&gpio1>; + interrupts = <16 2>; +}; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/ak8974.txt b/Documentation/devicetree/bindings/iio/magnetometer/ak8974.txt new file mode 100644 index 000000000000..77d5aba1bd8c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/ak8974.txt @@ -0,0 +1,29 @@ +* Asahi Kasei AK8974 magnetometer sensor + +Required properties: + +- compatible : should be "asahi-kasei,ak8974" +- reg : the I2C address of the magnetometer + +Optional properties: + +- avdd-supply: regulator supply for the analog voltage + (see regulator/regulator.txt) +- dvdd-supply: regulator supply for the digital voltage + (see regulator/regulator.txt) +- interrupts: data ready (DRDY) and interrupt (INT1) lines + from the chip, the DRDY interrupt must be placed first. + The interrupts can be triggered on rising or falling + edges alike. +- mount-matrix: an optional 3x3 mounting rotation matrix + +Example: + +ak8974@0f { + compatible = "asahi-kasei,ak8974"; + reg = <0x0f>; + avdd-supply = <&foo_reg>; + dvdd-supply = <&bar_reg>; + interrupts = <0 IRQ_TYPE_EDGE_RISING>, + <1 IRQ_TYPE_EDGE_RISING>; +}; diff --git a/Documentation/devicetree/bindings/iio/pressure/zpa2326.txt b/Documentation/devicetree/bindings/iio/pressure/zpa2326.txt new file mode 100644 index 000000000000..fb85de676e03 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/pressure/zpa2326.txt @@ -0,0 +1,31 @@ +Murata ZPA2326 pressure sensor + +Pressure sensor from Murata with SPI and I2C bus interfaces. + +Required properties: +- compatible: "murata,zpa2326" +- reg: the I2C address or SPI chip select the device will respond to + +Recommended properties for SPI bus usage: +- spi-max-frequency: maximum SPI bus frequency as documented in + Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: +- vref-supply: an optional regulator that needs to be on to provide VREF + power to the sensor +- vdd-supply: an optional regulator that needs to be on to provide VDD + power to the sensor +- interrupt-parent: phandle to the parent interrupt controller as documented in + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +- interrupts: interrupt mapping for IRQ as documented in + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Example: + +zpa2326@5c { + compatible = "murata,zpa2326"; + reg = <0x5c>; + interrupt-parent = <&gpio>; + interrupts = <12>; + vdd-supply = <&ldo_1v8_gnss>; +}; diff --git a/Documentation/devicetree/bindings/iio/proximity/sx9500.txt b/Documentation/devicetree/bindings/iio/proximity/sx9500.txt new file mode 100644 index 000000000000..b301dd2b35da --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/sx9500.txt @@ -0,0 +1,24 @@ +Semtech's SX9500 capacitive proximity button device driver + +Required properties: + - compatible: must be "semtech,sx9500" + - reg: i2c address where to find the device + - interrupt-parent : should be the phandle for the interrupt controller + - interrupts : the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic + interrupt client node bindings. + +Optional properties: + - reset-gpios: Reference to the GPIO connected to the device's active + low reset pin. + +Example: + +sx9500@28 { + compatible = "semtech,sx9500"; + reg = <0x28>; + interrupt-parent = <&gpio2>; + interrupts = <16 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&gpio2 10 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt b/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt new file mode 100644 index 000000000000..28bc5c4d965b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/temperature/maxim_thermocouple.txt @@ -0,0 +1,21 @@ +Maxim thermocouple support + +* https://datasheets.maximintegrated.com/en/ds/MAX6675.pdf +* https://datasheets.maximintegrated.com/en/ds/MAX31855.pdf + +Required properties: + + - compatible: must be "maxim,max31855" or "maxim,max6675" + - reg: SPI chip select number for the device + - spi-max-frequency: must be 4300000 + - spi-cpha: must be defined for max6675 to enable SPI mode 1 + + Refer to spi/spi-bus.txt for generic SPI slave bindings. + +Example: + + max31855@0 { + compatible = "maxim,max31855"; + reg = <0>; + spi-max-frequency = <4300000>; + }; diff --git a/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt b/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt new file mode 100644 index 000000000000..d3b273e4336a --- /dev/null +++ b/Documentation/devicetree/bindings/infiniband/hisilicon-hns-roce.txt @@ -0,0 +1,109 @@ +Hisilicon RoCE DT description + +Hisilicon RoCE engine is a part of network subsystem. +It works depending on other part of network wubsytem, such as, gmac and +dsa fabric. + +Additional properties are described here: + +Required properties: +- compatible: Should contain "hisilicon,hns-roce-v1". +- reg: Physical base address of the RoCE driver and +length of memory mapped region. +- eth-handle: phandle, specifies a reference to a node +representing a ethernet device. +- dsaf-handle: phandle, specifies a reference to a node +representing a dsaf device. +- node_guid: a number that uniquely identifies a device or component +- #address-cells: must be 2 +- #size-cells: must be 2 +Optional properties: +- dma-coherent: Present if DMA operations are coherent. +- interrupt-parent: the interrupt parent of this device. +- interrupts: should contain 32 completion event irq,1 async event irq +and 1 event overflow irq. +- interrupt-names:should be one of 34 irqs for roce device + - hns-roce-comp-0 ~ hns-roce-comp-31: 32 complete event irq + - hns-roce-async: 1 async event irq + - hns-roce-common: named common exception warning irq +Example: + infiniband@c4000000 { + compatible = "hisilicon,hns-roce-v1"; + reg = <0x0 0xc4000000 0x0 0x100000>; + dma-coherent; + eth-handle = <ð2 ð3 ð4 ð5 ð6 ð7>; + dsaf-handle = <&soc0_dsa>; + node-guid = [00 9A CD 00 00 01 02 03]; + #address-cells = <2>; + #size-cells = <2>; + interrupt-parent = <&mbigen_dsa>; + interrupts = <722 1>, + <723 1>, + <724 1>, + <725 1>, + <726 1>, + <727 1>, + <728 1>, + <729 1>, + <730 1>, + <731 1>, + <732 1>, + <733 1>, + <734 1>, + <735 1>, + <736 1>, + <737 1>, + <738 1>, + <739 1>, + <740 1>, + <741 1>, + <742 1>, + <743 1>, + <744 1>, + <745 1>, + <746 1>, + <747 1>, + <748 1>, + <749 1>, + <750 1>, + <751 1>, + <752 1>, + <753 1>, + <785 1>, + <754 4>; + + interrupt-names = "hns-roce-comp-0", + "hns-roce-comp-1", + "hns-roce-comp-2", + "hns-roce-comp-3", + "hns-roce-comp-4", + "hns-roce-comp-5", + "hns-roce-comp-6", + "hns-roce-comp-7", + "hns-roce-comp-8", + "hns-roce-comp-9", + "hns-roce-comp-10", + "hns-roce-comp-11", + "hns-roce-comp-12", + "hns-roce-comp-13", + "hns-roce-comp-14", + "hns-roce-comp-15", + "hns-roce-comp-16", + "hns-roce-comp-17", + "hns-roce-comp-18", + "hns-roce-comp-19", + "hns-roce-comp-20", + "hns-roce-comp-21", + "hns-roce-comp-22", + "hns-roce-comp-23", + "hns-roce-comp-24", + "hns-roce-comp-25", + "hns-roce-comp-26", + "hns-roce-comp-27", + "hns-roce-comp-28", + "hns-roce-comp-29", + "hns-roce-comp-30", + "hns-roce-comp-31", + "hns-roce-async", + "hns-roce-common"; + }; diff --git a/Documentation/devicetree/bindings/input/adc-keys.txt b/Documentation/devicetree/bindings/input/adc-keys.txt new file mode 100644 index 000000000000..e551814629b4 --- /dev/null +++ b/Documentation/devicetree/bindings/input/adc-keys.txt @@ -0,0 +1,49 @@ +ADC attached resistor ladder buttons +------------------------------------ + +Required properties: + - compatible: "adc-keys" + - io-channels: Phandle to an ADC channel + - io-channel-names = "buttons"; + - keyup-threshold-microvolt: Voltage at which all the keys are considered up. + +Optional properties: + - poll-interval: Poll interval time in milliseconds + - autorepeat: Boolean, Enable auto repeat feature of Linux input + subsystem. + +Each button (key) is represented as a sub-node of "adc-keys": + +Required subnode-properties: + - label: Descriptive name of the key. + - linux,code: Keycode to emit. + - press-threshold-microvolt: Voltage ADC input when this key is pressed. + +Example: + +#include + + adc-keys { + compatible = "adc-keys"; + io-channels = <&lradc 0>; + io-channel-names = "buttons"; + keyup-threshold-microvolt = <2000000>; + + button-up { + label = "Volume Up"; + linux,code = ; + press-threshold-microvolt = <1500000>; + }; + + button-down { + label = "Volume Down"; + linux,code = ; + press-threshold-microvolt = <1000000>; + }; + + button-enter { + label = "Enter"; + linux,code = ; + press-threshold-microvolt = <500000>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/gpio-decoder.txt b/Documentation/devicetree/bindings/input/gpio-decoder.txt new file mode 100644 index 000000000000..14a77fb96cf0 --- /dev/null +++ b/Documentation/devicetree/bindings/input/gpio-decoder.txt @@ -0,0 +1,23 @@ +* GPIO Decoder DT bindings + +Required Properties: +- compatible: should be "gpio-decoder" +- gpios: a spec of gpios (at least two) to be decoded to a number with + first entry representing the MSB. + +Optional Properties: +- decoder-max-value: Maximum possible value that can be reported by + the gpios. +- linux,axis: the input subsystem axis to map to (ABS_X/ABS_Y). + Defaults to 0 (ABS_X). + +Example: + gpio-decoder0 { + compatible = "gpio-decoder"; + gpios = <&pca9536 3 GPIO_ACTIVE_HIGH>, + <&pca9536 2 GPIO_ACTIVE_HIGH>, + <&pca9536 1 GPIO_ACTIVE_HIGH>, + <&pca9536 0 GPIO_ACTIVE_HIGH>; + linux,axis = <0>; /* ABS_X */ + decoder-max-value = <9>; + }; diff --git a/Documentation/devicetree/bindings/input/gpio-keys-polled.txt b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt index 95d0fb11a787..4d9a3717eaaf 100644 --- a/Documentation/devicetree/bindings/input/gpio-keys-polled.txt +++ b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt @@ -34,11 +34,10 @@ Example nodes: gpio_keys_polled { compatible = "gpio-keys-polled"; - #address-cells = <1>; - #size-cells = <0>; poll-interval = <100>; autorepeat; - button@21 { + + button21 { label = "GPIO Key UP"; linux,code = <103>; gpios = <&gpio1 0 1>; diff --git a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt index f99528da1b1d..6db22103e2dd 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/edt-ft5x06.txt @@ -19,6 +19,7 @@ Required properties: or: "edt,edt-ft5306" or: "edt,edt-ft5406" or: "edt,edt-ft5506" + or: "focaltech,ft6236" - reg: I2C slave address of the chip (0x38) - interrupt-parent: a phandle pointing to the interrupt controller @@ -43,6 +44,13 @@ Optional properties: - offset: allows setting the edge compensation in the range from 0 to 31. + - touchscreen-size-x : See touchscreen.txt + - touchscreen-size-y : See touchscreen.txt + - touchscreen-fuzz-x : See touchscreen.txt + - touchscreen-fuzz-y : See touchscreen.txt + - touchscreen-inverted-x : See touchscreen.txt + - touchscreen-inverted-y : See touchscreen.txt + - touchscreen-swapped-x-y : See touchscreen.txt Example: polytouch: edt-ft5x06@38 { diff --git a/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt b/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt new file mode 100644 index 000000000000..5a19f4c3e9d7 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/ektf2127.txt @@ -0,0 +1,27 @@ +* Elan eKTF2127 I2C touchscreen controller + +Required properties: + - compatible : "elan,ektf2127" + - reg : I2C slave address of the chip (0x40) + - interrupt-parent : a phandle pointing to the interrupt controller + serving the interrupt for this chip + - interrupts : interrupt specification for the ektf2127 interrupt + - power-gpios : GPIO specification for the pin connected to the + ektf2127's wake input. This needs to be driven high + to take ektf2127 out of it's low power state + +For additional optional properties see: touchscreen.txt + +Example: + +i2c@00000000 { + ektf2127: touchscreen@15 { + compatible = "elan,ektf2127"; + reg = <0x15>; + interrupt-parent = <&pio>; + interrupts = <6 11 IRQ_TYPE_EDGE_FALLING> + power-gpios = <&pio 1 3 GPIO_ACTIVE_HIGH>; + touchscreen-inverted-x; + touchscreen-swapped-x-y; + }; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt b/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt deleted file mode 100644 index 777521da3da5..000000000000 --- a/Documentation/devicetree/bindings/input/touchscreen/focaltech-ft6236.txt +++ /dev/null @@ -1,35 +0,0 @@ -* FocalTech FT6236 I2C touchscreen controller - -Required properties: - - compatible : "focaltech,ft6236" - - reg : I2C slave address of the chip (0x38) - - interrupt-parent : a phandle pointing to the interrupt controller - serving the interrupt for this chip - - interrupts : interrupt specification for the touch controller - interrupt - - reset-gpios : GPIO specification for the RSTN input - - touchscreen-size-x : horizontal resolution of touchscreen (in pixels) - - touchscreen-size-y : vertical resolution of touchscreen (in pixels) - -Optional properties: - - touchscreen-fuzz-x : horizontal noise value of the absolute input - device (in pixels) - - touchscreen-fuzz-y : vertical noise value of the absolute input - device (in pixels) - - touchscreen-inverted-x : X axis is inverted (boolean) - - touchscreen-inverted-y : Y axis is inverted (boolean) - - touchscreen-swapped-x-y: X and Y axis are swapped (boolean) - Swapping is done after inverting the axis - -Example: - - ft6x06@38 { - compatible = "focaltech,ft6236"; - reg = <0x38>; - interrupt-parent = <&gpio>; - interrupts = <23 2>; - touchscreen-size-x = <320>; - touchscreen-size-y = <480>; - touchscreen-inverted-x; - touchscreen-swapped-x-y; - }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/melfas_mip4.txt b/Documentation/devicetree/bindings/input/touchscreen/melfas_mip4.txt new file mode 100644 index 000000000000..7b8944c2cb31 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/melfas_mip4.txt @@ -0,0 +1,21 @@ +* MELFAS MIP4 Touchscreen + +Required properties: +- compatible: must be "melfas,mip4_ts" +- reg: I2C slave address of the chip (0x48 or 0x34) +- interrupt-parent: interrupt controller to which the chip is connected +- interrupts: interrupt to which the chip is connected + +Optional properties: +- ce-gpios: GPIO connected to the CE (chip enable) pin of the chip + +Example: + i2c@00000000 { + touchscreen: melfas_mip4@48 { + compatible = "melfas,mip4_ts"; + reg = <0x48>; + interrupt-parent = <&gpio>; + interrupts = <0 IRQ_TYPE_EDGE_FALLING>; + ce-gpios = <&gpio 0 GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt index 1112e0d794e1..820fee4b77b6 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/silead_gsl1680.txt @@ -13,6 +13,7 @@ Required properties: - touchscreen-size-y : See touchscreen.txt Optional properties: +- firmware-name : File basename (string) for board specific firmware - touchscreen-inverted-x : See touchscreen.txt - touchscreen-inverted-y : See touchscreen.txt - touchscreen-swapped-x-y : See touchscreen.txt diff --git a/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt index e30e0b93f2b3..3e5b9793341f 100644 --- a/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt +++ b/Documentation/devicetree/bindings/input/tps65218-pwrbutton.txt @@ -1,13 +1,24 @@ -Texas Instruments TPS65218 power button +Texas Instruments TPS65217 and TPS65218 power button + +This module is part of the TPS65217/TPS65218. For more details about the whole +TPS65217 chip see Documentation/devicetree/bindings/regulator/tps65217.txt. This driver provides a simple power button event via an Interrupt. Required properties: -- compatible: should be "ti,tps65218-pwrbutton" +- compatible: should be "ti,tps65217-pwrbutton" or "ti,tps65218-pwrbutton" + +Required properties for TPS65218: - interrupts: should be one of the following - <3 IRQ_TYPE_EDGE_BOTH>: For controllers compatible with tps65218 -Example: +Examples: + +&tps { + tps65217-pwrbutton { + compatible = "ti,tps65217-pwrbutton"; + }; +}; &tps { power-button { diff --git a/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt b/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt new file mode 100644 index 000000000000..ee2ad36f8df8 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/jcore,aic.txt @@ -0,0 +1,26 @@ +J-Core Advanced Interrupt Controller + +Required properties: + +- compatible: Should be "jcore,aic1" for the (obsolete) first-generation aic + with 8 interrupt lines with programmable priorities, or "jcore,aic2" for + the "aic2" core with 64 interrupts. + +- reg: Memory region(s) for configuration. For SMP, there should be one + region per cpu, indexed by the sequential, zero-based hardware cpu + number. + +- interrupt-controller: Identifies the node as an interrupt controller + +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source. The value shall be 1. + + +Example: + +aic: interrupt-controller@200 { + compatible = "jcore,aic2"; + reg = < 0x200 0x30 0x500 0x30 >; + interrupt-controller; + #interrupt-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt new file mode 100644 index 000000000000..86a7b4cd03f5 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,armada-8k-pic.txt @@ -0,0 +1,25 @@ +Marvell Armada 7K/8K PIC Interrupt controller +--------------------------------------------- + +This is the Device Tree binding for the PIC, a secondary interrupt +controller available on the Marvell Armada 7K/8K ARM64 SoCs, and +typically connected to the GIC as the primary interrupt controller. + +Required properties: +- compatible: should be "marvell,armada-8k-pic" +- interrupt-controller: identifies the node as an interrupt controller +- #interrupt-cells: the number of cells to define interrupts on this + controller. Should be 1 +- reg: the register area for the PIC interrupt controller +- interrupts: the interrupt to the primary interrupt controller, + typically the GIC + +Example: + + pic: interrupt-controller@3f0100 { + compatible = "marvell,armada-8k-pic"; + reg = <0x3f0100 0x10>; + #interrupt-cells = <1>; + interrupt-controller; + interrupts = ; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt index 8af0a8e613ab..3f6442c7f867 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/marvell,odmi-controller.txt @@ -31,7 +31,7 @@ Required properties: Example: odmi: odmi@300000 { - compatible = "marvell,ap806-odm-controller", + compatible = "marvell,ap806-odmi-controller", "marvell,odmi-controller"; interrupt-controller; msi-controller; diff --git a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt index ae5054c27c99..e3f052d8c11a 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/renesas,irqc.txt @@ -1,10 +1,12 @@ -DT bindings for the R-Mobile/R-Car interrupt controller +DT bindings for the R-Mobile/R-Car/RZ/G interrupt controller Required properties: - compatible: has to be "renesas,irqc-", "renesas,irqc" as fallback. Examples with soctypes are: - "renesas,irqc-r8a73a4" (R-Mobile APE6) + - "renesas,irqc-r8a7743" (RZ/G1M) + - "renesas,irqc-r8a7745" (RZ/G1E) - "renesas,irqc-r8a7790" (R-Car H2) - "renesas,irqc-r8a7791" (R-Car M2-W) - "renesas,irqc-r8a7792" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt new file mode 100644 index 000000000000..6e7703d4ff5b --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt @@ -0,0 +1,20 @@ +STM32 External Interrupt Controller + +Required properties: + +- compatible: Should be "st,stm32-exti" +- reg: Specifies base physical address and size of the registers +- interrupt-controller: Indentifies the node as an interrupt controller +- #interrupt-cells: Specifies the number of cells to encode an interrupt + specifier, shall be 2 +- interrupts: interrupts references to primary interrupt controller + +Example: + +exti: interrupt-controller@40013c00 { + compatible = "st,stm32-exti"; + interrupt-controller; + #interrupt-cells = <2>; + reg = <0x40013C00 0x400>; + interrupts = <1>, <2>, <3>, <6>, <7>, <8>, <9>, <10>, <23>, <40>, <41>, <42>, <62>, <76>; +}; diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt index 7b94c88cf2ee..be57550e14e4 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu-v3.txt @@ -27,6 +27,12 @@ the PCIe specification. * "cmdq-sync" - CMD_SYNC complete * "gerror" - Global Error activated +- #iommu-cells : See the generic IOMMU binding described in + devicetree/bindings/pci/pci-iommu.txt + for details. For SMMUv3, must be 1, with each cell + describing a single stream ID. All possible stream + IDs which a device may emit must be described. + ** SMMUv3 optional properties: - dma-coherent : Present if DMA operations made by the SMMU (page @@ -54,6 +60,6 @@ the PCIe specification. ; interrupt-names = "eventq", "priq", "cmdq-sync", "gerror"; dma-coherent; - #iommu-cells = <0>; + #iommu-cells = <1>; msi-parent = <&its 0xff0000>; }; diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt index 19fe6f2c83f6..e862d1485205 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt @@ -35,12 +35,16 @@ conditions. interrupt per context bank. In the case of a single, combined interrupt, it must be listed multiple times. -- mmu-masters : A list of phandles to device nodes representing bus - masters for which the SMMU can provide a translation - and their corresponding StreamIDs (see example below). - Each device node linked from this list must have a - "#stream-id-cells" property, indicating the number of - StreamIDs associated with it. +- #iommu-cells : See Documentation/devicetree/bindings/iommu/iommu.txt + for details. With a value of 1, each "iommus" entry + represents a distinct stream ID emitted by that device + into the relevant SMMU. + + SMMUs with stream matching support and complex masters + may use a value of 2, where the second cell represents + an SMR mask to combine with the ID in the first cell. + Care must be taken to ensure the set of matched IDs + does not result in conflicts. ** System MMU optional properties: @@ -56,9 +60,20 @@ conditions. aliases of secure registers have to be used during SMMU configuration. -Example: +** Deprecated properties: + +- mmu-masters (deprecated in favour of the generic "iommus" binding) : + A list of phandles to device nodes representing bus + masters for which the SMMU can provide a translation + and their corresponding Stream IDs. Each device node + linked from this list must have a "#stream-id-cells" + property, indicating the number of Stream ID + arguments associated with its phandle. - smmu { +** Examples: + + /* SMMU with stream matching or stream indexing */ + smmu1: iommu { compatible = "arm,smmu-v1"; reg = <0xba5e0000 0x10000>; #global-interrupts = <2>; @@ -68,11 +83,29 @@ Example: <0 35 4>, <0 36 4>, <0 37 4>; + #iommu-cells = <1>; + }; + + /* device with two stream IDs, 0 and 7 */ + master1 { + iommus = <&smmu1 0>, + <&smmu1 7>; + }; + + + /* SMMU with stream matching */ + smmu2: iommu { + ... + #iommu-cells = <2>; + }; + + /* device with stream IDs 0 and 7 */ + master2 { + iommus = <&smmu2 0 0>, + <&smmu2 7 0>; + }; - /* - * Two DMA controllers, the first with two StreamIDs (0xd01d - * and 0xd01e) and the second with only one (0xd11c). - */ - mmu-masters = <&dma0 0xd01d 0xd01e>, - <&dma1 0xd11c>; + /* device with stream IDs 1, 17, 33 and 49 */ + master3 { + iommus = <&smmu2 1 0x30>; }; diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt index 93ef6e6e43b5..696be5792625 100644 --- a/Documentation/devicetree/bindings/leds/common.txt +++ b/Documentation/devicetree/bindings/leds/common.txt @@ -19,6 +19,13 @@ Optional properties for child nodes: a device, i.e. no other LED class device can be assigned the same label. +- default-state : The initial state of the LED. Valid values are "on", "off", + and "keep". If the LED is already on or off and the default-state property is + set the to same value, then no glitch should be produced where the LED + momentarily turns off (or on). The "keep" setting will keep the LED at + whatever its current state is, without producing a glitch. The default is + off if this property is not present. + - linux,default-trigger : This parameter, if present, is a string defining the trigger assigned to the LED. Current triggers are: "backlight" - LED will act as a back-light, controlled by the framebuffer diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt index 3f48c1eaf085..ccebce597f37 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6328.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.txt @@ -49,7 +49,7 @@ LED sub-node optional properties: - active-low : Boolean, makes LED active low. Default : false - default-state : see - Documentation/devicetree/bindings/leds/leds-gpio.txt + Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : see Documentation/devicetree/bindings/leds/common.txt diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt index b22a55bcc65d..da5708e7b43b 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt @@ -28,7 +28,7 @@ LED sub-node optional properties: - active-low : Boolean, makes LED active low. Default : false - default-state : see - Documentation/devicetree/bindings/leds/leds-gpio.txt + Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : see Documentation/devicetree/bindings/leds/common.txt diff --git a/Documentation/devicetree/bindings/leds/leds-gpio.txt b/Documentation/devicetree/bindings/leds/leds-gpio.txt index 5b1b43a64265..76535ca37120 100644 --- a/Documentation/devicetree/bindings/leds/leds-gpio.txt +++ b/Documentation/devicetree/bindings/leds/leds-gpio.txt @@ -14,13 +14,8 @@ LED sub-node properties: see Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : (optional) see Documentation/devicetree/bindings/leds/common.txt -- default-state: (optional) The initial state of the LED. Valid - values are "on", "off", and "keep". If the LED is already on or off - and the default-state property is set the to same value, then no - glitch should be produced where the LED momentarily turns off (or - on). The "keep" setting will keep the LED at whatever its current - state is, without producing a glitch. The default is off if this - property is not present. +- default-state: (optional) The initial state of the LED. + see Documentation/devicetree/bindings/leds/common.txt - retain-state-suspended: (optional) The suspend state can be retained.Such as charge-led gpio. - panic-indicator : (optional) diff --git a/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt b/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt new file mode 100644 index 000000000000..fc2603484544 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-is31fl319x.txt @@ -0,0 +1,59 @@ +LEDs connected to is31fl319x LED controller chip + +Required properties: +- compatible : Should be any of + "issi,is31fl3190" + "issi,is31fl3191" + "issi,is31fl3193" + "issi,is31fl3196" + "issi,is31fl3199" + "si-en,sn3199". +- #address-cells: Must be 1. +- #size-cells: Must be 0. +- reg: 0x64, 0x65, 0x66, or 0x67. + +Optional properties: +- audio-gain-db : audio gain selection for external analog modulation input. + Valid values: 0 - 21, step by 3 (rounded down) + Default: 0 + +Each led is represented as a sub-node of the issi,is31fl319x device. +There can be less leds subnodes than the chip can support but not more. + +Required led sub-node properties: +- reg : number of LED line + Valid values: 1 - number of leds supported by the chip variant. + +Optional led sub-node properties: +- label : see Documentation/devicetree/bindings/leds/common.txt. +- linux,default-trigger : + see Documentation/devicetree/bindings/leds/common.txt. +- led-max-microamp : (optional) + Valid values: 5000 - 40000, step by 5000 (rounded down) + Default: 20000 (20 mA) + Note: a driver will take the lowest of all led limits since the + chip has a single global setting. The lowest value will be chosen + due to the PWM specificity, where lower brightness is achieved + by reducing the dury-cycle of pulses and not the current, which + will always have its peak value equal to led-max-microamp. + +Examples: + +fancy_leds: leds@65 { + compatible = "issi,is31fl3196"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x65>; + + red_aux: led@1 { + label = "red:aux"; + reg = <1>; + led-max-microamp = <10000>; + }; + + green_power: led@5 { + label = "green:power"; + reg = <5>; + linux,default-trigger = "default-on"; + }; +}; diff --git a/Documentation/devicetree/bindings/leds/leds-pm8058.txt b/Documentation/devicetree/bindings/leds/leds-pm8058.txt new file mode 100644 index 000000000000..89584c49aab2 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-pm8058.txt @@ -0,0 +1,67 @@ +Qualcomm PM8058 LED driver + +The Qualcomm PM8058 is a multi-functional device which contains +an LED driver block for up to six LEDs: three normal LEDs, two +"flash" LEDs and one "keypad backlight" LED. The names are +quoted because sometimes these LED drivers are used for wildly +different things than flash or keypad backlight: their names +are more of a suggestion than a hard-wired usecase. + +Hardware-wise the different LEDs support slightly different +output currents. The "flash" LEDs do not need to charge nor +do they support external triggers. They are just powerful LED +drivers. + +The LEDs appear as children to the PM8058 device, with the +proper compatible string. For the PM8058 bindings see: +mfd/qcom-pm8xxx.txt. + +Each LED is represented as a sub-node of the syscon device. Each +node's name represents the name of the corresponding LED. + +LED sub-node properties: + +Required properties: +- compatible: one of + "qcom,pm8058-led" (for the normal LEDs at 0x131, 0x132 and 0x133) + "qcom,pm8058-keypad-led" (for the "keypad" LED at 0x48) + "qcom,pm8058-flash-led" (for the "flash" LEDs at 0x49 and 0xFB) + +Optional properties: +- label: see Documentation/devicetree/bindings/leds/common.txt +- default-state: see Documentation/devicetree/bindings/leds/common.txt +- linux,default-trigger: see Documentation/devicetree/bindings/leds/common.txt + +Example: + +qcom,ssbi@500000 { + pmicintc: pmic@0 { + compatible = "qcom,pm8058"; + led@48 { + compatible = "qcom,pm8058-keypad-led"; + reg = <0x48>; + label = "pm8050:white:keypad"; + default-state = "off"; + }; + led@131 { + compatible = "qcom,pm8058-led"; + reg = <0x131>; + label = "pm8058:red"; + default-state = "off"; + }; + led@132 { + compatible = "qcom,pm8058-led"; + reg = <0x132>; + label = "pm8058:yellow"; + default-state = "off"; + linux,default-trigger = "mmc0"; + }; + led@133 { + compatible = "qcom,pm8058-led"; + reg = <0x133>; + label = "pm8058:green"; + default-state = "on"; + linux,default-trigger = "heartbeat"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/leds/register-bit-led.txt b/Documentation/devicetree/bindings/leds/register-bit-led.txt index 379cefdc0bda..59b56365f648 100644 --- a/Documentation/devicetree/bindings/leds/register-bit-led.txt +++ b/Documentation/devicetree/bindings/leds/register-bit-led.txt @@ -23,13 +23,8 @@ Optional properties: see Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : (optional) see Documentation/devicetree/bindings/leds/common.txt -- default-state: (optional) The initial state of the LED. Valid - values are "on", "off", and "keep". If the LED is already on or off - and the default-state property is set the to same value, then no - glitch should be produced where the LED momentarily turns off (or - on). The "keep" setting will keep the LED at whatever its current - state is, without producing a glitch. The default is off if this - property is not present. +- default-state: (optional) The initial state of the LED + see Documentation/devicetree/bindings/leds/common.txt Example: diff --git a/Documentation/devicetree/bindings/mailbox/meson-mhu.txt b/Documentation/devicetree/bindings/mailbox/meson-mhu.txt new file mode 100644 index 000000000000..a530310772b9 --- /dev/null +++ b/Documentation/devicetree/bindings/mailbox/meson-mhu.txt @@ -0,0 +1,34 @@ +Amlogic Meson MHU Mailbox Driver +================================ + +The Amlogic's Meson SoCs Message-Handling-Unit (MHU) is a mailbox controller +that has 3 independent channels/links to communicate with remote processor(s). +MHU links are hardwired on a platform. A link raises interrupt for any +received data. However, there is no specified way of knowing if the sent +data has been read by the remote. This driver assumes the sender polls +STAT register and the remote clears it after having read the data. + +Mailbox Device Node: +==================== + +Required properties: +-------------------- +- compatible: Shall be "amlogic,meson-gxbb-mhu" +- reg: Contains the mailbox register address range (base + address and length) +- #mbox-cells Shall be 1 - the index of the channel needed. +- interrupts: Contains the interrupt information corresponding to + each of the 2 links of MHU. + +Example: +-------- + + mailbox: mailbox@c883c404 { + #mbox-cells = <1>; + compatible = "amlogic,meson-gxbb-mhu"; + reg = <0 0xc883c404 0 0x4c>; + interrupts = <0 208 IRQ_TYPE_EDGE_RISING>, + <0 209 IRQ_TYPE_EDGE_RISING>, + <0 210 IRQ_TYPE_EDGE_RISING>; + #mbox-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/media/atmel-isc.txt b/Documentation/devicetree/bindings/media/atmel-isc.txt new file mode 100644 index 000000000000..bbe0e87c6188 --- /dev/null +++ b/Documentation/devicetree/bindings/media/atmel-isc.txt @@ -0,0 +1,65 @@ +Atmel Image Sensor Controller (ISC) +---------------------------------------------- + +Required properties for ISC: +- compatible + Must be "atmel,sama5d2-isc". +- reg + Physical base address and length of the registers set for the device. +- interrupts + Should contain IRQ line for the ISC. +- clocks + List of clock specifiers, corresponding to entries in + the clock-names property; + Please refer to clock-bindings.txt. +- clock-names + Required elements: "hclock", "iscck", "gck". +- #clock-cells + Should be 0. +- clock-output-names + Should be "isc-mck". +- pinctrl-names, pinctrl-0 + Please refer to pinctrl-bindings.txt. + +ISC supports a single port node with parallel bus. It should contain one +'port' child node with child 'endpoint' node. Please refer to the bindings +defined in Documentation/devicetree/bindings/media/video-interfaces.txt. + +Example: +isc: isc@f0008000 { + compatible = "atmel,sama5d2-isc"; + reg = <0xf0008000 0x4000>; + interrupts = <46 IRQ_TYPE_LEVEL_HIGH 5>; + clocks = <&isc_clk>, <&iscck>, <&isc_gclk>; + clock-names = "hclock", "iscck", "gck"; + #clock-cells = <0>; + clock-output-names = "isc-mck"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_isc_base &pinctrl_isc_data_8bit &pinctrl_isc_data_9_10 &pinctrl_isc_data_11_12>; + + port { + isc_0: endpoint { + remote-endpoint = <&ov7740_0>; + hsync-active = <1>; + vsync-active = <0>; + pclk-sample = <1>; + }; + }; +}; + +i2c1: i2c@fc028000 { + ov7740: camera@21 { + compatible = "ovti,ov7740"; + reg = <0x21>; + clocks = <&isc>; + clock-names = "xvclk"; + assigned-clocks = <&isc>; + assigned-clock-rates = <24000000>; + + port { + ov7740_0: endpoint { + remote-endpoint = <&isc_0>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt b/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt index 55c9ad6f9599..32ced99d4244 100644 --- a/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt +++ b/Documentation/devicetree/bindings/media/exynos4-fimc-is.txt @@ -16,9 +16,10 @@ Required properties: - clocks : list of clock specifiers, corresponding to entries in clock-names property; - clock-names : must contain "ppmuispx", "ppmuispx", "lite0", "lite1" - "mpll", "sysreg", "isp", "drc", "fd", "mcuisp", "uart", - "ispdiv0", "ispdiv1", "mcuispdiv0", "mcuispdiv1", "aclk200", - "div_aclk200", "aclk400mcuisp", "div_aclk400mcuisp" entries, + "mpll", "sysreg", "isp", "drc", "fd", "mcuisp", "gicisp", + "pwm_isp", "mcuctl_isp", "uart", "ispdiv0", "ispdiv1", + "mcuispdiv0", "mcuispdiv1", "aclk200", "div_aclk200", + "aclk400mcuisp", "div_aclk400mcuisp" entries, matching entries in the clocks property. pmu subnode ----------- diff --git a/Documentation/devicetree/bindings/media/i2c/ad5820.txt b/Documentation/devicetree/bindings/media/i2c/ad5820.txt new file mode 100644 index 000000000000..5940ca11c021 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/ad5820.txt @@ -0,0 +1,19 @@ +* Analog Devices AD5820 autofocus coil + +Required Properties: + + - compatible: Must contain "adi,ad5820" + + - reg: I2C slave address + + - VANA-supply: supply of voltage for VANA pin + +Example: + + ad5820: coil@c { + compatible = "adi,ad5820"; + reg = <0x0c>; + + VANA-supply = <&vaux4>; + }; + diff --git a/Documentation/devicetree/bindings/media/i2c/adv7180.txt b/Documentation/devicetree/bindings/media/i2c/adv7180.txt index 0d501154dfb2..4da486f96ff6 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7180.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7180.txt @@ -15,6 +15,11 @@ Required Properties : "adi,adv7282" "adi,adv7282-m" +Optional Properties : +- powerdown-gpios: reference to the GPIO connected to the powerdown pin, + if any. + + Example: i2c0@1c22000 { diff --git a/Documentation/devicetree/bindings/media/meson-ir.txt b/Documentation/devicetree/bindings/media/meson-ir.txt index 407848e85f31..e7e3f3c4fc8f 100644 --- a/Documentation/devicetree/bindings/media/meson-ir.txt +++ b/Documentation/devicetree/bindings/media/meson-ir.txt @@ -1,7 +1,10 @@ * Amlogic Meson IR remote control receiver Required properties: - - compatible : should be "amlogic,meson6-ir" + - compatible : depending on the platform this should be one of: + - "amlogic,meson6-ir" + - "amlogic,meson8b-ir" + - "amlogic,meson-gxbb-ir" - reg : physical base address and length of the device registers - interrupts : a single specifier for the interrupt from the device diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt index 6a12960609d8..27f9b8e459ac 100644 --- a/Documentation/devicetree/bindings/media/renesas,fcp.txt +++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt @@ -7,12 +7,14 @@ conversion of AXI transactions in order to reduce the memory bandwidth. There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP for FDP (FCPF). Their configuration and behaviour depend on the module they -are paired with. These DT bindings currently support the FCPV only. +are paired with. These DT bindings currently support the FCPV and FCPF. - compatible: Must be one or more of the following - "renesas,r8a7795-fcpv" for R8A7795 (R-Car H3) compatible 'FCP for VSP' + - "renesas,r8a7795-fcpf" for R8A7795 (R-Car H3) compatible 'FCP for FDP' - "renesas,fcpv" for generic compatible 'FCP for VSP' + - "renesas,fcpf" for generic compatible 'FCP for FDP' When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first, followed by the @@ -21,6 +23,10 @@ are paired with. These DT bindings currently support the FCPV only. - reg: the register base and size for the device registers - clocks: Reference to the functional clock +Optional properties: + - power-domains : power-domain property defined with a power domain specifier + to respective power domain. + Device node example ------------------- @@ -29,4 +35,5 @@ Device node example compatible = "renesas,r8a7795-fcpv", "renesas,fcpv"; reg = <0 0xfea2f000 0 0x200>; clocks = <&cpg CPG_MOD 602>; + power-domains = <&sysc R8A7795_PD_A3VP>; }; diff --git a/Documentation/devicetree/bindings/media/st,st-hva.txt b/Documentation/devicetree/bindings/media/st,st-hva.txt new file mode 100644 index 000000000000..0d76174a1f7e --- /dev/null +++ b/Documentation/devicetree/bindings/media/st,st-hva.txt @@ -0,0 +1,24 @@ +st-hva: multi-format video encoder for STMicroelectronics SoC. + +Required properties: +- compatible: should be "st,st-hva". +- reg: HVA physical address location and length, esram address location and + length. +- reg-names: names of the registers listed in registers property in the same + order. +- interrupts: HVA interrupt number. +- clocks: from common clock binding: handle hardware IP needed clocks, the + number of clocks may depend on the SoC type. + See ../clock/clock-bindings.txt for details. +- clock-names: names of the clocks listed in clocks property in the same order. + +Example: + hva@8c85000{ + compatible = "st,st-hva"; + reg = <0x8c85000 0x400>, <0x6000000 0x40000>; + reg-names = "hva_registers", "hva_esram"; + interrupts = , + ; + clock-names = "clk_hva"; + clocks = <&clk_s_c0_flexgen CLK_HVA>; + }; diff --git a/Documentation/devicetree/bindings/media/stih-cec.txt b/Documentation/devicetree/bindings/media/stih-cec.txt new file mode 100644 index 000000000000..71c4b2f4bcef --- /dev/null +++ b/Documentation/devicetree/bindings/media/stih-cec.txt @@ -0,0 +1,25 @@ +STMicroelectronics STIH4xx HDMI CEC driver + +Required properties: + - compatible : value should be "st,stih-cec" + - reg : Physical base address of the IP registers and length of memory + mapped region. + - clocks : from common clock binding: handle to HDMI CEC clock + - interrupts : HDMI CEC interrupt number to the CPU. + - pinctrl-names: Contains only one value - "default" + - pinctrl-0: Specifies the pin control groups used for CEC hardware. + - resets: Reference to a reset controller + +Example for STIH407: + +sti-cec@094a087c { + compatible = "st,stih-cec"; + reg = <0x94a087c 0x64>; + clocks = <&clk_sysin>; + clock-names = "cec-clk"; + interrupts = ; + interrupt-names = "cec-irq"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_cec0_default>; + resets = <&softreset STIH407_LPM_SOFTRESET>; +}; diff --git a/Documentation/devicetree/bindings/memory-controllers/fsl/ddr.txt b/Documentation/devicetree/bindings/memory-controllers/fsl/ddr.txt new file mode 100644 index 000000000000..dde6d837083a --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/fsl/ddr.txt @@ -0,0 +1,29 @@ +Freescale DDR memory controller + +Properties: + +- compatible : Should include "fsl,chip-memory-controller" where + chip is the processor (bsc9132, mpc8572 etc.), or + "fsl,qoriq-memory-controller". +- reg : Address and size of DDR controller registers +- interrupts : Error interrupt of DDR controller +- little-endian : Specifies little-endian access to registers + If omitted, big-endian will be used. + +Example 1: + + memory-controller@2000 { + compatible = "fsl,bsc9132-memory-controller"; + reg = <0x2000 0x1000>; + interrupts = <16 2 1 8>; + }; + + +Example 2: + + ddr1: memory-controller@8000 { + compatible = "fsl,qoriq-memory-controller-v4.7", + "fsl,qoriq-memory-controller"; + reg = <0x8000 0x1000>; + interrupts = <16 2 1 23>; + }; diff --git a/Documentation/devicetree/bindings/mfd/ac100.txt b/Documentation/devicetree/bindings/mfd/ac100.txt new file mode 100644 index 000000000000..b8ef00667599 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ac100.txt @@ -0,0 +1,54 @@ +X-Powers AC100 Codec/RTC IC Device Tree bindings + +AC100 is a audio codec and RTC subsystem combo IC. The 2 parts are +separated, including power supplies and interrupt lines, but share +a common register address space and host interface. + +Required properties: +- compatible: "x-powers,ac100" +- reg: The I2C slave address or RSB hardware address for the chip +- sub-nodes: + - codec + - compatible: "x-powers,ac100-codec" + - interrupt-parent: The parent interrupt controller + - interrupts: SoC NMI / GPIO interrupt connected to the + IRQ_AUDIO pin + - #clock-cells: Shall be 0 + - clock-output-names: "4M_adda" + + - see clock/clock-bindings.txt for common clock bindings + + - rtc + - compatible: "x-powers,ac100-rtc" + - interrupt-parent: The parent interrupt controller + - interrupts: SoC NMI / GPIO interrupt connected to the + IRQ_RTC pin + - clocks: A phandle to the codec's "4M_adda" clock + - #clock-cells: Shall be 1 + - clock-output-names: "cko1_rtc", "cko2_rtc", "cko3_rtc" + + - see clock/clock-bindings.txt for common clock bindings + +Example: + +ac100: codec@e89 { + compatible = "x-powers,ac100"; + reg = <0xe89>; + + ac100_codec: codec { + compatible = "x-powers,ac100-codec"; + interrupt-parent = <&r_pio>; + interrupts = <0 9 IRQ_TYPE_LEVEL_LOW>; /* PL9 */ + #clock-cells = <0>; + clock-output-names = "4M_adda"; + }; + + ac100_rtc: rtc { + compatible = "x-powers,ac100-rtc"; + interrupt-parent = <&nmi_intc>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + clocks = <&ac100_codec>; + #clock-cells = <1>; + clock-output-names = "cko1_rtc", "cko2_rtc", "cko3_rtc"; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/act8945a.txt b/Documentation/devicetree/bindings/mfd/act8945a.txt index f71283055685..462819ac3da8 100644 --- a/Documentation/devicetree/bindings/mfd/act8945a.txt +++ b/Documentation/devicetree/bindings/mfd/act8945a.txt @@ -14,13 +14,6 @@ Example: reg = <0x5b>; status = "okay"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_charger_chglev>; - active-semi,chglev-gpio = <&pioA 12 GPIO_ACTIVE_HIGH>; - active-semi,input-voltage-threshold-microvolt = <6600>; - active-semi,precondition-timeout = <40>; - active-semi,total-timeout = <3>; - active-semi,vsel-high; regulators { @@ -73,4 +66,19 @@ Example: regulator-always-on; }; }; + + charger { + compatible = "active-semi,act8945a-charger"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_charger_chglev &pinctrl_charger_lbo &pinctrl_charger_irq>; + interrupt-parent = <&pioA>; + interrupts = <45 GPIO_ACTIVE_LOW>; + + active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,lbo-gpios = <&pioA 72 GPIO_ACTIVE_LOW>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + status = "okay"; + }; }; diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index a6e2ea41160c..8f2e2822238d 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -85,6 +85,24 @@ Optional properties: present, the number of values should be less than or equal to the number of inputs, unspecified inputs will use the chip default. + - wlf,max-channels-clocked : The maximum number of channels to be clocked on + each AIF, useful for I2S systems with multiple data lines being mastered. + Specify one cell for each AIF to be configured, specify zero for AIFs that + should be handled normally. + If present, number of cells must be less than or equal to the number of + AIFs. If less than the number of AIFs, for cells that have not been + specified the corresponding AIFs will be treated as default setting. + + - wlf,spk-fmt : PDM speaker data format, must contain 2 cells (OUT5 and OUT6). + See the datasheet for values. + The second cell is ignored for codecs that do not have OUT6 (wm5102, wm8997, + wm8998, wm1814) + + - wlf,spk-mute : PDM speaker mute setting, must contain 2 cells (OUT5 and OUT6). + See the datasheet for values. + The second cell is ignored for codecs that do not have OUT6 (wm5102, wm8997, + wm8998, wm1814) + - DCVDD-supply, MICVDD-supply : Power supplies, only need to be specified if they are being externally supplied. As covered in Documentation/devicetree/bindings/regulator/regulator.txt diff --git a/Documentation/devicetree/bindings/mfd/aspeed-scu.txt b/Documentation/devicetree/bindings/mfd/aspeed-scu.txt new file mode 100644 index 000000000000..4fc5b83726d6 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/aspeed-scu.txt @@ -0,0 +1,18 @@ +The Aspeed System Control Unit manages the global behaviour of the SoC, +configuring elements such as clocks, pinmux, and reset. + +Required properties: +- compatible: One of: + "aspeed,ast2400-scu", "syscon", "simple-mfd" + "aspeed,g4-scu", "syscon", "simple-mfd" + "aspeed,ast2500-scu", "syscon", "simple-mfd" + "aspeed,g5-scu", "syscon", "simple-mfd" + +- reg: contains the offset and length of the SCU memory region + +Example: + +syscon: syscon@1e6e2000 { + compatible = "aspeed,ast2400-scu", "syscon", "simple-mfd"; + reg = <0x1e6e2000 0x1a8>; +}; diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 585a95546288..8f3ad9ab4637 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -10,7 +10,8 @@ axp809 (X-Powers) Required properties: - compatible: "x-powers,axp152", "x-powers,axp202", "x-powers,axp209", - "x-powers,axp221", "x-powers,axp223", "x-powers,axp809" + "x-powers,axp221", "x-powers,axp223", "x-powers,axp806", + "x-powers,axp809" - reg: The I2C slave address or RSB hardware address for the AXP chip - interrupt-parent: The parent interrupt controller - interrupts: SoC NMI / GPIO interrupt connected to the PMIC's IRQ pin @@ -47,7 +48,6 @@ Optional properties for DCDC regulators: probably makes sense for HiFi audio related applications that aren't battery constrained. - AXP202/AXP209 regulators, type, and corresponding input supply names: Regulator Type Supply Name Notes @@ -86,6 +86,30 @@ LDO_IO1 : LDO : ips-supply : GPIO 1 RTC_LDO : LDO : ips-supply : always on DRIVEVBUS : Enable output : drivevbus-supply : external regulator +AXP806 regulators, type, and corresponding input supply names: + +Regulator Type Supply Name Notes +--------- ---- ----------- ----- +DCDCA : DC-DC buck : vina-supply : poly-phase capable +DCDCB : DC-DC buck : vinb-supply : poly-phase capable +DCDCC : DC-DC buck : vinc-supply : poly-phase capable +DCDCD : DC-DC buck : vind-supply : poly-phase capable +DCDCE : DC-DC buck : vine-supply : poly-phase capable +ALDO1 : LDO : aldoin-supply : shared supply +ALDO2 : LDO : aldoin-supply : shared supply +ALDO3 : LDO : aldoin-supply : shared supply +BLDO1 : LDO : bldoin-supply : shared supply +BLDO2 : LDO : bldoin-supply : shared supply +BLDO3 : LDO : bldoin-supply : shared supply +BLDO4 : LDO : bldoin-supply : shared supply +CLDO1 : LDO : cldoin-supply : shared supply +CLDO2 : LDO : cldoin-supply : shared supply +CLDO3 : LDO : cldoin-supply : shared supply +SW : On/Off Switch : swin-supply + +Additionally, the AXP806 DC-DC regulators support poly-phase arrangements +for higher output current. The possible groupings are: A+B, A+B+C, D+E. + AXP809 regulators, type, and corresponding input supply names: Regulator Type Supply Name Notes diff --git a/Documentation/devicetree/bindings/mfd/lp873x.txt b/Documentation/devicetree/bindings/mfd/lp873x.txt new file mode 100644 index 000000000000..52766c2035f7 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/lp873x.txt @@ -0,0 +1,59 @@ +TI LP873X PMIC MFD driver + +Required properties: + - compatible: "ti,lp8732", "ti,lp8733" + - reg: I2C slave address. + - gpio-controller: Marks the device node as a GPIO Controller. + - #gpio-cells: Should be two. The first cell is the pin number and + the second cell is used to specify flags. + See ../gpio/gpio.txt for more information. + - regulators: List of child nodes that specify the regulator + initialization data. +Example: + +pmic: lp8733@60 { + compatible = "ti,lp8733"; + reg = <0x60>; + gpio-controller; + #gpio-cells = <2>; + + regulators { + lp8733_buck0: buck0 { + regulator-name = "lp8733-buck0"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1400000>; + regulator-min-microamp = <1500000>; + regulator-max-microamp = <4000000>; + regulator-ramp-delay = <10000>; + regulator-always-on; + regulator-boot-on; + }; + + lp8733_buck1: buck1 { + regulator-name = "lp8733-buck1"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1400000>; + regulator-min-microamp = <1500000>; + regulator-max-microamp = <4000000>; + regulator-ramp-delay = <10000>; + regulator-boot-on; + regulator-always-on; + }; + + lp8733_ldo0: ldo0 { + regulator-name = "lp8733-ldo0"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3000000>; + regulator-boot-on; + regulator-always-on; + }; + + lp8733_ldo1: ldo1 { + regulator-name = "lp8733-ldo1"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <3000000>; + regulator-always-on; + regulator-boot-on; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/max77693.txt b/Documentation/devicetree/bindings/mfd/max77693.txt index d3425846aa5b..6a1ae3a2b77f 100644 --- a/Documentation/devicetree/bindings/mfd/max77693.txt +++ b/Documentation/devicetree/bindings/mfd/max77693.txt @@ -17,28 +17,28 @@ Required properties: - interrupt-parent : The parent interrupt controller. Optional properties: -- regulators : The regulators of max77693 have to be instantiated under subnod +- regulators : The regulators of max77693 have to be instantiated under subnode named "regulators" using the following format. regulators { - regualtor-compatible = ESAFEOUT1/ESAFEOUT2/CHARGER - standard regulator constratints[*]. + regulator-compatible = ESAFEOUT1/ESAFEOUT2/CHARGER + standard regulator constraints[*]. }; [*] refer Documentation/devicetree/bindings/regulator/regulator.txt - haptic : The MAX77693 haptic device utilises a PWM controlled motor to provide users with tactile feedback. PWM period and duty-cycle are varied in - order to provide the approprite level of feedback. + order to provide the appropriate level of feedback. Required properties: - - compatible : Must be "maxim,max77693-hpatic" + - compatible : Must be "maxim,max77693-haptic" - haptic-supply : power supply for the haptic motor [*] refer Documentation/devicetree/bindings/regulator/regulator.txt - pwms : phandle to the physical PWM(Pulse Width Modulation) device. PWM properties should be named "pwms". And number of cell is different for each pwm device. - To get more informations, please refer to documentaion. + To get more information, please refer to documentation. [*] refer Documentation/devicetree/bindings/pwm/pwm.txt - charger : Node configuring the charger driver. diff --git a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt index f24f33409164..37a088f9a648 100644 --- a/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt +++ b/Documentation/devicetree/bindings/mfd/qcom-pm8xxx.txt @@ -62,6 +62,7 @@ The below bindings specify the set of valid subnodes. "qcom,pm8058-rtc" "qcom,pm8921-rtc" "qcom,pm8941-rtc" + "qcom,pm8018-rtc" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/mfd/qcom-rpm.txt b/Documentation/devicetree/bindings/mfd/qcom-rpm.txt index b98b291a31ba..485bc59fcc48 100644 --- a/Documentation/devicetree/bindings/mfd/qcom-rpm.txt +++ b/Documentation/devicetree/bindings/mfd/qcom-rpm.txt @@ -13,6 +13,7 @@ frequencies. "qcom,rpm-msm8660" "qcom,rpm-msm8960" "qcom,rpm-ipq8064" + "qcom,rpm-mdm9615" - reg: Usage: required @@ -59,6 +60,7 @@ Regulator nodes are identified by their compatible: "qcom,rpm-pm8058-regulators" "qcom,rpm-pm8901-regulators" "qcom,rpm-pm8921-regulators" + "qcom,rpm-pm8018-regulators" - vdd_l0_l1_lvs-supply: - vdd_l2_l11_l12-supply: @@ -137,6 +139,15 @@ Regulator nodes are identified by their compatible: Definition: reference to regulator supplying the input pin, as described in the data sheet +- vin_lvs1-supply: +- vdd_l7-supply: +- vdd_l8-supply: +- vdd_l9_l10_l11_l12-supply: + Usage: optional (pm8018 only) + Value type: + Definition: reference to regulator supplying the input pin, as + described in the data sheet + The regulator node houses sub-nodes for each regulator within the device. Each sub-node is identified using the node's name, with valid values listed for each of the pmics below. @@ -156,6 +167,10 @@ pm8921: l29, lvs1, lvs2, lvs3, lvs4, lvs5, lvs6, lvs7, usb-switch, hdmi-switch, ncp +pm8018: + s1, s2, s3, s4, s5, , l1, l2, l3, l4, l5, l6, l7, l8, l9, l10, l11, + l12, l14, lvs1 + The content of each sub-node is defined by the standard binding for regulators - see regulator.txt - with additional custom properties described below: diff --git a/Documentation/devicetree/bindings/mfd/rk808.txt b/Documentation/devicetree/bindings/mfd/rk808.txt index 4ca6aab4273a..9636ae8d8d41 100644 --- a/Documentation/devicetree/bindings/mfd/rk808.txt +++ b/Documentation/devicetree/bindings/mfd/rk808.txt @@ -1,7 +1,11 @@ -RK808 Power Management Integrated Circuit +RK8XX Power Management Integrated Circuit + +The rk8xx family current members: +rk808 +rk818 Required properties: -- compatible: "rockchip,rk808" +- compatible: "rockchip,rk808", "rockchip,rk818" - reg: I2C slave address - interrupt-parent: The parent interrupt controller. - interrupts: the interrupt outputs of the controller. @@ -13,6 +17,8 @@ Optional properties: default output clock name - rockchip,system-power-controller: Telling whether or not this pmic is controlling the system power. + +Optional RK808 properties: - vcc1-supply: The input supply for DCDC_REG1 - vcc2-supply: The input supply for DCDC_REG2 - vcc3-supply: The input supply for DCDC_REG3 @@ -29,7 +35,20 @@ Optional properties: the gpio controller. If DVS GPIOs aren't present, voltage changes will happen very quickly with no slow ramp time. -Regulators: All the regulators of RK808 to be instantiated shall be +Optional RK818 properties: +- vcc1-supply: The input supply for DCDC_REG1 +- vcc2-supply: The input supply for DCDC_REG2 +- vcc3-supply: The input supply for DCDC_REG3 +- vcc4-supply: The input supply for DCDC_REG4 +- boost-supply: The input supply for DCDC_BOOST +- vcc6-supply: The input supply for LDO_REG1 and LDO_REG2 +- vcc7-supply: The input supply for LDO_REG3, LDO_REG5 and LDO_REG7 +- vcc8-supply: The input supply for LDO_REG4, LDO_REG6 and LDO_REG8 +- vcc9-supply: The input supply for LDO_REG9 and SWITCH_REG +- h_5v-supply: The input supply for HDMI_SWITCH +- usb-supply: The input supply for OTG_SWITCH + +Regulators: All the regulators of RK8XX to be instantiated shall be listed in a child node named 'regulators'. Each regulator is represented by a child node of the 'regulators' node. @@ -48,6 +67,18 @@ number as described in RK808 datasheet. - SWITCH_REGn - valid values for n are 1 to 2 +Following regulators of the RK818 PMIC block are supported. Note that +the 'n' in regulator name, as in DCDC_REGn or LDOn, represents the DCDC or LDO +number as described in RK818 datasheet. + + - DCDC_REGn + - valid values for n are 1 to 4. + - LDO_REGn + - valid values for n are 1 to 9. + - SWITCH_REG + - HDMI_SWITCH + - OTG_SWITCH + Standard regulator bindings are used inside regulator subnodes. Check Documentation/devicetree/bindings/regulator/regulator.txt for more details diff --git a/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt new file mode 100644 index 000000000000..c110e118b79f --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/samsung,exynos5433-lpass.txt @@ -0,0 +1,70 @@ +Samsung Exynos SoC Low Power Audio Subsystem (LPASS) + +Required properties: + + - compatible : "samsung,exynos5433-lpass" + - reg : should contain the LPASS top SFR region location + and size + - samsung,pmu-syscon : the phandle to the Power Management Unit node + - #address-cells : should be 1 + - #size-cells : should be 1 + - ranges : must be present + +Each IP block of the Low Power Audio Subsystem should be specified as +an optional sub-node. For "samsung,exynos5433-lpass" compatible this includes: +UART, SLIMBUS, PCM, I2S, DMAC, Timers 0...4, VIC, WDT 0...1 devices. + +Bindings of the sub-nodes are described in: + ../serial/samsung_uart.txt + ../sound/samsung-i2s.txt + ../dma/arm-pl330.txt + + +Example: + +audio-subsystem { + compatible = "samsung,exynos5433-lpass"; + reg = <0x11400000 0x100>, <0x11500000 0x08>; + samsung,pmu-syscon = <&pmu_system_controller>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + adma: adma@11420000 { + compatible = "arm,pl330", "arm,primecell"; + reg = <0x11420000 0x1000>; + interrupts = <0 73 0>; + clocks = <&cmu_aud CLK_ACLK_DMAC>; + clock-names = "apb_pclk"; + #dma-cells = <1>; + #dma-channels = <8>; + #dma-requests = <32>; + }; + + i2s0: i2s0@11440000 { + compatible = "samsung,exynos7-i2s"; + reg = <0x11440000 0x100>; + dmas = <&adma 0 &adma 2>; + dma-names = "tx", "rx"; + interrupts = <0 70 0>; + clocks = <&cmu_aud CLK_PCLK_AUD_I2S>, + <&cmu_aud CLK_SCLK_AUD_I2S>, + <&cmu_aud CLK_SCLK_I2S_BCLK>; + clock-names = "iis", "i2s_opclk0", "i2s_opclk1"; + pinctrl-names = "default"; + pinctrl-0 = <&i2s0_bus>; + status = "disabled"; + }; + + serial_3: serial@11460000 { + compatible = "samsung,exynos5433-uart"; + reg = <0x11460000 0x100>; + interrupts = <0 67 0>; + clocks = <&cmu_aud CLK_PCLK_AUD_UART>, + <&cmu_aud CLK_SCLK_AUD_UART>; + clock-names = "uart", "clk_uart_baud0"; + pinctrl-names = "default"; + pinctrl-0 = <&uart_aud_bus>; + status = "disabled"; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/stmpe.txt b/Documentation/devicetree/bindings/mfd/stmpe.txt index 3fb68bfefc8b..f9065a5781a2 100644 --- a/Documentation/devicetree/bindings/mfd/stmpe.txt +++ b/Documentation/devicetree/bindings/mfd/stmpe.txt @@ -4,7 +4,7 @@ STMPE is an MFD device which may expose the following inbuilt devices: gpio, keypad, touchscreen, adc, pwm, rotator. Required properties: - - compatible : "st,stmpe[610|801|811|1601|2401|2403]" + - compatible : "st,stmpe[610|801|811|1600|1601|2401|2403]" - reg : I2C/SPI address of the device Optional properties: diff --git a/Documentation/devicetree/bindings/mfd/twl6040.txt b/Documentation/devicetree/bindings/mfd/twl6040.txt index e6afdfa3543d..9a98ee7c323d 100644 --- a/Documentation/devicetree/bindings/mfd/twl6040.txt +++ b/Documentation/devicetree/bindings/mfd/twl6040.txt @@ -12,6 +12,7 @@ Required properties: - interrupt-parent: The parent interrupt controller - gpio-controller: - #gpio-cells = <1>: twl6040 provides GPO lines. +- #clock-cells = <0>; twl6040 is a provider of pdmclk which is used by McPDM - twl6040,audpwron-gpio: Power on GPIO line for the twl6040 - vio-supply: Regulator for the twl6040 VIO supply diff --git a/Documentation/devicetree/bindings/mips/brcm/soc.txt b/Documentation/devicetree/bindings/mips/brcm/soc.txt index 4a7e030e4f9b..e4e1cd91fb1f 100644 --- a/Documentation/devicetree/bindings/mips/brcm/soc.txt +++ b/Documentation/devicetree/bindings/mips/brcm/soc.txt @@ -2,9 +2,9 @@ Required properties: -- compatible: "brcm,bcm3384", "brcm,bcm33843" +- compatible: "brcm,bcm3368", "brcm,bcm3384", "brcm,bcm33843" "brcm,bcm3384-viper", "brcm,bcm33843-viper" - "brcm,bcm6328", "brcm,bcm6358", "brcm,bcm6368", + "brcm,bcm6328", "brcm,bcm6358", "brcm,bcm6362", "brcm,bcm6368", "brcm,bcm63168", "brcm,bcm63268", "brcm,bcm7125", "brcm,bcm7346", "brcm,bcm7358", "brcm,bcm7360", "brcm,bcm7362", "brcm,bcm7420", "brcm,bcm7425" diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt index 3404afa9b938..49df630bd44f 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt @@ -36,6 +36,9 @@ Optional Properties: - #clock-cells: If specified this should be the value <0>. With this property in place we will export a clock representing the Card Clock. This clock is expected to be consumed by our PHY. You must also specify + - xlnx,fails-without-test-cd: when present, the controller doesn't work when + the CD line is not connected properly, and the line is not connected + properly. Test mode can be used to force the controller to function. Example: sdhci@e0100000 { diff --git a/Documentation/devicetree/bindings/mmc/brcm,bcm7425-sdhci.txt b/Documentation/devicetree/bindings/mmc/brcm,bcm7425-sdhci.txt deleted file mode 100644 index 82847174c37d..000000000000 --- a/Documentation/devicetree/bindings/mmc/brcm,bcm7425-sdhci.txt +++ /dev/null @@ -1,36 +0,0 @@ -* BROADCOM BRCMSTB/BMIPS SDHCI Controller - -This file documents differences between the core properties in mmc.txt -and the properties used by the sdhci-brcmstb driver. - -NOTE: The driver disables all UHS speed modes by default and depends -on Device Tree properties to enable them for SoC/Board combinations -that support them. - -Required properties: -- compatible: "brcm,bcm7425-sdhci" - -Refer to clocks/clock-bindings.txt for generic clock consumer properties. - -Example: - - sdhci@f03e0100 { - compatible = "brcm,bcm7425-sdhci"; - reg = <0xf03e0000 0x100>; - interrupts = <0x0 0x26 0x0>; - sdhci,auto-cmd12; - clocks = <&sw_sdio>; - sd-uhs-sdr50; - sd-uhs-ddr50; - }; - - sdhci@f03e0300 { - non-removable; - bus-width = <0x8>; - compatible = "brcm,bcm7425-sdhci"; - reg = <0xf03e0200 0x100>; - interrupts = <0x0 0x27 0x0>; - sdhci,auto-cmd12; - clocks = ; - mmc-hs200-1_8v; - }; diff --git a/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt new file mode 100644 index 000000000000..733b64a4d8eb --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/brcm,sdhci-brcmstb.txt @@ -0,0 +1,38 @@ +* BROADCOM BRCMSTB/BMIPS SDHCI Controller + +This file documents differences between the core properties in mmc.txt +and the properties used by the sdhci-brcmstb driver. + +NOTE: The driver disables all UHS speed modes by default and depends +on Device Tree properties to enable them for SoC/Board combinations +that support them. + +Required properties: +- compatible: should be one of the following + - "brcm,bcm7425-sdhci" + - "brcm,bcm7445-sdhci" + +Refer to clocks/clock-bindings.txt for generic clock consumer properties. + +Example: + + sdhci@f03e0100 { + compatible = "brcm,bcm7425-sdhci"; + reg = <0xf03e0000 0x100>; + interrupts = <0x0 0x26 0x0>; + sdhci,auto-cmd12; + clocks = <&sw_sdio>; + sd-uhs-sdr50; + sd-uhs-ddr50; + }; + + sdhci@f03e0300 { + non-removable; + bus-width = <0x8>; + compatible = "brcm,bcm7425-sdhci"; + reg = <0xf03e0200 0x100>; + interrupts = <0x0 0x27 0x0>; + sdhci,auto-cmd12; + clocks = ; + mmc-hs200-1_8v; + }; diff --git a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt index ce0e76749671..e25436861867 100644 --- a/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt +++ b/Documentation/devicetree/bindings/mmc/mmc-pwrseq-simple.txt @@ -16,6 +16,8 @@ Optional properties: See ../clocks/clock-bindings.txt for details. - clock-names : Must include the following entry: "ext_clock" (External clock provided to the card). +- post-power-on-delay-ms : Delay in ms after powering the card and + de-asserting the reset-gpios (if any) Example: diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index 22d1e1f3f38b..8a377827695b 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -75,6 +75,17 @@ Optional SDIO properties: - wakeup-source: Enables wake up of host system on SDIO IRQ assertion (Legacy property supported: "enable-sdio-wakeup") +MMC power +--------- + +Controllers may implement power control from both the connected cards and +the IO signaling (for example to change to high-speed 1.8V signalling). If +the system supports this, then the following two properties should point +to valid regulator nodes: + +- vqmmc-supply: supply node for IO line power +- vmmc-supply: supply node for card's power + MMC power sequences: -------------------- @@ -102,11 +113,13 @@ Required host node properties when using function subnodes: - #size-cells: should be zero. Required function subnode properties: -- compatible: name of SDIO function following generic names recommended practice - reg: Must contain the SDIO function number of the function this subnode describes. A value of 0 denotes the memory SD function, values from 1 to 7 denote the SDIO functions. +Optional function subnode properties: +- compatible: name of SDIO function following generic names recommended practice + Examples -------- diff --git a/Documentation/devicetree/bindings/mmc/sdhci-st.txt b/Documentation/devicetree/bindings/mmc/sdhci-st.txt index 88faa91125bf..3cd4c43a3260 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-st.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-st.txt @@ -10,7 +10,7 @@ Required properties: subsystem (mmcss) inside the FlashSS (available in STiH407 SoC family). -- clock-names: Should be "mmc". +- clock-names: Should be "mmc" and "icn". (NB: The latter is not compulsory) See: Documentation/devicetree/bindings/resource-names.txt - clocks: Phandle to the clock. See: Documentation/devicetree/bindings/clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/mmc/sunxi-mmc.txt b/Documentation/devicetree/bindings/mmc/sunxi-mmc.txt index 4bf41d833804..55cdd804cdba 100644 --- a/Documentation/devicetree/bindings/mmc/sunxi-mmc.txt +++ b/Documentation/devicetree/bindings/mmc/sunxi-mmc.txt @@ -8,7 +8,12 @@ as the speed of SD standard 3.0. Absolute maximum transfer rate is 200MB/s Required properties: - - compatible : "allwinner,sun4i-a10-mmc" or "allwinner,sun5i-a13-mmc" + - compatible : should be one of: + * "allwinner,sun4i-a10-mmc" + * "allwinner,sun5i-a13-mmc" + * "allwinner,sun7i-a20-mmc" + * "allwinner,sun9i-a80-mmc" + * "allwinner,sun50i-a64-mmc" - reg : mmc controller base registers - clocks : a list with 4 phandle + clock specifier pairs - clock-names : must contain "ahb", "mmc", "output" and "sample" diff --git a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt index 8636f5ae97e5..4e00e859e885 100644 --- a/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt +++ b/Documentation/devicetree/bindings/mmc/synopsys-dw-mshc.txt @@ -39,6 +39,10 @@ Required Properties: Optional properties: +* resets: phandle + reset specifier pair, intended to represent hardware + reset signal present internally in some host controller IC designs. + See Documentation/devicetree/bindings/reset/reset.txt for details. + * clocks: from common clock binding: handle to biu and ciu clocks for the bus interface unit clock and the card interface unit clock. diff --git a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt index 0f610d4b5b00..13df9c2399c3 100644 --- a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt +++ b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt @@ -23,6 +23,7 @@ Required properties: "renesas,sdhi-r8a7793" - SDHI IP on R8A7793 SoC "renesas,sdhi-r8a7794" - SDHI IP on R8A7794 SoC "renesas,sdhi-r8a7795" - SDHI IP on R8A7795 SoC + "renesas,sdhi-r8a7796" - SDHI IP on R8A7796 SoC Optional properties: - toshiba,mmc-wrprotect-disable: write-protect detection is unavailable diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt index 3733300de8dd..b05601600083 100644 --- a/Documentation/devicetree/bindings/mtd/nand.txt +++ b/Documentation/devicetree/bindings/mtd/nand.txt @@ -35,6 +35,15 @@ Optional NAND chip properties: - nand-ecc-step-size: integer representing the number of data bytes that are covered by a single ECC step. +- nand-ecc-maximize: boolean used to specify that you want to maximize ECC + strength. The maximum ECC strength is both controller and + chip dependent. The controller side has to select the ECC + config providing the best strength and taking the OOB area + size constraint into account. + This is particularly useful when only the in-band area is + used by the upper layers, and you want to make your NAND + as reliable as possible. + The ECC strength and ECC step size properties define the correction capability of a controller. Together, they say a controller can correct "{strength} bit errors per {size} bytes". diff --git a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt index e41b2d59ca7f..f591ab782dbc 100644 --- a/Documentation/devicetree/bindings/net/apm-xgene-enet.txt +++ b/Documentation/devicetree/bindings/net/apm-xgene-enet.txt @@ -47,6 +47,9 @@ Optional properties: Valid values are between 0 to 7, that maps to 273, 589, 899, 1222, 1480, 1806, 2147, 2464 ps Default value is 2, which corresponds to 899 ps +- rxlos-gpios: Input gpio from SFP+ module to indicate availability of + incoming signal. + Example: menetclk: menetclk { diff --git a/Documentation/devicetree/bindings/net/brcm,amac.txt b/Documentation/devicetree/bindings/net/brcm,amac.txt new file mode 100644 index 000000000000..ba5ecc1041a5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,amac.txt @@ -0,0 +1,24 @@ +Broadcom AMAC Ethernet Controller Device Tree Bindings +------------------------------------------------------------- + +Required properties: + - compatible: "brcm,amac" or "brcm,nsp-amac" + - reg: Address and length of the GMAC registers, + Address and length of the GMAC IDM registers + - reg-names: Names of the registers. Must have both "amac_base" and + "idm_base" + - interrupts: Interrupt number + +Optional properties: +- mac-address: See ethernet.txt file in the same directory + +Examples: + +amac0: ethernet@18022000 { + compatible = "brcm,nsp-amac"; + reg = <0x18022000 0x1000>, + <0x18110000 0x1000>; + reg-names = "amac_base", "idm_base"; + interrupts = ; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt index 30d487597ecb..fb40891ee606 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -6,9 +6,13 @@ Required properties: - reg: addresses and length of the register sets for the device, must be 6 pairs of register addresses and lengths - interrupts: interrupts for the devices, must be two interrupts +- #address-cells: must be 1, see dsa/dsa.txt +- #size-cells: must be 0, see dsa/dsa.txt + +Deprecated binding required properties: + - dsa,mii-bus: phandle to the MDIO bus controller, see dsa/dsa.txt - dsa,ethernet: phandle to the CPU network interface controller, see dsa/dsa.txt -- #size-cells: must be 0 - #address-cells: must be 2, see dsa/dsa.txt Subnodes: @@ -39,6 +43,45 @@ Optional properties: Example: +switch_top@f0b00000 { + compatible = "simple-bus"; + #size-cells = <1>; + #address-cells = <1>; + ranges = <0 0xf0b00000 0x40804>; + + ethernet_switch@0 { + compatible = "brcm,bcm7445-switch-v4.0"; + #size-cells = <0>; + #address-cells = <1>; + reg = <0x0 0x40000 + 0x40000 0x110 + 0x40340 0x30 + 0x40380 0x30 + 0x40400 0x34 + 0x40600 0x208>; + reg-names = "core", "reg", intrl2_0", "intrl2_1", + "fcb, "acb"; + interrupts = <0 0x18 0 + 0 0x19 0>; + brcm,num-gphy = <1>; + brcm,num-rgmii-ports = <2>; + brcm,fcb-pause-override; + brcm,acb-packets-inflight; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + label = "gphy"; + reg = <0>; + }; + }; + }; +}; + +Example using the old DSA DeviceTree binding: + switch_top@f0b00000 { compatible = "simple-bus"; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/net/brcm,bgmac-nsp.txt b/Documentation/devicetree/bindings/net/brcm,bgmac-nsp.txt new file mode 100644 index 000000000000..022946caa7e2 --- /dev/null +++ b/Documentation/devicetree/bindings/net/brcm,bgmac-nsp.txt @@ -0,0 +1,24 @@ +Broadcom GMAC Ethernet Controller Device Tree Bindings +------------------------------------------------------------- + +Required properties: + - compatible: "brcm,bgmac-nsp" + - reg: Address and length of the GMAC registers, + Address and length of the GMAC IDM registers + - reg-names: Names of the registers. Must have both "gmac_base" and + "idm_base" + - interrupts: Interrupt number + +Optional properties: +- mac-address: See ethernet.txt file in the same directory + +Examples: + +gmac0: ethernet@18022000 { + compatible = "brcm,bgmac-nsp"; + reg = <0x18022000 0x1000>, + <0x18110000 0x1000>; + reg-names = "gmac_base", "idm_base"; + interrupts = ; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/net/dsa/qca8k.txt b/Documentation/devicetree/bindings/net/dsa/qca8k.txt new file mode 100644 index 000000000000..9c67ee4890d7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/qca8k.txt @@ -0,0 +1,89 @@ +* Qualcomm Atheros QCA8xxx switch family + +Required properties: + +- compatible: should be "qca,qca8337" +- #size-cells: must be 0 +- #address-cells: must be 1 + +Subnodes: + +The integrated switch subnode should be specified according to the binding +described in dsa/dsa.txt. As the QCA8K switches do not have a N:N mapping of +port and PHY id, each subnode describing a port needs to have a valid phandle +referencing the internal PHY connected to it. The CPU port of this switch is +always port 0. + +Example: + + + &mdio0 { + phy_port1: phy@0 { + reg = <0>; + }; + + phy_port2: phy@1 { + reg = <1>; + }; + + phy_port3: phy@2 { + reg = <2>; + }; + + phy_port4: phy@3 { + reg = <3>; + }; + + phy_port5: phy@4 { + reg = <4>; + }; + + switch0@0 { + compatible = "qca,qca8337"; + #address-cells = <1>; + #size-cells = <0>; + + reg = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + label = "cpu"; + ethernet = <&gmac1>; + phy-mode = "rgmii"; + }; + + port@1 { + reg = <1>; + label = "lan1"; + phy-handle = <&phy_port1>; + }; + + port@2 { + reg = <2>; + label = "lan2"; + phy-handle = <&phy_port2>; + }; + + port@3 { + reg = <3>; + label = "lan3"; + phy-handle = <&phy_port3>; + }; + + port@4 { + reg = <4>; + label = "lan4"; + phy-handle = <&phy_port4>; + }; + + port@5 { + reg = <5>; + label = "wan"; + phy-handle = <&phy_port5>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index 5d88f37480b6..e1d76812419c 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -11,8 +11,8 @@ The following properties are common to the Ethernet controllers: the maximum frame size (there's contradiction in ePAPR). - phy-mode: string, operation mode of the PHY interface; supported values are "mii", "gmii", "sgmii", "qsgmii", "tbi", "rev-mii", "rmii", "rgmii", "rgmii-id", - "rgmii-rxid", "rgmii-txid", "rtbi", "smii", "xgmii"; this is now a de-facto - standard property; + "rgmii-rxid", "rgmii-txid", "rtbi", "smii", "xgmii", "trgmii"; this is now a + de-facto standard property; - phy-connection-type: the same as "phy-mode" property but described in ePAPR; - phy-handle: phandle, specifies a reference to a node representing a PHY device; this property is described in ePAPR and so preferred; diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index b5a42df4c928..1506e948610c 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -21,6 +21,7 @@ Required properties: - clock-names: Tuple listing input clock names. Required elements: 'pclk', 'hclk' Optional elements: 'tx_clk' + Optional elements: 'rx_clk' applies to cdns,zynqmp-gem - clocks: Phandles to input clocks. Optional properties for PHY child node: diff --git a/Documentation/devicetree/bindings/net/mediatek-net.txt b/Documentation/devicetree/bindings/net/mediatek-net.txt index 32eaaca04d9b..c010fafc66a8 100644 --- a/Documentation/devicetree/bindings/net/mediatek-net.txt +++ b/Documentation/devicetree/bindings/net/mediatek-net.txt @@ -25,13 +25,15 @@ Optional properties: - interrupt-parent: Should be the phandle for the interrupt controller that services interrupts for this device - * Ethernet MAC node Required properties: - compatible: Should be "mediatek,eth-mac" - reg: The number of the MAC -- phy-handle: see ethernet.txt file in the same directory. +- phy-handle: see ethernet.txt file in the same directory and + the phy-mode "trgmii" required being provided when reg + is equal to 0 and the MAC uses fixed-link to connect + with internal switch such as MT7530. Example: diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt index ec633d74a8a8..89e62ddc69ca 100644 --- a/Documentation/devicetree/bindings/net/meson-dwmac.txt +++ b/Documentation/devicetree/bindings/net/meson-dwmac.txt @@ -1,18 +1,32 @@ * Amlogic Meson DWMAC Ethernet controller The device inherits all the properties of the dwmac/stmmac devices -described in the file net/stmmac.txt with the following changes. +described in the file stmmac.txt in the current directory with the +following changes. -Required properties: +Required properties on all platforms: -- compatible: should be "amlogic,meson6-dwmac" along with "snps,dwmac" - and any applicable more detailed version number - described in net/stmmac.txt +- compatible: Depending on the platform this should be one of: + - "amlogic,meson6-dwmac" + - "amlogic,meson8b-dwmac" + - "amlogic,meson-gxbb-dwmac" + Additionally "snps,dwmac" and any applicable more + detailed version number described in net/stmmac.txt + should be used. -- reg: should contain a register range for the dwmac controller and - another one for the Amlogic specific configuration +- reg: The first register range should be the one of the DWMAC + controller. The second range is is for the Amlogic specific + configuration (for example the PRG_ETHERNET register range + on Meson8b and newer) -Example: +Required properties on Meson8b and newer: +- clock-names: Should contain the following: + - "stmmaceth" - see stmmac.txt + - "clkin0" - first parent clock of the internal mux + - "clkin1" - second parent clock of the internal mux + + +Example for Meson6: ethmac: ethernet@c9410000 { compatible = "amlogic,meson6-dwmac", "snps,dwmac"; @@ -23,3 +37,18 @@ Example: clocks = <&clk81>; clock-names = "stmmaceth"; } + +Example for GXBB: + ethmac: ethernet@c9410000 { + compatible = "amlogic,meson-gxbb-dwmac", "snps,dwmac"; + reg = <0x0 0xc9410000 0x0 0x10000>, + <0x0 0xc8834540 0x0 0x8>; + interrupts = <0 8 1>; + interrupt-names = "macirq"; + clocks = <&clkc CLKID_ETH>, + <&clkc CLKID_FCLK_DIV2>, + <&clkc CLKID_MPLL2>; + clock-names = "stmmaceth", "clkin0", "clkin1"; + phy-mode = "rgmii"; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt index f9c32adab5c6..c35b5b428a7f 100644 --- a/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt +++ b/Documentation/devicetree/bindings/net/micrel-ksz90x1.txt @@ -34,16 +34,17 @@ KSZ9031: All skew control options are specified in picoseconds. The minimum value is 0, and the maximum is property-dependent. The increment - step is 60ps. + step is 60ps. The default value is the neutral setting, so setting + rxc-skew-ps=<0> actually results in -900 picoseconds adjustment. Optional properties: - Maximum value of 1860: + Maximum value of 1860, default value 900: - rxc-skew-ps : Skew control of RX clock pad - txc-skew-ps : Skew control of TX clock pad - Maximum value of 900: + Maximum value of 900, default value 420: - rxdv-skew-ps : Skew control of RX CTL pad - txen-skew-ps : Skew control of TX CTL pad diff --git a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt new file mode 100644 index 000000000000..99c7eb0a00c8 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt @@ -0,0 +1,58 @@ +* Microsemi - vsc8531 Giga bit ethernet phy + +Required properties: +- compatible : Should contain phy id as "ethernet-phy-idAAAA.BBBB" + The PHY device uses the binding described in + Documentation/devicetree/bindings/net/phy.txt + +Optional properties: +- vsc8531,vddmac : The vddmac in mV. +- vsc8531,edge-slowdown : % the edge should be slowed down relative to + the fastest possible edge time. Native sign + need not enter. + Edge rate sets the drive strength of the MAC + interface output signals. Changing the drive + strength will affect the edge rate of the output + signal. The goal of this setting is to help + reduce electrical emission (EMI) by being able + to reprogram drive strength and in effect slow + down the edge rate if desired. Table 1 shows the + impact to the edge rate per VDDMAC supply for each + drive strength setting. + Ref: Table:1 - Edge rate change below. + +Note: see dt-bindings/net/mscc-phy-vsc8531.h for applicable values + +Table: 1 - Edge rate change +----------------------------------------------------------------| +| Edge Rate Change (VDDMAC) | +| | +| 3300 mV 2500 mV 1800 mV 1500 mV | +|---------------------------------------------------------------| +| Default Deafult Default Default | +| (Fastest) (recommended) (recommended) | +|---------------------------------------------------------------| +| -2% -3% -5% -6% | +|---------------------------------------------------------------| +| -4% -6% -9% -14% | +|---------------------------------------------------------------| +| -7% -10% -16% -21% | +|(recommended) (recommended) | +|---------------------------------------------------------------| +| -10% -14% -23% -29% | +|---------------------------------------------------------------| +| -17% -23% -35% -42% | +|---------------------------------------------------------------| +| -29% -37% -52% -58% | +|---------------------------------------------------------------| +| -53% -63% -76% -77% | +| (slowest) | +|---------------------------------------------------------------| + +Example: + + vsc8531_0: ethernet-phy@0 { + compatible = "ethernet-phy-id0007.0570"; + vsc8531,vddmac = <3300>; + vsc8531,edge-slowdown = <21>; + }; diff --git a/Documentation/devicetree/bindings/net/qcom-emac.txt b/Documentation/devicetree/bindings/net/qcom-emac.txt new file mode 100644 index 000000000000..346e6c7f47b7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qcom-emac.txt @@ -0,0 +1,111 @@ +Qualcomm Technologies EMAC Gigabit Ethernet Controller + +This network controller consists of two devices: a MAC and an SGMII +internal PHY. Each device is represented by a device tree node. A phandle +connects the MAC node to its corresponding internal phy node. Another +phandle points to the external PHY node. + +Required properties: + +MAC node: +- compatible : Should be "qcom,fsm9900-emac". +- reg : Offset and length of the register regions for the device +- interrupts : Interrupt number used by this controller +- mac-address : The 6-byte MAC address. If present, it is the default + MAC address. +- internal-phy : phandle to the internal PHY node +- phy-handle : phandle the the external PHY node + +Internal PHY node: +- compatible : Should be "qcom,fsm9900-emac-sgmii" or "qcom,qdf2432-emac-sgmii". +- reg : Offset and length of the register region(s) for the device +- interrupts : Interrupt number used by this controller + +The external phy child node: +- reg : The phy address + +Example: + +FSM9900: + +soc { + #address-cells = <1>; + #size-cells = <1>; + + emac0: ethernet@feb20000 { + compatible = "qcom,fsm9900-emac"; + reg = <0xfeb20000 0x10000>, + <0xfeb36000 0x1000>; + interrupts = <76>; + + clocks = <&gcc 0>, <&gcc 1>, <&gcc 3>, <&gcc 4>, <&gcc 5>, + <&gcc 6>, <&gcc 7>; + clock-names = "axi_clk", "cfg_ahb_clk", "high_speed_clk", + "mdio_clk", "tx_clk", "rx_clk", "sys_clk"; + + internal-phy = <&emac_sgmii>; + + phy-handle = <&phy0>; + + #address-cells = <1>; + #size-cells = <0>; + phy0: ethernet-phy@0 { + reg = <0>; + }; + + pinctrl-names = "default"; + pinctrl-0 = <&mdio_pins_a>; + }; + + emac_sgmii: ethernet@feb38000 { + compatible = "qcom,fsm9900-emac-sgmii"; + reg = <0xfeb38000 0x1000>; + interrupts = <80>; + }; + + tlmm: pinctrl@fd510000 { + compatible = "qcom,fsm9900-pinctrl"; + + mdio_pins_a: mdio { + state { + pins = "gpio123", "gpio124"; + function = "mdio"; + }; + }; + }; + + +QDF2432: + +soc { + #address-cells = <2>; + #size-cells = <2>; + + emac0: ethernet@38800000 { + compatible = "qcom,fsm9900-emac"; + reg = <0x0 0x38800000 0x0 0x10000>, + <0x0 0x38816000 0x0 0x1000>; + interrupts = <0 256 4>; + + clocks = <&gcc 0>, <&gcc 1>, <&gcc 3>, <&gcc 4>, <&gcc 5>, + <&gcc 6>, <&gcc 7>; + clock-names = "axi_clk", "cfg_ahb_clk", "high_speed_clk", + "mdio_clk", "tx_clk", "rx_clk", "sys_clk"; + + internal-phy = <&emac_sgmii>; + + phy-handle = <&phy0>; + + #address-cells = <1>; + #size-cells = <0>; + phy0: ethernet-phy@4 { + reg = <4>; + }; + }; + + emac_sgmii: ethernet@410400 { + compatible = "qcom,qdf2432-emac-sgmii"; + reg = <0x0 0x00410400 0x0 0xc00>, /* Base address */ + <0x0 0x00410000 0x0 0x400>; /* Per-lane digital */ + interrupts = <0 254 1>; + }; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index c8ac222eac67..b519503be51a 100644 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt @@ -10,6 +10,7 @@ Required properties: "renesas,etheravb-r8a7793" if the device is a part of R8A7793 SoC. "renesas,etheravb-r8a7794" if the device is a part of R8A7794 SoC. "renesas,etheravb-r8a7795" if the device is a part of R8A7795 SoC. + "renesas,etheravb-r8a7796" if the device is a part of R8A7796 SoC. "renesas,etheravb-rcar-gen2" for generic R-Car Gen 2 compatible interface. "renesas,etheravb-rcar-gen3" for generic R-Car Gen 3 compatible interface. @@ -33,7 +34,7 @@ Optional properties: - interrupt-parent: the phandle for the interrupt controller that services interrupts for this device. - interrupt-names: A list of interrupt names. - For the R8A7795 SoC this property is mandatory; + For the R8A779[56] SoCs this property is mandatory; it should include one entry per channel, named "ch%u", where %u is the channel number ranging from 0 to 24. For other SoCs this property is optional; if present diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt index cccd945fc45b..95383c5131fc 100644 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt @@ -3,8 +3,12 @@ Rockchip SoC RK3288 10/100/1000 Ethernet driver(GMAC) The device node has following properties. Required properties: - - compatible: Can be one of "rockchip,rk3228-gmac", "rockchip,rk3288-gmac", - "rockchip,rk3368-gmac" + - compatible: should be "rockchip,-gamc" + "rockchip,rk3228-gmac": found on RK322x SoCs + "rockchip,rk3288-gmac": found on RK3288 SoCs + "rockchip,rk3366-gmac": found on RK3366 SoCs + "rockchip,rk3368-gmac": found on RK3368 SoCs + "rockchip,rk3399-gmac": found on RK3399 SoCs - reg: addresses and length of the register sets for the device. - interrupts: Should contain the GMAC interrupts. - interrupt-names: Should contain the interrupt names "macirq". diff --git a/Documentation/devicetree/bindings/net/sh_eth.txt b/Documentation/devicetree/bindings/net/sh_eth.txt index 2f6ec85fda8e..0115c85a2425 100644 --- a/Documentation/devicetree/bindings/net/sh_eth.txt +++ b/Documentation/devicetree/bindings/net/sh_eth.txt @@ -5,6 +5,8 @@ interface contains. Required properties: - compatible: "renesas,gether-r8a7740" if the device is a part of R8A7740 SoC. + "renesas,ether-r8a7743" if the device is a part of R8A7743 SoC. + "renesas,ether-r8a7745" if the device is a part of R8A7745 SoC. "renesas,ether-r8a7778" if the device is a part of R8A7778 SoC. "renesas,ether-r8a7779" if the device is a part of R8A7779 SoC. "renesas,ether-r8a7790" if the device is a part of R8A7790 SoC. diff --git a/Documentation/devicetree/bindings/net/smsc911x.txt b/Documentation/devicetree/bindings/net/smsc911x.txt index 3fed3c124411..16c3a9501f5d 100644 --- a/Documentation/devicetree/bindings/net/smsc911x.txt +++ b/Documentation/devicetree/bindings/net/smsc911x.txt @@ -3,9 +3,11 @@ Required properties: - compatible : Should be "smsc,lan", "smsc,lan9115" - reg : Address and length of the io space for SMSC LAN -- interrupts : Should contain SMSC LAN interrupt line -- interrupt-parent : Should be the phandle for the interrupt controller - that services interrupts for this device +- interrupts : one or two interrupt specifiers + - The first interrupt is the SMSC LAN interrupt line + - The second interrupt (if present) is the PME (power + management event) interrupt that is able to wake up the host + system with a 50ms pulse on network activity - phy-mode : See ethernet.txt file in the same directory Optional properties: @@ -21,6 +23,10 @@ Optional properties: external PHY - smsc,save-mac-address : Indicates that mac address needs to be saved before resetting the controller +- reset-gpios : a GPIO line connected to the RESET (active low) signal + of the device. On many systems this is wired high so the device goes + out of reset at power-on, but if it is under program control, this + optional GPIO can wake up in response to it. Examples: @@ -29,7 +35,8 @@ lan9220@f4000000 { reg = <0xf4000000 0x2000000>; phy-mode = "mii"; interrupt-parent = <&gpio1>; - interrupts = <31>; + interrupts = <31>, <32>; + reset-gpios = <&gpio1 30 GPIO_ACTIVE_LOW>; reg-io-width = <4>; smsc,irq-push-pull; }; diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt index 51f8d2eba8d8..d93f71ce8346 100644 --- a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt +++ b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt @@ -1,21 +1,111 @@ * Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC) +This binding supports the Synopsys Designware Ethernet QoS (Quality Of Service) +IP block. The IP supports multiple options for bus type, clocking and reset +structure, and feature list. Consequently, a number of properties and list +entries in properties are marked as optional, or only required in specific HW +configurations. Required properties: -- compatible: Should be "snps,dwc-qos-ethernet-4.10" +- compatible: One of: + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10" + Represents the IP core when integrated into the Axis ARTPEC-6 SoC. + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10" + Represents the IP core when integrated into the NVIDIA Tegra186 SoC. + - "snps,dwc-qos-ethernet-4.10" + This combination is deprecated. It should be treated as equivalent to + "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10". It is supported to be + compatible with earlier revisions of this binding. - reg: Address and length of the register set for the device -- clocks: Phandles to the reference clock and the bus clock -- clock-names: Should be "phy_ref_clk" for the reference clock and "apb_pclk" - for the bus clock. +- clocks: Phandle and clock specifiers for each entry in clock-names, in the + same order. See ../clock/clock-bindings.txt. +- clock-names: May contain any/all of the following depending on the IP + configuration, in any order: + - "tx" + The EQOS transmit path clock. The HW signal name is clk_tx_i. + In some configurations (e.g. GMII/RGMII), this clock also drives the PHY TX + path. In other configurations, other clocks (such as tx_125, rmii) may + drive the PHY TX path. + - "rx" + The EQOS receive path clock. The HW signal name is clk_rx_i. + In some configurations (e.g. GMII/RGMII), this clock is derived from the + PHY's RX clock output. In other configurations, other clocks (such as + rx_125, rmii) may drive the EQOS RX path. + In cases where the PHY clock is directly fed into the EQOS receive path + without intervening logic, the DT need not represent this clock, since it + is assumed to be fully under the control of the PHY device/driver. In + cases where SoC integration adds additional logic to this path, such as a + SW-controlled clock gate, this clock should be represented in DT. + - "slave_bus" + The CPU/slave-bus (CSR) interface clock. This applies to any bus type; + APB, AHB, AXI, etc. The HW signal name is hclk_i (AHB) or clk_csr_i (other + buses). + - "master_bus" + The master bus interface clock. Only required in configurations that use a + separate clock for the master and slave bus interfaces. The HW signal name + is hclk_i (AHB) or aclk_i (AXI). + - "ptp_ref" + The PTP reference clock. The HW signal name is clk_ptp_ref_i. + - "phy_ref_clk" + This clock is deprecated and should not be used by new compatible values. + It is equivalent to "tx". + - "apb_pclk" + This clock is deprecated and should not be used by new compatible values. + It is equivalent to "slave_bus". + + Note: Support for additional IP configurations may require adding the + following clocks to this list in the future: clk_rx_125_i, clk_tx_125_i, + clk_pmarx_0_i, clk_pmarx1_i, clk_rmii_i, clk_revmii_rx_i, clk_revmii_tx_i. + Configurations exist where multiple similar clocks are used at once, e.g. all + of clk_rx_125_i, clk_pmarx_0_i, clk_pmarx1_i. For this reason it is best to + extend the binding with a separate clock-names entry for each of those RX + clocks, rather than repurposing the existing "rx" clock-names entry as a + generic/logical clock in a similar fashion to "master_bus" and "slave_bus". + This will allow easy support for configurations that support multiple PHY + interfaces using a mux, and hence need to have explicit control over + specific RX clocks. + + The following compatible values require the following set of clocks: + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10": + - "slave_bus" + - "master_bus" + - "rx" + - "tx" + - "ptp_ref" + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10": + - "slave_bus" + - "master_bus" + - "tx" + - "ptp_ref" + - "snps,dwc-qos-ethernet-4.10" (deprecated): + - "phy_ref_clk" + - "apb_clk" - interrupt-parent: Should be the phandle for the interrupt controller that services interrupts for this device - interrupts: Should contain the core's combined interrupt signal - phy-mode: See ethernet.txt file in the same directory +- resets: Phandle and reset specifiers for each entry in reset-names, in the + same order. See ../reset/reset.txt. +- reset-names: May contain any/all of the following depending on the IP + configuration, in any order: + - "eqos". The reset to the entire module. The HW signal name is hreset_n + (AHB) or aresetn_i (AXI). + + The following compatible values require the following set of resets: + (the reset properties may be omitted if empty) + - "nvidia,tegra186-eqos", "snps,dwc-qos-ethernet-4.10": + - "eqos". + - "axis,artpec6-eqos", "snps,dwc-qos-ethernet-4.10": + - None. + - "snps,dwc-qos-ethernet-4.10" (deprecated): + - None. Optional properties: - dma-coherent: Present if dma operations are coherent - mac-address: See ethernet.txt in the same directory - local-mac-address: See ethernet.txt in the same directory +- phy-reset-gpios: Phandle and specifier for any GPIO used to reset the PHY. + See ../gpio/gpio.txt. - snps,en-lpi: If present it enables use of the AXI low-power interface - snps,write-requests: Number of write requests that the AXI port can issue. It depends on the SoC configuration. @@ -52,6 +142,7 @@ ethernet2@40010000 { reg = <0x40010000 0x4000>; phy-handle = <&phy2>; phy-mode = "gmii"; + phy-reset-gpios = <&gpioctlr 43 GPIO_ACTIVE_LOW>; snps,en-tx-lpi-clockgating; snps,en-lpi; diff --git a/Documentation/devicetree/bindings/net/stm32-dwmac.txt b/Documentation/devicetree/bindings/net/stm32-dwmac.txt new file mode 100644 index 000000000000..c35afb7e956a --- /dev/null +++ b/Documentation/devicetree/bindings/net/stm32-dwmac.txt @@ -0,0 +1,32 @@ +STMicroelectronics STM32 / MCU DWMAC glue layer controller + +This file documents platform glue layer for stmmac. +Please see stmmac.txt for the other unchanged properties. + +The device node has following properties. + +Required properties: +- compatible: Should be "st,stm32-dwmac" to select glue, and + "snps,dwmac-3.50a" to select IP version. +- clocks: Must contain a phandle for each entry in clock-names. +- clock-names: Should be "stmmaceth" for the host clock. + Should be "mac-clk-tx" for the MAC TX clock. + Should be "mac-clk-rx" for the MAC RX clock. +- st,syscon : Should be phandle/offset pair. The phandle to the syscon node which + encompases the glue register, and the offset of the control register. +Example: + + ethernet@40028000 { + compatible = "st,stm32-dwmac", "snps,dwmac-3.50a"; + status = "disabled"; + reg = <0x40028000 0x8000>; + reg-names = "stmmaceth"; + interrupts = <0 61 0>, <0 62 0>; + interrupt-names = "macirq", "eth_wake_irq"; + clock-names = "stmmaceth", "mac-clk-tx", "mac-clk-rx"; + clocks = <&rcc 0 25>, <&rcc 0 26>, <&rcc 0 27>; + st,syscon = <&syscfg 0x4>; + snps,pbl = <8>; + snps,mixed-burst; + dma-ranges; + }; diff --git a/Documentation/devicetree/bindings/net/wireless/esp,esp8089.txt b/Documentation/devicetree/bindings/net/wireless/esp,esp8089.txt new file mode 100644 index 000000000000..19331bb4ff6e --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/esp,esp8089.txt @@ -0,0 +1,31 @@ +Espressif ESP8089 wireless SDIO devices + +This node provides properties for controlling the ESP8089 wireless device. +The node is expected to be specified as a child node to the SDIO controller +that connects the device to the system. + +Required properties: + + - compatible : Should be "esp,esp8089". + +Optional properties: + - esp,crystal-26M-en: Integer value for the crystal_26M_en firmware parameter + +Example: + +&mmc1 { + #address-cells = <1>; + #size-cells = <0>; + + vmmc-supply = <®_dldo1>; + mmc-pwrseq = <&wifi_pwrseq>; + bus-width = <4>; + non-removable; + status = "okay"; + + esp8089: sdio_wifi@1 { + compatible = "esp,esp8089"; + reg = <1>; + esp,crystal-26M-en = <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt b/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt new file mode 100644 index 000000000000..038dda48b8e6 --- /dev/null +++ b/Documentation/devicetree/bindings/net/xilinx_gmii2rgmii.txt @@ -0,0 +1,35 @@ +XILINX GMIITORGMII Converter Driver Device Tree Bindings +-------------------------------------------------------- + +The Gigabit Media Independent Interface (GMII) to Reduced Gigabit Media +Independent Interface (RGMII) core provides the RGMII between RGMII-compliant +Ethernet physical media devices (PHY) and the Gigabit Ethernet controller. +This core can be used in all three modes of operation(10/100/1000 Mb/s). +The Management Data Input/Output (MDIO) interface is used to configure the +Speed of operation. This core can switch dynamically between the three +Different speed modes by configuring the conveter register through mdio write. + +This converter sits between the ethernet MAC and the external phy. +MAC <==> GMII2RGMII <==> RGMII_PHY + +For more details about mdio please refer phy.txt file in the same directory. + +Required properties: +- compatible : Should be "xlnx,gmii-to-rgmii-1.0" +- reg : The ID number for the phy, usually a small integer +- phy-handle : Should point to the external phy device. + See ethernet.txt file in the same directory. + +Example: + mdio { + #address-cells = <1>; + #size-cells = <0>; + phy: ethernet-phy@0 { + ...... + }; + gmiitorgmii: gmiitorgmii@8 { + compatible = "xlnx,gmii-to-rgmii-1.0"; + reg = <8>; + phy-handle = <&phy>; + }; + }; diff --git a/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt b/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt new file mode 100644 index 000000000000..fafd85bd67a6 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt @@ -0,0 +1,39 @@ += Amlogic eFuse device tree bindings = + +Required properties: +- compatible: should be "amlogic,meson-gxbb-efuse" + += Data cells = +Are child nodes of eFuse, bindings of which as described in +bindings/nvmem/nvmem.txt + +Example: + + efuse: efuse { + compatible = "amlogic,meson-gxbb-efuse"; + #address-cells = <1>; + #size-cells = <1>; + + sn: sn@14 { + reg = <0x14 0x10>; + }; + + eth_mac: eth_mac@34 { + reg = <0x34 0x10>; + }; + + bid: bid@46 { + reg = <0x46 0x30>; + }; + }; + += Data consumers = +Are device nodes which consume nvmem data cells. + +For example: + + eth_mac { + ... + nvmem-cells = <ð_mac>; + nvmem-cell-names = "eth_mac"; + }; diff --git a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt index 8f86ab3b1046..94aeeeabadd5 100644 --- a/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/rockchip-efuse.txt @@ -1,11 +1,20 @@ = Rockchip eFuse device tree bindings = Required properties: -- compatible: Should be "rockchip,rockchip-efuse" +- compatible: Should be one of the following. + - "rockchip,rk3066a-efuse" - for RK3066a SoCs. + - "rockchip,rk3188-efuse" - for RK3188 SoCs. + - "rockchip,rk3288-efuse" - for RK3288 SoCs. + - "rockchip,rk3399-efuse" - for RK3399 SoCs. - reg: Should contain the registers location and exact eFuse size - clocks: Should be the clock id of eFuse - clock-names: Should be "pclk_efuse" +Deprecated properties: +- compatible: "rockchip,rockchip-efuse" + Old efuse compatible value compatible to rk3066a, rk3188 and rk3288 + efuses + = Data cells = Are child nodes of eFuse, bindings of which as described in bindings/nvmem/nvmem.txt @@ -13,7 +22,7 @@ bindings/nvmem/nvmem.txt Example: efuse: efuse@ffb40000 { - compatible = "rockchip,rockchip-efuse"; + compatible = "rockchip,rk3288-efuse"; reg = <0xffb40000 0x20>; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt index 330a45b5f0b5..5ecaea1e6eee 100644 --- a/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt +++ b/Documentation/devicetree/bindings/pci/axis,artpec6-pcie.txt @@ -24,16 +24,17 @@ Example: compatible = "axis,artpec6-pcie", "snps,dw-pcie"; reg = <0xf8050000 0x2000 0xf8040000 0x1000 - 0xc0000000 0x1000>; + 0xc0000000 0x2000>; reg-names = "dbi", "phy", "config"; #address-cells = <3>; #size-cells = <2>; device_type = "pci"; /* downstream I/O */ - ranges = <0x81000000 0 0x00010000 0xc0010000 0 0x00010000 + ranges = <0x81000000 0 0 0xc0002000 0 0x00010000 /* non-prefetchable memory */ - 0x82000000 0 0xc0020000 0xc0020000 0 0x1ffe0000>; + 0x82000000 0 0xc0012000 0xc0012000 0 0x1ffee000>; num-lanes = <2>; + bus-range = <0x00 0xff>; interrupts = ; interrupt-names = "msi"; #interrupt-cells = <1>; diff --git a/Documentation/devicetree/bindings/pci/designware-pcie.txt b/Documentation/devicetree/bindings/pci/designware-pcie.txt index 6c5322c55411..1392c705ceca 100644 --- a/Documentation/devicetree/bindings/pci/designware-pcie.txt +++ b/Documentation/devicetree/bindings/pci/designware-pcie.txt @@ -17,6 +17,8 @@ Required properties: - num-lanes: number of lanes to use Optional properties: +- num-viewport: number of view ports configured in hardware. If a platform + does not specify it, the driver assumes 2. - num-lanes: number of lanes to use (this property should be specified unless the link is brought already up in BIOS) - reset-gpio: gpio pin number of power good signal @@ -44,4 +46,5 @@ Example configuration: interrupts = <25>, <24>; #interrupt-cells = <1>; num-lanes = <1>; + num-viewport = <3>; }; diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt new file mode 100644 index 000000000000..56c829621b9a --- /dev/null +++ b/Documentation/devicetree/bindings/pci/pci-iommu.txt @@ -0,0 +1,171 @@ +This document describes the generic device tree binding for describing the +relationship between PCI(e) devices and IOMMU(s). + +Each PCI(e) device under a root complex is uniquely identified by its Requester +ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and +Function number. + +For the purpose of this document, when treated as a numeric value, a RID is +formatted such that: + +* Bits [15:8] are the Bus number. +* Bits [7:3] are the Device number. +* Bits [2:0] are the Function number. +* Any other bits required for padding must be zero. + +IOMMUs may distinguish PCI devices through sideband data derived from the +Requester ID. While a given PCI device can only master through one IOMMU, a +root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per +bus). + +The generic 'iommus' property is insufficient to describe this relationship, +and a mechanism is required to map from a PCI device to its IOMMU and sideband +data. + +For generic IOMMU bindings, see +Documentation/devicetree/bindings/iommu/iommu.txt. + + +PCI root complex +================ + +Optional properties +------------------- + +- iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier + data. + + The property is an arbitrary number of tuples of + (rid-base,iommu,iommu-base,length). + + Any RID r in the interval [rid-base, rid-base + length) is associated with + the listed IOMMU, with the iommu-specifier (r - rid-base + iommu-base). + +- iommu-map-mask: A mask to be applied to each Requester ID prior to being + mapped to an iommu-specifier per the iommu-map property. + + +Example (1) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + iommu: iommu@a { + reg = <0xa 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the IOMMU is the RID, + * identity-mapped. + */ + iommu-map = <0x0 &iommu 0x0 0x10000>; + }; +}; + + +Example (2) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + iommu: iommu@a { + reg = <0xa 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the IOMMU is the RID with the + * function bits masked out. + */ + iommu-map = <0x0 &iommu 0x0 0x10000>; + iommu-map-mask = <0xfff8>; + }; +}; + + +Example (3) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + iommu: iommu@a { + reg = <0xa 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * The sideband data provided to the IOMMU is the RID, + * but the high bits of the bus number are flipped. + */ + iommu-map = <0x0000 &iommu 0x8000 0x8000>, + <0x8000 &iommu 0x0000 0x8000>; + }; +}; + + +Example (4) +=========== + +/ { + #address-cells = <1>; + #size-cells = <1>; + + iommu_a: iommu@a { + reg = <0xa 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + iommu_b: iommu@b { + reg = <0xb 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + iommu_c: iommu@c { + reg = <0xc 0x1>; + compatible = "vendor,some-iommu"; + #iommu-cells = <1>; + }; + + pci: pci@f { + reg = <0xf 0x1>; + compatible = "vendor,pcie-root-complex"; + device_type = "pci"; + + /* + * Devices with bus number 0-127 are mastered via IOMMU + * a, with sideband data being RID[14:0]. + * Devices with bus number 128-255 are mastered via + * IOMMU b, with sideband data being RID[14:0]. + * No devices master via IOMMU c. + */ + iommu-map = <0x0000 &iommu_a 0x0000 0x8000>, + <0x8000 &iommu_b 0x0000 0x8000>; + }; +}; diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie.txt new file mode 100644 index 000000000000..ba67b39939c1 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/rockchip-pcie.txt @@ -0,0 +1,106 @@ +* Rockchip AXI PCIe Root Port Bridge DT description + +Required properties: +- #address-cells: Address representation for root ports, set to <3> +- #size-cells: Size representation for root ports, set to <2> +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- compatible: Should contain "rockchip,rk3399-pcie" +- reg: Two register ranges as listed in the reg-names property +- reg-names: Must include the following names + - "axi-base" + - "apb-base" +- clocks: Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must include the following entries: + - "aclk" + - "aclk-perf" + - "hclk" + - "pm" +- msi-map: Maps a Requester ID to an MSI controller and associated + msi-specifier data. See ./pci-msi.txt +- phys: From PHY bindings: Phandle for the Generic PHY for PCIe. +- phy-names: MUST be "pcie-phy". +- interrupts: Three interrupt entries must be specified. +- interrupt-names: Must include the following names + - "sys" + - "legacy" + - "client" +- resets: Must contain five entries for each entry in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include the following names + - "core" + - "mgmt" + - "mgmt-sticky" + - "pipe" +- pinctrl-names : The pin control state names +- pinctrl-0: The "default" pinctrl state +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- interrupt-map-mask and interrupt-map: standard PCI properties + +Optional Property: +- ep-gpios: contain the entry for pre-reset gpio +- num-lanes: number of lanes to use +- vpcie3v3-supply: The phandle to the 3.3v regulator to use for PCIe. +- vpcie1v8-supply: The phandle to the 1.8v regulator to use for PCIe. +- vpcie0v9-supply: The phandle to the 0.9v regulator to use for PCIe. + +*Interrupt controller child node* +The core controller provides a single interrupt for legacy INTx. The PCIe node +should contain an interrupt controller node as a target for the PCI +'interrupt-map' property. This node represents the domain at which the four +INTx interrupts are decoded and routed. + + +Required properties for Interrupt controller child node: +- interrupt-controller: identifies the node as an interrupt controller +- #address-cells: specifies the number of cells needed to encode an + address. The value must be 0. +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. + +Example: + +pcie0: pcie@f8000000 { + compatible = "rockchip,rk3399-pcie"; + #address-cells = <3>; + #size-cells = <2>; + clocks = <&cru ACLK_PCIE>, <&cru ACLK_PERF_PCIE>, + <&cru PCLK_PCIE>, <&cru SCLK_PCIE_PM>; + clock-names = "aclk", "aclk-perf", + "hclk", "pm"; + bus-range = <0x0 0x1>; + interrupts = , + , + ; + interrupt-names = "sys", "legacy", "client"; + assigned-clocks = <&cru SCLK_PCIEPHY_REF>; + assigned-clock-parents = <&cru SCLK_PCIEPHY_REF100M>; + assigned-clock-rates = <100000000>; + ep-gpios = <&gpio3 13 GPIO_ACTIVE_HIGH>; + ranges = <0x83000000 0x0 0xfa000000 0x0 0xfa000000 0x0 0x600000 + 0x81000000 0x0 0xfa600000 0x0 0xfa600000 0x0 0x100000>; + num-lanes = <4>; + msi-map = <0x0 &its 0x0 0x1000>; + reg = <0x0 0xf8000000 0x0 0x2000000>, <0x0 0xfd000000 0x0 0x1000000>; + reg-names = "axi-base", "apb-base"; + resets = <&cru SRST_PCIE_CORE>, <&cru SRST_PCIE_MGMT>, + <&cru SRST_PCIE_MGMT_STICKY>, <&cru SRST_PCIE_PIPE>; + reset-names = "core", "mgmt", "mgmt-sticky", "pipe"; + phys = <&pcie_phy>; + phy-names = "pcie-phy"; + pinctrl-names = "default"; + pinctrl-0 = <&pcie_clkreq>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie0_intc 0>, + <0 0 0 2 &pcie0_intc 1>, + <0 0 0 3 &pcie0_intc 2>, + <0 0 0 4 &pcie0_intc 3>; + pcie0_intc: interrupt-controller { + interrupt-controller; + #address-cells = <0>; + #interrupt-cells = <1>; + }; +}; diff --git a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt index 337fc97d18c9..3259798a1192 100644 --- a/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt +++ b/Documentation/devicetree/bindings/pci/xilinx-nwl-pcie.txt @@ -55,9 +55,10 @@ nwl_pcie: pcie@fd0e0000 { msi-parent = <&nwl_pcie>; reg = <0x0 0xfd0e0000 0x0 0x1000>, <0x0 0xfd480000 0x0 0x1000>, - <0x0 0xe0000000 0x0 0x1000000>; + <0x80 0x00000000 0x0 0x1000000>; reg-names = "breg", "pcireg", "cfg"; - ranges = <0x02000000 0x00000000 0xe1000000 0x00000000 0xe1000000 0 0x0f000000>; + ranges = <0x02000000 0x00000000 0xe0000000 0x00000000 0xe0000000 0x00000000 0x10000000 /* non-prefetchable memory */ + 0x43000000 0x00000006 0x00000000 0x00000006 0x00000000 0x00000002 0x00000000>;/* prefetchable memory */ pcie_intc: legacy-interrupt-controller { interrupt-controller; diff --git a/Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt b/Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt new file mode 100644 index 000000000000..afb11cf693c0 --- /dev/null +++ b/Documentation/devicetree/bindings/perf/apm-xgene-pmu.txt @@ -0,0 +1,112 @@ +* APM X-Gene SoC PMU bindings + +This is APM X-Gene SoC PMU (Performance Monitoring Unit) module. +The following PMU devices are supported: + + L3C - L3 cache controller + IOB - IO bridge + MCB - Memory controller bridge + MC - Memory controller + +The following section describes the SoC PMU DT node binding. + +Required properties: +- compatible : Shall be "apm,xgene-pmu" for revision 1 or + "apm,xgene-pmu-v2" for revision 2. +- regmap-csw : Regmap of the CPU switch fabric (CSW) resource. +- regmap-mcba : Regmap of the MCB-A (memory bridge) resource. +- regmap-mcbb : Regmap of the MCB-B (memory bridge) resource. +- reg : First resource shall be the CPU bus PMU resource. +- interrupts : Interrupt-specifier for PMU IRQ. + +Required properties for L3C subnode: +- compatible : Shall be "apm,xgene-pmu-l3c". +- reg : First resource shall be the L3C PMU resource. + +Required properties for IOB subnode: +- compatible : Shall be "apm,xgene-pmu-iob". +- reg : First resource shall be the IOB PMU resource. + +Required properties for MCB subnode: +- compatible : Shall be "apm,xgene-pmu-mcb". +- reg : First resource shall be the MCB PMU resource. +- enable-bit-index : The bit indicates if the according MCB is enabled. + +Required properties for MC subnode: +- compatible : Shall be "apm,xgene-pmu-mc". +- reg : First resource shall be the MC PMU resource. +- enable-bit-index : The bit indicates if the according MC is enabled. + +Example: + csw: csw@7e200000 { + compatible = "apm,xgene-csw", "syscon"; + reg = <0x0 0x7e200000 0x0 0x1000>; + }; + + mcba: mcba@7e700000 { + compatible = "apm,xgene-mcb", "syscon"; + reg = <0x0 0x7e700000 0x0 0x1000>; + }; + + mcbb: mcbb@7e720000 { + compatible = "apm,xgene-mcb", "syscon"; + reg = <0x0 0x7e720000 0x0 0x1000>; + }; + + pmu: pmu@78810000 { + compatible = "apm,xgene-pmu-v2"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + regmap-csw = <&csw>; + regmap-mcba = <&mcba>; + regmap-mcbb = <&mcbb>; + reg = <0x0 0x78810000 0x0 0x1000>; + interrupts = <0x0 0x22 0x4>; + + pmul3c@7e610000 { + compatible = "apm,xgene-pmu-l3c"; + reg = <0x0 0x7e610000 0x0 0x1000>; + }; + + pmuiob@7e940000 { + compatible = "apm,xgene-pmu-iob"; + reg = <0x0 0x7e940000 0x0 0x1000>; + }; + + pmucmcb@7e710000 { + compatible = "apm,xgene-pmu-mcb"; + reg = <0x0 0x7e710000 0x0 0x1000>; + enable-bit-index = <0>; + }; + + pmucmcb@7e730000 { + compatible = "apm,xgene-pmu-mcb"; + reg = <0x0 0x7e730000 0x0 0x1000>; + enable-bit-index = <1>; + }; + + pmucmc@7e810000 { + compatible = "apm,xgene-pmu-mc"; + reg = <0x0 0x7e810000 0x0 0x1000>; + enable-bit-index = <0>; + }; + + pmucmc@7e850000 { + compatible = "apm,xgene-pmu-mc"; + reg = <0x0 0x7e850000 0x0 0x1000>; + enable-bit-index = <1>; + }; + + pmucmc@7e890000 { + compatible = "apm,xgene-pmu-mc"; + reg = <0x0 0x7e890000 0x0 0x1000>; + enable-bit-index = <2>; + }; + + pmucmc@7e8d0000 { + compatible = "apm,xgene-pmu-mc"; + reg = <0x0 0x7e8d0000 0x0 0x1000>; + enable-bit-index = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt new file mode 100644 index 000000000000..09aeba94538d --- /dev/null +++ b/Documentation/devicetree/bindings/phy/bcm-ns-usb3-phy.txt @@ -0,0 +1,23 @@ +Driver for Broadcom Northstar USB 3.0 PHY + +Required properties: + +- compatible: one of: "brcm,ns-ax-usb3-phy", "brcm,ns-bx-usb3-phy". +- reg: register mappings for DMP (Device Management Plugin) and ChipCommon B + MMI. +- reg-names: "dmp" and "ccb-mii" + +Initialization of USB 3.0 PHY depends on Northstar version. There are currently +three known series: Ax, Bx and Cx. +Known A0: BCM4707 rev 0 +Known B0: BCM4707 rev 4, BCM53573 rev 2 +Known B1: BCM4707 rev 6 +Known C0: BCM47094 rev 0 + +Example: + usb3-phy { + compatible = "brcm,ns-ax-usb3-phy"; + reg = <0x18105000 0x1000>, <0x18003000 0x1000>; + reg-names = "dmp", "ccb-mii"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/meson-usb2-phy.txt b/Documentation/devicetree/bindings/phy/meson-usb2-phy.txt new file mode 100644 index 000000000000..9da5ea234154 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/meson-usb2-phy.txt @@ -0,0 +1,27 @@ +* Amlogic USB2 PHY + +Required properties: +- compatible: Depending on the platform this should be one of: + "amlogic,meson8b-usb2-phy" + "amlogic,meson-gxbb-usb2-phy" +- reg: The base address and length of the registers +- #phys-cells: should be 0 (see phy-bindings.txt in this directory) +- clocks: phandle and clock identifier for the phy clocks +- clock-names: "usb_general" and "usb" + +Optional properties: +- resets: reference to the reset controller +- phy-supply: see phy-bindings.txt in this directory + + +Example: + +usb0_phy: usb_phy@0 { + compatible = "amlogic,meson-gxbb-usb2-phy"; + #phy-cells = <0>; + reg = <0x0 0x0 0x0 0x20>; + resets = <&reset RESET_USB_OTG>; + clocks = <&clkc CLKID_USB>, <&clkc CLKID_USB0>; + clock-names = "usb_general", "usb"; + phy-supply = <&usb_vbus>; +}; diff --git a/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt index 379b84a567cc..1d25b04cd05e 100644 --- a/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/mxs-usb-phy.txt @@ -12,6 +12,16 @@ Required properties: - interrupts: Should contain phy interrupt - fsl,anatop: phandle for anatop register, it is only for imx6 SoC series +Optional properties: +- fsl,tx-cal-45-dn-ohms: Integer [30-55]. Resistance (in ohms) of switchable + high-speed trimming resistor connected in parallel with the 45 ohm resistor + that terminates the DN output signal. Default: 45 +- fsl,tx-cal-45-dp-ohms: Integer [30-55]. Resistance (in ohms) of switchable + high-speed trimming resistor connected in parallel with the 45 ohm resistor + that terminates the DP output signal. Default: 45 +- fsl,tx-d-cal: Integer [79-119]. Current trimming value (as a percentage) of + the 17.78mA TX reference current. Default: 100 + Example: usbphy1: usbphy@020c9000 { compatible = "fsl,imx6q-usbphy", "fsl,imx23-usbphy"; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt new file mode 100644 index 000000000000..3c29c77a7018 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt @@ -0,0 +1,64 @@ +ROCKCHIP USB2.0 PHY WITH INNO IP BLOCK + +Required properties (phy (parent) node): + - compatible : should be one of the listed compatibles: + * "rockchip,rk3366-usb2phy" + * "rockchip,rk3399-usb2phy" + - reg : the address offset of grf for usb-phy configuration. + - #clock-cells : should be 0. + - clock-output-names : specify the 480m output clock name. + +Optional properties: + - clocks : phandle + phy specifier pair, for the input clock of phy. + - clock-names : input clock name of phy, must be "phyclk". + +Required nodes : a sub-node is required for each port the phy provides. + The sub-node name is used to identify host or otg port, + and shall be the following entries: + * "otg-port" : the name of otg port. + * "host-port" : the name of host port. + +Required properties (port (child) node): + - #phy-cells : must be 0. See ./phy-bindings.txt for details. + - interrupts : specify an interrupt for each entry in interrupt-names. + - interrupt-names : a list which shall be the following entries: + * "otg-id" : for the otg id interrupt. + * "otg-bvalid" : for the otg vbus interrupt. + * "linestate" : for the host/otg linestate interrupt. + +Optional properties: + - phy-supply : phandle to a regulator that provides power to VBUS. + See ./phy-bindings.txt for details. + +Example: + +grf: syscon@ff770000 { + compatible = "rockchip,rk3366-grf", "syscon", "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + +... + + u2phy: usb2-phy@700 { + compatible = "rockchip,rk3366-usb2phy"; + reg = <0x700 0x2c>; + #clock-cells = <0>; + clock-output-names = "sclk_otgphy0_480m"; + + u2phy_otg: otg-port { + #phy-cells = <0>; + interrupts = , + , + ; + interrupt-names = "otg-id", "otg-bvalid", "linestate"; + status = "okay"; + }; + + u2phy_host: host-port { + #phy-cells = <0>; + interrupts = ; + interrupt-names = "linestate"; + status = "okay"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt new file mode 100644 index 000000000000..6ea867e3176f --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-typec.txt @@ -0,0 +1,101 @@ +* ROCKCHIP type-c PHY +--------------------- + +Required properties: + - compatible : must be "rockchip,rk3399-typec-phy" + - reg: Address and length of the usb phy control register set + - rockchip,grf : phandle to the syscon managing the "general + register files" + - clocks : phandle + clock specifier for the phy clocks + - clock-names : string, clock name, must be "tcpdcore", "tcpdphy-ref"; + - assigned-clocks: main clock, should be <&cru SCLK_UPHY0_TCPDCORE> or + <&cru SCLK_UPHY1_TCPDCORE>; + - assigned-clock-rates : the phy core clk frequency, shall be: 50000000 + - resets : a list of phandle + reset specifier pairs + - reset-names : string reset name, must be: + "uphy", "uphy-pipe", "uphy-tcphy" + - extcon : extcon specifier for the Power Delivery + +Note, there are 2 type-c phys for RK3399, and they are almost identical, except +these registers(description below), every register node contains 3 sections: +offset, enable bit, write mask bit. + - rockchip,typec-conn-dir : the register of type-c connector direction, + for type-c phy0, it must be <0xe580 0 16>; + for type-c phy1, it must be <0xe58c 0 16>; + - rockchip,usb3tousb2-en : the register of type-c force usb3 to usb2 enable + control. + for type-c phy0, it must be <0xe580 3 19>; + for type-c phy1, it must be <0xe58c 3 19>; + - rockchip,external-psm : the register of type-c phy external psm clock + selection. + for type-c phy0, it must be <0xe588 14 30>; + for type-c phy1, it must be <0xe594 14 30>; + - rockchip,pipe-status : the register of type-c phy pipe status. + for type-c phy0, it must be <0xe5c0 0 0>; + for type-c phy1, it must be <0xe5c0 16 16>; + +Required nodes : a sub-node is required for each port the phy provides. + The sub-node name is used to identify dp or usb3 port, + and shall be the following entries: + * "dp-port" : the name of DP port. + * "usb3-port" : the name of USB3 port. + +Required properties (port (child) node): +- #phy-cells : must be 0, See ./phy-bindings.txt for details. + +Example: + tcphy0: phy@ff7c0000 { + compatible = "rockchip,rk3399-typec-phy"; + reg = <0x0 0xff7c0000 0x0 0x40000>; + rockchip,grf = <&grf>; + extcon = <&fusb0>; + clocks = <&cru SCLK_UPHY0_TCPDCORE>, + <&cru SCLK_UPHY0_TCPDPHY_REF>; + clock-names = "tcpdcore", "tcpdphy-ref"; + assigned-clocks = <&cru SCLK_UPHY0_TCPDCORE>; + assigned-clock-rates = <50000000>; + resets = <&cru SRST_UPHY0>, + <&cru SRST_UPHY0_PIPE_L00>, + <&cru SRST_P_UPHY0_TCPHY>; + reset-names = "uphy", "uphy-pipe", "uphy-tcphy"; + rockchip,typec-conn-dir = <0xe580 0 16>; + rockchip,usb3tousb2-en = <0xe580 3 19>; + rockchip,external-psm = <0xe588 14 30>; + rockchip,pipe-status = <0xe5c0 0 0>; + + tcphy0_dp: dp-port { + #phy-cells = <0>; + }; + + tcphy0_usb3: usb3-port { + #phy-cells = <0>; + }; + }; + + tcphy1: phy@ff800000 { + compatible = "rockchip,rk3399-typec-phy"; + reg = <0x0 0xff800000 0x0 0x40000>; + rockchip,grf = <&grf>; + extcon = <&fusb1>; + clocks = <&cru SCLK_UPHY1_TCPDCORE>, + <&cru SCLK_UPHY1_TCPDPHY_REF>; + clock-names = "tcpdcore", "tcpdphy-ref"; + assigned-clocks = <&cru SCLK_UPHY1_TCPDCORE>; + assigned-clock-rates = <50000000>; + resets = <&cru SRST_UPHY1>, + <&cru SRST_UPHY1_PIPE_L00>, + <&cru SRST_P_UPHY1_TCPHY>; + reset-names = "uphy", "uphy-pipe", "uphy-tcphy"; + rockchip,typec-conn-dir = <0xe58c 0 16>; + rockchip,usb3tousb2-en = <0xe58c 3 19>; + rockchip,external-psm = <0xe594 14 30>; + rockchip,pipe-status = <0xe5c0 16 16>; + + tcphy1_dp: dp-port { + #phy-cells = <0>; + }; + + tcphy1_usb3: usb3-port { + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index 2281d6cdecb1..ace9cce2704a 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -5,6 +5,8 @@ This file provides information on what the device node for the R-Car generation Required properties: - compatible: "renesas,usb2-phy-r8a7795" if the device is a part of an R8A7795 + SoC. + "renesas,usb2-phy-r8a7796" if the device is a part of an R8A7796 SoC. "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3 compatible device. @@ -30,11 +32,11 @@ Example (R-Car H3): compatible = "renesas,usb2-phy-r8a7795", "renesas,rcar-gen3-usb2-phy"; reg = <0 0xee080200 0 0x700>; interrupts = ; - clocks = <&mstp7_clks R8A7795_CLK_EHCI0>; + clocks = <&cpg CPG_MOD 703>; }; usb-phy@ee0a0200 { compatible = "renesas,usb2-phy-r8a7795", "renesas,rcar-gen3-usb2-phy"; reg = <0 0xee0a0200 0 0x700>; - clocks = <&mstp7_clks R8A7795_CLK_EHCI0>; + clocks = <&cpg CPG_MOD 702>; }; diff --git a/Documentation/devicetree/bindings/phy/rockchip-pcie-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-pcie-phy.txt new file mode 100644 index 000000000000..0f6222a672ce --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip-pcie-phy.txt @@ -0,0 +1,31 @@ +Rockchip PCIE PHY +----------------------- + +Required properties: + - compatible: rockchip,rk3399-pcie-phy + - #phy-cells: must be 0 + - clocks: Must contain an entry in clock-names. + See ../clocks/clock-bindings.txt for details. + - clock-names: Must be "refclk" + - resets: Must contain an entry in reset-names. + See ../reset/reset.txt for details. + - reset-names: Must be "phy" + +Example: + +grf: syscon@ff770000 { + compatible = "rockchip,rk3399-grf", "syscon", "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + + ... + + pcie_phy: pcie-phy { + compatible = "rockchip,rk3399-pcie-phy"; + #phy-cells = <0>; + clocks = <&cru SCLK_PCIEPHY_REF>; + clock-names = "refclk"; + resets = <&cru SRST_PCIEPHY>; + reset-names = "phy"; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt index cc6be9680a6d..57dc388e2fa2 100644 --- a/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/rockchip-usb-phy.txt @@ -27,6 +27,9 @@ Optional Properties: - clocks : phandle + clock specifier for the phy clocks - clock-names: string, clock name, must be "phyclk" - #clock-cells: for users of the phy-pll, should be 0 +- reset-names: Only allow the following entries: + - phy-reset +- resets: Must contain an entry for each entry in reset-names. Example: diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index 95736d77fbb7..287150db6db4 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -10,6 +10,7 @@ Required properties: * allwinner,sun8i-a23-usb-phy * allwinner,sun8i-a33-usb-phy * allwinner,sun8i-h3-usb-phy + * allwinner,sun50i-a64-usb-phy - reg : a list of offset + length pairs - reg-names : * "phy_ctrl" diff --git a/Documentation/devicetree/bindings/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index a3b394587874..cd13e6157088 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -31,6 +31,8 @@ OMAP USB2 PHY Required properties: - compatible: Should be "ti,omap-usb2" + Should be "ti,dra7x-usb2" for the 1st instance of USB2 PHY on + DRA7x Should be "ti,dra7x-usb2-phy2" for the 2nd instance of USB2 PHY in DRA7x - reg : Address and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 69617220c5d6..1685821eea41 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -23,6 +23,7 @@ Required properties: "allwinner,sun8i-h3-pinctrl" "allwinner,sun8i-h3-r-pinctrl" "allwinner,sun50i-a64-pinctrl" + "nextthing,gr8-pinctrl" - reg: Should contain the register physical address and length for the pin controller. diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,orion-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,orion-pinctrl.txt index 27570a3a1741..ec8aa3c6936b 100644 --- a/Documentation/devicetree/bindings/pinctrl/marvell,orion-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/marvell,orion-pinctrl.txt @@ -4,7 +4,9 @@ Please refer to marvell,mvebu-pinctrl.txt in this directory for common binding part and usage. Required properties: -- compatible: "marvell,88f5181l-pinctrl", "marvell,88f5182-pinctrl", +- compatible: "marvell,88f5181-pinctrl", + "marvell,88f5181l-pinctrl", + "marvell,88f5182-pinctrl", "marvell,88f5281-pinctrl" - reg: two register areas, the first one describing the first two diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt new file mode 100644 index 000000000000..5e60ad18f147 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-aspeed.txt @@ -0,0 +1,65 @@ +Aspeed Pin Controllers +---------------------- + +The Aspeed SoCs vary in functionality inside a generation but have a common mux +device register layout. + +Required properties: +- compatible : Should be any one of the following: + "aspeed,ast2400-pinctrl" + "aspeed,g4-pinctrl" + "aspeed,ast2500-pinctrl" + "aspeed,g5-pinctrl" + +The pin controller node should be a child of a syscon node with the required +property: +- compatible: "syscon", "simple-mfd" + +Refer to the the bindings described in +Documentation/devicetree/bindings/mfd/syscon.txt + +Subnode Format +-------------- + +The required properties of child nodes are (as defined in pinctrl-bindings): +- function +- groups + +Each function has only one associated pin group. Each group is named by its +function. The following values for the function and groups properties are +supported: + +aspeed,ast2400-pinctrl, aspeed,g4-pinctrl: + +ACPI BMCINT DDCCLK DDCDAT FLACK FLBUSY FLWP GPID0 GPIE0 GPIE2 GPIE4 GPIE6 I2C10 +I2C11 I2C12 I2C13 I2C3 I2C4 I2C5 I2C6 I2C7 I2C8 I2C9 LPCPD LPCPME LPCSMI MDIO1 +MDIO2 NCTS1 NCTS3 NCTS4 NDCD1 NDCD3 NDCD4 NDSR1 NDSR3 NDTR1 NDTR3 NRI1 NRI3 +NRI4 NRTS1 NRTS3 PWM0 PWM1 PWM2 PWM3 PWM4 PWM5 PWM6 PWM7 RGMII1 RMII1 ROM16 +ROM8 ROMCS1 ROMCS2 ROMCS3 ROMCS4 RXD1 RXD3 RXD4 SD1 SGPMI SIOPBI SIOPBO TIMER3 +TIMER5 TIMER6 TIMER7 TIMER8 TXD1 TXD3 TXD4 UART6 VGAHS VGAVS VPI18 VPI24 VPI30 +VPO12 VPO24 + +aspeed,ast2500-pinctrl, aspeed,g5-pinctrl: + +GPID0 GPID2 GPIE0 I2C10 I2C11 I2C12 I2C13 I2C14 I2C3 I2C4 I2C5 I2C6 I2C7 I2C8 +I2C9 MAC1LINK MDIO1 MDIO2 OSCCLK PEWAKE PWM0 PWM1 PWM2 PWM3 PWM4 PWM5 PWM6 PWM7 +RGMII1 RGMII2 RMII1 RMII2 SD1 SPI1 TIMER4 TIMER5 TIMER6 TIMER7 TIMER8 + +Examples: + +syscon: scu@1e6e2000 { + compatible = "syscon", "simple-mfd"; + reg = <0x1e6e2000 0x1a8>; + + pinctrl: pinctrl { + compatible = "aspeed,g4-pinctrl"; + + pinctrl_i2c3_default: i2c3_default { + function = "I2C3"; + groups = "I2C3"; + }; + }; +}; + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt index 26bcb18f4e60..013c675b5b64 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-st.txt @@ -30,8 +30,7 @@ Second type has a dedicated interrupt per gpio bank. Pin controller node: Required properties: -- compatible : should be "st,--pinctrl" - like st,stih415-sbc-pinctrl, st,stih415-front-pinctrl and so on. +- compatible : should be "st,stih407--pinctrl" - st,syscfg : Should be a phandle of the syscfg node. - st,retime-pin-mask : Should be mask to specify which pins can be retimed. If the property is not present, it is assumed that all the pins in the @@ -50,7 +49,11 @@ Optional properties: GPIO controller/bank node. Required properties: - gpio-controller : Indicates this device is a GPIO controller -- #gpio-cells : Should be one. The first cell is the pin number. +- #gpio-cells : Must be two. + - First cell: specifies the pin number inside the controller + - Second cell: specifies whether the pin is logically inverted. + - 0 = active high + - 1 = active low - st,bank-name : Should be a name string for this bank as specified in datasheet. @@ -76,23 +79,23 @@ include/dt-bindings/interrupt-controller/irq.h Example: pin-controller-sbc { - #address-cells = <1>; - #size-cells = <1>; - compatible = "st,stih415-sbc-pinctrl"; - st,syscfg = <&syscfg_sbc>; - reg = <0xfe61f080 0x4>; - reg-names = "irqmux"; - interrupts = ; - interrupt-names = "irqmux"; - ranges = <0 0xfe610000 0x5000>; - - PIO0: gpio@fe610000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "st,stih407-sbc-pinctrl"; + st,syscfg = <&syscfg_sbc>; + reg = <0x0961f080 0x4>; + reg-names = "irqmux"; + interrupts = ; + interrupt-names = "irqmux"; + ranges = <0 0x09610000 0x6000>; + + pio0: gpio@09610000 { gpio-controller; - #gpio-cells = <1>; + #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; - reg = <0 0x100>; - st,bank-name = "PIO0"; + reg = <0x0 0x100>; + st,bank-name = "PIO0"; }; ... pin-functions nodes follow... @@ -162,7 +165,7 @@ pin-controller { sdhci0:sdhci@fe810000{ ... - interrupt-parent = <&PIO3>; + interrupt-parent = <&pio3>; #interrupt-cells = <2>; interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; /* Interrupt line via PIO3-3 */ interrupt-names = "card-detect"; diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt index a54c39ebbf8b..8d893a874634 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -17,6 +17,9 @@ PMIC's from Qualcomm. "qcom,pm8994-gpio" "qcom,pma8084-gpio" + And must contain either "qcom,spmi-gpio" or "qcom,ssbi-gpio" + if the device is on an spmi bus or an ssbi bus respectively + - reg: Usage: required Value type: @@ -183,7 +186,7 @@ to specify in a pin configuration subnode: Example: pm8921_gpio: gpio@150 { - compatible = "qcom,pm8921-gpio"; + compatible = "qcom,pm8921-gpio", "qcom,ssbi-gpio"; reg = <0x150 0x160>; interrupts = <192 1>, <193 1>, <194 1>, <195 1>, <196 1>, <197 1>, diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt index b484ba1af78c..2ab95bc26066 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-mpp.txt @@ -19,6 +19,9 @@ of PMIC's from Qualcomm. "qcom,pm8994-mpp", "qcom,pma8084-mpp", + And must contain either "qcom,spmi-mpp" or "qcom,ssbi-mpp" + if the device is on an spmi bus or an ssbi bus respectively. + - reg: Usage: required Value type: @@ -158,7 +161,7 @@ to specify in a pin configuration subnode: Example: mpps@a000 { - compatible = "qcom,pm8841-mpp"; + compatible = "qcom,pm8841-mpp", "qcom,spmi-mpp"; reg = <0xa000>; gpio-controller; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt index e4cf022c992e..13df9498311a 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt @@ -17,9 +17,11 @@ Required Properties: - "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller. - "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller. - "renesas,pfc-r8a7791": for R8A7791 (R-Car M2-W) compatible pin-controller. + - "renesas,pfc-r8a7792": for R8A7792 (R-Car V2H) compatible pin-controller. - "renesas,pfc-r8a7793": for R8A7793 (R-Car M2-N) compatible pin-controller. - "renesas,pfc-r8a7794": for R8A7794 (R-Car E2) compatible pin-controller. - "renesas,pfc-r8a7795": for R8A7795 (R-Car H3) compatible pin-controller. + - "renesas,pfc-r8a7796": for R8A7796 (R-Car M3-W) compatible pin-controller. - "renesas,pfc-sh73a0": for SH73A0 (SH-Mobile AG5) compatible pin-controller. - reg: Base address and length of each memory resource used by the pin diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt index 6db16b90873a..d49e22d2a8b5 100644 --- a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -229,6 +229,8 @@ Example: A pin-controller node with pin banks: Example 1: A pin-controller node with pin groups. + #include + pinctrl_0: pinctrl@11400000 { compatible = "samsung,exynos4210-pinctrl"; reg = <0x11400000 0x1000>; @@ -238,53 +240,53 @@ Example 1: A pin-controller node with pin groups. uart0_data: uart0-data { samsung,pins = "gpa0-0", "gpa0-1"; - samsung,pin-function = <2>; - samsung,pin-pud = <0>; - samsung,pin-drv = <0>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; uart0_fctl: uart0-fctl { samsung,pins = "gpa0-2", "gpa0-3"; - samsung,pin-function = <2>; - samsung,pin-pud = <0>; - samsung,pin-drv = <0>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; uart1_data: uart1-data { samsung,pins = "gpa0-4", "gpa0-5"; - samsung,pin-function = <2>; - samsung,pin-pud = <0>; - samsung,pin-drv = <0>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; uart1_fctl: uart1-fctl { samsung,pins = "gpa0-6", "gpa0-7"; - samsung,pin-function = <2>; - samsung,pin-pud = <0>; - samsung,pin-drv = <0>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; i2c2_bus: i2c2-bus { samsung,pins = "gpa0-6", "gpa0-7"; - samsung,pin-function = <3>; - samsung,pin-pud = <3>; - samsung,pin-drv = <0>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; sd4_bus8: sd4-bus-width8 { part-1 { samsung,pins = "gpk0-3", "gpk0-4", "gpk0-5", "gpk0-6"; - samsung,pin-function = <3>; - samsung,pin-pud = <3>; - samsung,pin-drv = <3>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; part-2 { samsung,pins = "gpk1-3", "gpk1-4", "gpk1-5", "gpk1-6"; - samsung,pin-function = <4>; - samsung,pin-pud = <4>; - samsung,pin-drv = <3>; + samsung,pin-function = ; + samsung,pin-pud = ; + samsung,pin-drv = ; }; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index 587bffb9cbc6..f9753c416974 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -14,6 +14,11 @@ Required properies: - #size-cells : The value of this property must be 1 - ranges : defines mapping between pin controller node (parent) to gpio-bank node (children). + - interrupt-parent: phandle of the interrupt parent to which the external + GPIO interrupts are forwarded to. + - st,syscfg: Should be phandle/offset pair. The phandle to the syscon node + which includes IRQ mux selection register, and the offset of the IRQ mux + selection register. - pins-are-numbered: Specify the subnodes are using numbered pinmux to specify pins. diff --git a/Documentation/devicetree/bindings/power/act8945a-charger.txt b/Documentation/devicetree/bindings/power/act8945a-charger.txt deleted file mode 100644 index bea254c9d136..000000000000 --- a/Documentation/devicetree/bindings/power/act8945a-charger.txt +++ /dev/null @@ -1,35 +0,0 @@ -Device-Tree bindings for charger of Active-semi ACT8945A Multi-Function Device - -Required properties: - - compatible: "active-semi,act8945a", please refer to ../mfd/act8945a.txt. - - active-semi,chglev-gpios: charge current level phandle with args - as described in ../gpio/gpio.txt. - -Optional properties: - - active-semi,check-battery-temperature: boolean to check the battery - temperature or not. - - active-semi,input-voltage-threshold-microvolt: unit: mV; - Specifies the charger's input over-voltage threshold value; - The value can be: 6600, 7000, 7500, 8000; default: 6600 - - active-semi,precondition-timeout: unit: minutes; - Specifies the charger's PRECONDITION safety timer setting value; - The value can be: 40, 60, 80, 0; If 0, it means to disable this timer; - default: 40. - - active-semi,total-timeout: unit: hours; - Specifies the charger's total safety timer setting value; - The value can be: 3, 4, 5, 0; If 0, it means to disable this timer; - default: 3. - -Example: - pmic@5b { - compatible = "active-semi,act8945a"; - reg = <0x5b>; - status = "okay"; - - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_charger_chglev>; - active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; - active-semi,input-voltage-threshold-microvolt = <6600>; - active-semi,precondition-timeout = <40>; - active-semi,total-timeout = <3>; - }; diff --git a/Documentation/devicetree/bindings/power/bq2415x.txt b/Documentation/devicetree/bindings/power/bq2415x.txt deleted file mode 100644 index d0327f0b59ad..000000000000 --- a/Documentation/devicetree/bindings/power/bq2415x.txt +++ /dev/null @@ -1,47 +0,0 @@ -Binding for TI bq2415x Li-Ion Charger - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq24150" - * "ti,bq24150" - * "ti,bq24150a" - * "ti,bq24151" - * "ti,bq24151a" - * "ti,bq24152" - * "ti,bq24153" - * "ti,bq24153a" - * "ti,bq24155" - * "ti,bq24156" - * "ti,bq24156a" - * "ti,bq24158" -- reg: integer, i2c address of the device. -- ti,current-limit: integer, initial maximum current charger can pull - from power supply in mA. -- ti,weak-battery-voltage: integer, weak battery voltage threshold in mV. - The chip will use slow precharge if battery voltage - is below this value. -- ti,battery-regulation-voltage: integer, maximum charging voltage in mV. -- ti,charge-current: integer, maximum charging current in mA. -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in mA). -- ti,resistor-sense: integer, value of sensing resistor in milliohm. - -Optional properties: -- ti,usb-charger-detection: phandle to usb charger detection device. - (required for auto mode) - -Example from Nokia N900: - -bq24150a { - compatible = "ti,bq24150a"; - reg = <0x6b>; - - ti,current-limit = <100>; - ti,weak-battery-voltage = <3400>; - ti,battery-regulation-voltage = <4200>; - ti,charge-current = <650>; - ti,termination-current = <100>; - ti,resistor-sense = <68>; - - ti,usb-charger-detection = <&isp1704>; -}; diff --git a/Documentation/devicetree/bindings/power/bq24257.txt b/Documentation/devicetree/bindings/power/bq24257.txt deleted file mode 100644 index d693702c9c1e..000000000000 --- a/Documentation/devicetree/bindings/power/bq24257.txt +++ /dev/null @@ -1,64 +0,0 @@ -Binding for TI bq24250/bq24251/bq24257 Li-Ion Charger - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq24250" - * "ti,bq24251" - * "ti,bq24257" -- reg: integer, i2c address of the device. -- interrupt-parent: Should be the phandle for the interrupt controller. Use in - conjunction with "interrupts". -- interrupts: Interrupt mapping for GPIO IRQ (configure for both edges). Use in - conjunction with "interrupt-parent". -- ti,battery-regulation-voltage: integer, maximum charging voltage in uV. -- ti,charge-current: integer, maximum charging current in uA. -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in uA). - -Optional properties: -- pg-gpios: GPIO used for connecting the bq2425x device PG (Power Good) pin. - This pin is not available on all devices however it should be used if - possible as this is the recommended way to obtain the charger's input PG - state. If this pin is not specified a software-based approach for PG - detection is used. -- ti,current-limit: The maximum current to be drawn from the charger's input - (in uA). If this property is not specified, the input limit current is - set automatically using USB D+/D- signal based charger type detection. - If the hardware does not support the D+/D- based detection, a default - of 500,000 is used (=500mA) instead. -- ti,ovp-voltage: Configures the over voltage protection voltage (in uV). If - not specified a default of 6,5000,000 (=6.5V) is used. -- ti,in-dpm-voltage: Configures the threshold input voltage for the dynamic - power path management (in uV). If not specified a default of 4,360,000 - (=4.36V) is used. - -Example: - -bq24257 { - compatible = "ti,bq24257"; - reg = <0x6a>; - interrupt-parent = <&gpio1>; - interrupts = <16 IRQ_TYPE_EDGE_BOTH>; - - pg-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <1000000>; - ti,termination-current = <50000>; -}; - -Example: - -bq24250 { - compatible = "ti,bq24250"; - reg = <0x6a>; - interrupt-parent = <&gpio1>; - interrupts = <16 IRQ_TYPE_EDGE_BOTH>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <500000>; - ti,termination-current = <50000>; - ti,current-limit = <900000>; - ti,ovp-voltage = <9500000>; - ti,in-dpm-voltage = <4440000>; -}; diff --git a/Documentation/devicetree/bindings/power/bq25890.txt b/Documentation/devicetree/bindings/power/bq25890.txt deleted file mode 100644 index c9dd17d142ad..000000000000 --- a/Documentation/devicetree/bindings/power/bq25890.txt +++ /dev/null @@ -1,46 +0,0 @@ -Binding for TI bq25890 Li-Ion Charger - -Required properties: -- compatible: Should contain one of the following: - * "ti,bq25890" -- reg: integer, i2c address of the device. -- ti,battery-regulation-voltage: integer, maximum charging voltage (in uV); -- ti,charge-current: integer, maximum charging current (in uA); -- ti,termination-current: integer, charge will be terminated when current in - constant-voltage phase drops below this value (in uA); -- ti,precharge-current: integer, maximum charge current during precharge - phase (in uA); -- ti,minimum-sys-voltage: integer, when battery is charging and it is below - minimum system voltage, the system will be regulated above - minimum-sys-voltage setting (in uV); -- ti,boost-voltage: integer, VBUS voltage level in boost mode (in uV); -- ti,boost-max-current: integer, maximum allowed current draw in boost mode - (in uA). - -Optional properties: -- ti,boost-low-freq: boolean, if present boost mode frequency will be 500kHz, - otherwise 1.5MHz; -- ti,use-ilim-pin: boolean, if present the ILIM resistor will be used and the - input current will be the lower between the resistor setting and the IINLIM - register setting; -- ti,thermal-regulation-threshold: integer, temperature above which the charge - current is lowered, to avoid overheating (in degrees Celsius). If omitted, - the default setting will be used (120 degrees); - -Example: - -bq25890 { - compatible = "ti,bq25890"; - reg = <0x6a>; - - ti,battery-regulation-voltage = <4200000>; - ti,charge-current = <1000000>; - ti,termination-current = <50000>; - ti,precharge-current = <128000>; - ti,minimum-sys-voltage = <3600000>; - ti,boost-voltage = <5000000>; - ti,boost-max-current = <1000000>; - - ti,use-ilim-pin; - ti,thermal-regulation-threshold = <120>; -}; diff --git a/Documentation/devicetree/bindings/power/da9150-charger.txt b/Documentation/devicetree/bindings/power/da9150-charger.txt deleted file mode 100644 index f3906663c454..000000000000 --- a/Documentation/devicetree/bindings/power/da9150-charger.txt +++ /dev/null @@ -1,26 +0,0 @@ -Dialog Semiconductor DA9150 Charger Power Supply bindings - -Required properties: -- compatible: "dlg,da9150-charger" for DA9150 Charger Power Supply - -Optional properties: -- io-channels: List of phandle and IIO specifier pairs -- io-channel-names: List of channel names used by charger - ["CHAN_IBUS", "CHAN_VBUS", "CHAN_TJUNC", "CHAN_VBAT"] - (See Documentation/devicetree/bindings/iio/iio-bindings.txt for further info) - - -Example: - - da9150-charger { - compatible = "dlg,da9150-charger"; - - io-channels = <&gpadc 0>, - <&gpadc 2>, - <&gpadc 8>, - <&gpadc 5>; - io-channel-names = "CHAN_IBUS", - "CHAN_VBUS", - "CHAN_TJUNC", - "CHAN_VBAT"; - }; diff --git a/Documentation/devicetree/bindings/power/da9150-fg.txt b/Documentation/devicetree/bindings/power/da9150-fg.txt deleted file mode 100644 index 00236fe3ea31..000000000000 --- a/Documentation/devicetree/bindings/power/da9150-fg.txt +++ /dev/null @@ -1,23 +0,0 @@ -Dialog Semiconductor DA9150 Fuel-Gauge Power Supply bindings - -Required properties: -- compatible: "dlg,da9150-fuel-gauge" for DA9150 Fuel-Gauge Power Supply - -Optional properties: -- dlg,update-interval: Interval time (milliseconds) between battery level checks. -- dlg,warn-soc-level: Battery discharge level (%) where warning event raised. - [1 - 100] -- dlg,crit-soc-level: Battery discharge level (%) where critical event raised. - This value should be lower than the warning level. - [1 - 100] - - -Example: - - fuel-gauge { - compatible = "dlg,da9150-fuel-gauge"; - - dlg,update-interval = <10000>; - dlg,warn-soc-level = /bits/ 8 <15>; - dlg,crit-soc-level = /bits/ 8 <5>; - }; diff --git a/Documentation/devicetree/bindings/power/isp1704.txt b/Documentation/devicetree/bindings/power/isp1704.txt deleted file mode 100644 index fa3596907967..000000000000 --- a/Documentation/devicetree/bindings/power/isp1704.txt +++ /dev/null @@ -1,17 +0,0 @@ -Binding for NXP ISP1704 USB Charger Detection - -Required properties: -- compatible: Should contain one of the following: - * "nxp,isp1704" -- nxp,enable-gpio: Should contain a phandle + gpio-specifier - to the GPIO pin connected to the chip's enable pin. -- usb-phy: Should contain a phandle to the USB PHY - the ISP1704 is connected to. - -Example: - -isp1704 { - compatible = "nxp,isp1704"; - nxp,enable-gpio = <&gpio3 3 GPIO_ACTIVE_LOW>; - usb-phy = <&usb2_phy>; -}; diff --git a/Documentation/devicetree/bindings/power/ltc2941.txt b/Documentation/devicetree/bindings/power/ltc2941.txt deleted file mode 100644 index ea42ae12d924..000000000000 --- a/Documentation/devicetree/bindings/power/ltc2941.txt +++ /dev/null @@ -1,27 +0,0 @@ -binding for LTC2941 and LTC2943 battery gauges - -Both the LTC2941 and LTC2943 measure battery capacity. -The LTC2943 is compatible with the LTC2941, it adds voltage and -temperature monitoring, and uses a slightly different conversion -formula for the charge counter. - -Required properties: -- compatible: Should contain "ltc2941" or "ltc2943" which also indicates the - type of I2C chip attached. -- reg: The 7-bit I2C address. -- lltc,resistor-sense: The sense resistor value in milli-ohms. Can be a 32-bit - negative value when the battery has been connected to the wrong end of the - resistor. -- lltc,prescaler-exponent: The prescaler exponent as explained in the datasheet. - This determines the range and accuracy of the gauge. The value is programmed - into the chip only if it differs from the current setting. The setting is - lost when the battery is disconnected. - -Example from the Topic Miami Florida board: - - fuelgauge: ltc2943@64 { - compatible = "ltc2943"; - reg = <0x64>; - lltc,resistor-sense = <15>; - lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ - }; diff --git a/Documentation/devicetree/bindings/power/qcom,coincell-charger.txt b/Documentation/devicetree/bindings/power/qcom,coincell-charger.txt deleted file mode 100644 index 747899223262..000000000000 --- a/Documentation/devicetree/bindings/power/qcom,coincell-charger.txt +++ /dev/null @@ -1,48 +0,0 @@ -Qualcomm Coincell Charger: - -The hardware block controls charging for a coincell or capacitor that is -used to provide power backup for certain features of the power management -IC (PMIC) - -- compatible: - Usage: required - Value type: - Definition: must be: "qcom,pm8941-coincell" - -- reg: - Usage: required - Value type: - Definition: base address of the coincell charger registers - -- qcom,rset-ohms: - Usage: required - Value type: - Definition: resistance (in ohms) for current-limiting resistor - must be one of: 800, 1200, 1700, 2100 - -- qcom,vset-millivolts: - Usage: required - Value type: - Definition: voltage (in millivolts) to apply for charging - must be one of: 2500, 3000, 3100, 3200 - -- qcom,charger-disable: - Usage: optional - Value type: - Definition: defining this property disables charging - -This charger is a sub-node of one of the 8941 PMIC blocks, and is specified -as a child node in DTS of that node. See ../mfd/qcom,spmi-pmic.txt and -../mfd/qcom-pm8xxx.txt - -Example: - - pm8941@0 { - coincell@2800 { - compatible = "qcom,pm8941-coincell"; - reg = <0x2800>; - - qcom,rset-ohms = <2100>; - qcom,vset-millivolts = <3000>; - }; - }; diff --git a/Documentation/devicetree/bindings/power/reset/axxia-reset.txt b/Documentation/devicetree/bindings/power/reset/axxia-reset.txt new file mode 100644 index 000000000000..47e720d249d2 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/axxia-reset.txt @@ -0,0 +1,20 @@ +Axxia Restart Driver + +This driver can do reset of the Axxia SoC. It uses the registers in the syscon +block to initiate a chip reset. + +Required Properties: + -compatible: "lsi,axm55xx-reset" + -syscon: phandle to the syscon node. + +Example: + + syscon: syscon@2010030000 { + compatible = "lsi,axxia-syscon", "syscon"; + reg = <0x20 0x10030000 0 0x2000>; + }; + + reset: reset@2010031000 { + compatible = "lsi,axm55xx-reset"; + syscon = <&syscon>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt new file mode 100644 index 000000000000..dc7c9bad63ea --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/imx-snvs-poweroff.txt @@ -0,0 +1,23 @@ +i.mx6 Poweroff Driver + +SNVS_LPCR in SNVS module can power off the whole system by pull +PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. +If you don't want to use PMIC_ON_REQ as power on/off control, +please set status='disabled' to disable this driver. + +Required Properties: +-compatible: "fsl,sec-v4.0-poweroff" +-reg: Specifies the physical address of the SNVS_LPCR register + +Example: + snvs@020cc000 { + compatible = "fsl,sec-v4.0-mon", "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x020cc000 0x4000>; + ..... + snvs_poweroff: snvs-poweroff@38 { + compatible = "fsl,sec-v4.0-poweroff"; + reg = <0x38 0x4>; + }; + } diff --git a/Documentation/devicetree/bindings/power/reset/msm-poweroff.txt b/Documentation/devicetree/bindings/power/reset/msm-poweroff.txt new file mode 100644 index 000000000000..ce44ad357565 --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/msm-poweroff.txt @@ -0,0 +1,17 @@ +MSM Restart Driver + +A power supply hold (ps-hold) bit is set to power the msm chipsets. +Clearing that bit allows us to restart/poweroff. The difference +between poweroff and restart is determined by unique power manager IC +settings. + +Required Properties: +-compatible: "qcom,pshold" +-reg: Specifies the physical address of the ps-hold register + +Example: + + restart@fc4ab000 { + compatible = "qcom,pshold"; + reg = <0xfc4ab000 0x4>; + }; diff --git a/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt b/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt new file mode 100644 index 000000000000..af25e77c0e0c --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt @@ -0,0 +1,16 @@ +* QNAP Power Off + +QNAP NAS devices have a microcontroller controlling the main power +supply. This microcontroller is connected to UART1 of the Kirkwood and +Orion5x SoCs. Sending the character 'A', at 19200 baud, tells the +microcontroller to turn the power off. This driver adds a handler to +pm_power_off which is called to turn the power off. + +Synology NAS devices use a similar scheme, but a different baud rate, +9600, and a different character, '1'. + +Required Properties: +- compatible: Should be "qnap,power-off" or "synology,power-off" + +- reg: Address and length of the register set for UART1 +- clocks: tclk clock diff --git a/Documentation/devicetree/bindings/power/reset/restart-poweroff.txt b/Documentation/devicetree/bindings/power/reset/restart-poweroff.txt new file mode 100644 index 000000000000..5776e684afda --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/restart-poweroff.txt @@ -0,0 +1,8 @@ +* Restart Power Off + +Buffalo Linkstation LS-XHL and LS-CHLv2, and other devices power off +by restarting and letting u-boot keep hold of the machine until the +user presses a button. + +Required Properties: +- compatible: Should be "restart-poweroff" diff --git a/Documentation/devicetree/bindings/power/reset/st-reset.txt b/Documentation/devicetree/bindings/power/reset/st-reset.txt index 809af54f02f3..83734dc3a389 100644 --- a/Documentation/devicetree/bindings/power/reset/st-reset.txt +++ b/Documentation/devicetree/bindings/power/reset/st-reset.txt @@ -1,11 +1,12 @@ *Device-Tree bindings for ST SW reset functionality Required properties: -- compatible: should be "st,-restart". +- compatible: should be "stih407-restart". - st,syscfg: should be a phandle of the syscfg node. Example node: restart { - compatible = "st,stih416-restart"; - st,syscfg = <&syscfg_sbc>; + compatible = "st,stih407-restart"; + st,syscfg = <&syscfg_sbc_reg>; + status = "okay"; }; diff --git a/Documentation/devicetree/bindings/power/rt9455_charger.txt b/Documentation/devicetree/bindings/power/rt9455_charger.txt deleted file mode 100644 index 5d9ad5cf2c5a..000000000000 --- a/Documentation/devicetree/bindings/power/rt9455_charger.txt +++ /dev/null @@ -1,48 +0,0 @@ -Binding for Richtek rt9455 battery charger - -Required properties: -- compatible: it should contain one of the following: - "richtek,rt9455". -- reg: integer, i2c address of the device. -- interrupt-parent: the phandle for the interrupt controller that - services interrupts for this device. -- interrupts: interrupt mapping for GPIO IRQ, it should be - configured with IRQ_TYPE_LEVEL_LOW flag. -- richtek,output-charge-current: integer, output current from the charger to the - battery, in uA. -- richtek,end-of-charge-percentage: integer, percent of the output charge current. - When the current in constant-voltage phase drops - below output_charge_current x end-of-charge-percentage, - charge is terminated. -- richtek,battery-regulation-voltage: integer, maximum battery voltage in uV. -- richtek,boost-output-voltage: integer, maximum voltage provided to consumer - devices, when the charger is in boost mode, in uV. - -Optional properties: -- richtek,min-input-voltage-regulation: integer, input voltage level in uV, used to - decrease voltage level when the over current - of the input power source occurs. - This prevents input voltage drop due to insufficient - current provided by the power source. - Default: 4500000 uV (4.5V) -- richtek,avg-input-current-regulation: integer, input current value in uA drained by the - charger from the power source. - Default: 500000 uA (500mA) - -Example: - -rt9455@22 { - compatible = "richtek,rt9455"; - reg = <0x22>; - - interrupt-parent = <&gpio1>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - - richtek,output-charge-current = <500000>; - richtek,end-of-charge-percentage = <10>; - richtek,battery-regulation-voltage = <4200000>; - richtek,boost-output-voltage = <5050000>; - - richtek,min-input-voltage-regulation = <4500000>; - richtek,avg-input-current-regulation = <500000>; -}; diff --git a/Documentation/devicetree/bindings/power/rx51-battery.txt b/Documentation/devicetree/bindings/power/rx51-battery.txt deleted file mode 100644 index 90438453db58..000000000000 --- a/Documentation/devicetree/bindings/power/rx51-battery.txt +++ /dev/null @@ -1,25 +0,0 @@ -Binding for Nokia N900 battery - -The Nokia N900 battery status can be read via the TWL4030's A/D converter. - -Required properties: -- compatible: Should contain one of the following: - * "nokia,n900-battery" -- io-channels: Should contain IIO channel specifiers - for each element in io-channel-names. -- io-channel-names: Should contain the following values: - * "temp" - The ADC channel for temperature reading - * "bsi" - The ADC channel for battery size identification - * "vbat" - The ADC channel to measure the battery voltage - -Example from Nokia N900: - -battery: n900-battery { - compatible = "nokia,n900-battery"; - io-channels = <&twl4030_madc 0>, - <&twl4030_madc 4>, - <&twl4030_madc 12>; - io-channel-names = "temp", - "bsi", - "vbat"; -}; diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt b/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt new file mode 100644 index 000000000000..0ba1bcc7f33a --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ab8500/btemp.txt @@ -0,0 +1,16 @@ +=== AB8500 Battery Temperature Monitor Driver === + +The properties below describes the node for btemp driver. + +Required Properties: +- compatible = Shall be: "stericsson,ab8500-btemp" +- battery = Shall be battery specific information + + Example: + ab8500_btemp { + compatible = "stericsson,ab8500-btemp"; + battery = <&ab8500_battery>; + }; + +For information on battery specific node, Ref: +Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt b/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt new file mode 100644 index 000000000000..ef5328371122 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ab8500/chargalg.txt @@ -0,0 +1,16 @@ +=== AB8500 Charging Algorithm Driver === + +The properties below describes the node for chargalg driver. + +Required Properties: +- compatible = Shall be: "stericsson,ab8500-chargalg" +- battery = Shall be battery specific information + +Example: +ab8500_chargalg { + compatible = "stericsson,ab8500-chargalg"; + battery = <&ab8500_battery>; +}; + +For information on battery specific node, Ref: +Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt b/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt new file mode 100644 index 000000000000..6bdbb08ea9e0 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ab8500/charger.txt @@ -0,0 +1,25 @@ +=== AB8500 Charger Driver === + +Required Properties: +- compatible = Shall be "stericsson,ab8500-charger" +- battery = Shall be battery specific information + Example: + ab8500_charger { + compatible = "stericsson,ab8500-charger"; + battery = <&ab8500_battery>; + }; + +- vddadc-supply: Supply for USB and Main charger + Example: + ab8500-charger { + vddadc-supply = <&ab8500_ldo_tvout_reg>; + } +- autopower_cfg: + Boolean value depicting the presence of 'automatic poweron after powerloss' + Example: + ab8500-charger { + autopower_cfg; + }; + +For information on battery specific node, Ref: +Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power/supply/ab8500/fg.txt b/Documentation/devicetree/bindings/power/supply/ab8500/fg.txt new file mode 100644 index 000000000000..ccafcb9112fb --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ab8500/fg.txt @@ -0,0 +1,58 @@ +=== AB8500 Fuel Gauge Driver === + +AB8500 is a mixed signal multimedia and power management +device comprising: power and energy-management-module, +wall-charger, usb-charger, audio codec, general purpose adc, +tvout, clock management and sim card interface. + +Fuelgauge support is part of energy-management-modules, other +components of this module are: +main-charger, usb-combo-charger and battery-temperature-monitoring. + +The properties below describes the node for fuelgauge driver. + +Required Properties: +- compatible = This shall be: "stericsson,ab8500-fg" +- battery = Shall be battery specific information + Example: + ab8500_fg { + compatible = "stericsson,ab8500-fg"; + battery = <&ab8500_battery>; + }; + +dependent node: + ab8500_battery: ab8500_battery { + }; + This node will provide information on 'thermistor interface' and + 'battery technology type' used. + +Properties of this node are: +thermistor-on-batctrl: + A boolean value indicating thermistor interface to battery + + Note: + 'btemp' and 'batctrl' are the pins interfaced for battery temperature + measurement, 'btemp' signal is used when NTC(negative temperature + coefficient) resister is interfaced external to battery whereas + 'batctrl' pin is used when NTC resister is internal to battery. + + Example: + ab8500_battery: ab8500_battery { + thermistor-on-batctrl; + }; + indicates: NTC resister is internal to battery, 'batctrl' is used + for thermal measurement. + + The absence of property 'thermal-on-batctrl' indicates + NTC resister is external to battery and 'btemp' signal is used + for thermal measurement. + +battery-type: + This shall be the battery manufacturing technology type, + allowed types are: + "UNKNOWN" "NiMH" "LION" "LIPO" "LiFe" "NiCd" "LiMn" + Example: + ab8500_battery: ab8500_battery { + stericsson,battery-type = "LIPO"; + } + diff --git a/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt b/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt new file mode 100644 index 000000000000..de78d761ce44 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/act8945a-charger.txt @@ -0,0 +1,48 @@ +Device-Tree bindings for charger of Active-semi ACT8945A Multi-Function Device + +Required properties: + - compatible: "active-semi,act8945a-charger". + - active-semi,chglev-gpios: charge current level phandle with args + as described in ../gpio/gpio.txt. + - active-semi,lbo-gpios: specify the low battery voltage detect phandle + with args as as described in ../gpio/gpio.txt. + - interrupts: where a is the interrupt number and b is a + field that represents an encoding of the sense and level + information for the interrupt. + - interrupt-parent: the phandle for the interrupt controller that + services interrupts for this device. + +Optional properties: + - active-semi,input-voltage-threshold-microvolt: unit: mV; + Specifies the charger's input over-voltage threshold value; + The value can be: 6600, 7000, 7500, 8000; default: 6600 + - active-semi,precondition-timeout: unit: minutes; + Specifies the charger's PRECONDITION safety timer setting value; + The value can be: 40, 60, 80, 0; If 0, it means to disable this timer; + default: 40. + - active-semi,total-timeout: unit: hours; + Specifies the charger's total safety timer setting value; + The value can be: 3, 4, 5, 0; If 0, it means to disable this timer; + default: 3. + +Example: + pmic@5b { + compatible = "active-semi,act8945a"; + reg = <0x5b>; + status = "okay"; + + charger { + compatible = "active-semi,act8945a-charger"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_charger_chglev &pinctrl_charger_lbo &pinctrl_charger_irq>; + interrupt-parent = <&pioA>; + interrupts = <45 GPIO_ACTIVE_LOW>; + + active-semi,chglev-gpios = <&pioA 12 GPIO_ACTIVE_HIGH>; + active-semi,lbo-gpios = <&pioA 72 GPIO_ACTIVE_LOW>; + active-semi,input-voltage-threshold-microvolt = <6600>; + active-semi,precondition-timeout = <40>; + active-semi,total-timeout = <3>; + status = "okay"; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt b/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt new file mode 100644 index 000000000000..f1d7beec45bf --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/axp20x_usb_power.txt @@ -0,0 +1,35 @@ +AXP20x USB power supply + +Required Properties: +-compatible: One of: "x-powers,axp202-usb-power-supply" + "x-powers,axp221-usb-power-supply" + +This node is a subnode of the axp20x PMIC. + +Example: + +axp209: pmic@34 { + compatible = "x-powers,axp209"; + reg = <0x34>; + interrupt-parent = <&nmi_intc>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <1>; + + regulators { + x-powers,dcdc-freq = <1500>; + + vdd_cpu: dcdc2 { + regulator-always-on; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1450000>; + regulator-name = "vdd-cpu"; + }; + + ... + }; + + usb-power-supply: usb-power-supply { + compatible = "x-powers,axp202-usb-power-supply"; + }; +}; diff --git a/Documentation/devicetree/bindings/power/supply/bq2415x.txt b/Documentation/devicetree/bindings/power/supply/bq2415x.txt new file mode 100644 index 000000000000..d0327f0b59ad --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq2415x.txt @@ -0,0 +1,47 @@ +Binding for TI bq2415x Li-Ion Charger + +Required properties: +- compatible: Should contain one of the following: + * "ti,bq24150" + * "ti,bq24150" + * "ti,bq24150a" + * "ti,bq24151" + * "ti,bq24151a" + * "ti,bq24152" + * "ti,bq24153" + * "ti,bq24153a" + * "ti,bq24155" + * "ti,bq24156" + * "ti,bq24156a" + * "ti,bq24158" +- reg: integer, i2c address of the device. +- ti,current-limit: integer, initial maximum current charger can pull + from power supply in mA. +- ti,weak-battery-voltage: integer, weak battery voltage threshold in mV. + The chip will use slow precharge if battery voltage + is below this value. +- ti,battery-regulation-voltage: integer, maximum charging voltage in mV. +- ti,charge-current: integer, maximum charging current in mA. +- ti,termination-current: integer, charge will be terminated when current in + constant-voltage phase drops below this value (in mA). +- ti,resistor-sense: integer, value of sensing resistor in milliohm. + +Optional properties: +- ti,usb-charger-detection: phandle to usb charger detection device. + (required for auto mode) + +Example from Nokia N900: + +bq24150a { + compatible = "ti,bq24150a"; + reg = <0x6b>; + + ti,current-limit = <100>; + ti,weak-battery-voltage = <3400>; + ti,battery-regulation-voltage = <4200>; + ti,charge-current = <650>; + ti,termination-current = <100>; + ti,resistor-sense = <68>; + + ti,usb-charger-detection = <&isp1704>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/bq24257.txt b/Documentation/devicetree/bindings/power/supply/bq24257.txt new file mode 100644 index 000000000000..d693702c9c1e --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq24257.txt @@ -0,0 +1,64 @@ +Binding for TI bq24250/bq24251/bq24257 Li-Ion Charger + +Required properties: +- compatible: Should contain one of the following: + * "ti,bq24250" + * "ti,bq24251" + * "ti,bq24257" +- reg: integer, i2c address of the device. +- interrupt-parent: Should be the phandle for the interrupt controller. Use in + conjunction with "interrupts". +- interrupts: Interrupt mapping for GPIO IRQ (configure for both edges). Use in + conjunction with "interrupt-parent". +- ti,battery-regulation-voltage: integer, maximum charging voltage in uV. +- ti,charge-current: integer, maximum charging current in uA. +- ti,termination-current: integer, charge will be terminated when current in + constant-voltage phase drops below this value (in uA). + +Optional properties: +- pg-gpios: GPIO used for connecting the bq2425x device PG (Power Good) pin. + This pin is not available on all devices however it should be used if + possible as this is the recommended way to obtain the charger's input PG + state. If this pin is not specified a software-based approach for PG + detection is used. +- ti,current-limit: The maximum current to be drawn from the charger's input + (in uA). If this property is not specified, the input limit current is + set automatically using USB D+/D- signal based charger type detection. + If the hardware does not support the D+/D- based detection, a default + of 500,000 is used (=500mA) instead. +- ti,ovp-voltage: Configures the over voltage protection voltage (in uV). If + not specified a default of 6,5000,000 (=6.5V) is used. +- ti,in-dpm-voltage: Configures the threshold input voltage for the dynamic + power path management (in uV). If not specified a default of 4,360,000 + (=4.36V) is used. + +Example: + +bq24257 { + compatible = "ti,bq24257"; + reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + pg-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <1000000>; + ti,termination-current = <50000>; +}; + +Example: + +bq24250 { + compatible = "ti,bq24250"; + reg = <0x6a>; + interrupt-parent = <&gpio1>; + interrupts = <16 IRQ_TYPE_EDGE_BOTH>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <500000>; + ti,termination-current = <50000>; + ti,current-limit = <900000>; + ti,ovp-voltage = <9500000>; + ti,in-dpm-voltage = <4440000>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/bq25890.txt b/Documentation/devicetree/bindings/power/supply/bq25890.txt new file mode 100644 index 000000000000..c9dd17d142ad --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/bq25890.txt @@ -0,0 +1,46 @@ +Binding for TI bq25890 Li-Ion Charger + +Required properties: +- compatible: Should contain one of the following: + * "ti,bq25890" +- reg: integer, i2c address of the device. +- ti,battery-regulation-voltage: integer, maximum charging voltage (in uV); +- ti,charge-current: integer, maximum charging current (in uA); +- ti,termination-current: integer, charge will be terminated when current in + constant-voltage phase drops below this value (in uA); +- ti,precharge-current: integer, maximum charge current during precharge + phase (in uA); +- ti,minimum-sys-voltage: integer, when battery is charging and it is below + minimum system voltage, the system will be regulated above + minimum-sys-voltage setting (in uV); +- ti,boost-voltage: integer, VBUS voltage level in boost mode (in uV); +- ti,boost-max-current: integer, maximum allowed current draw in boost mode + (in uA). + +Optional properties: +- ti,boost-low-freq: boolean, if present boost mode frequency will be 500kHz, + otherwise 1.5MHz; +- ti,use-ilim-pin: boolean, if present the ILIM resistor will be used and the + input current will be the lower between the resistor setting and the IINLIM + register setting; +- ti,thermal-regulation-threshold: integer, temperature above which the charge + current is lowered, to avoid overheating (in degrees Celsius). If omitted, + the default setting will be used (120 degrees); + +Example: + +bq25890 { + compatible = "ti,bq25890"; + reg = <0x6a>; + + ti,battery-regulation-voltage = <4200000>; + ti,charge-current = <1000000>; + ti,termination-current = <50000>; + ti,precharge-current = <128000>; + ti,minimum-sys-voltage = <3600000>; + ti,boost-voltage = <5000000>; + ti,boost-max-current = <1000000>; + + ti,use-ilim-pin; + ti,thermal-regulation-threshold = <120>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/charger-manager.txt b/Documentation/devicetree/bindings/power/supply/charger-manager.txt new file mode 100644 index 000000000000..ec4fe9de3137 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/charger-manager.txt @@ -0,0 +1,81 @@ +charger-manager bindings +~~~~~~~~~~~~~~~~~~~~~~~~ + +Required properties : + - compatible : "charger-manager" + - <>-supply : for regulator consumer + - cm-num-chargers : number of chargers + - cm-chargers : name of chargers + - cm-fuel-gauge : name of battery fuel gauge + - subnode : + - cm-regulator-name : name of charger regulator + - subnode : + - cm-cable-name : name of charger cable + - cm-cable-extcon : name of extcon dev +(optional) - cm-cable-min : minimum current of cable +(optional) - cm-cable-max : maximum current of cable + +Optional properties : + - cm-name : charger manager's name (default : "battery") + - cm-poll-mode : polling mode (enum polling_modes) + - cm-poll-interval : polling interval + - cm-battery-stat : battery status (enum data_source) + - cm-fullbatt-* : data for full battery checking + - cm-thermal-zone : name of external thermometer's thermal zone + - cm-battery-* : threshold battery temperature for charging + -cold : critical cold temperature of battery for charging + -cold-in-minus : flag that cold temperature is in minus degrees + -hot : critical hot temperature of battery for charging + -temp-diff : temperature difference to allow recharging + - cm-dis/charging-max = limits of charging duration + +Example : + charger-manager@0 { + compatible = "charger-manager"; + chg-reg-supply = <&charger_regulator>; + + cm-name = "battery"; + /* Always polling ON : 30s */ + cm-poll-mode = <1>; + cm-poll-interval = <30000>; + + cm-fullbatt-vchkdrop-ms = <30000>; + cm-fullbatt-vchkdrop-volt = <150000>; + cm-fullbatt-soc = <100>; + + cm-battery-stat = <3>; + + cm-num-chargers = <3>; + cm-chargers = "charger0", "charger1", "charger2"; + + cm-fuel-gauge = "fuelgauge0"; + + cm-thermal-zone = "thermal_zone.1" + /* in deci centigrade */ + cm-battery-cold = <50>; + cm-battery-cold-in-minus; + cm-battery-hot = <800>; + cm-battery-temp-diff = <100>; + + /* Allow charging for 5hr */ + cm-charging-max = <18000000>; + /* Allow discharging for 2hr */ + cm-discharging-max = <7200000>; + + regulator@0 { + cm-regulator-name = "chg-reg"; + cable@0 { + cm-cable-name = "USB"; + cm-cable-extcon = "extcon-dev.0"; + cm-cable-min = <475000>; + cm-cable-max = <500000>; + }; + cable@1 { + cm-cable-name = "TA"; + cm-cable-extcon = "extcon-dev.0"; + cm-cable-min = <650000>; + cm-cable-max = <675000>; + }; + }; + + }; diff --git a/Documentation/devicetree/bindings/power/supply/da9150-charger.txt b/Documentation/devicetree/bindings/power/supply/da9150-charger.txt new file mode 100644 index 000000000000..f3906663c454 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/da9150-charger.txt @@ -0,0 +1,26 @@ +Dialog Semiconductor DA9150 Charger Power Supply bindings + +Required properties: +- compatible: "dlg,da9150-charger" for DA9150 Charger Power Supply + +Optional properties: +- io-channels: List of phandle and IIO specifier pairs +- io-channel-names: List of channel names used by charger + ["CHAN_IBUS", "CHAN_VBUS", "CHAN_TJUNC", "CHAN_VBAT"] + (See Documentation/devicetree/bindings/iio/iio-bindings.txt for further info) + + +Example: + + da9150-charger { + compatible = "dlg,da9150-charger"; + + io-channels = <&gpadc 0>, + <&gpadc 2>, + <&gpadc 8>, + <&gpadc 5>; + io-channel-names = "CHAN_IBUS", + "CHAN_VBUS", + "CHAN_TJUNC", + "CHAN_VBAT"; + }; diff --git a/Documentation/devicetree/bindings/power/supply/da9150-fg.txt b/Documentation/devicetree/bindings/power/supply/da9150-fg.txt new file mode 100644 index 000000000000..00236fe3ea31 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/da9150-fg.txt @@ -0,0 +1,23 @@ +Dialog Semiconductor DA9150 Fuel-Gauge Power Supply bindings + +Required properties: +- compatible: "dlg,da9150-fuel-gauge" for DA9150 Fuel-Gauge Power Supply + +Optional properties: +- dlg,update-interval: Interval time (milliseconds) between battery level checks. +- dlg,warn-soc-level: Battery discharge level (%) where warning event raised. + [1 - 100] +- dlg,crit-soc-level: Battery discharge level (%) where critical event raised. + This value should be lower than the warning level. + [1 - 100] + + +Example: + + fuel-gauge { + compatible = "dlg,da9150-fuel-gauge"; + + dlg,update-interval = <10000>; + dlg,warn-soc-level = /bits/ 8 <15>; + dlg,crit-soc-level = /bits/ 8 <5>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/gpio-charger.txt b/Documentation/devicetree/bindings/power/supply/gpio-charger.txt new file mode 100644 index 000000000000..adbb5dc5b6e9 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/gpio-charger.txt @@ -0,0 +1,27 @@ +gpio-charger + +Required properties : + - compatible : "gpio-charger" + - gpios : GPIO indicating the charger presence. + See GPIO binding in bindings/gpio/gpio.txt . + - charger-type : power supply type, one of + unknown + battery + ups + mains + usb-sdp (USB standard downstream port) + usb-dcp (USB dedicated charging port) + usb-cdp (USB charging downstream port) + usb-aca (USB accessory charger adapter) + +Example: + + usb_charger: charger { + compatible = "gpio-charger"; + charger-type = "usb-sdp"; + gpios = <&gpf0 2 0 0 0>; + } + + battery { + power-supplies = <&usb_charger>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/isp1704.txt b/Documentation/devicetree/bindings/power/supply/isp1704.txt new file mode 100644 index 000000000000..fa3596907967 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/isp1704.txt @@ -0,0 +1,17 @@ +Binding for NXP ISP1704 USB Charger Detection + +Required properties: +- compatible: Should contain one of the following: + * "nxp,isp1704" +- nxp,enable-gpio: Should contain a phandle + gpio-specifier + to the GPIO pin connected to the chip's enable pin. +- usb-phy: Should contain a phandle to the USB PHY + the ISP1704 is connected to. + +Example: + +isp1704 { + compatible = "nxp,isp1704"; + nxp,enable-gpio = <&gpio3 3 GPIO_ACTIVE_LOW>; + usb-phy = <&usb2_phy>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt b/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt new file mode 100644 index 000000000000..2246bc5c874b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/lp8727_charger.txt @@ -0,0 +1,44 @@ +Binding for TI/National Semiconductor LP8727 Charger + +Required properties: +- compatible: "ti,lp8727" +- reg: I2C slave address 27h + +Optional properties: +- interrupt-parent: interrupt controller node (see interrupt binding[0]) +- interrupts: interrupt specifier (see interrupt binding[0]) +- debounce-ms: interrupt debounce time. (u32) + +AC and USB charging parameters +- charger-type: "ac" or "usb" (string) +- eoc-level: value of 'enum lp8727_eoc_level' (u8) +- charging-current: value of 'enum lp8727_ichg' (u8) + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Example) + +lp8727@27 { + compatible = "ti,lp8727"; + reg = <0x27>; + + /* GPIO 134 is used for LP8728 interrupt pin */ + interrupt-parent = <&gpio5>; /* base = 128 */ + interrupts = <6 0x2>; /* offset = 6, falling edge type */ + + debounce-ms = <300>; + + /* AC charger: 5% EOC and 500mA charging current */ + ac { + charger-type = "ac"; + eoc-level = /bits/ 8 <0>; + charging-current = /bits/ 8 <4>; + }; + + /* USB charger: 10% EOC and 400mA charging current */ + usb { + charger-type = "usb"; + eoc-level = /bits/ 8 <1>; + charging-current = /bits/ 8 <2>; + }; +}; diff --git a/Documentation/devicetree/bindings/power/supply/ltc2941.txt b/Documentation/devicetree/bindings/power/supply/ltc2941.txt new file mode 100644 index 000000000000..ea42ae12d924 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ltc2941.txt @@ -0,0 +1,27 @@ +binding for LTC2941 and LTC2943 battery gauges + +Both the LTC2941 and LTC2943 measure battery capacity. +The LTC2943 is compatible with the LTC2941, it adds voltage and +temperature monitoring, and uses a slightly different conversion +formula for the charge counter. + +Required properties: +- compatible: Should contain "ltc2941" or "ltc2943" which also indicates the + type of I2C chip attached. +- reg: The 7-bit I2C address. +- lltc,resistor-sense: The sense resistor value in milli-ohms. Can be a 32-bit + negative value when the battery has been connected to the wrong end of the + resistor. +- lltc,prescaler-exponent: The prescaler exponent as explained in the datasheet. + This determines the range and accuracy of the gauge. The value is programmed + into the chip only if it differs from the current setting. The setting is + lost when the battery is disconnected. + +Example from the Topic Miami Florida board: + + fuelgauge: ltc2943@64 { + compatible = "ltc2943"; + reg = <0x64>; + lltc,resistor-sense = <15>; + lltc,prescaler-exponent = <5>; /* 2^(2*5) = 1024 */ + }; diff --git a/Documentation/devicetree/bindings/power/supply/max17042_battery.txt b/Documentation/devicetree/bindings/power/supply/max17042_battery.txt new file mode 100644 index 000000000000..3f3894aaeebc --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/max17042_battery.txt @@ -0,0 +1,31 @@ +max17042_battery +~~~~~~~~~~~~~~~~ + +Required properties : + - compatible : "maxim,max17042" + +Optional properties : + - maxim,rsns-microohm : Resistance of rsns resistor in micro Ohms + (datasheet-recommended value is 10000). + Defining this property enables current-sense functionality. + +Optional threshold properties : + If skipped the condition won't be reported. + - maxim,cold-temp : Temperature threshold to report battery + as cold (in tenths of degree Celsius). + - maxim,over-heat-temp : Temperature threshold to report battery + as over heated (in tenths of degree Celsius). + - maxim,dead-volt : Voltage threshold to report battery + as dead (in mV). + - maxim,over-volt : Voltage threshold to report battery + as over voltage (in mV). + +Example: + + battery-charger@36 { + compatible = "maxim,max17042"; + reg = <0x36>; + maxim,rsns-microohm = <10000>; + maxim,over-heat-temp = <600>; + maxim,over-volt = <4300>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/max8925_batter.txt b/Documentation/devicetree/bindings/power/supply/max8925_batter.txt new file mode 100644 index 000000000000..d7e3e0c0f71d --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/max8925_batter.txt @@ -0,0 +1,18 @@ +max8925-battery bindings +~~~~~~~~~~~~~~~~ + +Optional properties : + - batt-detect: whether support battery detect + - topoff-threshold: set charging current in topoff mode + - fast-charge: set charging current in fast mode + - no-temp-support: whether support temperature protection detect + - no-insert-detect: whether support insert detect + +Example: + charger { + batt-detect = <0>; + topoff-threshold = <1>; + fast-charge = <7>; + no-temp-support = <0>; + no-insert-detect = <0>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/olpc_battery.txt b/Documentation/devicetree/bindings/power/supply/olpc_battery.txt new file mode 100644 index 000000000000..c8901b3992d9 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/olpc_battery.txt @@ -0,0 +1,5 @@ +OLPC battery +~~~~~~~~~~~~ + +Required properties: + - compatible : "olpc,xo1-battery" diff --git a/Documentation/devicetree/bindings/power/supply/power_supply.txt b/Documentation/devicetree/bindings/power/supply/power_supply.txt new file mode 100644 index 000000000000..8391bfa0edac --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/power_supply.txt @@ -0,0 +1,23 @@ +Power Supply Core Support + +Optional Properties: + - power-supplies : This property is added to a supply in order to list the + devices which supply it power, referenced by their phandles. + +Example: + + usb-charger: power@e { + compatible = "some,usb-charger"; + ... + }; + + ac-charger: power@c { + compatible = "some,ac-charger"; + ... + }; + + battery@b { + compatible = "some,battery"; + ... + power-supplies = <&usb-charger>, <&ac-charger>; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt b/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt new file mode 100644 index 000000000000..747899223262 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom,coincell-charger.txt @@ -0,0 +1,48 @@ +Qualcomm Coincell Charger: + +The hardware block controls charging for a coincell or capacitor that is +used to provide power backup for certain features of the power management +IC (PMIC) + +- compatible: + Usage: required + Value type: + Definition: must be: "qcom,pm8941-coincell" + +- reg: + Usage: required + Value type: + Definition: base address of the coincell charger registers + +- qcom,rset-ohms: + Usage: required + Value type: + Definition: resistance (in ohms) for current-limiting resistor + must be one of: 800, 1200, 1700, 2100 + +- qcom,vset-millivolts: + Usage: required + Value type: + Definition: voltage (in millivolts) to apply for charging + must be one of: 2500, 3000, 3100, 3200 + +- qcom,charger-disable: + Usage: optional + Value type: + Definition: defining this property disables charging + +This charger is a sub-node of one of the 8941 PMIC blocks, and is specified +as a child node in DTS of that node. See ../mfd/qcom,spmi-pmic.txt and +../mfd/qcom-pm8xxx.txt + +Example: + + pm8941@0 { + coincell@2800 { + compatible = "qcom,pm8941-coincell"; + reg = <0x2800>; + + qcom,rset-ohms = <2100>; + qcom,vset-millivolts = <3000>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt b/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt new file mode 100644 index 000000000000..65b88fac854b --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/qcom_smbb.txt @@ -0,0 +1,131 @@ +Qualcomm Switch-Mode Battery Charger and Boost + +PROPERTIES +- compatible: + Usage: required + Value type: + Description: Must be one of: + - "qcom,pm8941-charger" + +- reg: + Usage: required + Value type: + Description: Base address of registers for SMBB block + +- interrupts: + Usage: required + Value type: + Description: The format of the specifier is defined by the binding document + describing the node's interrupt parent. Must contain one + specifier for each of the following interrupts, in order: + - charge done + - charge fast mode + - charge trickle mode + - battery temperature ok + - battery present + - charger disconnected + - USB-in valid + - DC-in valid + +- interrupt-names: + Usage: required + Value type: + Description: Must contain the following list, strictly ordered: + "chg-done", + "chg-fast", + "chg-trkl", + "bat-temp-ok", + "bat-present", + "chg-gone", + "usb-valid", + "dc-valid" + +- qcom,fast-charge-current-limit: + Usage: optional (default: 1A, or pre-configured value) + Value type: ; uA; range [100mA : 3A] + Description: Maximum charge current; May be clamped to safety limits. + +- qcom,fast-charge-low-threshold-voltage: + Usage: optional (default: 3.2V, or pre-configured value) + Value type: ; uV; range [2.1V : 3.6V] + Description: Battery voltage limit above which fast charging may operate; + Below this value linear or switch-mode auto-trickle-charging + will operate. + +- qcom,fast-charge-high-threshold-voltage: + Usage: optional (default: 4.2V, or pre-configured value) + Value type: ; uV; range [3.24V : 5V] + Description: Battery voltage limit below which fast charging may operate; + The fast charger will attempt to charge the battery to this + voltage. May be clamped to safety limits. + +- qcom,fast-charge-safe-voltage: + Usage: optional (default: 4.2V, or pre-configured value) + Value type: ; uV; range [3.24V : 5V] + Description: Maximum safe battery voltage; May be pre-set by bootloader, in + which case, setting this will harmlessly fail. The property + 'fast-charge-high-watermark' will be clamped by this value. + +- qcom,fast-charge-safe-current: + Usage: optional (default: 1A, or pre-configured value) + Value type: ; uA; range [100mA : 3A] + Description: Maximum safe battery charge current; May pre-set by bootloader, + in which case, setting this will harmlessly fail. The property + 'qcom,fast-charge-current-limit' will be clamped by this value. + +- qcom,auto-recharge-threshold-voltage: + Usage: optional (default: 4.1V, or pre-configured value) + Value type: ; uV; range [3.24V : 5V] + Description: Battery voltage limit below which auto-recharge functionality + will restart charging after end-of-charge; The high cutoff + limit for auto-recharge is 5% above this value. + +- qcom,minimum-input-voltage: + Usage: optional (default: 4.3V, or pre-configured value) + Value type: ; uV; range [4.2V : 9.6V] + Description: Input voltage level above which charging may operate + +- qcom,dc-current-limit: + Usage: optional (default: 100mA, or pre-configured value) + Value type: ; uA; range [100mA : 2.5A] + Description: Default DC charge current limit + +- qcom,disable-dc: + Usage: optional (default: false) + Value type: boolean: or + Description: Disable DC charger + +- qcom,jeita-extended-temp-range: + Usage: optional (default: false) + Value type: boolean: or + Description: Enable JEITA extended temperature range; This does *not* + adjust the maximum charge voltage or current in the extended + temperature range. It only allows charging when the battery + is in the extended temperature range. Voltage/current + regulation must be done externally to fully comply with + the JEITA safety guidelines if this flag is set. + +EXAMPLE +charger@1000 { + compatible = "qcom,pm8941-charger"; + reg = <0x1000 0x700>; + interrupts = <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x10 4 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, + <0x0 0x14 1 IRQ_TYPE_EDGE_BOTH>; + interrupt-names = "chg-done", + "chg-fast", + "chg-trkl", + "bat-temp-ok", + "bat-present", + "chg-gone", + "usb-valid", + "dc-valid"; + + qcom,fast-charge-current-limit = <1000000>; + qcom,dc-charge-current-limit = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt b/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt new file mode 100644 index 000000000000..5d9ad5cf2c5a --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/rt9455_charger.txt @@ -0,0 +1,48 @@ +Binding for Richtek rt9455 battery charger + +Required properties: +- compatible: it should contain one of the following: + "richtek,rt9455". +- reg: integer, i2c address of the device. +- interrupt-parent: the phandle for the interrupt controller that + services interrupts for this device. +- interrupts: interrupt mapping for GPIO IRQ, it should be + configured with IRQ_TYPE_LEVEL_LOW flag. +- richtek,output-charge-current: integer, output current from the charger to the + battery, in uA. +- richtek,end-of-charge-percentage: integer, percent of the output charge current. + When the current in constant-voltage phase drops + below output_charge_current x end-of-charge-percentage, + charge is terminated. +- richtek,battery-regulation-voltage: integer, maximum battery voltage in uV. +- richtek,boost-output-voltage: integer, maximum voltage provided to consumer + devices, when the charger is in boost mode, in uV. + +Optional properties: +- richtek,min-input-voltage-regulation: integer, input voltage level in uV, used to + decrease voltage level when the over current + of the input power source occurs. + This prevents input voltage drop due to insufficient + current provided by the power source. + Default: 4500000 uV (4.5V) +- richtek,avg-input-current-regulation: integer, input current value in uA drained by the + charger from the power source. + Default: 500000 uA (500mA) + +Example: + +rt9455@22 { + compatible = "richtek,rt9455"; + reg = <0x22>; + + interrupt-parent = <&gpio1>; + interrupts = <0 IRQ_TYPE_LEVEL_LOW>; + + richtek,output-charge-current = <500000>; + richtek,end-of-charge-percentage = <10>; + richtek,battery-regulation-voltage = <4200000>; + richtek,boost-output-voltage = <5050000>; + + richtek,min-input-voltage-regulation = <4500000>; + richtek,avg-input-current-regulation = <500000>; +}; diff --git a/Documentation/devicetree/bindings/power/supply/rx51-battery.txt b/Documentation/devicetree/bindings/power/supply/rx51-battery.txt new file mode 100644 index 000000000000..90438453db58 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/rx51-battery.txt @@ -0,0 +1,25 @@ +Binding for Nokia N900 battery + +The Nokia N900 battery status can be read via the TWL4030's A/D converter. + +Required properties: +- compatible: Should contain one of the following: + * "nokia,n900-battery" +- io-channels: Should contain IIO channel specifiers + for each element in io-channel-names. +- io-channel-names: Should contain the following values: + * "temp" - The ADC channel for temperature reading + * "bsi" - The ADC channel for battery size identification + * "vbat" - The ADC channel to measure the battery voltage + +Example from Nokia N900: + +battery: n900-battery { + compatible = "nokia,n900-battery"; + io-channels = <&twl4030_madc 0>, + <&twl4030_madc 4>, + <&twl4030_madc 12>; + io-channel-names = "temp", + "bsi", + "vbat"; +}; diff --git a/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt b/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt new file mode 100644 index 000000000000..c40e8926facf --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sbs_sbs-battery.txt @@ -0,0 +1,23 @@ +SBS sbs-battery +~~~~~~~~~~ + +Required properties : + - compatible : "sbs,sbs-battery" + +Optional properties : + - sbs,i2c-retry-count : The number of times to retry i2c transactions on i2c + IO failure. + - sbs,poll-retry-count : The number of times to try looking for new status + after an external change notification. + - sbs,battery-detect-gpios : The gpio which signals battery detection and + a flag specifying its polarity. + +Example: + + bq20z75@b { + compatible = "sbs,sbs-battery"; + reg = < 0xb >; + sbs,i2c-retry-count = <2>; + sbs,poll-retry-count = <10>; + sbs,battery-detect-gpios = <&gpio-controller 122 1>; + } diff --git a/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt b/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt new file mode 100644 index 000000000000..3bf55757ceec --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/ti,bq24735.txt @@ -0,0 +1,35 @@ +TI BQ24735 Charge Controller +~~~~~~~~~~ + +Required properties : + - compatible : "ti,bq24735" + +Optional properties : + - interrupts : Specify the interrupt to be used to trigger when the AC + adapter is either plugged in or removed. + - ti,ac-detect-gpios : This GPIO is optionally used to read the AC adapter + presence. This is a Host GPIO that is configured as an input and + connected to the bq24735. + - ti,charge-current : Used to control and set the charging current. This value + must be between 128mA and 8.128A with a 64mA step resolution. The POR value + is 0x0000h. This number is in mA (e.g. 8192), see spec for more information + about the ChargeCurrent (0x14h) register. + - ti,charge-voltage : Used to control and set the charging voltage. This value + must be between 1.024V and 19.2V with a 16mV step resolution. The POR value + is 0x0000h. This number is in mV (e.g. 19200), see spec for more information + about the ChargeVoltage (0x15h) register. + - ti,input-current : Used to control and set the charger input current. This + value must be between 128mA and 8.064A with a 128mA step resolution. The + POR value is 0x1000h. This number is in mA (e.g. 8064), see the spec for + more information about the InputCurrent (0x3fh) register. + - ti,external-control : Indicates that the charger is configured externally + and that the host should not attempt to enable/disable charging or set the + charge voltage/current. + +Example: + + bq24735@9 { + compatible = "ti,bq24735"; + reg = <0x9>; + ti,ac-detect-gpios = <&gpio 72 0x1>; + } diff --git a/Documentation/devicetree/bindings/power/supply/tps65090.txt b/Documentation/devicetree/bindings/power/supply/tps65090.txt new file mode 100644 index 000000000000..8e5e0d3910df --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/tps65090.txt @@ -0,0 +1,17 @@ +TPS65090 Frontend PMU with Switchmode Charger + +Required Properties: +-compatible: "ti,tps65090-charger" + +Optional Properties: +-ti,enable-low-current-chrg: Enables charging when a low current is detected + while the default logic is to stop charging. + +This node is a subnode of the tps65090 PMIC. + +Example: + + tps65090-charger { + compatible = "ti,tps65090-charger"; + ti,enable-low-current-chrg; + }; diff --git a/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt b/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt new file mode 100644 index 000000000000..98d131acee95 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/tps65217_charger.txt @@ -0,0 +1,12 @@ +TPS65217 Charger + +Required Properties: +-compatible: "ti,tps65217-charger" + +This node is a subnode of the tps65217 PMIC. + +Example: + + tps65217-charger { + compatible = "ti,tps65090-charger"; + }; diff --git a/Documentation/devicetree/bindings/power/supply/twl-charger.txt b/Documentation/devicetree/bindings/power/supply/twl-charger.txt new file mode 100644 index 000000000000..3b4ea1b73b38 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/twl-charger.txt @@ -0,0 +1,30 @@ +TWL BCI (Battery Charger Interface) + +The battery charger needs to interact with the USB phy in order +to know when charging is permissible, and when there is a connection +or disconnection. + +The choice of phy cannot be configured at a hardware level, so there +is no value in explicit configuration in device-tree. Rather +if there is a sibling of the BCI node which is compatible with +"ti,twl4030-usb", then that is used to determine when and how +use USB power for charging. + +Required properties: +- compatible: + - "ti,twl4030-bci" +- interrupts: two interrupt lines from the TWL SIH (secondary + interrupt handler) - interrupts 9 and 2. + +Optional properties: +- ti,bb-uvolt: microvolts for charging the backup battery. +- ti,bb-uamp: microamps for charging the backup battery. + +Examples: + +bci { + compatible = "ti,twl4030-bci"; + interrupts = <9>, <2>; + ti,bb-uvolt = <3200000>; + ti,bb-uamp = <150>; +}; diff --git a/Documentation/devicetree/bindings/power/twl-charger.txt b/Documentation/devicetree/bindings/power/twl-charger.txt deleted file mode 100644 index 3b4ea1b73b38..000000000000 --- a/Documentation/devicetree/bindings/power/twl-charger.txt +++ /dev/null @@ -1,30 +0,0 @@ -TWL BCI (Battery Charger Interface) - -The battery charger needs to interact with the USB phy in order -to know when charging is permissible, and when there is a connection -or disconnection. - -The choice of phy cannot be configured at a hardware level, so there -is no value in explicit configuration in device-tree. Rather -if there is a sibling of the BCI node which is compatible with -"ti,twl4030-usb", then that is used to determine when and how -use USB power for charging. - -Required properties: -- compatible: - - "ti,twl4030-bci" -- interrupts: two interrupt lines from the TWL SIH (secondary - interrupt handler) - interrupts 9 and 2. - -Optional properties: -- ti,bb-uvolt: microvolts for charging the backup battery. -- ti,bb-uamp: microamps for charging the backup battery. - -Examples: - -bci { - compatible = "ti,twl4030-bci"; - interrupts = <9>, <2>; - ti,bb-uvolt = <3200000>; - ti,bb-uamp = <150>; -}; diff --git a/Documentation/devicetree/bindings/power_supply/ab8500/btemp.txt b/Documentation/devicetree/bindings/power_supply/ab8500/btemp.txt deleted file mode 100644 index 0ba1bcc7f33a..000000000000 --- a/Documentation/devicetree/bindings/power_supply/ab8500/btemp.txt +++ /dev/null @@ -1,16 +0,0 @@ -=== AB8500 Battery Temperature Monitor Driver === - -The properties below describes the node for btemp driver. - -Required Properties: -- compatible = Shall be: "stericsson,ab8500-btemp" -- battery = Shall be battery specific information - - Example: - ab8500_btemp { - compatible = "stericsson,ab8500-btemp"; - battery = <&ab8500_battery>; - }; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power_supply/ab8500/chargalg.txt b/Documentation/devicetree/bindings/power_supply/ab8500/chargalg.txt deleted file mode 100644 index ef5328371122..000000000000 --- a/Documentation/devicetree/bindings/power_supply/ab8500/chargalg.txt +++ /dev/null @@ -1,16 +0,0 @@ -=== AB8500 Charging Algorithm Driver === - -The properties below describes the node for chargalg driver. - -Required Properties: -- compatible = Shall be: "stericsson,ab8500-chargalg" -- battery = Shall be battery specific information - -Example: -ab8500_chargalg { - compatible = "stericsson,ab8500-chargalg"; - battery = <&ab8500_battery>; -}; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power_supply/ab8500/charger.txt b/Documentation/devicetree/bindings/power_supply/ab8500/charger.txt deleted file mode 100644 index 6bdbb08ea9e0..000000000000 --- a/Documentation/devicetree/bindings/power_supply/ab8500/charger.txt +++ /dev/null @@ -1,25 +0,0 @@ -=== AB8500 Charger Driver === - -Required Properties: -- compatible = Shall be "stericsson,ab8500-charger" -- battery = Shall be battery specific information - Example: - ab8500_charger { - compatible = "stericsson,ab8500-charger"; - battery = <&ab8500_battery>; - }; - -- vddadc-supply: Supply for USB and Main charger - Example: - ab8500-charger { - vddadc-supply = <&ab8500_ldo_tvout_reg>; - } -- autopower_cfg: - Boolean value depicting the presence of 'automatic poweron after powerloss' - Example: - ab8500-charger { - autopower_cfg; - }; - -For information on battery specific node, Ref: -Documentation/devicetree/bindings/power_supply/ab8500/fg.txt diff --git a/Documentation/devicetree/bindings/power_supply/ab8500/fg.txt b/Documentation/devicetree/bindings/power_supply/ab8500/fg.txt deleted file mode 100644 index ccafcb9112fb..000000000000 --- a/Documentation/devicetree/bindings/power_supply/ab8500/fg.txt +++ /dev/null @@ -1,58 +0,0 @@ -=== AB8500 Fuel Gauge Driver === - -AB8500 is a mixed signal multimedia and power management -device comprising: power and energy-management-module, -wall-charger, usb-charger, audio codec, general purpose adc, -tvout, clock management and sim card interface. - -Fuelgauge support is part of energy-management-modules, other -components of this module are: -main-charger, usb-combo-charger and battery-temperature-monitoring. - -The properties below describes the node for fuelgauge driver. - -Required Properties: -- compatible = This shall be: "stericsson,ab8500-fg" -- battery = Shall be battery specific information - Example: - ab8500_fg { - compatible = "stericsson,ab8500-fg"; - battery = <&ab8500_battery>; - }; - -dependent node: - ab8500_battery: ab8500_battery { - }; - This node will provide information on 'thermistor interface' and - 'battery technology type' used. - -Properties of this node are: -thermistor-on-batctrl: - A boolean value indicating thermistor interface to battery - - Note: - 'btemp' and 'batctrl' are the pins interfaced for battery temperature - measurement, 'btemp' signal is used when NTC(negative temperature - coefficient) resister is interfaced external to battery whereas - 'batctrl' pin is used when NTC resister is internal to battery. - - Example: - ab8500_battery: ab8500_battery { - thermistor-on-batctrl; - }; - indicates: NTC resister is internal to battery, 'batctrl' is used - for thermal measurement. - - The absence of property 'thermal-on-batctrl' indicates - NTC resister is external to battery and 'btemp' signal is used - for thermal measurement. - -battery-type: - This shall be the battery manufacturing technology type, - allowed types are: - "UNKNOWN" "NiMH" "LION" "LIPO" "LiFe" "NiCd" "LiMn" - Example: - ab8500_battery: ab8500_battery { - stericsson,battery-type = "LIPO"; - } - diff --git a/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt b/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt deleted file mode 100644 index f1d7beec45bf..000000000000 --- a/Documentation/devicetree/bindings/power_supply/axp20x_usb_power.txt +++ /dev/null @@ -1,35 +0,0 @@ -AXP20x USB power supply - -Required Properties: --compatible: One of: "x-powers,axp202-usb-power-supply" - "x-powers,axp221-usb-power-supply" - -This node is a subnode of the axp20x PMIC. - -Example: - -axp209: pmic@34 { - compatible = "x-powers,axp209"; - reg = <0x34>; - interrupt-parent = <&nmi_intc>; - interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <1>; - - regulators { - x-powers,dcdc-freq = <1500>; - - vdd_cpu: dcdc2 { - regulator-always-on; - regulator-min-microvolt = <1000000>; - regulator-max-microvolt = <1450000>; - regulator-name = "vdd-cpu"; - }; - - ... - }; - - usb-power-supply: usb-power-supply { - compatible = "x-powers,axp202-usb-power-supply"; - }; -}; diff --git a/Documentation/devicetree/bindings/power_supply/axxia-reset.txt b/Documentation/devicetree/bindings/power_supply/axxia-reset.txt deleted file mode 100644 index 47e720d249d2..000000000000 --- a/Documentation/devicetree/bindings/power_supply/axxia-reset.txt +++ /dev/null @@ -1,20 +0,0 @@ -Axxia Restart Driver - -This driver can do reset of the Axxia SoC. It uses the registers in the syscon -block to initiate a chip reset. - -Required Properties: - -compatible: "lsi,axm55xx-reset" - -syscon: phandle to the syscon node. - -Example: - - syscon: syscon@2010030000 { - compatible = "lsi,axxia-syscon", "syscon"; - reg = <0x20 0x10030000 0 0x2000>; - }; - - reset: reset@2010031000 { - compatible = "lsi,axm55xx-reset"; - syscon = <&syscon>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/charger-manager.txt b/Documentation/devicetree/bindings/power_supply/charger-manager.txt deleted file mode 100644 index ec4fe9de3137..000000000000 --- a/Documentation/devicetree/bindings/power_supply/charger-manager.txt +++ /dev/null @@ -1,81 +0,0 @@ -charger-manager bindings -~~~~~~~~~~~~~~~~~~~~~~~~ - -Required properties : - - compatible : "charger-manager" - - <>-supply : for regulator consumer - - cm-num-chargers : number of chargers - - cm-chargers : name of chargers - - cm-fuel-gauge : name of battery fuel gauge - - subnode : - - cm-regulator-name : name of charger regulator - - subnode : - - cm-cable-name : name of charger cable - - cm-cable-extcon : name of extcon dev -(optional) - cm-cable-min : minimum current of cable -(optional) - cm-cable-max : maximum current of cable - -Optional properties : - - cm-name : charger manager's name (default : "battery") - - cm-poll-mode : polling mode (enum polling_modes) - - cm-poll-interval : polling interval - - cm-battery-stat : battery status (enum data_source) - - cm-fullbatt-* : data for full battery checking - - cm-thermal-zone : name of external thermometer's thermal zone - - cm-battery-* : threshold battery temperature for charging - -cold : critical cold temperature of battery for charging - -cold-in-minus : flag that cold temperature is in minus degrees - -hot : critical hot temperature of battery for charging - -temp-diff : temperature difference to allow recharging - - cm-dis/charging-max = limits of charging duration - -Example : - charger-manager@0 { - compatible = "charger-manager"; - chg-reg-supply = <&charger_regulator>; - - cm-name = "battery"; - /* Always polling ON : 30s */ - cm-poll-mode = <1>; - cm-poll-interval = <30000>; - - cm-fullbatt-vchkdrop-ms = <30000>; - cm-fullbatt-vchkdrop-volt = <150000>; - cm-fullbatt-soc = <100>; - - cm-battery-stat = <3>; - - cm-num-chargers = <3>; - cm-chargers = "charger0", "charger1", "charger2"; - - cm-fuel-gauge = "fuelgauge0"; - - cm-thermal-zone = "thermal_zone.1" - /* in deci centigrade */ - cm-battery-cold = <50>; - cm-battery-cold-in-minus; - cm-battery-hot = <800>; - cm-battery-temp-diff = <100>; - - /* Allow charging for 5hr */ - cm-charging-max = <18000000>; - /* Allow discharging for 2hr */ - cm-discharging-max = <7200000>; - - regulator@0 { - cm-regulator-name = "chg-reg"; - cable@0 { - cm-cable-name = "USB"; - cm-cable-extcon = "extcon-dev.0"; - cm-cable-min = <475000>; - cm-cable-max = <500000>; - }; - cable@1 { - cm-cable-name = "TA"; - cm-cable-extcon = "extcon-dev.0"; - cm-cable-min = <650000>; - cm-cable-max = <675000>; - }; - }; - - }; diff --git a/Documentation/devicetree/bindings/power_supply/gpio-charger.txt b/Documentation/devicetree/bindings/power_supply/gpio-charger.txt deleted file mode 100644 index adbb5dc5b6e9..000000000000 --- a/Documentation/devicetree/bindings/power_supply/gpio-charger.txt +++ /dev/null @@ -1,27 +0,0 @@ -gpio-charger - -Required properties : - - compatible : "gpio-charger" - - gpios : GPIO indicating the charger presence. - See GPIO binding in bindings/gpio/gpio.txt . - - charger-type : power supply type, one of - unknown - battery - ups - mains - usb-sdp (USB standard downstream port) - usb-dcp (USB dedicated charging port) - usb-cdp (USB charging downstream port) - usb-aca (USB accessory charger adapter) - -Example: - - usb_charger: charger { - compatible = "gpio-charger"; - charger-type = "usb-sdp"; - gpios = <&gpf0 2 0 0 0>; - } - - battery { - power-supplies = <&usb_charger>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt b/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt deleted file mode 100644 index dc7c9bad63ea..000000000000 --- a/Documentation/devicetree/bindings/power_supply/imx-snvs-poweroff.txt +++ /dev/null @@ -1,23 +0,0 @@ -i.mx6 Poweroff Driver - -SNVS_LPCR in SNVS module can power off the whole system by pull -PMIC_ON_REQ low if PMIC_ON_REQ is connected with external PMIC. -If you don't want to use PMIC_ON_REQ as power on/off control, -please set status='disabled' to disable this driver. - -Required Properties: --compatible: "fsl,sec-v4.0-poweroff" --reg: Specifies the physical address of the SNVS_LPCR register - -Example: - snvs@020cc000 { - compatible = "fsl,sec-v4.0-mon", "simple-bus"; - #address-cells = <1>; - #size-cells = <1>; - ranges = <0 0x020cc000 0x4000>; - ..... - snvs_poweroff: snvs-poweroff@38 { - compatible = "fsl,sec-v4.0-poweroff"; - reg = <0x38 0x4>; - }; - } diff --git a/Documentation/devicetree/bindings/power_supply/lp8727_charger.txt b/Documentation/devicetree/bindings/power_supply/lp8727_charger.txt deleted file mode 100644 index 2246bc5c874b..000000000000 --- a/Documentation/devicetree/bindings/power_supply/lp8727_charger.txt +++ /dev/null @@ -1,44 +0,0 @@ -Binding for TI/National Semiconductor LP8727 Charger - -Required properties: -- compatible: "ti,lp8727" -- reg: I2C slave address 27h - -Optional properties: -- interrupt-parent: interrupt controller node (see interrupt binding[0]) -- interrupts: interrupt specifier (see interrupt binding[0]) -- debounce-ms: interrupt debounce time. (u32) - -AC and USB charging parameters -- charger-type: "ac" or "usb" (string) -- eoc-level: value of 'enum lp8727_eoc_level' (u8) -- charging-current: value of 'enum lp8727_ichg' (u8) - -[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt - -Example) - -lp8727@27 { - compatible = "ti,lp8727"; - reg = <0x27>; - - /* GPIO 134 is used for LP8728 interrupt pin */ - interrupt-parent = <&gpio5>; /* base = 128 */ - interrupts = <6 0x2>; /* offset = 6, falling edge type */ - - debounce-ms = <300>; - - /* AC charger: 5% EOC and 500mA charging current */ - ac { - charger-type = "ac"; - eoc-level = /bits/ 8 <0>; - charging-current = /bits/ 8 <4>; - }; - - /* USB charger: 10% EOC and 400mA charging current */ - usb { - charger-type = "usb"; - eoc-level = /bits/ 8 <1>; - charging-current = /bits/ 8 <2>; - }; -}; diff --git a/Documentation/devicetree/bindings/power_supply/max17042_battery.txt b/Documentation/devicetree/bindings/power_supply/max17042_battery.txt deleted file mode 100644 index 3f3894aaeebc..000000000000 --- a/Documentation/devicetree/bindings/power_supply/max17042_battery.txt +++ /dev/null @@ -1,31 +0,0 @@ -max17042_battery -~~~~~~~~~~~~~~~~ - -Required properties : - - compatible : "maxim,max17042" - -Optional properties : - - maxim,rsns-microohm : Resistance of rsns resistor in micro Ohms - (datasheet-recommended value is 10000). - Defining this property enables current-sense functionality. - -Optional threshold properties : - If skipped the condition won't be reported. - - maxim,cold-temp : Temperature threshold to report battery - as cold (in tenths of degree Celsius). - - maxim,over-heat-temp : Temperature threshold to report battery - as over heated (in tenths of degree Celsius). - - maxim,dead-volt : Voltage threshold to report battery - as dead (in mV). - - maxim,over-volt : Voltage threshold to report battery - as over voltage (in mV). - -Example: - - battery-charger@36 { - compatible = "maxim,max17042"; - reg = <0x36>; - maxim,rsns-microohm = <10000>; - maxim,over-heat-temp = <600>; - maxim,over-volt = <4300>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/max8925_batter.txt b/Documentation/devicetree/bindings/power_supply/max8925_batter.txt deleted file mode 100644 index d7e3e0c0f71d..000000000000 --- a/Documentation/devicetree/bindings/power_supply/max8925_batter.txt +++ /dev/null @@ -1,18 +0,0 @@ -max8925-battery bindings -~~~~~~~~~~~~~~~~ - -Optional properties : - - batt-detect: whether support battery detect - - topoff-threshold: set charging current in topoff mode - - fast-charge: set charging current in fast mode - - no-temp-support: whether support temperature protection detect - - no-insert-detect: whether support insert detect - -Example: - charger { - batt-detect = <0>; - topoff-threshold = <1>; - fast-charge = <7>; - no-temp-support = <0>; - no-insert-detect = <0>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/msm-poweroff.txt b/Documentation/devicetree/bindings/power_supply/msm-poweroff.txt deleted file mode 100644 index ce44ad357565..000000000000 --- a/Documentation/devicetree/bindings/power_supply/msm-poweroff.txt +++ /dev/null @@ -1,17 +0,0 @@ -MSM Restart Driver - -A power supply hold (ps-hold) bit is set to power the msm chipsets. -Clearing that bit allows us to restart/poweroff. The difference -between poweroff and restart is determined by unique power manager IC -settings. - -Required Properties: --compatible: "qcom,pshold" --reg: Specifies the physical address of the ps-hold register - -Example: - - restart@fc4ab000 { - compatible = "qcom,pshold"; - reg = <0xfc4ab000 0x4>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/olpc_battery.txt b/Documentation/devicetree/bindings/power_supply/olpc_battery.txt deleted file mode 100644 index c8901b3992d9..000000000000 --- a/Documentation/devicetree/bindings/power_supply/olpc_battery.txt +++ /dev/null @@ -1,5 +0,0 @@ -OLPC battery -~~~~~~~~~~~~ - -Required properties: - - compatible : "olpc,xo1-battery" diff --git a/Documentation/devicetree/bindings/power_supply/power_supply.txt b/Documentation/devicetree/bindings/power_supply/power_supply.txt deleted file mode 100644 index 8391bfa0edac..000000000000 --- a/Documentation/devicetree/bindings/power_supply/power_supply.txt +++ /dev/null @@ -1,23 +0,0 @@ -Power Supply Core Support - -Optional Properties: - - power-supplies : This property is added to a supply in order to list the - devices which supply it power, referenced by their phandles. - -Example: - - usb-charger: power@e { - compatible = "some,usb-charger"; - ... - }; - - ac-charger: power@c { - compatible = "some,ac-charger"; - ... - }; - - battery@b { - compatible = "some,battery"; - ... - power-supplies = <&usb-charger>, <&ac-charger>; - }; diff --git a/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt b/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt deleted file mode 100644 index 65b88fac854b..000000000000 --- a/Documentation/devicetree/bindings/power_supply/qcom_smbb.txt +++ /dev/null @@ -1,131 +0,0 @@ -Qualcomm Switch-Mode Battery Charger and Boost - -PROPERTIES -- compatible: - Usage: required - Value type: - Description: Must be one of: - - "qcom,pm8941-charger" - -- reg: - Usage: required - Value type: - Description: Base address of registers for SMBB block - -- interrupts: - Usage: required - Value type: - Description: The format of the specifier is defined by the binding document - describing the node's interrupt parent. Must contain one - specifier for each of the following interrupts, in order: - - charge done - - charge fast mode - - charge trickle mode - - battery temperature ok - - battery present - - charger disconnected - - USB-in valid - - DC-in valid - -- interrupt-names: - Usage: required - Value type: - Description: Must contain the following list, strictly ordered: - "chg-done", - "chg-fast", - "chg-trkl", - "bat-temp-ok", - "bat-present", - "chg-gone", - "usb-valid", - "dc-valid" - -- qcom,fast-charge-current-limit: - Usage: optional (default: 1A, or pre-configured value) - Value type: ; uA; range [100mA : 3A] - Description: Maximum charge current; May be clamped to safety limits. - -- qcom,fast-charge-low-threshold-voltage: - Usage: optional (default: 3.2V, or pre-configured value) - Value type: ; uV; range [2.1V : 3.6V] - Description: Battery voltage limit above which fast charging may operate; - Below this value linear or switch-mode auto-trickle-charging - will operate. - -- qcom,fast-charge-high-threshold-voltage: - Usage: optional (default: 4.2V, or pre-configured value) - Value type: ; uV; range [3.24V : 5V] - Description: Battery voltage limit below which fast charging may operate; - The fast charger will attempt to charge the battery to this - voltage. May be clamped to safety limits. - -- qcom,fast-charge-safe-voltage: - Usage: optional (default: 4.2V, or pre-configured value) - Value type: ; uV; range [3.24V : 5V] - Description: Maximum safe battery voltage; May be pre-set by bootloader, in - which case, setting this will harmlessly fail. The property - 'fast-charge-high-watermark' will be clamped by this value. - -- qcom,fast-charge-safe-current: - Usage: optional (default: 1A, or pre-configured value) - Value type: ; uA; range [100mA : 3A] - Description: Maximum safe battery charge current; May pre-set by bootloader, - in which case, setting this will harmlessly fail. The property - 'qcom,fast-charge-current-limit' will be clamped by this value. - -- qcom,auto-recharge-threshold-voltage: - Usage: optional (default: 4.1V, or pre-configured value) - Value type: ; uV; range [3.24V : 5V] - Description: Battery voltage limit below which auto-recharge functionality - will restart charging after end-of-charge; The high cutoff - limit for auto-recharge is 5% above this value. - -- qcom,minimum-input-voltage: - Usage: optional (default: 4.3V, or pre-configured value) - Value type: ; uV; range [4.2V : 9.6V] - Description: Input voltage level above which charging may operate - -- qcom,dc-current-limit: - Usage: optional (default: 100mA, or pre-configured value) - Value type: ; uA; range [100mA : 2.5A] - Description: Default DC charge current limit - -- qcom,disable-dc: - Usage: optional (default: false) - Value type: boolean: or - Description: Disable DC charger - -- qcom,jeita-extended-temp-range: - Usage: optional (default: false) - Value type: boolean: or - Description: Enable JEITA extended temperature range; This does *not* - adjust the maximum charge voltage or current in the extended - temperature range. It only allows charging when the battery - is in the extended temperature range. Voltage/current - regulation must be done externally to fully comply with - the JEITA safety guidelines if this flag is set. - -EXAMPLE -charger@1000 { - compatible = "qcom,pm8941-charger"; - reg = <0x1000 0x700>; - interrupts = <0x0 0x10 7 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x10 5 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x10 4 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x12 1 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x12 0 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x13 2 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x13 1 IRQ_TYPE_EDGE_BOTH>, - <0x0 0x14 1 IRQ_TYPE_EDGE_BOTH>; - interrupt-names = "chg-done", - "chg-fast", - "chg-trkl", - "bat-temp-ok", - "bat-present", - "chg-gone", - "usb-valid", - "dc-valid"; - - qcom,fast-charge-current-limit = <1000000>; - qcom,dc-charge-current-limit = <1000000>; -}; diff --git a/Documentation/devicetree/bindings/power_supply/qnap-poweroff.txt b/Documentation/devicetree/bindings/power_supply/qnap-poweroff.txt deleted file mode 100644 index af25e77c0e0c..000000000000 --- a/Documentation/devicetree/bindings/power_supply/qnap-poweroff.txt +++ /dev/null @@ -1,16 +0,0 @@ -* QNAP Power Off - -QNAP NAS devices have a microcontroller controlling the main power -supply. This microcontroller is connected to UART1 of the Kirkwood and -Orion5x SoCs. Sending the character 'A', at 19200 baud, tells the -microcontroller to turn the power off. This driver adds a handler to -pm_power_off which is called to turn the power off. - -Synology NAS devices use a similar scheme, but a different baud rate, -9600, and a different character, '1'. - -Required Properties: -- compatible: Should be "qnap,power-off" or "synology,power-off" - -- reg: Address and length of the register set for UART1 -- clocks: tclk clock diff --git a/Documentation/devicetree/bindings/power_supply/restart-poweroff.txt b/Documentation/devicetree/bindings/power_supply/restart-poweroff.txt deleted file mode 100644 index 5776e684afda..000000000000 --- a/Documentation/devicetree/bindings/power_supply/restart-poweroff.txt +++ /dev/null @@ -1,8 +0,0 @@ -* Restart Power Off - -Buffalo Linkstation LS-XHL and LS-CHLv2, and other devices power off -by restarting and letting u-boot keep hold of the machine until the -user presses a button. - -Required Properties: -- compatible: Should be "restart-poweroff" diff --git a/Documentation/devicetree/bindings/power_supply/sbs_sbs-battery.txt b/Documentation/devicetree/bindings/power_supply/sbs_sbs-battery.txt deleted file mode 100644 index c40e8926facf..000000000000 --- a/Documentation/devicetree/bindings/power_supply/sbs_sbs-battery.txt +++ /dev/null @@ -1,23 +0,0 @@ -SBS sbs-battery -~~~~~~~~~~ - -Required properties : - - compatible : "sbs,sbs-battery" - -Optional properties : - - sbs,i2c-retry-count : The number of times to retry i2c transactions on i2c - IO failure. - - sbs,poll-retry-count : The number of times to try looking for new status - after an external change notification. - - sbs,battery-detect-gpios : The gpio which signals battery detection and - a flag specifying its polarity. - -Example: - - bq20z75@b { - compatible = "sbs,sbs-battery"; - reg = < 0xb >; - sbs,i2c-retry-count = <2>; - sbs,poll-retry-count = <10>; - sbs,battery-detect-gpios = <&gpio-controller 122 1>; - } diff --git a/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt b/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt deleted file mode 100644 index 3bf55757ceec..000000000000 --- a/Documentation/devicetree/bindings/power_supply/ti,bq24735.txt +++ /dev/null @@ -1,35 +0,0 @@ -TI BQ24735 Charge Controller -~~~~~~~~~~ - -Required properties : - - compatible : "ti,bq24735" - -Optional properties : - - interrupts : Specify the interrupt to be used to trigger when the AC - adapter is either plugged in or removed. - - ti,ac-detect-gpios : This GPIO is optionally used to read the AC adapter - presence. This is a Host GPIO that is configured as an input and - connected to the bq24735. - - ti,charge-current : Used to control and set the charging current. This value - must be between 128mA and 8.128A with a 64mA step resolution. The POR value - is 0x0000h. This number is in mA (e.g. 8192), see spec for more information - about the ChargeCurrent (0x14h) register. - - ti,charge-voltage : Used to control and set the charging voltage. This value - must be between 1.024V and 19.2V with a 16mV step resolution. The POR value - is 0x0000h. This number is in mV (e.g. 19200), see spec for more information - about the ChargeVoltage (0x15h) register. - - ti,input-current : Used to control and set the charger input current. This - value must be between 128mA and 8.064A with a 128mA step resolution. The - POR value is 0x1000h. This number is in mA (e.g. 8064), see the spec for - more information about the InputCurrent (0x3fh) register. - - ti,external-control : Indicates that the charger is configured externally - and that the host should not attempt to enable/disable charging or set the - charge voltage/current. - -Example: - - bq24735@9 { - compatible = "ti,bq24735"; - reg = <0x9>; - ti,ac-detect-gpios = <&gpio 72 0x1>; - } diff --git a/Documentation/devicetree/bindings/power_supply/tps65090.txt b/Documentation/devicetree/bindings/power_supply/tps65090.txt deleted file mode 100644 index 8e5e0d3910df..000000000000 --- a/Documentation/devicetree/bindings/power_supply/tps65090.txt +++ /dev/null @@ -1,17 +0,0 @@ -TPS65090 Frontend PMU with Switchmode Charger - -Required Properties: --compatible: "ti,tps65090-charger" - -Optional Properties: --ti,enable-low-current-chrg: Enables charging when a low current is detected - while the default logic is to stop charging. - -This node is a subnode of the tps65090 PMIC. - -Example: - - tps65090-charger { - compatible = "ti,tps65090-charger"; - ti,enable-low-current-chrg; - }; diff --git a/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt b/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt deleted file mode 100644 index 98d131acee95..000000000000 --- a/Documentation/devicetree/bindings/power_supply/tps65217_charger.txt +++ /dev/null @@ -1,12 +0,0 @@ -TPS65217 Charger - -Required Properties: --compatible: "ti,tps65217-charger" - -This node is a subnode of the tps65217 PMIC. - -Example: - - tps65217-charger { - compatible = "ti,tps65090-charger"; - }; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/mem-ctrlr.txt b/Documentation/devicetree/bindings/powerpc/fsl/mem-ctrlr.txt deleted file mode 100644 index f87856faf1ab..000000000000 --- a/Documentation/devicetree/bindings/powerpc/fsl/mem-ctrlr.txt +++ /dev/null @@ -1,27 +0,0 @@ -Freescale DDR memory controller - -Properties: - -- compatible : Should include "fsl,chip-memory-controller" where - chip is the processor (bsc9132, mpc8572 etc.), or - "fsl,qoriq-memory-controller". -- reg : Address and size of DDR controller registers -- interrupts : Error interrupt of DDR controller - -Example 1: - - memory-controller@2000 { - compatible = "fsl,bsc9132-memory-controller"; - reg = <0x2000 0x1000>; - interrupts = <16 2 1 8>; - }; - - -Example 2: - - ddr1: memory-controller@8000 { - compatible = "fsl,qoriq-memory-controller-v4.7", - "fsl,qoriq-memory-controller"; - reg = <0x8000 0x1000>; - interrupts = <16 2 1 23>; - }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-meson.txt b/Documentation/devicetree/bindings/pwm/pwm-meson.txt new file mode 100644 index 000000000000..5376a4468cb6 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-meson.txt @@ -0,0 +1,23 @@ +Amlogic Meson PWM Controller +============================ + +Required properties: +- compatible: Shall contain "amlogic,meson8b-pwm" or "amlogic,meson-gxbb-pwm". +- #pwm-cells: Should be 3. See pwm.txt in this directory for a description of + the cells format. + +Optional properties: +- clocks: Could contain one or two parents clocks phandle for each of the two + PWM channels. +- clock-names: Could contain at least the "clkin0" and/or "clkin1" names. + +Example: + + pwm_ab: pwm@8550 { + compatible = "amlogic,meson-gxbb-pwm"; + reg = <0x0 0x08550 0x0 0x10>; + #pwm-cells = <3>; + status = "disabled"; + clocks = <&xtal>, <&xtal>; + clock-names = "clkin0", "clkin1"; + } diff --git a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt index f8f59baf6b67..6f8af2bcc7b7 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-mtk-disp.txt @@ -2,8 +2,9 @@ MediaTek display PWM controller Required properties: - compatible: should be "mediatek,-disp-pwm": - - "mediatek,mt8173-disp-pwm": found on mt8173 SoC. + - "mediatek,mt2701-disp-pwm": found on mt2701 SoC. - "mediatek,mt6595-disp-pwm": found on mt6595 SoC. + - "mediatek,mt8173-disp-pwm": found on mt8173 SoC. - reg: physical base address and length of the controller's registers. - #pwm-cells: must be 2. See pwm.txt in this directory for a description of the cell format. diff --git a/Documentation/devicetree/bindings/pwm/pwm-st.txt b/Documentation/devicetree/bindings/pwm/pwm-st.txt index 84d2fb807d3c..19fce774cafa 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-st.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-st.txt @@ -13,13 +13,14 @@ Required parameters: - pinctrl-0: List of phandles pointing to pin configuration nodes for PWM module. For Pinctrl properties, please refer to [1]. -- clock-names: Set to "pwm". +- clock-names: Valid entries are "pwm" and/or "capture". - clocks: phandle of the clock used by the PWM module. For Clk properties, please refer to [2]. +- interrupts: IRQ for the Capture device Optional properties: -- st,pwm-num-chan: Number of available channels. If not passed, the driver - will consider single channel by default. +- st,pwm-num-chan: Number of available PWM channels. Default is 0. +- st,capture-num-chan: Number of available Capture channels. Default is 0. [1] Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt [2] Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -38,4 +39,5 @@ pwm1: pwm@fe510000 { clocks = <&clk_sysin>; clock-names = "pwm"; st,pwm-num-chan = <4>; + st,capture-num-chan = <2>; }; diff --git a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt index cf6068b8e974..f1cbeefb3087 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-sun4i.txt @@ -6,6 +6,7 @@ Required properties: - "allwinner,sun5i-a10s-pwm" - "allwinner,sun5i-a13-pwm" - "allwinner,sun7i-a20-pwm" + - "allwinner,sun8i-h3-pwm" - reg: physical base address and length of the controller's registers - #pwm-cells: should be 3. See pwm.txt in this directory for a description of the cells format. diff --git a/Documentation/devicetree/bindings/regulator/ltc3676.txt b/Documentation/devicetree/bindings/regulator/ltc3676.txt new file mode 100644 index 000000000000..d4eb366ce18c --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ltc3676.txt @@ -0,0 +1,94 @@ +Linear Technology LTC3676 8-output regulators + +Required properties: +- compatible: "lltc,ltc3676" +- reg: I2C slave address + +Required child node: +- regulators: Contains eight regulator child nodes sw1, sw2, sw3, sw4, + ldo1, ldo2, ldo3, and ldo4, specifying the initialization data as + documented in Documentation/devicetree/bindings/regulator/regulator.txt. + +Each regulator is defined using the standard binding for regulators. The +nodes for sw1, sw2, sw3, sw4, ldo1, ldo2 and ldo4 additionally need to specify +the resistor values of their external feedback voltage dividers: + +Required properties (not on ldo3): +- lltc,fb-voltage-divider: An array of two integers containing the resistor + values R1 and R2 of the feedback voltage divider in ohms. + +Regulators sw1, sw2, sw3, sw4 can regulate the feedback reference from: +412.5mV to 800mV in 12.5 mV steps. The output voltage thus ranges between +0.4125 * (1 + R1/R2) V and 0.8 * (1 + R1/R2) V. + +Regulators ldo1, ldo2, and ldo4 have a fixed 0.725 V reference and thus output +0.725 * (1 + R1/R2) V. The ldo3 regulator is fixed to 1.8 V. The ldo1 standby +regulator can not be disabled and thus should have the regulator-always-on +property set. + +Example: + + ltc3676: pmic@3c { + compatible = "lltc,ltc3676"; + reg = <0x3c>; + + regulators { + sw1_reg: sw1 { + regulator-min-microvolt = <674400>; + regulator-max-microvolt = <1308000>; + lltc,fb-voltage-divider = <127000 200000>; + regulator-ramp-delay = <7000>; + regulator-boot-on; + regulator-always-on; + }; + + sw2_reg: sw2 { + regulator-min-microvolt = <1033310>; + regulator-max-microvolt = <200400>; + lltc,fb-voltage-divider = <301000 200000>; + regulator-ramp-delay = <7000>; + regulator-boot-on; + regulator-always-on; + }; + + sw3_reg: sw3 { + regulator-min-microvolt = <674400>; + regulator-max-microvolt = <130800>; + lltc,fb-voltage-divider = <127000 200000>; + regulator-ramp-delay = <7000>; + regulator-boot-on; + regulator-always-on; + }; + + sw4_reg: sw4 { + regulator-min-microvolt = <868310>; + regulator-max-microvolt = <168400>; + lltc,fb-voltage-divider = <221000 200000>; + regulator-ramp-delay = <7000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo2_reg: ldo2 { + regulator-min-microvolt = <2490375>; + regulator-max-microvolt = <2490375>; + lltc,fb-voltage-divider = <487000 200000>; + regulator-boot-on; + regulator-always-on; + }; + + ldo3_reg: ldo3 { + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + }; + + ldo4_reg: ldo4 { + regulator-min-microvolt = <3023250>; + regulator-max-microvolt = <3023250>; + lltc,fb-voltage-divider = <634000 200000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/pv88080.txt b/Documentation/devicetree/bindings/regulator/pv88080.txt index 38a614210dcb..e6e4b9c82d89 100644 --- a/Documentation/devicetree/bindings/regulator/pv88080.txt +++ b/Documentation/devicetree/bindings/regulator/pv88080.txt @@ -1,22 +1,28 @@ * Powerventure Semiconductor PV88080 Voltage Regulator Required properties: -- compatible: "pvs,pv88080". -- reg: I2C slave address, usually 0x49. +- compatible: Must be one of the following, depending on the + silicon version: + - "pvs,pv88080" (DEPRECATED) + + - "pvs,pv88080-aa" for PV88080 AA or AB silicon + - "pvs,pv88080-ba" for PV88080 BA or BB silicon + NOTE: The use of the compatibles with no silicon version is deprecated. +- reg: I2C slave address, usually 0x49 - interrupts: the interrupt outputs of the controller - regulators: A node that houses a sub-node for each regulator within the device. Each sub-node is identified using the node's name, with valid values listed below. The content of each sub-node is defined by the standard binding for regulators; see regulator.txt. - BUCK1, BUCK2, and BUCK3. + BUCK1, BUCK2, BUCK3 and HVBUCK. Optional properties: - Any optional property defined in regulator.txt -Example +Example: pmic: pv88080@49 { - compatible = "pvs,pv88080"; + compatible = "pvs,pv88080-ba"; reg = <0x49>; interrupt-parent = <&gpio>; interrupts = <24 24>; @@ -45,5 +51,12 @@ Example regulator-min-microamp = <1496000>; regulator-max-microamp = <4189000>; }; + + HVBUCK { + regulator-name = "hvbuck"; + regulator-min-microvolt = < 5000>; + regulator-max-microvolt = <1275000>; + }; }; }; + diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index ecfc593cac15..6ab5aef619d9 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -13,7 +13,7 @@ Optional properties: - regulator-allow-bypass: allow the regulator to go into bypass mode - regulator-allow-set-load: allow the regulator performance level to be configured - -supply: phandle to the parent supply/regulator node -- regulator-ramp-delay: ramp delay for regulator(in uV/uS) +- regulator-ramp-delay: ramp delay for regulator(in uV/us) For hardware which supports disabling ramp rate, it should be explicitly initialised to zero (regulator-ramp-delay = <0>) for disabling ramp delay. - regulator-enable-ramp-delay: The time taken, in microseconds, for the supply diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt b/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt new file mode 100644 index 000000000000..0d2361ebe3d7 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,wcnss-pil.txt @@ -0,0 +1,132 @@ +Qualcomm WCNSS Peripheral Image Loader + +This document defines the binding for a component that loads and boots firmware +on the Qualcomm WCNSS core. + +- compatible: + Usage: required + Value type: + Definition: must be one of: + "qcom,riva-pil", + "qcom,pronto-v1-pil", + "qcom,pronto-v2-pil" + +- reg: + Usage: required + Value type: + Definition: must specify the base address and size of the CCU, DXE and + PMU register blocks + +- reg-names: + Usage: required + Value type: + Definition: must be "ccu", "dxe", "pmu" + +- interrupts-extended: + Usage: required + Value type: + Definition: must list the watchdog and fatal IRQs and may specify the + ready, handover and stop-ack IRQs + +- interrupt-names: + Usage: required + Value type: + Definition: should be "wdog", "fatal", optionally followed by "ready", + "handover", "stop-ack" + +- vddmx-supply: +- vddcx-supply: +- vddpx-supply: + Usage: required + Value type: + Definition: reference to the regulators to be held on behalf of the + booting of the WCNSS core + +- qcom,smem-states: + Usage: optional + Value type: + Definition: reference to the SMEM state used to indicate to WCNSS that + it should shut down + +- qcom,smem-state-names: + Usage: optional + Value type: + Definition: should be "stop" + +- memory-region: + Usage: required + Value type: + Definition: reference to reserved-memory node for the remote processor + see ../reserved-memory/reserved-memory.txt + += SUBNODES +A single subnode of the WCNSS PIL describes the attached rf module and its +resource dependencies. + +- compatible: + Usage: required + Value type: + Definition: must be one of: + "qcom,wcn3620", + "qcom,wcn3660", + "qcom,wcn3680" + +- clocks: + Usage: required + Value type: + Definition: should specify the xo clock and optionally the rf clock + +- clock-names: + Usage: required + Value type: + Definition: should be "xo", optionally followed by "rf" + +- vddxo-supply: +- vddrfa-supply: +- vddpa-supply: +- vdddig-supply: + Usage: required + Value type: + Definition: reference to the regulators to be held on behalf of the + booting of the WCNSS core + += EXAMPLE +The following example describes the resources needed to boot control the WCNSS, +with attached WCN3680, as it is commonly found on MSM8974 boards. + +pronto@fb204000 { + compatible = "qcom,pronto-v2-pil"; + reg = <0xfb204000 0x2000>, <0xfb202000 0x1000>, <0xfb21b000 0x3000>; + reg-names = "ccu", "dxe", "pmu"; + + interrupts-extended = <&intc 0 149 1>, + <&wcnss_smp2p_slave 0 0>, + <&wcnss_smp2p_slave 1 0>, + <&wcnss_smp2p_slave 2 0>, + <&wcnss_smp2p_slave 3 0>; + interrupt-names = "wdog", "fatal", "ready", "handover", "stop-ack"; + + vddmx-supply = <&pm8841_s1>; + vddcx-supply = <&pm8841_s2>; + vddpx-supply = <&pm8941_s3>; + + qcom,smem-states = <&wcnss_smp2p_out 0>; + qcom,smem-state-names = "stop"; + + memory-region = <&wcnss_region>; + + pinctrl-names = "default"; + pinctrl-0 = <&wcnss_pin_a>; + + iris { + compatible = "qcom,wcn3680"; + + clocks = <&rpmcc RPM_CXO_CLK_SRC>, <&rpmcc RPM_CXO_A2>; + clock-names = "xo", "rf"; + + vddxo-supply = <&pm8941_l6>; + vddrfa-supply = <&pm8941_l11>; + vddpa-supply = <&pm8941_l19>; + vdddig-supply = <&pm8941_s3>; + }; +}; diff --git a/Documentation/devicetree/bindings/reset/st,stm32-rcc.txt b/Documentation/devicetree/bindings/reset/st,stm32-rcc.txt new file mode 100644 index 000000000000..01db34375192 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/st,stm32-rcc.txt @@ -0,0 +1,6 @@ +STMicroelectronics STM32 Peripheral Reset Controller +==================================================== + +The RCC IP is both a reset and a clock controller. + +Please see Documentation/devicetree/bindings/clock/st,stm32-rcc.txt diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt new file mode 100644 index 000000000000..e6bbfccd56c3 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/uniphier-reset.txt @@ -0,0 +1,93 @@ +UniPhier reset controller + + +System reset +------------ + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-sld3-reset" - for PH1-sLD3 SoC. + "socionext,uniphier-ld4-reset" - for PH1-LD4 SoC. + "socionext,uniphier-pro4-reset" - for PH1-Pro4 SoC. + "socionext,uniphier-sld8-reset" - for PH1-sLD8 SoC. + "socionext,uniphier-pro5-reset" - for PH1-Pro5 SoC. + "socionext,uniphier-pxs2-reset" - for ProXstream2/PH1-LD6b SoC. + "socionext,uniphier-ld11-reset" - for PH1-LD11 SoC. + "socionext,uniphier-ld20-reset" - for PH1-LD20 SoC. +- #reset-cells: should be 1. + +Example: + + sysctrl@61840000 { + compatible = "socionext,uniphier-ld20-sysctrl", + "simple-mfd", "syscon"; + reg = <0x61840000 0x4000>; + + reset { + compatible = "socionext,uniphier-ld20-reset"; + #reset-cells = <1>; + }; + + other nodes ... + }; + + +Media I/O (MIO) reset +--------------------- + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-sld3-mio-reset" - for PH1-sLD3 SoC. + "socionext,uniphier-ld4-mio-reset" - for PH1-LD4 SoC. + "socionext,uniphier-pro4-mio-reset" - for PH1-Pro4 SoC. + "socionext,uniphier-sld8-mio-reset" - for PH1-sLD8 SoC. + "socionext,uniphier-pro5-mio-reset" - for PH1-Pro5 SoC. + "socionext,uniphier-pxs2-mio-reset" - for ProXstream2/PH1-LD6b SoC. + "socionext,uniphier-ld11-mio-reset" - for PH1-LD11 SoC. + "socionext,uniphier-ld20-mio-reset" - for PH1-LD20 SoC. +- #reset-cells: should be 1. + +Example: + + mioctrl@59810000 { + compatible = "socionext,uniphier-ld20-mioctrl", + "simple-mfd", "syscon"; + reg = <0x59810000 0x800>; + + reset { + compatible = "socionext,uniphier-ld20-mio-reset"; + #reset-cells = <1>; + }; + + other nodes ... + }; + + +Peripheral reset +---------------- + +Required properties: +- compatible: should be one of the following: + "socionext,uniphier-ld4-peri-reset" - for PH1-LD4 SoC. + "socionext,uniphier-pro4-peri-reset" - for PH1-Pro4 SoC. + "socionext,uniphier-sld8-peri-reset" - for PH1-sLD8 SoC. + "socionext,uniphier-pro5-peri-reset" - for PH1-Pro5 SoC. + "socionext,uniphier-pxs2-peri-reset" - for ProXstream2/PH1-LD6b SoC. + "socionext,uniphier-ld11-peri-reset" - for PH1-LD11 SoC. + "socionext,uniphier-ld20-peri-reset" - for PH1-LD20 SoC. +- #reset-cells: should be 1. + +Example: + + perictrl@59820000 { + compatible = "socionext,uniphier-ld20-perictrl", + "simple-mfd", "syscon"; + reg = <0x59820000 0x200>; + + reset { + compatible = "socionext,uniphier-ld20-peri-reset"; + #reset-cells = <1>; + }; + + other nodes ... + }; diff --git a/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt b/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt index 8e76f2648796..9882b819f173 100644 --- a/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt +++ b/Documentation/devicetree/bindings/rtc/dallas,ds1390.txt @@ -11,7 +11,7 @@ Optional properties: - trickle-diode-disable : Do not use internal trickle charger diode Should be given if internal trickle charger diode should be disabled Example: - ds1390: rtc@68 { + ds1390: rtc@0 { compatible = "dallas,ds1390"; trickle-resistor-ohms = <250>; reg = <0>; diff --git a/Documentation/devicetree/bindings/rtc/epson,rx8900.txt b/Documentation/devicetree/bindings/rtc/epson,rx8900.txt new file mode 100644 index 000000000000..3f61e516ecf6 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/epson,rx8900.txt @@ -0,0 +1,22 @@ +Real Time Clock driver for: + - Epson RX8900 + - Micro Crystal rv8803 + +Required properties: +- compatible: should be: "microcrystal,rv8803" or "epson,rx8900" +- reg : the I2C address of the device for I2C + +Optional properties: +- epson,vdet-disable : boolean, if present will disable voltage detector. + Should be set if no backup battery is used. +- trickle-diode-disable : boolean, if present will disable internal trickle + charger diode + +Example: + + rtc: rtc@32 { + compatible = "epson,rx8900" + reg = <0x32>; + epson,vdet-disable; + trickle-diode-disable; + }; diff --git a/Documentation/devicetree/bindings/rtc/rtc-omap.txt b/Documentation/devicetree/bindings/rtc/rtc-omap.txt index bf7d11ae9bea..bee41f97044e 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-omap.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-omap.txt @@ -18,6 +18,18 @@ Optional properties: through pmic_power_en - clocks: Any internal or external clocks feeding in to rtc - clock-names: Corresponding names of the clocks +- pinctrl-0: a phandle pointing to the pin settings for the device +- pinctrl-names: should be "default" + +Optional subnodes: +- generic pinctrl node + +Required pinctrl subnodes properties: +- pins - Names of ext_wakeup pins to configure + +Optional pinctrl subnodes properties: +- input-enable - Enables ext_wakeup +- ti,active-high - Set input active high (by default active low) Example: @@ -30,4 +42,13 @@ rtc@1c23000 { system-power-controller; clocks = <&clk_32k_rtc>, <&clk_32768_ck>; clock-names = "ext-clk", "int-clk"; + + pinctrl-0 = <&ext_wakeup>; + pinctrl-names = "default"; + + ext_wakeup: ext-wakeup { + pins = "ext_wakeup0"; + input-enable; + ti,active-high; + }; }; diff --git a/Documentation/devicetree/bindings/serial/8250.txt b/Documentation/devicetree/bindings/serial/8250.txt index 936ab5b87324..f86bb06c39e9 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -42,6 +42,8 @@ Optional properties: - auto-flow-control: one way to enable automatic flow control support. The driver is allowed to detect support for the capability even without this property. +- tx-threshold: Specify the TX FIFO low water indication for parts with + programmable TX FIFO thresholds. Note: * fsl,ns16550: diff --git a/Documentation/devicetree/bindings/serial/st,stm32-usart.txt b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt new file mode 100644 index 000000000000..85ec5f2b1996 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/st,stm32-usart.txt @@ -0,0 +1,46 @@ +* STMicroelectronics STM32 USART + +Required properties: +- compatible: Can be either "st,stm32-usart", "st,stm32-uart", +"st,stm32f7-usart" or "st,stm32f7-uart" depending on whether +the device supports synchronous mode and is compatible with +stm32(f4) or stm32f7. +- reg: The address and length of the peripheral registers space +- interrupts: The interrupt line of the USART instance +- clocks: The input clock of the USART instance + +Optional properties: +- pinctrl: The reference on the pins configuration +- st,hw-flow-ctrl: bool flag to enable hardware flow control. +- dmas: phandle(s) to DMA controller node(s). Refer to stm32-dma.txt +- dma-names: "rx" and/or "tx" + +Examples: +usart4: serial@40004c00 { + compatible = "st,stm32-uart"; + reg = <0x40004c00 0x400>; + interrupts = <52>; + clocks = <&clk_pclk1>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_usart4>; +}; + +usart2: serial@40004400 { + compatible = "st,stm32-usart", "st,stm32-uart"; + reg = <0x40004400 0x400>; + interrupts = <38>; + clocks = <&clk_pclk1>; + st,hw-flow-ctrl; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_usart2 &pinctrl_usart2_rtscts>; +}; + +usart1: serial@40011000 { + compatible = "st,stm32-usart", "st,stm32-uart"; + reg = <0x40011000 0x400>; + interrupts = <37>; + clocks = <&rcc 0 164>; + dmas = <&dma2 2 4 0x414 0x0>, + <&dma2 7 4 0x414 0x0>; + dma-names = "rx", "tx"; +}; diff --git a/Documentation/devicetree/bindings/soc/mediatek/auxadc.txt b/Documentation/devicetree/bindings/soc/mediatek/auxadc.txt deleted file mode 100644 index bdb782918a72..000000000000 --- a/Documentation/devicetree/bindings/soc/mediatek/auxadc.txt +++ /dev/null @@ -1,21 +0,0 @@ -MediaTek AUXADC -=============== - -The Auxiliary Analog/Digital Converter (AUXADC) is an ADC found -in some Mediatek SoCs which among other things measures the temperatures -in the SoC. It can be used directly with register accesses, but it is also -used by thermal controller which reads the temperatures from the AUXADC -directly via its own bus interface. See -Documentation/devicetree/bindings/thermal/mediatek-thermal.txt -for the Thermal Controller which holds a phandle to the AUXADC. - -Required properties: -- compatible: Must be "mediatek,mt8173-auxadc" -- reg: Address range of the AUXADC unit - -Example: - -auxadc: auxadc@11001000 { - compatible = "mediatek,mt8173-auxadc"; - reg = <0 0x11001000 0 0x1000>; -}; diff --git a/Documentation/devicetree/bindings/sound/nau8810.txt b/Documentation/devicetree/bindings/sound/nau8810.txt new file mode 100644 index 000000000000..05830e477acd --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nau8810.txt @@ -0,0 +1,16 @@ +NAU8810 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "nuvoton,nau8810" + + - reg : the I2C address of the device. + +Example: + +codec: nau8810@1a { + compatible = "nuvoton,nau8810"; + reg = <0x1a>; +}; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt new file mode 100644 index 000000000000..5da7da4ea07a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra-audio-sgtl5000.txt @@ -0,0 +1,42 @@ +NVIDIA Tegra audio complex, with SGTL5000 CODEC + +Required properties: +- compatible : "nvidia,tegra-audio-sgtl5000" +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names : Must include the following entries: + - pll_a + - pll_a_out0 + - mclk (The Tegra cdev1/extern1 clock, which feeds the CODEC's mclk) +- nvidia,model : The user-visible name of this sound complex. +- nvidia,audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the SGTL5000's pins (as documented in its binding), and the jacks + on the board: + + * Headphone Jack + * Line In Jack + * Mic Jack + +- nvidia,i2s-controller : The phandle of the Tegra I2S controller that's + connected to the CODEC. +- nvidia,audio-codec : The phandle of the SGTL5000 audio codec. + +Example: + +sound { + compatible = "toradex,tegra-audio-sgtl5000-apalis_t30", + "nvidia,tegra-audio-sgtl5000"; + nvidia,model = "Toradex Apalis T30"; + nvidia,audio-routing = + "Headphone Jack", "HP_OUT", + "LINE_IN", "Line In Jack", + "MIC_IN", "Mic Jack"; + nvidia,i2s-controller = <&tegra_i2s2>; + nvidia,audio-codec = <&sgtl5000>; + clocks = <&tegra_car TEGRA30_CLK_PLL_A>, + <&tegra_car TEGRA30_CLK_PLL_A_OUT0>, + <&tegra_car TEGRA30_CLK_EXTERN1>; + clock-names = "pll_a", "pll_a_out0", "mclk"; +}; diff --git a/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt b/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt index 48129368d4d9..d9d8635ff94c 100644 --- a/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt +++ b/Documentation/devicetree/bindings/sound/qcom,apq8016-sbc.txt @@ -16,6 +16,24 @@ Required properties: * "spkr-iomux" - qcom,model : Name of the sound card. +- qcom,audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the + connection's sink, the second being the connection's + source. Valid names could be power supplies, MicBias + of msm8x16_wcd codec and the jacks on the board: + + Power supplies: + * MIC BIAS External1 + * MIC BIAS External2 + * MIC BIAS Internal1 + * MIC BIAS Internal2 + + Board connectors: + * Headset Mic + * Secondary Mic", + * DMIC + * Ext Spk + Dai-link subnode properties and subnodes: Required dai-link subnodes: @@ -37,6 +55,18 @@ sound: sound { reg-names = "mic-iomux", "spkr-iomux"; qcom,model = "DB410c"; + qcom,audio-routing = + "MIC BIAS External1", "Handset Mic", + "MIC BIAS Internal2", "Headset Mic", + "MIC BIAS External1", "Secondary Mic", + "AMIC1", "MIC BIAS External1", + "AMIC2", "MIC BIAS Internal2", + "AMIC3", "MIC BIAS External1", + "DMIC1", "MIC BIAS Internal1", + "MIC BIAS Internal1", "Digital Mic1", + "DMIC2", "MIC BIAS Internal1", + "MIC BIAS Internal1", "Digital Mic2"; + /* I2S - Internal codec */ internal-dai-link@0 { cpu { /* PRIMARY */ diff --git a/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt b/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt deleted file mode 100644 index 255ece3043ad..000000000000 --- a/Documentation/devicetree/bindings/sound/renesas,rsrc-card.txt +++ /dev/null @@ -1,75 +0,0 @@ -Renesas Sampling Rate Convert Sound Card: - -Renesas Sampling Rate Convert Sound Card specifies audio DAI connections of SoC <-> codec. - -Required properties: - -- compatible : "renesas,rsrc-card{,}" - Examples with boards are: - - "renesas,rsrc-card" - - "renesas,rsrc-card,lager" - - "renesas,rsrc-card,koelsch" -Optional properties: - -- card_name : User specified audio sound card name, one string - property. -- cpu : CPU sub-node -- codec : CODEC sub-node - -Optional subnode properties: - -- format : CPU/CODEC common audio format. - "i2s", "right_j", "left_j" , "dsp_a" - "dsp_b", "ac97", "pdm", "msb", "lsb" -- frame-master : Indicates dai-link frame master. - phandle to a cpu or codec subnode. -- bitclock-master : Indicates dai-link bit clock master. - phandle to a cpu or codec subnode. -- bitclock-inversion : bool property. Add this if the - dai-link uses bit clock inversion. -- frame-inversion : bool property. Add this if the - dai-link uses frame clock inversion. -- convert-rate : platform specified sampling rate convert -- convert-channels : platform specified converted channel size (2 - 8 ch) -- audio-prefix : see audio-routing -- audio-routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources. - use audio-prefix if some components is using same sink/sources naming. - it can be used if compatible was "renesas,rsrc-card"; - -Required CPU/CODEC subnodes properties: - -- sound-dai : phandle and port of CPU/CODEC - -Optional CPU/CODEC subnodes properties: - -- clocks / system-clock-frequency : specify subnode's clock if needed. - it can be specified via "clocks" if system has - clock node (= common clock), or "system-clock-frequency" - (if system doens't support common clock) - If a clock is specified, it is - enabled with clk_prepare_enable() - in dai startup() and disabled with - clk_disable_unprepare() in dai - shutdown(). - -Example - -sound { - compatible = "renesas,rsrc-card,lager"; - - card-name = "rsnd-ak4643"; - format = "left_j"; - bitclock-master = <&sndcodec>; - frame-master = <&sndcodec>; - - sndcpu: cpu { - sound-dai = <&rcar_sound>; - }; - - sndcodec: codec { - sound-dai = <&ak4643>; - system-clock-frequency = <11289600>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.txt new file mode 100644 index 000000000000..eac91db07178 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.txt @@ -0,0 +1,22 @@ +ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards + +Required properties: +- compatible: "rockchip,rk3399-gru-sound" +- rockchip,cpu: The phandle of the Rockchip I2S controller that's + connected to the codecs +- rockchip,codec: The phandle of the MAX98357A/RT5514/DA7219 codecs + +Optional properties: +- dmic-wakeup-delay-ms : specify delay time (ms) for DMIC ready. + If this option is specified, which means it's required dmic need + delay for DMIC to ready so that rt5514 can avoid recording before + DMIC send valid data + +Example: + +sound { + compatible = "rockchip,rk3399-gru-sound"; + rockchip,cpu = <&i2s0>; + rockchip,codec = <&max98357a &rt5514 &da7219>; + dmic-wakeup-delay-ms = <20>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5659.txt b/Documentation/devicetree/bindings/sound/rt5659.txt index 5f79e7fde032..1766e0543fc5 100644 --- a/Documentation/devicetree/bindings/sound/rt5659.txt +++ b/Documentation/devicetree/bindings/sound/rt5659.txt @@ -12,6 +12,9 @@ Required properties: Optional properties: +- clocks: The phandle of the master clock to the CODEC +- clock-names: Should be "mclk" + - realtek,in1-differential - realtek,in3-differential - realtek,in4-differential diff --git a/Documentation/devicetree/bindings/sound/rt5660.txt b/Documentation/devicetree/bindings/sound/rt5660.txt new file mode 100644 index 000000000000..30be5f921930 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5660.txt @@ -0,0 +1,47 @@ +RT5660 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : "realtek,rt5660". + +- reg : The I2C address of the device. + +Optional properties: + +- clocks: The phandle of the master clock to the CODEC +- clock-names: Should be "mclk" + +- realtek,in1-differential +- realtek,in3-differential + Boolean. Indicate MIC1/3 input are differential, rather than single-ended. + +- realtek,poweroff-in-suspend + Boolean. If the codec will be powered off in suspend, the resume should be + added delay time for waiting codec power ready. + +- realtek,dmic1-data-pin + 0: dmic1 is not used + 1: using GPIO2 pin as dmic1 data pin + 2: using IN1P pin as dmic1 data pin + +Pins on the device (for linking into audio routes) for RT5660: + + * DMIC L1 + * DMIC R1 + * IN1P + * IN1N + * IN2P + * IN3P + * IN3N + * SPO + * LOUTL + * LOUTR + +Example: + +rt5660 { + compatible = "realtek,rt5660"; + reg = <0x1c>; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5663.txt b/Documentation/devicetree/bindings/sound/rt5663.txt new file mode 100644 index 000000000000..7d3c974c6e2e --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rt5663.txt @@ -0,0 +1,30 @@ +RT5663/RT5668 audio CODEC + +This device supports I2C only. + +Required properties: + +- compatible : One of "realtek,rt5663" or "realtek,rt5668". + +- reg : The I2C address of the device. + +- interrupts : The CODEC's interrupt output. + +Optional properties: + +Pins on the device (for linking into audio routes) for RT5663/RT5668: + + * IN1P + * IN1N + * IN2P + * IN2N + * HPOL + * HPOR + +Example: + +codec: rt5663@12 { + compatible = "realtek,rt5663"; + reg = <0x12>; + interrupts = <7 IRQ_TYPE_EDGE_FALLING>; +}; diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index 59d862801e59..c7a93931fad2 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -22,6 +22,8 @@ Optional properties: headphones are attached. - simple-audio-card,mic-det-gpio : Reference to GPIO that signals when a microphone is attached. +- simple-audio-card,aux-devs : List of phandles pointing to auxiliary devices, such + as amplifiers, to be added to the sound card. Optional subnodes: @@ -162,3 +164,38 @@ sound { }; }; }; + +Example 3 - route audio from IMX6 SSI2 through TLV320DAC3100 codec +through TPA6130A2 amplifier to headphones: + +&i2c0 { + codec: tlv320dac3100@18 { + compatible = "ti,tlv320dac3100"; + ... + } + + amp: tpa6130a2@60 { + compatible = "ti,tpa6130a2"; + ... + } +} + +sound { + compatible = "simple-audio-card"; + ... + simple-audio-card,widgets = + "Headphone", "Headphone Jack"; + simple-audio-card,routing = + "Headphone Jack", "HPLEFT", + "Headphone Jack", "HPRIGHT", + "LEFTIN", "HPL", + "RIGHTIN", "HPR"; + simple-audio-card,aux-devs = <&>; + simple-audio-card,cpu { + sound-dai = <&ssi2>; + }; + simple-audio-card,codec { + sound-dai = <&codec>; + clocks = ... + }; +}; diff --git a/Documentation/devicetree/bindings/sound/simple-scu-card.txt b/Documentation/devicetree/bindings/sound/simple-scu-card.txt new file mode 100644 index 000000000000..d6fe47ed09af --- /dev/null +++ b/Documentation/devicetree/bindings/sound/simple-scu-card.txt @@ -0,0 +1,110 @@ +ASoC simple SCU Sound Card + +Simple-Card specifies audio DAI connections of SoC <-> codec. + +Required properties: + +- compatible : "simple-scu-audio-card" + "renesas,rsrc-card" + +Optional properties: + +- simple-audio-card,name : User specified audio sound card name, one string + property. +- simple-audio-card,cpu : CPU sub-node +- simple-audio-card,codec : CODEC sub-node + +Optional subnode properties: + +- simple-audio-card,format : CPU/CODEC common audio format. + "i2s", "right_j", "left_j" , "dsp_a" + "dsp_b", "ac97", "pdm", "msb", "lsb" +- simple-audio-card,frame-master : Indicates dai-link frame master. + phandle to a cpu or codec subnode. +- simple-audio-card,bitclock-master : Indicates dai-link bit clock master. + phandle to a cpu or codec subnode. +- simple-audio-card,bitclock-inversion : bool property. Add this if the + dai-link uses bit clock inversion. +- simple-audio-card,frame-inversion : bool property. Add this if the + dai-link uses frame clock inversion. +- simple-audio-card,convert-rate : platform specified sampling rate convert +- simple-audio-card,convert-channels : platform specified converted channel size (2 - 8 ch) +- simple-audio-card,prefix : see audio-routing +- simple-audio-card,routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources. + use audio-prefix if some components is using same sink/sources naming. + it can be used if compatible was "renesas,rsrc-card"; + +Required CPU/CODEC subnodes properties: + +- sound-dai : phandle and port of CPU/CODEC + +Optional CPU/CODEC subnodes properties: + +- clocks / system-clock-frequency : specify subnode's clock if needed. + it can be specified via "clocks" if system has + clock node (= common clock), or "system-clock-frequency" + (if system doens't support common clock) + If a clock is specified, it is + enabled with clk_prepare_enable() + in dai startup() and disabled with + clk_disable_unprepare() in dai + shutdown(). + +Example 1. Sampling Rate Covert + +sound { + compatible = "simple-scu-audio-card"; + + simple-audio-card,name = "rsnd-ak4643"; + simple-audio-card,format = "left_j"; + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&sndcodec>; + simple-audio-card,frame-master = <&sndcodec>; + + simple-audio-card,convert-rate = <48000>; /* see audio_clk_a */ + + simple-audio-card,prefix = "ak4642"; + simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", + "DAI0 Capture", "ak4642 Capture"; + + sndcpu: simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + }; + + sndcodec: simple-audio-card,codec { + sound-dai = <&ak4643>; + system-clock-frequency = <11289600>; + }; +}; + +Example 2. 2 CPU 1 Codec + +sound { + compatible = "renesas,rsrc-card"; + + card-name = "rsnd-ak4643"; + format = "left_j"; + bitclock-master = <&dpcmcpu>; + frame-master = <&dpcmcpu>; + + convert-rate = <48000>; /* see audio_clk_a */ + + audio-prefix = "ak4642"; + audio-routing = "ak4642 Playback", "DAI0 Playback", + "ak4642 Playback", "DAI1 Playback"; + + dpcmcpu: cpu@0 { + sound-dai = <&rcar_sound 0>; + }; + + cpu@1 { + sound-dai = <&rcar_sound 1>; + }; + + codec { + sound-dai = <&ak4643>; + clocks = <&audio_clock>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt index 16bcdfb6760e..745dc62f76ea 100644 --- a/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt +++ b/Documentation/devicetree/bindings/sound/st,sti-asoc-card.txt @@ -11,7 +11,9 @@ Documentation/devicetree/bindings/sound/simple-card.txt. --------------------------------------- Required properties: - - compatible: "st,sti-uni-player" or "st,sti-uni-reader" + - compatible: "st,stih407-uni-player-hdmi", "st,stih407-uni-player-pcm-out", + "st,stih407-uni-player-dac", "st,stih407-uni-player-spdif", + "st,stih407-uni-reader-pcm_in", "st,stih407-uni-reader-hdmi", - st,syscfg: phandle to boot-device system configuration registers @@ -33,32 +35,24 @@ Required properties: "tx" for "st,sti-uni-player" compatibility "rx" for "st,sti-uni-reader" compatibility - - st,version: IP version integrated in SOC. - - - dai-name: DAI name that describes the IP. - - - st,mode: IP working mode depending on associated codec. - "HDMI" connected to HDMI codec and support IEC HDMI formats (player only). - "SPDIF" connected to SPDIF codec and support SPDIF formats (player only). - "PCM" PCM standard mode for I2S or TDM bus. - "TDM" TDM mode for TDM bus. - Required properties ("st,sti-uni-player" compatibility only): - clocks: CPU_DAI IP clock source, listed in the same order than the CPU_DAI properties. - - st,uniperiph-id: internal SOC IP instance ID. - Optional properties: - pinctrl-0: defined for CPU_DAI@1 and CPU_DAI@4 to describe I2S PIOs for external codecs connection. - pinctrl-names: should contain only one value - "default". + - st,tdm-mode: to declare to set TDM mode for unireader and uniplayer IPs. + Only compartible with IPs in charge of the external I2S/TDM bus. + Should be declared depending on associated codec. + Example: - sti_uni_player1: sti-uni-player@1 { - compatible = "st,sti-uni-player"; + sti_uni_player1: sti-uni-player@0x8D81000 { + compatible = "st,stih407-uni-player-hdmi"; status = "okay"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -66,15 +60,12 @@ Example: reg = <0x8D81000 0x158>; interrupts = ; dmas = <&fdma0 3 0 1>; - st,dai-name = "Uni Player #1 (I2S)"; dma-names = "tx"; - st,uniperiph-id = <1>; - st,version = <5>; - st,mode = "TDM"; + st,tdm-mode = <1>; }; - sti_uni_player2: sti-uni-player@2 { - compatible = "st,sti-uni-player"; + sti_uni_player2: sti-uni-player@0x8D82000 { + compatible = "st,stih407-uni-player-pcm-out"; status = "okay"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -82,15 +73,11 @@ Example: reg = <0x8D82000 0x158>; interrupts = ; dmas = <&fdma0 4 0 1>; - dai-name = "Uni Player #2 (DAC)"; dma-names = "tx"; - st,uniperiph-id = <2>; - st,version = <5>; - st,mode = "PCM"; }; - sti_uni_player3: sti-uni-player@3 { - compatible = "st,sti-uni-player"; + sti_uni_player3: sti-uni-player@0x8D85000 { + compatible = "st,stih407-uni-player-spdif"; status = "okay"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -99,14 +86,10 @@ Example: interrupts = ; dmas = <&fdma0 7 0 1>; dma-names = "tx"; - dai-name = "Uni Player #3 (SPDIF)"; - st,uniperiph-id = <3>; - st,version = <5>; - st,mode = "SPDIF"; }; - sti_uni_reader1: sti-uni-reader@1 { - compatible = "st,sti-uni-reader"; + sti_uni_reader1: sti-uni-reader@0x8D84000 { + compatible = "st,stih407-uni-reader-hdmi"; status = "disabled"; #sound-dai-cells = <0>; st,syscfg = <&syscfg_core>; @@ -114,9 +97,6 @@ Example: interrupts = ; dmas = <&fdma0 6 0 1>; dma-names = "rx"; - dai-name = "Uni Reader #1 (HDMI RX)"; - st,version = <3>; - st,mode = "PCM"; }; 2) sti-sas-codec: internal audio codec IPs driver diff --git a/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt index 13503aa505a9..0230c4d20506 100644 --- a/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt +++ b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt @@ -9,6 +9,7 @@ Required properties: - compatible : should be one of the following: - "allwinner,sun4i-a10-spdif": for the Allwinner A10 SoC + - "allwinner,sun6i-a31-spdif": for the Allwinner A31 SoC - reg : Offset and length of the register set for the device. @@ -25,6 +26,8 @@ Required properties: "apb" clock for the spdif bus. "spdif" clock for spdif controller. + - resets : reset specifier for the ahb reset (A31 and newer only) + Example: spdif: spdif@01c21000 { diff --git a/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt b/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt index eff12be5e789..9340d2ddcc54 100644 --- a/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt +++ b/Documentation/devicetree/bindings/sound/tlv320aic31xx.txt @@ -11,6 +11,7 @@ Required properties: "ti,tlv320aic3110" - TLV320AIC3110 (stereo speaker amp, no MiniDSP) "ti,tlv320aic3120" - TLV320AIC3120 (mono speaker amp, MiniDSP) "ti,tlv320aic3111" - TLV320AIC3111 (stereo speaker amp, MiniDSP) + "ti,tlv320dac3100" - TLV320DAC3100 (no ADC, mono speaker amp, no MiniDSP) - reg - - I2C slave address - HPVDD-supply, SPRVDD-supply, SPLVDD-supply, AVDD-supply, IOVDD-supply, @@ -37,9 +38,11 @@ CODEC output pins: * MICBIAS CODEC input pins: - * MIC1LP - * MIC1RP - * MIC1LM + * MIC1LP, devices with ADC + * MIC1RP, devices with ADC + * MIC1LM, devices with ADC + * AIN1, devices without ADC + * AIN2, devices without ADC The pins can be used in referring sound node's audio-routing property. diff --git a/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt new file mode 100644 index 000000000000..ad7ac80a3841 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/brcm,spi-bcm-qspi.txt @@ -0,0 +1,233 @@ +Broadcom SPI controller + +The Broadcom SPI controller is a SPI master found on various SOCs, including +BRCMSTB (BCM7XXX), Cygnus, NSP and NS2. The Broadcom Master SPI hw IP consits +of : + MSPI : SPI master controller can read and write to a SPI slave device + BSPI : Broadcom SPI in combination with the MSPI hw IP provides acceleration + for flash reads and be configured to do single, double, quad lane + io with 3-byte and 4-byte addressing support. + + Supported Broadcom SoCs have one instance of MSPI+BSPI controller IP. + MSPI master can be used wihout BSPI. BRCMSTB SoCs have an additional instance + of a MSPI master without the BSPI to use with non flash slave devices that + use SPI protocol. + +Required properties: + +- #address-cells: + Must be <1>, as required by generic SPI binding. + +- #size-cells: + Must be <0>, also as required by generic SPI binding. + +- compatible: + Must be one of : + "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-qspi" : MSPI+BSPI on BRCMSTB SoCs + "brcm,spi-bcm-qspi", "brcm,spi-brcmstb-mspi" : Second Instance of MSPI + BRCMSTB SoCs + "brcm,spi-bcm-qspi", "brcm,spi-nsp-qspi" : MSPI+BSPI on Cygnus, NSP + "brcm,spi-bcm-qspi", "brcm,spi-ns2-qspi" : NS2 SoCs + +- reg: + Define the bases and ranges of the associated I/O address spaces. + The required range is MSPI controller registers. + +- reg-names: + First name does not matter, but must be reserved for the MSPI controller + register range as mentioned in 'reg' above, and will typically contain + - "bspi_regs": BSPI register range, not required with compatible + "spi-brcmstb-mspi" + - "mspi_regs": MSPI register range is required for compatible strings + - "intr_regs", "intr_status_reg" : Interrupt and status register for + NSP, NS2, Cygnus SoC + +- interrupts + The interrupts used by the MSPI and/or BSPI controller. + +- interrupt-names: + Names of interrupts associated with MSPI + - "mspi_halted" : + - "mspi_done": Indicates that the requested SPI operation is complete. + - "spi_lr_fullness_reached" : Linear read BSPI pipe full + - "spi_lr_session_aborted" : Linear read BSPI pipe aborted + - "spi_lr_impatient" : Linear read BSPI requested when pipe empty + - "spi_lr_session_done" : Linear read BSPI session done + +- clocks: + A phandle to the reference clock for this block. + +Optional properties: + + +- native-endian + Defined when using BE SoC and device uses BE register read/write + +Recommended optional m25p80 properties: +- spi-rx-bus-width: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Examples: + +BRCMSTB SoC Example: + + SPI Master (MSPI+BSPI) for SPI-NOR access: + + spi@f03e3400 { + #address-cells = <0x1>; + #size-cells = <0x0>; + compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-brcmstb-qspi"; + reg = <0xf03e0920 0x4 0xf03e3400 0x188 0xf03e3200 0x50>; + reg-names = "cs_reg", "mspi", "bspi"; + interrupts = <0x6 0x5 0x4 0x3 0x2 0x1 0x0>; + interrupt-parent = <0x1c>; + interrupt-names = "mspi_halted", + "mspi_done", + "spi_lr_overread", + "spi_lr_session_done", + "spi_lr_impatient", + "spi_lr_session_aborted", + "spi_lr_fullness_reached"; + + clocks = <&hif_spi>; + clock-names = "sw_spi"; + + m25p80@0 { + #size-cells = <0x2>; + #address-cells = <0x2>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <0x2625a00>; + spi-cpol; + spi-cpha; + m25p,fast-read; + + flash0.bolt@0 { + reg = <0x0 0x0 0x0 0x100000>; + }; + + flash0.macadr@100000 { + reg = <0x0 0x100000 0x0 0x10000>; + }; + + flash0.nvram@110000 { + reg = <0x0 0x110000 0x0 0x10000>; + }; + + flash0.kernel@120000 { + reg = <0x0 0x120000 0x0 0x400000>; + }; + + flash0.devtree@520000 { + reg = <0x0 0x520000 0x0 0x10000>; + }; + + flash0.splash@530000 { + reg = <0x0 0x530000 0x0 0x80000>; + }; + + flash0@0 { + reg = <0x0 0x0 0x0 0x4000000>; + }; + }; + }; + + + MSPI master for any SPI device : + + spi@f0416000 { + #address-cells = <1>; + #size-cells = <0>; + clocks = <&upg_fixed>; + compatible = "brcm,spi-brcmstb-qspi", "brcm,spi-brcmstb-mspi"; + reg = <0xf0416000 0x180>; + reg-names = "mspi"; + interrupts = <0x14>; + interrupt-parent = <&irq0_aon_intc>; + interrupt-names = "mspi_done"; + }; + +iProc SoC Example: + + qspi: spi@18027200 { + compatible = "brcm,spi-bcm-qspi", "brcm,spi-nsp-qspi"; + reg = <0x18027200 0x184>, + <0x18027000 0x124>, + <0x1811c408 0x004>, + <0x180273a0 0x01c>; + reg-names = "mspi_regs", "bspi_regs", "intr_regs", "intr_status_reg"; + interrupts = , + , + , + , + , + , + ; + interrupt-names = + "spi_lr_fullness_reached", + "spi_lr_session_aborted", + "spi_lr_impatient", + "spi_lr_session_done", + "mspi_done", + "mspi_halted"; + clocks = <&iprocmed>; + clock-names = "iprocmed"; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + }; + + + NS2 SoC Example: + + qspi: spi@66470200 { + compatible = "brcm,spi-bcm-qspi", "brcm,spi-ns2-qspi"; + reg = <0x66470200 0x184>, + <0x66470000 0x124>, + <0x67017408 0x004>, + <0x664703a0 0x01c>; + reg-names = "mspi", "bspi", "intr_regs", + "intr_status_reg"; + interrupts = ; + interrupt-names = "spi_l1_intr"; + clocks = <&iprocmed>; + clock-names = "iprocmed"; + num-cs = <2>; + #address-cells = <1>; + #size-cells = <0>; + }; + + + m25p80 node for NSP, NS2 + + &qspi { + flash: m25p80@0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "m25p80"; + reg = <0x0>; + spi-max-frequency = <12500000>; + m25p,fast-read; + spi-cpol; + spi-cpha; + + partition@0 { + label = "boot"; + reg = <0x00000000 0x000a0000>; + }; + + partition@a0000 { + label = "env"; + reg = <0x000a0000 0x00060000>; + }; + + partition@100000 { + label = "system"; + reg = <0x00100000 0x00600000>; + }; + + partition@700000 { + label = "rootfs"; + reg = <0x00700000 0x01900000>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/jcore,spi.txt b/Documentation/devicetree/bindings/spi/jcore,spi.txt new file mode 100644 index 000000000000..93936d16e139 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/jcore,spi.txt @@ -0,0 +1,34 @@ +J-Core SPI master + +Required properties: + +- compatible: Must be "jcore,spi2". + +- reg: Memory region for registers. + +- #address-cells: Must be 1. + +- #size-cells: Must be 0. + +Optional properties: + +- clocks: If a phandle named "ref_clk" is present, SPI clock speed + programming is relative to the frequency of the indicated clock. + Necessary only if the input clock rate is something other than a + fixed 50 MHz. + +- clock-names: Clock names, one for each phandle in clocks. + +See spi-bus.txt for additional properties not specific to this device. + +Example: + +spi@40 { + compatible = "jcore,spi2"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x40 0x8>; + spi-max-frequency = <25000000>; + clocks = <&bus_clk>; + clock-names = "ref_clk"; +} diff --git a/Documentation/devicetree/bindings/spi/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt index 17822860cb98..4b1d6e74c744 100644 --- a/Documentation/devicetree/bindings/spi/spi-bus.txt +++ b/Documentation/devicetree/bindings/spi/spi-bus.txt @@ -31,7 +31,7 @@ with max(cs-gpios > hw cs). So if for example the controller has 2 CS lines, and the cs-gpios property looks like this: -cs-gpios = <&gpio1 0 0> <0> <&gpio1 1 0> <&gpio1 2 0>; +cs-gpios = <&gpio1 0 0>, <0>, <&gpio1 1 0>, <&gpio1 2 0>; Then it should be configured so that num_chipselect = 4 with the following mapping: diff --git a/Documentation/devicetree/bindings/spi/spi-meson.txt b/Documentation/devicetree/bindings/spi/spi-meson.txt index bb52a86f3365..dc6d0313324a 100644 --- a/Documentation/devicetree/bindings/spi/spi-meson.txt +++ b/Documentation/devicetree/bindings/spi/spi-meson.txt @@ -7,7 +7,7 @@ NOR memories, without DMA support and a 64-byte unified transmit / receive buffer. Required properties: - - compatible: should be "amlogic,meson6-spifc" + - compatible: should be "amlogic,meson6-spifc" or "amlogic,meson-gxbb-spifc" - reg: physical base address and length of the controller registers - clocks: phandle of the input clock for the baud rate generator - #address-cells: should be 1 diff --git a/Documentation/devicetree/bindings/thermal/max77620_thermal.txt b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt new file mode 100644 index 000000000000..323a3b3822aa --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/max77620_thermal.txt @@ -0,0 +1,70 @@ +Thermal driver for MAX77620 Power management IC from Maxim Semiconductor. + +Maxim Semiconductor MAX77620 supports alarm interrupts when its +die temperature crosses 120C and 140C. These threshold temperatures +are not configurable. Device does not provide the real temperature +of die other than just indicating whether temperature is above or +below threshold level. + +Required properties: +------------------- +#thermal-sensor-cells: Please refer + for more details. + The value must be 0. + +For more details, please refer generic thermal DT binding document +. + +Please refer for mfd DT binding +document for the MAX77620. + +Example: +-------- +#include +#include +... + +i2c@7000d000 { + spmic: max77620@3c { + compatible = "maxim,max77620"; + ::::: + #thermal-sensor-cells = <0>; + ::: + }; +}; + +cool_dev: cool-dev { + compatible = "cooling-dev"; + #cooling-cells = <2>; +}; + +thermal-zones { + PMIC-Die { + polling-delay = <0>; + polling-delay-passive = <0>; + thermal-sensors = <&spmic>; + + trips { + pmic_die_warn_temp_thresh: hot-die { + temperature = <120000>; + type = "hot"; + hysteresis = <0>; + }; + + pmic_die_cirt_temp_thresh: cirtical-die { + temperature = <140000>; + type = "critical"; + hysteresis = <0>; + }; + }; + + cooling-maps { + map0 { + trip = <&pmic_die_warn_temp_thresh>; + cooling-device = <&cool_dev THERMAL_NO_LIMIT + THERMAL_NO_LIMIT>; + contribution = <100>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt index 81f9a512bc2a..e2f494d74d8a 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt @@ -8,7 +8,9 @@ apmixedsys register space via AHB bus accesses, so a phandle to the APMIXEDSYS is also needed. Required properties: -- compatible: "mediatek,mt8173-thermal" +- compatible: + - "mediatek,mt8173-thermal" : For MT8173 family of SoCs + - "mediatek,mt2701-thermal" : For MT2701 family of SoCs - reg: Address range of the thermal controller - interrupts: IRQ for the thermal controller - clocks, clock-names: Clocks needed for the thermal controller. required diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt index edebfa0a985e..b6c0ae53d4dc 100644 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra124-soctherm.txt @@ -10,8 +10,14 @@ Required properties : - compatible : For Tegra124, must contain "nvidia,tegra124-soctherm". For Tegra132, must contain "nvidia,tegra132-soctherm". For Tegra210, must contain "nvidia,tegra210-soctherm". -- reg : Should contain 1 entry: +- reg : Should contain at least 2 entries for each entry in reg-names: - SOCTHERM register set + - Tegra CAR register set: Required for Tegra124 and Tegra210. + - CCROC register set: Required for Tegra132. +- reg-names : Should contain at least 2 entries: + - soctherm-reg + - car-reg + - ccroc-reg - interrupts : Defines the interrupt used by SOCTHERM - clocks : Must contain an entry for each entry in clock-names. See ../clocks/clock-bindings.txt for details. @@ -25,17 +31,45 @@ Required properties : - #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description of this property. See for a list of valid values when referring to thermal sensors. +- throttle-cfgs: A sub-node which is a container of configuration for each + hardware throttle events. These events can be set as cooling devices. + * throttle events: Sub-nodes must be named as "light" or "heavy". + Properties: + - nvidia,priority: Each throttles has its own throttle settings, so the + SW need to set priorities for various throttle, the HW arbiter can select + the final throttle settings. + Bigger value indicates higher priority, In general, higher priority + translates to lower target frequency. SW needs to ensure that critical + thermal alarms are given higher priority, and ensure that there is + no race if priority of two vectors is set to the same value. + The range of this value is 1~100. + - nvidia,cpu-throt-percent: This property is for Tegra124 and Tegra210. + It is the throttling depth of pulse skippers, it's the percentage + throttling. + - nvidia,cpu-throt-level: This property is only for Tegra132, it is the + level of pulse skippers, which used to throttle clock frequencies. It + indicates cpu clock throttling depth, and the depth can be programmed. + Must set as following values: + TEGRA_SOCTHERM_THROT_LEVEL_LOW, TEGRA_SOCTHERM_THROT_LEVEL_MED + TEGRA_SOCTHERM_THROT_LEVEL_HIGH, TEGRA_SOCTHERM_THROT_LEVEL_NONE + - #cooling-cells: Should be 1. This cooling device only support on/off state. + See ./thermal.txt for a description of this property. Note: - the "critical" type trip points will be set to SOC_THERM hardware as the shut down temperature. Once the temperature of this thermal zone is higher than it, the system will be shutdown or reset by hardware. +- the "hot" type trip points will be set to SOC_THERM hardware as the throttle +temperature. Once the the temperature of this thermal zone is higher +than it, it will trigger the HW throttle event. Example : soctherm@700e2000 { compatible = "nvidia,tegra124-soctherm"; - reg = <0x0 0x700e2000 0x0 0x1000>; + reg = <0x0 0x700e2000 0x0 0x600 /* SOC_THERM reg_base */ + 0x0 0x60006000 0x0 0x400 /* CAR reg_base */ + reg-names = "soctherm-reg", "car-reg"; interrupts = ; clocks = <&tegra_car TEGRA124_CLK_TSENSOR>, <&tegra_car TEGRA124_CLK_SOC_THERM>; @@ -44,6 +78,76 @@ Example : reset-names = "soctherm"; #thermal-sensor-cells = <1>; + + throttle-cfgs { + /* + * When the "heavy" cooling device triggered, + * the HW will skip cpu clock's pulse in 85% depth + */ + throttle_heavy: heavy { + nvidia,priority = <100>; + nvidia,cpu-throt-percent = <85>; + + #cooling-cells = <1>; + }; + + /* + * When the "light" cooling device triggered, + * the HW will skip cpu clock's pulse in 50% depth + */ + throttle_light: light { + nvidia,priority = <80>; + nvidia,cpu-throt-percent = <50>; + + #cooling-cells = <1>; + }; + + /* + * If these two devices are triggered in same time, the HW throttle + * arbiter will select the highest priority as the final throttle + * settings to skip cpu pulse. + */ + }; + }; + +Example: referring to Tegra132's "reg", "reg-names" and "throttle-cfgs" : + + soctherm@700e2000 { + compatible = "nvidia,tegra132-soctherm"; + reg = <0x0 0x700e2000 0x0 0x600 /* SOC_THERM reg_base */ + 0x0 0x70040000 0x0 0x200>; /* CCROC reg_base */; + reg-names = "soctherm-reg", "ccroc-reg"; + + throttle-cfgs { + /* + * When the "heavy" cooling device triggered, + * the HW will skip cpu clock's pulse in HIGH level + */ + throttle_heavy: heavy { + nvidia,priority = <100>; + nvidia,cpu-throt-level = ; + + #cooling-cells = <1>; + }; + + /* + * When the "light" cooling device triggered, + * the HW will skip cpu clock's pulse in MED level + */ + throttle_light: light { + nvidia,priority = <80>; + nvidia,cpu-throt-level = ; + + #cooling-cells = <1>; + }; + + /* + * If these two devices are triggered in same time, the HW throttle + * arbiter will select the highest priority as the final throttle + * settings to skip cpu pulse. + */ + + }; }; Example: referring to thermal sensors : @@ -62,6 +166,19 @@ Example: referring to thermal sensors : hysteresis = <1000>; type = "critical"; }; + + cpu_throttle_trip: throttle-trip { + temperature = <100000>; + hysteresis = <1000>; + type = "hot"; + }; + }; + + cooling-maps { + map0 { + trip = <&cpu_throttle_trip>; + cooling-device = <&throttle_heavy 1 1>; + }; }; }; }; diff --git a/Documentation/devicetree/bindings/thermal/qcom-tsens.txt b/Documentation/devicetree/bindings/thermal/qcom-tsens.txt new file mode 100644 index 000000000000..292ed89d900b --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/qcom-tsens.txt @@ -0,0 +1,21 @@ +* QCOM SoC Temperature Sensor (TSENS) + +Required properties: +- compatible : + - "qcom,msm8916-tsens" : For 8916 Family of SoCs + - "qcom,msm8974-tsens" : For 8974 Family of SoCs + - "qcom,msm8996-tsens" : For 8996 Family of SoCs + +- reg: Address range of the thermal registers +- #thermal-sensor-cells : Should be 1. See ./thermal.txt for a description. +- Refer to Documentation/devicetree/bindings/nvmem/nvmem.txt to know how to specify +nvmem cells + +Example: +tsens: thermal-sensor@900000 { + compatible = "qcom,msm8916-tsens"; + reg = <0x4a8000 0x2000>; + nvmem-cells = <&tsens_caldata>, <&tsens_calsel>; + nvmem-cell-names = "caldata", "calsel"; + #thermal-sensor-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/timer/moxa,moxart-timer.txt b/Documentation/devicetree/bindings/timer/moxa,moxart-timer.txt index da2d510cae47..e207c11630af 100644 --- a/Documentation/devicetree/bindings/timer/moxa,moxart-timer.txt +++ b/Documentation/devicetree/bindings/timer/moxa,moxart-timer.txt @@ -2,7 +2,9 @@ MOXA ART timer Required properties: -- compatible : Must be "moxa,moxart-timer" +- compatible : Must be one of: + - "moxa,moxart-timer" + - "aspeed,ast2400-timer" - reg : Should contain registers location and length - interrupts : Should contain the timer interrupt number - clocks : Should contain phandle for the clock that drives the counter diff --git a/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt b/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt index 3ca89cd1caef..d191612539e8 100644 --- a/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt +++ b/Documentation/devicetree/bindings/timer/oxsemi,rps-timer.txt @@ -2,7 +2,7 @@ Oxford Semiconductor OXNAS SoCs Family RPS Timer ================================================ Required properties: -- compatible: Should be "oxsemi,ox810se-rps-timer" +- compatible: Should be "oxsemi,ox810se-rps-timer" or "oxsemi,ox820-rps-timer" - reg : Specifies base physical address and size of the registers. - interrupts : The interrupts of the two timers - clocks : The phandle of the timer clock source diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index 341dc67f3472..0e03344e2e8b 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -81,6 +81,8 @@ i.mx specific properties - fsl,usbmisc: phandler of non-core register device, with one argument that indicate usb controller index - disable-over-current: disable over current detect +- over-current-active-high: over current signal polarity is high active, + typically over current signal polarity is low active. - external-vbus-divider: enables off-chip resistor divider for Vbus Example: diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 20a68bf2b4e7..455f2c310a1b 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -10,6 +10,8 @@ Required properties: - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; - "lantiq,xrx200-usb": The DWC2 USB controller instance in Lantiq XRX SoCs; + - "amlogic,meson8b-usb": The DWC2 USB controller instance in Amlogic Meson8b SoCs; + - "amlogic,meson-gxbb-usb": The DWC2 USB controller instance in Amlogic S905 SoCs; - snps,dwc2: A generic DWC2 USB controller with default parameters. - reg : Should contain 1 register range (address and length) - interrupts : Should contain 1 interrupt @@ -26,7 +28,10 @@ Refer to phy/phy-bindings.txt for generic phy consumer properties - g-use-dma: enable dma usage in gadget driver. - g-rx-fifo-size: size of rx fifo size in gadget mode. - g-np-tx-fifo-size: size of non-periodic tx fifo size in gadget mode. -- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) in gadget mode. + +Deprecated properties: +- g-tx-fifo-size: size of periodic tx fifo per endpoint (except ep0) + in gadget mode. Example: diff --git a/Documentation/devicetree/bindings/usb/dwc3-cavium.txt b/Documentation/devicetree/bindings/usb/dwc3-cavium.txt new file mode 100644 index 000000000000..710b782ccf65 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/dwc3-cavium.txt @@ -0,0 +1,28 @@ +Cavium SuperSpeed DWC3 USB SoC controller + +Required properties: +- compatible: Should contain "cavium,octeon-7130-usb-uctl" + +Required child node: +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +Example device node: + + uctl@1180069000000 { + compatible = "cavium,octeon-7130-usb-uctl"; + reg = <0x00011800 0x69000000 0x00000000 0x00000100>; + ranges; + #address-cells = <0x00000002>; + #size-cells = <0x00000002>; + refclk-frequency = <0x05f5e100>; + refclk-type-ss = "dlmc_ref_clk0"; + refclk-type-hs = "dlmc_ref_clk0"; + power = <0x00000002 0x00000002 0x00000001>; + xhci@1690000000000 { + compatible = "cavium,octeon-7130-xhci", "synopsys,dwc3"; + reg = <0x00016900 0x00000000 0x00000010 0x00000000>; + interrupt-parent = <0x00000010>; + interrupts = <0x00000009 0x00000004>; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 7d7ce089b003..e3e6983288e3 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -13,7 +13,8 @@ Optional properties: in the array is expected to be a handle to the USB2/HS PHY and the second element is expected to be a handle to the USB3/SS PHY - phys: from the *Generic PHY* bindings - - phy-names: from the *Generic PHY* bindings + - phy-names: from the *Generic PHY* bindings; supported names are "usb2-phy" + or "usb3-phy". - snps,usb3_lpm_capable: determines if platform is USB3 LPM capable - snps,disable_scramble_quirk: true when SW should disable data scrambling. Only really useful for FPGA builds. @@ -39,6 +40,11 @@ Optional properties: disabling the suspend signal to the PHY. - snps,dis_rxdet_inp3_quirk: when set core will disable receiver detection in PHY P3 power state. + - snps,dis-u2-freeclk-exists-quirk: when set, clear the u2_freeclk_exists + in GUSB2PHYCFG, specify that USB2 PHY doesn't provide + a free-running PHY clock. + - snps,dis-del-phy-power-chg-quirk: when set core will change PHY power + from P0 to P1/P2/P3 without delay. - snps,is-utmi-l1-suspend: true when DWC3 asserts output signal utmi_l1_suspend_n, false when asserts utmi_sleep_n - snps,hird-threshold: HIRD threshold diff --git a/Documentation/devicetree/bindings/usb/generic.txt b/Documentation/devicetree/bindings/usb/generic.txt index bba825711873..bfadeb1c3bab 100644 --- a/Documentation/devicetree/bindings/usb/generic.txt +++ b/Documentation/devicetree/bindings/usb/generic.txt @@ -11,6 +11,11 @@ Optional properties: "peripheral" and "otg". In case this attribute isn't passed via DT, USB DRD controllers should default to OTG. + - phy_type: tells USB controllers that we want to configure the core to support + a UTMI+ PHY with an 8- or 16-bit interface if UTMI+ is + selected. Valid arguments are "utmi" and "utmi_wide". + In case this isn't passed via DT, USB controllers should + default to HW capability. - otg-rev: tells usb driver the release number of the OTG and EH supplement with which the device and its descriptors are compliant, in binary-coded decimal (i.e. 2.0 is 0200H). This @@ -34,6 +39,7 @@ dwc3@4a030000 { usb-phy = <&usb2_phy>, <&usb3,phy>; maximum-speed = "super-speed"; dr_mode = "otg"; + phy_type = "utmi_wide"; otg-rev = <0x0200>; adp-disable; }; diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index b6040563e51a..9e18e000339e 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -9,6 +9,7 @@ Required properties: - "renesas,usbhs-r8a7793" for r8a7793 (R-Car M2-N) compatible device - "renesas,usbhs-r8a7794" for r8a7794 (R-Car E2) compatible device - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device + - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device - "renesas,rcar-gen2-usbhs" for R-Car Gen2 compatible device - "renesas,rcar-gen3-usbhs" for R-Car Gen3 compatible device diff --git a/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt b/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt new file mode 100644 index 000000000000..0536a938e3ab --- /dev/null +++ b/Documentation/devicetree/bindings/usb/rockchip,dwc3.txt @@ -0,0 +1,59 @@ +Rockchip SuperSpeed DWC3 USB SoC controller + +Required properties: +- compatible: should contain "rockchip,rk3399-dwc3" for rk3399 SoC +- clocks: A list of phandle + clock-specifier pairs for the + clocks listed in clock-names +- clock-names: Should contain the following: + "ref_clk" Controller reference clk, have to be 24 MHz + "suspend_clk" Controller suspend clk, have to be 24 MHz or 32 KHz + "bus_clk" Master/Core clock, have to be >= 62.5 MHz for SS + operation and >= 30MHz for HS operation + "grf_clk" Controller grf clk + +Required child node: +A child node must exist to represent the core DWC3 IP block. The name of +the node is not important. The content of the node is defined in dwc3.txt. + +Phy documentation is provided in the following places: +Documentation/devicetree/bindings/phy/rockchip,dwc3-usb-phy.txt + +Example device nodes: + + usbdrd3_0: usb@fe800000 { + compatible = "rockchip,rk3399-dwc3"; + clocks = <&cru SCLK_USB3OTG0_REF>, <&cru SCLK_USB3OTG0_SUSPEND>, + <&cru ACLK_USB3OTG0>, <&cru ACLK_USB3_GRF>; + clock-names = "ref_clk", "suspend_clk", + "bus_clk", "grf_clk"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + status = "disabled"; + usbdrd_dwc3_0: dwc3@fe800000 { + compatible = "snps,dwc3"; + reg = <0x0 0xfe800000 0x0 0x100000>; + interrupts = ; + dr_mode = "otg"; + status = "disabled"; + }; + }; + + usbdrd3_1: usb@fe900000 { + compatible = "rockchip,rk3399-dwc3"; + clocks = <&cru SCLK_USB3OTG1_REF>, <&cru SCLK_USB3OTG1_SUSPEND>, + <&cru ACLK_USB3OTG1>, <&cru ACLK_USB3_GRF>; + clock-names = "ref_clk", "suspend_clk", + "bus_clk", "grf_clk"; + #address-cells = <2>; + #size-cells = <2>; + ranges; + status = "disabled"; + usbdrd_dwc3_1: dwc3@fe900000 { + compatible = "snps,dwc3"; + reg = <0x0 0xfe900000 0x0 0x100000>; + interrupts = ; + dr_mode = "otg"; + status = "disabled"; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/usb4604.txt b/Documentation/devicetree/bindings/usb/usb4604.txt new file mode 100644 index 000000000000..82506d17712c --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb4604.txt @@ -0,0 +1,19 @@ +SMSC USB4604 High-Speed Hub Controller + +Required properties: +- compatible: Should be "smsc,usb4604" + +Optional properties: +- reg: Specifies the i2c slave address, it is required and should be 0x2d + if I2C is used. +- reset-gpios: Should specify GPIO for reset. +- initial-mode: Should specify initial mode. + (1 for HUB mode, 2 for STANDBY mode) + +Examples: + usb-hub@2d { + compatible = "smsc,usb4604"; + reg = <0x2d>; + reset-gpios = <&gpx3 5 1>; + initial-mode = <1>; + }; diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt index 3539d4e7d23e..f1e27faf528e 100644 --- a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -6,6 +6,7 @@ Required properties: "fsl,imx6q-usbmisc" for imx6q "fsl,vf610-usbmisc" for Vybrid vf610 "fsl,imx6sx-usbmisc" for imx6sx + "fsl,imx7d-usbmisc" for imx7d - reg: Should contain registers location and length Examples: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 1992aa97d45a..f0a48ea78659 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -3,8 +3,8 @@ Device tree binding vendor prefix registry. Keep list in alphabetical order. This isn't an exhaustive list, but you should add new prefixes to it before using them to avoid name-space collisions. -abilis Abilis Systems abcn Abracon Corporation +abilis Abilis Systems active-semi Active-Semi International Inc ad Avionic Design GmbH adapteva Adapteva, Inc. @@ -36,6 +36,7 @@ aspeed ASPEED Technology Inc. atlas Atlas Scientific LLC atmel Atmel Corporation auo AU Optronics Corporation +auvidea Auvidea GmbH avago Avago Technologies avic Shanghai AVIC Optoelectronics Co., Ltd. axis Axis Communications AB @@ -75,6 +76,7 @@ digilent Diglent, Inc. dlg Dialog Semiconductor dlink D-Link Corporation dmo Data Modul AG +domintech Domintech Co., Ltd. dptechnics DPTechnics dragino Dragino Technology Co., Limited ea Embedded Artists AB @@ -85,6 +87,7 @@ elan Elan Microelectronic Corp. embest Shenzhen Embest Technology Co., Ltd. emmicro EM Microelectronic energymicro Silicon Laboratories (formerly Energy Micro AS) +engicam Engicam S.r.l. epcos EPCOS AG epfl Ecole Polytechnique Fédérale de Lausanne epson Seiko Epson Corp. @@ -98,11 +101,12 @@ ezchip EZchip Semiconductor fcs Fairchild Semiconductor firefly Firefly focaltech FocalTech Systems Co.,Ltd +friendlyarm Guangzhou FriendlyARM Computer Tech Co., Ltd fsl Freescale Semiconductor ge General Electric Company geekbuying GeekBuying -GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. +GEFanuc GE Fanuc Intelligent Platforms Embedded Systems, Inc. geniatech Geniatech, Inc. giantplus Giantplus Technology Co., Ltd. globalscale Globalscale Technologies, Inc. @@ -126,7 +130,6 @@ i2se I2SE GmbH ibm International Business Machines (IBM) idt Integrated Device Technologies, Inc. ifi Ingenieurburo Fur Ic-Technologie (I/F/I) -iom Iomega Corporation img Imagination Technologies Ltd. infineon Infineon Technologies inforce Inforce Computing @@ -135,11 +138,15 @@ innolux Innolux Corporation intel Intel Corporation intercontrol Inter Control Group invensense InvenSense Inc. +inversepath Inverse Path +iom Iomega Corporation isee ISEE 2007 S.L. isil Intersil issi Integrated Silicon Solutions Inc. +jdi Japan Display Inc. jedec JEDEC Solid State Technology Association karo Ka-Ro electronics GmbH +keithkoep Keith & Koep GmbH keymile Keymile GmbH kinetic Kinetic Technologies kosagi Sutajio Ko-Usagi PTE Ltd. @@ -149,16 +156,18 @@ lantiq Lantiq Semiconductor lenovo Lenovo Group Ltd. lg LG Corporation linux Linux-specific binding -lsi LSI Corp. (LSI Logic) lltc Linear Technology Corporation +lsi LSI Corp. (LSI Logic) marvell Marvell Technology Group Ltd. maxim Maxim Integrated Products meas Measurement Specialties mediatek MediaTek Inc. melexis Melexis N.V. +melfas MELFAS Inc. merrii Merrii Technology Co., Ltd. micrel Micrel Inc. microchip Microchip Technology Inc. +microcrystal Micro Crystal AG micron Micron Technology Inc. minix MINIX Technology Ltd. mitsubishi Mitsubishi Electric Corporation @@ -190,20 +199,20 @@ onnn ON Semiconductor Corp. ontat On Tat Industrial Company opencores OpenCores.org option Option NV +ORCL Oracle Corporation ortustech Ortus Technology Co., Ltd. ovti OmniVision Technologies -ORCL Oracle Corporation oxsemi Oxford Semiconductor, Ltd. panasonic Panasonic Corporation parade Parade Technologies Inc. pericom Pericom Technology Inc. phytec PHYTEC Messtechnik GmbH picochip Picochip Ltd +pixcir PIXCIR MICROELECTRONICS Co., Ltd plathome Plat'Home Co., Ltd. plda PLDA -pixcir PIXCIR MICROELECTRONICS Co., Ltd -pulsedlight PulsedLight, Inc powervr PowerVR (deprecated, use img) +pulsedlight PulsedLight, Inc qca Qualcomm Atheros, Inc. qcom Qualcomm Technologies, Inc qemu QEMU, a generic and open source machine emulator and virtualizer @@ -231,12 +240,13 @@ sgx SGX Sensortech sharp Sharp Corporation si-en Si-En Technology Ltd. sigma Sigma Designs, Inc. +sii Seiko Instruments, Inc. sil Silicon Image silabs Silicon Laboratories +silead Silead Inc. +silergy Silergy Corp. siliconmitus Silicon Mitus, Inc. simtek -sii Seiko Instruments, Inc. -silergy Silergy Corp. sirf SiRF Technology, Inc. sis Silicon Integrated Systems Corp. sitronix Sitronix Technology Corporation @@ -254,9 +264,12 @@ starry Starry Electronic Technology (ShenZhen) Co., LTD startek Startek ste ST-Ericsson stericsson ST-Ericsson +summit Summit microelectronics +sunchip Shenzhen Sunchip Technology Co., Ltd +SUNW Sun Microsystems, Inc +swir Sierra Wireless syna Synaptics Inc. synology Synology, Inc. -SUNW Sun Microsystems, Inc tbs TBS Technologies tcg Trusted Computing Group tcl Toby Churchill Ltd. @@ -265,17 +278,19 @@ technologic Technologic Systems thine THine Electronics, Inc. ti Texas Instruments tlm Trusted Logic Mobility +topeet Topeet toradex Toradex AG toshiba Toshiba Corporation toumaz Toumaz -tplink TP-LINK Technologies Co., Ltd. tpk TPK U.S.A. LLC +tplink TP-LINK Technologies Co., Ltd. +tpo TPO tronfy Tronfy tronsmart Tronsmart truly Truly Semiconductors Limited tyan Tyan Computer Corporation -upisemi uPI Semiconductor Corp. uniwest United Western Technologies Corp (UniWest) +upisemi uPI Semiconductor Corp. urt United Radiant Technology Corporation usi Universal Scientific Industrial Co., Ltd. v3 V3 Semiconductor @@ -293,7 +308,7 @@ x-powers X-Powers xes Extreme Engineering Solutions (X-ES) xillybus Xillybus Ltd. xlnx Xilinx -zyxel ZyXEL Communications Corp. zarlink Zarlink Semiconductor zii Zodiac Inflight Innovations zte ZTE Corp. +zyxel ZyXEL Communications Corp. diff --git a/Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt b/Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt index 6d63782a7378..c6ae9c9d5e3e 100644 --- a/Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/of-xilinx-wdt.txt @@ -7,6 +7,8 @@ Required properties: - reg : Physical base address and size Optional properties: +- clocks : Input clock specifier. Refer to common clock + bindings. - clock-frequency : Frequency of clock in Hz - xlnx,wdt-enable-once : 0 - Watchdog can be restarted 1 - Watchdog can be enabled just once @@ -17,6 +19,7 @@ Example: axi-timebase-wdt@40100000 { clock-frequency = <50000000>; compatible = "xlnx,xps-timebase-wdt-1.00.a"; + clocks = <&clkc 15>; reg = <0x40100000 0x10000>; xlnx,wdt-enable-once = <0x0>; xlnx,wdt-interval = <0x1b>; diff --git a/Documentation/devicetree/bindings/watchdog/st_lpc_wdt.txt b/Documentation/devicetree/bindings/watchdog/st_lpc_wdt.txt index 039c5ca45577..b949039bc502 100644 --- a/Documentation/devicetree/bindings/watchdog/st_lpc_wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/st_lpc_wdt.txt @@ -9,8 +9,7 @@ functionality. Required properties -- compatible : Must be one of: "st,stih407-lpc" "st,stih416-lpc" - "st,stih415-lpc" "st,stid127-lpc" +- compatible : Should be: "st,stih407-lpc" - reg : LPC registers base address + size - interrupts : LPC interrupt line number and associated flags - clocks : Clock used by LPC device (See: ../clock/clock-bindings.txt) diff --git a/Documentation/devicetree/changesets.txt b/Documentation/devicetree/changesets.txt index 935ba5acc34e..cb488eeb6353 100644 --- a/Documentation/devicetree/changesets.txt +++ b/Documentation/devicetree/changesets.txt @@ -21,20 +21,11 @@ a set of changes. No changes to the active tree are made at this point. All the change operations are recorded in the of_changeset 'entries' list. -3. mutex_lock(of_mutex) - starts a changeset; The global of_mutex -ensures there can only be one editor at a time. - -4. of_changeset_apply() - Apply the changes to the tree. Either the +3. of_changeset_apply() - Apply the changes to the tree. Either the entire changeset will get applied, or if there is an error the tree will -be restored to the previous state - -5. mutex_unlock(of_mutex) - All operations complete, release the mutex +be restored to the previous state. The core ensures proper serialization +through locking. An unlocked version __of_changeset_apply is available, +if needed. If a successfully applied changeset needs to be removed, it can be done -with the following sequence. - -1. mutex_lock(of_mutex) - -2. of_changeset_revert() - -3. mutex_unlock(of_mutex) +with of_changeset_revert(). diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt index 91ce82d5f0c4..c4fd47540b31 100644 --- a/Documentation/dmaengine/provider.txt +++ b/Documentation/dmaengine/provider.txt @@ -282,6 +282,17 @@ supported. that is supposed to push the current transaction descriptor to a pending queue, waiting for issue_pending to be called. + - In this structure the function pointer callback_result can be + initialized in order for the submitter to be notified that a + transaction has completed. In the earlier code the function pointer + callback has been used. However it does not provide any status to the + transaction and will be deprecated. The result structure defined as + dmaengine_result that is passed in to callback_result has two fields: + + result: This provides the transfer result defined by + dmaengine_tx_result. Either success or some error + condition. + + residue: Provides the residue bytes of the transfer for those that + support residue. * device_issue_pending - Takes the first transaction descriptor in the pending queue, diff --git a/Documentation/docutils.conf b/Documentation/docutils.conf new file mode 100644 index 000000000000..2830772264c8 --- /dev/null +++ b/Documentation/docutils.conf @@ -0,0 +1,7 @@ +# -*- coding: utf-8 mode: conf-colon -*- +# +# docutils configuration file +# http://docutils.sourceforge.net/docs/user/config.html + +[general] +halt_level: severe \ No newline at end of file diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst new file mode 100644 index 000000000000..935b9b8d456c --- /dev/null +++ b/Documentation/driver-api/basics.rst @@ -0,0 +1,120 @@ +Driver Basics +============= + +Driver Entry and Exit points +---------------------------- + +.. kernel-doc:: include/linux/init.h + :internal: + +Atomic and pointer manipulation +------------------------------- + +.. kernel-doc:: arch/x86/include/asm/atomic.h + :internal: + +Delaying, scheduling, and timer routines +---------------------------------------- + +.. kernel-doc:: include/linux/sched.h + :internal: + +.. kernel-doc:: kernel/sched/core.c + :export: + +.. kernel-doc:: kernel/sched/cpupri.c + :internal: + +.. kernel-doc:: kernel/sched/fair.c + :internal: + +.. kernel-doc:: include/linux/completion.h + :internal: + +.. kernel-doc:: kernel/time/timer.c + :export: + +Wait queues and Wake events +--------------------------- + +.. kernel-doc:: include/linux/wait.h + :internal: + +.. kernel-doc:: kernel/sched/wait.c + :export: + +High-resolution timers +---------------------- + +.. kernel-doc:: include/linux/ktime.h + :internal: + +.. kernel-doc:: include/linux/hrtimer.h + :internal: + +.. kernel-doc:: kernel/time/hrtimer.c + :export: + +Workqueues and Kevents +---------------------- + +.. kernel-doc:: include/linux/workqueue.h + :internal: + +.. kernel-doc:: kernel/workqueue.c + :export: + +Internal Functions +------------------ + +.. kernel-doc:: kernel/exit.c + :internal: + +.. kernel-doc:: kernel/signal.c + :internal: + +.. kernel-doc:: include/linux/kthread.h + :internal: + +.. kernel-doc:: kernel/kthread.c + :export: + +Kernel objects manipulation +--------------------------- + +.. kernel-doc:: lib/kobject.c + :export: + +Kernel utility functions +------------------------ + +.. kernel-doc:: include/linux/kernel.h + :internal: + +.. kernel-doc:: kernel/printk/printk.c + :export: + +.. kernel-doc:: kernel/panic.c + :export: + +.. kernel-doc:: kernel/sys.c + :export: + +.. kernel-doc:: kernel/rcu/srcu.c + :export: + +.. kernel-doc:: kernel/rcu/tree.c + :export: + +.. kernel-doc:: kernel/rcu/tree_plugin.h + :export: + +.. kernel-doc:: kernel/rcu/update.c + :export: + +Device Resource Management +-------------------------- + +.. kernel-doc:: drivers/base/devres.c + :export: + diff --git a/Documentation/driver-api/frame-buffer.rst b/Documentation/driver-api/frame-buffer.rst new file mode 100644 index 000000000000..9dd3060f027d --- /dev/null +++ b/Documentation/driver-api/frame-buffer.rst @@ -0,0 +1,62 @@ +Frame Buffer Library +==================== + +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. + +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. + +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. + +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. + +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. + +Frame Buffer Memory +------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbmem.c + :export: + +Frame Buffer Colormap +--------------------- + +.. kernel-doc:: drivers/video/fbdev/core/fbcmap.c + :export: + +Frame Buffer Video Mode Database +-------------------------------- + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :internal: + +.. kernel-doc:: drivers/video/fbdev/core/modedb.c + :export: + +Frame Buffer Macintosh Video Mode Database +------------------------------------------ + +.. kernel-doc:: drivers/video/fbdev/macmodes.c + :export: + +Frame Buffer Fonts +------------------ + +Refer to the file lib/fonts/fonts.c for more information. + diff --git a/Documentation/driver-api/hsi.rst b/Documentation/driver-api/hsi.rst new file mode 100644 index 000000000000..f9cec02b72a1 --- /dev/null +++ b/Documentation/driver-api/hsi.rst @@ -0,0 +1,88 @@ +High Speed Synchronous Serial Interface (HSI) +============================================= + +Introduction +--------------- + +High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, +that is optimized for die-level interconnect between an Application Processor +and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and +implemented by multiple vendors since then. + +The HSI interface supports full duplex communication over multiple channels +(typically 8) and is capable of reaching speeds up to 200 Mbit/s. + +The serial protocol uses two signals, DATA and FLAG as combined data and clock +signals and an additional READY signal for flow control. An additional WAKE +signal can be used to wakeup the chips from standby modes. The signals are +commonly prefixed by AC for signals going from the application die to the +cellular die and CA for signals going the other way around. + +:: + + +------------+ +---------------+ + | Cellular | | Application | + | Die | | Die | + | | - - - - - - CAWAKE - - - - - - >| | + | T|------------ CADATA ------------>|R | + | X|------------ CAFLAG ------------>|X | + | |<----------- ACREADY ------------| | + | | | | + | | | | + | |< - - - - - ACWAKE - - - - - - -| | + | R|<----------- ACDATA -------------|T | + | X|<----------- ACFLAG -------------|X | + | |------------ CAREADY ----------->| | + | | | | + | | | | + +------------+ +---------------+ + +HSI Subsystem in Linux +------------------------- + +In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. +The hsi subsystem contains drivers for hsi controllers including support for +multi-port controllers and provides a generic API for using the HSI ports. + +It also contains HSI client drivers, which make use of the generic API to +implement a protocol used on the HSI interface. These client drivers can +use an arbitrary number of channels. + +hsi-char Device +------------------ + +Each port automatically registers a generic client driver called hsi_char, +which provides a charecter device for userspace representing the HSI port. +It can be used to communicate via HSI from userspace. Userspace may +configure the hsi_char device using the following ioctl commands: + +HSC_RESET + flush the HSI port + +HSC_SET_PM + enable or disable the client. + +HSC_SEND_BREAK + send break + +HSC_SET_RX + set RX configuration + +HSC_GET_RX + get RX configuration + +HSC_SET_TX + set TX configuration + +HSC_GET_TX + get TX configuration + +The kernel HSI API +------------------ + +.. kernel-doc:: include/linux/hsi/hsi.h + :internal: + +.. kernel-doc:: drivers/hsi/hsi_core.c + :export: + diff --git a/Documentation/driver-api/i2c.rst b/Documentation/driver-api/i2c.rst new file mode 100644 index 000000000000..f3939f7852bd --- /dev/null +++ b/Documentation/driver-api/i2c.rst @@ -0,0 +1,46 @@ +I\ :sup:`2`\ C and SMBus Subsystem +================================== + +I\ :sup:`2`\ 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. + +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 +:c:type:`struct i2c_adapter ` representing each +I2C bus segment it manages. On each I2C bus segment will be I2C devices +represented by a :c:type:`struct i2c_client `. +Those devices will be bound to a :c:type:`struct i2c_driver +`, 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. + +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. + +.. kernel-doc:: include/linux/i2c.h + :internal: + +.. kernel-doc:: drivers/i2c/i2c-boardinfo.c + :functions: i2c_register_board_info + +.. kernel-doc:: drivers/i2c/i2c-core.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst new file mode 100644 index 000000000000..8e259c5d0322 --- /dev/null +++ b/Documentation/driver-api/index.rst @@ -0,0 +1,26 @@ +======================================== +The Linux driver implementer's API guide +======================================== + +The kernel offers a wide variety of interfaces to support the development +of device drivers. This document is an only somewhat organized collection +of some of those interfaces — it will hopefully get better over time! The +available subsections can be seen below. + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + basics + infrastructure + message-based + sound + frame-buffer + input + spi + i2c + hsi + miscellaneous diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst new file mode 100644 index 000000000000..5d50d6733db3 --- /dev/null +++ b/Documentation/driver-api/infrastructure.rst @@ -0,0 +1,169 @@ +Device drivers infrastructure +============================= + +The Basic Device Driver-Model Structures +---------------------------------------- + +.. kernel-doc:: include/linux/device.h + :internal: + +Device Drivers Base +------------------- + +.. kernel-doc:: drivers/base/init.c + :internal: + +.. kernel-doc:: drivers/base/driver.c + :export: + +.. kernel-doc:: drivers/base/core.c + :export: + +.. kernel-doc:: drivers/base/syscore.c + :export: + +.. kernel-doc:: drivers/base/class.c + :export: + +.. kernel-doc:: drivers/base/node.c + :internal: + +.. kernel-doc:: drivers/base/firmware_class.c + :export: + +.. kernel-doc:: drivers/base/transport_class.c + :export: + +.. kernel-doc:: drivers/base/dd.c + :export: + +.. kernel-doc:: include/linux/platform_device.h + :internal: + +.. kernel-doc:: drivers/base/platform.c + :export: + +.. kernel-doc:: drivers/base/bus.c + :export: + +Buffer Sharing and Synchronization +---------------------------------- + +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. + +This is used, for example, by drm "prime" multi-GPU support, but is of +course not limited to GPU use cases. + +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. + +dma-buf +~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :export: + +.. kernel-doc:: include/linux/dma-buf.h + :internal: + +reservation +~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/reservation.c + :doc: Reservation Object Overview + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +fence +~~~~~ + +.. kernel-doc:: drivers/dma-buf/fence.c + :export: + +.. kernel-doc:: include/linux/fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/seqno-fence.c + :export: + +.. kernel-doc:: include/linux/seqno-fence.h + :internal: + +.. kernel-doc:: drivers/dma-buf/fence-array.c + :export: + +.. kernel-doc:: include/linux/fence-array.h + :internal: + +.. kernel-doc:: drivers/dma-buf/reservation.c + :export: + +.. kernel-doc:: include/linux/reservation.h + :internal: + +.. kernel-doc:: drivers/dma-buf/sync_file.c + :export: + +.. kernel-doc:: include/linux/sync_file.h + :internal: + +Device Drivers DMA Management +----------------------------- + +.. kernel-doc:: drivers/base/dma-coherent.c + :export: + +.. kernel-doc:: drivers/base/dma-mapping.c + :export: + +Device Drivers Power Management +------------------------------- + +.. kernel-doc:: drivers/base/power/main.c + :export: + +Device Drivers ACPI Support +--------------------------- + +.. kernel-doc:: drivers/acpi/scan.c + :export: + +.. kernel-doc:: drivers/acpi/scan.c + :internal: + +Device drivers PnP support +-------------------------- + +.. kernel-doc:: drivers/pnp/core.c + :internal: + +.. kernel-doc:: drivers/pnp/card.c + :export: + +.. kernel-doc:: drivers/pnp/driver.c + :internal: + +.. kernel-doc:: drivers/pnp/manager.c + :export: + +.. kernel-doc:: drivers/pnp/support.c + :export: + +Userspace IO devices +-------------------- + +.. kernel-doc:: drivers/uio/uio.c + :export: + +.. kernel-doc:: include/linux/uio_driver.h + :internal: + diff --git a/Documentation/driver-api/input.rst b/Documentation/driver-api/input.rst new file mode 100644 index 000000000000..d05bf58fa83e --- /dev/null +++ b/Documentation/driver-api/input.rst @@ -0,0 +1,51 @@ +Input Subsystem +=============== + +Input core +---------- + +.. kernel-doc:: include/linux/input.h + :internal: + +.. kernel-doc:: drivers/input/input.c + :export: + +.. kernel-doc:: drivers/input/ff-core.c + :export: + +.. kernel-doc:: drivers/input/ff-memless.c + :export: + +Multitouch Library +------------------ + +.. kernel-doc:: include/linux/input/mt.h + :internal: + +.. kernel-doc:: drivers/input/input-mt.c + :export: + +Polled input devices +-------------------- + +.. kernel-doc:: include/linux/input-polldev.h + :internal: + +.. kernel-doc:: drivers/input/input-polldev.c + :export: + +Matrix keyboards/keypads +------------------------ + +.. kernel-doc:: include/linux/input/matrix_keypad.h + :internal: + +Sparse keymap support +--------------------- + +.. kernel-doc:: include/linux/input/sparse-keymap.h + :internal: + +.. kernel-doc:: drivers/input/sparse-keymap.c + :export: + diff --git a/Documentation/driver-api/message-based.rst b/Documentation/driver-api/message-based.rst new file mode 100644 index 000000000000..18ff94ef6d8e --- /dev/null +++ b/Documentation/driver-api/message-based.rst @@ -0,0 +1,12 @@ +Message-based devices +===================== + +Fusion message devices +---------------------- + +.. kernel-doc:: drivers/message/fusion/mptbase.c + :export: + +.. kernel-doc:: drivers/message/fusion/mptscsih.c + :export: + diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst new file mode 100644 index 000000000000..8da7d115bafc --- /dev/null +++ b/Documentation/driver-api/miscellaneous.rst @@ -0,0 +1,50 @@ +Parallel Port Devices +===================== + +.. kernel-doc:: include/linux/parport.h + :internal: + +.. kernel-doc:: drivers/parport/ieee1284.c + :export: + +.. kernel-doc:: drivers/parport/share.c + :export: + +.. kernel-doc:: drivers/parport/daisy.c + :internal: + +16x50 UART Driver +================= + +.. kernel-doc:: drivers/tty/serial/serial_core.c + :export: + +.. kernel-doc:: drivers/tty/serial/8250/8250_core.c + :export: + +Pulse-Width Modulation (PWM) +============================ + +Pulse-width modulation is a modulation technique primarily used to +control power supplied to electrical devices. + +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 :c:type:`struct pwm_chip `. Providers +are expected to embed this structure in a driver-specific structure. +This structure contains fields that describe a particular chip. + +A chip exposes one or more PWM signal sources, each of which exposed as +a :c:type:`struct pwm_device `. Operations can be +performed on PWM devices to control the period, duty cycle, polarity and +active state of the signal. + +Note that PWM devices are exclusive resources: they can always only be +used by one consumer at a time. + +.. kernel-doc:: include/linux/pwm.h + :internal: + +.. kernel-doc:: drivers/pwm/core.c + :export: + diff --git a/Documentation/driver-api/sound.rst b/Documentation/driver-api/sound.rst new file mode 100644 index 000000000000..afef6eabc073 --- /dev/null +++ b/Documentation/driver-api/sound.rst @@ -0,0 +1,54 @@ +Sound Devices +============= + +.. kernel-doc:: include/sound/core.h + :internal: + +.. kernel-doc:: sound/sound_core.c + :export: + +.. kernel-doc:: include/sound/pcm.h + :internal: + +.. kernel-doc:: sound/core/pcm.c + :export: + +.. kernel-doc:: sound/core/device.c + :export: + +.. kernel-doc:: sound/core/info.c + :export: + +.. kernel-doc:: sound/core/rawmidi.c + :export: + +.. kernel-doc:: sound/core/sound.c + :export: + +.. kernel-doc:: sound/core/memory.c + :export: + +.. kernel-doc:: sound/core/pcm_memory.c + :export: + +.. kernel-doc:: sound/core/init.c + :export: + +.. kernel-doc:: sound/core/isadma.c + :export: + +.. kernel-doc:: sound/core/control.c + :export: + +.. kernel-doc:: sound/core/pcm_lib.c + :export: + +.. kernel-doc:: sound/core/hwdep.c + :export: + +.. kernel-doc:: sound/core/pcm_native.c + :export: + +.. kernel-doc:: sound/core/memalloc.c + :export: + diff --git a/Documentation/driver-api/spi.rst b/Documentation/driver-api/spi.rst new file mode 100644 index 000000000000..f64cb666498a --- /dev/null +++ b/Documentation/driver-api/spi.rst @@ -0,0 +1,53 @@ +Serial Peripheral Interface (SPI) +================================= + +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. + +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.) + +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 :c:type:`struct spi_master +`. SPI devices are children of that master, +represented as a :c:type:`struct spi_device ` and +manufactured from :c:type:`struct spi_board_info +` descriptors which are usually provided by +board-specific initialization code. A :c:type:`struct spi_driver +` is called a "Protocol Driver", and is bound to a +spi_device using normal driver model calls. + +The I/O model is a set of queued messages. Protocol drivers submit one +or more :c:type:`struct spi_message ` objects, +which are processed and completed asynchronously. (There are synchronous +wrappers, however.) Messages are built from one or more +:c:type:`struct spi_transfer ` 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. + +.. kernel-doc:: include/linux/spi/spi.h + :internal: + +.. kernel-doc:: drivers/spi/spi.c + :functions: spi_register_board_info + +.. kernel-doc:: drivers/spi/spi.c + :export: diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt index 1e70220d20f4..2403eb856187 100644 --- a/Documentation/driver-model/device.txt +++ b/Documentation/driver-model/device.txt @@ -50,7 +50,7 @@ Attributes of devices can be exported by a device driver through sysfs. Please see Documentation/filesystems/sysfs.txt for more information on how sysfs works. -As explained in Documentation/kobject.txt, device attributes must be be +As explained in Documentation/kobject.txt, device attributes must be created before the KOBJ_ADD uevent is generated. The only way to realize that is by defining an attribute group. diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index b0d775d28e97..167070895498 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -266,8 +266,12 @@ IIO devm_iio_device_unregister() devm_iio_kfifo_allocate() devm_iio_kfifo_free() + devm_iio_triggered_buffer_setup() + devm_iio_triggered_buffer_cleanup() devm_iio_trigger_alloc() devm_iio_trigger_free() + devm_iio_trigger_register() + devm_iio_trigger_unregister() devm_iio_channel_get() devm_iio_channel_release() devm_iio_channel_get_all() @@ -342,6 +346,10 @@ PINCTRL devm_pinctrl_register() devm_pinctrl_unregister() +POWER + devm_reboot_mode_register() + devm_reboot_mode_unregister() + PWM devm_pwm_get() devm_pwm_put() diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt index 2d485dea8cec..ac892b30815e 100644 --- a/Documentation/email-clients.txt +++ b/Documentation/email-clients.txt @@ -1,23 +1,27 @@ +.. _email_clients: + Email clients info for Linux -====================================================================== +============================ Git ----------------------------------------------------------------------- -These days most developers use `git send-email` instead of regular +--- + +These days most developers use ``git send-email`` instead of regular email clients. The man page for this is quite good. On the receiving -end, maintainers use `git am` to apply the patches. +end, maintainers use ``git am`` to apply the patches. -If you are new to git then send your first patch to yourself. Save it -as raw text including all the headers. Run `git am raw_email.txt` and -then review the changelog with `git log`. When that works then send +If you are new to ``git`` then send your first patch to yourself. Save it +as raw text including all the headers. Run ``git am raw_email.txt`` and +then review the changelog with ``git log``. When that works then send the patch to the appropriate mailing list(s). General Preferences ----------------------------------------------------------------------- +------------------- + Patches for the Linux kernel are submitted via email, preferably as inline text in the body of the email. Some maintainers accept attachments, but then the attachments should have content-type -"text/plain". However, attachments are generally frowned upon because +``text/plain``. However, attachments are generally frowned upon because it makes quoting portions of the patch more difficult in the patch review process. @@ -25,7 +29,7 @@ Email clients that are used for Linux kernel patches should send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines. -Don't send patches with "format=flowed". This can cause unexpected +Don't send patches with ``format=flowed``. This can cause unexpected and unwanted line breaks. Don't let your email client do automatic word wrapping for you. @@ -54,57 +58,63 @@ mailing lists. Some email client (MUA) hints ----------------------------------------------------------------------- +----------------------------- + Here are some specific MUA configuration hints for editing and sending patches for the Linux kernel. These are not meant to be complete software package configuration summaries. + Legend: -TUI = text-based user interface -GUI = graphical user interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- TUI = text-based user interface +- GUI = graphical user interface + Alpine (TUI) +************ Config options: -In the "Sending Preferences" section: -- "Do Not Send Flowed Text" must be enabled -- "Strip Whitespace Before Sending" must be disabled +In the :menuselection:`Sending Preferences` section: + +- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` When composing the message, the cursor should be placed where the patch -should appear, and then pressing CTRL-R let you specify the patch file +should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file to insert into the message. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Claws Mail (GUI) +**************** Works. Some people use this successfully for patches. -To insert a patch use Message->Insert File (CTRL+i) or an external editor. +To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +or an external editor. If the inserted patch has to be edited in the Claws composition window -"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be +"Auto wrapping" in +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be disabled. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Evolution (GUI) +*************** Some people use this successfully for patches. When composing mail select: Preformat - from Format->Paragraph Style->Preformatted (Ctrl-7) + from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) or the toolbar Then use: - Insert->Text File... (Alt-n x) +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) to insert the patch. -You can also "diff -Nru old.c new.c | xclip", select Preformat, then -paste with the middle button. +You can also ``diff -Nru old.c new.c | xclip``, select +:menuselection:`Preformat`, then paste with the middle button. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kmail (GUI) +*********** Some people use Kmail successfully for patches. @@ -120,11 +130,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing wrapping. At the bottom of your email, put the commonly-used patch delimiter before -inserting your patch: three hyphens (---). +inserting your patch: three hyphens (``---``). -Then from the "Message" menu item, select insert file and choose your patch. +Then from the :menuselection:`Message` menu item, select insert file and +choose your patch. As an added bonus you can customise the message creation toolbar menu -and put the "insert file" icon there. +and put the :menuselection:`insert file` icon there. Make the composer window wide enough so that no lines wrap. As of KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending @@ -139,86 +150,96 @@ as inlined text will make them tricky to extract from their 7-bit encoding. If you absolutely must send patches as attachments instead of inlining them as text, right click on the attachment and select properties, and -highlight "Suggest automatic display" to make the attachment inlined to -make it more viewable. +highlight :menuselection:`Suggest automatic display` to make the attachment +inlined to make it more viewable. When saving patches that are sent as inlined text, select the email that contains the patch from the message list pane, right click and select -"save as". You can use the whole email unmodified as a patch if it was -properly composed. There is no option currently to save the email when you -are actually viewing it in its own window -- there has been a request filed -at kmail's bugzilla and hopefully this will be addressed. Emails are saved -as read-write for user only so you will have to chmod them to make them +:menuselection:`save as`. You can use the whole email unmodified as a patch +if it was properly composed. There is no option currently to save the email +when you are actually viewing it in its own window -- there has been a request +filed at kmail's bugzilla and hopefully this will be addressed. Emails are +saved as read-write for user only so you will have to chmod them to make them group and world readable if you copy them elsewhere. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Lotus Notes (GUI) +***************** Run away from it. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Mutt (TUI) +********** -Plenty of Linux developers use mutt, so it must work pretty well. +Plenty of Linux developers use ``mutt``, so it must work pretty well. Mutt doesn't come with an editor, so whatever editor you use should be used in a way that there are no automatic linebreaks. Most editors have -an "insert file" option that inserts the contents of a file unaltered. +an :menuselection:`insert file` option that inserts the contents of a file +unaltered. + +To use ``vim`` with mutt:: -To use 'vim' with mutt: set editor="vi" - If using xclip, type the command +If using xclip, type the command:: + :set paste - before middle button or shift-insert or use + +before middle button or shift-insert or use:: + :r filename if you want to include the patch inline. -(a)ttach works fine without "set paste". +(a)ttach works fine without ``set paste``. + +You can also generate patches with ``git format-patch`` and then use Mutt +to send them:: -You can also generate patches with 'git format-patch' and then use Mutt -to send them: $ mutt -H 0001-some-bug-fix.patch Config options: + It should work with default settings. -However, it's a good idea to set the "send_charset" to: +However, it's a good idea to set the ``send_charset`` to:: + set send_charset="us-ascii:utf-8" Mutt is highly customizable. Here is a minimum configuration to start -using Mutt to send patches through Gmail: - -# .muttrc -# ================ IMAP ==================== -set imap_user = 'yourusername@gmail.com' -set imap_pass = 'yourpassword' -set spoolfile = imaps://imap.gmail.com/INBOX -set folder = imaps://imap.gmail.com/ -set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" -set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" -set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" - -# ================ SMTP ==================== -set smtp_url = "smtp://username@smtp.gmail.com:587/" -set smtp_pass = $imap_pass -set ssl_force_tls = yes # Require encrypted connection - -# ================ Composition ==================== -set editor = `echo \$EDITOR` -set edit_headers = yes # See the headers when editing -set charset = UTF-8 # value of $LANG; also fallback for send_charset -# Sender, email address, and sign-off line must match -unset use_domain # because joe@localhost is just embarrassing -set realname = "YOUR NAME" -set from = "username@gmail.com" -set use_from = yes +using Mutt to send patches through Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection + + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes The Mutt docs have lots more information: + http://dev.mutt.org/trac/wiki/UseCases/Gmail + http://dev.mutt.org/doc/manual.html -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pine (TUI) +********** Pine has had some whitespace truncation issues in the past, but these should all be fixed now. @@ -226,12 +247,13 @@ should all be fixed now. Use alpine (pine's successor) if you can. Config options: -- quell-flowed-text is needed for recent versions -- the "no-strip-whitespace-before-send" option is needed + +- ``quell-flowed-text`` is needed for recent versions +- the ``no-strip-whitespace-before-send`` option is needed -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sylpheed (GUI) +************** - Works well for inlining text (or using attachments). - Allows use of an external editor. @@ -241,50 +263,50 @@ Sylpheed (GUI) - Adding addresses to address book doesn't understand the display name properly. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thunderbird (GUI) +***************** Thunderbird is an Outlook clone that likes to mangle text, but there are ways to coerce it into behaving. - Allow use of an external editor: The easiest thing to do with Thunderbird and patches is to use an - "external editor" extension and then just use your favorite $EDITOR + "external editor" extension and then just use your favorite ``$EDITOR`` for reading/merging patches into the body text. To do this, download and install the extension, then add a button for it using - View->Toolbars->Customize... and finally just click on it when in the - Compose dialog. + :menuselection:`View-->Toolbars-->Customize...` and finally just click on it + when in the :menuselection:`Compose` dialog. Please note that "external editor" requires that your editor must not fork, or in other words, the editor must not return before closing. You may have to pass additional flags or change the settings of your editor. Most notably if you are using gvim then you must pass the -f - option to gvim by putting "/usr/bin/gvim -f" (if the binary is in - /usr/bin) to the text editor field in "external editor" settings. If you - are using some other editor then please read its manual to find out how - to do this. + option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in + ``/usr/bin``) to the text editor field in :menuselection:`external editor` + settings. If you are using some other editor then please read its manual + to find out how to do this. To beat some sense out of the internal editor, do this: -- Edit your Thunderbird config settings so that it won't use format=flowed. - Go to "edit->preferences->advanced->config editor" to bring up the - thunderbird's registry editor. +- Edit your Thunderbird config settings so that it won't use ``format=flowed``. + Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up + the thunderbird's registry editor. -- Set "mailnews.send_plaintext_flowed" to "false" +- Set ``mailnews.send_plaintext_flowed`` to ``false`` -- Set "mailnews.wraplength" from "72" to "0" +- Set ``mailnews.wraplength`` from ``72`` to ``0`` -- "View" > "Message Body As" > "Plain Text" +- :menuselection:`View-->Message Body As-->Plain Text` -- "View" > "Character Encoding" > "Unicode (UTF-8)" +- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TkRat (GUI) +*********** Works. Use "Insert file..." or external editor. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Gmail (Web GUI) +*************** Does not work for sending patches. @@ -295,5 +317,3 @@ although tab2space problem can be solved with external editor. Another problem is that Gmail will base64-encode any message that has a non-ASCII character. That includes things like European names. - - ### diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 9855ad044386..4660bf222db1 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -22,7 +22,7 @@ | m68k: | TODO | | metag: | TODO | | microblaze: | TODO | - | mips: | TODO | + | mips: | ok | | mn10300: | TODO | | nios2: | TODO | | openrisc: | TODO | diff --git a/Documentation/filesystems/.gitignore b/Documentation/filesystems/.gitignore deleted file mode 100644 index 31d6e426b6d4..000000000000 --- a/Documentation/filesystems/.gitignore +++ /dev/null @@ -1 +0,0 @@ -dnotify_test diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX index 9922939e7d99..f66e748fc5e4 100644 --- a/Documentation/filesystems/00-INDEX +++ b/Documentation/filesystems/00-INDEX @@ -2,8 +2,6 @@ - this file (info on some of the filesystems supported by linux). Locking - info on locking rules as they pertain to Linux VFS. -Makefile - - Makefile for building the filsystems-part of DocBook. 9p.txt - 9p (v9fs) is an implementation of the Plan 9 remote fs protocol. adfs.txt diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index d30fb2cb5066..14cdc101d165 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -51,8 +51,6 @@ prototypes: int (*rmdir) (struct inode *,struct dentry *); int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); int (*rename) (struct inode *, struct dentry *, - struct inode *, struct dentry *); - int (*rename2) (struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); const char *(*get_link) (struct dentry *, struct inode *, void **); @@ -61,10 +59,7 @@ prototypes: int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *); - int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); - ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); ssize_t (*listxattr) (struct dentry *, char *, size_t); - int (*removexattr) (struct dentry *, const char *); int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, @@ -83,31 +78,44 @@ symlink: yes mkdir: yes unlink: yes (both) rmdir: yes (both) (see below) -rename: yes (all) (see below) -rename2: yes (all) (see below) +rename: yes (all) (see below) readlink: no get_link: no setattr: yes permission: no (may not block if called in rcu-walk mode) get_acl: no getattr: no -setxattr: yes -getxattr: no listxattr: no -removexattr: yes fiemap: no update_time: no atomic_open: yes tmpfile: no + Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on victim. - cross-directory ->rename() and rename2() has (per-superblock) -->s_vfs_rename_sem. + cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. See Documentation/filesystems/directory-locking for more detailed discussion of the locking scheme for directory operations. +----------------------- xattr_handler operations ----------------------- +prototypes: + bool (*list)(struct dentry *dentry); + int (*get)(const struct xattr_handler *handler, struct dentry *dentry, + struct inode *inode, const char *name, void *buffer, + size_t size); + int (*set)(const struct xattr_handler *handler, struct dentry *dentry, + struct inode *inode, const char *name, const void *buffer, + size_t size, int flags); + +locking rules: + all may block + i_mutex(inode) +list: no +get: no +set: yes + --------------------------- super_operations --------------------------- prototypes: struct inode *(*alloc_inode)(struct super_block *sb); diff --git a/Documentation/filesystems/Makefile b/Documentation/filesystems/Makefile deleted file mode 100644 index 883010ce5e35..000000000000 --- a/Documentation/filesystems/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# List of programs to build -hostprogs-y := dnotify_test - -# Tell kbuild to always build the programs -always := $(hostprogs-y) diff --git a/Documentation/filesystems/autofs4-mount-control.txt b/Documentation/filesystems/autofs4-mount-control.txt index aff22113a986..50a3e01a36f8 100644 --- a/Documentation/filesystems/autofs4-mount-control.txt +++ b/Documentation/filesystems/autofs4-mount-control.txt @@ -179,8 +179,19 @@ struct autofs_dev_ioctl { * including this struct */ __s32 ioctlfd; /* automount command fd */ - __u32 arg1; /* Command parameters */ - __u32 arg2; + union { + struct args_protover protover; + struct args_protosubver protosubver; + struct args_openmount openmount; + struct args_ready ready; + struct args_fail fail; + struct args_setpipefd setpipefd; + struct args_timeout timeout; + struct args_requester requester; + struct args_expire expire; + struct args_askumount askumount; + struct args_ismountpoint ismountpoint; + }; char path[0]; }; @@ -192,8 +203,8 @@ optionally be used to check a specific mount corresponding to a given mount point file descriptor, and when requesting the uid and gid of the last successful mount on a directory within the autofs file system. -The fields arg1 and arg2 are used to communicate parameters and results of -calls made as described below. +The union is used to communicate parameters and results of calls made +as described below. The path field is used to pass a path where it is needed and the size field is used account for the increased structure length when translating the @@ -245,9 +256,9 @@ AUTOFS_DEV_IOCTL_PROTOVER_CMD and AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD Get the major and minor version of the autofs4 protocol version understood by loaded module. This call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to a valid autofs mount point descriptor -and sets the requested version number in structure field arg1. These -commands return 0 on success or one of the negative error codes if -validation fails. +and sets the requested version number in version field of struct args_protover +or sub_version field of struct args_protosubver. These commands return +0 on success or one of the negative error codes if validation fails. AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT @@ -256,9 +267,9 @@ AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT Obtain and release a file descriptor for an autofs managed mount point path. The open call requires an initialized struct autofs_dev_ioctl with the path field set and the size field adjusted appropriately as well -as the arg1 field set to the device number of the autofs mount. The -device number can be obtained from the mount options shown in -/proc/mounts. The close call requires an initialized struct +as the devid field of struct args_openmount set to the device number of +the autofs mount. The device number can be obtained from the mount options +shown in /proc/mounts. The close call requires an initialized struct autofs_dev_ioct with the ioctlfd field set to the descriptor obtained from the open call. The release of the file descriptor can also be done with close(2) so any open descriptors will also be closed at process exit. @@ -272,10 +283,10 @@ AUTOFS_DEV_IOCTL_READY_CMD and AUTOFS_DEV_IOCTL_FAIL_CMD Return mount and expire result status from user space to the kernel. Both of these calls require an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open -call and the arg1 field set to the wait queue token number, received -by user space in the foregoing mount or expire request. The arg2 field -is set to the status to be returned. For the ready call this is always -0 and for the fail call it is set to the errno of the operation. +call and the token field of struct args_ready or struct args_fail set +to the wait queue token number, received by user space in the foregoing +mount or expire request. The status field of struct args_fail is set to +the errno of the operation. It is set to 0 on success. AUTOFS_DEV_IOCTL_SETPIPEFD_CMD @@ -290,9 +301,10 @@ mount be catatonic (see next call). The call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open call and -the arg1 field set to descriptor of the pipe. On success the call -also sets the process group id used to identify the controlling process -(eg. the owning automount(8) daemon) to the process group of the caller. +the pipefd field of struct args_setpipefd set to descriptor of the pipe. +On success the call also sets the process group id used to identify the +controlling process (eg. the owning automount(8) daemon) to the process +group of the caller. AUTOFS_DEV_IOCTL_CATATONIC_CMD @@ -323,9 +335,8 @@ mount on the given path dentry. The call requires an initialized struct autofs_dev_ioctl with the path field set to the mount point in question and the size field adjusted -appropriately as well as the arg1 field set to the device number of the -containing autofs mount. Upon return the struct field arg1 contains the -uid and arg2 the gid. +appropriately. Upon return the uid field of struct args_requester contains +the uid and gid field the gid. When reconstructing an autofs mount tree with active mounts we need to re-connect to mounts that may have used the original process uid and @@ -343,8 +354,9 @@ this ioctl is called until no further expire candidates are found. The call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open call. In addition an immediate expire, independent of the mount timeout, can be -requested by setting the arg1 field to 1. If no expire candidates can -be found the ioctl returns -1 with errno set to EAGAIN. +requested by setting the how field of struct args_expire to 1. If no +expire candidates can be found the ioctl returns -1 with errno set to +EAGAIN. This call causes the kernel module to check the mount corresponding to the given ioctlfd for mounts that can be expired, issues an expire @@ -357,7 +369,8 @@ Checks if an autofs mount point is in use. The call requires an initialized struct autofs_dev_ioctl with the ioctlfd field set to the descriptor obtained from the open call and -it returns the result in the arg1 field, 1 for busy and 0 otherwise. +it returns the result in the may_umount field of struct args_askumount, +1 for busy and 0 otherwise. AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD @@ -369,12 +382,12 @@ The call requires an initialized struct autofs_dev_ioctl. There are two possible variations. Both use the path field set to the path of the mount point to check and the size field adjusted appropriately. One uses the ioctlfd field to identify a specific mount point to check while the other -variation uses the path and optionally arg1 set to an autofs mount type. -The call returns 1 if this is a mount point and sets arg1 to the device -number of the mount and field arg2 to the relevant super block magic -number (described below) or 0 if it isn't a mountpoint. In both cases -the the device number (as returned by new_encode_dev()) is returned -in field arg1. +variation uses the path and optionally in.type field of struct args_ismountpoint +set to an autofs mount type. The call returns 1 if this is a mount point +and sets out.devid field to the device number of the mount and out.magic +field to the relevant super block magic number (described below) or 0 if +it isn't a mountpoint. In both cases the the device number (as returned +by new_encode_dev()) is returned in out.devid field. If supplied with a file descriptor we're looking for a specific mount, not necessarily at the top of the mounted stack. In this case the path diff --git a/Documentation/filesystems/autofs4.txt b/Documentation/filesystems/autofs4.txt index 39d02e19fb62..8fac3fe7b8c9 100644 --- a/Documentation/filesystems/autofs4.txt +++ b/Documentation/filesystems/autofs4.txt @@ -203,9 +203,9 @@ initiated or is being considered, otherwise it returns 0. Mountpoint expiry ----------------- -The VFS has a mechansim for automatically expiring unused mounts, +The VFS has a mechanism for automatically expiring unused mounts, much as it can expire any unused dentry information from the dcache. -This is guided by the MNT_SHRINKABLE flag. This only applies to +This is guided by the MNT_SHRINKABLE flag. This only applies to mounts that were created by `d_automount()` returning a filesystem to be mounted. As autofs doesn't return such a filesystem but leaves the mounting to the automount daemon, it must involve the automount daemon @@ -298,7 +298,7 @@ remove directories and symlinks using normal filesystem operations. autofs knows whether a process requesting some operation is the daemon or not based on its process-group id number (see getpgid(1)). -When an autofs filesystem it mounted the pgid of the mounting +When an autofs filesystem is mounted the pgid of the mounting processes is recorded unless the "pgrp=" option is given, in which case that number is recorded instead. Any request arriving from a process in that process group is considered to come from the daemon. @@ -450,7 +450,7 @@ Commands are: numbers for existing filesystems can be found in `/proc/self/mountinfo`. - **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: same as `close(ioctlfd)`. -- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in +- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in catatonic mode, this can provide the write end of a new pipe in `arg1` to re-establish communication with a daemon. The process group of the calling process is used to identify the diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt index d6030aa33376..f5306ee40ea9 100644 --- a/Documentation/filesystems/ceph.txt +++ b/Documentation/filesystems/ceph.txt @@ -98,6 +98,10 @@ Mount Options size. rsize=X + Specify the maximum read size in bytes. By default there is no + maximum. + + rasize=X Specify the maximum readahead. mount_timeout=X diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index 0c16a22521a8..23d18b8a49d5 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -123,9 +123,12 @@ The DAX code does not work correctly on architectures which have virtually mapped caches such as ARM, MIPS and SPARC. Calling get_user_pages() on a range of user memory that has been mmaped -from a DAX file will fail as there are no 'struct page' to describe -those pages. This problem is being worked on. That means that O_DIRECT -reads/writes to those memory ranges from a non-DAX file will fail (note -that O_DIRECT reads/writes _of a DAX file_ do work, it is the memory -that is being accessed that is key here). Other things that will not -work include RDMA, sendfile() and splice(). +from a DAX file will fail when there are no 'struct page' to describe +those pages. This problem has been addressed in some device drivers +by adding optional struct page support for pages under the control of +the driver (see CONFIG_NVDIMM_PFN in drivers/nvdimm for an example of +how to do this). In the non struct page cases O_DIRECT reads/writes to +those memory ranges from a non-DAX file will fail (note that O_DIRECT +reads/writes _of a DAX file_ do work, it is the memory that is being +accessed that is key here). Other things that will not work in the +non struct page case include RDMA, sendfile() and splice(). diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking index c314badbcfc6..4e32cb961e5b 100644 --- a/Documentation/filesystems/directory-locking +++ b/Documentation/filesystems/directory-locking @@ -19,7 +19,7 @@ locks victim and calls the method. Locks are exclusive. 4) rename() that is _not_ cross-directory. Locking rules: caller locks the parent and finds source and target. In case of exchange (with -RENAME_EXCHANGE in rename2() flags argument) lock both. In any case, +RENAME_EXCHANGE in flags argument) lock both. In any case, if the target already exists, lock it. If the source is a non-directory, lock it. If we need to lock both, lock them in inode pointer order. Then call the method. All locks are exclusive. diff --git a/Documentation/filesystems/dnotify_test.c b/Documentation/filesystems/dnotify_test.c deleted file mode 100644 index 8b37b4a1e18d..000000000000 --- a/Documentation/filesystems/dnotify_test.c +++ /dev/null @@ -1,34 +0,0 @@ -#define _GNU_SOURCE /* needed to get the defines */ -#include /* in glibc 2.2 this has the needed - values defined */ -#include -#include -#include - -static volatile int event_fd; - -static void handler(int sig, siginfo_t *si, void *data) -{ - event_fd = si->si_fd; -} - -int main(void) -{ - struct sigaction act; - int fd; - - act.sa_sigaction = handler; - sigemptyset(&act.sa_mask); - act.sa_flags = SA_SIGINFO; - sigaction(SIGRTMIN + 1, &act, NULL); - - fd = open(".", O_RDONLY); - fcntl(fd, F_SETSIG, SIGRTMIN + 1); - fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT); - /* we will now be notified if any of the files - in "." is modified or new files are created */ - while (1) { - pause(); - printf("Got event on fd=%d\n", event_fd); - } -} diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index ecd808088362..753dd4f96afe 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -131,6 +131,7 @@ inline_dentry Enable the inline dir feature: data in new created directory entries can be written into inode block. The space of inode block which is used to store inline dentries is limited to ~3.4k. +noinline_dentry Diable the inline dentry feature. flush_merge Merge concurrent cache_flush commands as much as possible to eliminate redundant command issues. If the underlying device handles the cache_flush command relatively slowly, diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index b1bd05ea66b2..bdd025ceb763 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -287,8 +287,8 @@ implementing on-disk size changes. Start with a copy of the old inode_setattr and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to be in order of zeroing blocks using block_truncate_page or similar helpers, size update and on finally on-disk truncation which should not fail. -inode_change_ok now includes the size checks for ATTR_SIZE and must be called -in the beginning of ->setattr unconditionally. +setattr_prepare (which used to be inode_change_ok) now includes the size checks +for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally. [mandatory] @@ -592,3 +592,7 @@ in your dentry operations instead. work just as well; if it's something more complicated, use dentry->d_parent. Just be careful not to assume that fetching it more than once will yield the same value - in RCU mode it could change under you. +-- +[mandatory] + ->rename() has an added flags argument. Any flags not handled by the + filesystem should result in EINVAL being returned. diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 68080ad6a75e..219ffd41a911 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -145,7 +145,7 @@ Table 1-1: Process specific entries in /proc symbol the task is blocked in - or "0" if not blocked. pagemap Page table stack Report full stack trace, enable via CONFIG_STACKTRACE - smaps a extension based on maps, showing the memory consumption of + smaps an extension based on maps, showing the memory consumption of each mapping and flags associated with it numa_maps an extension based on maps, showing the memory locality and binding policy as well as mem usage (in pages) of each mapping. @@ -515,6 +515,18 @@ be vanished or the reverse -- new added. This file is only present if the CONFIG_MMU kernel configuration option is enabled. +Note: reading /proc/PID/maps or /proc/PID/smaps is inherently racy (consistent +output can be achieved only in the single read call). +This typically manifests when doing partial reads of these files while the +memory map is being modified. Despite the races, we do provide the following +guarantees: + +1) The mapped addresses never go backwards, which implies no two + regions will ever overlap. +2) If there is something at a given vaddr during the entirety of the + life of the smaps/maps walk, there will be some output for it. + + The /proc/PID/clear_refs is used to reset the PG_Referenced and ACCESSED/YOUNG bits on both physical and virtual pages associated with a process, and the soft-dirty bit on pte (see Documentation/vm/soft-dirty.txt for details). diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 9ace359d6cc5..d619c8d71966 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -323,6 +323,35 @@ Whoever sets up the inode is responsible for filling in the "i_op" field. This is a pointer to a "struct inode_operations" which describes the methods that can be performed on individual inodes. +struct xattr_handlers +--------------------- + +On filesystems that support extended attributes (xattrs), the s_xattr +superblock field points to a NULL-terminated array of xattr handlers. Extended +attributes are name:value pairs. + + name: Indicates that the handler matches attributes with the specified name + (such as "system.posix_acl_access"); the prefix field must be NULL. + + prefix: Indicates that the handler matches all attributes with the specified + name prefix (such as "user."); the name field must be NULL. + + list: Determine if attributes matching this xattr handler should be listed + for a particular dentry. Used by some listxattr implementations like + generic_listxattr. + + get: Called by the VFS to get the value of a particular extended attribute. + This method is called by the getxattr(2) system call. + + set: Called by the VFS to set the value of a particular extended attribute. + When the new value is NULL, called to remove a particular extended + attribute. This method is called by the the setxattr(2) and + removexattr(2) system calls. + +When none of the xattr handlers of a filesystem match the specified attribute +name or when a filesystem doesn't support extended attributes, the various +*xattr(2) system calls return -EOPNOTSUPP. + The Inode Object ================ @@ -346,8 +375,6 @@ struct inode_operations { int (*rmdir) (struct inode *,struct dentry *); int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); int (*rename) (struct inode *, struct dentry *, - struct inode *, struct dentry *); - int (*rename2) (struct inode *, struct dentry *, struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); const char *(*get_link) (struct dentry *, struct inode *, @@ -356,10 +383,7 @@ struct inode_operations { int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *); - int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); - ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); ssize_t (*listxattr) (struct dentry *, char *, size_t); - int (*removexattr) (struct dentry *, const char *); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, unsigned open_flag, umode_t create_mode, int *opened); @@ -416,11 +440,8 @@ otherwise noted. rename: called by the rename(2) system call to rename the object to have the parent and name given by the second inode and dentry. - rename2: this has an additional flags argument compared to rename. - If no flags are supported by the filesystem then this method - need not be implemented. If some flags are supported then the - filesystem must return -EINVAL for any unsupported or unknown - flags. Currently the following flags are implemented: + The filesystem must return -EINVAL for any unsupported or + unknown flags. Currently the following flags are implemented: (1) RENAME_NOREPLACE: this flag indicates that if the target of the rename exists the rename should fail with -EEXIST instead of replacing the target. The VFS already checks for @@ -463,19 +484,8 @@ otherwise noted. getattr: called by the VFS to get attributes of a file. This method is called by stat(2) and related system calls. - setxattr: called by the VFS to set an extended attribute for a file. - Extended attribute is a name:value pair associated with an - inode. This method is called by setxattr(2) system call. - - getxattr: called by the VFS to retrieve the value of an extended - attribute name. This method is called by getxattr(2) function - call. - listxattr: called by the VFS to list all extended attributes for a - given file. This method is called by listxattr(2) system call. - - removexattr: called by the VFS to remove an extended attribute from - a file. This method is called by removexattr(2) system call. + given file. This method is called by the listxattr(2) system call. update_time: called by the VFS to update a specific time or the i_version of an inode. If this is not defined the VFS will update the inode itself @@ -722,7 +732,7 @@ struct address_space_operations { The second case is when a request has been made to invalidate some or all pages in an address_space. This can happen - through the fadvice(POSIX_FADV_DONTNEED) system call or by the + through the fadvise(POSIX_FADV_DONTNEED) system call or by the filesystem explicitly requesting it as nfs and 9fs do (when they believe the cache may be out of date with storage) by calling invalidate_inode_pages2(). diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index 8146e9fd5ffc..c2d44e6e117b 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -348,3 +348,126 @@ Removed Sysctls ---- ------- fs.xfs.xfsbufd_centisec v4.0 fs.xfs.age_buffer_centisecs v4.0 + + +Error handling +============== + +XFS can act differently according to the type of error found during its +operation. The implementation introduces the following concepts to the error +handler: + + -failure speed: + Defines how fast XFS should propagate an error upwards when a specific + error is found during the filesystem operation. It can propagate + immediately, after a defined number of retries, after a set time period, + or simply retry forever. + + -error classes: + Specifies the subsystem the error configuration will apply to, such as + metadata IO or memory allocation. Different subsystems will have + different error handlers for which behaviour can be configured. + + -error handlers: + Defines the behavior for a specific error. + +The filesystem behavior during an error can be set via sysfs files. Each +error handler works independently - the first condition met by an error handler +for a specific class will cause the error to be propagated rather than reset and +retried. + +The action taken by the filesystem when the error is propagated is context +dependent - it may cause a shut down in the case of an unrecoverable error, +it may be reported back to userspace, or it may even be ignored because +there's nothing useful we can with the error or anyone we can report it to (e.g. +during unmount). + +The configuration files are organized into the following hierarchy for each +mounted filesystem: + + /sys/fs/xfs//error/// + +Where: + + The short device name of the mounted filesystem. This is the same device + name that shows up in XFS kernel error messages as "XFS(): ..." + + + The subsystem the error configuration belongs to. As of 4.9, the defined + classes are: + + - "metadata": applies metadata buffer write IO + + + The individual error handler configurations. + + +Each filesystem has "global" error configuration options defined in their top +level directory: + + /sys/fs/xfs//error/ + + fail_at_unmount (Min: 0 Default: 1 Max: 1) + Defines the filesystem error behavior at unmount time. + + If set to a value of 1, XFS will override all other error configurations + during unmount and replace them with "immediate fail" characteristics. + i.e. no retries, no retry timeout. This will always allow unmount to + succeed when there are persistent errors present. + + If set to 0, the configured retry behaviour will continue until all + retries and/or timeouts have been exhausted. This will delay unmount + completion when there are persistent errors, and it may prevent the + filesystem from ever unmounting fully in the case of "retry forever" + handler configurations. + + Note: there is no guarantee that fail_at_unmount can be set whilst an + unmount is in progress. It is possible that the sysfs entries are + removed by the unmounting filesystem before a "retry forever" error + handler configuration causes unmount to hang, and hence the filesystem + must be configured appropriately before unmount begins to prevent + unmount hangs. + +Each filesystem has specific error class handlers that define the error +propagation behaviour for specific errors. There is also a "default" error +handler defined, which defines the behaviour for all errors that don't have +specific handlers defined. Where multiple retry constraints are configuredi for +a single error, the first retry configuration that expires will cause the error +to be propagated. The handler configurations are found in the directory: + + /sys/fs/xfs//error/// + + max_retries (Min: -1 Default: Varies Max: INTMAX) + Defines the allowed number of retries of a specific error before + the filesystem will propagate the error. The retry count for a given + error context (e.g. a specific metadata buffer) is reset every time + there is a successful completion of the operation. + + Setting the value to "-1" will cause XFS to retry forever for this + specific error. + + Setting the value to "0" will cause XFS to fail immediately when the + specific error is reported. + + Setting the value to "N" (where 0 < N < Max) will make XFS retry the + operation "N" times before propagating the error. + + retry_timeout_seconds (Min: -1 Default: Varies Max: 1 day) + Define the amount of time (in seconds) that the filesystem is + allowed to retry its operations when the specific error is + found. + + Setting the value to "-1" will allow XFS to retry forever for this + specific error. + + Setting the value to "0" will cause XFS to fail immediately when the + specific error is reported. + + Setting the value to "N" (where 0 < N < Max) will allow XFS to retry the + operation for up to "N" seconds before propagating the error. + +Note: The default behaviour for a specific error handler is dependent on both +the class and error context. For example, the default values for +"metadata/ENODEV" are "0" rather than "-1" so that this error handler defaults +to "fail immediately" behaviour. This is done because ENODEV is a fatal, +unrecoverable error no matter how many times the metadata IO is retried. diff --git a/Documentation/gcov.txt b/Documentation/gcov.txt deleted file mode 100644 index 7b727783db7e..000000000000 --- a/Documentation/gcov.txt +++ /dev/null @@ -1,257 +0,0 @@ -Using gcov with the Linux kernel -================================ - -1. Introduction -2. Preparation -3. Customization -4. Files -5. Modules -6. Separated build and test machines -7. Troubleshooting -Appendix A: sample script: gather_on_build.sh -Appendix B: sample script: gather_on_test.sh - - -1. Introduction -=============== - -gcov profiling kernel support enables the use of GCC's coverage testing -tool gcov [1] with the Linux kernel. Coverage data of a running kernel -is exported in gcov-compatible format via the "gcov" debugfs directory. -To get coverage data for a specific file, change to the kernel build -directory and use gcov with the -o option as follows (requires root): - -# cd /tmp/linux-out -# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c - -This will create source code files annotated with execution counts -in the current directory. In addition, graphical gcov front-ends such -as lcov [2] can be used to automate the process of collecting data -for the entire kernel and provide coverage overviews in HTML format. - -Possible uses: - -* debugging (has this line been reached at all?) -* test improvement (how do I change my test to cover these lines?) -* minimizing kernel configurations (do I need this option if the - associated code is never run?) - --- - -[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html -[2] http://ltp.sourceforge.net/coverage/lcov.php - - -2. Preparation -============== - -Configure the kernel with: - - CONFIG_DEBUG_FS=y - CONFIG_GCOV_KERNEL=y - -select the gcc's gcov format, default is autodetect based on gcc version: - - CONFIG_GCOV_FORMAT_AUTODETECT=y - -and to get coverage data for the entire kernel: - - CONFIG_GCOV_PROFILE_ALL=y - -Note that kernels compiled with profiling flags will be significantly -larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported -on all architectures. - -Profiling data will only become accessible once debugfs has been -mounted: - - mount -t debugfs none /sys/kernel/debug - - -3. Customization -================ - -To enable profiling for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - - For a single file (e.g. main.o): - GCOV_PROFILE_main.o := y - - For all files in one directory: - GCOV_PROFILE := y - -To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL -is specified, use: - - GCOV_PROFILE_main.o := n - and: - GCOV_PROFILE := n - -Only files which are linked to the main kernel image or are compiled as -kernel modules are supported by this mechanism. - - -4. Files -======== - -The gcov kernel support creates the following files in debugfs: - - /sys/kernel/debug/gcov - Parent directory for all gcov-related files. - - /sys/kernel/debug/gcov/reset - Global reset file: resets all coverage data to zero when - written to. - - /sys/kernel/debug/gcov/path/to/compile/dir/file.gcda - The actual gcov data file as understood by the gcov - tool. Resets file coverage data to zero when written to. - - /sys/kernel/debug/gcov/path/to/compile/dir/file.gcno - Symbolic link to a static data file required by the gcov - tool. This file is generated by gcc when compiling with - option -ftest-coverage. - - -5. Modules -========== - -Kernel modules may contain cleanup code which is only run during -module unload time. The gcov mechanism provides a means to collect -coverage data for such code by keeping a copy of the data associated -with the unloaded module. This data remains available through debugfs. -Once the module is loaded again, the associated coverage counters are -initialized with the data from its previous instantiation. - -This behavior can be deactivated by specifying the gcov_persist kernel -parameter: - - gcov_persist=0 - -At run-time, a user can also choose to discard data for an unloaded -module by writing to its data file or the global reset file. - - -6. Separated build and test machines -==================================== - -The gcov kernel profiling infrastructure is designed to work out-of-the -box for setups where kernels are built and run on the same machine. In -cases where the kernel runs on a separate machine, special preparations -must be made, depending on where the gcov tool is used: - -a) gcov is run on the TEST machine - -The gcov tool version on the test machine must be compatible with the -gcc version used for kernel build. Also the following files need to be -copied from build to test machine: - -from the source tree: - - all C source files + headers - -from the build tree: - - all C source files + headers - - all .gcda and .gcno files - - all links to directories - -It is important to note that these files need to be placed into the -exact same file system location on the test machine as on the build -machine. If any of the path components is symbolic link, the actual -directory needs to be used instead (due to make's CURDIR handling). - -b) gcov is run on the BUILD machine - -The following files need to be copied after each test case from test -to build machine: - -from the gcov directory in sysfs: - - all .gcda files - - all links to .gcno files - -These files can be copied to any location on the build machine. gcov -must then be called with the -o option pointing to that directory. - -Example directory setup on the build machine: - - /tmp/linux: kernel source tree - /tmp/out: kernel build directory as specified by make O= - /tmp/coverage: location of the files copied from the test machine - - [user@build] cd /tmp/out - [user@build] gcov -o /tmp/coverage/tmp/out/init main.c - - -7. Troubleshooting -================== - -Problem: Compilation aborts during linker step. -Cause: Profiling flags are specified for source files which are not - linked to the main kernel or which are linked by a custom - linker procedure. -Solution: Exclude affected source files from profiling by specifying - GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the - corresponding Makefile. - -Problem: Files copied from sysfs appear empty or incomplete. -Cause: Due to the way seq_file works, some tools such as cp or tar - may not correctly copy files from sysfs. -Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links. - Alternatively use the mechanism shown in Appendix B. - - -Appendix A: gather_on_build.sh -============================== - -Sample script to gather coverage meta files on the build machine -(see 6a): -#!/bin/bash - -KSRC=$1 -KOBJ=$2 -DEST=$3 - -if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then - echo "Usage: $0 " >&2 - exit 1 -fi - -KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) -KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) - -find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ - -perm /u+r,g+r | tar cfz $DEST -P -T - - -if [ $? -eq 0 ] ; then - echo "$DEST successfully created, copy to test system and unpack with:" - echo " tar xfz $DEST -P" -else - echo "Could not create file $DEST" -fi - - -Appendix B: gather_on_test.sh -============================= - -Sample script to gather coverage data files on the test machine -(see 6b): - -#!/bin/bash -e - -DEST=$1 -GCDA=/sys/kernel/debug/gcov - -if [ -z "$DEST" ] ; then - echo "Usage: $0 " >&2 - exit 1 -fi - -TEMPDIR=$(mktemp -d) -echo Collecting data.. -find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; -find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; -find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; -tar czf $DEST -C $TEMPDIR sys -rm -rf $TEMPDIR - -echo "$DEST successfully created, copy to build system and unpack with:" -echo " tar xfz $DEST" diff --git a/Documentation/gdb-kernel-debugging.txt b/Documentation/gdb-kernel-debugging.txt deleted file mode 100644 index 7050ce8794b9..000000000000 --- a/Documentation/gdb-kernel-debugging.txt +++ /dev/null @@ -1,160 +0,0 @@ -Debugging kernel and modules via gdb -==================================== - -The kernel debugger kgdb, hypervisors like QEMU or JTAG-based hardware -interfaces allow to debug the Linux kernel and its modules during runtime -using gdb. Gdb comes with a powerful scripting interface for python. The -kernel provides a collection of helper scripts that can simplify typical -kernel debugging steps. This is a short tutorial about how to enable and use -them. It focuses on QEMU/KVM virtual machines as target, but the examples can -be transferred to the other gdb stubs as well. - - -Requirements ------------- - - o gdb 7.2+ (recommended: 7.4+) with python support enabled (typically true - for distributions) - - -Setup ------ - - o Create a virtual Linux machine for QEMU/KVM (see www.linux-kvm.org and - www.qemu.org for more details). For cross-development, - http://landley.net/aboriginal/bin keeps a pool of machine images and - toolchains that can be helpful to start from. - - o Build the kernel with CONFIG_GDB_SCRIPTS enabled, but leave - CONFIG_DEBUG_INFO_REDUCED off. If your architecture supports - CONFIG_FRAME_POINTER, keep it enabled. - - o Install that kernel on the guest. - - Alternatively, QEMU allows to boot the kernel directly using -kernel, - -append, -initrd command line switches. This is generally only useful if - you do not depend on modules. See QEMU documentation for more details on - this mode. - - o Enable the gdb stub of QEMU/KVM, either - - at VM startup time by appending "-s" to the QEMU command line - or - - during runtime by issuing "gdbserver" from the QEMU monitor - console - - o cd /path/to/linux-build - - o Start gdb: gdb vmlinux - - Note: Some distros may restrict auto-loading of gdb scripts to known safe - directories. In case gdb reports to refuse loading vmlinux-gdb.py, add - - add-auto-load-safe-path /path/to/linux-build - - to ~/.gdbinit. See gdb help for more details. - - o Attach to the booted guest: - (gdb) target remote :1234 - - -Examples of using the Linux-provided gdb helpers ------------------------------------------------- - - o Load module (and main kernel) symbols: - (gdb) lx-symbols - loading vmlinux - scanning for modules in /home/user/linux/build - loading @0xffffffffa0020000: /home/user/linux/build/net/netfilter/xt_tcpudp.ko - loading @0xffffffffa0016000: /home/user/linux/build/net/netfilter/xt_pkttype.ko - loading @0xffffffffa0002000: /home/user/linux/build/net/netfilter/xt_limit.ko - loading @0xffffffffa00ca000: /home/user/linux/build/net/packet/af_packet.ko - loading @0xffffffffa003c000: /home/user/linux/build/fs/fuse/fuse.ko - ... - loading @0xffffffffa0000000: /home/user/linux/build/drivers/ata/ata_generic.ko - - o Set a breakpoint on some not yet loaded module function, e.g.: - (gdb) b btrfs_init_sysfs - Function "btrfs_init_sysfs" not defined. - Make breakpoint pending on future shared library load? (y or [n]) y - Breakpoint 1 (btrfs_init_sysfs) pending. - - o Continue the target - (gdb) c - - o Load the module on the target and watch the symbols being loaded as well as - the breakpoint hit: - loading @0xffffffffa0034000: /home/user/linux/build/lib/libcrc32c.ko - loading @0xffffffffa0050000: /home/user/linux/build/lib/lzo/lzo_compress.ko - loading @0xffffffffa006e000: /home/user/linux/build/lib/zlib_deflate/zlib_deflate.ko - loading @0xffffffffa01b1000: /home/user/linux/build/fs/btrfs/btrfs.ko - - Breakpoint 1, btrfs_init_sysfs () at /home/user/linux/fs/btrfs/sysfs.c:36 - 36 btrfs_kset = kset_create_and_add("btrfs", NULL, fs_kobj); - - o Dump the log buffer of the target kernel: - (gdb) lx-dmesg - [ 0.000000] Initializing cgroup subsys cpuset - [ 0.000000] Initializing cgroup subsys cpu - [ 0.000000] Linux version 3.8.0-rc4-dbg+ (... - [ 0.000000] Command line: root=/dev/sda2 resume=/dev/sda1 vga=0x314 - [ 0.000000] e820: BIOS-provided physical RAM map: - [ 0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable - [ 0.000000] BIOS-e820: [mem 0x000000000009fc00-0x000000000009ffff] reserved - .... - - o Examine fields of the current task struct: - (gdb) p $lx_current().pid - $1 = 4998 - (gdb) p $lx_current().comm - $2 = "modprobe\000\000\000\000\000\000\000" - - o Make use of the per-cpu function for the current or a specified CPU: - (gdb) p $lx_per_cpu("runqueues").nr_running - $3 = 1 - (gdb) p $lx_per_cpu("runqueues", 2).nr_running - $4 = 0 - - o Dig into hrtimers using the container_of helper: - (gdb) set $next = $lx_per_cpu("hrtimer_bases").clock_base[0].active.next - (gdb) p *$container_of($next, "struct hrtimer", "node") - $5 = { - node = { - node = { - __rb_parent_color = 18446612133355256072, - rb_right = 0x0 , - rb_left = 0x0 - }, - expires = { - tv64 = 1835268000000 - } - }, - _softexpires = { - tv64 = 1835268000000 - }, - function = 0xffffffff81078232 , - base = 0xffff88003fd0d6f0, - state = 1, - start_pid = 0, - start_site = 0xffffffff81055c1f , - start_comm = "swapper/2\000\000\000\000\000\000" - } - - -List of commands and functions ------------------------------- - -The number of commands and convenience functions may evolve over the time, -this is just a snapshot of the initial version: - - (gdb) apropos lx - function lx_current -- Return current task - function lx_module -- Find module by name and return the module variable - function lx_per_cpu -- Return per-cpu variable - function lx_task_by_pid -- Find Linux task by PID and return the task_struct variable - function lx_thread_info -- Calculate Linux thread_info from task variable - lx-dmesg -- Print Linux kernel log buffer - lx-lsmod -- List currently loaded modules - lx-symbols -- (Re-)load symbols of Linux kernel and currently loaded modules - -Detailed help can be obtained via "help " for commands and "help -function " for convenience functions. diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt index 86d3fa95fd12..40884c4fe40c 100644 --- a/Documentation/gpio/board.txt +++ b/Documentation/gpio/board.txt @@ -8,9 +8,9 @@ gpio-legacy.txt (actually, there is no real mapping possible with the old interface; you just fetch an integer from somewhere and request the corresponding GPIO. -Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage -is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in -their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to +All platforms can enable the GPIO library, but if the platform strictly +requires GPIO functionality to be present, it needs to select GPIOLIB from its +Kconfig. Then, how GPIOs are mapped depends on what the platform uses to describe its hardware layout. Currently, mappings can be defined through device tree, ACPI, and platform data. diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 6cb35a78eff4..368d5a294d89 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -262,6 +262,12 @@ symbol: to the container using container_of(). (See Documentation/driver-model/design-patterns.txt) + If there is a need to exclude certain GPIOs from the IRQ domain, one can + set .irq_need_valid_mask of the gpiochip before gpiochip_add_data() is + called. This allocates .irq_valid_mask with as many bits set as there are + GPIOs in the chip. Drivers can exclude GPIOs by clearing bits from this + mask. The mask must be filled in before gpiochip_irqchip_add() is called. + * gpiochip_set_chained_irqchip(): sets up a chained irq handler for a gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler data. (Notice handler data, since the irqchip data is likely used by the diff --git a/Documentation/gpio/gpio-legacy.txt b/Documentation/gpio/gpio-legacy.txt index 79ab5648d69b..b34fd94f7089 100644 --- a/Documentation/gpio/gpio-legacy.txt +++ b/Documentation/gpio/gpio-legacy.txt @@ -72,8 +72,8 @@ in this document, but drivers acting as clients to the GPIO interface must not care how it's implemented.) That said, if the convention is supported on their platform, drivers should -use it when possible. Platforms must select ARCH_REQUIRE_GPIOLIB or -ARCH_WANT_OPTIONAL_GPIOLIB in their Kconfig. Drivers that can't work without +use it when possible. Platforms must select GPIOLIB if GPIO functionality +is strictly required. Drivers that can't work without standard GPIO calls should have Kconfig entries which depend on GPIOLIB. The GPIO calls are available, either as "real code" or as optimized-away stubs, when drivers use the include file: @@ -553,22 +553,14 @@ either NULL or the label associated with that GPIO when it was requested. Platform Support ---------------- -To support this framework, a platform's Kconfig will "select" either -ARCH_REQUIRE_GPIOLIB or ARCH_WANT_OPTIONAL_GPIOLIB -and arrange that its includes and defines -three functions: gpio_get_value(), gpio_set_value(), and gpio_cansleep(). +To force-enable this framework, a platform's Kconfig will "select" GPIOLIB, +else it is up to the user to configure support for GPIO. It may also provide a custom value for ARCH_NR_GPIOS, so that it better reflects the number of GPIOs in actual use on that platform, without wasting static table space. (It should count both built-in/SoC GPIOs and also ones on GPIO expanders. -ARCH_REQUIRE_GPIOLIB means that the gpiolib code will always get compiled -into the kernel on that architecture. - -ARCH_WANT_OPTIONAL_GPIOLIB means the gpiolib code defaults to off and the user -can enable it and build it into the kernel optionally. - If neither of these options are selected, the platform does not support GPIOs through GPIO-lib and the code cannot be enabled by the user. diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py new file mode 100644 index 000000000000..6314d1708230 --- /dev/null +++ b/Documentation/gpu/conf.py @@ -0,0 +1,5 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Linux GPU Driver Developer's Guide" + +tags.add("subproject") diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 3bb26135971f..37284bcc7764 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -53,9 +53,12 @@ u32 driver_features; DRIVER_USE_AGP Driver uses AGP interface, the DRM core will manage AGP resources. -DRIVER_REQUIRE_AGP - Driver needs AGP interface to function. AGP initialization failure - will become a fatal error. +DRIVER_LEGACY + Denote a legacy driver using shadow attach. Don't use. + +DRIVER_KMS_LEGACY_CONTEXT + Used only by nouveau for backwards compatibility with existing userspace. + Don't use. DRIVER_PCI_DMA Driver is capable of PCI DMA, mapping of PCI DMA buffers to diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 0b302fedf1af..bb4254d19cbb 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -2,38 +2,45 @@ Mode Setting Helper Functions ============================= -The plane, CRTC, encoder and connector functions provided by the drivers -implement the DRM API. They're called by the DRM core and ioctl handlers -to handle device state changes and configuration request. As -implementing those functions often requires logic not specific to -drivers, mid-layer helper functions are available to avoid duplicating -boilerplate code. - -The DRM core contains one mid-layer implementation. The mid-layer -provides implementations of several plane, CRTC, encoder and connector -functions (called from the top of the mid-layer) that pre-process -requests and call lower-level functions provided by the driver (at the -bottom of the mid-layer). For instance, the -:c:func:`drm_crtc_helper_set_config()` function can be used to -fill the :c:type:`struct drm_crtc_funcs ` -set_config field. When called, it will split the set_config operation -in smaller, simpler operations and call the driver to handle them. - -To use the mid-layer, drivers call -:c:func:`drm_crtc_helper_add()`, -:c:func:`drm_encoder_helper_add()` and -:c:func:`drm_connector_helper_add()` functions to install their -mid-layer bottom operations handlers, and fill the :c:type:`struct -drm_crtc_funcs `, :c:type:`struct -drm_encoder_funcs ` and :c:type:`struct -drm_connector_funcs ` structures with -pointers to the mid-layer top API functions. Installing the mid-layer -bottom operation handlers is best done right after registering the -corresponding KMS object. - -The mid-layer is not split between CRTC, encoder and connector -operations. To use it, a driver must provide bottom functions for all of -the three KMS entities. +The DRM subsystem aims for a strong separation between core code and helper +libraries. Core code takes care of general setup and teardown and decoding +userspace requests to kernel internal objects. Everything else is handled by a +large set of helper libraries, which can be combined freely to pick and choose +for each driver what fits, and avoid shared code where special behaviour is +needed. + +This distinction between core code and helpers is especially strong in the +modesetting code, where there's a shared userspace ABI for all drivers. This is +in contrast to the render side, where pretty much everything (with very few +exceptions) can be considered optional helper code. + +There are a few areas these helpers can grouped into: + +* Helpers to implement modesetting. The important ones here are the atomic + helpers. Old drivers still often use the legacy CRTC helpers. They both share + the same set of common helper vtables. For really simple drivers (anything + that would have been a great fit in the deprecated fbdev subsystem) there's + also the simple display pipe helpers. + +* There's a big pile of helpers for handling outputs. First the generic bridge + helpers for handling encoder and transcoder IP blocks. Second the panel helpers + for handling panel-related information and logic. Plus then a big set of + helpers for the various sink standards (DisplayPort, HDMI, MIPI DSI). Finally + there's also generic helpers for handling output probing, and for dealing with + EDIDs. + +* The last group of helpers concerns itself with the frontend side of a display + pipeline: Planes, handling rectangles for visibility checking and scissoring, + flip queues and assorted bits. + +Modeset Helper Reference for Common Vtables +=========================================== + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :internal: + +.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h + :doc: overview Atomic Modeset Helper Functions Reference ========================================= @@ -62,33 +69,27 @@ Atomic State Reset and Initialization .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :export: -Modeset Helper Reference for Common Vtables -=========================================== - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :internal: - -.. kernel-doc:: include/drm/drm_modeset_helper_vtables.h - :doc: overview - Legacy CRTC/Modeset Helper Functions Reference ============================================== .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :export: + :doc: overview .. kernel-doc:: drivers/gpu/drm/drm_crtc_helper.c - :doc: overview + :export: -Output Probing Helper Functions Reference -========================================= +Simple KMS Helper Reference +=========================== -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c - :doc: output probing helper overview +.. kernel-doc:: include/drm/drm_simple_kms_helper.h + :internal: -.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c :export: +.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c + :doc: overview + fbdev Helper Functions Reference ================================ @@ -110,6 +111,43 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: +Bridges +======= + +Overview +-------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: overview + +Default bridge callback sequence +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge callbacks + + +Bridge Helper Reference +------------------------- + +.. kernel-doc:: include/drm/drm_bridge.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :export: + +Panel Helper Reference +====================== + +.. kernel-doc:: include/drm/drm_panel.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :export: + +.. kernel-doc:: drivers/gpu/drm/drm_panel.c + :doc: drm panel + Display Port Helper Functions Reference ======================================= @@ -158,9 +196,21 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c :export: +Output Probing Helper Functions Reference +========================================= + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :doc: output probing helper overview + +.. kernel-doc:: drivers/gpu/drm/drm_probe_helper.c + :export: + EDID Helper Functions Reference =============================== +.. kernel-doc:: include/drm/drm_edid.h + :internal: + .. kernel-doc:: drivers/gpu/drm/drm_edid.c :export: @@ -176,18 +226,6 @@ Rectangle Utilities Reference .. kernel-doc:: drivers/gpu/drm/drm_rect.c :export: -Flip-work Helper Reference -========================== - -.. kernel-doc:: include/drm/drm_flip_work.h - :doc: flip utils - -.. kernel-doc:: include/drm/drm_flip_work.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c - :export: - HDMI Infoframes Helper Reference ================================ @@ -202,59 +240,40 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: -Plane Helper Reference -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :export: - -.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c - :doc: overview +Flip-work Helper Reference +========================== -Tile group ----------- +.. kernel-doc:: include/drm/drm_flip_work.h + :doc: flip utils -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :doc: Tile group +.. kernel-doc:: include/drm/drm_flip_work.h + :internal: -Bridges -======= +.. kernel-doc:: drivers/gpu/drm/drm_flip_work.c + :export: -Overview --------- +Plane Helper Reference +====================== -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :doc: overview -Default bridge callback sequence --------------------------------- - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c - :doc: bridge callbacks - -.. kernel-doc:: drivers/gpu/drm/drm_bridge.c +.. kernel-doc:: drivers/gpu/drm/drm_plane_helper.c :export: -Panel Helper Reference -====================== - -.. kernel-doc:: include/drm/drm_panel.h - :internal: +Tile group +========== -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :export: +# FIXME: This should probably be moved into a property documentation section -.. kernel-doc:: drivers/gpu/drm/drm_panel.c - :doc: drm panel +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :doc: Tile group -Simple KMS Helper Reference -=========================== +Auxiliary Modeset Helpers +========================= -.. kernel-doc:: include/drm/drm_simple_kms_helper.h - :internal: +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c + :doc: aux kms helpers -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_modeset_helper.c :export: - -.. kernel-doc:: drivers/gpu/drm/drm_simple_kms_helper.c - :doc: overview diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 8dfa4b214b96..53b872c105d2 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -2,9 +2,6 @@ Kernel Mode Setting (KMS) ========================= -Mode Setting -============ - Drivers must initialize the mode setting core by calling :c:func:`drm_mode_config_init()` on the DRM device. The function initializes the :c:type:`struct drm_device ` @@ -18,60 +15,59 @@ be setup by initializing the following fields. - struct drm_mode_config_funcs \*funcs; Mode setting functions. -Display Modes Function Reference --------------------------------- +Modeset Base Object Abstraction +=============================== -.. kernel-doc:: include/drm/drm_modes.h +.. kernel-doc:: include/drm/drm_mode_object.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_modes.c +.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c + :export: + +KMS Data Structures +=================== + +.. kernel-doc:: include/drm/drm_crtc.h + :internal: + +KMS API Functions +================= + +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c :export: Atomic Mode Setting Function Reference --------------------------------------- +====================================== .. kernel-doc:: drivers/gpu/drm/drm_atomic.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c +.. kernel-doc:: include/drm/drm_atomic.h :internal: Frame Buffer Abstraction ------------------------- - -Frame buffers are abstract memory objects that provide a source of -pixels to scanout to a CRTC. Applications explicitly request the -creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls -and receive an opaque handle that can be passed to the KMS CRTC control, -plane configuration and page flip functions. - -Frame buffers rely on the underneath memory manager for low-level memory -operations. When creating a frame buffer applications pass a memory -handle (or a list of memory handles for multi-planar formats) through -the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their -userspace buffer management interface this would be a GEM handle. -Drivers are however free to use their own backing storage object -handles, e.g. vmwgfx directly exposes special TTM handles to userspace -and so expects TTM handles in the create ioctl and not GEM handles. - -The lifetime of a drm framebuffer is controlled with a reference count, -drivers can grab additional references with -:c:func:`drm_framebuffer_reference()`and drop them again with -:c:func:`drm_framebuffer_unreference()`. For driver-private -framebuffers for which the last reference is never dropped (e.g. for the -fbdev framebuffer when the struct :c:type:`struct drm_framebuffer -` is embedded into the fbdev helper struct) -drivers can manually clean up a framebuffer at module unload time with -:c:func:`drm_framebuffer_unregister_private()`. +======================== + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :doc: overview + +Frame Buffer Functions Reference +-------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c + :export: + +.. kernel-doc:: include/drm/drm_framebuffer.h + :internal: DRM Format Handling -------------------- +=================== .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export: Dumb Buffer Objects -------------------- +=================== The KMS API doesn't standardize backing storage object creation and leaves it to driver-specific ioctls. Furthermore actually creating a @@ -114,14 +110,59 @@ Note that dumb objects may not be used for gpu acceleration, as has been attempted on some ARM embedded platforms. Such drivers really must have a hardware-specific ioctl to allocate suitable buffer objects. -Output Polling --------------- +Plane Abstraction +================= + +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :doc: overview + +Plane Functions Reference +------------------------- + +.. kernel-doc:: include/drm/drm_plane.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_plane.c + :export: + +Display Modes Function Reference +================================ + +.. kernel-doc:: include/drm/drm_modes.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_modes.c + :export: -void (\*output_poll_changed)(struct drm_device \*dev); -This operation notifies the driver that the status of one or more -connectors has changed. Drivers that use the fb helper can just call the -:c:func:`drm_fb_helper_hotplug_event()` function to handle this -operation. +Connector Abstraction +===================== + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :doc: overview + +Connector Functions Reference +----------------------------- + +.. kernel-doc:: include/drm/drm_connector.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :export: + +Encoder Abstraction +=================== + +.. kernel-doc:: drivers/gpu/drm/drm_encoder.c + :doc: overview + +Encoder Functions Reference +--------------------------- + +.. kernel-doc:: include/drm/drm_encoder.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_encoder.c + :export: KMS Initialization and Cleanup ============================== @@ -151,250 +192,6 @@ allocated and zeroed by the driver, possibly as part of a larger structure, and registered with a call to :c:func:`drm_crtc_init()` with a pointer to CRTC functions. -Planes (:c:type:`struct drm_plane `) ------------------------------------------------ - -A plane represents an image source that can be blended with or overlayed -on top of a CRTC during the scanout process. Planes are associated with -a frame buffer to crop a portion of the image memory (source) and -optionally scale it to a destination size. The result is then blended -with or overlayed on top of a CRTC. - -The DRM core recognizes three types of planes: - -- DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. - Primary planes are the planes operated upon by CRTC modesetting and - flipping operations described in the page_flip hook in - :c:type:`struct drm_crtc_funcs `. -- DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. - Cursor planes are the planes operated upon by the - DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls. -- DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor - planes. Some drivers refer to these types of planes as "sprites" - internally. - -For compatibility with legacy userspace, only overlay planes are made -available to userspace by default. Userspace clients may set the -DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate -that they wish to receive a universal plane list containing all plane -types. - -Plane Initialization -~~~~~~~~~~~~~~~~~~~~ - -To create a plane, a KMS drivers allocates and zeroes an instances of -:c:type:`struct drm_plane ` (possibly as part of a -larger structure) and registers it with a call to -:c:func:`drm_universal_plane_init()`. The function takes a -bitmask of the CRTCs that can be associated with the plane, a pointer to -the plane functions, a list of format supported formats, and the type of -plane (primary, cursor, or overlay) being initialized. - -Cursor and overlay planes are optional. All drivers should provide one -primary plane per CRTC (although this requirement may change in the -future); drivers that do not wish to provide special handling for -primary planes may make use of the helper functions described in ? to -create and register a primary plane with standard capabilities. - -Encoders (:c:type:`struct drm_encoder `) ------------------------------------------------------ - -An encoder takes pixel data from a CRTC and converts it to a format -suitable for any attached connectors. On some devices, it may be -possible to have a CRTC send data to more than one encoder. In that -case, both encoders would receive data from the same scanout buffer, -resulting in a "cloned" display configuration across the connectors -attached to each encoder. - -Encoder Initialization -~~~~~~~~~~~~~~~~~~~~~~ - -As for CRTCs, a KMS driver must create, initialize and register at least -one :c:type:`struct drm_encoder ` instance. The -instance is allocated and zeroed by the driver, possibly as part of a -larger structure. - -Drivers must initialize the :c:type:`struct drm_encoder -` possible_crtcs and possible_clones fields before -registering the encoder. Both fields are bitmasks of respectively the -CRTCs that the encoder can be connected to, and sibling encoders -candidate for cloning. - -After being initialized, the encoder must be registered with a call to -:c:func:`drm_encoder_init()`. The function takes a pointer to the -encoder functions and an encoder type. Supported types are - -- DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A -- DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort -- DRM_MODE_ENCODER_LVDS for display panels -- DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, - Component, SCART) -- DRM_MODE_ENCODER_VIRTUAL for virtual machine displays - -Encoders must be attached to a CRTC to be used. DRM drivers leave -encoders unattached at initialization time. Applications (or the fbdev -compatibility layer when implemented) are responsible for attaching the -encoders they want to use to a CRTC. - -Connectors (:c:type:`struct drm_connector `) ------------------------------------------------------------ - -A connector is the final destination for pixel data on a device, and -usually connects directly to an external display device like a monitor -or laptop panel. A connector can only be attached to one encoder at a -time. The connector is also the structure where information about the -attached display is kept, so it contains fields for display data, EDID -data, DPMS & connection status, and information about modes supported on -the attached displays. - -Connector Initialization -~~~~~~~~~~~~~~~~~~~~~~~~ - -Finally a KMS driver must create, initialize, register and attach at -least one :c:type:`struct drm_connector ` -instance. The instance is created as other KMS objects and initialized -by setting the following fields. - -interlace_allowed - Whether the connector can handle interlaced modes. - -doublescan_allowed - Whether the connector can handle doublescan. - -display_info - Display information is filled from EDID information when a display - is detected. For non hot-pluggable displays such as flat panels in - embedded systems, the driver should initialize the - display_info.width_mm and display_info.height_mm fields with the - physical size of the display. - -polled - Connector polling mode, a combination of - - DRM_CONNECTOR_POLL_HPD - The connector generates hotplug events and doesn't need to be - periodically polled. The CONNECT and DISCONNECT flags must not - be set together with the HPD flag. - - DRM_CONNECTOR_POLL_CONNECT - Periodically poll the connector for connection. - - DRM_CONNECTOR_POLL_DISCONNECT - Periodically poll the connector for disconnection. - - Set to 0 for connectors that don't support connection status - discovery. - -The connector is then registered with a call to -:c:func:`drm_connector_init()` with a pointer to the connector -functions and a connector type, and exposed through sysfs with a call to -:c:func:`drm_connector_register()`. - -Supported connector types are - -- DRM_MODE_CONNECTOR_VGA -- DRM_MODE_CONNECTOR_DVII -- DRM_MODE_CONNECTOR_DVID -- DRM_MODE_CONNECTOR_DVIA -- DRM_MODE_CONNECTOR_Composite -- DRM_MODE_CONNECTOR_SVIDEO -- DRM_MODE_CONNECTOR_LVDS -- DRM_MODE_CONNECTOR_Component -- DRM_MODE_CONNECTOR_9PinDIN -- DRM_MODE_CONNECTOR_DisplayPort -- DRM_MODE_CONNECTOR_HDMIA -- DRM_MODE_CONNECTOR_HDMIB -- DRM_MODE_CONNECTOR_TV -- DRM_MODE_CONNECTOR_eDP -- DRM_MODE_CONNECTOR_VIRTUAL - -Connectors must be attached to an encoder to be used. For devices that -map connectors to encoders 1:1, the connector should be attached at -initialization time with a call to -:c:func:`drm_mode_connector_attach_encoder()`. The driver must -also set the :c:type:`struct drm_connector ` -encoder field to point to the attached encoder. - -Finally, drivers must initialize the connectors state change detection -with a call to :c:func:`drm_kms_helper_poll_init()`. If at least -one connector is pollable but can't generate hotplug interrupts -(indicated by the DRM_CONNECTOR_POLL_CONNECT and -DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will -automatically be queued to periodically poll for changes. Connectors -that can generate hotplug interrupts must be marked with the -DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must -call :c:func:`drm_helper_hpd_irq_event()`. The function will -queue a delayed work to check the state of all connectors, but no -periodic polling will be done. - -Connector Operations -~~~~~~~~~~~~~~~~~~~~ - - **Note** - - Unless otherwise state, all operations are mandatory. - -DPMS -'''' - -void (\*dpms)(struct drm_connector \*connector, int mode); -The DPMS operation sets the power state of a connector. The mode -argument is one of - -- DRM_MODE_DPMS_ON - -- DRM_MODE_DPMS_STANDBY - -- DRM_MODE_DPMS_SUSPEND - -- DRM_MODE_DPMS_OFF - -In all but DPMS_ON mode the encoder to which the connector is attached -should put the display in low-power mode by driving its signals -appropriately. If more than one connector is attached to the encoder -care should be taken not to change the power state of other displays as -a side effect. Low-power mode should be propagated to the encoders and -CRTCs when all related connectors are put in low-power mode. - -Modes -''''' - -int (\*fill_modes)(struct drm_connector \*connector, uint32_t -max_width, uint32_t max_height); -Fill the mode list with all supported modes for the connector. If the -``max_width`` and ``max_height`` arguments are non-zero, the -implementation must ignore all modes wider than ``max_width`` or higher -than ``max_height``. - -The connector must also fill in this operation its display_info -width_mm and height_mm fields with the connected display physical size -in millimeters. The fields should be set to 0 if the value isn't known -or is not applicable (for instance for projector devices). - -Connection Status -''''''''''''''''' - -The connection status is updated through polling or hotplug events when -supported (see ?). The status value is reported to userspace through -ioctls and must not be used inside the driver, as it only gets -initialized by a call to :c:func:`drm_mode_getconnector()` from -userspace. - -enum drm_connector_status (\*detect)(struct drm_connector -\*connector, bool force); -Check to see if anything is attached to the connector. The ``force`` -parameter is set to false whilst polling or to true when checking the -connector due to user request. ``force`` can be used by the driver to -avoid expensive, destructive operations during automated probing. - -Return connector_status_connected if something is connected to the -connector, connector_status_disconnected if nothing is connected and -connector_status_unknown if the connection state isn't known. - -Drivers should only return connector_status_connected if the -connection status has really been probed as connected. Connectors that -can't detect the connection status, or failed connection status probes, -should return connector_status_unknown. Cleanup ------- @@ -463,20 +260,8 @@ created for fetching EDID data and performing monitor detection. Once the process is complete, the new connector is registered with sysfs to make its properties available to applications. -KMS API Functions ------------------ - -.. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :export: - -KMS Data Structures -------------------- - -.. kernel-doc:: include/drm/drm_crtc.h - :internal: - KMS Locking ------------ +=========== .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c :doc: kms locking @@ -490,90 +275,38 @@ KMS Locking KMS Properties ============== -Drivers may need to expose additional parameters to applications than -those described in the previous sections. KMS supports attaching -properties to CRTCs, connectors and planes and offers a userspace API to -list, get and set the property values. - -Properties are identified by a name that uniquely defines the property -purpose, and store an associated value. For all property types except -blob properties the value is a 64-bit unsigned integer. - -KMS differentiates between properties and property instances. Drivers -first create properties and then create and associate individual -instances of those properties to objects. A property can be instantiated -multiple times and associated with different objects. Values are stored -in property instances, and all other property information are stored in -the property and shared between all instances of the property. - -Every property is created with a type that influences how the KMS core -handles the property. Supported property types are - -DRM_MODE_PROP_RANGE - Range properties report their minimum and maximum admissible values. - The KMS core verifies that values set by application fit in that - range. - -DRM_MODE_PROP_ENUM - Enumerated properties take a numerical value that ranges from 0 to - the number of enumerated values defined by the property minus one, - and associate a free-formed string name to each value. Applications - can retrieve the list of defined value-name pairs and use the - numerical value to get and set property instance values. - -DRM_MODE_PROP_BITMASK - Bitmask properties are enumeration properties that additionally - restrict all enumerated values to the 0..63 range. Bitmask property - instance values combine one or more of the enumerated bits defined - by the property. - -DRM_MODE_PROP_BLOB - Blob properties store a binary blob without any format restriction. - The binary blobs are created as KMS standalone objects, and blob - property instance values store the ID of their associated blob - object. - - Blob properties are only used for the connector EDID property and - cannot be created by drivers. - -To create a property drivers call one of the following functions -depending on the property type. All property creation functions take -property flags and name, as well as type-specific arguments. - -- struct drm_property \*drm_property_create_range(struct - drm_device \*dev, int flags, const char \*name, uint64_t min, - uint64_t max); - Create a range property with the given minimum and maximum values. - -- struct drm_property \*drm_property_create_enum(struct drm_device - \*dev, int flags, const char \*name, const struct - drm_prop_enum_list \*props, int num_values); - Create an enumerated property. The ``props`` argument points to an - array of ``num_values`` value-name pairs. - -- struct drm_property \*drm_property_create_bitmask(struct - drm_device \*dev, int flags, const char \*name, const struct - drm_prop_enum_list \*props, int num_values); - Create a bitmask property. The ``props`` argument points to an array - of ``num_values`` value-name pairs. - -Properties can additionally be created as immutable, in which case they -will be read-only for applications but can be modified by the driver. To -create an immutable property drivers must set the -DRM_MODE_PROP_IMMUTABLE flag at property creation time. - -When no array of value-name pairs is readily available at property -creation time for enumerated or range properties, drivers can create the -property using the :c:func:`drm_property_create()` function and -manually add enumeration value-name pairs by calling the -:c:func:`drm_property_add_enum()` function. Care must be taken to -properly specify the property type through the ``flags`` argument. - -After creating properties drivers can attach property instances to CRTC, -connector and plane objects by calling the -:c:func:`drm_object_attach_property()`. The function takes a -pointer to the target object, a pointer to the previously created -property and an initial instance value. +Property Types and Blob Property Support +---------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_property.c + :doc: overview + +.. kernel-doc:: include/drm/drm_property.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_property.c + :export: + +Plane Composition Properties +---------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_blend.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_blend.c + :export: + +Color Management Properties +--------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c + :doc: overview + +.. kernel-doc:: include/drm/drm_color_mgmt.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c + :export: Existing KMS Properties ----------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 59f9822fecd0..bca808535dfd 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -26,12 +26,12 @@ TTM, but has no video RAM management capabilities and is thus limited to UMA devices. The Translation Table Manager (TTM) ------------------------------------ +=================================== TTM design background and information belongs here. TTM initialization -~~~~~~~~~~~~~~~~~~ +------------------ **Warning** @@ -77,7 +77,7 @@ object, ttm_global_item_ref() is used to create an initial reference count for the TTM, which will call your initialization function. The Graphics Execution Manager (GEM) ------------------------------------- +==================================== The GEM design approach has resulted in a memory manager that doesn't provide full coverage of all (or even all common) use cases in its @@ -114,7 +114,7 @@ read & write, mapping, and domain ownership transfers are left to driver-specific ioctls. GEM Initialization -~~~~~~~~~~~~~~~~~~ +------------------ Drivers that use GEM must set the DRIVER_GEM bit in the struct :c:type:`struct drm_driver ` driver_features @@ -132,7 +132,7 @@ typically not managed by GEM, and must be initialized separately into its own DRM MM object. GEM Objects Creation -~~~~~~~~~~~~~~~~~~~~ +-------------------- GEM splits creation of GEM objects and allocation of the memory that backs them in two distinct operations. @@ -173,7 +173,7 @@ a call to :c:func:`drm_gem_private_object_init()` instead of must be managed by drivers. GEM Objects Lifetime -~~~~~~~~~~~~~~~~~~~~ +-------------------- All GEM objects are reference-counted by the GEM core. References can be acquired and release by :c:func:`calling @@ -196,7 +196,7 @@ resources created by the GEM core, which need to be released with :c:func:`drm_gem_object_release()`. GEM Objects Naming -~~~~~~~~~~~~~~~~~~ +------------------ Communication between userspace and the kernel refers to GEM objects using local handles, global names or, more recently, file descriptors. @@ -245,7 +245,7 @@ Furthermore PRIME also allows cross-device buffer sharing since it is based on dma-bufs. GEM Objects Mapping -~~~~~~~~~~~~~~~~~~~ +------------------- Because mapping operations are fairly heavyweight GEM favours read/write-like access to buffers, implemented through driver-specific @@ -304,7 +304,7 @@ Drivers that want to map the GEM object upfront instead of handling page faults can implement their own mmap file operation handler. Memory Coherency -~~~~~~~~~~~~~~~~ +---------------- When mapped to the device or used in a command buffer, backing pages for an object are flushed to memory and marked write combined so as to be @@ -320,7 +320,7 @@ blocks the client and waits for rendering to complete before performing any necessary flushing operations). Command Execution -~~~~~~~~~~~~~~~~~ +----------------- Perhaps the most important GEM function for GPU devices is providing a command execution interface to clients. Client programs construct @@ -348,8 +348,20 @@ GEM Function Reference .. kernel-doc:: include/drm/drm_gem.h :internal: +GEM CMA Helper Functions Reference +---------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c + :doc: cma helpers + +.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c + :export: + +.. kernel-doc:: include/drm/drm_gem_cma_helper.h + :internal: + VMA Offset Manager ------------------- +================== .. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c :doc: vma offset manager @@ -361,14 +373,14 @@ VMA Offset Manager :internal: PRIME Buffer Sharing --------------------- +==================== PRIME is the cross device buffer sharing framework in drm, originally created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME buffers are dma-buf based file descriptors. Overview and Driver Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- Similar to GEM global names, PRIME file descriptors are also used to share buffer objects across processes. They offer additional security: @@ -406,7 +418,7 @@ struct drm_gem_object \*obj, int flags); struct drm_gem_object \* support PRIME. PRIME Helper Functions -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. kernel-doc:: drivers/gpu/drm/drm_prime.c :doc: PRIME Helpers @@ -418,16 +430,16 @@ PRIME Function References :export: DRM MM Range Allocator ----------------------- +====================== Overview -~~~~~~~~ +-------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c :doc: Overview LRU Scan/Eviction Support -~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c :doc: lru scan roaster @@ -440,15 +452,3 @@ DRM MM Range Allocator Function References .. kernel-doc:: include/drm/drm_mm.h :internal: - -CMA Helper Functions Reference ------------------------------- - -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :doc: cma helpers - -.. kernel-doc:: drivers/gpu/drm/drm_gem_cma_helper.c - :export: - -.. kernel-doc:: include/drm/drm_gem_cma_helper.h - :internal: diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index 536bf3eaadd4..1ba301cebe16 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -33,6 +33,76 @@ Primary Nodes, DRM Master and Authentication .. kernel-doc:: include/drm/drm_auth.h :internal: +Open-Source Userspace Requirements +================================== + +The DRM subsystem has stricter requirements than most other kernel subsystems on +what the userspace side for new uAPI needs to look like. This section here +explains what exactly those requirements are, and why they exist. + +The short summary is that any addition of DRM uAPI requires corresponding +open-sourced userspace patches, and those patches must be reviewed and ready for +merging into a suitable and canonical upstream project. + +GFX devices (both display and render/GPU side) are really complex bits of +hardware, with userspace and kernel by necessity having to work together really +closely. The interfaces, for rendering and modesetting, must be extremely wide +and flexible, and therefore it is almost always impossible to precisely define +them for every possible corner case. This in turn makes it really practically +infeasible to differentiate between behaviour that's required by userspace, and +which must not be changed to avoid regressions, and behaviour which is only an +accidental artifact of the current implementation. + +Without access to the full source code of all userspace users that means it +becomes impossible to change the implementation details, since userspace could +depend upon the accidental behaviour of the current implementation in minute +details. And debugging such regressions without access to source code is pretty +much impossible. As a consequence this means: + +- The Linux kernel's "no regression" policy holds in practice only for + open-source userspace of the DRM subsystem. DRM developers are perfectly fine + if closed-source blob drivers in userspace use the same uAPI as the open + drivers, but they must do so in the exact same way as the open drivers. + Creative (ab)use of the interfaces will, and in the past routinely has, lead + to breakage. + +- Any new userspace interface must have an open-source implementation as + demonstration vehicle. + +The other reason for requiring open-source userspace is uAPI review. Since the +kernel and userspace parts of a GFX stack must work together so closely, code +review can only assess whether a new interface achieves its goals by looking at +both sides. Making sure that the interface indeed covers the use-case fully +leads to a few additional requirements: + +- The open-source userspace must not be a toy/test application, but the real + thing. Specifically it needs to handle all the usual error and corner cases. + These are often the places where new uAPI falls apart and hence essential to + assess the fitness of a proposed interface. + +- The userspace side must be fully reviewed and tested to the standards of that + userspace project. For e.g. mesa this means piglit testcases and review on the + mailing list. This is again to ensure that the new interface actually gets the + job done. + +- The userspace patches must be against the canonical upstream, not some vendor + fork. This is to make sure that no one cheats on the review and testing + requirements by doing a quick fork. + +- The kernel patch can only be merged after all the above requirements are met, + but it **must** be merged **before** the userspace patches land. uAPI always flows + from the kernel, doing things the other way round risks divergence of the uAPI + definitions and header files. + +These are fairly steep requirements, but have grown out from years of shared +pain and experience with uAPI added hastily, and almost always regretted about +just as fast. GFX devices change really fast, requiring a paradigm shift and +entire new set of uAPI interfaces every few years at least. Together with the +Linux kernel's guarantee to keep existing userspace running for 10+ years this +is already rather painful for the DRM subsystem, with multiple different uAPIs +for the same thing co-existing. If we add a few more complete mistakes into the +mix every year it would be entirely unmanageable. + Render nodes ============ @@ -86,6 +156,43 @@ other hand, a driver requires shared state between clients which is visible to user-space and accessible beyond open-file boundaries, they cannot support render nodes. +Validating changes with IGT +=========================== + +There's a collection of tests that aims to cover the whole functionality of +DRM drivers and that can be used to check that changes to DRM drivers or the +core don't regress existing functionality. This test suite is called IGT and +its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/. + +To build IGT, start by installing its build dependencies. In Debian-based +systems:: + + # apt-get build-dep intel-gpu-tools + +And in Fedora-based systems:: + + # dnf builddep intel-gpu-tools + +Then clone the repository:: + + $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools + +Configure the build system and start the build:: + + $ cd igt-gpu-tools && ./autogen.sh && make -j6 + +Download the piglit dependency:: + + $ ./scripts/run-tests.sh -d + +And run the tests:: + + $ ./scripts/run-tests.sh -t kms -t core -s + +run-tests.sh is a wrapper around piglit that will execute the tests matching +the -t options. A report in HTML format will be available in +./results/html/index.html. Results can be compared with piglit. + VBlank event handling ===================== diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 2fe5952e90f1..87aaffc22920 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -70,6 +70,9 @@ Frontbuffer Tracking .. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c :doc: frontbuffer tracking +.. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.h + :internal: + .. kernel-doc:: drivers/gpu/drm/i915/intel_frontbuffer.c :internal: diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index fcac0fa72056..be0dafcf5556 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -12,3 +12,11 @@ Linux GPU Driver Developer's Guide drm-uapi i915 vga-switcheroo + vgaarbiter + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/gpu/kms-properties.csv b/Documentation/gpu/kms-properties.csv index 4c5ce3edcfd9..981873a05d14 100644 --- a/Documentation/gpu/kms-properties.csv +++ b/Documentation/gpu/kms-properties.csv @@ -1,23 +1,10 @@ Owner Module/Drivers,Group,Property Name,Type,Property Values,Object attached,Description/Restrictions -DRM,Generic,“rotation”,BITMASK,"{ 0, ""rotate-0"" }, { 1, ""rotate-90"" }, { 2, ""rotate-180"" }, { 3, ""rotate-270"" }, { 4, ""reflect-x"" }, { 5, ""reflect-y"" }","CRTC, Plane",rotate-(degrees) rotates the image by the specified amount in degrees in counter clockwise direction. reflect-x and reflect-y reflects the image along the specified axis prior to rotation ,,“scaling mode”,ENUM,"{ ""None"", ""Full"", ""Center"", ""Full aspect"" }",Connector,"Supported by: amdgpu, gma500, i915, nouveau and radeon." ,Connector,“EDID”,BLOB | IMMUTABLE,0,Connector,Contains id of edid blob ptr object. ,,“DPMS”,ENUM,"{ “On”, “Standby”, “Suspend”, “Off” }",Connector,Contains DPMS operation mode value. ,,“PATH”,BLOB | IMMUTABLE,0,Connector,Contains topology path to a connector. ,,“TILE”,BLOB | IMMUTABLE,0,Connector,Contains tiling information for a connector. ,,“CRTC_ID”,OBJECT,DRM_MODE_OBJECT_CRTC,Connector,CRTC that connector is attached to (atomic) -,Plane,“type”,ENUM | IMMUTABLE,"{ ""Overlay"", ""Primary"", ""Cursor"" }",Plane,Plane type -,,“SRC_X”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout source x coordinate in 16.16 fixed point (atomic) -,,“SRC_Y”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout source y coordinate in 16.16 fixed point (atomic) -,,“SRC_W”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout source width in 16.16 fixed point (atomic) -,,“SRC_H”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout source height in 16.16 fixed point (atomic) -,,“CRTC_X”,SIGNED_RANGE,"Min=INT_MIN, Max=INT_MAX",Plane,Scanout CRTC (destination) x coordinate (atomic) -,,“CRTC_Y”,SIGNED_RANGE,"Min=INT_MIN, Max=INT_MAX",Plane,Scanout CRTC (destination) y coordinate (atomic) -,,“CRTC_W”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout CRTC (destination) width (atomic) -,,“CRTC_H”,RANGE,"Min=0, Max=UINT_MAX",Plane,Scanout CRTC (destination) height (atomic) -,,“FB_ID”,OBJECT,DRM_MODE_OBJECT_FB,Plane,Scanout framebuffer (atomic) -,,“CRTC_ID”,OBJECT,DRM_MODE_OBJECT_CRTC,Plane,CRTC that plane is attached to (atomic) -,,“zpos”,RANGE,"Min=0, Max=UINT_MAX","Plane,Z-order of the plane.Planes with higher Z-order values are displayed on top, planes with identical Z-order values are display in an undefined order" ,DVI-I,“subconnector”,ENUM,"{ “Unknown”, “DVI-D”, “DVI-A” }",Connector,TBD ,,“select subconnector”,ENUM,"{ “Automatic”, “DVI-D”, “DVI-A” }",Connector,TBD ,TV,“subconnector”,ENUM,"{ ""Unknown"", ""Composite"", ""SVIDEO"", ""Component"", ""SCART"" }",Connector,TBD @@ -36,12 +23,6 @@ DRM,Generic,“rotation”,BITMASK,"{ 0, ""rotate-0"" }, { 1, ""rotate-90"" }, { ,Virtual GPU,“suggested X”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an X offset for a connector ,,“suggested Y”,RANGE,"Min=0, Max=0xffffffff",Connector,property to suggest an Y offset for a connector ,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9"" }",Connector,TDB -,,“dirty”,ENUM | IMMUTABLE,"{ ""Off"", ""On"", ""Annotate"" }",Connector,TBD -,,“DEGAMMA_LUT”,BLOB,0,CRTC,DRM property to set the degamma lookup table (LUT) mapping pixel data from the framebuffer before it is given to the transformation matrix. The data is an interpreted as an array of struct drm_color_lut elements. Hardware might choose not to use the full precision of the LUT elements nor use all the elements of the LUT (for example the hardware might choose to interpolate between LUT[0] and LUT[4]). -,,“DEGAMMA_LUT_SIZE”,RANGE | IMMUTABLE,"Min=0, Max=UINT_MAX",CRTC,DRM property to gives the size of the lookup table to be set on the DEGAMMA_LUT property (the size depends on the underlying hardware). -,,“CTM”,BLOB,0,CRTC,DRM property to set the current transformation matrix (CTM) apply to pixel data after the lookup through the degamma LUT and before the lookup through the gamma LUT. The data is an interpreted as a struct drm_color_ctm. -,,“GAMMA_LUT”,BLOB,0,CRTC,DRM property to set the gamma lookup table (LUT) mapping pixel data after to the transformation matrix to data sent to the connector. The data is an interpreted as an array of struct drm_color_lut elements. Hardware might choose not to use the full precision of the LUT elements nor use all the elements of the LUT (for example the hardware might choose to interpolate between LUT[0] and LUT[4]). -,,“GAMMA_LUT_SIZE”,RANGE | IMMUTABLE,"Min=0, Max=UINT_MAX",CRTC,DRM property to gives the size of the lookup table to be set on the GAMMA_LUT property (the size depends on the underlying hardware). i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is set, the hardware will be programmed with the result of the multiplication of CTM by the limited range matrix to ensure the pixels normaly in the range 0..1.0 are remapped to the range 16/255..235/255." ,,“audio”,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on"" }",Connector,TBD ,SDVO-TV,“mode”,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B"" } etc.",Connector,TBD @@ -95,7 +76,6 @@ armada,CRTC,"""CSC_YUV""",ENUM,"{ ""Auto"" , ""CCIR601"", ""CCIR709"" }",CRTC,TB ,,"""contrast""",RANGE,"Min=0, Max=0x7fff",Plane,TBD ,,"""saturation""",RANGE,"Min=0, Max=0x7fff",Plane,TBD exynos,CRTC,“mode”,ENUM,"{ ""normal"", ""blank"" }",CRTC,TBD -,Overlay,“zpos”,RANGE,"Min=0, Max=MAX_PLANE-1",Plane,TBD i2c/ch7006_drv,Generic,“scale”,RANGE,"Min=0, Max=2",Connector,TBD ,TV,“mode”,ENUM,"{ ""PAL"", ""PAL-M"",""PAL-N""}, ”PAL-Nc"" , ""PAL-60"", ""NTSC-M"", ""NTSC-J"" }",Connector,TBD nouveau,NV10 Overlay,"""colorkey""",RANGE,"Min=0, Max=0x01ffffff",Plane,TBD @@ -126,4 +106,3 @@ radeon,DVI-I,“coherent”,RANGE,"Min=0, Max=1",Connector,TBD ,FMT Dithering,“dither”,ENUM,"{ ""off"", ""on"" }",Connector,TBD rcar-du,Generic,"""alpha""",RANGE,"Min=0, Max=255",Plane,TBD ,,"""colorkey""",RANGE,"Min=0, Max=0x01ffffff",Plane,TBD -,,"""zpos""",RANGE,"Min=1, Max=7",Plane,TBD diff --git a/Documentation/gpu/vgaarbiter.rst b/Documentation/gpu/vgaarbiter.rst new file mode 100644 index 000000000000..0b41b051d021 --- /dev/null +++ b/Documentation/gpu/vgaarbiter.rst @@ -0,0 +1,191 @@ +=========== +VGA Arbiter +=========== + +Graphic devices are accessed through ranges in I/O or memory space. While most +modern devices allow relocation of such ranges, some "Legacy" VGA devices +implemented on PCI will typically have the same "hard-decoded" addresses as +they did on ISA. For more details see "PCI Bus Binding to IEEE Std 1275-1994 +Standard for Boot (Initialization Configuration) Firmware Revision 2.1" +Section 7, Legacy Devices. + +The Resource Access Control (RAC) module inside the X server [0] existed for +the legacy VGA arbitration task (besides other bus management tasks) when more +than one legacy device co-exists on the same machine. But the problem happens +when these devices are trying to be accessed by different userspace clients +(e.g. two server in parallel). Their address assignments conflict. Moreover, +ideally, being a userspace application, it is not the role of the X server to +control bus resources. Therefore an arbitration scheme outside of the X server +is needed to control the sharing of these resources. This document introduces +the operation of the VGA arbiter implemented for the Linux kernel. + +vgaarb kernel/userspace ABI +--------------------------- + +The vgaarb is a module of the Linux Kernel. When it is initially loaded, it +scans all PCI devices and adds the VGA ones inside the arbitration. The +arbiter then enables/disables the decoding on different devices of the VGA +legacy instructions. Devices which do not want/need to use the arbiter may +explicitly tell it by calling vga_set_legacy_decoding(). + +The kernel exports a char device interface (/dev/vga_arbiter) to the clients, +which has the following semantics: + +open + Opens a user instance of the arbiter. By default, it's attached to the + default VGA device of the system. + +close + Close a user instance. Release locks made by the user + +read + Return a string indicating the status of the target like: + + ",decodes=,owns=,locks= (ic,mc)" + + An IO state string is of the form {io,mem,io+mem,none}, mc and + ic are respectively mem and io lock counts (for debugging/ + diagnostic only). "decodes" indicate what the card currently + decodes, "owns" indicates what is currently enabled on it, and + "locks" indicates what is locked by this card. If the card is + unplugged, we get "invalid" then for card_ID and an -ENODEV + error is returned for any command until a new card is targeted. + + +write + Write a command to the arbiter. List of commands: + + target + switch target to card (see below) + lock + acquires locks on target ("none" is an invalid io_state) + trylock + non-blocking acquire locks on target (returns EBUSY if + unsuccessful) + unlock + release locks on target + unlock all + release all locks on target held by this user (not implemented + yet) + decodes + set the legacy decoding attributes for the card + + poll + event if something changes on any card (not just the target) + + card_ID is of the form "PCI:domain:bus:dev.fn". It can be set to "default" + to go back to the system default card (TODO: not implemented yet). Currently, + only PCI is supported as a prefix, but the userland API may support other bus + types in the future, even if the current kernel implementation doesn't. + +Note about locks: + +The driver keeps track of which user has which locks on which card. It +supports stacking, like the kernel one. This complexifies the implementation +a bit, but makes the arbiter more tolerant to user space problems and able +to properly cleanup in all cases when a process dies. +Currently, a max of 16 cards can have locks simultaneously issued from +user space for a given user (file descriptor instance) of the arbiter. + +In the case of devices hot-{un,}plugged, there is a hook - pci_notify() - to +notify them being added/removed in the system and automatically added/removed +in the arbiter. + +There is also an in-kernel API of the arbiter in case DRM, vgacon, or other +drivers want to use it. + +In-kernel interface +------------------- + +.. kernel-doc:: include/linux/vgaarb.h + :internal: + +.. kernel-doc:: drivers/gpu/vga/vgaarb.c + :export: + +libpciaccess +------------ + +To use the vga arbiter char device it was implemented an API inside the +libpciaccess library. One field was added to struct pci_device (each device +on the system):: + + /* the type of resource decoded by the device */ + int vgaarb_rsrc; + +Besides it, in pci_system were added:: + + int vgaarb_fd; + int vga_count; + struct pci_device *vga_target; + struct pci_device *vga_default_dev; + +The vga_count is used to track how many cards are being arbitrated, so for +instance, if there is only one card, then it can completely escape arbitration. + +These functions below acquire VGA resources for the given card and mark those +resources as locked. If the resources requested are "normal" (and not legacy) +resources, the arbiter will first check whether the card is doing legacy +decoding for that type of resource. If yes, the lock is "converted" into a +legacy resource lock. The arbiter will first look for all VGA cards that +might conflict and disable their IOs and/or Memory access, including VGA +forwarding on P2P bridges if necessary, so that the requested resources can +be used. Then, the card is marked as locking these resources and the IO and/or +Memory access is enabled on the card (including VGA forwarding on parent +P2P bridges if any). In the case of vga_arb_lock(), the function will block +if some conflicting card is already locking one of the required resources (or +any resource on a different bus segment, since P2P bridges don't differentiate +VGA memory and IO afaik). If the card already owns the resources, the function +succeeds. vga_arb_trylock() will return (-EBUSY) instead of blocking. Nested +calls are supported (a per-resource counter is maintained). + +Set the target device of this client. :: + + int pci_device_vgaarb_set_target (struct pci_device *dev); + +For instance, in x86 if two devices on the same bus want to lock different +resources, both will succeed (lock). If devices are in different buses and +trying to lock different resources, only the first who tried succeeds. :: + + int pci_device_vgaarb_lock (void); + int pci_device_vgaarb_trylock (void); + +Unlock resources of device. :: + + int pci_device_vgaarb_unlock (void); + +Indicates to the arbiter if the card decodes legacy VGA IOs, legacy VGA +Memory, both, or none. All cards default to both, the card driver (fbdev for +example) should tell the arbiter if it has disabled legacy decoding, so the +card can be left out of the arbitration process (and can be safe to take +interrupts at any time. :: + + int pci_device_vgaarb_decodes (int new_vgaarb_rsrc); + +Connects to the arbiter device, allocates the struct :: + + int pci_device_vgaarb_init (void); + +Close the connection :: + + void pci_device_vgaarb_fini (void); + +xf86VGAArbiter (X server implementation) +---------------------------------------- + +X server basically wraps all the functions that touch VGA registers somehow. + +References +---------- + +Benjamin Herrenschmidt (IBM?) started this work when he discussed such design +with the Xorg community in 2005 [1, 2]. In the end of 2007, Paulo Zanoni and +Tiago Vignatti (both of C3SL/Federal University of Paraná) proceeded his work +enhancing the kernel code to adapt as a kernel module and also did the +implementation of the user space side [3]. Now (2009) Tiago Vignatti and Dave +Airlie finally put this work in shape and queued to Jesse Barnes' PCI tree. + +0) http://cgit.freedesktop.org/xorg/xserver/commit/?id=4b42448a2388d40f257774fbffdccaea87bd0347 +1) http://lists.freedesktop.org/archives/xorg/2005-March/006663.html +2) http://lists.freedesktop.org/archives/xorg/2005-March/006745.html +3) http://lists.freedesktop.org/archives/xorg/2007-October/029507.html diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt new file mode 100644 index 000000000000..d48b21c71ddd --- /dev/null +++ b/Documentation/hid/intel-ish-hid.txt @@ -0,0 +1,454 @@ +Intel Integrated Sensor Hub (ISH) +=============================== + +A sensor hub enables the ability to offload sensor polling and algorithm +processing to a dedicated low power co-processor. This allows the core +processor to go into low power modes more often, resulting in the increased +battery life. + +There are many vendors providing external sensor hubs confirming to HID +Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops +and embedded products. Linux had this support since Linux 3.9. + +Intel® introduced integrated sensor hubs as a part of the SoC starting from +Cherry Trail and now supported on multiple generations of CPU packages. There +are many commercial devices already shipped with Integrated Sensor Hubs (ISH). +These ISH also comply to HID sensor specification, but the difference is the +transport protocol used for communication. The current external sensor hubs +mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. + +1. Overview + +Using a analogy with a usbhid implementation, the ISH follows a similar model +for a very high speed communication: + + ----------------- ---------------------- + | USB HID | --> | ISH HID | + ----------------- ---------------------- + ----------------- ---------------------- + | USB protocol | --> | ISH Transport | + ----------------- ---------------------- + ----------------- ---------------------- + | EHCI/XHCI | --> | ISH IPC | + ----------------- ---------------------- + PCI PCI + ----------------- ---------------------- + |Host controller| --> | ISH processor | + ----------------- ---------------------- + USB Link + ----------------- ---------------------- + | USB End points| --> | ISH Clients | + ----------------- ---------------------- + +Like USB protocol provides a method for device enumeration, link management +and user data encapsulation, the ISH also provides similar services. But it is +very light weight tailored to manage and communicate with ISH client +applications implemented in the firmware. + +The ISH allows multiple sensor management applications executing in the +firmware. Like USB endpoints the messaging can be to/from a client. As part of +enumeration process, these clients are identified. These clients can be simple +HID sensor applications, sensor calibration application or senor firmware +update application. + +The implementation model is similar, like USB bus, ISH transport is also +implemented as a bus. Each client application executing in the ISH processor +is registered as a device on this bus. The driver, which binds each device +(ISH HID driver) identifies the device type and registers with the hid core. + +2. ISH Implementation: Block Diagram + + --------------------------- + | User Space Applications | + --------------------------- + +----------------IIO ABI---------------- + -------------------------- + | IIO Sensor Drivers | + -------------------------- + -------------------------- + | IIO core | + -------------------------- + -------------------------- + | HID Sensor Hub MFD | + -------------------------- + -------------------------- + | HID Core | + -------------------------- + -------------------------- + | HID over ISH Client | + -------------------------- + -------------------------- + | ISH Transport (ISHTP) | + -------------------------- + -------------------------- + | IPC Drivers | + -------------------------- +OS +---------------- PCI ----------------- +Hardware + Firmware + ---------------------------- + | ISH Hardware/Firmware(FW) | + ---------------------------- + +3. High level processing in above blocks + +3.1 Hardware Interface + +The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI +product and vendor IDs are changed from different generations of processors. So +the source code which enumerate drivers needs to update from generation to +generation. + +3.2 Inter Processor Communication (IPC) driver +Location: drivers/hid/intel-ish-hid/ipc + +The IPC message used memory mapped I/O. The registers are defined in +hw-ish-regs.h. + +3.2.1 IPC/FW message types + +There are two types of messages, one for management of link and other messages +are to and from transport layers. + +TX and RX of Transport messages + +A set of memory mapped register offers support of multi byte messages TX and +RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains +internal queues to sequence messages and send them in order to the FW. +Optionally the caller can register handler to get notification of completion. +A door bell mechanism is used in messaging to trigger processing in host and +client firmware side. When ISH interrupt handler is called, the ISH2HOST +doorbell register is used by host drivers to determine that the interrupt +is for ISH. + +Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell +register has the following format: +Bits 0..6: fragment length (7 bits are used) +Bits 10..13: encapsulated protocol +Bits 16..19: management command (for IPC management protocol) +Bit 31: doorbell trigger (signal H/W interrupt to the other side) +Other bits are reserved, should be 0. + +3.2.2 Transport layer interface + +To abstract HW level IPC communication, a set of callbacks are registered. +The transport layer uses them to send and receive messages. +Refer to struct ishtp_hw_ops for callbacks. + +3.3 ISH Transport layer +Location: drivers/hid/intel-ish-hid/ishtp/ + +3.3.1 A Generic Transport Layer + +The transport layer is a bi-directional protocol, which defines: +- Set of commands to start, stop, connect, disconnect and flow control +(ishtp/hbm.h) for details +- A flow control mechanism to avoid buffer overflows + +This protocol resembles bus messages described in the following document: +http://www.intel.com/content/dam/www/public/us/en/documents/technical-\ +specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer" + +3.3.2 Connection and Flow Control Mechanism + +Each FW client and a protocol is identified by an UUID. In order to communicate +to a FW client, a connection must be established using connect request and +response bus messages. If successful, a pair (host_client_id and fw_client_id) +will identify the connection. + +Once connection is established, peers send each other flow control bus messages +independently. Every peer may send a message only if it has received a +flow-control credit before. Once it sent a message, it may not send another one +before receiving the next flow control credit. +Either side can send disconnect request bus message to end communication. Also +the link will be dropped if major FW reset occurs. + +3.3.3 Peer to Peer data transfer + +Peer to Peer data transfer can happen with or without using DMA. Depending on +the sensor bandwidth requirement DMA can be enabled by using module parameter +ishtp_use_dma under intel_ishtp. + +Each side (host and FW) manages its DMA transfer memory independently. When an +ISHTP client from either host or FW side wants to send something, it decides +whether to send over IPC or over DMA; for each transfer the decision is +independent. The sending side sends DMA_XFER message when the message is in +the respective host buffer (TX when host client sends, RX when FW client +sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating +the sender that the memory region for that message may be reused. + +DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message +(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. +Additionally to DMA address communication, this sequence checks capabilities: +if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't +send DMA; if FW doesn't support DMA then it won't respond with +DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. +Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, +it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means +that it already did DMA and the message resides at host. Thus, DMA_XFER +and DMA_XFER_ACK act as ownership indicators. + +At initial state all outgoing memory belongs to the sender (TX to host, RX to +FW), DMA_XFER transfers ownership on the region that contains ISHTP message to +the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender +needs not wait for previous DMA_XFER to be ack'ed, and may send another message +as long as remaining continuous memory in its ownership is enough. +In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once +(up to IPC MTU), thus allowing for interrupt throttling. +Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC +fragments and via IPC otherwise. + +3.3.4 Ring Buffers + +When a client initiate a connection, a ring or RX and TX buffers are allocated. +The size of ring can be specified by the client. HID client set 16 and 32 for +TX and RX buffers respectively. On send request from client, the data to be +sent is copied to one of the send ring buffer and scheduled to be sent using +bus message protocol. These buffers are required because the FW may have not +have processed the last message and may not have enough flow control credits +to send. Same thing holds true on receive side and flow control is required. + +3.3.5 Host Enumeration + +The host enumeration bus command allow discovery of clients present in the FW. +There can be multiple sensor clients and clients for calibration function. + +To ease in implantation and allow independent driver handle each client +this transport layer takes advantage of Linux Bus driver model. Each +client is registered as device on the the transport bus (ishtp bus). + +Enumeration sequence of messages: +- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up. +- FW responds with HOST_START_RES_CMD +- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients) +- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW +client IDs +- For each FW ID found in that bitmap host sends +HOST_CLIENT_PROPERTIES_REQ_CMD +- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID, +max ISHTP message size, etc. +- Once host received properties for that last discovered client, it considers +ISHTP device fully functional (and allocates DMA buffers) + +3.4 HID over ISH Client +Location: drivers/hid/intel-ish-hid + +The ISHTP client driver is responsible for: +- enumerate HID devices under FW ISH client +- Get Report descriptor +- Register with HID core as a LL driver +- Process Get/Set feature request +- Get input reports + +3.5 HID Sensor Hub MFD and IIO sensor drivers + +The functionality in these drivers is the same as an external sensor hub. +Refer to +Documentation/hid/hid-sensor.txt for HID sensor +Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space + +3.6 End to End HID transport Sequence Diagram + +HID-ISH-CLN ISHTP IPC HW + | | | | + | | |-----WAKE UP------------------>| + | | | | + | | |-----HOST READY--------------->| + | | | | + | | |<----MNG_RESET_NOTIFY_ACK----- | + | | | | + | |<----ISHTP_START------ | | + | | | | + | |<-----------------HOST_START_RES_CMD-------------------| + | | | | + | |------------------QUERY_SUBSCRIBER-------------------->| + | | | | + | |------------------HOST_ENUM_REQ_CMD------------------->| + | | | | + | |<-----------------HOST_ENUM_RES_CMD--------------------| + | | | | + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| + | | | | + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| + | Create new device on in ishtp bus | | + | | | | + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| + | | | | + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| + | Create new device on in ishtp bus | | + | | | | + | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--| + | | | | + probed() + |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->| + | | | | + | |<----------------CLIENT_CONNECT_RES_CMD----------------| + | | | | + |register event callback| | | + | | | | + |ishtp_cl_send( + HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >| + | | | | + | | |<-----IRQ(IPC_PROTOCOL_ISHTP---| + | | | | + |<--ENUM_DEVICE RSP-----| | | + | | | | +for each enumerated device + |ishtp_cl_send( + HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >| + | | | | + ...Response + | | | | +for each enumerated device + |ishtp_cl_send( + HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >| + | | | | + | | | | + hid_allocate_device + | | | | + hid_add_device | | | + | | | | + + +3.7 ISH Debugging + +To debug ISH, event tracing mechanism is used. To enable debug logs +echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable +cat sys/kernel/debug/tracing/trace + +3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 + +root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/ +/sys/bus/iio/devices/ +├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0 +│   ├── buffer +│   │   ├── enable +│   │   ├── length +│   │   └── watermark +... +│   ├── in_accel_hysteresis +│   ├── in_accel_offset +│   ├── in_accel_sampling_frequency +│   ├── in_accel_scale +│   ├── in_accel_x_raw +│   ├── in_accel_y_raw +│   ├── in_accel_z_raw +│   ├── name +│   ├── scan_elements +│   │   ├── in_accel_x_en +│   │   ├── in_accel_x_index +│   │   ├── in_accel_x_type +│   │   ├── in_accel_y_en +│   │   ├── in_accel_y_index +│   │   ├── in_accel_y_type +│   │   ├── in_accel_z_en +│   │   ├── in_accel_z_index +│   │   └── in_accel_z_type +... +│   │   ├── devices +│   │   │   │   ├── buffer +│   │   │   │   │   ├── enable +│   │   │   │   │   ├── length +│   │   │   │   │   └── watermark +│   │   │   │   ├── dev +│   │   │   │   ├── in_intensity_both_raw +│   │   │   │   ├── in_intensity_hysteresis +│   │   │   │   ├── in_intensity_offset +│   │   │   │   ├── in_intensity_sampling_frequency +│   │   │   │   ├── in_intensity_scale +│   │   │   │   ├── name +│   │   │   │   ├── scan_elements +│   │   │   │   │   ├── in_intensity_both_en +│   │   │   │   │   ├── in_intensity_both_index +│   │   │   │   │   └── in_intensity_both_type +│   │   │   │   ├── trigger +│   │   │   │   │   └── current_trigger +... +│   │   │   │   ├── buffer +│   │   │   │   │   ├── enable +│   │   │   │   │   ├── length +│   │   │   │   │   └── watermark +│   │   │   │   ├── dev +│   │   │   │   ├── in_magn_hysteresis +│   │   │   │   ├── in_magn_offset +│   │   │   │   ├── in_magn_sampling_frequency +│   │   │   │   ├── in_magn_scale +│   │   │   │   ├── in_magn_x_raw +│   │   │   │   ├── in_magn_y_raw +│   │   │   │   ├── in_magn_z_raw +│   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw +│   │   │   │   ├── in_rot_hysteresis +│   │   │   │   ├── in_rot_offset +│   │   │   │   ├── in_rot_sampling_frequency +│   │   │   │   ├── in_rot_scale +│   │   │   │   ├── name +... +│   │   │   │   ├── scan_elements +│   │   │   │   │   ├── in_magn_x_en +│   │   │   │   │   ├── in_magn_x_index +│   │   │   │   │   ├── in_magn_x_type +│   │   │   │   │   ├── in_magn_y_en +│   │   │   │   │   ├── in_magn_y_index +│   │   │   │   │   ├── in_magn_y_type +│   │   │   │   │   ├── in_magn_z_en +│   │   │   │   │   ├── in_magn_z_index +│   │   │   │   │   ├── in_magn_z_type +│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en +│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index +│   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type +│   │   │   │   ├── trigger +│   │   │   │   │   └── current_trigger +... +│   │   │   │   ├── buffer +│   │   │   │   │   ├── enable +│   │   │   │   │   ├── length +│   │   │   │   │   └── watermark +│   │   │   │   ├── dev +│   │   │   │   ├── in_anglvel_hysteresis +│   │   │   │   ├── in_anglvel_offset +│   │   │   │   ├── in_anglvel_sampling_frequency +│   │   │   │   ├── in_anglvel_scale +│   │   │   │   ├── in_anglvel_x_raw +│   │   │   │   ├── in_anglvel_y_raw +│   │   │   │   ├── in_anglvel_z_raw +│   │   │   │   ├── name +│   │   │   │   ├── scan_elements +│   │   │   │   │   ├── in_anglvel_x_en +│   │   │   │   │   ├── in_anglvel_x_index +│   │   │   │   │   ├── in_anglvel_x_type +│   │   │   │   │   ├── in_anglvel_y_en +│   │   │   │   │   ├── in_anglvel_y_index +│   │   │   │   │   ├── in_anglvel_y_type +│   │   │   │   │   ├── in_anglvel_z_en +│   │   │   │   │   ├── in_anglvel_z_index +│   │   │   │   │   └── in_anglvel_z_type +│   │   │   │   ├── trigger +│   │   │   │   │   └── current_trigger +... +│   │   │   │   ├── buffer +│   │   │   │   │   ├── enable +│   │   │   │   │   ├── length +│   │   │   │   │   └── watermark +│   │   │   │   ├── dev +│   │   │   │   ├── in_anglvel_hysteresis +│   │   │   │   ├── in_anglvel_offset +│   │   │   │   ├── in_anglvel_sampling_frequency +│   │   │   │   ├── in_anglvel_scale +│   │   │   │   ├── in_anglvel_x_raw +│   │   │   │   ├── in_anglvel_y_raw +│   │   │   │   ├── in_anglvel_z_raw +│   │   │   │   ├── name +│   │   │   │   ├── scan_elements +│   │   │   │   │   ├── in_anglvel_x_en +│   │   │   │   │   ├── in_anglvel_x_index +│   │   │   │   │   ├── in_anglvel_x_type +│   │   │   │   │   ├── in_anglvel_y_en +│   │   │   │   │   ├── in_anglvel_y_index +│   │   │   │   │   ├── in_anglvel_y_type +│   │   │   │   │   ├── in_anglvel_z_en +│   │   │   │   │   ├── in_anglvel_z_index +│   │   │   │   │   └── in_anglvel_z_type +│   │   │   │   ├── trigger +│   │   │   │   │   └── current_trigger +... diff --git a/Documentation/hsi.txt b/Documentation/hsi.txt deleted file mode 100644 index 6ac6cd51852a..000000000000 --- a/Documentation/hsi.txt +++ /dev/null @@ -1,75 +0,0 @@ -HSI - High-speed Synchronous Serial Interface - -1. Introduction -~~~~~~~~~~~~~~~ - -High Speed Syncronous Interface (HSI) is a fullduplex, low latency protocol, -that is optimized for die-level interconnect between an Application Processor -and a Baseband chipset. It has been specified by the MIPI alliance in 2003 and -implemented by multiple vendors since then. - -The HSI interface supports full duplex communication over multiple channels -(typically 8) and is capable of reaching speeds up to 200 Mbit/s. - -The serial protocol uses two signals, DATA and FLAG as combined data and clock -signals and an additional READY signal for flow control. An additional WAKE -signal can be used to wakeup the chips from standby modes. The signals are -commonly prefixed by AC for signals going from the application die to the -cellular die and CA for signals going the other way around. - -+------------+ +---------------+ -| Cellular | | Application | -| Die | | Die | -| | - - - - - - CAWAKE - - - - - - >| | -| T|------------ CADATA ------------>|R | -| X|------------ CAFLAG ------------>|X | -| |<----------- ACREADY ------------| | -| | | | -| | | | -| |< - - - - - ACWAKE - - - - - - -| | -| R|<----------- ACDATA -------------|T | -| X|<----------- ACFLAG -------------|X | -| |------------ CAREADY ----------->| | -| | | | -| | | | -+------------+ +---------------+ - -2. HSI Subsystem in Linux -~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the Linux kernel the hsi subsystem is supposed to be used for HSI devices. -The hsi subsystem contains drivers for hsi controllers including support for -multi-port controllers and provides a generic API for using the HSI ports. - -It also contains HSI client drivers, which make use of the generic API to -implement a protocol used on the HSI interface. These client drivers can -use an arbitrary number of channels. - -3. hsi-char Device -~~~~~~~~~~~~~~~~~~ - -Each port automatically registers a generic client driver called hsi_char, -which provides a charecter device for userspace representing the HSI port. -It can be used to communicate via HSI from userspace. Userspace may -configure the hsi_char device using the following ioctl commands: - -* HSC_RESET: - - flush the HSI port - -* HSC_SET_PM - - enable or disable the client. - -* HSC_SEND_BREAK - - send break - -* HSC_SET_RX - - set RX configuration - -* HSC_GET_RX - - get RX configuration - -* HSC_SET_TX - - set TX configuration - -* HSC_GET_TX - - get TX configuration diff --git a/Documentation/hwmon/adt7470 b/Documentation/hwmon/adt7470 index 8ce4aa0a0f55..fe68e18a0c8d 100644 --- a/Documentation/hwmon/adt7470 +++ b/Documentation/hwmon/adt7470 @@ -65,6 +65,23 @@ from 0 (off) to 255 (full speed). Fan speed will be set to maximum when the temperature sensor associated with the PWM control exceeds pwm#_auto_point2_temp. +The driver also allows control of the PWM frequency: + +* pwm1_freq + +The PWM frequency is rounded to the nearest one of: + +* 11.0 Hz +* 14.7 Hz +* 22.1 Hz +* 29.4 Hz +* 35.3 Hz +* 44.1 Hz +* 58.8 Hz +* 88.2 Hz +* 1.4 kHz +* 22.5 kHz + Notes ----- diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.txt index 2ecdbfc85ecf..ef9d74947f5c 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.txt @@ -34,6 +34,19 @@ devm_hwmon_device_register_with_groups(struct device *dev, const char *name, void *drvdata, const struct attribute_group **groups); +struct device * +hwmon_device_register_with_info(struct device *dev, + const char *name, void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **groups); + +struct device * +devm_hwmon_device_register_with_info(struct device *dev, + const char *name, + void *drvdata, + const struct hwmon_chip_info *info, + const struct attribute_group **groups); + void hwmon_device_unregister(struct device *dev); void devm_hwmon_device_unregister(struct device *dev); @@ -60,15 +73,229 @@ devm_hwmon_device_register_with_groups is similar to hwmon_device_register_with_groups. However, it is device managed, meaning the hwmon device does not have to be removed explicitly by the removal function. +hwmon_device_register_with_info is the most comprehensive and preferred means +to register a hardware monitoring device. It creates the standard sysfs +attributes in the hardware monitoring core, letting the driver focus on reading +from and writing to the chip instead of having to bother with sysfs attributes. +Its parameters are described in more detail below. + +devm_hwmon_device_register_with_info is similar to +hwmon_device_register_with_info. However, it is device managed, meaning the +hwmon device does not have to be removed explicitly by the removal function. + hwmon_device_unregister deregisters a registered hardware monitoring device. The parameter of this function is the pointer to the registered hardware monitoring device structure. This function must be called from the driver remove function if the hardware monitoring device was registered with -hwmon_device_register or with hwmon_device_register_with_groups. +hwmon_device_register, hwmon_device_register_with_groups, or +hwmon_device_register_with_info. devm_hwmon_device_unregister does not normally have to be called. It is only needed for error handling, and only needed if the driver probe fails after -the call to devm_hwmon_device_register_with_groups. +the call to devm_hwmon_device_register_with_groups and if the automatic +(device managed) removal would be too late. + +Using devm_hwmon_device_register_with_info() +-------------------------------------------- + +hwmon_device_register_with_info() registers a hardware monitoring device. +The parameters to this function are + +struct device *dev Pointer to parent device +const char *name Device name +void *drvdata Driver private data +const struct hwmon_chip_info *info + Pointer to chip description. +const struct attribute_group **groups + Null-terminated list of additional sysfs attribute + groups. + +This function returns a pointer to the created hardware monitoring device +on success and a negative error code for failure. + +The hwmon_chip_info structure looks as follows. + +struct hwmon_chip_info { + const struct hwmon_ops *ops; + const struct hwmon_channel_info **info; +}; + +It contains the following fields: + +* ops: Pointer to device operations. +* info: NULL-terminated list of device channel descriptors. + +The list of hwmon operations is defined as: + +struct hwmon_ops { + umode_t (*is_visible)(const void *, enum hwmon_sensor_types type, + u32 attr, int); + int (*read)(struct device *, enum hwmon_sensor_types type, + u32 attr, int, long *); + int (*write)(struct device *, enum hwmon_sensor_types type, + u32 attr, int, long); +}; + +It defines the following operations. + +* is_visible: Pointer to a function to return the file mode for each supported + attribute. This function is mandatory. + +* read: Pointer to a function for reading a value from the chip. This function + is optional, but must be provided if any readable attributes exist. + +* write: Pointer to a function for writing a value to the chip. This function is + optional, but must be provided if any writeable attributes exist. + +Each sensor channel is described with struct hwmon_channel_info, which is +defined as follows. + +struct hwmon_channel_info { + enum hwmon_sensor_types type; + u32 *config; +}; + +It contains following fields: + +* type: The hardware monitoring sensor type. + Supported sensor types are + * hwmon_chip A virtual sensor type, used to describe attributes + which apply to the entire chip. + * hwmon_temp Temperature sensor + * hwmon_in Voltage sensor + * hwmon_curr Current sensor + * hwmon_power Power sensor + * hwmon_energy Energy sensor + * hwmon_humidity Humidity sensor + * hwmon_fan Fan speed sensor + * hwmon_pwm PWM control + +* config: Pointer to a 0-terminated list of configuration values for each + sensor of the given type. Each value is a combination of bit values + describing the attributes supposed by a single sensor. + +As an example, here is the complete description file for a LM75 compatible +sensor chip. The chip has a single temperature sensor. The driver wants to +register with the thermal subsystem (HWMON_C_REGISTER_TZ), and it supports +the update_interval attribute (HWMON_C_UPDATE_INTERVAL). The chip supports +reading the temperature (HWMON_T_INPUT), it has a maximum temperature +register (HWMON_T_MAX) as well as a maximum temperature hysteresis register +(HWMON_T_MAX_HYST). + +static const u32 lm75_chip_config[] = { + HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL, + 0 +}; + +static const struct hwmon_channel_info lm75_chip = { + .type = hwmon_chip, + .config = lm75_chip_config, +}; + +static const u32 lm75_temp_config[] = { + HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST, + 0 +}; + +static const struct hwmon_channel_info lm75_temp = { + .type = hwmon_temp, + .config = lm75_temp_config, +}; + +static const struct hwmon_channel_info *lm75_info[] = { + &lm75_chip, + &lm75_temp, + NULL +}; + +static const struct hwmon_ops lm75_hwmon_ops = { + .is_visible = lm75_is_visible, + .read = lm75_read, + .write = lm75_write, +}; + +static const struct hwmon_chip_info lm75_chip_info = { + .ops = &lm75_hwmon_ops, + .info = lm75_info, +}; + +A complete list of bit values indicating individual attribute support +is defined in include/linux/hwmon.h. Definition prefixes are as follows. + +HWMON_C_xxxx Chip attributes, for use with hwmon_chip. +HWMON_T_xxxx Temperature attributes, for use with hwmon_temp. +HWMON_I_xxxx Voltage attributes, for use with hwmon_in. +HWMON_C_xxxx Current attributes, for use with hwmon_curr. + Notice the prefix overlap with chip attributes. +HWMON_P_xxxx Power attributes, for use with hwmon_power. +HWMON_E_xxxx Energy attributes, for use with hwmon_energy. +HWMON_H_xxxx Humidity attributes, for use with hwmon_humidity. +HWMON_F_xxxx Fan speed attributes, for use with hwmon_fan. +HWMON_PWM_xxxx PWM control attributes, for use with hwmon_pwm. + +Driver callback functions +------------------------- + +Each driver provides is_visible, read, and write functions. Parameters +and return values for those functions are as follows. + +umode_t is_visible_func(const void *data, enum hwmon_sensor_types type, + u32 attr, int channel) + +Parameters: + data: Pointer to device private data structure. + type: The sensor type. + attr: Attribute identifier associated with a specific attribute. + For example, the attribute value for HWMON_T_INPUT would be + hwmon_temp_input. For complete mappings of bit fields to + attribute values please see include/linux/hwmon.h. + channel:The sensor channel number. + +Return value: + The file mode for this attribute. Typically, this will be 0 (the + attribute will not be created), S_IRUGO, or 'S_IRUGO | S_IWUSR'. + +int read_func(struct device *dev, enum hwmon_sensor_types type, + u32 attr, int channel, long *val) + +Parameters: + dev: Pointer to the hardware monitoring device. + type: The sensor type. + attr: Attribute identifier associated with a specific attribute. + For example, the attribute value for HWMON_T_INPUT would be + hwmon_temp_input. For complete mappings please see + include/linux/hwmon.h. + channel:The sensor channel number. + val: Pointer to attribute value. + +Return value: + 0 on success, a negative error number otherwise. + +int write_func(struct device *dev, enum hwmon_sensor_types type, + u32 attr, int channel, long val) + +Parameters: + dev: Pointer to the hardware monitoring device. + type: The sensor type. + attr: Attribute identifier associated with a specific attribute. + For example, the attribute value for HWMON_T_INPUT would be + hwmon_temp_input. For complete mappings please see + include/linux/hwmon.h. + channel:The sensor channel number. + val: The value to write to the chip. + +Return value: + 0 on success, a negative error number otherwise. + + +Driver-provided sysfs attributes +-------------------------------- + +If the hardware monitoring device is registered with +hwmon_device_register_with_info or devm_hwmon_device_register_with_info, +it is most likely not necessary to provide sysfs attributes. Only non-standard +sysfs attributes need to be provided when one of those registration functions +is used. The header file linux/hwmon-sysfs.h provides a number of useful macros to declare and use hardware monitoring sysfs attributes. diff --git a/Documentation/hwmon/max6650 b/Documentation/hwmon/max6650 index 58d9644a2bde..dff1d296a48b 100644 --- a/Documentation/hwmon/max6650 +++ b/Documentation/hwmon/max6650 @@ -34,6 +34,7 @@ fan3_input ro " fan4_input ro " fan1_target rw desired fan speed in RPM (closed loop mode only) pwm1_enable rw regulator mode, 0=full on, 1=open loop, 2=closed loop + 3=off pwm1 rw relative speed (0-255), 255=max. speed. Used in open loop mode only. fan1_div rw sets the speed range the inputs can handle. Legal diff --git a/Documentation/hwmon/ucd9000 b/Documentation/hwmon/ucd9000 index 805e33edb978..262e713e60ff 100644 --- a/Documentation/hwmon/ucd9000 +++ b/Documentation/hwmon/ucd9000 @@ -2,12 +2,13 @@ Kernel driver ucd9000 ===================== Supported chips: - * TI UCD90120, UCD90124, UCD9090, and UCD90910 - Prefixes: 'ucd90120', 'ucd90124', 'ucd9090', 'ucd90910' + * TI UCD90120, UCD90124, UCD90160, UCD9090, and UCD90910 + Prefixes: 'ucd90120', 'ucd90124', 'ucd90160', 'ucd9090', 'ucd90910' Addresses scanned: - Datasheets: http://focus.ti.com/lit/ds/symlink/ucd90120.pdf http://focus.ti.com/lit/ds/symlink/ucd90124.pdf + http://focus.ti.com/lit/ds/symlink/ucd90160.pdf http://focus.ti.com/lit/ds/symlink/ucd9090.pdf http://focus.ti.com/lit/ds/symlink/ucd90910.pdf @@ -32,6 +33,13 @@ interrupts, cascading, or other system functions. Twelve of these pins offer PWM functionality. Using these pins, the UCD90124 offers support for fan control, margining, and general-purpose PWM functions. +The UCD90160 is a 16-rail PMBus/I2C addressable power-supply sequencer and +monitor. The device integrates a 12-bit ADC for monitoring up to 16 power-supply +voltage inputs. Twenty-six GPIO pins can be used for power supply enables, +power-on reset signals, external interrupts, cascading, or other system +functions. Twelve of these pins offer PWM functionality. Using these pins, the +UCD90160 offers support for margining, and general-purpose PWM functions. + The UCD9090 is a 10-rail PMBus/I2C addressable power-supply sequencer and monitor. The device integrates a 12-bit ADC for monitoring up to 10 power-supply voltage inputs. Twenty-three GPIO pins can be used for power supply enables, diff --git a/Documentation/hwmon/xgene-hwmon b/Documentation/hwmon/xgene-hwmon new file mode 100644 index 000000000000..6ec50ed7cc8f --- /dev/null +++ b/Documentation/hwmon/xgene-hwmon @@ -0,0 +1,30 @@ +Kernel driver xgene-hwmon +======================== + +Supported chips: + * APM X-Gene SoC + +Description +----------- + +This driver adds hardware temperature and power reading support for +APM X-Gene SoC using the mailbox communication interface. +For device tree, it is the standard DT mailbox. +For ACPI, it is the PCC mailbox. + +The following sensors are supported + + * Temperature + - SoC on-die temperature in milli-degree C + - Alarm when high/over temperature occurs + * Power + - CPU power in uW + - IO power in uW + +sysfs-Interface +--------------- + +temp0_input - SoC on-die temperature (milli-degree C) +temp0_critical_alarm - An 1 would indicates on-die temperature exceeded threshold +power0_input - CPU power in (uW) +power1_input - IO power in (uW) diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface index 80807adb8ded..7e2a228f21bc 100644 --- a/Documentation/i2c/slave-interface +++ b/Documentation/i2c/slave-interface @@ -145,6 +145,11 @@ If you want to add slave support to the bus driver: * Catch the slave interrupts and send appropriate i2c_slave_events to the backend. +Note that most hardware supports being master _and_ slave on the same bus. So, +if you extend a bus driver, please make sure that the driver supports that as +well. In almost all cases, slave support does not need to disable the master +functionality. + Check the i2c-rcar driver as an example. diff --git a/Documentation/ia64/.gitignore b/Documentation/ia64/.gitignore deleted file mode 100644 index ab806edc8732..000000000000 --- a/Documentation/ia64/.gitignore +++ /dev/null @@ -1 +0,0 @@ -aliasing-test diff --git a/Documentation/ia64/Makefile b/Documentation/ia64/Makefile deleted file mode 100644 index d493163affe7..000000000000 --- a/Documentation/ia64/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# List of programs to build -hostprogs-y := aliasing-test - -# Tell kbuild to always build the programs -always := $(hostprogs-y) diff --git a/Documentation/ia64/aliasing-test.c b/Documentation/ia64/aliasing-test.c deleted file mode 100644 index 62a190d45f38..000000000000 --- a/Documentation/ia64/aliasing-test.c +++ /dev/null @@ -1,263 +0,0 @@ -/* - * Exercise /dev/mem mmap cases that have been troublesome in the past - * - * (c) Copyright 2007 Hewlett-Packard Development Company, L.P. - * Bjorn Helgaas - * - * This program 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. - */ - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -int sum; - -static int map_mem(char *path, off_t offset, size_t length, int touch) -{ - int fd, rc; - void *addr; - int *c; - - fd = open(path, O_RDWR); - if (fd == -1) { - perror(path); - return -1; - } - - if (fnmatch("/proc/bus/pci/*", path, 0) == 0) { - rc = ioctl(fd, PCIIOC_MMAP_IS_MEM); - if (rc == -1) - perror("PCIIOC_MMAP_IS_MEM ioctl"); - } - - addr = mmap(NULL, length, PROT_READ|PROT_WRITE, MAP_SHARED, fd, offset); - if (addr == MAP_FAILED) - return 1; - - if (touch) { - c = (int *) addr; - while (c < (int *) (addr + length)) - sum += *c++; - } - - rc = munmap(addr, length); - if (rc == -1) { - perror("munmap"); - return -1; - } - - close(fd); - return 0; -} - -static int scan_tree(char *path, char *file, off_t offset, size_t length, int touch) -{ - struct dirent **namelist; - char *name, *path2; - int i, n, r, rc = 0, result = 0; - struct stat buf; - - n = scandir(path, &namelist, 0, alphasort); - if (n < 0) { - perror("scandir"); - return -1; - } - - for (i = 0; i < n; i++) { - name = namelist[i]->d_name; - - if (fnmatch(".", name, 0) == 0) - goto skip; - if (fnmatch("..", name, 0) == 0) - goto skip; - - path2 = malloc(strlen(path) + strlen(name) + 3); - strcpy(path2, path); - strcat(path2, "/"); - strcat(path2, name); - - if (fnmatch(file, name, 0) == 0) { - rc = map_mem(path2, offset, length, touch); - if (rc == 0) - fprintf(stderr, "PASS: %s 0x%lx-0x%lx is %s\n", path2, offset, offset + length, touch ? "readable" : "mappable"); - else if (rc > 0) - fprintf(stderr, "PASS: %s 0x%lx-0x%lx not mappable\n", path2, offset, offset + length); - else { - fprintf(stderr, "FAIL: %s 0x%lx-0x%lx not accessible\n", path2, offset, offset + length); - return rc; - } - } else { - r = lstat(path2, &buf); - if (r == 0 && S_ISDIR(buf.st_mode)) { - rc = scan_tree(path2, file, offset, length, touch); - if (rc < 0) - return rc; - } - } - - result |= rc; - free(path2); - -skip: - free(namelist[i]); - } - free(namelist); - return result; -} - -char buf[1024]; - -static int read_rom(char *path) -{ - int fd, rc; - size_t size = 0; - - fd = open(path, O_RDWR); - if (fd == -1) { - perror(path); - return -1; - } - - rc = write(fd, "1", 2); - if (rc <= 0) { - close(fd); - perror("write"); - return -1; - } - - do { - rc = read(fd, buf, sizeof(buf)); - if (rc > 0) - size += rc; - } while (rc > 0); - - close(fd); - return size; -} - -static int scan_rom(char *path, char *file) -{ - struct dirent **namelist; - char *name, *path2; - int i, n, r, rc = 0, result = 0; - struct stat buf; - - n = scandir(path, &namelist, 0, alphasort); - if (n < 0) { - perror("scandir"); - return -1; - } - - for (i = 0; i < n; i++) { - name = namelist[i]->d_name; - - if (fnmatch(".", name, 0) == 0) - goto skip; - if (fnmatch("..", name, 0) == 0) - goto skip; - - path2 = malloc(strlen(path) + strlen(name) + 3); - strcpy(path2, path); - strcat(path2, "/"); - strcat(path2, name); - - if (fnmatch(file, name, 0) == 0) { - rc = read_rom(path2); - - /* - * It's OK if the ROM is unreadable. Maybe there - * is no ROM, or some other error occurred. The - * important thing is that no MCA happened. - */ - if (rc > 0) - fprintf(stderr, "PASS: %s read %d bytes\n", path2, rc); - else { - fprintf(stderr, "PASS: %s not readable\n", path2); - return rc; - } - } else { - r = lstat(path2, &buf); - if (r == 0 && S_ISDIR(buf.st_mode)) { - rc = scan_rom(path2, file); - if (rc < 0) - return rc; - } - } - - result |= rc; - free(path2); - -skip: - free(namelist[i]); - } - free(namelist); - return result; -} - -int main(void) -{ - int rc; - - if (map_mem("/dev/mem", 0, 0xA0000, 1) == 0) - fprintf(stderr, "PASS: /dev/mem 0x0-0xa0000 is readable\n"); - else - fprintf(stderr, "FAIL: /dev/mem 0x0-0xa0000 not accessible\n"); - - /* - * It's not safe to blindly read the VGA frame buffer. If you know - * how to poke the card the right way, it should respond, but it's - * not safe in general. Many machines, e.g., Intel chipsets, cover - * up a non-responding card by just returning -1, but others will - * report the failure as a machine check. - */ - if (map_mem("/dev/mem", 0xA0000, 0x20000, 0) == 0) - fprintf(stderr, "PASS: /dev/mem 0xa0000-0xc0000 is mappable\n"); - else - fprintf(stderr, "FAIL: /dev/mem 0xa0000-0xc0000 not accessible\n"); - - if (map_mem("/dev/mem", 0xC0000, 0x40000, 1) == 0) - fprintf(stderr, "PASS: /dev/mem 0xc0000-0x100000 is readable\n"); - else - fprintf(stderr, "FAIL: /dev/mem 0xc0000-0x100000 not accessible\n"); - - /* - * Often you can map all the individual pieces above (0-0xA0000, - * 0xA0000-0xC0000, and 0xC0000-0x100000), but can't map the whole - * thing at once. This is because the individual pieces use different - * attributes, and there's no single attribute supported over the - * whole region. - */ - rc = map_mem("/dev/mem", 0, 1024*1024, 0); - if (rc == 0) - fprintf(stderr, "PASS: /dev/mem 0x0-0x100000 is mappable\n"); - else if (rc > 0) - fprintf(stderr, "PASS: /dev/mem 0x0-0x100000 not mappable\n"); - else - fprintf(stderr, "FAIL: /dev/mem 0x0-0x100000 not accessible\n"); - - scan_tree("/sys/class/pci_bus", "legacy_mem", 0, 0xA0000, 1); - scan_tree("/sys/class/pci_bus", "legacy_mem", 0xA0000, 0x20000, 0); - scan_tree("/sys/class/pci_bus", "legacy_mem", 0xC0000, 0x40000, 1); - scan_tree("/sys/class/pci_bus", "legacy_mem", 0, 1024*1024, 0); - - scan_rom("/sys/devices", "rom"); - - scan_tree("/proc/bus/pci", "??.?", 0, 0xA0000, 1); - scan_tree("/proc/bus/pci", "??.?", 0xA0000, 0x20000, 0); - scan_tree("/proc/bus/pci", "??.?", 0xC0000, 0x40000, 1); - scan_tree("/proc/bus/pci", "??.?", 0, 1024*1024, 0); - - return rc; -} diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.txt index f0add35cd52e..4e5f101837a8 100644 --- a/Documentation/iio/iio_configfs.txt +++ b/Documentation/iio/iio_configfs.txt @@ -82,8 +82,8 @@ users to create hrtimer triggers under /config/iio/triggers/hrtimer. e.g: -$ mkdir /config/triggers/hrtimer/instance1 -$ rmdir /config/triggers/hrtimer/instance1 +$ mkdir /config/iio/triggers/hrtimer/instance1 +$ rmdir /config/iio/triggers/hrtimer/instance1 Each trigger can have one or more attributes specific to the trigger type. diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..c53d089455a4 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -6,22 +6,20 @@ Welcome to The Linux Kernel's documentation! ============================================ -Nothing for you to see here *yet*. Please move along. - Contents: .. toctree:: :maxdepth: 2 kernel-documentation - media/media_uapi - media/media_kapi - media/dvb-drivers/index - media/v4l-drivers/index + development-process/index + dev-tools/tools + driver-api/index + media/index gpu/index + 80211/index Indices and tables ================== * :ref:`genindex` -* :ref:`search` diff --git a/Documentation/infiniband/sysfs.txt b/Documentation/infiniband/sysfs.txt index 45bcafe6ff8a..77570d16b170 100644 --- a/Documentation/infiniband/sysfs.txt +++ b/Documentation/infiniband/sysfs.txt @@ -89,6 +89,36 @@ HFI1 nctxts - number of allowed contexts (PSM2) chip_reset - diagnostic (root only) boardversion - board version + + sdma/ - one directory per sdma engine (0 - 15) + sdma/cpu_list - read-write, list of cpus for user-process to sdma + engine assignment. + sdma/vl - read-only, vl the sdma engine maps to. + + The new interface will give the user control on the affinity settings + for the hfi1 device. + As an example, to set an sdma engine irq affinity and thread affinity + of a user processes to use the sdma engine, which is "near" in terms + of NUMA configuration, or physical cpu location, the user will do: + + echo "3" > /proc/irq//smp_affinity_list + echo "4-7" > /sys/devices/.../sdma3/cpu_list + cat /sys/devices/.../sdma3/vl + 0 + echo "8" > /proc/irq//smp_affinity_list + echo "9-12" > /sys/devices/.../sdma4/cpu_list + cat /sys/devices/.../sdma4/vl + 1 + + to make sure that when a process runs on cpus 4,5,6, or 7, + and uses vl=0, then sdma engine 3 is selected by the driver, + and also the interrupt of the sdma engine 3 is steered to cpu 3. + Similarly, when a process runs on cpus 9,10,11, or 12 and sets vl=1, + then engine 4 will be selected and the irq of the sdma engine 4 is + steered to cpu 8. + This assumes that in the above N is the irq number of "sdma3", + and M is irq number of "sdma4" in the /proc/interrupts file. + ports/1/ CCMgtA/ cc_settings_bin - CCA tables used by PSM2 diff --git a/Documentation/input/alps.txt b/Documentation/input/alps.txt index 1fec1135791d..8d1341ccde64 100644 --- a/Documentation/input/alps.txt +++ b/Documentation/input/alps.txt @@ -319,3 +319,60 @@ For touchpad packet, the format is: otherwise byte 0 bit 4 must be set and byte 0/4/5 are in NEW fmt F: Number of fingers - 3, 0 means 3 fingers, 1 means 4 ... + + +ALPS Absolute Mode - Protocol Version 8 +--------------------------------------- + +Spoken by SS4 (73 03 14) and SS5 (73 03 28) hardware. + +The packet type is given by the APD field, bits 4-5 of byte 3. + +Touchpad packet (APD = 0x2): + + b7 b6 b5 b4 b3 b2 b1 b0 + byte 0: SWM SWR SWL 1 1 0 0 X7 + byte 1: 0 X6 X5 X4 X3 X2 X1 X0 + byte 2: 0 Y6 Y5 Y4 Y3 Y2 Y1 Y0 + byte 3: 0 T&P 1 0 1 0 0 Y7 + byte 4: 0 Z6 Z5 Z4 Z3 Z2 Z1 Z0 + byte 5: 0 0 0 0 0 0 0 0 + +SWM, SWR, SWL: Middle, Right, and Left button states + +Touchpad 1 Finger packet (APD = 0x0): + + b7 b6 b5 b4 b3 b2 b1 b0 + byte 0: SWM SWR SWL 1 1 X2 X1 X0 + byte 1: X9 X8 X7 1 X6 X5 X4 X3 + byte 2: 0 X11 X10 LFB Y3 Y2 Y1 Y0 + byte 3: Y5 Y4 0 0 1 TAPF2 TAPF1 TAPF0 + byte 4: Zv7 Y11 Y10 1 Y9 Y8 Y7 Y6 + byte 5: Zv6 Zv5 Zv4 0 Zv3 Zv2 Zv1 Zv0 + +TAPF: ??? +LFB: ??? + +Touchpad 2 Finger packet (APD = 0x1): + + b7 b6 b5 b4 b3 b2 b1 b0 + byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4 + byte 1: AX11 AX10 AX9 AX8 AX7 AZ1 AY4 AZ0 + byte 2: AY11 AY10 AY9 CONT AY8 AY7 AY6 AY5 + byte 3: 0 0 0 1 1 BX6 BX5 BX4 + byte 4: BX11 BX10 BX9 BX8 BX7 BZ1 BY4 BZ0 + byte 5: BY11 BY10 BY9 0 BY8 BY7 BY5 BY5 + +CONT: A 3-or-4 Finger packet is to follow + +Touchpad 3-or-4 Finger packet (APD = 0x3): + + b7 b6 b5 b4 b3 b2 b1 b0 + byte 0: SWM SWR SWL 1 1 AX6 AX5 AX4 + byte 1: AX11 AX10 AX9 AX8 AX7 AZ1 AY4 AZ0 + byte 2: AY11 AY10 AY9 OVF AY8 AY7 AY6 AY5 + byte 3: 0 0 1 1 1 BX6 BX5 BX4 + byte 4: BX11 BX10 BX9 BX8 BX7 BZ1 BY4 BZ0 + byte 5: BY11 BY10 BY9 0 BY8 BY7 BY5 BY5 + +OVF: 5th finger detected diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index cc30b14791cb..36138c632f7a 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer: 64-bit platforms do. So we always need padding to the natural size to get this right. - * Pad the entire struct to a multiple of 64-bits - the structure size will - otherwise differ on 32-bit versus 64-bit. Having a different structure size - hurts when passing arrays of structures to the kernel, or if the kernel - checks the structure size, which e.g. the drm core does. + * Pad the entire struct to a multiple of 64-bits if the structure contains + 64-bit types - the structure size will otherwise differ on 32-bit versus + 64-bit. Having a different structure size hurts when passing arrays of + structures to the kernel, or if the kernel checks the structure size, which + e.g. the drm core does. * Pointers are __u64, cast from/to a uintprt_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. + diminishes the checking tools like sparse can provide. The macro + u64_to_user_ptr can be used in the kernel to avoid warnings about integers + and pointres of different sizes. Basics diff --git a/Documentation/kasan.txt b/Documentation/kasan.txt deleted file mode 100644 index 7dd95b35cd7c..000000000000 --- a/Documentation/kasan.txt +++ /dev/null @@ -1,171 +0,0 @@ -KernelAddressSanitizer (KASAN) -============================== - -0. Overview -=========== - -KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides -a fast and comprehensive solution for finding use-after-free and out-of-bounds -bugs. - -KASAN uses compile-time instrumentation for checking every memory access, -therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is -required for detection of out-of-bounds accesses to stack or global variables. - -Currently KASAN is supported only for x86_64 architecture. - -1. Usage -======== - -To enable KASAN configure kernel with: - - CONFIG_KASAN = y - -and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and -inline are compiler instrumentation types. The former produces smaller binary -the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC -version 5.0 or later. - -KASAN works with both SLUB and SLAB memory allocators. -For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. - -To disable instrumentation for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - - For a single file (e.g. main.o): - KASAN_SANITIZE_main.o := n - - For all files in one directory: - KASAN_SANITIZE := n - -1.1 Error reports -================= - -A typical out of bounds access report looks like this: - -================================================================== -BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 -Write of size 1 by task modprobe/1689 -============================================================================= -BUG kmalloc-128 (Not tainted): kasan error ------------------------------------------------------------------------------ - -Disabling lock debugging due to kernel taint -INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 - __slab_alloc+0x4b4/0x4f0 - kmem_cache_alloc_trace+0x10b/0x190 - kmalloc_oob_right+0x3d/0x75 [test_kasan] - init_module+0x9/0x47 [test_kasan] - do_one_initcall+0x99/0x200 - load_module+0x2cb3/0x3b20 - SyS_finit_module+0x76/0x80 - system_call_fastpath+0x12/0x17 -INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 -INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 - -Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ -Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk -Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. -Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ -Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ -CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 -Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 - ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 - ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 - ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 -Call Trace: - [] dump_stack+0x46/0x58 - [] print_trailer+0xf8/0x160 - [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [] object_err+0x35/0x40 - [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [] kasan_report_error+0x38a/0x3f0 - [] ? kasan_poison_shadow+0x2f/0x40 - [] ? kasan_unpoison_shadow+0x14/0x40 - [] ? kasan_poison_shadow+0x2f/0x40 - [] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [] __asan_store1+0x75/0xb0 - [] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] - [] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [] kmalloc_oob_right+0x65/0x75 [test_kasan] - [] init_module+0x9/0x47 [test_kasan] - [] do_one_initcall+0x99/0x200 - [] ? __vunmap+0xec/0x160 - [] load_module+0x2cb3/0x3b20 - [] ? m_show+0x240/0x240 - [] SyS_finit_module+0x76/0x80 - [] system_call_fastpath+0x12/0x17 -Memory state around the buggy address: - ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc - ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 ->ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc - ^ - ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb -================================================================== - -The header of the report discribe what kind of bug happened and what kind of -access caused it. It's followed by the description of the accessed slub object -(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and -the description of the accessed memory page. - -In the last section the report shows memory state around the accessed address. -Reading this part requires some understanding of how KASAN works. - -The state of each 8 aligned bytes of memory is encoded in one shadow byte. -Those 8 bytes can be accessible, partially accessible, freed or be a redzone. -We use the following encoding for each shadow byte: 0 means that all 8 bytes -of the corresponding memory region are accessible; number N (1 <= N <= 7) means -that the first N bytes are accessible, and other (8 - N) bytes are not; -any negative value indicates that the entire 8-byte word is inaccessible. -We use different negative values to distinguish between different kinds of -inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). - -In the report above the arrows point to the shadow byte 03, which means that -the accessed address is partially accessible. - - -2. Implementation details -========================= - -From a high level, our approach to memory error detection is similar to that -of kmemcheck: use shadow memory to record whether each byte of memory is safe -to access, and use compile-time instrumentation to check shadow memory on each -memory access. - -AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory -(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and -offset to translate a memory address to its corresponding shadow address. - -Here is the function which translates an address to its corresponding shadow -address: - -static inline void *kasan_mem_to_shadow(const void *addr) -{ - return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT) - + KASAN_SHADOW_OFFSET; -} - -where KASAN_SHADOW_SCALE_SHIFT = 3. - -Compile-time instrumentation used for checking memory accesses. Compiler inserts -function calls (__asan_load*(addr), __asan_store*(addr)) before each memory -access of size 1, 2, 4, 8 or 16. These functions check whether memory access is -valid or not by checking corresponding shadow memory. - -GCC 5.0 has possibility to perform inline instrumentation. Instead of making -function calls GCC directly inserts the code to check the shadow memory. -This option significantly enlarges kernel but it gives x1.1-x2 performance -boost over outline instrumented kernel. diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt index db101857b2c9..069fcb3eef6e 100644 --- a/Documentation/kbuild/kconfig-language.txt +++ b/Documentation/kbuild/kconfig-language.txt @@ -274,7 +274,44 @@ menuconfig: This is similar to the simple config entry above, but it also gives a hint to front ends, that all suboptions should be displayed as a -separate list of options. +separate list of options. To make sure all the suboptions will really +show up under the menuconfig entry and not outside of it, every item +from the list must depend on the menuconfig symbol. +In practice, this is achieved by using one of the next two constructs: + +(1): +menuconfig M +if M + config C1 + config C2 +endif + +(2): +menuconfig M +config C1 + depends on M +config C2 + depends on M + +In the following examples (3) and (4), C1 and C2 still have the M +dependency, but will not appear under menuconfig M anymore, because +of C0, which doesn't depend on M: + +(3): +menuconfig M + config C0 +if M + config C1 + config C2 +endif + +(4): +menuconfig M +config C0 +config C1 + depends on M +config C2 + depends on M choices: diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 385a5ef41c17..9b9c4797fc55 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -41,6 +41,7 @@ This document describes the Linux kernel Makefiles. --- 6.8 Custom kbuild commands --- 6.9 Preprocessing linker scripts --- 6.10 Generic header files + --- 6.11 Post-link pass === 7 Kbuild syntax for exported headers --- 7.1 header-y @@ -1237,6 +1238,21 @@ When kbuild executes, the following steps are followed (roughly): to list the file in the Kbuild file. See "7.4 generic-y" for further info on syntax etc. +--- 6.11 Post-link pass + + If the file arch/xxx/Makefile.postlink exists, this makefile + will be invoked for post-link objects (vmlinux and modules.ko) + for architectures to run post-link passes on. Must also handle + the clean target. + + This pass runs after kallsyms generation. If the architecture + needs to modify symbol locations, rather than manipulate the + kallsyms, it may be easier to add another postlink target for + .tmp_vmlinux? targets to be called from link-vmlinux.sh. + + For example, powerpc uses this to check relocation sanity of + the linked vmlinux file. + === 7 Kbuild syntax for exported headers The kernel includes a set of headers that is exported to userspace. diff --git a/Documentation/kcov.txt b/Documentation/kcov.txt deleted file mode 100644 index 779ff4ab1c1d..000000000000 --- a/Documentation/kcov.txt +++ /dev/null @@ -1,111 +0,0 @@ -kcov: code coverage for fuzzing -=============================== - -kcov exposes kernel code coverage information in a form suitable for coverage- -guided fuzzing (randomized testing). Coverage data of a running kernel is -exported via the "kcov" debugfs file. Coverage collection is enabled on a task -basis, and thus it can capture precise coverage of a single system call. - -Note that kcov does not aim to collect as much coverage as possible. It aims -to collect more or less stable coverage that is function of syscall inputs. -To achieve this goal it does not collect coverage in soft/hard interrupts -and instrumentation of some inherently non-deterministic parts of kernel is -disbled (e.g. scheduler, locking). - -Usage: -====== - -Configure kernel with: - - CONFIG_KCOV=y - -CONFIG_KCOV requires gcc built on revision 231296 or later. -Profiling data will only become accessible once debugfs has been mounted: - - mount -t debugfs none /sys/kernel/debug - -The following program demonstrates kcov usage from within a test program: - -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#define KCOV_INIT_TRACE _IOR('c', 1, unsigned long) -#define KCOV_ENABLE _IO('c', 100) -#define KCOV_DISABLE _IO('c', 101) -#define COVER_SIZE (64<<10) - -int main(int argc, char **argv) -{ - int fd; - unsigned long *cover, n, i; - - /* A single fd descriptor allows coverage collection on a single - * thread. - */ - fd = open("/sys/kernel/debug/kcov", O_RDWR); - if (fd == -1) - perror("open"), exit(1); - /* Setup trace mode and trace size. */ - if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE)) - perror("ioctl"), exit(1); - /* Mmap buffer shared between kernel- and user-space. */ - cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long), - PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); - if ((void*)cover == MAP_FAILED) - perror("mmap"), exit(1); - /* Enable coverage collection on the current thread. */ - if (ioctl(fd, KCOV_ENABLE, 0)) - perror("ioctl"), exit(1); - /* Reset coverage from the tail of the ioctl() call. */ - __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED); - /* That's the target syscal call. */ - read(-1, NULL, 0); - /* Read number of PCs collected. */ - n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); - for (i = 0; i < n; i++) - printf("0x%lx\n", cover[i + 1]); - /* Disable coverage collection for the current thread. After this call - * coverage can be enabled for a different thread. - */ - if (ioctl(fd, KCOV_DISABLE, 0)) - perror("ioctl"), exit(1); - /* Free resources. */ - if (munmap(cover, COVER_SIZE * sizeof(unsigned long))) - perror("munmap"), exit(1); - if (close(fd)) - perror("close"), exit(1); - return 0; -} - -After piping through addr2line output of the program looks as follows: - -SyS_read -fs/read_write.c:562 -__fdget_pos -fs/file.c:774 -__fget_light -fs/file.c:746 -__fget_light -fs/file.c:750 -__fget_light -fs/file.c:760 -__fdget_pos -fs/file.c:784 -SyS_read -fs/read_write.c:562 - -If a program needs to collect coverage from several threads (independently), -it needs to open /sys/kernel/debug/kcov in each thread separately. - -The interface is fine-grained to allow efficient forking of test processes. -That is, a parent process opens /sys/kernel/debug/kcov, enables trace mode, -mmaps coverage buffer and then forks child processes in a loop. Child processes -only need to enable coverage (disable happens automatically on thread end). diff --git a/Documentation/kdump/kdump.txt b/Documentation/kdump/kdump.txt index 88ff63d5fde3..b0eb27b956d9 100644 --- a/Documentation/kdump/kdump.txt +++ b/Documentation/kdump/kdump.txt @@ -393,6 +393,15 @@ Notes on loading the dump-capture kernel: * We generally don' have to bring up a SMP kernel just to capture the dump. Hence generally it is useful either to build a UP dump-capture kernel or specify maxcpus=1 option while loading dump-capture kernel. + Note, though maxcpus always works, you had better replace it with + nr_cpus to save memory if supported by the current ARCH, such as x86. + +* You should enable multi-cpu support in dump-capture kernel if you intend + to use multi-thread programs with it, such as parallel dump feature of + makedumpfile. Otherwise, the multi-thread program may have a great + performance degradation. To enable multi-cpu support, you should bring up an + SMP dump-capture kernel and specify maxcpus/nr_cpus, disable_cpu_apicid=[X] + options while loading it. * For s390x there are two kdump modes: If a ELF header is specified with the elfcorehdr= kernel parameter, it is used by the kdump kernel as it diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt index 1dafc52167b0..05a7857a4a83 100644 --- a/Documentation/kernel-docs.txt +++ b/Documentation/kernel-docs.txt @@ -1,731 +1,652 @@ +.. _kernel_docs: - Index of Documentation for People Interested in Writing and/or - - Understanding the Linux Kernel. +Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel +============================================================================================= Juan-Mariano de Goyeneche -/* - * The latest version of this document may be found at: - * http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html - */ - - The need for a document like this one became apparent in the - linux-kernel mailing list as the same questions, asking for pointers - to information, appeared again and again. - - Fortunately, as more and more people get to GNU/Linux, more and more - get interested in the Kernel. But reading the sources is not always - enough. It is easy to understand the code, but miss the concepts, the - philosophy and design decisions behind this code. - - Unfortunately, not many documents are available for beginners to - start. And, even if they exist, there was no "well-known" place which - kept track of them. These lines try to cover this lack. All documents - available on line known by the author are listed, while some reference - books are also mentioned. - - PLEASE, if you know any paper not listed here or write a new document, - send me an e-mail, and I'll include a reference to it here. Any - corrections, ideas or comments are also welcomed. - - The papers that follow are listed in no particular order. All are - cataloged with the following fields: the document's "Title", the - "Author"/s, the "URL" where they can be found, some "Keywords" helpful - when searching for specific topics, and a brief "Description" of the - Document. - - Enjoy! - - ON-LINE DOCS: - - * Title: "Linux Device Drivers, Third Edition" - Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - URL: http://lwn.net/Kernel/LDD3/ - Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - - * Title: "The Linux Kernel" - Author: David A. Rusling. - URL: http://www.tldp.org/LDP/tlk/tlk.html - Keywords: everything!, book. - Description: On line, 200 pages book describing most aspects of - the Linux Kernel. Probably, the first reference for beginners. - Lots of illustrations explaining data structures use and - relationships in the purest Richard W. Stevens' style. Contents: - "1.-Hardware Basics, 2.-Software Basics, 3.-Memory Management, - 4.-Processes, 5.-Interprocess Communication Mechanisms, 6.-PCI, - 7.-Interrupts and Interrupt Handling, 8.-Device Drivers, 9.-The - File system, 10.-Networks, 11.-Kernel Mechanisms, 12.-Modules, - 13.-The Linux Kernel Sources, A.-Linux Data Structures, B.-The - Alpha AXP Processor, C.-Useful Web and FTP Sites, D.-The GNU - General Public License, Glossary". In short: a must have. - - * Title: "Linux Device Drivers, 2nd Edition" - Author: Alessandro Rubini and Jonathan Corbet. - URL: http://www.xml.com/ldd/chapter/book/index.html - Keywords: device drivers, modules, debugging, memory, hardware, - interrupt handling, char drivers, block drivers, kmod, mmap, DMA, - buses. - Description: O'Reilly's popular book, now also on-line under the - GNU Free Documentation License. - Notes: You can also buy it in paper-form from O'Reilly. See below - under BOOKS (Not on-line). - - * Title: "Conceptual Architecture of the Linux Kernel" - Author: Ivan T. Bowman. - URL: http://plg.uwaterloo.ca/ - Keywords: conceptual software architecture, extracted design, - reverse engineering, system structure. - Description: Conceptual software architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. - - * Title: "Concrete Architecture of the Linux Kernel" - Author: Ivan T. Bowman, Saheem Siddiqi, and Meyer C. Tanuan. - URL: http://plg.uwaterloo.ca/ - Keywords: concrete architecture, extracted design, reverse - engineering, system structure, dependencies. - Description: Concrete architecture of the Linux kernel, - automatically extracted from the source code. Very detailed. Good - figures. Gives good overall kernel understanding. This papers - focus on lower details than its predecessor (files, variables...). - - * Title: "Linux as a Case Study: Its Extracted Software - Architecture" - Author: Ivan T. Bowman, Richard C. Holt and Neil V. Brewster. - URL: http://plg.uwaterloo.ca/ - Keywords: software architecture, architecture recovery, - redocumentation. - Description: Paper appeared at ICSE'99, Los Angeles, May 16-22, - 1999. A mixture of the previous two documents from the same - author. - - * Title: "Overview of the Virtual File System" - Author: Richard Gooch. - URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. - - * Title: "The Linux RAID-1, 4, 5 Code" - Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - URL: http://www.linuxjournal.com/article.php?sid=2391 - Keywords: RAID, MD driver. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software". - - * Title: "Dynamic Kernels: Modularized Device Drivers" - Author: Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1219 - Keywords: device driver, module, loading/unloading modules, - allocating resources. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment". - - * Title: "Dynamic Kernels: Discovery" - Author: Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1220 - Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls". - - * Title: "The Devil's in the Details" - Author: Georg v. Zezschwitz and Alessandro Rubini. - URL: http://www.linuxjournal.com/article.php?sid=1221 - Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls". - - * Title: "Dissecting Interrupts and Browsing DMA" - Author: Alessandro Rubini and Georg v. Zezschwitz. - URL: http://www.linuxjournal.com/article.php?sid=1222 - Keywords: interrupts, irqs, DMA, bottom halves, task queues. - Description: Linux Journal Kernel Korner article. Here is its - abstract: "This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ``interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA". - - * Title: "Device Drivers Concluded" - Author: Georg v. Zezschwitz. - URL: http://www.linuxjournal.com/article.php?sid=1287 - Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: "Network Buffers And Memory Management" - Author: Alan Cox. - URL: http://www.linuxjournal.com/article.php?sid=1312 - Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - Description: Linux Journal Kernel Korner. Here is the abstract: - "Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory". - - * Title: "Linux Kernel Hackers' Guide" - Author: Michael K. Johnson. - URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: "The Venus kernel interface" - Author: Peter J. Braam. - URL: - http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - Keywords: coda, filesystem, venus, cache manager. - Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: "Programming PCI-Devices under Linux" - Author: Claus Schroeter. - URL: - ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/pcip.ps.gz - Keywords: PCI, device, busmastering. - Description: 6 pages tutorial on PCI programming under Linux. - Gives the basic concepts on the architecture of the PCI subsystem, - as long as basic functions and macros to read/write the devices - and perform busmastering. - - * Title: "Writing Character Device Driver for Linux" - Author: R. Baruch and C. Schroeter. - URL: - ftp://ftp.llp.fu-berlin.de/pub/linux/LINUX-LAB/whitepapers/drivers.ps.gz - Keywords: character device drivers, I/O, signals, DMA, accessing - ports in user space, kernel environment. - Description: 68 pages paper on writing character drivers. A little - bit old (1.993, 1.994) although still useful. - - * Title: "Design and Implementation of the Second Extended - Filesystem" - Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: "Analysis of the Ext2fs structure" - Author: Louis-Dominique Dubeau. - URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - Keywords: ext2, filesystem, ext2fs. - Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - - * Title: "Journaling the Linux ext2fs Filesystem" - Author: Stephen C. Tweedie. - URL: - ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz - Keywords: ext3, journaling. - Description: Excellent 8-pages paper explaining the journaling - capabilities added to ext2 by the author, showing different - problems faced and the alternatives chosen. - - * Title: "Kernel API changes from 2.0 to 2.2" - Author: Richard Gooch. - URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.2.html - Keywords: 2.2, changes. - Description: Kernel functions/structures/variables which changed - from 2.0.x to 2.2.x. - - * Title: "Kernel API changes from 2.2 to 2.4" - Author: Richard Gooch. - URL: http://www.safe-mbox.com/~rgooch/linux/docs/porting-to-2.4.html - Keywords: 2.4, changes. - Description: Kernel functions/structures/variables which changed - from 2.2.x to 2.4.x. - - * Title: "Linux Kernel Module Programming Guide" - Author: Ori Pomerantz. - URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: "I/O Event Handling Under Linux" - Author: Richard Gooch. - Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: "The Kernel Hacking HOWTO" - Author: Various Talented People, and Rusty. - Location: in kernel tree, Documentation/DocBook/kernel-hacking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - - * Title: "Writing an ALSA Driver" - Author: Takashi Iwai - URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: "Programming Guide for Linux USB Device Drivers" - Author: Detlef Fliegl. - URL: http://usb.in.tum.de/usbdoc/ - Keywords: USB, universal serial bus. - Description: A must-read. From the Preface: "This document should - give detailed information about the current state of the USB - subsystem and its API for USB device drivers. The first section - will deal with the basics of USB devices. You will learn about - different types of devices and their properties. Going into detail - you will see how USB devices communicate on the bus. The second - section gives an overview of the Linux USB subsystem [2] and the - device driver framework. Then the API and its data structures will - be explained step by step. The last section of this document - contains a reference of all API calls and their return codes". - Notes: Beware: the main page states: "This document may not be - published, printed or used in excerpts without explicit permission - of the author". Fortunately, it may still be read... - - * Title: "Linux Kernel Mailing List Glossary" - Author: various - URL: http://kernelnewbies.org/glossary/ - Keywords: glossary, terms, linux-kernel. - Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: "Linux Kernel Locking HOWTO" - Author: Various Talented People, and Rusty. - Location: in kernel tree, Documentation/DocBook/kernel-locking.tmpl - (must be built as "make {htmldocs | psdocs | pdfdocs}) - Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. - - * Title: "Global spinlock list and usage" - Author: Rick Lindsley. - URL: http://lse.sourceforge.net/lockhier/global-spin-lock - Keywords: spinlock. - Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: "Porting Linux 2.0 Drivers To Linux 2.2: Changes and New - Features " - Author: Alan Cox. - URL: http://www.linux-mag.com/1999-05/gear_01.html - Keywords: ports, porting. - Description: Article from Linux Magazine on porting from 2.0 to - 2.2 kernels. - - * Title: "Porting Device Drivers To Linux 2.2: part II" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/238 - Keywords: ports, porting. - Description: Second part on porting from 2.0 to 2.2 kernels. - - * Title: "How To Make Sure Your Driver Will Work On The Power - Macintosh" - Author: Paul Mackerras. - URL: http://www.linux-mag.com/id/261 - Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - Description: The title says it all. - - * Title: "An Introduction to SCSI Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/284 - Keywords: SCSI, device, driver. - Description: The title says it all. - - * Title: "Advanced SCSI Drivers And Other Tales" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/307 - Keywords: SCSI, device, driver, advanced. - Description: The title says it all. - - * Title: "Writing Linux Mouse Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/330 - Keywords: mouse, driver, gpm. - Description: The title says it all. - - * Title: "More on Mouse Drivers" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/356 - Keywords: mouse, driver, gpm, races, asynchronous I/O. - Description: The title still says it all. - - * Title: "Writing Video4linux Radio Driver" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/381 - Keywords: video4linux, driver, radio, radio devices. - Description: The title says it all. - - * Title: "Video4linux Drivers, Part 1: Video-Capture Device" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/406 - Keywords: video4linux, driver, video capture, capture devices, - camera driver. - Description: The title says it all. - - * Title: "Video4linux Drivers, Part 2: Video-capture Devices" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/429 - Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - Description: The title says it all. - - * Title: "PCI Management in Linux 2.2" - Author: Alan Cox. - URL: http://www.linux-mag.com/id/452 - Keywords: PCI, bus, bus-mastering. - Description: The title says it all. - - * Title: "Linux 2.4 Kernel Internals" - Author: Tigran Aivazian and Christoph Hellwig. - URL: http://www.moses.uklinux.net/patches/lki.html - Keywords: Linux, kernel, booting, SMB boot, VFS, page cache. - Description: A little book used for a short training course. - Covers building the kernel image, booting (including SMP bootup), - process management, VFS and more. - - * Title: "Linux IP Networking. A Guide to the Implementation and - Modification of the Linux Protocol Stack." - Author: Glenn Herrin. - URL: http://www.cs.unh.edu/cnrg/gherrin - Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: "Get those boards talking under Linux." - Author: Alex Ivchenko. - URL: http://www.edn.com/article/CA46968.html - Keywords: data-acquisition boards, drivers, modules, interrupts, - memory allocation. - Description: Article written for people wishing to make their data - acquisition boards work on their GNU/Linux machines. Gives a basic - overview on writing drivers, from the naming of functions to - interrupt handling. - Notes: Two-parts article. Part II is at - URL: http://www.edn.com/article/CA46998.html - - * Title: "Linux PCMCIA Programmer's Guide" - Author: David Hinds. - URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - Keywords: PCMCIA. - Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: "The Linux Kernel NFSD Implementation" - Author: Neil Brown. - URL: - http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/nfsd.html - Keywords: knfsd, nfsd, NFS, RPC, lockd, mountd, statd. - Description: The title says it all. - Notes: Covers knfsd's version 1.4.7 (patch against 2.2.7 kernel). - - * Title: "A Linux vm README" - Author: Kanoj Sarcar. - URL: http://kos.enix.org/pub/linux-vmm.html - Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: "(nearly) Complete Linux Loadable Kernel Modules. The - definitive guide for hackers, virus coders and system - administrators." - Author: pragmatic/THC. - URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - Keywords: syscalls, intercept, hide, abuse, symbol table. - Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - BOOKS: (Not on-line) - - * Title: "Linux Device Drivers" - Author: Alessandro Rubini. - Publisher: O'Reilly & Associates. - Date: 1998. - Pages: 439. - ISBN: 1-56592-292-1 - - * Title: "Linux Device Drivers, 2nd Edition" - Author: Alessandro Rubini and Jonathan Corbet. - Publisher: O'Reilly & Associates. - Date: 2001. - Pages: 586. - ISBN: 0-59600-008-1 - Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive2/ - - * Title: "Linux Device Drivers, 3rd Edition" - Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - Publisher: O'Reilly & Associates. - Date: 2005. - Pages: 636. - ISBN: 0-596-00590-3 - Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ - - * Title: "Linux Kernel Internals" - Author: Michael Beck. - Publisher: Addison-Wesley. - Date: 1997. - ISBN: 0-201-33143-8 (second edition) - - * Title: "The Design of the UNIX Operating System" - Author: Maurice J. Bach. - Publisher: Prentice Hall. - Date: 1986. - Pages: 471. - ISBN: 0-13-201757-1 - - * Title: "The Design and Implementation of the 4.3 BSD UNIX - Operating System" - Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J. - Karels, John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1989 (reprinted with corrections on October, 1990). - ISBN: 0-201-06196-1 - - * Title: "The Design and Implementation of the 4.4 BSD UNIX - Operating System" - Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman. - Publisher: Addison-Wesley. - Date: 1996. - ISBN: 0-201-54979-4 - - * Title: "Programmation Linux 2.0 API systeme et fonctionnement du - noyau" - Author: Remy Card, Eric Dumas, Franck Mevel. - Publisher: Eyrolles. - Date: 1997. - Pages: 520. - ISBN: 2-212-08932-5 - Notes: French. - - * Title: "Unix internals -- the new frontiers" - Author: Uresh Vahalia. - Publisher: Prentice Hall. - Date: 1996. - Pages: 600. - ISBN: 0-13-101908-2 - - * Title: "Programming for the real world - POSIX.4" - Author: Bill O. Gallmeister. - Publisher: O'Reilly & Associates, Inc.. - Date: 1995. - Pages: ???. - ISBN: I-56592-074-0 - Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. - - * Title: "UNIX Systems for Modern Architectures: Symmetric - Multiprocessing and Caching for Kernel Programmers" - Author: Curt Schimmel. - Publisher: Addison Wesley. - Date: June, 1994. - Pages: 432. - ISBN: 0-201-63338-8 - - * Title: "Linux Kernel Development, 3rd Edition" - Author: Robert Love - Publisher: Addison-Wesley. - Date: July, 2010 - Pages: 440 - ISBN: 978-0672329463 - - MISCELLANEOUS: - - * Name: linux/Documentation - Author: Many. - URL: Just look inside your kernel sources. - Keywords: anything, DocBook. - Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. - - * Name: "Linux Kernel Source Reference" - Author: Thomas Graichen. - URL: http://marc.info/?l=linux-kernel&m=96446640102205&w=4 - Keywords: CVS, web, cvsweb, browsing source code. - Description: Web interface to a CVS server with the kernel - sources. "Here you can have a look at any file of the Linux kernel - sources of any version starting from 1.0 up to the (daily updated) - current version available. Also you can check the differences - between two versions of a file". - - * Name: "Cross-Referencing Linux" - URL: http://lxr.free-electrons.com/ - Keywords: Browsing source code. - Description: Another web-based Linux kernel source code browser. - Lots of cross references to variables and functions. You can see - where they are defined and where they are used. - - * Name: "Linux Weekly News" - URL: http://lwn.net - Keywords: latest kernel news. - Description: The title says it all. There's a fixed kernel section - summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. - - * Name: "Kernel Traffic" - URL: http://kt.earth.li/kernel-traffic/index.html - Keywords: linux-kernel mailing list, weekly kernel news. - Description: Weekly newsletter covering the most relevant - discussions of the linux-kernel mailing list. - - * Name: "CuTTiNG.eDGe.LiNuX" - URL: http://edge.kernelnotes.org - Keywords: changelist. - Description: Site which provides the changelist for every kernel - release. What's new, what's better, what's changed. Myrdraal reads - the patches and describes them. Pointers to the patches are there, - too. - - * Name: "New linux-kernel Mailing List FAQ" - URL: http://www.tux.org/lkml/ - Keywords: linux-kernel mailing list FAQ. - Description: linux-kernel is a mailing list for developers to - communicate. This FAQ builds on the previous linux-kernel mailing - list FAQ maintained by Frohwalt Egerer, who no longer maintains - it. Read it to see how to join the mailing list. Dozens of - interesting questions regarding the list, Linux, developers (who - is ...?), terms (what is...?) are answered here too. Just read it. - - * Name: "Linux Virtual File System" - Author: Peter J. Braam. - URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - Keywords: slides, VFS, inode, superblock, dentry, dcache. - Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - - * Name: "Gary's Encyclopedia - The Linux Kernel" - Author: Gary (I suppose...). - URL: http://slencyclopedia.berlios.de/index.html - Keywords: linux, community, everything! - Description: Gary's Encyclopedia exists to allow the rapid finding - of documentation and other information of interest to GNU/Linux - users. It has about 4000 links to external pages in 150 major - categories. This link is for kernel-specific links, documents, - sites... This list is now hosted by developer.Berlios.de, - but seems not to have been updated since sometime in 1999. - - * Name: "The home page of Linux-MM" - Author: The Linux-MM team. - URL: http://linux-mm.org/ - Keywords: memory management, Linux-MM, mm patches, TODO, docs, - mailing list. - Description: Site devoted to Linux Memory Management development. - Memory related patches, HOWTOs, links, mm developers... Don't miss - it if you are interested in memory management development! - - * Name: "Kernel Newbies IRC Channel and Website" - URL: http://www.kernelnewbies.org - Keywords: IRC, newbies, channel, asking doubts. - Description: #kernelnewbies on irc.oftc.net. - #kernelnewbies is an IRC network dedicated to the 'newbie' - kernel hacker. The audience mostly consists of people who are - learning about the kernel, working on kernel projects or - professional kernel hackers that want to help less seasoned kernel - people. - #kernelnewbies is on the OFTC IRC Network. - Try irc.oftc.net as your server and then /join #kernelnewbies. - The kernelnewbies website also hosts articles, documents, FAQs... - - * Name: "linux-kernel mailing list archives and search engines" - URL: http://vger.kernel.org/vger-lists.html - URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - URL: http://marc.theaimsgroup.com/?l=linux-kernel - URL: http://groups.google.com/group/mlist.linux.kernel - URL: http://www.cs.helsinki.fi/linux/linux-kernel/ - URL: http://www.lib.uaa.alaska.edu/linux-kernel/ - Keywords: linux-kernel, archives, search. - Description: Some of the linux-kernel mailing list archivers. If - you have a better/another one, please let me know. - _________________________________________________________________ - - Document last updated on Sat 2005-NOV-19 +The need for a document like this one became apparent in the +linux-kernel mailing list as the same questions, asking for pointers +to information, appeared again and again. + +Fortunately, as more and more people get to GNU/Linux, more and more +get interested in the Kernel. But reading the sources is not always +enough. It is easy to understand the code, but miss the concepts, the +philosophy and design decisions behind this code. + +Unfortunately, not many documents are available for beginners to +start. And, even if they exist, there was no "well-known" place which +kept track of them. These lines try to cover this lack. All documents +available on line known by the author are listed, while some reference +books are also mentioned. + +PLEASE, if you know any paper not listed here or write a new document, +send me an e-mail, and I'll include a reference to it here. Any +corrections, ideas or comments are also welcomed. + +The papers that follow are listed in no particular order. All are +cataloged with the following fields: the document's "Title", the +"Author"/s, the "URL" where they can be found, some "Keywords" helpful +when searching for specific topics, and a brief "Description" of the +Document. + +Enjoy! + +.. note:: + + The documents on each section of this document are ordered by its + published date, from the newest to the oldest. + +Docs at the Linux Kernel tree +----------------------------- + +The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. +The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. + + * Name: **linux/Documentation** + + :Author: Many. + :Location: Documentation/ + :Keywords: text files, Sphinx, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-hacking.tmpl + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-locking.tmpl + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + +On-line docs +------------ + + * Title: **Linux Kernel Mailing List Glossary** + + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Date: rolling version + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Date: 2016 + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Date: 2008 + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. + + * Title: **Overview of the Virtual File System** + + :Author: Richard Gooch. + :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Date: 2007 + :Keywords: VFS, File System, mounting filesystems, opening files, + dentries, dcache. + :Description: Brief introduction to the Linux Virtual File System. + What is it, how it works, operations taken when opening a file or + mounting a file system and description of important data + structures explaining the purpose of each of their entries. + + * Title: **Linux Device Drivers, Third Edition** + + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Date: 2005 + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. + :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Date: 2005 + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Date: 2003 + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **Linux Kernel Module Programming Guide** + + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Date: 2001 + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Date: 2001 + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Date: 2001 + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Date: 2000 + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Date: 1999 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Date: 1999 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Date: 1999 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Date: 1999 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Date: 1999 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Date: 1999 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :URL: http://web.mit.edu/~yandros/doc/io-events.html + :Date: 1999 + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Date: 1999 + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. + + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Date: 1998 + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + + * Title: **The Venus kernel interface** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Date: 1998 + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". + + * Title: **Design and Implementation of the Second Extended Filesystem** + + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Date: 1998 + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + + * Title: **The Linux RAID-1, 4, 5 Code** + + :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. + :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Date: 1997 + :Keywords: RAID, MD driver. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *A description of the implementation of the RAID-1, + RAID-4 and RAID-5 personalities of the MD device driver in the + Linux kernel, providing users with high performance and reliable, + secondary-storage capability using software*. + + * Title: **Linux Kernel Hackers' Guide** + + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Date: 1997 + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. + + * Title: **Dynamic Kernels: Modularized Device Drivers** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Date: 1996 + :Keywords: device driver, module, loading/unloading modules, + allocating resources. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the first of a series of four articles + co-authored by Alessandro Rubini and Georg Zezchwitz which present + a practical approach to writing Linux device drivers as kernel + loadable modules. This installment presents an introduction to the + topic, preparing the reader to understand next month's + installment*. + + * Title: **Dynamic Kernels: Discovery** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Date: 1996 + :Keywords: character driver, init_module, clean_up module, + autodetection, mayor number, minor number, file operations, + open(), close(). + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the second of four, introduces part of + the actual code to create custom module implementing a character + device driver. It describes the code for module initialization and + cleanup, as well as the open() and close() system calls*. + + * Title: **The Devil's in the Details** + + :Author: Georg v. Zezschwitz and Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Date: 1996 + :Keywords: read(), write(), select(), ioctl(), blocking/non + blocking mode, interrupt handler. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the third of four on writing character + device drivers, introduces concepts of reading, writing, and using + ioctl-calls*. + + * Title: **Dissecting Interrupts and Browsing DMA** + + :Author: Alessandro Rubini and Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Date: 1996 + :Keywords: interrupts, irqs, DMA, bottom halves, task queues. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the fourth in a series of articles about + writing character device drivers as loadable kernel modules. This + month, we further investigate the field of interrupt handling. + Though it is conceptually simple, practical limitations and + constraints make this an ''interesting'' part of device driver + writing, and several different facilities have been provided for + different situations. We also investigate the complex topic of + DMA*. + + * Title: **Device Drivers Concluded** + + :Author: Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Date: 1996 + :Keywords: address spaces, pages, pagination, page management, + demand loading, swapping, memory protection, memory mapping, mmap, + virtual memory areas (VMAs), vremap, PCI. + :Description: Finally, the above turned out into a five articles + series. This latest one's introduction reads: "This is the last of + five articles about character device drivers. In this final + section, Georg deals with memory mapping devices, beginning with + an overall description of the Linux memory management concepts". + + * Title: **Network Buffers And Memory Management** + + :Author: Alan Cox. + :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Date: 1996 + :Keywords: sk_buffs, network devices, protocol/link layer + variables, network devices flags, transmit, receive, + configuration, multicast. + :Description: Linux Journal Kernel Korner. + :Abstract: *Writing a network device driver for Linux is fundamentally + simple---most of the complexity (other than talking to the + hardware) involves managing network packets in memory*. + + * Title: **Analysis of the Ext2fs structure** + + :Author: Louis-Dominique Dubeau. + :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Date: 1994 + :Keywords: ext2, filesystem, ext2fs. + :Description: Description of ext2's blocks, directories, inodes, + bitmaps, invariants... + +Published books +--------------- + + * Title: **Linux Treiber entwickeln** + + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. + + * Title: **Linux Kernel Networking: Implementation and Theory** + + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 + + * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** + + :Author: Christopher Hallinan + :Publisher: Pearson + :Date: November, 2010 + :Pages: 656 + :ISBN: 978-0137017836 + + * Title: **Linux Kernel Development, 3rd Edition** + + :Author: Robert Love + :Publisher: Addison-Wesley + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 + + * Title: **Essential Linux Device Drivers** + + :Author: Sreekrishnan Venkateswaran + :Published: Prentice Hall + :Date: April, 2008 + :Pages: 744 + :ISBN: 978-0132396554 + +.. _ldd3_published: + + * Title: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publisher: O'Reilly & Associates + :Date: 2005 + :Pages: 636 + :ISBN: 0-596-00590-3 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive3/ + PDF format, URL: http://lwn.net/Kernel/LDD3/ + + * Title: **Linux Kernel Internals** + + :Author: Michael Beck + :Publisher: Addison-Wesley + :Date: 1997 + :ISBN: 0-201-33143-8 (second edition) + + * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** + + :Author: Remy Card, Eric Dumas, Franck Mevel + :Publisher: Eyrolles + :Date: 1997 + :Pages: 520 + :ISBN: 2-212-08932-5 + :Notes: French + + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 + :ISBN: 0-201-54979-4 + + * Title: **Unix internals -- the new frontiers** + + :Author: Uresh Vahalia + :Publisher: Prentice Hall + :Date: 1996 + :Pages: 600 + :ISBN: 0-13-101908-2 + + * Title: **Programming for the real world - POSIX.4** + + :Author: Bill O. Gallmeister + :Publisher: O'Reilly & Associates, Inc + :Date: 1995 + :Pages: 552 + :ISBN: I-56592-074-0 + :Notes: Though not being directly about Linux, Linux aims to be + POSIX. Good reference. + + * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** + + :Author: Curt Schimmel + :Publisher: Addison Wesley + :Date: June, 1994 + :Pages: 432 + :ISBN: 0-201-63338-8 + + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** + + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1989 (reprinted with corrections on October, 1990) + :ISBN: 0-201-06196-1 + + * Title: **The Design of the UNIX Operating System** + + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 + :ISBN: 0-13-201757-1 + +Miscellaneous +------------- + + * Name: **Cross-Referencing Linux** + + :URL: http://lxr.free-electrons.com/ + :Keywords: Browsing source code. + :Description: Another web-based Linux kernel source code browser. + Lots of cross references to variables and functions. You can see + where they are defined and where they are used. + + * Name: **Linux Weekly News** + + :URL: http://lwn.net + :Keywords: latest kernel news. + :Description: The title says it all. There's a fixed kernel section + summarizing developers' work, bug fixes, new features and versions + produced during the week. Published every Thursday. + + * Name: **The home page of Linux-MM** + + :Author: The Linux-MM team. + :URL: http://linux-mm.org/ + :Keywords: memory management, Linux-MM, mm patches, TODO, docs, + mailing list. + :Description: Site devoted to Linux Memory Management development. + Memory related patches, HOWTOs, links, mm developers... Don't miss + it if you are interested in memory management development! + + * Name: **Kernel Newbies IRC Channel and Website** + + :URL: http://www.kernelnewbies.org + :Keywords: IRC, newbies, channel, asking doubts. + :Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' + kernel hacker. The audience mostly consists of people who are + learning about the kernel, working on kernel projects or + professional kernel hackers that want to help less seasoned kernel + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... + + * Name: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Keywords: linux-kernel, archives, search. + :Description: Some of the linux-kernel mailing list archivers. If + you have a better/another one, please let me know. + +------- + +Document last updated on Tue 2016-Sep-20 + +This document is based on: + http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index 391decc66a18..10cc7ddb6235 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -107,6 +107,35 @@ Here are some specific guidelines for the kernel documentation: the order as encountered."), having the higher levels the same overall makes it easier to follow the documents. + +the C domain +------------ + +The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a +function prototype: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + +The C domain of the kernel-doc has some additional features. E.g. you can +*rename* the reference name of a function with a common name like ``open`` or +``ioctl``: + +.. code-block:: rst + + .. c:function:: int ioctl( int fd, int request ) + :name: VIDIOC_LOG_STATUS + +The func-name (e.g. ioctl) remains in the output but the ref-name changed from +``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also +changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by: + +.. code-block:: rst + + :c:func:`VIDIOC_LOG_STATUS` + + list tables ----------- @@ -265,6 +294,8 @@ The kernel-doc extension is included in the kernel source tree, at ``scripts/kernel-doc`` script to extract the documentation comments from the source. +.. _kernel_doc: + Writing kernel-doc comments =========================== diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index a4f4d693e2c1..37babf91f2cb 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -33,6 +33,37 @@ can also be entered as Double-quotes can be used to protect spaces in values, e.g.: param="spaces in here" +cpu lists: +---------- + +Some kernel parameters take a list of CPUs as a value, e.g. isolcpus, +nohz_full, irqaffinity, rcu_nocbs. The format of this list is: + + ,..., + +or + + - + (must be a positive range in ascending order) + +or a mixture + +,...,- + +Note that for the special case of a range one can split the range into equal +sized groups and for each group use some amount from the beginning of that +group: + + -cpu number>:/ + +For example one can add to the command line following parameter: + + isolcpus=1,2,10-20,100-2000:2/25 + +where the final item represents CPUs 100,101,125,126,150,151,... + + + This document may not be entirely up to date and comprehensive. The command "modinfo -p ${modulename}" shows a current list of all parameters of a loadable module. Loadable modules, after being loaded into the running kernel, also @@ -460,6 +491,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. driver will print ACPI tables for AMD IOMMU during IOMMU initialization. + amd_iommu_intr= [HW,X86-64] + Specifies one of the following AMD IOMMU interrupt + remapping modes: + legacy - Use legacy interrupt remapping mode. + vapic - Use virtual APIC mode, which allows IOMMU + to inject interrupts directly into guest. + This mode requires kvm-amd.avic=1. + (Default when IOMMU HW support is present.) + amijoy.map= [HW,JOY] Amiga joystick support Map of devices attached to JOY0DAT and JOY1DAT Format: , @@ -698,6 +738,15 @@ bytes respectively. Such letter suffixes can also be entirely omitted. loops can be debugged more effectively on production systems. + clocksource.arm_arch_timer.fsl-a008585= + [ARM64] + Format: + Enable/disable the workaround of Freescale/NXP + erratum A-008585. This can be useful for KVM + guests, if the guest device tree doesn't show the + erratum. If unspecified, the workaround is + enabled based on the device tree. + clearcpuid=BITNUM [X86] Disable CPUID feature X for the kernel. See arch/x86/include/asm/cpufeatures.h for the valid bit @@ -1045,11 +1094,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. determined by the stdout-path property in device tree's chosen node. - cdns, - Start an early, polled-mode console on a cadence serial - port at the specified address. The cadence serial port - must already be setup and configured. Options are not - yet supported. + cdns,[,options] + Start an early, polled-mode console on a Cadence + (xuartps) serial port at the specified address. Only + supported option is baud rate. If baud rate is not + specified, the serial port must already be setup and + configured. uart[8250],io,[,options] uart[8250],mmio,[,options] @@ -1364,6 +1414,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: such that (rxsize & ~0x1fffc0) == 0. Default: 1024 + gpio-mockup.gpio_mockup_ranges + [HW] Sets the ranges of gpiochip of for this device. + Format: ,,,... + hardlockup_all_cpu_backtrace= [KNL] Should the hard-lockup detector generate backtraces on all cpus. @@ -1457,7 +1511,14 @@ bytes respectively. Such letter suffixes can also be entirely omitted. i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX controllers i8042.notimeout [HW] Ignore timeout condition signalled by controller - i8042.reset [HW] Reset the controller during init and cleanup + i8042.reset [HW] Reset the controller during init, cleanup and + suspend-to-ram transitions, only during s2r + transitions, or never reset + Format: { 1 | Y | y | 0 | N | n } + 1, Y, y: always reset controller + 0, N, n: don't ever reset controller + Default: only on s2r transitions on x86; most other + architectures force reset to be always executed i8042.unlock [HW] Unlock (ignore) the keylock i8042.kbdreset [HW] Reset device connected to KBD port @@ -1643,6 +1704,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. initrd= [BOOT] Specify the location of the initial ramdisk + init_pkru= [x86] Specify the default memory protection keys rights + register contents for all processes. 0x55555554 by + default (disallow access to all but pkey 0). Can + override in debugfs after boot. + inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver Format: @@ -1688,7 +1754,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. intel_idle.max_cstate= [KNL,HW,ACPI,X86] 0 disables intel_idle and fall back on acpi_idle. - 1 to 6 specify maximum depth of C-state. + 1 to 9 specify maximum depth of C-state. intel_pstate= [X86] disable @@ -1761,13 +1827,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See Documentation/filesystems/nfs/nfsroot.txt. irqaffinity= [SMP] Set the default irq affinity mask - Format: - ,..., - or - - - (must be a positive range in ascending order) - or a mixture - ,...,- + The argument is a cpu list, as described above. irqfixup [HW] When an interrupt is not handled search all handlers @@ -1784,13 +1844,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: ,,, isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. - Format: - ,..., - or - - - (must be a positive range in ascending order) - or a mixture - ,...,- + The argument is a cpu list, as described above. This option can be used to specify one or more CPUs to isolate from the general SMP balancing and scheduling @@ -2161,10 +2215,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. than or equal to this physical address is ignored. maxcpus= [SMP] Maximum number of processors that an SMP kernel - should make use of. maxcpus=n : n >= 0 limits the - kernel to using 'n' processors. n=0 is a special case, - it is equivalent to "nosmp", which also disables - the IO APIC. + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. max_loop= [LOOP] The number of loop block devices that get (loop.max_loop) unconditionally pre-created at init time. The default @@ -2420,6 +2477,11 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nfsrootdebug [NFS] enable nfsroot debugging messages. See Documentation/filesystems/nfs/nfsroot.txt. + nfs.callback_nr_threads= + [NFSv4] set the total number of threads that the + NFS client will assign to service NFSv4 callback + requests. + nfs.callback_tcpport= [NFS] set the TCP port on which the NFSv4 callback channel should listen. @@ -2443,6 +2505,13 @@ bytes respectively. Such letter suffixes can also be entirely omitted. of returning the full 64-bit number. The default is to return 64-bit inode numbers. + nfs.max_session_cb_slots= + [NFSv4.1] Sets the maximum number of session + slots the client will assign to the callback + channel. This determines the maximum number of + callbacks the client will process in parallel for + a particular server. + nfs.max_session_slots= [NFSv4.1] Sets the maximum number of session slots the client will attempt to negotiate with the server. @@ -2571,8 +2640,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nodelayacct [KNL] Disable per-task delay accounting - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - nodsp [SH] Disable hardware DSP at boot time. noefi Disable EFI runtime services support. @@ -2651,6 +2718,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Default: on nohz_full= [KNL,BOOT] + The argument is a cpu list, as described above. In kernels built with CONFIG_NO_HZ_FULL=y, set the specified list of CPUs whose tick will be stopped whenever possible. The boot CPU will be forced outside @@ -2773,9 +2841,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nr_cpus= [SMP] Maximum number of processors that an SMP kernel could support. nr_cpus=n : n >= 1 limits the kernel to - supporting 'n' processors. Later in runtime you can not - use hotplug cpu feature to put more cpu back to online. - just like you compile the kernel NR_CPUS=n + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. nr_uarts= [SERIAL] maximum number of UARTs to be registered. @@ -3253,6 +3324,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See Documentation/blockdev/ramdisk.txt. rcu_nocbs= [KNL] + The argument is a cpu list, as described above. + In kernels built with CONFIG_RCU_NOCB_CPU=y, set the specified list of CPUs to be no-callback CPUs. Invocation of these CPUs' RCU callbacks will @@ -4238,6 +4311,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted. u = IGNORE_UAS (don't bind to the uas driver); w = NO_WP_DETECT (don't test whether the medium is write-protected). + y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE + even if the device claims no cache) Example: quirks=0419:aaf5:rl,0421:0433:rc user_debug= [KNL,ARM] diff --git a/Documentation/kmemcheck.txt b/Documentation/kmemcheck.txt deleted file mode 100644 index 80aae85d8da6..000000000000 --- a/Documentation/kmemcheck.txt +++ /dev/null @@ -1,754 +0,0 @@ -GETTING STARTED WITH KMEMCHECK -============================== - -Vegard Nossum - - -Contents -======== -0. Introduction -1. Downloading -2. Configuring and compiling -3. How to use -3.1. Booting -3.2. Run-time enable/disable -3.3. Debugging -3.4. Annotating false positives -4. Reporting errors -5. Technical description - - -0. Introduction -=============== - -kmemcheck is a debugging feature for the Linux Kernel. More specifically, it -is a dynamic checker that detects and warns about some uses of uninitialized -memory. - -Userspace programmers might be familiar with Valgrind's memcheck. The main -difference between memcheck and kmemcheck is that memcheck works for userspace -programs only, and kmemcheck works for the kernel only. The implementations -are of course vastly different. Because of this, kmemcheck is not as accurate -as memcheck, but it turns out to be good enough in practice to discover real -programmer errors that the compiler is not able to find through static -analysis. - -Enabling kmemcheck on a kernel will probably slow it down to the extent that -the machine will not be usable for normal workloads such as e.g. an -interactive desktop. kmemcheck will also cause the kernel to use about twice -as much memory as normal. For this reason, kmemcheck is strictly a debugging -feature. - - -1. Downloading -============== - -As of version 2.6.31-rc1, kmemcheck is included in the mainline kernel. - - -2. Configuring and compiling -============================ - -kmemcheck only works for the x86 (both 32- and 64-bit) platform. A number of -configuration variables must have specific settings in order for the kmemcheck -menu to even appear in "menuconfig". These are: - - o CONFIG_CC_OPTIMIZE_FOR_SIZE=n - - This option is located under "General setup" / "Optimize for size". - - Without this, gcc will use certain optimizations that usually lead to - false positive warnings from kmemcheck. An example of this is a 16-bit - field in a struct, where gcc may load 32 bits, then discard the upper - 16 bits. kmemcheck sees only the 32-bit load, and may trigger a - warning for the upper 16 bits (if they're uninitialized). - - o CONFIG_SLAB=y or CONFIG_SLUB=y - - This option is located under "General setup" / "Choose SLAB - allocator". - - o CONFIG_FUNCTION_TRACER=n - - This option is located under "Kernel hacking" / "Tracers" / "Kernel - Function Tracer" - - When function tracing is compiled in, gcc emits a call to another - function at the beginning of every function. This means that when the - page fault handler is called, the ftrace framework will be called - before kmemcheck has had a chance to handle the fault. If ftrace then - modifies memory that was tracked by kmemcheck, the result is an - endless recursive page fault. - - o CONFIG_DEBUG_PAGEALLOC=n - - This option is located under "Kernel hacking" / "Memory Debugging" - / "Debug page memory allocations". - -In addition, I highly recommend turning on CONFIG_DEBUG_INFO=y. This is also -located under "Kernel hacking". With this, you will be able to get line number -information from the kmemcheck warnings, which is extremely valuable in -debugging a problem. This option is not mandatory, however, because it slows -down the compilation process and produces a much bigger kernel image. - -Now the kmemcheck menu should be visible (under "Kernel hacking" / "Memory -Debugging" / "kmemcheck: trap use of uninitialized memory"). Here follows -a description of the kmemcheck configuration variables: - - o CONFIG_KMEMCHECK - - This must be enabled in order to use kmemcheck at all... - - o CONFIG_KMEMCHECK_[DISABLED | ENABLED | ONESHOT]_BY_DEFAULT - - This option controls the status of kmemcheck at boot-time. "Enabled" - will enable kmemcheck right from the start, "disabled" will boot the - kernel as normal (but with the kmemcheck code compiled in, so it can - be enabled at run-time after the kernel has booted), and "one-shot" is - a special mode which will turn kmemcheck off automatically after - detecting the first use of uninitialized memory. - - If you are using kmemcheck to actively debug a problem, then you - probably want to choose "enabled" here. - - The one-shot mode is mostly useful in automated test setups because it - can prevent floods of warnings and increase the chances of the machine - surviving in case something is really wrong. In other cases, the one- - shot mode could actually be counter-productive because it would turn - itself off at the very first error -- in the case of a false positive - too -- and this would come in the way of debugging the specific - problem you were interested in. - - If you would like to use your kernel as normal, but with a chance to - enable kmemcheck in case of some problem, it might be a good idea to - choose "disabled" here. When kmemcheck is disabled, most of the run- - time overhead is not incurred, and the kernel will be almost as fast - as normal. - - o CONFIG_KMEMCHECK_QUEUE_SIZE - - Select the maximum number of error reports to store in an internal - (fixed-size) buffer. Since errors can occur virtually anywhere and in - any context, we need a temporary storage area which is guaranteed not - to generate any other page faults when accessed. The queue will be - emptied as soon as a tasklet may be scheduled. If the queue is full, - new error reports will be lost. - - The default value of 64 is probably fine. If some code produces more - than 64 errors within an irqs-off section, then the code is likely to - produce many, many more, too, and these additional reports seldom give - any more information (the first report is usually the most valuable - anyway). - - This number might have to be adjusted if you are not using serial - console or similar to capture the kernel log. If you are using the - "dmesg" command to save the log, then getting a lot of kmemcheck - warnings might overflow the kernel log itself, and the earlier reports - will get lost in that way instead. Try setting this to 10 or so on - such a setup. - - o CONFIG_KMEMCHECK_SHADOW_COPY_SHIFT - - Select the number of shadow bytes to save along with each entry of the - error-report queue. These bytes indicate what parts of an allocation - are initialized, uninitialized, etc. and will be displayed when an - error is detected to help the debugging of a particular problem. - - The number entered here is actually the logarithm of the number of - bytes that will be saved. So if you pick for example 5 here, kmemcheck - will save 2^5 = 32 bytes. - - The default value should be fine for debugging most problems. It also - fits nicely within 80 columns. - - o CONFIG_KMEMCHECK_PARTIAL_OK - - This option (when enabled) works around certain GCC optimizations that - produce 32-bit reads from 16-bit variables where the upper 16 bits are - thrown away afterwards. - - The default value (enabled) is recommended. This may of course hide - some real errors, but disabling it would probably produce a lot of - false positives. - - o CONFIG_KMEMCHECK_BITOPS_OK - - This option silences warnings that would be generated for bit-field - accesses where not all the bits are initialized at the same time. This - may also hide some real bugs. - - This option is probably obsolete, or it should be replaced with - the kmemcheck-/bitfield-annotations for the code in question. The - default value is therefore fine. - -Now compile the kernel as usual. - - -3. How to use -============= - -3.1. Booting -============ - -First some information about the command-line options. There is only one -option specific to kmemcheck, and this is called "kmemcheck". It can be used -to override the default mode as chosen by the CONFIG_KMEMCHECK_*_BY_DEFAULT -option. Its possible settings are: - - o kmemcheck=0 (disabled) - o kmemcheck=1 (enabled) - o kmemcheck=2 (one-shot mode) - -If SLUB debugging has been enabled in the kernel, it may take precedence over -kmemcheck in such a way that the slab caches which are under SLUB debugging -will not be tracked by kmemcheck. In order to ensure that this doesn't happen -(even though it shouldn't by default), use SLUB's boot option "slub_debug", -like this: slub_debug=- - -In fact, this option may also be used for fine-grained control over SLUB vs. -kmemcheck. For example, if the command line includes "kmemcheck=1 -slub_debug=,dentry", then SLUB debugging will be used only for the "dentry" -slab cache, and with kmemcheck tracking all the other caches. This is advanced -usage, however, and is not generally recommended. - - -3.2. Run-time enable/disable -============================ - -When the kernel has booted, it is possible to enable or disable kmemcheck at -run-time. WARNING: This feature is still experimental and may cause false -positive warnings to appear. Therefore, try not to use this. If you find that -it doesn't work properly (e.g. you see an unreasonable amount of warnings), I -will be happy to take bug reports. - -Use the file /proc/sys/kernel/kmemcheck for this purpose, e.g.: - - $ echo 0 > /proc/sys/kernel/kmemcheck # disables kmemcheck - -The numbers are the same as for the kmemcheck= command-line option. - - -3.3. Debugging -============== - -A typical report will look something like this: - -WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - ^ - -Pid: 1856, comm: ntpdate Not tainted 2.6.29-rc5 #264 945P-A -RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 -RSP: 0018:ffff88003cdf7d98 EFLAGS: 00210002 -RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 -RDX: ffff88003e5d6018 RSI: ffff88003e5d6024 RDI: ffff88003cdf7e84 -RBP: ffff88003cdf7db8 R08: ffff88003e5d6000 R09: 0000000000000000 -R10: 0000000000000080 R11: 0000000000000000 R12: 000000000000000e -R13: ffff88003cdf7e78 R14: ffff88003d530710 R15: ffff88003d5a98c8 -FS: 0000000000000000(0000) GS:ffff880001982000(0063) knlGS:00000 -CS: 0010 DS: 002b ES: 002b CR0: 0000000080050033 -CR2: ffff88003f806ea0 CR3: 000000003c036000 CR4: 00000000000006a0 -DR0: 0000000000000000 DR1: 0000000000000000 DR2: 0000000000000000 -DR3: 0000000000000000 DR6: 00000000ffff4ff0 DR7: 0000000000000400 - [] dequeue_signal+0x8e/0x170 - [] get_signal_to_deliver+0x98/0x390 - [] do_notify_resume+0xad/0x7d0 - [] int_signal+0x12/0x17 - [] 0xffffffffffffffff - -The single most valuable information in this report is the RIP (or EIP on 32- -bit) value. This will help us pinpoint exactly which instruction that caused -the warning. - -If your kernel was compiled with CONFIG_DEBUG_INFO=y, then all we have to do -is give this address to the addr2line program, like this: - - $ addr2line -e vmlinux -i ffffffff8104ede8 - arch/x86/include/asm/string_64.h:12 - include/asm-generic/siginfo.h:287 - kernel/signal.c:380 - kernel/signal.c:410 - -The "-e vmlinux" tells addr2line which file to look in. IMPORTANT: This must -be the vmlinux of the kernel that produced the warning in the first place! If -not, the line number information will almost certainly be wrong. - -The "-i" tells addr2line to also print the line numbers of inlined functions. -In this case, the flag was very important, because otherwise, it would only -have printed the first line, which is just a call to memcpy(), which could be -called from a thousand places in the kernel, and is therefore not very useful. -These inlined functions would not show up in the stack trace above, simply -because the kernel doesn't load the extra debugging information. This -technique can of course be used with ordinary kernel oopses as well. - -In this case, it's the caller of memcpy() that is interesting, and it can be -found in include/asm-generic/siginfo.h, line 287: - -281 static inline void copy_siginfo(struct siginfo *to, struct siginfo *from) -282 { -283 if (from->si_code < 0) -284 memcpy(to, from, sizeof(*to)); -285 else -286 /* _sigchld is currently the largest know union member */ -287 memcpy(to, from, __ARCH_SI_PREAMBLE_SIZE + sizeof(from->_sifields._sigchld)); -288 } - -Since this was a read (kmemcheck usually warns about reads only, though it can -warn about writes to unallocated or freed memory as well), it was probably the -"from" argument which contained some uninitialized bytes. Following the chain -of calls, we move upwards to see where "from" was allocated or initialized, -kernel/signal.c, line 380: - -359 static void collect_signal(int sig, struct sigpending *list, siginfo_t *info) -360 { -... -367 list_for_each_entry(q, &list->list, list) { -368 if (q->info.si_signo == sig) { -369 if (first) -370 goto still_pending; -371 first = q; -... -377 if (first) { -378 still_pending: -379 list_del_init(&first->list); -380 copy_siginfo(info, &first->info); -381 __sigqueue_free(first); -... -392 } -393 } - -Here, it is &first->info that is being passed on to copy_siginfo(). The -variable "first" was found on a list -- passed in as the second argument to -collect_signal(). We continue our journey through the stack, to figure out -where the item on "list" was allocated or initialized. We move to line 410: - -395 static int __dequeue_signal(struct sigpending *pending, sigset_t *mask, -396 siginfo_t *info) -397 { -... -410 collect_signal(sig, pending, info); -... -414 } - -Now we need to follow the "pending" pointer, since that is being passed on to -collect_signal() as "list". At this point, we've run out of lines from the -"addr2line" output. Not to worry, we just paste the next addresses from the -kmemcheck stack dump, i.e.: - - [] dequeue_signal+0x8e/0x170 - [] get_signal_to_deliver+0x98/0x390 - [] do_notify_resume+0xad/0x7d0 - [] int_signal+0x12/0x17 - - $ addr2line -e vmlinux -i ffffffff8104f04e ffffffff81050bd8 \ - ffffffff8100b87d ffffffff8100c7b5 - kernel/signal.c:446 - kernel/signal.c:1806 - arch/x86/kernel/signal.c:805 - arch/x86/kernel/signal.c:871 - arch/x86/kernel/entry_64.S:694 - -Remember that since these addresses were found on the stack and not as the -RIP value, they actually point to the _next_ instruction (they are return -addresses). This becomes obvious when we look at the code for line 446: - -422 int dequeue_signal(struct task_struct *tsk, sigset_t *mask, siginfo_t *info) -423 { -... -431 signr = __dequeue_signal(&tsk->signal->shared_pending, -432 mask, info); -433 /* -434 * itimer signal ? -435 * -436 * itimers are process shared and we restart periodic -437 * itimers in the signal delivery path to prevent DoS -438 * attacks in the high resolution timer case. This is -439 * compliant with the old way of self restarting -440 * itimers, as the SIGALRM is a legacy signal and only -441 * queued once. Changing the restart behaviour to -442 * restart the timer in the signal dequeue path is -443 * reducing the timer noise on heavy loaded !highres -444 * systems too. -445 */ -446 if (unlikely(signr == SIGALRM)) { -... -489 } - -So instead of looking at 446, we should be looking at 431, which is the line -that executes just before 446. Here we see that what we are looking for is -&tsk->signal->shared_pending. - -Our next task is now to figure out which function that puts items on this -"shared_pending" list. A crude, but efficient tool, is git grep: - - $ git grep -n 'shared_pending' kernel/ - ... - kernel/signal.c:828: pending = group ? &t->signal->shared_pending : &t->pending; - kernel/signal.c:1339: pending = group ? &t->signal->shared_pending : &t->pending; - ... - -There were more results, but none of them were related to list operations, -and these were the only assignments. We inspect the line numbers more closely -and find that this is indeed where items are being added to the list: - -816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, -817 int group) -818 { -... -828 pending = group ? &t->signal->shared_pending : &t->pending; -... -851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && -852 (is_si_special(info) || -853 info->si_code >= 0))); -854 if (q) { -855 list_add_tail(&q->list, &pending->list); -... -890 } - -and: - -1309 int send_sigqueue(struct sigqueue *q, struct task_struct *t, int group) -1310 { -.... -1339 pending = group ? &t->signal->shared_pending : &t->pending; -1340 list_add_tail(&q->list, &pending->list); -.... -1347 } - -In the first case, the list element we are looking for, "q", is being returned -from the function __sigqueue_alloc(), which looks like an allocation function. -Let's take a look at it: - -187 static struct sigqueue *__sigqueue_alloc(struct task_struct *t, gfp_t flags, -188 int override_rlimit) -189 { -190 struct sigqueue *q = NULL; -191 struct user_struct *user; -192 -193 /* -194 * We won't get problems with the target's UID changing under us -195 * because changing it requires RCU be used, and if t != current, the -196 * caller must be holding the RCU readlock (by way of a spinlock) and -197 * we use RCU protection here -198 */ -199 user = get_uid(__task_cred(t)->user); -200 atomic_inc(&user->sigpending); -201 if (override_rlimit || -202 atomic_read(&user->sigpending) <= -203 t->signal->rlim[RLIMIT_SIGPENDING].rlim_cur) -204 q = kmem_cache_alloc(sigqueue_cachep, flags); -205 if (unlikely(q == NULL)) { -206 atomic_dec(&user->sigpending); -207 free_uid(user); -208 } else { -209 INIT_LIST_HEAD(&q->list); -210 q->flags = 0; -211 q->user = user; -212 } -213 -214 return q; -215 } - -We see that this function initializes q->list, q->flags, and q->user. It seems -that now is the time to look at the definition of "struct sigqueue", e.g.: - -14 struct sigqueue { -15 struct list_head list; -16 int flags; -17 siginfo_t info; -18 struct user_struct *user; -19 }; - -And, you might remember, it was a memcpy() on &first->info that caused the -warning, so this makes perfect sense. It also seems reasonable to assume that -it is the caller of __sigqueue_alloc() that has the responsibility of filling -out (initializing) this member. - -But just which fields of the struct were uninitialized? Let's look at -kmemcheck's report again: - -WARNING: kmemcheck: Caught 32-bit read from uninitialized memory (ffff88003e4a2024) -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - ^ - -These first two lines are the memory dump of the memory object itself, and the -shadow bytemap, respectively. The memory object itself is in this case -&first->info. Just beware that the start of this dump is NOT the start of the -object itself! The position of the caret (^) corresponds with the address of -the read (ffff88003e4a2024). - -The shadow bytemap dump legend is as follows: - - i - initialized - u - uninitialized - a - unallocated (memory has been allocated by the slab layer, but has not - yet been handed off to anybody) - f - freed (memory has been allocated by the slab layer, but has been freed - by the previous owner) - -In order to figure out where (relative to the start of the object) the -uninitialized memory was located, we have to look at the disassembly. For -that, we'll need the RIP address again: - -RIP: 0010:[] [] __dequeue_signal+0xc8/0x190 - - $ objdump -d --no-show-raw-insn vmlinux | grep -C 8 ffffffff8104ede8: - ffffffff8104edc8: mov %r8,0x8(%r8) - ffffffff8104edcc: test %r10d,%r10d - ffffffff8104edcf: js ffffffff8104ee88 <__dequeue_signal+0x168> - ffffffff8104edd5: mov %rax,%rdx - ffffffff8104edd8: mov $0xc,%ecx - ffffffff8104eddd: mov %r13,%rdi - ffffffff8104ede0: mov $0x30,%eax - ffffffff8104ede5: mov %rdx,%rsi - ffffffff8104ede8: rep movsl %ds:(%rsi),%es:(%rdi) - ffffffff8104edea: test $0x2,%al - ffffffff8104edec: je ffffffff8104edf0 <__dequeue_signal+0xd0> - ffffffff8104edee: movsw %ds:(%rsi),%es:(%rdi) - ffffffff8104edf0: test $0x1,%al - ffffffff8104edf2: je ffffffff8104edf5 <__dequeue_signal+0xd5> - ffffffff8104edf4: movsb %ds:(%rsi),%es:(%rdi) - ffffffff8104edf5: mov %r8,%rdi - ffffffff8104edf8: callq ffffffff8104de60 <__sigqueue_free> - -As expected, it's the "rep movsl" instruction from the memcpy() that causes -the warning. We know about REP MOVSL that it uses the register RCX to count -the number of remaining iterations. By taking a look at the register dump -again (from the kmemcheck report), we can figure out how many bytes were left -to copy: - -RAX: 0000000000000030 RBX: ffff88003d4ea968 RCX: 0000000000000009 - -By looking at the disassembly, we also see that %ecx is being loaded with the -value $0xc just before (ffffffff8104edd8), so we are very lucky. Keep in mind -that this is the number of iterations, not bytes. And since this is a "long" -operation, we need to multiply by 4 to get the number of bytes. So this means -that the uninitialized value was encountered at 4 * (0xc - 0x9) = 12 bytes -from the start of the object. - -We can now try to figure out which field of the "struct siginfo" that was not -initialized. This is the beginning of the struct: - -40 typedef struct siginfo { -41 int si_signo; -42 int si_errno; -43 int si_code; -44 -45 union { -.. -92 } _sifields; -93 } siginfo_t; - -On 64-bit, the int is 4 bytes long, so it must the union member that has -not been initialized. We can verify this using gdb: - - $ gdb vmlinux - ... - (gdb) p &((struct siginfo *) 0)->_sifields - $1 = (union {...} *) 0x10 - -Actually, it seems that the union member is located at offset 0x10 -- which -means that gcc has inserted 4 bytes of padding between the members si_code -and _sifields. We can now get a fuller picture of the memory dump: - - _----------------------------=> si_code - / _--------------------=> (padding) - | / _------------=> _sifields(._kill._pid) - | | / _----=> _sifields(._kill._uid) - | | | / --------|-------|-------|-------| -80000000000000000000000000000000000000000088ffff0000000000000000 - i i i i u u u u i i i i i i i i u u u u u u u u u u u u u u u u - -This allows us to realize another important fact: si_code contains the value -0x80. Remember that x86 is little endian, so the first 4 bytes "80000000" are -really the number 0x00000080. With a bit of research, we find that this is -actually the constant SI_KERNEL defined in include/asm-generic/siginfo.h: - -144 #define SI_KERNEL 0x80 /* sent by the kernel from somewhere */ - -This macro is used in exactly one place in the x86 kernel: In send_signal() -in kernel/signal.c: - -816 static int send_signal(int sig, struct siginfo *info, struct task_struct *t, -817 int group) -818 { -... -828 pending = group ? &t->signal->shared_pending : &t->pending; -... -851 q = __sigqueue_alloc(t, GFP_ATOMIC, (sig < SIGRTMIN && -852 (is_si_special(info) || -853 info->si_code >= 0))); -854 if (q) { -855 list_add_tail(&q->list, &pending->list); -856 switch ((unsigned long) info) { -... -865 case (unsigned long) SEND_SIG_PRIV: -866 q->info.si_signo = sig; -867 q->info.si_errno = 0; -868 q->info.si_code = SI_KERNEL; -869 q->info.si_pid = 0; -870 q->info.si_uid = 0; -871 break; -... -890 } - -Not only does this match with the .si_code member, it also matches the place -we found earlier when looking for where siginfo_t objects are enqueued on the -"shared_pending" list. - -So to sum up: It seems that it is the padding introduced by the compiler -between two struct fields that is uninitialized, and this gets reported when -we do a memcpy() on the struct. This means that we have identified a false -positive warning. - -Normally, kmemcheck will not report uninitialized accesses in memcpy() calls -when both the source and destination addresses are tracked. (Instead, we copy -the shadow bytemap as well). In this case, the destination address clearly -was not tracked. We can dig a little deeper into the stack trace from above: - - arch/x86/kernel/signal.c:805 - arch/x86/kernel/signal.c:871 - arch/x86/kernel/entry_64.S:694 - -And we clearly see that the destination siginfo object is located on the -stack: - -782 static void do_signal(struct pt_regs *regs) -783 { -784 struct k_sigaction ka; -785 siginfo_t info; -... -804 signr = get_signal_to_deliver(&info, &ka, regs, NULL); -... -854 } - -And this &info is what eventually gets passed to copy_siginfo() as the -destination argument. - -Now, even though we didn't find an actual error here, the example is still a -good one, because it shows how one would go about to find out what the report -was all about. - - -3.4. Annotating false positives -=============================== - -There are a few different ways to make annotations in the source code that -will keep kmemcheck from checking and reporting certain allocations. Here -they are: - - o __GFP_NOTRACK_FALSE_POSITIVE - - This flag can be passed to kmalloc() or kmem_cache_alloc() (therefore - also to other functions that end up calling one of these) to indicate - that the allocation should not be tracked because it would lead to - a false positive report. This is a "big hammer" way of silencing - kmemcheck; after all, even if the false positive pertains to - particular field in a struct, for example, we will now lose the - ability to find (real) errors in other parts of the same struct. - - Example: - - /* No warnings will ever trigger on accessing any part of x */ - x = kmalloc(sizeof *x, GFP_KERNEL | __GFP_NOTRACK_FALSE_POSITIVE); - - o kmemcheck_bitfield_begin(name)/kmemcheck_bitfield_end(name) and - kmemcheck_annotate_bitfield(ptr, name) - - The first two of these three macros can be used inside struct - definitions to signal, respectively, the beginning and end of a - bitfield. Additionally, this will assign the bitfield a name, which - is given as an argument to the macros. - - Having used these markers, one can later use - kmemcheck_annotate_bitfield() at the point of allocation, to indicate - which parts of the allocation is part of a bitfield. - - Example: - - struct foo { - int x; - - kmemcheck_bitfield_begin(flags); - int flag_a:1; - int flag_b:1; - kmemcheck_bitfield_end(flags); - - int y; - }; - - struct foo *x = kmalloc(sizeof *x); - - /* No warnings will trigger on accessing the bitfield of x */ - kmemcheck_annotate_bitfield(x, flags); - - Note that kmemcheck_annotate_bitfield() can be used even before the - return value of kmalloc() is checked -- in other words, passing NULL - as the first argument is legal (and will do nothing). - - -4. Reporting errors -=================== - -As we have seen, kmemcheck will produce false positive reports. Therefore, it -is not very wise to blindly post kmemcheck warnings to mailing lists and -maintainers. Instead, I encourage maintainers and developers to find errors -in their own code. If you get a warning, you can try to work around it, try -to figure out if it's a real error or not, or simply ignore it. Most -developers know their own code and will quickly and efficiently determine the -root cause of a kmemcheck report. This is therefore also the most efficient -way to work with kmemcheck. - -That said, we (the kmemcheck maintainers) will always be on the lookout for -false positives that we can annotate and silence. So whatever you find, -please drop us a note privately! Kernel configs and steps to reproduce (if -available) are of course a great help too. - -Happy hacking! - - -5. Technical description -======================== - -kmemcheck works by marking memory pages non-present. This means that whenever -somebody attempts to access the page, a page fault is generated. The page -fault handler notices that the page was in fact only hidden, and so it calls -on the kmemcheck code to make further investigations. - -When the investigations are completed, kmemcheck "shows" the page by marking -it present (as it would be under normal circumstances). This way, the -interrupted code can continue as usual. - -But after the instruction has been executed, we should hide the page again, so -that we can catch the next access too! Now kmemcheck makes use of a debugging -feature of the processor, namely single-stepping. When the processor has -finished the one instruction that generated the memory access, a debug -exception is raised. From here, we simply hide the page again and continue -execution, this time with the single-stepping feature turned off. - -kmemcheck requires some assistance from the memory allocator in order to work. -The memory allocator needs to - - 1. Tell kmemcheck about newly allocated pages and pages that are about to - be freed. This allows kmemcheck to set up and tear down the shadow memory - for the pages in question. The shadow memory stores the status of each - byte in the allocation proper, e.g. whether it is initialized or - uninitialized. - - 2. Tell kmemcheck which parts of memory should be marked uninitialized. - There are actually a few more states, such as "not yet allocated" and - "recently freed". - -If a slab cache is set up using the SLAB_NOTRACK flag, it will never return -memory that can take page faults because of kmemcheck. - -If a slab cache is NOT set up using the SLAB_NOTRACK flag, callers can still -request memory with the __GFP_NOTRACK or __GFP_NOTRACK_FALSE_POSITIVE flags. -This does not prevent the page faults from occurring, however, but marks the -object in question as being initialized so that no warnings will ever be -produced for this object. - -Currently, the SLAB and SLUB allocators are supported by kmemcheck. diff --git a/Documentation/kmemleak.txt b/Documentation/kmemleak.txt deleted file mode 100644 index 18e24abb3ecf..000000000000 --- a/Documentation/kmemleak.txt +++ /dev/null @@ -1,203 +0,0 @@ -Kernel Memory Leak Detector -=========================== - -Introduction ------------- - -Kmemleak provides a way of detecting possible kernel memory leaks in a -way similar to a tracing garbage collector -(https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29#Tracing_garbage_collectors), -with the difference that the orphan objects are not freed but only -reported via /sys/kernel/debug/kmemleak. A similar method is used by the -Valgrind tool (memcheck --leak-check) to detect the memory leaks in -user-space applications. -Kmemleak is supported on x86, arm, powerpc, sparc, sh, microblaze, ppc, mips, s390, metag and tile. - -Usage ------ - -CONFIG_DEBUG_KMEMLEAK in "Kernel hacking" has to be enabled. A kernel -thread scans the memory every 10 minutes (by default) and prints the -number of new unreferenced objects found. To display the details of all -the possible memory leaks: - - # mount -t debugfs nodev /sys/kernel/debug/ - # cat /sys/kernel/debug/kmemleak - -To trigger an intermediate memory scan: - - # echo scan > /sys/kernel/debug/kmemleak - -To clear the list of all current possible memory leaks: - - # echo clear > /sys/kernel/debug/kmemleak - -New leaks will then come up upon reading /sys/kernel/debug/kmemleak -again. - -Note that the orphan objects are listed in the order they were allocated -and one object at the beginning of the list may cause other subsequent -objects to be reported as orphan. - -Memory scanning parameters can be modified at run-time by writing to the -/sys/kernel/debug/kmemleak file. The following parameters are supported: - - off - disable kmemleak (irreversible) - stack=on - enable the task stacks scanning (default) - stack=off - disable the tasks stacks scanning - scan=on - start the automatic memory scanning thread (default) - scan=off - stop the automatic memory scanning thread - scan= - set the automatic memory scanning period in seconds - (default 600, 0 to stop the automatic scanning) - scan - trigger a memory scan - clear - clear list of current memory leak suspects, done by - marking all current reported unreferenced objects grey, - or free all kmemleak objects if kmemleak has been disabled. - dump= - dump information about the object found at - -Kmemleak can also be disabled at boot-time by passing "kmemleak=off" on -the kernel command line. - -Memory may be allocated or freed before kmemleak is initialised and -these actions are stored in an early log buffer. The size of this buffer -is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. - -If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is -disabled by default. Passing "kmemleak=on" on the kernel command -line enables the function. - -Basic Algorithm ---------------- - -The memory allocations via kmalloc, vmalloc, kmem_cache_alloc and -friends are traced and the pointers, together with additional -information like size and stack trace, are stored in a rbtree. -The corresponding freeing function calls are tracked and the pointers -removed from the kmemleak data structures. - -An allocated block of memory is considered orphan if no pointer to its -start address or to any location inside the block can be found by -scanning the memory (including saved registers). This means that there -might be no way for the kernel to pass the address of the allocated -block to a freeing function and therefore the block is considered a -memory leak. - -The scanning algorithm steps: - - 1. mark all objects as white (remaining white objects will later be - considered orphan) - 2. scan the memory starting with the data section and stacks, checking - the values against the addresses stored in the rbtree. If - a pointer to a white object is found, the object is added to the - gray list - 3. scan the gray objects for matching addresses (some white objects - can become gray and added at the end of the gray list) until the - gray set is finished - 4. the remaining white objects are considered orphan and reported via - /sys/kernel/debug/kmemleak - -Some allocated memory blocks have pointers stored in the kernel's -internal data structures and they cannot be detected as orphans. To -avoid this, kmemleak can also store the number of values pointing to an -address inside the block address range that need to be found so that the -block is not considered a leak. One example is __vmalloc(). - -Testing specific sections with kmemleak ---------------------------------------- - -Upon initial bootup your /sys/kernel/debug/kmemleak output page may be -quite extensive. This can also be the case if you have very buggy code -when doing development. To work around these situations you can use the -'clear' command to clear all reported unreferenced objects from the -/sys/kernel/debug/kmemleak output. By issuing a 'scan' after a 'clear' -you can find new unreferenced objects; this should help with testing -specific sections of code. - -To test a critical section on demand with a clean kmemleak do: - - # echo clear > /sys/kernel/debug/kmemleak - ... test your kernel or modules ... - # echo scan > /sys/kernel/debug/kmemleak - -Then as usual to get your report with: - - # cat /sys/kernel/debug/kmemleak - -Freeing kmemleak internal objects ---------------------------------- - -To allow access to previously found memory leaks after kmemleak has been -disabled by the user or due to an fatal error, internal kmemleak objects -won't be freed when kmemleak is disabled, and those objects may occupy -a large part of physical memory. - -In this situation, you may reclaim memory with: - - # echo clear > /sys/kernel/debug/kmemleak - -Kmemleak API ------------- - -See the include/linux/kmemleak.h header for the functions prototype. - -kmemleak_init - initialize kmemleak -kmemleak_alloc - notify of a memory block allocation -kmemleak_alloc_percpu - notify of a percpu memory block allocation -kmemleak_free - notify of a memory block freeing -kmemleak_free_part - notify of a partial memory block freeing -kmemleak_free_percpu - notify of a percpu memory block freeing -kmemleak_update_trace - update object allocation stack trace -kmemleak_not_leak - mark an object as not a leak -kmemleak_ignore - do not scan or report an object as leak -kmemleak_scan_area - add scan areas inside a memory block -kmemleak_no_scan - do not scan a memory block -kmemleak_erase - erase an old value in a pointer variable -kmemleak_alloc_recursive - as kmemleak_alloc but checks the recursiveness -kmemleak_free_recursive - as kmemleak_free but checks the recursiveness - -Dealing with false positives/negatives --------------------------------------- - -The false negatives are real memory leaks (orphan objects) but not -reported by kmemleak because values found during the memory scanning -point to such objects. To reduce the number of false negatives, kmemleak -provides the kmemleak_ignore, kmemleak_scan_area, kmemleak_no_scan and -kmemleak_erase functions (see above). The task stacks also increase the -amount of false negatives and their scanning is not enabled by default. - -The false positives are objects wrongly reported as being memory leaks -(orphan). For objects known not to be leaks, kmemleak provides the -kmemleak_not_leak function. The kmemleak_ignore could also be used if -the memory block is known not to contain other pointers and it will no -longer be scanned. - -Some of the reported leaks are only transient, especially on SMP -systems, because of pointers temporarily stored in CPU registers or -stacks. Kmemleak defines MSECS_MIN_AGE (defaulting to 1000) representing -the minimum age of an object to be reported as a memory leak. - -Limitations and Drawbacks -------------------------- - -The main drawback is the reduced performance of memory allocation and -freeing. To avoid other penalties, the memory scanning is only performed -when the /sys/kernel/debug/kmemleak file is read. Anyway, this tool is -intended for debugging purposes where the performance might not be the -most important requirement. - -To keep the algorithm simple, kmemleak scans for values pointing to any -address inside a block's address range. This may lead to an increased -number of false negatives. However, it is likely that a real memory leak -will eventually become visible. - -Another source of false negatives is the data stored in non-pointer -values. In a future version, kmemleak could only scan the pointer -members in the allocated structures. This feature would solve many of -the false negative cases described above. - -The tool can report false positives. These are cases where an allocated -block doesn't need to be freed (some cases in the init_call functions), -the pointer is calculated by other methods than the usual container_of -macro or the pointer is stored in a location not scanned by kmemleak. - -Page allocations and ioremap are not tracked. diff --git a/Documentation/ko_KR/memory-barriers.txt b/Documentation/ko_KR/memory-barriers.txt new file mode 100644 index 000000000000..34d3d380893d --- /dev/null +++ b/Documentation/ko_KR/memory-barriers.txt @@ -0,0 +1,3135 @@ +NOTE: +This is a version of Documentation/memory-barriers.txt translated into Korean. +This document is maintained by SeongJae Park . +If you find any difference between this document and the original file or +a problem with the translation, please contact the maintainer of this file. + +Please also note that the purpose of this file is to be easier to +read for non English (read: Korean) speakers and is not intended as +a fork. So if you have any comments or updates for this file please +update the original English file first. The English version is +definitive, and readers should look there if they have any doubt. + +=================================== +이 문서는 +Documentation/memory-barriers.txt +의 한글 번역입니다. + +역자： 박성재 +=================================== + + + ========================= + 리눅스 커널 메모리 배리어 + ========================= + +저자: David Howells + Paul E. McKenney + Will Deacon + Peter Zijlstra + +======== +면책조항 +======== + +이 문서는 명세서가 아닙니다; 이 문서는 완벽하지 않은데, 간결성을 위해 의도된 +부분도 있고, 의도하진 않았지만 사람에 의해 쓰였다보니 불완전한 부분도 있습니다. +이 문서는 리눅스에서 제공하는 다양한 메모리 배리어들을 사용하기 위한 +안내서입니다만, 뭔가 이상하다 싶으면 (그런게 많을 겁니다) 질문을 부탁드립니다. + +다시 말하지만, 이 문서는 리눅스가 하드웨어에 기대하는 사항에 대한 명세서가 +아닙니다. + +이 문서의 목적은 두가지입니다: + + (1) 어떤 특정 배리어에 대해 기대할 수 있는 최소한의 기능을 명세하기 위해서, + 그리고 + + (2) 사용 가능한 배리어들에 대해 어떻게 사용해야 하는지에 대한 안내를 제공하기 + 위해서. + +어떤 아키텍쳐는 특정한 배리어들에 대해서는 여기서 이야기하는 최소한의 +요구사항들보다 많은 기능을 제공할 수도 있습니다만, 여기서 이야기하는 +요구사항들을 충족하지 않는 아키텍쳐가 있다면 그 아키텍쳐가 잘못된 것이란 점을 +알아두시기 바랍니다. + +또한, 특정 아키텍쳐에서 일부 배리어는 해당 아키텍쳐의 특수한 동작 방식으로 인해 +해당 배리어의 명시적 사용이 불필요해서 no-op 이 될수도 있음을 알아두시기 +바랍니다. + +역자: 본 번역 역시 완벽하지 않은데, 이 역시 부분적으로는 의도된 것이기도 +합니다. 여타 기술 문서들이 그렇듯 완벽한 이해를 위해서는 번역문과 원문을 함께 +읽으시되 번역문을 하나의 가이드로 활용하시길 추천드리며, 발견되는 오역 등에 +대해서는 언제든 의견을 부탁드립니다. 과한 번역으로 인한 오해를 최소화하기 위해 +애매한 부분이 있을 경우에는 어색함이 있더라도 원래의 용어를 차용합니다. + + +===== +목차: +===== + + (*) 추상 메모리 액세스 모델. + + - 디바이스 오퍼레이션. + - 보장사항. + + (*) 메모리 배리어란 무엇인가? + + - 메모리 배리어의 종류. + - 메모리 배리어에 대해 가정해선 안될 것. + - 데이터 의존성 배리어. + - 컨트롤 의존성. + - SMP 배리어 짝맞추기. + - 메모리 배리어 시퀀스의 예. + - 읽기 메모리 배리어 vs 로드 예측. + - 이행성 + + (*) 명시적 커널 배리어. + + - 컴파일러 배리어. + - CPU 메모리 배리어. + - MMIO 쓰기 배리어. + + (*) 암묵적 커널 메모리 배리어. + + - 락 Acquisition 함수. + - 인터럽트 비활성화 함수. + - 슬립과 웨이크업 함수. + - 그외의 함수들. + + (*) CPU 간 ACQUIRING 배리어의 효과. + + - Acquire vs 메모리 액세스. + - Acquire vs I/O 액세스. + + (*) 메모리 배리어가 필요한 곳 + + - 프로세서간 상호 작용. + - 어토믹 오퍼레이션. + - 디바이스 액세스. + - 인터럽트. + + (*) 커널 I/O 배리어의 효과. + + (*) 가정되는 가장 완화된 실행 순서 모델. + + (*) CPU 캐시의 영향. + + - 캐시 일관성. + - 캐시 일관성 vs DMA. + - 캐시 일관성 vs MMIO. + + (*) CPU 들이 저지르는 일들. + + - 그리고, Alpha 가 있다. + - 가상 머신 게스트. + + (*) 사용 예. + + - 순환식 버퍼. + + (*) 참고 문헌. + + +======================= +추상 메모리 액세스 모델 +======================= + +다음과 같이 추상화된 시스템 모델을 생각해 봅시다: + + : : + : : + : : + +-------+ : +--------+ : +-------+ + | | : | | : | | + | | : | | : | | + | CPU 1 |<----->| Memory |<----->| CPU 2 | + | | : | | : | | + | | : | | : | | + +-------+ : +--------+ : +-------+ + ^ : ^ : ^ + | : | : | + | : | : | + | : v : | + | : +--------+ : | + | : | | : | + | : | | : | + +---------->| Device |<----------+ + : | | : + : | | : + : +--------+ : + : : + +프로그램은 여러 메모리 액세스 오퍼레이션을 발생시키고, 각각의 CPU 는 그런 +프로그램들을 실행합니다. 추상화된 CPU 모델에서 메모리 오퍼레이션들의 순서는 +매우 완화되어 있고, CPU 는 프로그램이 인과관계를 어기지 않는 상태로 관리된다고 +보일 수만 있다면 메모리 오퍼레이션을 자신이 원하는 어떤 순서대로든 재배치해 +동작시킬 수 있습니다. 비슷하게, 컴파일러 또한 프로그램의 정상적 동작을 해치지 +않는 한도 내에서는 어떤 순서로든 자신이 원하는 대로 인스트럭션을 재배치 할 수 +있습니다. + +따라서 위의 다이어그램에서 한 CPU가 동작시키는 메모리 오퍼레이션이 만들어내는 +변화는 해당 오퍼레이션이 CPU 와 시스템의 다른 부분들 사이의 인터페이스(점선)를 +지나가면서 시스템의 나머지 부분들에 인지됩니다. + + +예를 들어, 다음의 일련의 이벤트들을 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1; B == 2 } + A = 3; x = B; + B = 4; y = A; + +다이어그램의 가운데에 위치한 메모리 시스템에 보여지게 되는 액세스들은 다음의 총 +24개의 조합으로 재구성될 수 있습니다: + + STORE A=3, STORE B=4, y=LOAD A->3, x=LOAD B->4 + STORE A=3, STORE B=4, x=LOAD B->4, y=LOAD A->3 + STORE A=3, y=LOAD A->3, STORE B=4, x=LOAD B->4 + STORE A=3, y=LOAD A->3, x=LOAD B->2, STORE B=4 + STORE A=3, x=LOAD B->2, STORE B=4, y=LOAD A->3 + STORE A=3, x=LOAD B->2, y=LOAD A->3, STORE B=4 + STORE B=4, STORE A=3, y=LOAD A->3, x=LOAD B->4 + STORE B=4, ... + ... + +따라서 다음의 네가지 조합의 값들이 나올 수 있습니다: + + x == 2, y == 1 + x == 2, y == 3 + x == 4, y == 1 + x == 4, y == 3 + + +한발 더 나아가서, 한 CPU 가 메모리 시스템에 반영한 스토어 오퍼레이션들의 결과는 +다른 CPU 에서의 로드 오퍼레이션을 통해 인지되는데, 이 때 스토어가 반영된 순서와 +다른 순서로 인지될 수도 있습니다. + + +예로, 아래의 일련의 이벤트들을 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; Q = P; + P = &B D = *Q; + +D 로 읽혀지는 값은 CPU 2 에서 P 로부터 읽혀진 주소값에 의존적이기 때문에 여기엔 +분명한 데이터 의존성이 있습니다. 하지만 이 이벤트들의 실행 결과로는 아래의 +결과들이 모두 나타날 수 있습니다: + + (Q == &A) and (D == 1) + (Q == &B) and (D == 2) + (Q == &B) and (D == 4) + +CPU 2 는 *Q 의 로드를 요청하기 전에 P 를 Q 에 넣기 때문에 D 에 C 를 집어넣는 +일은 없음을 알아두세요. + + +디바이스 오퍼레이션 +------------------- + +일부 디바이스는 자신의 컨트롤 인터페이스를 메모리의 특정 영역으로 매핑해서 +제공하는데(Memory mapped I/O), 해당 컨트롤 레지스터에 접근하는 순서는 매우 +중요합니다. 예를 들어, 어드레스 포트 레지스터 (A) 와 데이터 포트 레지스터 (D) +를 통해 접근되는 내부 레지스터 집합을 갖는 이더넷 카드를 생각해 봅시다. 내부의 +5번 레지스터를 읽기 위해 다음의 코드가 사용될 수 있습니다: + + *A = 5; + x = *D; + +하지만, 이건 다음의 두 조합 중 하나로 만들어질 수 있습니다: + + STORE *A = 5, x = LOAD *D + x = LOAD *D, STORE *A = 5 + +두번째 조합은 데이터를 읽어온 _후에_ 주소를 설정하므로, 오동작을 일으킬 겁니다. + + +보장사항 +-------- + +CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니다: + + (*) 어떤 CPU 든, 의존성이 존재하는 메모리 액세스들은 해당 CPU 자신에게 + 있어서는 순서대로 메모리 시스템에 수행 요청됩니다. 즉, 다음에 대해서: + + Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q); + + CPU 는 다음과 같은 메모리 오퍼레이션 시퀀스를 수행 요청합니다: + + Q = LOAD P, D = LOAD *Q + + 그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다. 대부분의 시스템에서 + smp_read_barrier_depends() 는 아무일도 안하지만 DEC Alpha 에서는 + 명시적으로 사용되어야 합니다. 보통의 경우에는 smp_read_barrier_depends() + 를 직접 사용하는 대신 rcu_dereference() 같은 것들을 사용해야 함을 + 알아두세요. + + (*) 특정 CPU 내에서 겹치는 영역의 메모리에 행해지는 로드와 스토어 들은 해당 + CPU 안에서는 순서가 바뀌지 않은 것으로 보여집니다. 즉, 다음에 대해서: + + a = READ_ONCE(*X); WRITE_ONCE(*X, b); + + CPU 는 다음의 메모리 오퍼레이션 시퀀스만을 메모리에 요청할 겁니다: + + a = LOAD *X, STORE *X = b + + 그리고 다음에 대해서는: + + WRITE_ONCE(*X, c); d = READ_ONCE(*X); + + CPU 는 다음의 수행 요청만을 만들어 냅니다: + + STORE *X = c, d = LOAD *X + + (로드 오퍼레이션과 스토어 오퍼레이션이 겹치는 메모리 영역에 대해 + 수행된다면 해당 오퍼레이션들은 겹친다고 표현됩니다). + +그리고 _반드시_ 또는 _절대로_ 가정하거나 가정하지 말아야 하는 것들이 있습니다: + + (*) 컴파일러가 READ_ONCE() 나 WRITE_ONCE() 로 보호되지 않은 메모리 액세스를 + 당신이 원하는 대로 할 것이라는 가정은 _절대로_ 해선 안됩니다. 그것들이 + 없다면, 컴파일러는 컴파일러 배리어 섹션에서 다루게 될, 모든 "창의적인" + 변경들을 만들어낼 권한을 갖게 됩니다. + + (*) 개별적인 로드와 스토어들이 주어진 순서대로 요청될 것이라는 가정은 _절대로_ + 하지 말아야 합니다. 이 말은 곧: + + X = *A; Y = *B; *D = Z; + + 는 다음의 것들 중 어느 것으로든 만들어질 수 있다는 의미입니다: + + X = LOAD *A, Y = LOAD *B, STORE *D = Z + X = LOAD *A, STORE *D = Z, Y = LOAD *B + Y = LOAD *B, X = LOAD *A, STORE *D = Z + Y = LOAD *B, STORE *D = Z, X = LOAD *A + STORE *D = Z, X = LOAD *A, Y = LOAD *B + STORE *D = Z, Y = LOAD *B, X = LOAD *A + + (*) 겹치는 메모리 액세스들은 합쳐지거나 버려질 수 있음을 _반드시_ 가정해야 + 합니다. 다음의 코드는: + + X = *A; Y = *(A + 4); + + 다음의 것들 중 뭐든 될 수 있습니다: + + X = LOAD *A; Y = LOAD *(A + 4); + Y = LOAD *(A + 4); X = LOAD *A; + {X, Y} = LOAD {*A, *(A + 4) }; + + 그리고: + + *A = X; *(A + 4) = Y; + + 는 다음 중 뭐든 될 수 있습니다: + + STORE *A = X; STORE *(A + 4) = Y; + STORE *(A + 4) = Y; STORE *A = X; + STORE {*A, *(A + 4) } = {X, Y}; + +그리고 보장사항에 반대되는 것들(anti-guarantees)이 있습니다: + + (*) 이 보장사항들은 bitfield 에는 적용되지 않는데, 컴파일러들은 bitfield 를 + 수정하는 코드를 생성할 때 원자성 없는(non-atomic) 읽고-수정하고-쓰는 + 인스트럭션들의 조합을 만드는 경우가 많기 때문입니다. 병렬 알고리즘의 + 동기화에 bitfield 를 사용하려 하지 마십시오. + + (*) bitfield 들이 여러 락으로 보호되는 경우라 하더라도, 하나의 bitfield 의 + 모든 필드들은 하나의 락으로 보호되어야 합니다. 만약 한 bitfield 의 두 + 필드가 서로 다른 락으로 보호된다면, 컴파일러의 원자성 없는 + 읽고-수정하고-쓰는 인스트럭션 조합은 한 필드에의 업데이트가 근처의 + 필드에도 영향을 끼치게 할 수 있습니다. + + (*) 이 보장사항들은 적절하게 정렬되고 크기가 잡힌 스칼라 변수들에 대해서만 + 적용됩니다. "적절하게 크기가 잡힌" 이라함은 현재로써는 "char", "short", + "int" 그리고 "long" 과 같은 크기의 변수들을 의미합니다. "적절하게 정렬된" + 은 자연스런 정렬을 의미하는데, 따라서 "char" 에 대해서는 아무 제약이 없고, + "short" 에 대해서는 2바이트 정렬을, "int" 에는 4바이트 정렬을, 그리고 + "long" 에 대해서는 32-bit 시스템인지 64-bit 시스템인지에 따라 4바이트 또는 + 8바이트 정렬을 의미합니다. 이 보장사항들은 C11 표준에서 소개되었으므로, + C11 전의 오래된 컴파일러(예를 들어, gcc 4.6) 를 사용할 때엔 주의하시기 + 바랍니다. 표준에 이 보장사항들은 "memory location" 을 정의하는 3.14 + 섹션에 다음과 같이 설명되어 있습니다: + (역자: 인용문이므로 번역하지 않습니다) + + memory location + either an object of scalar type, or a maximal sequence + of adjacent bit-fields all having nonzero width + + NOTE 1: Two threads of execution can update and access + separate memory locations without interfering with + each other. + + NOTE 2: A bit-field and an adjacent non-bit-field member + are in separate memory locations. The same applies + to two bit-fields, if one is declared inside a nested + structure declaration and the other is not, or if the two + are separated by a zero-length bit-field declaration, + or if they are separated by a non-bit-field member + declaration. It is not safe to concurrently update two + bit-fields in the same structure if all members declared + between them are also bit-fields, no matter what the + sizes of those intervening bit-fields happen to be. + + +========================= +메모리 배리어란 무엇인가? +========================= + +앞에서 봤듯이, 상호간 의존성이 없는 메모리 오퍼레이션들은 실제로는 무작위적 +순서로 수행될 수 있으며, 이는 CPU 와 CPU 간의 상호작용이나 I/O 에 문제가 될 수 +있습니다. 따라서 컴파일러와 CPU 가 순서를 바꾸는데 제약을 걸 수 있도록 개입할 +수 있는 어떤 방법이 필요합니다. + +메모리 배리어는 그런 개입 수단입니다. 메모리 배리어는 배리어를 사이에 둔 앞과 +뒤 양측의 메모리 오퍼레이션들 간에 부분적 순서가 존재하도록 하는 효과를 줍니다. + +시스템의 CPU 들과 여러 디바이스들은 성능을 올리기 위해 명령어 재배치, 실행 +유예, 메모리 오퍼레이션들의 조합, 예측적 로드(speculative load), 브랜치 +예측(speculative branch prediction), 다양한 종류의 캐싱(caching) 등의 다양한 +트릭을 사용할 수 있기 때문에 이런 강제력은 중요합니다. 메모리 배리어들은 이런 +트릭들을 무효로 하거나 억제하는 목적으로 사용되어져서 코드가 여러 CPU 와 +디바이스들 간의 상호작용을 정상적으로 제어할 수 있게 해줍니다. + + +메모리 배리어의 종류 +-------------------- + +메모리 배리어는 네개의 기본 타입으로 분류됩니다: + + (1) 쓰기 (또는 스토어) 메모리 배리어. + + 쓰기 메모리 배리어는 시스템의 다른 컴포넌트들에 해당 배리어보다 앞서 + 명시된 모든 STORE 오퍼레이션들이 해당 배리어 뒤에 명시된 모든 STORE + 오퍼레이션들보다 먼저 수행된 것으로 보일 것을 보장합니다. + + 쓰기 배리어는 스토어 오퍼레이션들에 대한 부분적 순서 세우기입니다; 로드 + 오퍼레이션들에 대해서는 어떤 영향도 끼치지 않습니다. + + CPU 는 시간의 흐름에 따라 메모리 시스템에 일련의 스토어 오퍼레이션들을 + 하나씩 요청해 집어넣습니다. 쓰기 배리어 앞의 모든 스토어 오퍼레이션들은 + 쓰기 배리어 뒤의 모든 스토어 오퍼레이션들보다 _앞서_ 수행될 겁니다. + + [!] 쓰기 배리어들은 읽기 또는 데이터 의존성 배리어와 함께 짝을 맞춰 + 사용되어야만 함을 알아두세요; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (2) 데이터 의존성 배리어. + + 데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다. 두개의 로드 + 오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예: + 두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올 + 데이터는 첫번째 로드에 의해 그 주소가 얻어지기 전에 업데이트 되어 있음을 + 보장하기 위해서 데이터 의존성 배리어가 필요할 수 있습니다. + + 데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서 + 세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는 + 로드들에 대해서는 어떤 영향도 끼치지 않습니다. + + (1) 에서 언급했듯이, 시스템의 CPU 들은 메모리 시스템에 일련의 스토어 + 오퍼레이션들을 던져 넣고 있으며, 거기에 관심이 있는 다른 CPU 는 그 + 오퍼레이션들을 메모리 시스템이 실행한 결과를 인지할 수 있습니다. 이처럼 + 다른 CPU 의 스토어 오퍼레이션의 결과에 관심을 두고 있는 CPU 가 수행 요청한 + 데이터 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서 + 던져 넣은 스토어 오퍼레이션과 같은 영역을 향했다면, 그런 스토어 + 오퍼레이션들이 만들어내는 결과가 데이터 의존성 배리어 뒤의 로드 + 오퍼레이션들에게는 보일 것을 보장합니다. + + 이 순서 세우기 제약에 대한 그림을 보기 위해선 "메모리 배리어 시퀀스의 예" + 서브섹션을 참고하시기 바랍니다. + + [!] 첫번째 로드는 반드시 _데이터_ 의존성을 가져야지 컨트롤 의존성을 가져야 + 하는게 아님을 알아두십시오. 만약 두번째 로드를 위한 주소가 첫번째 로드에 + 의존적이지만 그 의존성은 조건적이지 그 주소 자체를 가져오는게 아니라면, + 그것은 _컨트롤_ 의존성이고, 이 경우에는 읽기 배리어나 그보다 강력한 + 무언가가 필요합니다. 더 자세한 내용을 위해서는 "컨트롤 의존성" 서브섹션을 + 참고하시기 바랍니다. + + [!] 데이터 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 + 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (3) 읽기 (또는 로드) 메모리 배리어. + + 읽기 배리어는 데이터 의존성 배리어 기능의 보장사항에 더해서 배리어보다 + 앞서 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD + 오퍼레이션들보다 먼저 행해진 것으로 시스템의 다른 컴포넌트들에 보여질 것을 + 보장합니다. + + 읽기 배리어는 로드 오퍼레이션에 행해지는 부분적 순서 세우기입니다; 스토어 + 오퍼레이션에 대해서는 어떤 영향도 끼치지 않습니다. + + 읽기 메모리 배리어는 데이터 의존성 배리어를 내장하므로 데이터 의존성 + 배리어를 대신할 수 있습니다. + + [!] 읽기 배리어는 일반적으로 쓰기 배리어들과 함께 짝을 맞춰 사용되어야 + 합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요. + + + (4) 범용 메모리 배리어. + + 범용(general) 메모리 배리어는 배리어보다 앞서 명시된 모든 LOAD 와 STORE + 오퍼레이션들이 배리어 뒤에 명시된 모든 LOAD 와 STORE 오퍼레이션들보다 + 먼저 수행된 것으로 시스템의 나머지 컴포넌트들에 보이게 됨을 보장합니다. + + 범용 메모리 배리어는 로드와 스토어 모두에 대한 부분적 순서 세우기입니다. + + 범용 메모리 배리어는 읽기 메모리 배리어, 쓰기 메모리 배리어 모두를 + 내장하므로, 두 배리어를 모두 대신할 수 있습니다. + + +그리고 두개의 명시적이지 않은 타입이 있습니다: + + (5) ACQUIRE 오퍼레이션. + + 이 타입의 오퍼레이션은 단방향의 투과성 배리어처럼 동작합니다. ACQUIRE + 오퍼레이션 뒤의 모든 메모리 오퍼레이션들이 ACQUIRE 오퍼레이션 후에 + 일어난 것으로 시스템의 나머지 컴포넌트들에 보이게 될 것이 보장됩니다. + LOCK 오퍼레이션과 smp_load_acquire(), smp_cond_acquire() 오퍼레이션도 + ACQUIRE 오퍼레이션에 포함됩니다. smp_cond_acquire() 오퍼레이션은 컨트롤 + 의존성과 smp_rmb() 를 사용해서 ACQUIRE 의 의미적 요구사항(semantic)을 + 충족시킵니다. + + ACQUIRE 오퍼레이션 앞의 메모리 오퍼레이션들은 ACQUIRE 오퍼레이션 완료 후에 + 수행된 것처럼 보일 수 있습니다. + + ACQUIRE 오퍼레이션은 거의 항상 RELEASE 오퍼레이션과 짝을 지어 사용되어야 + 합니다. + + + (6) RELEASE 오퍼레이션. + + 이 타입의 오퍼레이션들도 단방향 투과성 배리어처럼 동작합니다. RELEASE + 오퍼레이션 앞의 모든 메모리 오퍼레이션들은 RELEASE 오퍼레이션 전에 완료된 + 것으로 시스템의 다른 컴포넌트들에 보여질 것이 보장됩니다. UNLOCK 류의 + 오퍼레이션들과 smp_store_release() 오퍼레이션도 RELEASE 오퍼레이션의 + 일종입니다. + + RELEASE 오퍼레이션 뒤의 메모리 오퍼레이션들은 RELEASE 오퍼레이션이 + 완료되기 전에 행해진 것처럼 보일 수 있습니다. + + ACQUIRE 와 RELEASE 오퍼레이션의 사용은 일반적으로 다른 메모리 배리어의 + 필요성을 없앱니다 (하지만 "MMIO 쓰기 배리어" 서브섹션에서 설명되는 예외를 + 알아두세요). 또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 동작할 + 것을 보장하지 -않습니다-. 하지만, 어떤 변수에 대한 RELEASE 오퍼레이션을 + 앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 뒤이어 같은 + 변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 액세스에는 보여질 + 것이 보장됩니다. 다르게 말하자면, 주어진 변수의 크리티컬 섹션에서는, 해당 + 변수에 대한 앞의 크리티컬 섹션에서의 모든 액세스들이 완료되었을 것을 + 보장합니다. + + 즉, ACQUIRE 는 최소한의 "취득" 동작처럼, 그리고 RELEASE 는 최소한의 "공개" + 처럼 동작한다는 의미입니다. + +atomic_ops.txt 에서 설명되는 어토믹 오퍼레이션들 중에는 완전히 순서잡힌 것들과 +(배리어를 사용하지 않는) 완화된 순서의 것들 외에 ACQUIRE 와 RELEASE 부류의 +것들도 존재합니다. 로드와 스토어를 모두 수행하는 조합된 어토믹 오퍼레이션에서, +ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 는 해당 +오퍼레이션의 스토어 부분에만 적용됩니다. + +메모리 배리어들은 두 CPU 간, 또는 CPU 와 디바이스 간에 상호작용의 가능성이 있을 +때에만 필요합니다. 만약 어떤 코드에 그런 상호작용이 없을 것이 보장된다면, 해당 +코드에서는 메모리 배리어를 사용할 필요가 없습니다. + + +이것들은 _최소한의_ 보장사항들임을 알아두세요. 다른 아키텍쳐에서는 더 강력한 +보장사항을 제공할 수도 있습니다만, 그런 보장사항은 아키텍쳐 종속적 코드 이외의 +부분에서는 신뢰되지 _않을_ 겁니다. + + +메모리 배리어에 대해 가정해선 안될 것 +------------------------------------- + +리눅스 커널 메모리 배리어들이 보장하지 않는 것들이 있습니다: + + (*) 메모리 배리어 앞에서 명시된 어떤 메모리 액세스도 메모리 배리어 명령의 수행 + 완료 시점까지 _완료_ 될 것이란 보장은 없습니다; 배리어가 하는 일은 CPU 의 + 액세스 큐에 특정 타입의 액세스들은 넘을 수 없는 선을 긋는 것으로 생각될 수 + 있습니다. + + (*) 한 CPU 에서 메모리 배리어를 수행하는게 시스템의 다른 CPU 나 하드웨어에 + 어떤 직접적인 영향을 끼친다는 보장은 존재하지 않습니다. 배리어 수행이 + 만드는 간접적 영향은 두번째 CPU 가 첫번째 CPU 의 액세스들의 결과를 + 바라보는 순서가 됩니다만, 다음 항목을 보세요: + + (*) 첫번째 CPU 가 두번째 CPU 의 메모리 액세스들의 결과를 바라볼 때, _설령_ + 두번째 CPU 가 메모리 배리어를 사용한다 해도, 첫번째 CPU _또한_ 그에 맞는 + 메모리 배리어를 사용하지 않는다면 ("SMP 배리어 짝맞추기" 서브섹션을 + 참고하세요) 그 결과가 올바른 순서로 보여진다는 보장은 없습니다. + + (*) CPU 바깥의 하드웨어[*] 가 메모리 액세스들의 순서를 바꾸지 않는다는 보장은 + 존재하지 않습니다. CPU 캐시 일관성 메커니즘은 메모리 배리어의 간접적 + 영향을 CPU 사이에 전파하긴 하지만, 순서대로 전파하지는 않을 수 있습니다. + + [*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다: + + Documentation/PCI/pci.txt + Documentation/DMA-API-HOWTO.txt + Documentation/DMA-API.txt + + +데이터 의존성 배리어 +-------------------- + +데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터 +의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다. 설명을 위해 +다음의 이벤트 시퀀스를 생각해 봅시다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B) + Q = READ_ONCE(P); + D = *Q; + +여기엔 분명한 데이터 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B +일 것이고, 따라서: + + (Q == &A) 는 (D == 1) 를, + (Q == &B) 는 (D == 4) 를 의미합니다. + +하지만! CPU 2 는 B 의 업데이트를 인식하기 전에 P 의 업데이트를 인식할 수 있고, +따라서 다음의 결과가 가능합니다: + + (Q == &B) and (D == 2) ???? + +이런 결과는 일관성이나 인과 관계 유지가 실패한 것처럼 보일 수도 있겠지만, +그렇지 않습니다, 그리고 이 현상은 (DEC Alpha 와 같은) 여러 CPU 에서 실제로 +발견될 수 있습니다. + +이 문제 상황을 제대로 해결하기 위해, 데이터 의존성 배리어나 그보다 강화된 +무언가가 주소를 읽어올 때와 데이터를 읽어올 때 사이에 추가되어야만 합니다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C == 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B); + Q = READ_ONCE(P); + <데이터 의존성 배리어> + D = *Q; + +이 변경은 앞의 처음 두가지 결과 중 하나만이 발생할 수 있고, 세번째의 결과는 +발생할 수 없도록 합니다. + +데이터 의존성 배리어는 의존적 쓰기에 대해서도 순서를 잡아줍니다: + + CPU 1 CPU 2 + =============== =============== + { A == 1, B == 2, C = 3, P == &A, Q == &C } + B = 4; + <쓰기 배리어> + WRITE_ONCE(P, &B); + Q = READ_ONCE(P); + <데이터 의존성 배리어> + *Q = 5; + +이 데이터 의존성 배리어는 Q 로의 읽기가 *Q 로의 스토어와 순서를 맞추게 +해줍니다. 이는 다음과 같은 결과를 막습니다: + + (Q == &B) && (B == 4) + +이런 패턴은 드물게 사용되어야 함을 알아 두시기 바랍니다. 무엇보다도, 의존성 +순서 규칙의 의도는 쓰기 작업을 -예방- 해서 그로 인해 발생하는 비싼 캐시 미스도 +없애려는 것입니다. 이 패턴은 드물게 발생하는 에러 조건 같은것들을 기록하는데 +사용될 수 있고, 이렇게 배리어를 사용해 순서를 지키게 함으로써 그런 기록이 +사라지는 것을 막습니다. + + +[!] 상당히 비직관적인 이 상황은 분리된 캐시를 가진 기계, 예를 들어 한 캐시 +뱅크가 짝수번 캐시 라인을 처리하고 다른 뱅크는 홀수번 캐시 라인을 처리하는 기계 +등에서 가장 잘 발생합니다. 포인터 P 는 홀수 번호의 캐시 라인에 있고, 변수 B 는 +짝수 번호 캐시 라인에 있다고 생각해 봅시다. 그런 상태에서 읽기 작업을 하는 CPU +의 짝수번 뱅크는 할 일이 쌓여 매우 바쁘지만 홀수번 뱅크는 할 일이 없어 아무 +일도 하지 않고 있었다면, 포인터 P 는 새 값 (&B) 을, 그리고 변수 B 는 옛날 값 +(2) 을 가지고 있는 상태가 보여질 수도 있습니다. + + +데이터 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다. +include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를 +참고하세요. 여기서 데이터 의존성 배리어는 RCU 로 관리되는 포인터의 타겟을 현재 +타겟에서 수정된 새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가 +완료되지 않은 채로 보여지는 일이 일어나지 않게 해줍니다. + +더 많은 예를 위해선 "캐시 일관성" 서브섹션을 참고하세요. + + +컨트롤 의존성 +------------- + +로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가 +없어서 읽기 메모리 배리어를 필요로 합니다. 아래의 코드를 봅시다: + + q = READ_ONCE(a); + if (q) { + <데이터 의존성 배리어> /* BUG: No data dependency!!! */ + p = READ_ONCE(b); + } + +이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 데이터 의존성이 +아니라 컨트롤 의존성이 존재하기 때문으로, 이런 상황에서 CPU 는 실행 속도를 더 +빠르게 하기 위해 분기 조건의 결과를 예측하고 코드를 재배치 할 수 있어서 다른 +CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레이션보다 먼저 발생한 +걸로 인식할 수 있습니다. 여기에 정말로 필요했던 건 다음과 같습니다: + + q = READ_ONCE(a); + if (q) { + <읽기 배리어> + p = READ_ONCE(b); + } + +하지만, 스토어 오퍼레이션은 예측적으로 수행되지 않습니다. 즉, 다음 예에서와 +같이 로드-스토어 컨트롤 의존성이 존재하는 경우에는 순서가 -지켜진다-는 +의미입니다. + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, p); + } + +컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. 그렇다곤 +하나, READ_ONCE() 는 반드시 사용해야 함을 부디 명심하세요! READ_ONCE() 가 +없다면, 컴파일러가 'a' 로부터의 로드를 'a' 로부터의 또다른 로드와, 'b' 로의 +스토어를 'b' 로의 또다른 스토어와 조합해 버려 매우 비직관적인 결과를 초래할 수 +있습니다. + +이걸로 끝이 아닌게, 컴파일러가 변수 'a' 의 값이 항상 0이 아니라고 증명할 수 +있다면, 앞의 예에서 "if" 문을 없애서 다음과 같이 최적화 할 수도 있습니다: + + q = a; + b = p; /* BUG: Compiler and CPU can both reorder!!! */ + +그러니 READ_ONCE() 를 반드시 사용하세요. + +다음과 같이 "if" 문의 양갈래 브랜치에 모두 존재하는 동일한 스토어에 대해 순서를 +강제하고 싶은 경우가 있을 수 있습니다: + + q = READ_ONCE(a); + if (q) { + barrier(); + WRITE_ONCE(b, p); + do_something(); + } else { + barrier(); + WRITE_ONCE(b, p); + do_something_else(); + } + +안타깝게도, 현재의 컴파일러들은 높은 최적화 레벨에서는 이걸 다음과 같이 +바꿔버립니다: + + q = READ_ONCE(a); + barrier(); + WRITE_ONCE(b, p); /* BUG: No ordering vs. load from a!!! */ + if (q) { + /* WRITE_ONCE(b, p); -- moved up, BUG!!! */ + do_something(); + } else { + /* WRITE_ONCE(b, p); -- moved up, BUG!!! */ + do_something_else(); + } + +이제 'a' 에서의 로드와 'b' 로의 스토어 사이에는 조건적 관계가 없기 때문에 CPU +는 이들의 순서를 바꿀 수 있게 됩니다: 이런 경우에 조건적 관계는 반드시 +필요한데, 모든 컴파일러 최적화가 이루어지고 난 후의 어셈블리 코드에서도 +마찬가지입니다. 따라서, 이 예에서 순서를 지키기 위해서는 smp_store_release() +와 같은 명시적 메모리 배리어가 필요합니다: + + q = READ_ONCE(a); + if (q) { + smp_store_release(&b, p); + do_something(); + } else { + smp_store_release(&b, p); + do_something_else(); + } + +반면에 명시적 메모리 배리어가 없다면, 이런 경우의 순서는 스토어 오퍼레이션들이 +서로 다를 때에만 보장되는데, 예를 들면 다음과 같은 경우입니다: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, p); + do_something(); + } else { + WRITE_ONCE(b, r); + do_something_else(); + } + +처음의 READ_ONCE() 는 컴파일러가 'a' 의 값을 증명해내는 것을 막기 위해 여전히 +필요합니다. + +또한, 로컬 변수 'q' 를 가지고 하는 일에 대해 주의해야 하는데, 그러지 않으면 +컴파일러는 그 값을 추측하고 또다시 필요한 조건관계를 없애버릴 수 있습니다. +예를 들면: + + q = READ_ONCE(a); + if (q % MAX) { + WRITE_ONCE(b, p); + do_something(); + } else { + WRITE_ONCE(b, r); + do_something_else(); + } + +만약 MAX 가 1 로 정의된 상수라면, 컴파일러는 (q % MAX) 는 0이란 것을 알아채고, +위의 코드를 아래와 같이 바꿔버릴 수 있습니다: + + q = READ_ONCE(a); + WRITE_ONCE(b, p); + do_something_else(); + +이렇게 되면, CPU 는 변수 'a' 로부터의 로드와 변수 'b' 로의 스토어 사이의 순서를 +지켜줄 필요가 없어집니다. barrier() 를 추가해 해결해 보고 싶겠지만, 그건 +도움이 안됩니다. 조건 관계는 사라졌고, barrier() 는 이를 되돌리지 못합니다. +따라서, 이 순서를 지켜야 한다면, MAX 가 1 보다 크다는 것을, 다음과 같은 방법을 +사용해 분명히 해야 합니다: + + q = READ_ONCE(a); + BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ + if (q % MAX) { + WRITE_ONCE(b, p); + do_something(); + } else { + WRITE_ONCE(b, r); + do_something_else(); + } + +'b' 로의 스토어들은 여전히 서로 다름을 알아두세요. 만약 그것들이 동일하면, +앞에서 이야기했듯, 컴파일러가 그 스토어 오퍼레이션들을 'if' 문 바깥으로 +끄집어낼 수 있습니다. + +또한 이진 조건문 평가에 너무 의존하지 않도록 조심해야 합니다. 다음의 예를 +봅시다: + + q = READ_ONCE(a); + if (q || 1 > 0) + WRITE_ONCE(b, 1); + +첫번째 조건만으로는 브랜치 조건 전체를 거짓으로 만들 수 없고 두번째 조건은 항상 +참이기 때문에, 컴파일러는 이 예를 다음과 같이 바꿔서 컨트롤 의존성을 없애버릴 +수 있습니다: + + q = READ_ONCE(a); + WRITE_ONCE(b, 1); + +이 예는 컴파일러가 코드를 추측으로 수정할 수 없도록 분명히 해야 한다는 점을 +강조합니다. 조금 더 일반적으로 말해서, READ_ONCE() 는 컴파일러에게 주어진 로드 +오퍼레이션을 위한 코드를 정말로 만들도록 하지만, 컴파일러가 그렇게 만들어진 +코드의 수행 결과를 사용하도록 강제하지는 않습니다. + +마지막으로, 컨트롤 의존성은 이행성 (transitivity) 을 제공하지 -않습니다-. 이건 +x 와 y 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로 +보이겠습니다: + + CPU 0 CPU 1 + ======================= ======================= + r1 = READ_ONCE(x); r2 = READ_ONCE(y); + if (r1 > 0) if (r2 > 0) + WRITE_ONCE(y, 1); WRITE_ONCE(x, 1); + + assert(!(r1 == 1 && r2 == 1)); + +이 두 CPU 예제에서 assert() 의 조건은 항상 참일 것입니다. 그리고, 만약 컨트롤 +의존성이 이행성을 (실제로는 그러지 않지만) 보장한다면, 다음의 CPU 가 추가되어도 +아래의 assert() 조건은 참이 될것입니다: + + CPU 2 + ===================== + WRITE_ONCE(x, 2); + + assert(!(r1 == 2 && r2 == 1 && x == 2)); /* FAILS!!! */ + +하지만 컨트롤 의존성은 이행성을 제공하지 -않기- 때문에, 세개의 CPU 예제가 실행 +완료된 후에 위의 assert() 의 조건은 거짓으로 평가될 수 있습니다. 세개의 CPU +예제가 순서를 지키길 원한다면, CPU 0 와 CPU 1 코드의 로드와 스토어 사이, "if" +문 바로 다음에 smp_mb()를 넣어야 합니다. 더 나아가서, 최초의 두 CPU 예제는 +매우 위험하므로 사용되지 않아야 합니다. + +이 두개의 예제는 다음 논문: +http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf 와 +이 사이트: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html 에 나온 LB 와 WWC +리트머스 테스트입니다. + +요약하자면: + + (*) 컨트롤 의존성은 앞의 로드들을 뒤의 스토어들에 대해 순서를 맞춰줍니다. + 하지만, 그 외의 어떤 순서도 보장하지 -않습니다-: 앞의 로드와 뒤의 로드들 + 사이에도, 앞의 스토어와 뒤의 스토어들 사이에도요. 이런 다른 형태의 + 순서가 필요하다면 smp_rmb() 나 smp_wmb()를, 또는, 앞의 스토어들과 뒤의 + 로드들 사이의 순서를 위해서는 smp_mb() 를 사용하세요. + + (*) "if" 문의 양갈래 브랜치가 같은 변수에의 동일한 스토어로 시작한다면, 그 + 스토어들은 각 스토어 앞에 smp_mb() 를 넣거나 smp_store_release() 를 + 사용해서 스토어를 하는 식으로 순서를 맞춰줘야 합니다. 이 문제를 해결하기 + 위해 "if" 문의 양갈래 브랜치의 시작 지점에 barrier() 를 넣는 것만으로는 + 충분한 해결이 되지 않는데, 이는 앞의 예에서 본것과 같이, 컴파일러의 + 최적화는 barrier() 가 의미하는 바를 지키면서도 컨트롤 의존성을 손상시킬 + 수 있기 때문이라는 점을 부디 알아두시기 바랍니다. + + (*) 컨트롤 의존성은 앞의 로드와 뒤의 스토어 사이에 최소 하나의, 실행 + 시점에서의 조건관계를 필요로 하며, 이 조건관계는 앞의 로드와 관계되어야 + 합니다. 만약 컴파일러가 조건 관계를 최적화로 없앨수 있다면, 순서도 + 최적화로 없애버렸을 겁니다. READ_ONCE() 와 WRITE_ONCE() 의 주의 깊은 + 사용은 주어진 조건 관계를 유지하는데 도움이 될 수 있습니다. + + (*) 컨트롤 의존성을 위해선 컴파일러가 조건관계를 없애버리는 것을 막아야 + 합니다. 주의 깊은 READ_ONCE() 나 atomic{,64}_read() 의 사용이 컨트롤 + 의존성이 사라지지 않게 하는데 도움을 줄 수 있습니다. 더 많은 정보를 + 위해선 "컴파일러 배리어" 섹션을 참고하시기 바랍니다. + + (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. + + (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-. 이행성이 필요하다면, + smp_mb() 를 사용하세요. + + +SMP 배리어 짝맞추기 +-------------------- + +CPU 간 상호작용을 다룰 때에 일부 타입의 메모리 배리어는 항상 짝을 맞춰 +사용되어야 합니다. 적절하게 짝을 맞추지 않은 코드는 사실상 에러에 가깝습니다. + +범용 배리어들은 범용 배리어끼리도 짝을 맞추지만 이행성이 없는 대부분의 다른 +타입의 배리어들과도 짝을 맞춥니다. ACQUIRE 배리어는 RELEASE 배리어와 짝을 +맞춥니다만, 둘 다 범용 배리어를 포함해 다른 배리어들과도 짝을 맞출 수 있습니다. +쓰기 배리어는 데이터 의존성 배리어나 컨트롤 의존성, ACQUIRE 배리어, RELEASE +배리어, 읽기 배리어, 또는 범용 배리어와 짝을 맞춥니다. 비슷하게 읽기 배리어나 +컨트롤 의존성, 또는 데이터 의존성 배리어는 쓰기 배리어나 ACQUIRE 배리어, +RELEASE 배리어, 또는 범용 배리어와 짝을 맞추는데, 다음과 같습니다: + + CPU 1 CPU 2 + =============== =============== + WRITE_ONCE(a, 1); + <쓰기 배리어> + WRITE_ONCE(b, 2); x = READ_ONCE(b); + <읽기 배리어> + y = READ_ONCE(a); + +또는: + + CPU 1 CPU 2 + =============== =============================== + a = 1; + <쓰기 배리어> + WRITE_ONCE(b, &a); x = READ_ONCE(b); + <데이터 의존성 배리어> + y = *x; + +또는: + + CPU 1 CPU 2 + =============== =============================== + r1 = READ_ONCE(y); + <범용 배리어> + WRITE_ONCE(y, 1); if (r2 = READ_ONCE(x)) { + <묵시적 컨트롤 의존성> + WRITE_ONCE(y, 1); + } + + assert(r1 == 0 || r2 == 0); + +기본적으로, 여기서의 읽기 배리어는 "더 완화된" 타입일 순 있어도 항상 존재해야 +합니다. + +[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 데이터 +의존성 배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다: + + CPU 1 CPU 2 + =================== =================== + WRITE_ONCE(a, 1); }---- --->{ v = READ_ONCE(c); + WRITE_ONCE(b, 2); } \ / { w = READ_ONCE(d); + <쓰기 배리어> \ <읽기 배리어> + WRITE_ONCE(c, 3); } / \ { x = READ_ONCE(a); + WRITE_ONCE(d, 4); }---- --->{ y = READ_ONCE(b); + + +메모리 배리어 시퀀스의 예 +------------------------- + +첫째, 쓰기 배리어는 스토어 오퍼레이션들의 부분적 순서 세우기로 동작합니다. +아래의 이벤트 시퀀스를 보세요: + + CPU 1 + ======================= + STORE A = 1 + STORE B = 2 + STORE C = 3 + <쓰기 배리어> + STORE D = 4 + STORE E = 5 + +이 이벤트 시퀀스는 메모리 일관성 시스템에 원소끼리의 순서가 존재하지 않는 집합 +{ STORE A, STORE B, STORE C } 가 역시 원소끼리의 순서가 존재하지 않는 집합 +{ STORE D, STORE E } 보다 먼저 일어난 것으로 시스템의 나머지 요소들에 보이도록 +전달됩니다: + + +-------+ : : + | | +------+ + | |------>| C=3 | } /\ + | | : +------+ }----- \ -----> 시스템의 나머지 요소에 + | | : | A=1 | } \/ 보여질 수 있는 이벤트들 + | | : +------+ } + | CPU 1 | : | B=2 | } + | | +------+ } + | | wwwwwwwwwwwwwwww } <--- 여기서 쓰기 배리어는 배리어 앞의 + | | +------+ } 모든 스토어가 배리어 뒤의 스토어 + | | : | E=5 | } 전에 메모리 시스템에 전달되도록 + | | : +------+ } 합니다 + | |------>| D=4 | } + | | +------+ + +-------+ : : + | + | CPU 1 에 의해 메모리 시스템에 전달되는 + | 일련의 스토어 오퍼레이션들 + V + + +둘째, 데이터 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서 +세우기로 동작합니다. 다음 일련의 이벤트들을 보세요: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <쓰기 배리어> + STORE C = &B LOAD X + STORE D = 4 LOAD C (gets &B) + LOAD *C (reads B) + +여기에 별다른 개입이 없다면, CPU 1 의 쓰기 배리어에도 불구하고 CPU 2 는 CPU 1 +의 이벤트들을 완전히 무작위적 순서로 인지하게 됩니다: + + +-------+ : : : : + | | +------+ +-------+ | CPU 2 에 인지되는 + | |------>| B=2 |----- --->| Y->8 | | 업데이트 이벤트 + | | : +------+ \ +-------+ | 시퀀스 + | CPU 1 | : | A=1 | \ --->| C->&Y | V + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + 분명히 잘못된 ---> | | B->7 |------>| | + B 의 값 인지 (!) | +-------+ | | + | : : | | + | +-------+ | | + X 의 로드가 B 의 ---> \ | X->9 |------>| | + 일관성 유지를 \ +-------+ | | + 지연시킴 ----->| B->2 | +-------+ + +-------+ + : : + + +앞의 예에서, CPU 2 는 (B 의 값이 될) *C 의 값 읽기가 C 의 LOAD 뒤에 이어짐에도 +B 가 7 이라는 결과를 얻습니다. + +하지만, 만약 데이터 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에 +있었다면: + + CPU 1 CPU 2 + ======================= ======================= + { B = 7; X = 9; Y = 8; C = &Y } + STORE A = 1 + STORE B = 2 + <쓰기 배리어> + STORE C = &B LOAD X + STORE D = 4 LOAD C (gets &B) + <데이터 의존성 배리어> + LOAD *C (reads B) + +다음과 같이 됩니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| B=2 |----- --->| Y->8 | + | | : +------+ \ +-------+ + | CPU 1 | : | A=1 | \ --->| C->&Y | + | | +------+ | +-------+ + | | wwwwwwwwwwwwwwww | : : + | | +------+ | : : + | | : | C=&B |--- | : : +-------+ + | | : +------+ \ | +-------+ | | + | |------>| D=4 | ----------->| C->&B |------>| | + | | +------+ | +-------+ | | + +-------+ : : | : : | | + | : : | | + | : : | CPU 2 | + | +-------+ | | + | | X->9 |------>| | + | +-------+ | | + C 로의 스토어 앞의 ---> \ ddddddddddddddddd | | + 모든 이벤트 결과가 \ +-------+ | | + 뒤의 로드에게 ----->| B->2 |------>| | + 보이게 강제한다 +-------+ | | + : : +-------+ + + +셋째, 읽기 배리어는 로드 오퍼레이션들에의 부분적 순서 세우기로 동작합니다. +아래의 일련의 이벤트를 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + LOAD A + +CPU 1 은 쓰기 배리어를 쳤지만, 별다른 개입이 없다면 CPU 2 는 CPU 1 에서 행해진 +이벤트의 결과를 무작위적 순서로 인지하게 됩니다. + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | | A->0 |------>| | + | +-------+ | | + | : : +-------+ + \ : : + \ +-------+ + ---->| A->1 | + +-------+ + : : + + +하지만, 만약 읽기 배리어가 B 의 로드와 A 의 로드 사이에 존재한다면: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + <읽기 배리어> + LOAD A + +CPU 1 에 의해 만들어진 부분적 순서가 CPU 2 에도 그대로 인지됩니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + 여기서 읽기 배리어는 ----> \ rrrrrrrrrrrrrrrrr | | + B 로의 스토어 전의 \ +-------+ | | + 모든 결과를 CPU 2 에 ---->| A->1 |------>| | + 보이도록 한다 +-------+ | | + : : +-------+ + + +더 완벽한 설명을 위해, A 의 로드가 읽기 배리어 앞과 뒤에 있으면 어떻게 될지 +생각해 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + { A = 0, B = 9 } + STORE A=1 + <쓰기 배리어> + STORE B=2 + LOAD B + LOAD A [first load of A] + <읽기 배리어> + LOAD A [second load of A] + +A 의 로드 두개가 모두 B 의 로드 뒤에 있지만, 서로 다른 값을 얻어올 수 +있습니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + | : : | | + | +-------+ | | + | | A->0 |------>| 1st | + | +-------+ | | + 여기서 읽기 배리어는 ----> \ rrrrrrrrrrrrrrrrr | | + B 로의 스토어 전의 \ +-------+ | | + 모든 결과를 CPU 2 에 ---->| A->1 |------>| 2nd | + 보이도록 한다 +-------+ | | + : : +-------+ + + +하지만 CPU 1 에서의 A 업데이트는 읽기 배리어가 완료되기 전에도 보일 수도 +있긴 합니다: + + +-------+ : : : : + | | +------+ +-------+ + | |------>| A=1 |------ --->| A->0 | + | | +------+ \ +-------+ + | CPU 1 | wwwwwwwwwwwwwwww \ --->| B->9 | + | | +------+ | +-------+ + | |------>| B=2 |--- | : : + | | +------+ \ | : : +-------+ + +-------+ : : \ | +-------+ | | + ---------->| B->2 |------>| | + | +-------+ | CPU 2 | + | : : | | + \ : : | | + \ +-------+ | | + ---->| A->1 |------>| 1st | + +-------+ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + | A->1 |------>| 2nd | + +-------+ | | + : : +-------+ + + +여기서 보장되는 건, 만약 B 의 로드가 B == 2 라는 결과를 봤다면, A 에의 두번째 +로드는 항상 A == 1 을 보게 될 것이라는 겁니다. A 에의 첫번째 로드에는 그런 +보장이 없습니다; A == 0 이거나 A == 1 이거나 둘 중 하나의 결과를 보게 될겁니다. + + +읽기 메모리 배리어 VS 로드 예측 +------------------------------- + +많은 CPU들이 로드를 예측적으로 (speculatively) 합니다: 어떤 데이터를 메모리에서 +로드해야 하게 될지 예측을 했다면, 해당 데이터를 로드하는 인스트럭션을 실제로는 +아직 만나지 않았더라도 다른 로드 작업이 없어 버스 (bus) 가 아무 일도 하고 있지 +않다면, 그 데이터를 로드합니다. 이후에 실제 로드 인스트럭션이 실행되면 CPU 가 +이미 그 값을 가지고 있기 때문에 그 로드 인스트럭션은 즉시 완료됩니다. + +해당 CPU 는 실제로는 그 값이 필요치 않았다는 사실이 나중에 드러날 수도 있는데 - +해당 로드 인스트럭션이 브랜치로 우회되거나 했을 수 있겠죠 - , 그렇게 되면 앞서 +읽어둔 값을 버리거나 나중의 사용을 위해 캐시에 넣어둘 수 있습니다. + +다음을 생각해 봅시다: + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE } 나누기 명령은 일반적으로 + DIVIDE } 긴 시간을 필요로 합니다 + LOAD A + +는 이렇게 될 수 있습니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측해서 수행한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + 나누기가 끝나면 ---> ---> : : ~-->| | + CPU 는 해당 LOAD 를 : : | | + 즉각 완료한다 : : +-------+ + + +읽기 배리어나 데이터 의존성 배리어를 두번째 로드 직전에 놓는다면: + + CPU 1 CPU 2 + ======================= ======================= + LOAD B + DIVIDE + DIVIDE + <읽기 배리어> + LOAD A + +예측으로 얻어진 값은 사용된 배리어의 타입에 따라서 해당 값이 옳은지 검토되게 +됩니다. 만약 해당 메모리 영역에 변화가 없었다면, 예측으로 얻어두었던 값이 +사용됩니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrr~ | | + : : ~ | | + : : ~-->| | + : : | | + : : +-------+ + + +하지만 다른 CPU 에서 업데이트나 무효화가 있었다면, 그 예측은 무효화되고 그 값은 +다시 읽혀집니다: + + : : +-------+ + +-------+ | | + --->| B->2 |------>| | + +-------+ | CPU 2 | + : :DIVIDE | | + +-------+ | | + 나누기 하느라 바쁜 ---> --->| A->0 |~~~~ | | + CPU 는 A 의 LOAD 를 +-------+ ~ | | + 예측한다 : : ~ | | + : :DIVIDE | | + : : ~ | | + : : ~ | | + rrrrrrrrrrrrrrrrr | | + +-------+ | | + 예측성 동작은 무효화 되고 ---> --->| A->1 |------>| | + 업데이트된 값이 다시 읽혀진다 +-------+ | | + : : +-------+ + + +이행성 +------ + +이행성(transitivity)은 실제의 컴퓨터 시스템에서 항상 제공되지는 않는, 순서 +맞추기에 대한 상당히 직관적인 개념입니다. 다음의 예가 이행성을 보여줍니다: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <범용 배리어> <범용 배리어> + LOAD Y LOAD X + +CPU 2 의 X 로드가 1을 리턴했고 Y 로드가 0을 리턴했다고 해봅시다. 이는 CPU 2 의 +X 로드가 CPU 1 의 X 스토어 뒤에 이루어졌고 CPU 2 의 Y 로드는 CPU 3 의 Y 스토어 +전에 이루어졌음을 의미합니다. 그럼 "CPU 3 의 X 로드는 0을 리턴할 수 있나요?" + +CPU 2 의 X 로드는 CPU 1 의 스토어 후에 이루어졌으니, CPU 3 의 X 로드는 1을 +리턴하는게 자연스럽습니다. 이런 생각이 이행성의 한 예입니다: CPU A 에서 실행된 +로드가 CPU B 에서의 같은 변수에 대한 로드를 뒤따른다면, CPU A 의 로드는 CPU B +의 로드가 내놓은 값과 같거나 그 후의 값을 내놓아야 합니다. + +리눅스 커널에서 범용 배리어의 사용은 이행성을 보장합니다. 따라서, 앞의 예에서 +CPU 2 의 X 로드가 1을, Y 로드는 0을 리턴했다면, CPU 3 의 X 로드는 반드시 1을 +리턴합니다. + +하지만, 읽기나 쓰기 배리어에 대해서는 이행성이 보장되지 -않습니다-. 예를 들어, +앞의 예에서 CPU 2 의 범용 배리어가 아래처럼 읽기 배리어로 바뀐 경우를 생각해 +봅시다: + + CPU 1 CPU 2 CPU 3 + ======================= ======================= ======================= + { X = 0, Y = 0 } + STORE X=1 LOAD X STORE Y=1 + <읽기 배리어> <범용 배리어> + LOAD Y LOAD X + +이 코드는 이행성을 갖지 않습니다: 이 예에서는, CPU 2 의 X 로드가 1을 +리턴하고, Y 로드는 0을 리턴하지만 CPU 3 의 X 로드가 0을 리턴하는 것도 완전히 +합법적입니다. + +CPU 2 의 읽기 배리어가 자신의 읽기는 순서를 맞춰줘도, CPU 1 의 스토어와의 +순서를 맞춰준다고는 보장할 수 없다는게 핵심입니다. 따라서, CPU 1 과 CPU 2 가 +버퍼나 캐시를 공유하는 시스템에서 이 예제 코드가 실행된다면, CPU 2 는 CPU 1 이 +쓴 값에 좀 빨리 접근할 수 있을 것입니다. 따라서 CPU 1 과 CPU 2 의 접근으로 +조합된 순서를 모든 CPU 가 동의할 수 있도록 하기 위해 범용 배리어가 필요합니다. + +범용 배리어는 "글로벌 이행성"을 제공해서, 모든 CPU 들이 오퍼레이션들의 순서에 +동의하게 할 것입니다. 반면, release-acquire 조합은 "로컬 이행성" 만을 +제공해서, 해당 조합이 사용된 CPU 들만이 해당 액세스들의 조합된 순서에 동의함이 +보장됩니다. 예를 들어, 존경스런 Herman Hollerith 의 C 코드로 보면: + + int u, v, x, y, z; + + void cpu0(void) + { + r0 = smp_load_acquire(&x); + WRITE_ONCE(u, 1); + smp_store_release(&y, 1); + } + + void cpu1(void) + { + r1 = smp_load_acquire(&y); + r4 = READ_ONCE(v); + r5 = READ_ONCE(u); + smp_store_release(&z, 1); + } + + void cpu2(void) + { + r2 = smp_load_acquire(&z); + smp_store_release(&x, 1); + } + + void cpu3(void) + { + WRITE_ONCE(v, 1); + smp_mb(); + r3 = READ_ONCE(u); + } + +cpu0(), cpu1(), 그리고 cpu2() 는 smp_store_release()/smp_load_acquire() 쌍의 +연결을 통한 로컬 이행성에 동참하고 있으므로, 다음과 같은 결과는 나오지 않을 +겁니다: + + r0 == 1 && r1 == 1 && r2 == 1 + +더 나아가서, cpu0() 와 cpu1() 사이의 release-acquire 관계로 인해, cpu1() 은 +cpu0() 의 쓰기를 봐야만 하므로, 다음과 같은 결과도 없을 겁니다: + + r1 == 1 && r5 == 0 + +하지만, release-acquire 타동성은 동참한 CPU 들에만 적용되므로 cpu3() 에는 +적용되지 않습니다. 따라서, 다음과 같은 결과가 가능합니다: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 + +비슷하게, 다음과 같은 결과도 가능합니다: + + r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 && r5 == 1 + +cpu0(), cpu1(), 그리고 cpu2() 는 그들의 읽기와 쓰기를 순서대로 보게 되지만, +release-acquire 체인에 관여되지 않은 CPU 들은 그 순서에 이견을 가질 수 +있습니다. 이런 이견은 smp_load_acquire() 와 smp_store_release() 의 구현에 +사용되는 완화된 메모리 배리어 인스트럭션들은 항상 배리어 앞의 스토어들을 뒤의 +로드들에 앞세울 필요는 없다는 사실에서 기인합니다. 이 말은 cpu3() 는 cpu0() 의 +u 로의 스토어를 cpu1() 의 v 로부터의 로드 뒤에 일어난 것으로 볼 수 있다는 +뜻입니다, cpu0() 와 cpu1() 은 이 두 오퍼레이션이 의도된 순서대로 일어났음에 +모두 동의하는데도 말입니다. + +하지만, smp_load_acquire() 는 마술이 아님을 명심하시기 바랍니다. 구체적으로, +이 함수는 단순히 순서 규칙을 지키며 인자로부터의 읽기를 수행합니다. 이것은 +어떤 특정한 값이 읽힐 것인지는 보장하지 -않습니다-. 따라서, 다음과 같은 결과도 +가능합니다: + + r0 == 0 && r1 == 0 && r2 == 0 && r5 == 0 + +이런 결과는 어떤 것도 재배치 되지 않는, 순차적 일관성을 가진 가상의 +시스템에서도 일어날 수 있음을 기억해 두시기 바랍니다. + +다시 말하지만, 당신의 코드가 글로벌 이행성을 필요로 한다면, 범용 배리어를 +사용하십시오. + + +================== +명시적 커널 배리어 +================== + +리눅스 커널은 서로 다른 단계에서 동작하는 다양한 배리어들을 가지고 있습니다: + + (*) 컴파일러 배리어. + + (*) CPU 메모리 배리어. + + (*) MMIO 쓰기 배리어. + + +컴파일러 배리어 +--------------- + +리눅스 커널은 컴파일러가 메모리 액세스를 재배치 하는 것을 막아주는 명시적인 +컴파일러 배리어를 가지고 있습니다: + + barrier(); + +이건 범용 배리어입니다 -- barrier() 의 읽기-읽기 나 쓰기-쓰기 변종은 없습니다. +하지만, READ_ONCE() 와 WRITE_ONCE() 는 특정 액세스들에 대해서만 동작하는 +barrier() 의 완화된 형태로 볼 수 있습니다. + +barrier() 함수는 다음과 같은 효과를 갖습니다: + + (*) 컴파일러가 barrier() 뒤의 액세스들이 barrier() 앞의 액세스보다 앞으로 + 재배치되지 못하게 합니다. 예를 들어, 인터럽트 핸들러 코드와 인터럽트 당한 + 코드 사이의 통신을 신중히 하기 위해 사용될 수 있습니다. + + (*) 루프에서, 컴파일러가 루프 조건에 사용된 변수를 매 이터레이션마다 + 메모리에서 로드하지 않아도 되도록 최적화 하는걸 방지합니다. + +READ_ONCE() 와 WRITE_ONCE() 함수는 싱글 쓰레드 코드에서는 문제 없지만 동시성이 +있는 코드에서는 문제가 될 수 있는 모든 최적화를 막습니다. 이런 류의 최적화에 +대한 예를 몇가지 들어보면 다음과 같습니다: + + (*) 컴파일러는 같은 변수에 대한 로드와 스토어를 재배치 할 수 있고, 어떤 + 경우에는 CPU가 같은 변수로부터의 로드들을 재배치할 수도 있습니다. 이는 + 다음의 코드가: + + a[0] = x; + a[1] = x; + + x 의 예전 값이 a[1] 에, 새 값이 a[0] 에 있게 할 수 있다는 뜻입니다. + 컴파일러와 CPU가 이런 일을 못하게 하려면 다음과 같이 해야 합니다: + + a[0] = READ_ONCE(x); + a[1] = READ_ONCE(x); + + 즉, READ_ONCE() 와 WRITE_ONCE() 는 여러 CPU 에서 하나의 변수에 가해지는 + 액세스들에 캐시 일관성을 제공합니다. + + (*) 컴파일러는 같은 변수에 대한 연속적인 로드들을 병합할 수 있습니다. 그런 + 병합 작업으로 컴파일러는 다음의 코드를: + + while (tmp = a) + do_something_with(tmp); + + 다음과 같이, 싱글 쓰레드 코드에서는 말이 되지만 개발자의 의도와 전혀 맞지 + 않는 방향으로 "최적화" 할 수 있습니다: + + if (tmp = a) + for (;;) + do_something_with(tmp); + + 컴파일러가 이런 짓을 하지 못하게 하려면 READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + (*) 예컨대 레지스터 사용량이 많아 컴파일러가 모든 데이터를 레지스터에 담을 수 + 없는 경우, 컴파일러는 변수를 다시 로드할 수 있습니다. 따라서 컴파일러는 + 앞의 예에서 변수 'tmp' 사용을 최적화로 없애버릴 수 있습니다: + + while (tmp = a) + do_something_with(tmp); + + 이 코드는 다음과 같이 싱글 쓰레드에서는 완벽하지만 동시성이 존재하는 + 경우엔 치명적인 코드로 바뀔 수 있습니다: + + while (a) + do_something_with(a); + + 예를 들어, 최적화된 이 코드는 변수 a 가 다른 CPU 에 의해 "while" 문과 + do_something_with() 호출 사이에 바뀌어 do_something_with() 에 0을 넘길 + 수도 있습니다. + + 이번에도, 컴파일러가 그런 짓을 하는걸 막기 위해 READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + 레지스터가 부족한 상황을 겪는 경우, 컴파일러는 tmp 를 스택에 저장해둘 수도 + 있습니다. 컴파일러가 변수를 다시 읽어들이는건 이렇게 저장해두고 후에 다시 + 읽어들이는데 드는 오버헤드 때문입니다. 그렇게 하는게 싱글 쓰레드 + 코드에서는 안전하므로, 안전하지 않은 경우에는 컴파일러에게 직접 알려줘야 + 합니다. + + (*) 컴파일러는 그 값이 무엇일지 알고 있다면 로드를 아예 안할 수도 있습니다. + 예를 들어, 다음의 코드는 변수 'a' 의 값이 항상 0임을 증명할 수 있다면: + + while (tmp = a) + do_something_with(tmp); + + 이렇게 최적화 되어버릴 수 있습니다: + + do { } while (0); + + 이 변환은 싱글 쓰레드 코드에서는 도움이 되는데 로드와 브랜치를 제거했기 + 때문입니다. 문제는 컴파일러가 'a' 의 값을 업데이트 하는건 현재의 CPU 하나 + 뿐이라는 가정 위에서 증명을 했다는데 있습니다. 만약 변수 'a' 가 공유되어 + 있다면, 컴파일러의 증명은 틀린 것이 될겁니다. 컴파일러는 그 자신이 + 생각하는 것만큼 많은 것을 알고 있지 못함을 컴파일러에게 알리기 위해 + READ_ONCE() 를 사용하세요: + + while (tmp = READ_ONCE(a)) + do_something_with(tmp); + + 하지만 컴파일러는 READ_ONCE() 뒤에 나오는 값에 대해서도 눈길을 두고 있음을 + 기억하세요. 예를 들어, 다음의 코드에서 MAX 는 전처리기 매크로로, 1의 값을 + 갖는다고 해봅시다: + + while ((tmp = READ_ONCE(a)) % MAX) + do_something_with(tmp); + + 이렇게 되면 컴파일러는 MAX 를 가지고 수행되는 "%" 오퍼레이터의 결과가 항상 + 0이라는 것을 알게 되고, 컴파일러가 코드를 실질적으로는 존재하지 않는 + 것처럼 최적화 하는 것이 허용되어 버립니다. ('a' 변수의 로드는 여전히 + 행해질 겁니다.) + + (*) 비슷하게, 컴파일러는 변수가 저장하려 하는 값을 이미 가지고 있다는 것을 + 알면 스토어 자체를 제거할 수 있습니다. 이번에도, 컴파일러는 현재의 CPU + 만이 그 변수에 값을 쓰는 오로지 하나의 존재라고 생각하여 공유된 변수에 + 대해서는 잘못된 일을 하게 됩니다. 예를 들어, 다음과 같은 경우가 있을 수 + 있습니다: + + a = 0; + ... 변수 a 에 스토어를 하지 않는 코드 ... + a = 0; + + 컴파일러는 변수 'a' 의 값은 이미 0이라는 것을 알고, 따라서 두번째 스토어를 + 삭제할 겁니다. 만약 다른 CPU 가 그 사이 변수 'a' 에 다른 값을 썼다면 + 황당한 결과가 나올 겁니다. + + 컴파일러가 그런 잘못된 추측을 하지 않도록 WRITE_ONCE() 를 사용하세요: + + WRITE_ONCE(a, 0); + ... 변수 a 에 스토어를 하지 않는 코드 ... + WRITE_ONCE(a, 0); + + (*) 컴파일러는 하지 말라고 하지 않으면 메모리 액세스들을 재배치 할 수 + 있습니다. 예를 들어, 다음의 프로세스 레벨 코드와 인터럽트 핸들러 사이의 + 상호작용을 생각해 봅시다: + + void process_level(void) + { + msg = get_message(); + flag = true; + } + + void interrupt_handler(void) + { + if (flag) + process_message(msg); + } + + 이 코드에는 컴파일러가 process_level() 을 다음과 같이 변환하는 것을 막을 + 수단이 없고, 이런 변환은 싱글쓰레드에서라면 실제로 훌륭한 선택일 수 + 있습니다: + + void process_level(void) + { + flag = true; + msg = get_message(); + } + + 이 두개의 문장 사이에 인터럽트가 발생한다면, interrupt_handler() 는 의미를 + 알 수 없는 메세지를 받을 수도 있습니다. 이걸 막기 위해 다음과 같이 + WRITE_ONCE() 를 사용하세요: + + void process_level(void) + { + WRITE_ONCE(msg, get_message()); + WRITE_ONCE(flag, true); + } + + void interrupt_handler(void) + { + if (READ_ONCE(flag)) + process_message(READ_ONCE(msg)); + } + + interrupt_handler() 안에서도 중첩된 인터럽트나 NMI 와 같이 인터럽트 핸들러 + 역시 'flag' 와 'msg' 에 접근하는 또다른 무언가에 인터럽트 될 수 있다면 + READ_ONCE() 와 WRITE_ONCE() 를 사용해야 함을 기억해 두세요. 만약 그런 + 가능성이 없다면, interrupt_handler() 안에서는 문서화 목적이 아니라면 + READ_ONCE() 와 WRITE_ONCE() 는 필요치 않습니다. (근래의 리눅스 커널에서 + 중첩된 인터럽트는 보통 잘 일어나지 않음도 기억해 두세요, 실제로, 어떤 + 인터럽트 핸들러가 인터럽트가 활성화된 채로 리턴하면 WARN_ONCE() 가 + 실행됩니다.) + + 컴파일러는 READ_ONCE() 와 WRITE_ONCE() 뒤의 READ_ONCE() 나 WRITE_ONCE(), + barrier(), 또는 비슷한 것들을 담고 있지 않은 코드를 움직일 수 있을 것으로 + 가정되어야 합니다. + + 이 효과는 barrier() 를 통해서도 만들 수 있지만, READ_ONCE() 와 + WRITE_ONCE() 가 좀 더 안목 높은 선택입니다: READ_ONCE() 와 WRITE_ONCE()는 + 컴파일러에 주어진 메모리 영역에 대해서만 최적화 가능성을 포기하도록 + 하지만, barrier() 는 컴파일러가 지금까지 기계의 레지스터에 캐시해 놓은 + 모든 메모리 영역의 값을 버려야 하게 하기 때문입니다. 물론, 컴파일러는 + READ_ONCE() 와 WRITE_ONCE() 가 일어난 순서도 지켜줍니다, CPU 는 당연히 + 그 순서를 지킬 의무가 없지만요. + + (*) 컴파일러는 다음의 예에서와 같이 변수에의 스토어를 날조해낼 수도 있습니다: + + if (a) + b = a; + else + b = 42; + + 컴파일러는 아래와 같은 최적화로 브랜치를 줄일 겁니다: + + b = 42; + if (a) + b = a; + + 싱글 쓰레드 코드에서 이 최적화는 안전할 뿐 아니라 브랜치 갯수를 + 줄여줍니다. 하지만 안타깝게도, 동시성이 있는 코드에서는 이 최적화는 다른 + CPU 가 'b' 를 로드할 때, -- 'a' 가 0이 아닌데도 -- 가짜인 값, 42를 보게 + 되는 경우를 가능하게 합니다. 이걸 방지하기 위해 WRITE_ONCE() 를 + 사용하세요: + + if (a) + WRITE_ONCE(b, a); + else + WRITE_ONCE(b, 42); + + 컴파일러는 로드를 만들어낼 수도 있습니다. 일반적으로는 문제를 일으키지 + 않지만, 캐시 라인 바운싱을 일으켜 성능과 확장성을 떨어뜨릴 수 있습니다. + 날조된 로드를 막기 위해선 READ_ONCE() 를 사용하세요. + + (*) 정렬된 메모리 주소에 위치한, 한번의 메모리 참조 인스트럭션으로 액세스 + 가능한 크기의 데이터는 하나의 큰 액세스가 여러개의 작은 액세스들로 + 대체되는 "로드 티어링(load tearing)" 과 "스토어 티어링(store tearing)" 을 + 방지합니다. 예를 들어, 주어진 아키텍쳐가 7-bit imeediate field 를 갖는 + 16-bit 스토어 인스트럭션을 제공한다면, 컴파일러는 다음의 32-bit 스토어를 + 구현하는데에 두개의 16-bit store-immediate 명령을 사용하려 할겁니다: + + p = 0x00010002; + + 스토어 할 상수를 만들고 그 값을 스토어 하기 위해 두개가 넘는 인스트럭션을 + 사용하게 되는, 이런 종류의 최적화를 GCC 는 실제로 함을 부디 알아 두십시오. + 이 최적화는 싱글 쓰레드 코드에서는 성공적인 최적화 입니다. 실제로, 근래에 + 발생한 (그리고 고쳐진) 버그는 GCC 가 volatile 스토어에 비정상적으로 이 + 최적화를 사용하게 했습니다. 그런 버그가 없다면, 다음의 예에서 + WRITE_ONCE() 의 사용은 스토어 티어링을 방지합니다: + + WRITE_ONCE(p, 0x00010002); + + Packed 구조체의 사용 역시 다음의 예처럼 로드 / 스토어 티어링을 유발할 수 + 있습니다: + + struct __attribute__((__packed__)) foo { + short a; + int b; + short c; + }; + struct foo foo1, foo2; + ... + + foo2.a = foo1.a; + foo2.b = foo1.b; + foo2.c = foo1.c; + + READ_ONCE() 나 WRITE_ONCE() 도 없고 volatile 마킹도 없기 때문에, + 컴파일러는 이 세개의 대입문을 두개의 32-bit 로드와 두개의 32-bit 스토어로 + 변환할 수 있습니다. 이는 'foo1.b' 의 값의 로드 티어링과 'foo2.b' 의 + 스토어 티어링을 초래할 겁니다. 이 예에서도 READ_ONCE() 와 WRITE_ONCE() + 가 티어링을 막을 수 있습니다: + + foo2.a = foo1.a; + WRITE_ONCE(foo2.b, READ_ONCE(foo1.b)); + foo2.c = foo1.c; + +그렇지만, volatile 로 마크된 변수에 대해서는 READ_ONCE() 와 WRITE_ONCE() 가 +필요치 않습니다. 예를 들어, 'jiffies' 는 volatile 로 마크되어 있기 때문에, +READ_ONCE(jiffies) 라고 할 필요가 없습니다. READ_ONCE() 와 WRITE_ONCE() 가 +실은 volatile 캐스팅으로 구현되어 있어서 인자가 이미 volatile 로 마크되어 +있다면 또다른 효과를 내지는 않기 때문입니다. + +이 컴파일러 배리어들은 CPU 에는 직접적 효과를 전혀 만들지 않기 때문에, 결국은 +재배치가 일어날 수도 있음을 부디 기억해 두십시오. + + +CPU 메모리 배리어 +----------------- + +리눅스 커널은 다음의 여덟개 기본 CPU 메모리 배리어를 가지고 있습니다: + + TYPE MANDATORY SMP CONDITIONAL + =============== ======================= =========================== + 범용 mb() smp_mb() + 쓰기 wmb() smp_wmb() + 읽기 rmb() smp_rmb() + 데이터 의존성 read_barrier_depends() smp_read_barrier_depends() + + +데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를 +포함합니다. 데이터 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지 +않습니다. + +방백: 데이터 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬 +것으로 (예: `a[b]` 는 a[b] 를 로드 하기 전에 b 의 값을 먼저 로드한다) +기대되지만, C 언어 사양에는 컴파일러가 b 의 값을 추측 (예: 1 과 같음) 해서 +b 로드 전에 a 로드를 하는 코드 (예: tmp = a[1]; if (b != 1) tmp = a[b]; ) 를 +만들지 않아야 한다는 내용 같은 건 없습니다. 또한 컴파일러는 a[b] 를 로드한 +후에 b 를 또다시 로드할 수도 있어서, a[b] 보다 최신 버전의 b 값을 가질 수도 +있습니다. 이런 문제들의 해결책에 대한 의견 일치는 아직 없습니다만, 일단 +READ_ONCE() 매크로부터 보기 시작하는게 좋은 시작이 될겁니다. + +SMP 메모리 배리어들은 유니프로세서로 컴파일된 시스템에서는 컴파일러 배리어로 +바뀌는데, 하나의 CPU 는 스스로 일관성을 유지하고, 겹치는 액세스들 역시 올바른 +순서로 행해질 것으로 생각되기 때문입니다. 하지만, 아래의 "Virtual Machine +Guests" 서브섹션을 참고하십시오. + +[!] SMP 시스템에서 공유메모리로의 접근들을 순서 세워야 할 때, SMP 메모리 +배리어는 _반드시_ 사용되어야 함을 기억하세요, 그대신 락을 사용하는 것으로도 +충분하긴 하지만 말이죠. + +Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효과만 통제하기에는 +불필요한 오버헤드를 갖기 때문에 SMP 효과만 통제하면 되는 곳에는 사용되지 않아야 +합니다. 하지만, 느슨한 순서 규칙의 메모리 I/O 윈도우를 통한 MMIO 의 효과를 +통제할 때에는 mandatory 배리어들이 사용될 수 있습니다. 이 배리어들은 +컴파일러와 CPU 모두 재배치를 못하도록 함으로써 메모리 오퍼레이션들이 디바이스에 +보여지는 순서에도 영향을 주기 때문에, SMP 가 아닌 시스템이라 할지라도 필요할 수 +있습니다. + + +일부 고급 배리어 함수들도 있습니다: + + (*) smp_store_mb(var, value) + + 이 함수는 특정 변수에 특정 값을 대입하고 범용 메모리 배리어를 칩니다. + UP 컴파일에서는 컴파일러 배리어보다 더한 것을 친다고는 보장되지 않습니다. + + + (*) smp_mb__before_atomic(); + (*) smp_mb__after_atomic(); + + 이것들은 값을 리턴하지 않는 (더하기, 빼기, 증가, 감소와 같은) 어토믹 + 함수들을 위한, 특히 그것들이 레퍼런스 카운팅에 사용될 때를 위한 + 함수들입니다. 이 함수들은 메모리 배리어를 내포하고 있지는 않습니다. + + 이것들은 값을 리턴하지 않으며 어토믹한 (set_bit 과 clear_bit 같은) 비트 + 연산에도 사용될 수 있습니다. + + 한 예로, 객체 하나를 무효한 것으로 표시하고 그 객체의 레퍼런스 카운트를 + 감소시키는 다음 코드를 보세요: + + obj->dead = 1; + smp_mb__before_atomic(); + atomic_dec(&obj->ref_count); + + 이 코드는 객체의 업데이트된 death 마크가 레퍼런스 카운터 감소 동작 + *전에* 보일 것을 보장합니다. + + 더 많은 정보를 위해선 Documentation/atomic_ops.txt 문서를 참고하세요. + 어디서 이것들을 사용해야 할지 궁금하다면 "어토믹 오퍼레이션" 서브섹션을 + 참고하세요. + + + (*) lockless_dereference(); + + 이 함수는 smp_read_barrier_depends() 데이터 의존성 배리어를 사용하는 + 포인터 읽어오기 래퍼(wrapper) 함수로 생각될 수 있습니다. + + 객체의 라이프타임이 RCU 외의 메커니즘으로 관리된다는 점을 제외하면 + rcu_dereference() 와도 유사한데, 예를 들면 객체가 시스템이 꺼질 때에만 + 제거되는 경우 등입니다. 또한, lockless_dereference() 은 RCU 와 함께 + 사용될수도, RCU 없이 사용될 수도 있는 일부 데이터 구조에 사용되고 + 있습니다. + + + (*) dma_wmb(); + (*) dma_rmb(); + + 이것들은 CPU 와 DMA 가능한 디바이스에서 모두 액세스 가능한 공유 메모리의 + 읽기, 쓰기 작업들의 순서를 보장하기 위해 consistent memory 에서 사용하기 + 위한 것들입니다. + + 예를 들어, 디바이스와 메모리를 공유하며, 디스크립터 상태 값을 사용해 + 디스크립터가 디바이스에 속해 있는지 아니면 CPU 에 속해 있는지 표시하고, + 공지용 초인종(doorbell) 을 사용해 업데이트된 디스크립터가 디바이스에 사용 + 가능해졌음을 공지하는 디바이스 드라이버를 생각해 봅시다: + + if (desc->status != DEVICE_OWN) { + /* 디스크립터를 소유하기 전에는 데이터를 읽지 않음 */ + dma_rmb(); + + /* 데이터를 읽고 씀 */ + read_data = desc->data; + desc->data = write_data; + + /* 상태 업데이트 전 수정사항을 반영 */ + dma_wmb(); + + /* 소유권을 수정 */ + desc->status = DEVICE_OWN; + + /* MMIO 를 통해 디바이스에 공지를 하기 전에 메모리를 동기화 */ + wmb(); + + /* 업데이트된 디스크립터의 디바이스에 공지 */ + writel(DESC_NOTIFY, doorbell); + } + + dma_rmb() 는 디스크립터로부터 데이터를 읽어오기 전에 디바이스가 소유권을 + 내놓았음을 보장하게 하고, dma_wmb() 는 디바이스가 자신이 소유권을 다시 + 가졌음을 보기 전에 디스크립터에 데이터가 쓰였음을 보장합니다. wmb() 는 + 캐시 일관성이 없는 (cache incoherent) MMIO 영역에 쓰기를 시도하기 전에 + 캐시 일관성이 있는 메모리 (cache coherent memory) 쓰기가 완료되었음을 + 보장해주기 위해 필요합니다. + + consistent memory 에 대한 자세한 내용을 위해선 Documentation/DMA-API.txt + 문서를 참고하세요. + + +MMIO 쓰기 배리어 +---------------- + +리눅스 커널은 또한 memory-mapped I/O 쓰기를 위한 특별한 배리어도 가지고 +있습니다: + + mmiowb(); + +이것은 mandatory 쓰기 배리어의 변종으로, 완화된 순서 규칙의 I/O 영역에으로의 +쓰기가 부분적으로 순서를 맞추도록 해줍니다. 이 함수는 CPU->하드웨어 사이를 +넘어서 실제 하드웨어에까지 일부 수준의 영향을 끼칩니다. + +더 많은 정보를 위해선 "Acquire vs I/O 액세스" 서브섹션을 참고하세요. + + +========================= +암묵적 커널 메모리 배리어 +========================= + +리눅스 커널의 일부 함수들은 메모리 배리어를 내장하고 있는데, 락(lock)과 +스케쥴링 관련 함수들이 대부분입니다. + +여기선 _최소한의_ 보장을 설명합니다; 특정 아키텍쳐에서는 이 설명보다 더 많은 +보장을 제공할 수도 있습니다만 해당 아키텍쳐에 종속적인 코드 외의 부분에서는 +그런 보장을 기대해선 안될겁니다. + + +락 ACQUISITION 함수 +------------------- + +리눅스 커널은 다양한 락 구성체를 가지고 있습니다: + + (*) 스핀 락 + (*) R/W 스핀 락 + (*) 뮤텍스 + (*) 세마포어 + (*) R/W 세마포어 + +각 구성체마다 모든 경우에 "ACQUIRE" 오퍼레이션과 "RELEASE" 오퍼레이션의 변종이 +존재합니다. 이 오퍼레이션들은 모두 적절한 배리어를 내포하고 있습니다: + + (1) ACQUIRE 오퍼레이션의 영향: + + ACQUIRE 뒤에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 + 뒤에 완료됩니다. + + ACQUIRE 앞에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 후에 + 완료될 수 있습니다. smp_mb__before_spinlock() 뒤에 ACQUIRE 가 실행되는 + 코드 블록은 블록 앞의 스토어를 블록 뒤의 로드와 스토어에 대해 순서 + 맞춥니다. 이건 smp_mb() 보다 완화된 것임을 기억하세요! 많은 아키텍쳐에서 + smp_mb__before_spinlock() 은 사실 아무일도 하지 않습니다. + + (2) RELEASE 오퍼레이션의 영향: + + RELEASE 앞에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션이 완료되기 + 전에 완료됩니다. + + RELEASE 뒤에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션 완료 전에 + 완료될 수 있습니다. + + (3) ACQUIRE vs ACQUIRE 영향: + + 어떤 ACQUIRE 오퍼레이션보다 앞에서 요청된 모든 ACQUIRE 오퍼레이션은 그 + ACQUIRE 오퍼레이션 전에 완료됩니다. + + (4) ACQUIRE vs RELEASE implication: + + 어떤 RELEASE 오퍼레이션보다 앞서 요청된 ACQUIRE 오퍼레이션은 그 RELEASE + 오퍼레이션보다 먼저 완료됩니다. + + (5) 실패한 조건적 ACQUIRE 영향: + + ACQUIRE 오퍼레이션의 일부 락(lock) 변종은 락이 곧바로 획득하기에는 + 불가능한 상태이거나 락이 획득 가능해지도록 기다리는 도중 시그널을 받거나 + 해서 실패할 수 있습니다. 실패한 락은 어떤 배리어도 내포하지 않습니다. + +[!] 참고: 락 ACQUIRE 와 RELEASE 가 단방향 배리어여서 나타나는 현상 중 하나는 +크리티컬 섹션 바깥의 인스트럭션의 영향이 크리티컬 섹션 내부로도 들어올 수 +있다는 것입니다. + +RELEASE 후에 요청되는 ACQUIRE 는 전체 메모리 배리어라 여겨지면 안되는데, +ACQUIRE 앞의 액세스가 ACQUIRE 후에 수행될 수 있고, RELEASE 후의 액세스가 +RELEASE 전에 수행될 수도 있으며, 그 두개의 액세스가 서로를 지나칠 수도 있기 +때문입니다: + + *A = a; + ACQUIRE M + RELEASE M + *B = b; + +는 다음과 같이 될 수도 있습니다: + + ACQUIRE M, STORE *B, STORE *A, RELEASE M + +ACQUIRE 와 RELEASE 가 락 획득과 해제라면, 그리고 락의 ACQUIRE 와 RELEASE 가 +같은 락 변수에 대한 것이라면, 해당 락을 쥐고 있지 않은 다른 CPU 의 시야에는 +이와 같은 재배치가 일어나는 것으로 보일 수 있습니다. 요약하자면, ACQUIRE 에 +이어 RELEASE 오퍼레이션을 순차적으로 실행하는 행위가 전체 메모리 배리어로 +생각되어선 -안됩니다-. + +비슷하게, 앞의 반대 케이스인 RELEASE 와 ACQUIRE 두개 오퍼레이션의 순차적 실행 +역시 전체 메모리 배리어를 내포하지 않습니다. 따라서, RELEASE, ACQUIRE 로 +규정되는 크리티컬 섹션의 CPU 수행은 RELEASE 와 ACQUIRE 를 가로지를 수 있으므로, +다음과 같은 코드는: + + *A = a; + RELEASE M + ACQUIRE N + *B = b; + +다음과 같이 수행될 수 있습니다: + + ACQUIRE N, STORE *B, STORE *A, RELEASE M + +이런 재배치는 데드락을 일으킬 수도 있을 것처럼 보일 수 있습니다. 하지만, 그런 +데드락의 조짐이 있다면 RELEASE 는 단순히 완료될 것이므로 데드락은 존재할 수 +없습니다. + + 이게 어떻게 올바른 동작을 할 수 있을까요? + + 우리가 이야기 하고 있는건 재배치를 하는 CPU 에 대한 이야기이지, + 컴파일러에 대한 것이 아니란 점이 핵심입니다. 컴파일러 (또는, 개발자) + 가 오퍼레이션들을 이렇게 재배치하면, 데드락이 일어날 수 -있습-니다. + + 하지만 CPU 가 오퍼레이션들을 재배치 했다는걸 생각해 보세요. 이 예에서, + 어셈블리 코드 상으로는 언락이 락을 앞서게 되어 있습니다. CPU 가 이를 + 재배치해서 뒤의 락 오퍼레이션을 먼저 실행하게 됩니다. 만약 데드락이 + 존재한다면, 이 락 오퍼레이션은 그저 스핀을 하며 계속해서 락을 + 시도합니다 (또는, 한참 후에겠지만, 잠듭니다). CPU 는 언젠가는 + (어셈블리 코드에서는 락을 앞서는) 언락 오퍼레이션을 실행하는데, 이 언락 + 오퍼레이션이 잠재적 데드락을 해결하고, 락 오퍼레이션도 뒤이어 성공하게 + 됩니다. + + 하지만 만약 락이 잠을 자는 타입이었다면요? 그런 경우에 코드는 + 스케쥴러로 들어가려 할 거고, 여기서 결국은 메모리 배리어를 만나게 + 되는데, 이 메모리 배리어는 앞의 언락 오퍼레이션이 완료되도록 만들고, + 데드락은 이번에도 해결됩니다. 잠을 자는 행위와 언락 사이의 경주 상황 + (race) 도 있을 수 있겠습니다만, 락 관련 기능들은 그런 경주 상황을 모든 + 경우에 제대로 해결할 수 있어야 합니다. + +락과 세마포어는 UP 컴파일된 시스템에서의 순서에 대해 보장을 하지 않기 때문에, +그런 상황에서 인터럽트 비활성화 오퍼레이션과 함께가 아니라면 어떤 일에도 - 특히 +I/O 액세스와 관련해서는 - 제대로 사용될 수 없을 겁니다. + +"CPU 간 ACQUIRING 배리어 효과" 섹션도 참고하시기 바랍니다. + + +예를 들어, 다음과 같은 코드를 생각해 봅시다: + + *A = a; + *B = b; + ACQUIRE + *C = c; + *D = d; + RELEASE + *E = e; + *F = f; + +여기선 다음의 이벤트 시퀀스가 생길 수 있습니다: + + ACQUIRE, {*F,*A}, *E, {*C,*D}, *B, RELEASE + + [+] {*F,*A} 는 조합된 액세스를 의미합니다. + +하지만 다음과 같은 건 불가능하죠: + + {*F,*A}, *B, ACQUIRE, *C, *D, RELEASE, *E + *A, *B, *C, ACQUIRE, *D, RELEASE, *E, *F + *A, *B, ACQUIRE, *C, RELEASE, *D, *E, *F + *B, ACQUIRE, *C, *D, RELEASE, {*F,*A}, *E + + + +인터럽트 비활성화 함수 +---------------------- + +인터럽트를 비활성화 하는 함수 (ACQUIRE 와 동일) 와 인터럽트를 활성화 하는 함수 +(RELEASE 와 동일) 는 컴파일러 배리어처럼만 동작합니다. 따라서, 별도의 메모리 +배리어나 I/O 배리어가 필요한 상황이라면 그 배리어들은 인터럽트 비활성화 함수 +외의 방법으로 제공되어야만 합니다. + + +슬립과 웨이크업 함수 +-------------------- + +글로벌 데이터에 표시된 이벤트에 의해 프로세스를 잠에 빠트리는 것과 깨우는 것은 +해당 이벤트를 기다리는 태스크의 태스크 상태와 그 이벤트를 알리기 위해 사용되는 +글로벌 데이터, 두 데이터간의 상호작용으로 볼 수 있습니다. 이것이 옳은 순서대로 +일어남을 분명히 하기 위해, 프로세스를 잠에 들게 하는 기능과 깨우는 기능은 +몇가지 배리어를 내포합니다. + +먼저, 잠을 재우는 쪽은 일반적으로 다음과 같은 이벤트 시퀀스를 따릅니다: + + for (;;) { + set_current_state(TASK_UNINTERRUPTIBLE); + if (event_indicated) + break; + schedule(); + } + +set_current_state() 에 의해, 태스크 상태가 바뀐 후 범용 메모리 배리어가 +자동으로 삽입됩니다: + + CPU 1 + =============================== + set_current_state(); + smp_store_mb(); + STORE current->state + <범용 배리어> + LOAD event_indicated + +set_current_state() 는 다음의 것들로 감싸질 수도 있습니다: + + prepare_to_wait(); + prepare_to_wait_exclusive(); + +이것들 역시 상태를 설정한 후 범용 메모리 배리어를 삽입합니다. +앞의 전체 시퀀스는 다음과 같은 함수들로 한번에 수행 가능한데, 이것들은 모두 +올바른 장소에 메모리 배리어를 삽입합니다: + + wait_event(); + wait_event_interruptible(); + wait_event_interruptible_exclusive(); + wait_event_interruptible_timeout(); + wait_event_killable(); + wait_event_timeout(); + wait_on_bit(); + wait_on_bit_lock(); + + +두번째로, 깨우기를 수행하는 코드는 일반적으로 다음과 같을 겁니다: + + event_indicated = 1; + wake_up(&event_wait_queue); + +또는: + + event_indicated = 1; + wake_up_process(event_daemon); + +wake_up() 류에 의해 쓰기 메모리 배리어가 내포됩니다. 만약 그것들이 뭔가를 +깨운다면요. 이 배리어는 태스크 상태가 지워지기 전에 수행되므로, 이벤트를 +알리기 위한 STORE 와 태스크 상태를 TASK_RUNNING 으로 설정하는 STORE 사이에 +위치하게 됩니다. + + CPU 1 CPU 2 + =============================== =============================== + set_current_state(); STORE event_indicated + smp_store_mb(); wake_up(); + STORE current->state <쓰기 배리어> + <범용 배리어> STORE current->state + LOAD event_indicated + +한번더 말합니다만, 이 쓰기 메모리 배리어는 이 코드가 정말로 뭔가를 깨울 때에만 +실행됩니다. 이걸 설명하기 위해, X 와 Y 는 모두 0 으로 초기화 되어 있다는 가정 +하에 아래의 이벤트 시퀀스를 생각해 봅시다: + + CPU 1 CPU 2 + =============================== =============================== + X = 1; STORE event_indicated + smp_mb(); wake_up(); + Y = 1; wait_event(wq, Y == 1); + wake_up(); load from Y sees 1, no memory barrier + load from X might see 0 + +위 예제에서의 경우와 달리 깨우기가 정말로 행해졌다면, CPU 2 의 X 로드는 1 을 +본다고 보장될 수 있을 겁니다. + +사용 가능한 깨우기류 함수들로 다음과 같은 것들이 있습니다: + + complete(); + wake_up(); + wake_up_all(); + wake_up_bit(); + wake_up_interruptible(); + wake_up_interruptible_all(); + wake_up_interruptible_nr(); + wake_up_interruptible_poll(); + wake_up_interruptible_sync(); + wake_up_interruptible_sync_poll(); + wake_up_locked(); + wake_up_locked_poll(); + wake_up_nr(); + wake_up_poll(); + wake_up_process(); + + +[!] 잠재우는 코드와 깨우는 코드에 내포되는 메모리 배리어들은 깨우기 전에 +이루어진 스토어를 잠재우는 코드가 set_current_state() 를 호출한 후에 행하는 +로드에 대해 순서를 맞추지 _않는다는_ 점을 기억하세요. 예를 들어, 잠재우는 +코드가 다음과 같고: + + set_current_state(TASK_INTERRUPTIBLE); + if (event_indicated) + break; + __set_current_state(TASK_RUNNING); + do_something(my_data); + +깨우는 코드는 다음과 같다면: + + my_data = value; + event_indicated = 1; + wake_up(&event_wait_queue); + +event_indecated 에의 변경이 잠재우는 코드에게 my_data 에의 변경 후에 이루어진 +것으로 인지될 것이라는 보장이 없습니다. 이런 경우에는 양쪽 코드 모두 각각의 +데이터 액세스 사이에 메모리 배리어를 직접 쳐야 합니다. 따라서 앞의 재우는 +코드는 다음과 같이: + + set_current_state(TASK_INTERRUPTIBLE); + if (event_indicated) { + smp_rmb(); + do_something(my_data); + } + +그리고 깨우는 코드는 다음과 같이 되어야 합니다: + + my_data = value; + smp_wmb(); + event_indicated = 1; + wake_up(&event_wait_queue); + + +그외의 함수들 +------------- + +그외의 배리어를 내포하는 함수들은 다음과 같습니다: + + (*) schedule() 과 그 유사한 것들이 완전한 메모리 배리어를 내포합니다. + + +============================== +CPU 간 ACQUIRING 배리어의 효과 +============================== + +SMP 시스템에서의 락 기능들은 더욱 강력한 형태의 배리어를 제공합니다: 이 +배리어는 동일한 락을 사용하는 다른 CPU 들의 메모리 액세스 순서에도 영향을 +끼칩니다. + + +ACQUIRE VS 메모리 액세스 +------------------------ + +다음의 예를 생각해 봅시다: 시스템은 두개의 스핀락 (M) 과 (Q), 그리고 세개의 CPU +를 가지고 있습니다; 여기에 다음의 이벤트 시퀀스가 발생합니다: + + CPU 1 CPU 2 + =============================== =============================== + WRITE_ONCE(*A, a); WRITE_ONCE(*E, e); + ACQUIRE M ACQUIRE Q + WRITE_ONCE(*B, b); WRITE_ONCE(*F, f); + WRITE_ONCE(*C, c); WRITE_ONCE(*G, g); + RELEASE M RELEASE Q + WRITE_ONCE(*D, d); WRITE_ONCE(*H, h); + +*A 로의 액세스부터 *H 로의 액세스까지가 어떤 순서로 CPU 3 에게 보여질지에 +대해서는 각 CPU 에서의 락 사용에 의해 내포되어 있는 제약을 제외하고는 어떤 +보장도 존재하지 않습니다. 예를 들어, CPU 3 에게 다음과 같은 순서로 보여지는 +것이 가능합니다: + + *E, ACQUIRE M, ACQUIRE Q, *G, *C, *F, *A, *B, RELEASE Q, *D, *H, RELEASE M + +하지만 다음과 같이 보이지는 않을 겁니다: + + *B, *C or *D preceding ACQUIRE M + *A, *B or *C following RELEASE M + *F, *G or *H preceding ACQUIRE Q + *E, *F or *G following RELEASE Q + + + +ACQUIRE VS I/O 액세스 +---------------------- + +특정한 (특히 NUMA 가 관련된) 환경 하에서 두개의 CPU 에서 동일한 스핀락으로 +보호되는 두개의 크리티컬 섹션 안의 I/O 액세스는 PCI 브릿지에 겹쳐진 I/O +액세스로 보일 수 있는데, PCI 브릿지는 캐시 일관성 프로토콜과 합을 맞춰야 할 +의무가 없으므로, 필요한 읽기 메모리 배리어가 요청되지 않기 때문입니다. + +예를 들어서: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + writel(1, DATA); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + writel(5, DATA); + spin_unlock(Q); + +는 PCI 브릿지에 다음과 같이 보일 수 있습니다: + + STORE *ADDR = 0, STORE *ADDR = 4, STORE *DATA = 1, STORE *DATA = 5 + +이렇게 되면 하드웨어의 오동작을 일으킬 수 있습니다. + + +이런 경우엔 잡아둔 스핀락을 내려놓기 전에 mmiowb() 를 수행해야 하는데, 예를 +들면 다음과 같습니다: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + writel(1, DATA); + mmiowb(); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + writel(5, DATA); + mmiowb(); + spin_unlock(Q); + +이 코드는 CPU 1 에서 요청된 두개의 스토어가 PCI 브릿지에 CPU 2 에서 요청된 +스토어들보다 먼저 보여짐을 보장합니다. + + +또한, 같은 디바이스에서 스토어를 이어 로드가 수행되면 이 로드는 로드가 수행되기 +전에 스토어가 완료되기를 강제하므로 mmiowb() 의 필요가 없어집니다: + + CPU 1 CPU 2 + =============================== =============================== + spin_lock(Q) + writel(0, ADDR) + a = readl(DATA); + spin_unlock(Q); + spin_lock(Q); + writel(4, ADDR); + b = readl(DATA); + spin_unlock(Q); + + +더 많은 정보를 위해선 Documenataion/DocBook/deviceiobook.tmpl 을 참고하세요. + + +========================= +메모리 배리어가 필요한 곳 +========================= + +설령 SMP 커널을 사용하더라도 싱글 쓰레드로 동작하는 코드는 올바르게 동작하는 +것으로 보여질 것이기 때문에, 평범한 시스템 운영중에 메모리 오퍼레이션 재배치는 +일반적으로 문제가 되지 않습니다. 하지만, 재배치가 문제가 _될 수 있는_ 네가지 +환경이 있습니다: + + (*) 프로세서간 상호 작용. + + (*) 어토믹 오퍼레이션. + + (*) 디바이스 액세스. + + (*) 인터럽트. + + +프로세서간 상호 작용 +-------------------- + +두개 이상의 프로세서를 가진 시스템이 있다면, 시스템의 두개 이상의 CPU 는 동시에 +같은 데이터에 대한 작업을 할 수 있습니다. 이는 동기화 문제를 일으킬 수 있고, +이 문제를 해결하는 일반적 방법은 락을 사용하는 것입니다. 하지만, 락은 상당히 +비용이 비싸서 가능하면 락을 사용하지 않고 일을 처리하는 것이 낫습니다. 이런 +경우, 두 CPU 모두에 영향을 끼치는 오퍼레이션들은 오동작을 막기 위해 신중하게 +순서가 맞춰져야 합니다. + +예를 들어, R/W 세마포어의 느린 수행경로 (slow path) 를 생각해 봅시다. +세마포어를 위해 대기를 하는 하나의 프로세스가 자신의 스택 중 일부를 이 +세마포어의 대기 프로세스 리스트에 링크한 채로 있습니다: + + struct rw_semaphore { + ... + spinlock_t lock; + struct list_head waiters; + }; + + struct rwsem_waiter { + struct list_head list; + struct task_struct *task; + }; + +특정 대기 상태 프로세스를 깨우기 위해, up_read() 나 up_write() 함수는 다음과 +같은 일을 합니다: + + (1) 다음 대기 상태 프로세스 레코드는 어디있는지 알기 위해 이 대기 상태 + 프로세스 레코드의 next 포인터를 읽습니다; + + (2) 이 대기 상태 프로세스의 task 구조체로의 포인터를 읽습니다; + + (3) 이 대기 상태 프로세스가 세마포어를 획득했음을 알리기 위해 task + 포인터를 초기화 합니다; + + (4) 해당 태스크에 대해 wake_up_process() 를 호출합니다; 그리고 + + (5) 해당 대기 상태 프로세스의 task 구조체를 잡고 있던 레퍼런스를 해제합니다. + +달리 말하자면, 다음 이벤트 시퀀스를 수행해야 합니다: + + LOAD waiter->list.next; + LOAD waiter->task; + STORE waiter->task; + CALL wakeup + RELEASE task + +그리고 이 이벤트들이 다른 순서로 수행된다면, 오동작이 일어날 수 있습니다. + +한번 세마포어의 대기줄에 들어갔고 세마포어 락을 놓았다면, 해당 대기 프로세스는 +락을 다시는 잡지 않습니다; 대신 자신의 task 포인터가 초기화 되길 기다립니다. +그 레코드는 대기 프로세스의 스택에 있기 때문에, 리스트의 next 포인터가 읽혀지기 +_전에_ task 포인터가 지워진다면, 다른 CPU 는 해당 대기 프로세스를 시작해 버리고 +up*() 함수가 next 포인터를 읽기 전에 대기 프로세스의 스택을 마구 건드릴 수 +있습니다. + +그렇게 되면 위의 이벤트 시퀀스에 어떤 일이 일어나는지 생각해 보죠: + + CPU 1 CPU 2 + =============================== =============================== + down_xxx() + Queue waiter + Sleep + up_yyy() + LOAD waiter->task; + STORE waiter->task; + Woken up by other event + + Resume processing + down_xxx() returns + call foo() + foo() clobbers *waiter + + LOAD waiter->list.next; + --- OOPS --- + +이 문제는 세마포어 락의 사용으로 해결될 수도 있겠지만, 그렇게 되면 깨어난 후에 +down_xxx() 함수가 불필요하게 스핀락을 또다시 얻어야만 합니다. + +이 문제를 해결하는 방법은 범용 SMP 메모리 배리어를 추가하는 겁니다: + + LOAD waiter->list.next; + LOAD waiter->task; + smp_mb(); + STORE waiter->task; + CALL wakeup + RELEASE task + +이 경우에, 배리어는 시스템의 나머지 CPU 들에게 모든 배리어 앞의 메모리 액세스가 +배리어 뒤의 메모리 액세스보다 앞서 일어난 것으로 보이게 만듭니다. 배리어 앞의 +메모리 액세스들이 배리어 명령 자체가 완료되는 시점까지 완료된다고는 보장하지 +_않습니다_. + +(이게 문제가 되지 않을) 단일 프로세서 시스템에서 smp_mb() 는 실제로는 그저 +컴파일러가 CPU 안에서의 순서를 바꾸거나 하지 않고 주어진 순서대로 명령을 +내리도록 하는 컴파일러 배리어일 뿐입니다. 오직 하나의 CPU 만 있으니, CPU 의 +의존성 순서 로직이 그 외의 모든것을 알아서 처리할 겁니다. + + +어토믹 오퍼레이션 +----------------- + +어토믹 오퍼레이션은 기술적으로 프로세서간 상호작용으로 분류되며 그 중 일부는 +전체 메모리 배리어를 내포하고 또 일부는 내포하지 않지만, 커널에서 상당히 +의존적으로 사용하는 기능 중 하나입니다. + +메모리의 어떤 상태를 수정하고 해당 상태에 대한 (예전의 또는 최신의) 정보를 +리턴하는 어토믹 오퍼레이션은 모두 SMP-조건적 범용 메모리 배리어(smp_mb())를 +실제 오퍼레이션의 앞과 뒤에 내포합니다. 이런 오퍼레이션은 다음의 것들을 +포함합니다: + + xchg(); + atomic_xchg(); atomic_long_xchg(); + atomic_inc_return(); atomic_long_inc_return(); + atomic_dec_return(); atomic_long_dec_return(); + atomic_add_return(); atomic_long_add_return(); + atomic_sub_return(); atomic_long_sub_return(); + atomic_inc_and_test(); atomic_long_inc_and_test(); + atomic_dec_and_test(); atomic_long_dec_and_test(); + atomic_sub_and_test(); atomic_long_sub_and_test(); + atomic_add_negative(); atomic_long_add_negative(); + test_and_set_bit(); + test_and_clear_bit(); + test_and_change_bit(); + + /* exchange 조건이 성공할 때 */ + cmpxchg(); + atomic_cmpxchg(); atomic_long_cmpxchg(); + atomic_add_unless(); atomic_long_add_unless(); + +이것들은 메모리 배리어 효과가 필요한 ACQUIRE 부류와 RELEASE 부류 오퍼레이션들을 +구현할 때, 그리고 객체 해제를 위해 레퍼런스 카운터를 조정할 때, 암묵적 메모리 +배리어 효과가 필요한 곳 등에 사용됩니다. + + +다음의 오퍼레이션들은 메모리 배리어를 내포하지 _않기_ 때문에 문제가 될 수 +있지만, RELEASE 부류의 오퍼레이션들과 같은 것들을 구현할 때 사용될 수도 +있습니다: + + atomic_set(); + set_bit(); + clear_bit(); + change_bit(); + +이것들을 사용할 때에는 필요하다면 적절한 (예를 들면 smp_mb__before_atomic() +같은) 메모리 배리어가 명시적으로 함께 사용되어야 합니다. + + +아래의 것들도 메모리 배리어를 내포하지 _않기_ 때문에, 일부 환경에서는 (예를 +들면 smp_mb__before_atomic() 과 같은) 명시적인 메모리 배리어 사용이 필요합니다. + + atomic_add(); + atomic_sub(); + atomic_inc(); + atomic_dec(); + +이것들이 통계 생성을 위해 사용된다면, 그리고 통계 데이터 사이에 관계가 존재하지 +않는다면 메모리 배리어는 필요치 않을 겁니다. + +객체의 수명을 관리하기 위해 레퍼런스 카운팅 목적으로 사용된다면, 레퍼런스 +카운터는 락으로 보호되는 섹션에서만 조정되거나 호출하는 쪽이 이미 충분한 +레퍼런스를 잡고 있을 것이기 때문에 메모리 배리어는 아마 필요 없을 겁니다. + +만약 어떤 락을 구성하기 위해 사용된다면, 락 관련 동작은 일반적으로 작업을 특정 +순서대로 진행해야 하므로 메모리 배리어가 필요할 수 있습니다. + +기본적으로, 각 사용처에서는 메모리 배리어가 필요한지 아닌지 충분히 고려해야 +합니다. + +아래의 오퍼레이션들은 특별한 락 관련 동작들입니다: + + test_and_set_bit_lock(); + clear_bit_unlock(); + __clear_bit_unlock(); + +이것들은 ACQUIRE 류와 RELEASE 류의 오퍼레이션들을 구현합니다. 락 관련 도구를 +구현할 때에는 이것들을 좀 더 선호하는 편이 나은데, 이것들의 구현은 많은 +아키텍쳐에서 최적화 될 수 있기 때문입니다. + +[!] 이런 상황에 사용할 수 있는 특수한 메모리 배리어 도구들이 있습니다만, 일부 +CPU 에서는 사용되는 어토믹 인스트럭션 자체에 메모리 배리어가 내포되어 있어서 +어토믹 오퍼레이션과 메모리 배리어를 함께 사용하는 게 불필요한 일이 될 수 +있는데, 그런 경우에 이 특수 메모리 배리어 도구들은 no-op 이 되어 실질적으로 +아무일도 하지 않습니다. + +더 많은 내용을 위해선 Documentation/atomic_ops.txt 를 참고하세요. + + +디바이스 액세스 +--------------- + +많은 디바이스가 메모리 매핑 기법으로 제어될 수 있는데, 그렇게 제어되는 +디바이스는 CPU 에는 단지 특정 메모리 영역의 집합처럼 보이게 됩니다. 드라이버는 +그런 디바이스를 제어하기 위해 정확히 올바른 순서로 올바른 메모리 액세스를 +만들어야 합니다. + +하지만, 액세스들을 재배치 하거나 조합하거나 병합하는게 더 효율적이라 판단하는 +영리한 CPU 나 컴파일러들을 사용하면 드라이버 코드의 조심스럽게 순서 맞춰진 +액세스들이 디바이스에는 요청된 순서대로 도착하지 못하게 할 수 있는 - 디바이스가 +오동작을 하게 할 - 잠재적 문제가 생길 수 있습니다. + +리눅스 커널 내부에서, I/O 는 어떻게 액세스들을 적절히 순차적이게 만들 수 있는지 +알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만 +합니다. 이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가 +없습니다만, 다음의 두가지 상황에서는 명시적 메모리 배리어가 필요할 수 있습니다: + + (1) 일부 시스템에서 I/O 스토어는 모든 CPU 에 일관되게 순서 맞춰지지 않는데, + 따라서 _모든_ 일반적인 드라이버들에 락이 사용되어야만 하고 이 크리티컬 + 섹션을 빠져나오기 전에 mmiowb() 가 꼭 호출되어야 합니다. + + (2) 만약 액세스 함수들이 완화된 메모리 액세스 속성을 갖는 I/O 메모리 윈도우를 + 사용한다면, 순서를 강제하기 위해선 _mandatory_ 메모리 배리어가 필요합니다. + +더 많은 정보를 위해선 Documentation/DocBook/deviceiobook.tmpl 을 참고하십시오. + + +인터럽트 +-------- + +드라이버는 자신의 인터럽트 서비스 루틴에 의해 인터럽트 당할 수 있기 때문에 +드라이버의 이 두 부분은 서로의 디바이스 제어 또는 액세스 부분과 상호 간섭할 수 +있습니다. + +스스로에게 인터럽트 당하는 걸 불가능하게 하고, 드라이버의 크리티컬한 +오퍼레이션들을 모두 인터럽트가 불가능하게 된 영역에 집어넣거나 하는 방법 (락의 +한 형태) 으로 이런 상호 간섭을 - 최소한 부분적으로라도 - 줄일 수 있습니다. +드라이버의 인터럽트 루틴이 실행 중인 동안, 해당 드라이버의 코어는 같은 CPU 에서 +수행되지 않을 것이며, 현재의 인터럽트가 처리되는 중에는 또다시 인터럽트가 +일어나지 못하도록 되어 있으니 인터럽트 핸들러는 그에 대해서는 락을 잡지 않아도 +됩니다. + +하지만, 어드레스 레지스터와 데이터 레지스터를 갖는 이더넷 카드를 다루는 +드라이버를 생각해 봅시다. 만약 이 드라이버의 코어가 인터럽트를 비활성화시킨 +채로 이더넷 카드와 대화하고 드라이버의 인터럽트 핸들러가 호출되었다면: + + LOCAL IRQ DISABLE + writew(ADDR, 3); + writew(DATA, y); + LOCAL IRQ ENABLE + + writew(ADDR, 4); + q = readw(DATA); + + +만약 순서 규칙이 충분히 완화되어 있다면 데이터 레지스터에의 스토어는 어드레스 +레지스터에 두번째로 행해지는 스토어 뒤에 일어날 수도 있습니다: + + STORE *ADDR = 3, STORE *ADDR = 4, STORE *DATA = y, q = LOAD *DATA + + +만약 순서 규칙이 충분히 완화되어 있고 묵시적으로든 명시적으로든 배리어가 +사용되지 않았다면 인터럽트 비활성화 섹션에서 일어난 액세스가 바깥으로 새어서 +인터럽트 내에서 일어난 액세스와 섞일 수 있다고 - 그리고 그 반대도 - 가정해야만 +합니다. + +그런 영역 안에서 일어나는 I/O 액세스들은 엄격한 순서 규칙의 I/O 레지스터에 +묵시적 I/O 배리어를 형성하는 동기적 (synchronous) 로드 오퍼레이션을 포함하기 +때문에 일반적으로는 이런게 문제가 되지 않습니다. 만약 이걸로는 충분치 않다면 +mmiowb() 가 명시적으로 사용될 필요가 있습니다. + + +하나의 인터럽트 루틴과 별도의 CPU 에서 수행중이며 서로 통신을 하는 두 루틴 +사이에도 비슷한 상황이 일어날 수 있습니다. 만약 그런 경우가 발생할 가능성이 +있다면, 순서를 보장하기 위해 인터럽트 비활성화 락이 사용되어져야만 합니다. + + +====================== +커널 I/O 배리어의 효과 +====================== + +I/O 메모리에 액세스할 때, 드라이버는 적절한 액세스 함수를 사용해야 합니다: + + (*) inX(), outX(): + + 이것들은 메모리 공간보다는 I/O 공간에 이야기를 하려는 의도로 + 만들어졌습니다만, 그건 기본적으로 CPU 마다 다른 컨셉입니다. i386 과 + x86_64 프로세서들은 특별한 I/O 공간 액세스 사이클과 명령어를 실제로 가지고 + 있지만, 다른 많은 CPU 들에는 그런 컨셉이 존재하지 않습니다. + + 다른 것들 중에서도 PCI 버스가 I/O 공간 컨셉을 정의하는데, 이는 - i386 과 + x86_64 같은 CPU 에서 - CPU 의 I/O 공간 컨셉으로 쉽게 매치됩니다. 하지만, + 대체할 I/O 공간이 없는 CPU 에서는 CPU 의 메모리 맵의 가상 I/O 공간으로 + 매핑될 수도 있습니다. + + 이 공간으로의 액세스는 (i386 등에서는) 완전하게 동기화 됩니다만, 중간의 + (PCI 호스트 브리지와 같은) 브리지들은 이를 완전히 보장하진 않을수도 + 있습니다. + + 이것들의 상호간의 순서는 완전하게 보장됩니다. + + 다른 타입의 메모리 오퍼레이션, I/O 오퍼레이션에 대한 순서는 완전하게 + 보장되지는 않습니다. + + (*) readX(), writeX(): + + 이것들이 수행 요청되는 CPU 에서 서로에게 완전히 순서가 맞춰지고 독립적으로 + 수행되는지에 대한 보장 여부는 이들이 액세스 하는 메모리 윈도우에 정의된 + 특성에 의해 결정됩니다. 예를 들어, 최신의 i386 아키텍쳐 머신에서는 MTRR + 레지스터로 이 특성이 조정됩니다. + + 일반적으로는, 프리페치 (prefetch) 가능한 디바이스를 액세스 하는게 + 아니라면, 이것들은 완전히 순서가 맞춰지고 결합되지 않게 보장될 겁니다. + + 하지만, (PCI 브리지와 같은) 중간의 하드웨어는 자신이 원한다면 집행을 + 연기시킬 수 있습니다; 스토어 명령을 실제로 하드웨어로 내려보내기(flush) + 위해서는 같은 위치로부터 로드를 하는 방법이 있습니다만[*], PCI 의 경우는 + 같은 디바이스나 환경 구성 영역에서의 로드만으로도 충분할 겁니다. + + [*] 주의! 쓰여진 것과 같은 위치로부터의 로드를 시도하는 것은 오동작을 + 일으킬 수도 있습니다 - 예로 16650 Rx/Tx 시리얼 레지스터를 생각해 + 보세요. + + 프리페치 가능한 I/O 메모리가 사용되면, 스토어 명령들이 순서를 지키도록 + 하기 위해 mmiowb() 배리어가 필요할 수 있습니다. + + PCI 트랜잭션 사이의 상호작용에 대해 더 많은 정보를 위해선 PCI 명세서를 + 참고하시기 바랍니다. + + (*) readX_relaxed(), writeX_relaxed() + + 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 + 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스 (예: DMA 버퍼) 에도 + LOCK 이나 UNLOCK 오퍼레이션들에도 순서를 보장하지 않습니다. LOCK 이나 + UNLOCK 오퍼레이션들에 맞춰지는 순서가 필요하다면, mmiowb() 배리어가 사용될 + 수 있습니다. 같은 주변 장치에의 완화된 액세스끼리는 순서가 지켜짐을 알아 + 두시기 바랍니다. + + (*) ioreadX(), iowriteX() + + 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 + 종류에 따라 적절하게 수행될 것입니다. + + +=================================== +가정되는 가장 완화된 실행 순서 모델 +=================================== + +컨셉적으로 CPU 는 주어진 프로그램에 대해 프로그램 그 자체에는 인과성 (program +causality) 을 지키는 것처럼 보이게 하지만 일반적으로는 순서를 거의 지켜주지 +않는다고 가정되어야만 합니다. (i386 이나 x86_64 같은) 일부 CPU 들은 코드 +재배치에 (powerpc 나 frv 와 같은) 다른 것들에 비해 강한 제약을 갖지만, 아키텍쳐 +종속적 코드 이외의 코드에서는 순서에 대한 제약이 가장 완화된 경우 (DEC Alpha) +를 가정해야 합니다. + +이 말은, CPU 에게 주어지는 인스트럭션 스트림 내의 한 인스트럭션이 앞의 +인스트럭션에 종속적이라면 앞의 인스트럭션은 뒤의 종속적 인스트럭션이 실행되기 +전에 완료[*]될 수 있어야 한다는 제약 (달리 말해서, 인과성이 지켜지는 것으로 +보이게 함) 외에는 자신이 원하는 순서대로 - 심지어 병렬적으로도 - 그 스트림을 +실행할 수 있음을 의미합니다 + + [*] 일부 인스트럭션은 하나 이상의 영향 - 조건 코드를 바꾼다던지, 레지스터나 + 메모리를 바꾼다던지 - 을 만들어내며, 다른 인스트럭션은 다른 효과에 + 종속적일 수 있습니다. + +CPU 는 최종적으로 아무 효과도 만들지 않는 인스트럭션 시퀀스는 없애버릴 수도 +있습니다. 예를 들어, 만약 두개의 연속되는 인스트럭션이 둘 다 같은 레지스터에 +직접적인 값 (immediate value) 을 집어넣는다면, 첫번째 인스트럭션은 버려질 수도 +있습니다. + + +비슷하게, 컴파일러 역시 프로그램의 인과성만 지켜준다면 인스트럭션 스트림을 +자신이 보기에 올바르다 생각되는대로 재배치 할 수 있습니다. + + +=============== +CPU 캐시의 영향 +=============== + +캐시된 메모리 오퍼레이션들이 시스템 전체에 어떻게 인지되는지는 CPU 와 메모리 +사이에 존재하는 캐시들, 그리고 시스템 상태의 일관성을 관리하는 메모리 일관성 +시스템에 상당 부분 영향을 받습니다. + +한 CPU 가 시스템의 다른 부분들과 캐시를 통해 상호작용한다면, 메모리 시스템은 +CPU 의 캐시들을 포함해야 하며, CPU 와 CPU 자신의 캐시 사이에서의 동작을 위한 +메모리 배리어를 가져야 합니다. (메모리 배리어는 논리적으로는 다음 그림의 +점선에서 동작합니다): + + <--- CPU ---> : <----------- Memory -----------> + : + +--------+ +--------+ : +--------+ +-----------+ + | | | | : | | | | +--------+ + | CPU | | Memory | : | CPU | | | | | + | Core |--->| Access |----->| Cache |<-->| | | | + | | | Queue | : | | | |--->| Memory | + | | | | : | | | | | | + +--------+ +--------+ : +--------+ | | | | + : | Cache | +--------+ + : | Coherency | + : | Mechanism | +--------+ + +--------+ +--------+ : +--------+ | | | | + | | | | : | | | | | | + | CPU | | Memory | : | CPU | | |--->| Device | + | Core |--->| Access |----->| Cache |<-->| | | | + | | | Queue | : | | | | | | + | | | | : | | | | +--------+ + +--------+ +--------+ : +--------+ +-----------+ + : + : + +특정 로드나 스토어는 해당 오퍼레이션을 요청한 CPU 의 캐시 내에서 동작을 완료할 +수도 있기 때문에 해당 CPU 의 바깥에는 보이지 않을 수 있지만, 다른 CPU 가 관심을 +갖는다면 캐시 일관성 메커니즘이 해당 캐시라인을 해당 CPU 에게 전달하고, 해당 +메모리 영역에 대한 오퍼레이션이 발생할 때마다 그 영향을 전파시키기 때문에, 해당 +오퍼레이션은 메모리에 실제로 액세스를 한것처럼 나타날 것입니다. + +CPU 코어는 프로그램의 인과성이 유지된다고만 여겨진다면 인스트럭션들을 어떤 +순서로든 재배치해서 수행할 수 있습니다. 일부 인스트럭션들은 로드나 스토어 +오퍼레이션을 만드는데 이 오퍼레이션들은 이후 수행될 메모리 액세스 큐에 들어가게 +됩니다. 코어는 이 오퍼레이션들을 해당 큐에 어떤 순서로든 원하는대로 넣을 수 +있고, 다른 인스트럭션의 완료를 기다리도록 강제되기 전까지는 수행을 계속합니다. + +메모리 배리어가 하는 일은 CPU 쪽에서 메모리 쪽으로 넘어가는 액세스들의 순서, +그리고 그 액세스의 결과가 시스템의 다른 관찰자들에게 인지되는 순서를 제어하는 +것입니다. + +[!] CPU 들은 항상 그들 자신의 로드와 스토어는 프로그램 순서대로 일어난 것으로 +보기 때문에, 주어진 CPU 내에서는 메모리 배리어를 사용할 필요가 _없습니다_. + +[!] MMIO 나 다른 디바이스 액세스들은 캐시 시스템을 우회할 수도 있습니다. 우회 +여부는 디바이스가 액세스 되는 메모리 윈도우의 특성에 의해 결정될 수도 있고, CPU +가 가지고 있을 수 있는 특수한 디바이스 통신 인스트럭션의 사용에 의해서 결정될 +수도 있습니다. + + +캐시 일관성 +----------- + +하지만 삶은 앞에서 이야기한 것처럼 단순하지 않습니다: 캐시들은 일관적일 것으로 +기대되지만, 그 일관성이 순서에도 적용될 거라는 보장은 없습니다. 한 CPU 에서 +만들어진 변경 사항은 최종적으로는 시스템의 모든 CPU 에게 보여지게 되지만, 다른 +CPU 들에게도 같은 순서로 보이게 될 거라는 보장은 없다는 뜻입니다. + + +두개의 CPU (1 & 2) 가 달려 있고, 각 CPU 에 두개의 데이터 캐시(CPU 1 은 A/B 를, +CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다룬다고 생각해 +봅시다: + + : + : +--------+ + : +---------+ | | + +--------+ : +--->| Cache A |<------->| | + | | : | +---------+ | | + | CPU 1 |<---+ | | + | | : | +---------+ | | + +--------+ : +--->| Cache B |<------->| | + : +---------+ | | + : | Memory | + : +---------+ | System | + +--------+ : +--->| Cache C |<------->| | + | | : | +---------+ | | + | CPU 2 |<---+ | | + | | : | +---------+ | | + +--------+ : +--->| Cache D |<------->| | + : +---------+ | | + : +--------+ + : + +이 시스템이 다음과 같은 특성을 갖는다 생각해 봅시다: + + (*) 홀수번 캐시라인은 캐시 A, 캐시 C 또는 메모리에 위치할 수 있음; + + (*) 짝수번 캐시라인은 캐시 B, 캐시 D 또는 메모리에 위치할 수 있음; + + (*) CPU 코어가 한개의 캐시에 접근하는 동안, 다른 캐시는 - 더티 캐시라인을 + 메모리에 내리거나 추측성 로드를 하거나 하기 위해 - 시스템의 다른 부분에 + 액세스 하기 위해 버스를 사용할 수 있음; + + (*) 각 캐시는 시스템의 나머지 부분들과 일관성을 맞추기 위해 해당 캐시에 + 적용되어야 할 오퍼레이션들의 큐를 가짐; + + (*) 이 일관성 큐는 캐시에 이미 존재하는 라인에 가해지는 평범한 로드에 의해서는 + 비워지지 않는데, 큐의 오퍼레이션들이 이 로드의 결과에 영향을 끼칠 수 있다 + 할지라도 그러함. + +이제, 첫번째 CPU 에서 두개의 쓰기 오퍼레이션을 만드는데, 해당 CPU 의 캐시에 +요청된 순서로 오퍼레이션이 도달됨을 보장하기 위해 두 오퍼레이션 사이에 쓰기 +배리어를 사용하는 상황을 상상해 봅시다: + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); v 의 변경이 p 의 변경 전에 보일 것을 + 분명히 함 + v 는 이제 캐시 A 에 독점적으로 존재함 + p = &v; + p 는 이제 캐시 B 에 독점적으로 존재함 + +여기서의 쓰기 메모리 배리어는 CPU 1 의 캐시가 올바른 순서로 업데이트 된 것으로 +시스템의 다른 CPU 들이 인지하게 만듭니다. 하지만, 이제 두번째 CPU 가 그 값들을 +읽으려 하는 상황을 생각해 봅시다: + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + ... + q = p; + x = *q; + +위의 두개의 읽기 오퍼레이션은 예상된 순서로 일어나지 못할 수 있는데, 두번째 CPU +의 한 캐시에 다른 캐시 이벤트가 발생해 v 를 담고 있는 캐시라인의 해당 캐시에의 +업데이트가 지연되는 사이, p 를 담고 있는 캐시라인은 두번째 CPU 의 다른 캐시에 +업데이트 되어버렸을 수 있기 때문입니다. + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); + + + p = &v; q = p; + + + + x = *q; + 캐시에 업데이트 되기 전의 v 를 읽음 + + + +기본적으로, 두개의 캐시라인 모두 CPU 2 에 최종적으로는 업데이트 될 것이지만, +별도의 개입 없이는, 업데이트의 순서가 CPU 1 에서 만들어진 순서와 동일할 +것이라는 보장이 없습니다. + + +여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들 +사이에 넣어야 합니다. 이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성 +큐를 처리하도록 강제하게 됩니다. + + CPU 1 CPU 2 COMMENT + =============== =============== ======================================= + u == 0, v == 1 and p == &u, q == &u + v = 2; + smp_wmb(); + + + p = &v; q = p; + + + + smp_read_barrier_depends() + + + x = *q; + 캐시에 업데이트 된 v 를 읽음 + + +이런 부류의 문제는 DEC Alpha 계열 프로세서들에서 발견될 수 있는데, 이들은 +데이터 버스를 좀 더 잘 사용해 성능을 개선할 수 있는, 분할된 캐시를 가지고 있기 +때문입니다. 대부분의 CPU 는 하나의 읽기 오퍼레이션의 메모리 액세스가 다른 읽기 +오퍼레이션에 의존적이라면 데이터 의존성 배리어를 내포시킵니다만, 모두가 그런건 +아니기 때문에 이점에 의존해선 안됩니다. + +다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리 +액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다. Alpha 는 가장 +약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로 +사용되지 않았을 때에는 그런 조정이 필요하지 않게 했습니다. + + +캐시 일관성 VS DMA +------------------ + +모든 시스템이 DMA 를 하는 디바이스에 대해서까지 캐시 일관성을 유지하지는 +않습니다. 그런 경우, DMA 를 시도하는 디바이스는 RAM 으로부터 잘못된 데이터를 +읽을 수 있는데, 더티 캐시 라인이 CPU 의 캐시에 머무르고 있고, 바뀐 값이 아직 +RAM 에 써지지 않았을 수 있기 때문입니다. 이 문제를 해결하기 위해선, 커널의 +적절한 부분에서 각 CPU 캐시의 문제되는 비트들을 플러시 (flush) 시켜야만 합니다 +(그리고 그것들을 무효화 - invalidation - 시킬 수도 있겠죠). + +또한, 디바이스에 의해 RAM 에 DMA 로 쓰여진 값은 디바이스가 쓰기를 완료한 후에 +CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮어써질 수도 있고, CPU +의 캐시에 존재하는 캐시 라인이 해당 캐시에서 삭제되고 다시 값을 읽어들이기 +전까지는 RAM 이 업데이트 되었다는 사실 자체가 숨겨져 버릴 수도 있습니다. 이 +문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는 +비트들을 무효화 시켜야 합니다. + +캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를 +참고하세요. + + +캐시 일관성 VS MMIO +------------------- + +Memory mapped I/O 는 일반적으로 CPU 의 메모리 공간 내의 한 윈도우의 특정 부분 +내의 메모리 지역에 이루어지는데, 이 윈도우는 일반적인, RAM 으로 향하는 +윈도우와는 다른 특성을 갖습니다. + +그런 특성 가운데 하나는, 일반적으로 그런 액세스는 캐시를 완전히 우회하고 +디바이스 버스로 곧바로 향한다는 것입니다. 이 말은 MMIO 액세스는 먼저 +시작되어서 캐시에서 완료된 메모리 액세스를 추월할 수 있다는 뜻입니다. 이런 +경우엔 메모리 배리어만으로는 충분치 않고, 만약 캐시된 메모리 쓰기 오퍼레이션과 +MMIO 액세스가 어떤 방식으로든 의존적이라면 해당 캐시는 두 오퍼레이션 사이에 +비워져(flush)야만 합니다. + + +====================== +CPU 들이 저지르는 일들 +====================== + +프로그래머는 CPU 가 메모리 오퍼레이션들을 정확히 요청한대로 수행해 줄 것이라고 +생각하는데, 예를 들어 다음과 같은 코드를 CPU 에게 넘긴다면: + + a = READ_ONCE(*A); + WRITE_ONCE(*B, b); + c = READ_ONCE(*C); + d = READ_ONCE(*D); + WRITE_ONCE(*E, e); + +CPU 는 다음 인스트럭션을 처리하기 전에 현재의 인스트럭션을 위한 메모리 +오퍼레이션을 완료할 것이라 생각하고, 따라서 시스템 외부에서 관찰하기에도 정해진 +순서대로 오퍼레이션이 수행될 것으로 예상합니다: + + LOAD *A, STORE *B, LOAD *C, LOAD *D, STORE *E. + + +당연하지만, 실제로는 훨씬 엉망입니다. 많은 CPU 와 컴파일러에서 앞의 가정은 +성립하지 못하는데 그 이유는 다음과 같습니다: + + (*) 로드 오퍼레이션들은 실행을 계속 해나가기 위해 곧바로 완료될 필요가 있는 + 경우가 많은 반면, 스토어 오퍼레이션들은 종종 별다른 문제 없이 유예될 수 + 있습니다; + + (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으며, 필요없는 로드였다고 + 증명된 예측적 로드의 결과는 버려집니다; + + (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으므로, 예상된 이벤트의 + 시퀀스와 다른 시간에 로드가 이뤄질 수 있습니다; + + (*) 메모리 액세스 순서는 CPU 버스와 캐시를 좀 더 잘 사용할 수 있도록 재배치 + 될 수 있습니다; + + (*) 로드와 스토어는 인접한 위치에의 액세스들을 일괄적으로 처리할 수 있는 + 메모리나 I/O 하드웨어 (메모리와 PCI 디바이스 둘 다 이게 가능할 수 + 있습니다) 에 대해 요청되는 경우, 개별 오퍼레이션을 위한 트랜잭션 설정 + 비용을 아끼기 위해 조합되어 실행될 수 있습니다; 그리고 + + (*) 해당 CPU 의 데이터 캐시가 순서에 영향을 끼칠 수도 있고, 캐시 일관성 + 메커니즘이 - 스토어가 실제로 캐시에 도달한다면 - 이 문제를 완화시킬 수는 + 있지만 이 일관성 관리가 다른 CPU 들에도 같은 순서로 전달된다는 보장은 + 없습니다. + +따라서, 앞의 코드에 대해 다른 CPU 가 보는 결과는 다음과 같을 수 있습니다: + + LOAD *A, ..., LOAD {*C,*D}, STORE *E, STORE *B + + ("LOAD {*C,*D}" 는 조합된 로드입니다) + + +하지만, CPU 는 스스로는 일관적일 것을 보장합니다: CPU _자신_ 의 액세스들은 +자신에게는 메모리 배리어가 없음에도 불구하고 정확히 순서 세워진 것으로 보여질 +것입니다. 예를 들어 다음의 코드가 주어졌다면: + + U = READ_ONCE(*A); + WRITE_ONCE(*A, V); + WRITE_ONCE(*A, W); + X = READ_ONCE(*A); + WRITE_ONCE(*A, Y); + Z = READ_ONCE(*A); + +그리고 외부의 영향에 의한 간섭이 없다고 가정하면, 최종 결과는 다음과 같이 +나타날 것이라고 예상될 수 있습니다: + + U == *A 의 최초 값 + X == W + Z == Y + *A == Y + +앞의 코드는 CPU 가 다음의 메모리 액세스 시퀀스를 만들도록 할겁니다: + + U=LOAD *A, STORE *A=V, STORE *A=W, X=LOAD *A, STORE *A=Y, Z=LOAD *A + +하지만, 별다른 개입이 없고 프로그램의 시야에 이 세상이 여전히 일관적이라고 +보인다는 보장만 지켜진다면 이 시퀀스는 어떤 조합으로든 재구성될 수 있으며, 각 +액세스들은 합쳐지거나 버려질 수 있습니다. 일부 아키텍쳐에서 CPU 는 같은 위치에 +대한 연속적인 로드 오퍼레이션들을 재배치 할 수 있기 때문에 앞의 예에서의 +READ_ONCE() 와 WRITE_ONCE() 는 반드시 존재해야 함을 알아두세요. 그런 종류의 +아키텍쳐에서 READ_ONCE() 와 WRITE_ONCE() 는 이 문제를 막기 위해 필요한 일을 +뭐가 됐든지 하게 되는데, 예를 들어 Itanium 에서는 READ_ONCE() 와 WRITE_ONCE() +가 사용하는 volatile 캐스팅은 GCC 가 그런 재배치를 방지하는 특수 인스트럭션인 +ld.acq 와 stl.rel 인스트럭션을 각각 만들어 내도록 합니다. + +컴파일러 역시 이 시퀀스의 액세스들을 CPU 가 보기도 전에 합치거나 버리거나 뒤로 +미뤄버릴 수 있습니다. + +예를 들어: + + *A = V; + *A = W; + +는 다음과 같이 변형될 수 있습니다: + + *A = W; + +따라서, 쓰기 배리어나 WRITE_ONCE() 가 없다면 *A 로의 V 값의 저장의 효과는 +사라진다고 가정될 수 있습니다. 비슷하게: + + *A = Y; + Z = *A; + +는, 메모리 배리어나 READ_ONCE() 와 WRITE_ONCE() 없이는 다음과 같이 변형될 수 +있습니다: + + *A = Y; + Z = Y; + +그리고 이 LOAD 오퍼레이션은 CPU 바깥에는 아예 보이지 않습니다. + + +그리고, ALPHA 가 있다 +--------------------- + +DEC Alpha CPU 는 가장 완화된 메모리 순서의 CPU 중 하나입니다. 뿐만 아니라, +Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서, 의미적으로 +관계되어 있는 두개의 캐시 라인이 서로 다른 시간에 업데이트 되는게 가능합니다. +이게 데이터 의존성 배리어가 정말 필요해지는 부분인데, 데이터 의존성 배리어는 +메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운 +데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다. + +리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다. + +위의 "캐시 일관성" 서브섹션을 참고하세요. + + +가상 머신 게스트 +---------------- + +가상 머신에서 동작하는 게스트들은 게스트 자체는 SMP 지원 없이 컴파일 되었다 +해도 SMP 영향을 받을 수 있습니다. 이건 UP 커널을 사용하면서 SMP 호스트와 +결부되어 발생하는 부작용입니다. 이 경우에는 mandatory 배리어를 사용해서 문제를 +해결할 수 있겠지만 그런 해결은 대부분의 경우 최적의 해결책이 아닙니다. + +이 문제를 완벽하게 해결하기 위해, 로우 레벨의 virt_mb() 등의 매크로를 사용할 수 +있습니다. 이것들은 SMP 가 활성화 되어 있다면 smp_mb() 등과 동일한 효과를 +갖습니다만, SMP 와 SMP 아닌 시스템 모두에 대해 동일한 코드를 만들어냅니다. +예를 들어, 가상 머신 게스트들은 (SMP 일 수 있는) 호스트와 동기화를 할 때에는 +smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다. + +이것들은 smp_mb() 류의 것들과 모든 부분에서 동일하며, 특히, MMIO 의 영향에 +대해서는 간여하지 않습니다: MMIO 의 영향을 제어하려면, mandatory 배리어를 +사용하시기 바랍니다. + + +======= +사용 예 +======= + +순환식 버퍼 +----------- + +메모리 배리어는 순환식 버퍼를 생성자(producer)와 소비자(consumer) 사이의 +동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다. 더 자세한 내용을 +위해선 다음을 참고하세요: + + Documentation/circular-buffers.txt + + +========= +참고 문헌 +========= + +Alpha AXP Architecture Reference Manual, Second Edition (Sites & Witek, +Digital Press) + Chapter 5.2: Physical Address Space Characteristics + Chapter 5.4: Caches and Write Buffers + Chapter 5.5: Data Sharing + Chapter 5.6: Read/Write Ordering + +AMD64 Architecture Programmer's Manual Volume 2: System Programming + Chapter 7.1: Memory-Access Ordering + Chapter 7.4: Buffering and Combining Memory Writes + +IA-32 Intel Architecture Software Developer's Manual, Volume 3: +System Programming Guide + Chapter 7.1: Locked Atomic Operations + Chapter 7.2: Memory Ordering + Chapter 7.4: Serializing Instructions + +The SPARC Architecture Manual, Version 9 + Chapter 8: Memory Models + Appendix D: Formal Specification of the Memory Models + Appendix J: Programming with the Memory Models + +UltraSPARC Programmer Reference Manual + Chapter 5: Memory Accesses and Cacheability + Chapter 15: Sparc-V9 Memory Models + +UltraSPARC III Cu User's Manual + Chapter 9: Memory Models + +UltraSPARC IIIi Processor User's Manual + Chapter 8: Memory Models + +UltraSPARC Architecture 2005 + Chapter 9: Memory + Appendix D: Formal Specifications of the Memory Models + +UltraSPARC T1 Supplement to the UltraSPARC Architecture 2005 + Chapter 8: Memory Models + Appendix F: Caches and Cache Coherency + +Solaris Internals, Core Kernel Architecture, p63-68: + Chapter 3.3: Hardware Considerations for Locks and + Synchronization + +Unix Systems for Modern Architectures, Symmetric Multiprocessing and Caching +for Kernel Programmers: + Chapter 13: Other Memory Models + +Intel Itanium Architecture Software Developer's Manual: Volume 1: + Section 2.6: Speculation + Section 4.4: Memory Access diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.txt index 1f9b3e2b98ae..1f6d45abfe42 100644 --- a/Documentation/kprobes.txt +++ b/Documentation/kprobes.txt @@ -103,6 +103,16 @@ Note that the probed function's args may be passed on the stack or in registers. The jprobe will work in either case, so long as the handler's prototype matches that of the probed function. +Note that in some architectures (e.g.: arm64 and sparc64) the stack +copy is not done, as the actual location of stacked parameters may be +outside of a reasonable MAX_STACK_SIZE value and because that location +cannot be determined by the jprobes code. In this case the jprobes +user must be careful to make certain the calling signature of the +function does not cause parameters to be passed on the stack (e.g.: +more than eight function arguments, an argument of more than sixteen +bytes, or more than 64 bytes of argument data, depending on +architecture). + 1.3 Return Probes 1.3.1 How Does a Return Probe Work? diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt index 979eacae243d..54bee77fa728 100644 --- a/Documentation/kselftest.txt +++ b/Documentation/kselftest.txt @@ -1,8 +1,9 @@ Linux Kernel Selftests The kernel contains a set of "self tests" under the tools/testing/selftests/ -directory. These are intended to be small unit tests to exercise individual -code paths in the kernel. +directory. These are intended to be small tests to exercise individual code +paths in the kernel. Tests are intended to be run after building, installing +and booting a kernel. On some systems, hot-plug tests could hang forever waiting for cpu and memory to be ready to be offlined. A special hot-plug target is created diff --git a/Documentation/laptops/.gitignore b/Documentation/laptops/.gitignore deleted file mode 100644 index 9fc984e64386..000000000000 --- a/Documentation/laptops/.gitignore +++ /dev/null @@ -1 +0,0 @@ -dslm diff --git a/Documentation/laptops/00-INDEX b/Documentation/laptops/00-INDEX index 7c0ac2a26b9e..86169dc766f7 100644 --- a/Documentation/laptops/00-INDEX +++ b/Documentation/laptops/00-INDEX @@ -1,13 +1,9 @@ 00-INDEX - This file -Makefile - - Makefile for building dslm example program. asus-laptop.txt - information on the Asus Laptop Extras driver. disk-shock-protection.txt - information on hard disk shock protection. -dslm.c - - Simple Disk Sleep Monitor program laptop-mode.txt - how to conserve battery power using laptop-mode. sony-laptop.txt diff --git a/Documentation/laptops/Makefile b/Documentation/laptops/Makefile deleted file mode 100644 index 0abe44f68965..000000000000 --- a/Documentation/laptops/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -# List of programs to build -hostprogs-y := dslm - -# Tell kbuild to always build the programs -always := $(hostprogs-y) diff --git a/Documentation/laptops/dslm.c b/Documentation/laptops/dslm.c deleted file mode 100644 index d5dd2d4b04d8..000000000000 --- a/Documentation/laptops/dslm.c +++ /dev/null @@ -1,166 +0,0 @@ -/* - * dslm.c - * Simple Disk Sleep Monitor - * by Bartek Kania - * Licensed under the GPL - */ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#ifdef DEBUG -#define D(x) x -#else -#define D(x) -#endif - -int endit = 0; - -/* Check if the disk is in powersave-mode - * Most of the code is stolen from hdparm. - * 1 = active, 0 = standby/sleep, -1 = unknown */ -static int check_powermode(int fd) -{ - unsigned char args[4] = {WIN_CHECKPOWERMODE1,0,0,0}; - int state; - - if (ioctl(fd, HDIO_DRIVE_CMD, &args) - && (args[0] = WIN_CHECKPOWERMODE2) /* try again with 0x98 */ - && ioctl(fd, HDIO_DRIVE_CMD, &args)) { - if (errno != EIO || args[0] != 0 || args[1] != 0) { - state = -1; /* "unknown"; */ - } else - state = 0; /* "sleeping"; */ - } else { - state = (args[2] == 255) ? 1 : 0; - } - D(printf(" drive state is: %d\n", state)); - - return state; -} - -static char *state_name(int i) -{ - if (i == -1) return "unknown"; - if (i == 0) return "sleeping"; - if (i == 1) return "active"; - - return "internal error"; -} - -static char *myctime(time_t time) -{ - char *ts = ctime(&time); - ts[strlen(ts) - 1] = 0; - - return ts; -} - -static void measure(int fd) -{ - time_t start_time; - int last_state; - time_t last_time; - int curr_state; - time_t curr_time = 0; - time_t time_diff; - time_t active_time = 0; - time_t sleep_time = 0; - time_t unknown_time = 0; - time_t total_time = 0; - int changes = 0; - float tmp; - - printf("Starting measurements\n"); - - last_state = check_powermode(fd); - start_time = last_time = time(0); - printf(" System is in state %s\n\n", state_name(last_state)); - - while(!endit) { - sleep(1); - curr_state = check_powermode(fd); - - if (curr_state != last_state || endit) { - changes++; - curr_time = time(0); - time_diff = curr_time - last_time; - - if (last_state == 1) active_time += time_diff; - else if (last_state == 0) sleep_time += time_diff; - else unknown_time += time_diff; - - last_state = curr_state; - last_time = curr_time; - - printf("%s: State-change to %s\n", myctime(curr_time), - state_name(curr_state)); - } - } - changes--; /* Compensate for SIGINT */ - - total_time = time(0) - start_time; - printf("\nTotal running time: %lus\n", curr_time - start_time); - printf(" State changed %d times\n", changes); - - tmp = (float)sleep_time / (float)total_time * 100; - printf(" Time in sleep state: %lus (%.2f%%)\n", sleep_time, tmp); - tmp = (float)active_time / (float)total_time * 100; - printf(" Time in active state: %lus (%.2f%%)\n", active_time, tmp); - tmp = (float)unknown_time / (float)total_time * 100; - printf(" Time in unknown state: %lus (%.2f%%)\n", unknown_time, tmp); -} - -static void ender(int s) -{ - endit = 1; -} - -static void usage(void) -{ - puts("usage: dslm [-w