diff options
| author | Jiri Kosina <jkosina@suse.cz> | 2017-05-02 11:02:41 +0200 |
|---|---|---|
| committer | Jiri Kosina <jkosina@suse.cz> | 2017-05-02 11:02:41 +0200 |
| commit | 4d6ca227c768b50b05cf183974b40abe444e9d0c (patch) | |
| tree | bf953d8e895281053548b9967a2c4b58d641df00 /Documentation | |
| parent | 800f3eef8ebc1264e9c135bfa892c8ae41fa4792 (diff) | |
| parent | af22a610bc38508d5ea760507d31be6b6983dfa8 (diff) | |
| download | linux-4d6ca227c768b50b05cf183974b40abe444e9d0c.tar.gz linux-4d6ca227c768b50b05cf183974b40abe444e9d0c.tar.bz2 linux-4d6ca227c768b50b05cf183974b40abe444e9d0c.zip | |
Merge branch 'for-4.12/asus' into for-linus
Diffstat (limited to 'Documentation')
372 files changed, 10237 insertions, 6212 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index c8a8eb1a2b11..793acf999e9e 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -270,8 +270,8 @@ m68k/ - directory with info about Linux on Motorola 68k architecture. mailbox.txt - How to write drivers for the common mailbox framework (IPC). -md-cluster.txt - - info on shared-device RAID MD cluster. +md/ + - directory with info about Linux Software RAID media/ - info on media drivers: uAPI, kAPI and driver documentation. memory-barriers.txt diff --git a/Documentation/ABI/obsolete/sysfs-block-zram b/Documentation/ABI/obsolete/sysfs-block-zram deleted file mode 100644 index 720ea92cfb2e..000000000000 --- a/Documentation/ABI/obsolete/sysfs-block-zram +++ /dev/null @@ -1,119 +0,0 @@ -What: /sys/block/zram<id>/num_reads -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The num_reads file is read-only and specifies the number of - reads (failed or successful) done on this device. - Now accessible via zram<id>/stat node. - -What: /sys/block/zram<id>/num_writes -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The num_writes file is read-only and specifies the number of - writes (failed or successful) done on this device. - Now accessible via zram<id>/stat node. - -What: /sys/block/zram<id>/invalid_io -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The invalid_io file is read-only and specifies the number of - non-page-size-aligned I/O requests issued to this device. - Now accessible via zram<id>/io_stat node. - -What: /sys/block/zram<id>/failed_reads -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The failed_reads file is read-only and specifies the number of - failed reads happened on this device. - Now accessible via zram<id>/io_stat node. - -What: /sys/block/zram<id>/failed_writes -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The failed_writes file is read-only and specifies the number of - failed writes happened on this device. - Now accessible via zram<id>/io_stat node. - -What: /sys/block/zram<id>/notify_free -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The notify_free file is read-only. Depending on device usage - scenario it may account a) the number of pages freed because - of swap slot free notifications or b) the number of pages freed - because of REQ_DISCARD requests sent by bio. The former ones - are sent to a swap block device when a swap slot is freed, which - implies that this disk is being used as a swap disk. The latter - ones are sent by filesystem mounted with discard option, - whenever some data blocks are getting discarded. - Now accessible via zram<id>/io_stat node. - -What: /sys/block/zram<id>/zero_pages -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The zero_pages file is read-only and specifies number of zero - filled pages written to this disk. No memory is allocated for - such pages. - Now accessible via zram<id>/mm_stat node. - -What: /sys/block/zram<id>/orig_data_size -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The orig_data_size file is read-only and specifies uncompressed - size of data stored in this disk. This excludes zero-filled - pages (zero_pages) since no memory is allocated for them. - Unit: bytes - Now accessible via zram<id>/mm_stat node. - -What: /sys/block/zram<id>/compr_data_size -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The compr_data_size file is read-only and specifies compressed - size of data stored in this disk. So, compression ratio can be - calculated using orig_data_size and this statistic. - Unit: bytes - Now accessible via zram<id>/mm_stat node. - -What: /sys/block/zram<id>/mem_used_total -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The mem_used_total file is read-only and specifies the amount - of memory, including allocator fragmentation and metadata - overhead, allocated for this disk. So, allocator space - efficiency can be calculated using compr_data_size and this - statistic. - Unit: bytes - Now accessible via zram<id>/mm_stat node. - -What: /sys/block/zram<id>/mem_used_max -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The mem_used_max file is read/write and specifies the amount - of maximum memory zram have consumed to store compressed data. - For resetting the value, you should write "0". Otherwise, - you could see -EINVAL. - Unit: bytes - Downgraded to write-only node: so it's possible to set new - value only; its current value is stored in zram<id>/mm_stat - node. - -What: /sys/block/zram<id>/mem_limit -Date: August 2015 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The mem_limit file is read/write and specifies the maximum - amount of memory ZRAM can use to store the compressed data. - The limit could be changed in run time and "0" means disable - the limit. No limit is the initial state. Unit: bytes - Downgraded to write-only node: so it's possible to set new - value only; its current value is stored in zram<id>/mm_stat - node. diff --git a/Documentation/ABI/testing/configfs-rdma_cm b/Documentation/ABI/testing/configfs-rdma_cm index 5c389aaf5291..74f9506f42e7 100644 --- a/Documentation/ABI/testing/configfs-rdma_cm +++ b/Documentation/ABI/testing/configfs-rdma_cm @@ -20,3 +20,11 @@ Description: RDMA-CM based connections from HCA <hca> at port <port-num> will be initiated with this RoCE type as default. The possible RoCE types are either "IB/RoCE v1" or "RoCE v2". This parameter has RW access. + +What: /config/rdma_cm/<hca>/ports/<port-num>/default_roce_tos +Date: February 7, 2017 +KernelVersion: 4.11.0 +Description: RDMA-CM QPs from HCA <hca> at port <port-num> + will be created with this TOS as default. + This can be overridden by using the rdma_set_option API. + The possible RoCE TOS values are 0-255. diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram index 4518d30b8c2e..451b6d882b2c 100644 --- a/Documentation/ABI/testing/sysfs-block-zram +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -22,41 +22,6 @@ Description: device. The reset operation frees all the memory associated with this device. -What: /sys/block/zram<id>/num_reads -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The num_reads file is read-only and specifies the number of - reads (failed or successful) done on this device. - -What: /sys/block/zram<id>/num_writes -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The num_writes file is read-only and specifies the number of - writes (failed or successful) done on this device. - -What: /sys/block/zram<id>/invalid_io -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The invalid_io file is read-only and specifies the number of - non-page-size-aligned I/O requests issued to this device. - -What: /sys/block/zram<id>/failed_reads -Date: February 2014 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The failed_reads file is read-only and specifies the number of - failed reads happened on this device. - -What: /sys/block/zram<id>/failed_writes -Date: February 2014 -Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> -Description: - The failed_writes file is read-only and specifies the number of - failed writes happened on this device. - What: /sys/block/zram<id>/max_comp_streams Date: February 2014 Contact: Sergey Senozhatsky <sergey.senozhatsky@gmail.com> @@ -73,74 +38,24 @@ Description: available and selected compression algorithms, change compression algorithm selection. -What: /sys/block/zram<id>/notify_free -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The notify_free file is read-only. Depending on device usage - scenario it may account a) the number of pages freed because - of swap slot free notifications or b) the number of pages freed - because of REQ_DISCARD requests sent by bio. The former ones - are sent to a swap block device when a swap slot is freed, which - implies that this disk is being used as a swap disk. The latter - ones are sent by filesystem mounted with discard option, - whenever some data blocks are getting discarded. - -What: /sys/block/zram<id>/zero_pages -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The zero_pages file is read-only and specifies number of zero - filled pages written to this disk. No memory is allocated for - such pages. - -What: /sys/block/zram<id>/orig_data_size -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The orig_data_size file is read-only and specifies uncompressed - size of data stored in this disk. This excludes zero-filled - pages (zero_pages) since no memory is allocated for them. - Unit: bytes - -What: /sys/block/zram<id>/compr_data_size -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The compr_data_size file is read-only and specifies compressed - size of data stored in this disk. So, compression ratio can be - calculated using orig_data_size and this statistic. - Unit: bytes - -What: /sys/block/zram<id>/mem_used_total -Date: August 2010 -Contact: Nitin Gupta <ngupta@vflare.org> -Description: - The mem_used_total file is read-only and specifies the amount - of memory, including allocator fragmentation and metadata - overhead, allocated for this disk. So, allocator space - efficiency can be calculated using compr_data_size and this - statistic. - Unit: bytes - What: /sys/block/zram<id>/mem_used_max Date: August 2014 Contact: Minchan Kim <minchan@kernel.org> Description: - The mem_used_max file is read/write and specifies the amount - of maximum memory zram have consumed to store compressed data. - For resetting the value, you should write "0". Otherwise, - you could see -EINVAL. + The mem_used_max file is write-only and is used to reset + the counter of maximum memory zram have consumed to store + compressed data. For resetting the value, you should write + "0". Otherwise, you could see -EINVAL. Unit: bytes What: /sys/block/zram<id>/mem_limit Date: August 2014 Contact: Minchan Kim <minchan@kernel.org> Description: - The mem_limit file is read/write and specifies the maximum - amount of memory ZRAM can use to store the compressed data. The - limit could be changed in run time and "0" means disable the - limit. No limit is the initial state. Unit: bytes + The mem_limit file is write-only and specifies the maximum + amount of memory ZRAM can use to store the compressed data. + The limit could be changed in run time and "0" means disable + the limit. No limit is the initial state. Unit: bytes What: /sys/block/zram<id>/compact Date: August 2015 diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k b/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k new file mode 100644 index 000000000000..398b258fb770 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-bq32k @@ -0,0 +1,7 @@ +What: /sys/bus/i2c/devices/.../trickle_charge_bypass +Date: Jan 2017 +KernelVersion: 4.11 +Contact: Enric Balletbo i Serra <eballetbo@gmail.com> +Description: Attribute for enable/disable the trickle charge bypass + The trickle_charge_bypass attribute allows the userspace to + enable/disable the Trickle charge FET bypass. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index b8f220f978dd..530809ccfacf 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -170,6 +170,16 @@ Description: Has all of the equivalent parameters as per voltageY. Units after application of scale and offset are m/s^2. +What: /sys/bus/iio/devices/iio:deviceX/in_gravity_x_raw +What: /sys/bus/iio/devices/iio:deviceX/in_gravity_y_raw +What: /sys/bus/iio/devices/iio:deviceX/in_gravity_z_raw +KernelVersion: 4.11 +Contact: linux-iio@vger.kernel.org +Description: + Gravity in direction x, y or z (may be arbitrarily assigned + but should match other such assignments on device). + Units after application of scale and offset are m/s^2. + What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_raw What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_raw What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_raw @@ -805,7 +815,7 @@ Description: attribute. E.g. if in_voltage0_raw_thresh_rising_value is set to 1200 and in_voltage0_raw_thresh_rising_hysteresis is set to 50. The event will get activated once in_voltage0_raw goes above 1200 and will become - deactived again once the value falls below 1150. + deactivated again once the value falls below 1150. What: /sys/.../events/in_accel_x_raw_roc_rising_value What: /sys/.../events/in_accel_x_raw_roc_falling_value @@ -1245,7 +1255,8 @@ Description: reflectivity of infrared or ultrasound emitted. Often these sensors are unit less and as such conversion to SI units is not possible. Higher proximity measurements - indicate closer objects, and vice versa. + indicate closer objects, and vice versa. Units after + application of scale and offset are meters. What: /sys/.../iio:deviceX/in_illuminance_input What: /sys/.../iio:deviceX/in_illuminance_raw diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 new file mode 100644 index 000000000000..efe4c85e3c8b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 @@ -0,0 +1,18 @@ +What: /sys/bus/iio/devices/triggerX/trigger_polarity +KernelVersion: 4.11 +Contact: fabrice.gasnier@st.com +Description: + The STM32 ADC can be configured to use external trigger sources + (e.g. timers, pwm or exti gpio). Then, it can be tuned to start + conversions on external trigger by either: + - "rising-edge" + - "falling-edge" + - "both-edges". + Reading returns current trigger polarity. + Writing value before enabling conversions sets trigger polarity. + +What: /sys/bus/iio/devices/triggerX/trigger_polarity_available +KernelVersion: 4.11 +Contact: fabrice.gasnier@st.com +Description: + List all available trigger_polarity settings. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 new file mode 100644 index 000000000000..0a1ca1487fa9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 @@ -0,0 +1,22 @@ +What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity +Date: January 2017 +KernelVersion: 4.11 +Contact: linux-iio@vger.kernel.org +Description: + Show or set the gain boost of the amp, from 0-31 range. + default 31 + +What /sys/bus/iio/devices/iio:deviceX/sensor_max_range +Date: January 2017 +KernelVersion: 4.11 +Contact: linux-iio@vger.kernel.org +Description: + Show or set the maximum range between the sensor and the + first object echoed in meters. Default value is 6.020. + This setting limits the time the driver is waiting for a + echo. + Showing the range of available values is represented as the + minimum value, the step and the maximum value, all enclosed + in square brackets. + Example: + [0.043 0.043 11.008] diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 new file mode 100644 index 000000000000..6534a60037ff --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 @@ -0,0 +1,29 @@ +What: /sys/bus/iio/devices/triggerX/master_mode_available +KernelVersion: 4.11 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the list possible master modes which are: + - "reset" : The UG bit from the TIMx_EGR register is used as trigger output (TRGO). + - "enable" : The Counter Enable signal CNT_EN is used as trigger output. + - "update" : The update event is selected as trigger output. + For instance a master timer can then be used as a prescaler for a slave timer. + - "compare_pulse" : The trigger output send a positive pulse when the CC1IF flag is to be set. + - "OC1REF" : OC1REF signal is used as trigger output. + - "OC2REF" : OC2REF signal is used as trigger output. + - "OC3REF" : OC3REF signal is used as trigger output. + - "OC4REF" : OC4REF signal is used as trigger output. + +What: /sys/bus/iio/devices/triggerX/master_mode +KernelVersion: 4.11 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the current master modes. + Writing set the master mode + +What: /sys/bus/iio/devices/triggerX/sampling_frequency +KernelVersion: 4.11 +Contact: benjamin.gaignard@st.com +Description: + Reading returns the current sampling frequency. + Writing an value different of 0 set and start sampling. + Writing 0 stop sampling. diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.txt index b1a19835e907..c41331398752 100644 --- a/Documentation/DMA-ISA-LPC.txt +++ b/Documentation/DMA-ISA-LPC.txt @@ -42,7 +42,7 @@ requirements you pass the flag GFP_DMA to kmalloc. Unfortunately the memory available for ISA DMA is scarce so unless you allocate the memory during boot-up it's a good idea to also pass -__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder. +__GFP_REPEAT and __GFP_NOWARN to make the allocator try a bit harder. (This scarcity also means that you should allocate the buffer as early as possible and not release it until the driver is unloaded.) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index a6eb7dcd4dd5..164c1c76971f 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -7,13 +7,13 @@ # list of DOCBOOKS. DOCBOOKS := z8530book.xml \ - kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ + kernel-hacking.xml kernel-locking.xml \ writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - sh.xml regulator.xml w1.xml \ - writing_musb_glue_layer.xml iio.xml + genericirq.xml s390-drivers.xml scsi.xml \ + sh.xml w1.xml \ + writing_musb_glue_layer.xml ifeq ($(DOCBOOKS),) @@ -71,6 +71,7 @@ installmandocs: mandocs # no-op for the DocBook toolchain epubdocs: latexdocs: +linkcheckdocs: ### #External programs used @@ -272,6 +273,6 @@ cleandocs: $(Q)rm -rf $(call objectify, $(clean-dirs)) # Declare the contents of the .PHONY variable as phony. We keep that -# information in a variable se we can use it in if_changed and friends. +# information in a variable so we can use it in if_changed and friends. .PHONY: $(PHONY) diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl deleted file mode 100644 index 54199a0dcf9a..000000000000 --- a/Documentation/DocBook/deviceiobook.tmpl +++ /dev/null @@ -1,323 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="DoingIO"> - <bookinfo> - <title>Bus-Independent Device Accesses</title> - - <authorgroup> - <author> - <firstname>Matthew</firstname> - <surname>Wilcox</surname> - <affiliation> - <address> - <email>matthew@wil.cx</email> - </address> - </affiliation> - </author> - </authorgroup> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@lxorguk.ukuu.org.uk</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2001</year> - <holder>Matthew Wilcox</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - Linux provides an API which abstracts performing IO across all busses - and devices, allowing device drivers to be written independently of - bus type. - </para> - </chapter> - - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None. - </para> - </chapter> - - <chapter id="mmio"> - <title>Memory Mapped IO</title> - <sect1 id="getting_access_to_the_device"> - <title>Getting Access to the Device</title> - <para> - The most widely supported form of IO is memory mapped IO. - That is, a part of the CPU's address space is interpreted - not as accesses to memory, but as accesses to a device. Some - architectures define devices to be at a fixed address, but most - have some method of discovering devices. The PCI bus walk is a - good example of such a scheme. This document does not cover how - to receive such an address, but assumes you are starting with one. - Physical addresses are of type unsigned long. - </para> - - <para> - This address should not be used directly. Instead, to get an - address suitable for passing to the accessor functions described - below, you should call <function>ioremap</function>. - An address suitable for accessing the device will be returned to you. - </para> - - <para> - After you've finished using the device (say, in your module's - exit routine), call <function>iounmap</function> in order to return - the address space to the kernel. Most architectures allocate new - address space each time you call <function>ioremap</function>, and - they can run out unless you call <function>iounmap</function>. - </para> - </sect1> - - <sect1 id="accessing_the_device"> - <title>Accessing the device</title> - <para> - The part of the interface most used by drivers is reading and - writing memory-mapped registers on the device. Linux provides - interfaces to read and write 8-bit, 16-bit, 32-bit and 64-bit - quantities. Due to a historical accident, these are named byte, - word, long and quad accesses. Both read and write accesses are - supported; there is no prefetch support at this time. - </para> - - <para> - The functions are named <function>readb</function>, - <function>readw</function>, <function>readl</function>, - <function>readq</function>, <function>readb_relaxed</function>, - <function>readw_relaxed</function>, <function>readl_relaxed</function>, - <function>readq_relaxed</function>, <function>writeb</function>, - <function>writew</function>, <function>writel</function> and - <function>writeq</function>. - </para> - - <para> - Some devices (such as framebuffers) would like to use larger - transfers than 8 bytes at a time. For these devices, the - <function>memcpy_toio</function>, <function>memcpy_fromio</function> - and <function>memset_io</function> functions are provided. - Do not use memset or memcpy on IO addresses; they - are not guaranteed to copy data in order. - </para> - - <para> - The read and write functions are defined to be ordered. That is the - compiler is not permitted to reorder the I/O sequence. When the - ordering can be compiler optimised, you can use <function> - __readb</function> and friends to indicate the relaxed ordering. Use - this with care. - </para> - - <para> - While the basic functions are defined to be synchronous with respect - to each other and ordered with respect to each other the busses the - devices sit on may themselves have asynchronicity. In particular many - authors are burned by the fact that PCI bus writes are posted - asynchronously. A driver author must issue a read from the same - device to ensure that writes have occurred in the specific cases the - author cares. This kind of property cannot be hidden from driver - writers in the API. In some cases, the read used to flush the device - may be expected to fail (if the card is resetting, for example). In - that case, the read should be done from config space, which is - guaranteed to soft-fail if the card doesn't respond. - </para> - - <para> - The following is an example of flushing a write to a device when - the driver would like to ensure the write's effects are visible prior - to continuing execution. - </para> - -<programlisting> -static inline void -qla1280_disable_intrs(struct scsi_qla_host *ha) -{ - struct device_reg *reg; - - reg = ha->iobase; - /* disable risc and host interrupts */ - WRT_REG_WORD(&reg->ictrl, 0); - /* - * The following read will ensure that the above write - * has been received by the device before we return from this - * function. - */ - RD_REG_WORD(&reg->ictrl); - ha->flags.ints_enabled = 0; -} -</programlisting> - - <para> - In addition to write posting, on some large multiprocessing systems - (e.g. SGI Challenge, Origin and Altix machines) posted writes won't - be strongly ordered coming from different CPUs. Thus it's important - to properly protect parts of your driver that do memory-mapped writes - with locks and use the <function>mmiowb</function> to make sure they - arrive in the order intended. Issuing a regular <function>readX - </function> will also ensure write ordering, but should only be used - when the driver has to be sure that the write has actually arrived - at the device (not that it's simply ordered with respect to other - writes), since a full <function>readX</function> is a relatively - expensive operation. - </para> - - <para> - Generally, one should use <function>mmiowb</function> prior to - releasing a spinlock that protects regions using <function>writeb - </function> or similar functions that aren't surrounded by <function> - readb</function> calls, which will ensure ordering and flushing. The - following pseudocode illustrates what might occur if write ordering - isn't guaranteed via <function>mmiowb</function> or one of the - <function>readX</function> functions. - </para> - -<programlisting> -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: writel(newval2, ring_ptr); -CPU B: ... -CPU B: spin_unlock_irqrestore(&dev_lock, flags) -</programlisting> - - <para> - In the case above, newval2 could be written to ring_ptr before - newval. Fixing it is easy though: - </para> - -<programlisting> -CPU A: spin_lock_irqsave(&dev_lock, flags) -CPU A: ... -CPU A: writel(newval, ring_ptr); -CPU A: mmiowb(); /* ensure no other writes beat us to the device */ -CPU A: spin_unlock_irqrestore(&dev_lock, flags) - ... -CPU B: spin_lock_irqsave(&dev_lock, flags) -CPU B: writel(newval2, ring_ptr); -CPU B: ... -CPU B: mmiowb(); -CPU B: spin_unlock_irqrestore(&dev_lock, flags) -</programlisting> - - <para> - See tg3.c for a real world example of how to use <function>mmiowb - </function> - </para> - - <para> - PCI ordering rules also guarantee that PIO read responses arrive - after any outstanding DMA writes from that bus, since for some devices - the result of a <function>readb</function> call may signal to the - driver that a DMA transaction is complete. In many cases, however, - the driver may want to indicate that the next - <function>readb</function> call has no relation to any previous DMA - writes performed by the device. The driver can use - <function>readb_relaxed</function> for these cases, although only - some platforms will honor the relaxed semantics. Using the relaxed - read functions will provide significant performance benefits on - platforms that support it. The qla2xxx driver provides examples - of how to use <function>readX_relaxed</function>. In many cases, - a majority of the driver's <function>readX</function> calls can - safely be converted to <function>readX_relaxed</function> calls, since - only a few will indicate or depend on DMA completion. - </para> - </sect1> - - </chapter> - - <chapter id="port_space_accesses"> - <title>Port Space Accesses</title> - <sect1 id="port_space_explained"> - <title>Port Space Explained</title> - - <para> - Another form of IO commonly supported is Port Space. This is a - range of addresses separate to the normal memory address space. - Access to these addresses is generally not as fast as accesses - to the memory mapped addresses, and it also has a potentially - smaller address space. - </para> - - <para> - Unlike memory mapped IO, no preparation is required - to access port space. - </para> - - </sect1> - <sect1 id="accessing_port_space"> - <title>Accessing Port Space</title> - <para> - Accesses to this space are provided through a set of functions - which allow 8-bit, 16-bit and 32-bit accesses; also - known as byte, word and long. These functions are - <function>inb</function>, <function>inw</function>, - <function>inl</function>, <function>outb</function>, - <function>outw</function> and <function>outl</function>. - </para> - - <para> - Some variants are provided for these functions. Some devices - require that accesses to their ports are slowed down. This - functionality is provided by appending a <function>_p</function> - to the end of the function. There are also equivalents to memcpy. - The <function>ins</function> and <function>outs</function> - functions copy bytes, words or longs to the given port. - </para> - </sect1> - - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Iarch/x86/include/asm/io.h -!Elib/pci_iomap.c - </chapter> - -</book> diff --git a/Documentation/DocBook/iio.tmpl b/Documentation/DocBook/iio.tmpl deleted file mode 100644 index e2ab6a1f223e..000000000000 --- a/Documentation/DocBook/iio.tmpl +++ /dev/null @@ -1,697 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="iioid"> - <bookinfo> - <title>Industrial I/O driver developer's guide </title> - - <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Baluta</surname> - <affiliation> - <address> - <email>daniel.baluta@intel.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2015</year> - <holder>Intel Corporation</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2. - </para> - </legalnotice> - </bookinfo> - - <toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The main purpose of the Industrial I/O subsystem (IIO) is to provide - support for devices that in some sense perform either analog-to-digital - conversion (ADC) or digital-to-analog conversion (DAC) or both. The aim - is to fill the gap between the somewhat similar hwmon and input - subsystems. - Hwmon is directed at low sample rate sensors used to monitor and - control the system itself, like fan speed control or temperature - measurement. Input is, as its name suggests, focused on human interaction - input devices (keyboard, mouse, touchscreen). In some cases there is - considerable overlap between these and IIO. - </para> - <para> - Devices that fall into this category include: - <itemizedlist> - <listitem> - analog to digital converters (ADCs) - </listitem> - <listitem> - accelerometers - </listitem> - <listitem> - capacitance to digital converters (CDCs) - </listitem> - <listitem> - digital to analog converters (DACs) - </listitem> - <listitem> - gyroscopes - </listitem> - <listitem> - inertial measurement units (IMUs) - </listitem> - <listitem> - color and light sensors - </listitem> - <listitem> - magnetometers - </listitem> - <listitem> - pressure sensors - </listitem> - <listitem> - proximity sensors - </listitem> - <listitem> - temperature sensors - </listitem> - </itemizedlist> - Usually these sensors are connected via SPI or I2C. A common use case of the - sensors devices is to have combined functionality (e.g. light plus proximity - sensor). - </para> - </chapter> - <chapter id='iiosubsys'> - <title>Industrial I/O core</title> - <para> - The Industrial I/O core offers: - <itemizedlist> - <listitem> - a unified framework for writing drivers for many different types of - embedded sensors. - </listitem> - <listitem> - a standard interface to user space applications manipulating sensors. - </listitem> - </itemizedlist> - The implementation can be found under <filename> - drivers/iio/industrialio-*</filename> - </para> - <sect1 id="iiodevice"> - <title> Industrial I/O devices </title> - -!Finclude/linux/iio/iio.h iio_dev -!Fdrivers/iio/industrialio-core.c iio_device_alloc -!Fdrivers/iio/industrialio-core.c iio_device_free -!Fdrivers/iio/industrialio-core.c iio_device_register -!Fdrivers/iio/industrialio-core.c iio_device_unregister - - <para> - An IIO device usually corresponds to a single hardware sensor and it - provides all the information needed by a driver handling a device. - Let's first have a look at the functionality embedded in an IIO - device then we will show how a device driver makes use of an IIO - device. - </para> - <para> - There are two ways for a user space application to interact - with an IIO driver. - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/</filename>, this - represents a hardware sensor and groups together the data - channels of the same chip. - </listitem> - <listitem> - <filename>/dev/iio:deviceX</filename>, character device node - interface used for buffered data transfer and for events information - retrieval. - </listitem> - </itemizedlist> - </para> - A typical IIO driver will register itself as an I2C or SPI driver and will - create two routines, <function> probe </function> and <function> remove - </function>. At <function>probe</function>: - <itemizedlist> - <listitem>call <function>iio_device_alloc</function>, which allocates memory - for an IIO device. - </listitem> - <listitem> initialize IIO device fields with driver specific information - (e.g. device name, device channels). - </listitem> - <listitem>call <function> iio_device_register</function>, this registers the - device with the IIO core. After this call the device is ready to accept - requests from user space applications. - </listitem> - </itemizedlist> - At <function>remove</function>, we free the resources allocated in - <function>probe</function> in reverse order: - <itemizedlist> - <listitem><function>iio_device_unregister</function>, unregister the device - from the IIO core. - </listitem> - <listitem><function>iio_device_free</function>, free the memory allocated - for the IIO device. - </listitem> - </itemizedlist> - - <sect2 id="iioattr"> <title> IIO device sysfs interface </title> - <para> - Attributes are sysfs files used to expose chip info and also allowing - applications to set various configuration parameters. For device - with index X, attributes can be found under - <filename>/sys/bus/iio/iio:deviceX/ </filename> directory. - Common attributes are: - <itemizedlist> - <listitem><filename>name</filename>, description of the physical - chip. - </listitem> - <listitem><filename>dev</filename>, shows the major:minor pair - associated with <filename>/dev/iio:deviceX</filename> node. - </listitem> - <listitem><filename>sampling_frequency_available</filename>, - available discrete set of sampling frequency values for - device. - </listitem> - </itemizedlist> - Available standard attributes for IIO devices are described in the - <filename>Documentation/ABI/testing/sysfs-bus-iio </filename> file - in the Linux kernel sources. - </para> - </sect2> - <sect2 id="iiochannel"> <title> IIO device channels </title> -!Finclude/linux/iio/iio.h iio_chan_spec structure. - <para> - An IIO device channel is a representation of a data channel. An - IIO device can have one or multiple channels. For example: - <itemizedlist> - <listitem> - a thermometer sensor has one channel representing the - temperature measurement. - </listitem> - <listitem> - a light sensor with two channels indicating the measurements in - the visible and infrared spectrum. - </listitem> - <listitem> - an accelerometer can have up to 3 channels representing - acceleration on X, Y and Z axes. - </listitem> - </itemizedlist> - An IIO channel is described by the <type> struct iio_chan_spec - </type>. A thermometer driver for the temperature sensor in the - example above would have to describe its channel as follows: - <programlisting> - static const struct iio_chan_spec temp_channel[] = { - { - .type = IIO_TEMP, - .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), - }, - }; - - </programlisting> - Channel sysfs attributes exposed to userspace are specified in - the form of <emphasis>bitmasks</emphasis>. Depending on their - shared info, attributes can be set in one of the following masks: - <itemizedlist> - <listitem><emphasis>info_mask_separate</emphasis>, attributes will - be specific to this channel</listitem> - <listitem><emphasis>info_mask_shared_by_type</emphasis>, - attributes are shared by all channels of the same type</listitem> - <listitem><emphasis>info_mask_shared_by_dir</emphasis>, attributes - are shared by all channels of the same direction </listitem> - <listitem><emphasis>info_mask_shared_by_all</emphasis>, - attributes are shared by all channels</listitem> - </itemizedlist> - When there are multiple data channels per channel type we have two - ways to distinguish between them: - <itemizedlist> - <listitem> set <emphasis> .modified</emphasis> field of <type> - iio_chan_spec</type> to 1. Modifiers are specified using - <emphasis>.channel2</emphasis> field of the same - <type>iio_chan_spec</type> structure and are used to indicate a - physically unique characteristic of the channel such as its direction - or spectral response. For example, a light sensor can have two channels, - one for infrared light and one for both infrared and visible light. - </listitem> - <listitem> set <emphasis>.indexed </emphasis> field of - <type>iio_chan_spec</type> to 1. In this case the channel is - simply another instance with an index specified by the - <emphasis>.channel</emphasis> field. - </listitem> - </itemizedlist> - Here is how we can make use of the channel's modifiers: - <programlisting> - static const struct iio_chan_spec light_channels[] = { - { - .type = IIO_INTENSITY, - .modified = 1, - .channel2 = IIO_MOD_LIGHT_IR, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - { - .type = IIO_INTENSITY, - .modified = 1, - .channel2 = IIO_MOD_LIGHT_BOTH, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - { - .type = IIO_LIGHT, - .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), - .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), - }, - - } - </programlisting> - This channel's definition will generate two separate sysfs files - for raw data retrieval: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_intensity_ir_raw</filename> - </listitem> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_intensity_both_raw</filename> - </listitem> - </itemizedlist> - one file for processed data: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/in_illuminance_input - </filename> - </listitem> - </itemizedlist> - and one shared sysfs file for sampling frequency: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/iio:deviceX/sampling_frequency. - </filename> - </listitem> - </itemizedlist> - </para> - <para> - Here is how we can make use of the channel's indexing: - <programlisting> - static const struct iio_chan_spec light_channels[] = { - { - .type = IIO_VOLTAGE, - .indexed = 1, - .channel = 0, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - }, - { - .type = IIO_VOLTAGE, - .indexed = 1, - .channel = 1, - .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), - }, - } - </programlisting> - This will generate two separate attributes files for raw data - retrieval: - <itemizedlist> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage0_raw</filename>, - representing voltage measurement for channel 0. - </listitem> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/in_voltage1_raw</filename>, - representing voltage measurement for channel 1. - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - - <sect1 id="iiobuffer"> <title> Industrial I/O buffers </title> -!Finclude/linux/iio/buffer.h iio_buffer -!Edrivers/iio/industrialio-buffer.c - - <para> - The Industrial I/O core offers a way for continuous data capture - based on a trigger source. Multiple data channels can be read at once - from <filename>/dev/iio:deviceX</filename> character device node, - thus reducing the CPU load. - </para> - - <sect2 id="iiobuffersysfs"> - <title>IIO buffer sysfs interface </title> - <para> - An IIO buffer has an associated attributes directory under <filename> - /sys/bus/iio/iio:deviceX/buffer/</filename>. Here are the existing - attributes: - <itemizedlist> - <listitem> - <emphasis>length</emphasis>, the total number of data samples - (capacity) that can be stored by the buffer. - </listitem> - <listitem> - <emphasis>enable</emphasis>, activate buffer capture. - </listitem> - </itemizedlist> - - </para> - </sect2> - <sect2 id="iiobuffersetup"> <title> IIO buffer setup </title> - <para>The meta information associated with a channel reading - placed in a buffer is called a <emphasis> scan element </emphasis>. - The important bits configuring scan elements are exposed to - userspace applications via the <filename> - /sys/bus/iio/iio:deviceX/scan_elements/</filename> directory. This - file contains attributes of the following form: - <itemizedlist> - <listitem><emphasis>enable</emphasis>, used for enabling a channel. - If and only if its attribute is non zero, then a triggered capture - will contain data samples for this channel. - </listitem> - <listitem><emphasis>type</emphasis>, description of the scan element - data storage within the buffer and hence the form in which it is - read from user space. Format is <emphasis> - [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] </emphasis>. - <itemizedlist> - <listitem> <emphasis>be</emphasis> or <emphasis>le</emphasis>, specifies - big or little endian. - </listitem> - <listitem> - <emphasis>s </emphasis>or <emphasis>u</emphasis>, specifies if - signed (2's complement) or unsigned. - </listitem> - <listitem><emphasis>bits</emphasis>, is the number of valid data - bits. - </listitem> - <listitem><emphasis>storagebits</emphasis>, is the number of bits - (after padding) that it occupies in the buffer. - </listitem> - <listitem> - <emphasis>shift</emphasis>, if specified, is the shift that needs - to be applied prior to masking out unused bits. - </listitem> - <listitem> - <emphasis>repeat</emphasis>, specifies the number of bits/storagebits - repetitions. When the repeat element is 0 or 1, then the repeat - value is omitted. - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - For example, a driver for a 3-axis accelerometer with 12 bit - resolution where data is stored in two 8-bits registers as - follows: - <programlisting> - 7 6 5 4 3 2 1 0 - +---+---+---+---+---+---+---+---+ - |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) - +---+---+---+---+---+---+---+---+ - - 7 6 5 4 3 2 1 0 - +---+---+---+---+---+---+---+---+ - |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) - +---+---+---+---+---+---+---+---+ - </programlisting> - - will have the following scan element type for each axis: - <programlisting> - $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type - le:s12/16>>4 - </programlisting> - A user space application will interpret data samples read from the - buffer as two byte little endian signed data, that needs a 4 bits - right shift before masking out the 12 valid bits of data. - </para> - <para> - For implementing buffer support a driver should initialize the following - fields in <type>iio_chan_spec</type> definition: - <programlisting> - struct iio_chan_spec { - /* other members */ - int scan_index - struct { - char sign; - u8 realbits; - u8 storagebits; - u8 shift; - u8 repeat; - enum iio_endian endianness; - } scan_type; - }; - </programlisting> - The driver implementing the accelerometer described above will - have the following channel definition: - <programlisting> - struct struct iio_chan_spec accel_channels[] = { - { - .type = IIO_ACCEL, - .modified = 1, - .channel2 = IIO_MOD_X, - /* other stuff here */ - .scan_index = 0, - .scan_type = { - .sign = 's', - .realbits = 12, - .storagebits = 16, - .shift = 4, - .endianness = IIO_LE, - }, - } - /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) - * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis - */ - } - </programlisting> - </para> - <para> - Here <emphasis> scan_index </emphasis> defines the order in which - the enabled channels are placed inside the buffer. Channels with a lower - scan_index will be placed before channels with a higher index. Each - channel needs to have a unique scan_index. - </para> - <para> - Setting scan_index to -1 can be used to indicate that the specific - channel does not support buffered capture. In this case no entries will - be created for the channel in the scan_elements directory. - </para> - </sect2> - </sect1> - - <sect1 id="iiotrigger"> <title> Industrial I/O triggers </title> -!Finclude/linux/iio/trigger.h iio_trigger -!Edrivers/iio/industrialio-trigger.c - <para> - In many situations it is useful for a driver to be able to - capture data based on some external event (trigger) as opposed - to periodically polling for data. An IIO trigger can be provided - by a device driver that also has an IIO device based on hardware - generated events (e.g. data ready or threshold exceeded) or - provided by a separate driver from an independent interrupt - source (e.g. GPIO line connected to some external system, timer - interrupt or user space writing a specific file in sysfs). A - trigger may initiate data capture for a number of sensors and - also it may be completely unrelated to the sensor itself. - </para> - - <sect2 id="iiotrigsysfs"> <title> IIO trigger sysfs interface </title> - There are two locations in sysfs related to triggers: - <itemizedlist> - <listitem><filename>/sys/bus/iio/devices/triggerY</filename>, - this file is created once an IIO trigger is registered with - the IIO core and corresponds to trigger with index Y. Because - triggers can be very different depending on type there are few - standard attributes that we can describe here: - <itemizedlist> - <listitem> - <emphasis>name</emphasis>, trigger name that can be later - used for association with a device. - </listitem> - <listitem> - <emphasis>sampling_frequency</emphasis>, some timer based - triggers use this attribute to specify the frequency for - trigger calls. - </listitem> - </itemizedlist> - </listitem> - <listitem> - <filename>/sys/bus/iio/devices/iio:deviceX/trigger/</filename>, this - directory is created once the device supports a triggered - buffer. We can associate a trigger with our device by writing - the trigger's name in the <filename>current_trigger</filename> file. - </listitem> - </itemizedlist> - </sect2> - - <sect2 id="iiotrigattr"> <title> IIO trigger setup</title> - - <para> - Let's see a simple example of how to setup a trigger to be used - by a driver. - - <programlisting> - struct iio_trigger_ops trigger_ops = { - .set_trigger_state = sample_trigger_state, - .validate_device = sample_validate_device, - } - - struct iio_trigger *trig; - - /* first, allocate memory for our trigger */ - trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx); - - /* setup trigger operations field */ - trig->ops = &trigger_ops; - - /* now register the trigger with the IIO core */ - iio_trigger_register(trig); - </programlisting> - </para> - </sect2> - - <sect2 id="iiotrigsetup"> <title> IIO trigger ops</title> -!Finclude/linux/iio/trigger.h iio_trigger_ops - <para> - Notice that a trigger has a set of operations attached: - <itemizedlist> - <listitem> - <function>set_trigger_state</function>, switch the trigger on/off - on demand. - </listitem> - <listitem> - <function>validate_device</function>, function to validate the - device when the current trigger gets changed. - </listitem> - </itemizedlist> - </para> - </sect2> - </sect1> - <sect1 id="iiotriggered_buffer"> - <title> Industrial I/O triggered buffers </title> - <para> - Now that we know what buffers and triggers are let's see how they - work together. - </para> - <sect2 id="iiotrigbufsetup"> <title> IIO triggered buffer setup</title> -!Edrivers/iio/buffer/industrialio-triggered-buffer.c -!Finclude/linux/iio/iio.h iio_buffer_setup_ops - - - <para> - A typical triggered buffer setup looks like this: - <programlisting> - const struct iio_buffer_setup_ops sensor_buffer_setup_ops = { - .preenable = sensor_buffer_preenable, - .postenable = sensor_buffer_postenable, - .postdisable = sensor_buffer_postdisable, - .predisable = sensor_buffer_predisable, - }; - - irqreturn_t sensor_iio_pollfunc(int irq, void *p) - { - pf->timestamp = iio_get_time_ns((struct indio_dev *)p); - return IRQ_WAKE_THREAD; - } - - irqreturn_t sensor_trigger_handler(int irq, void *p) - { - u16 buf[8]; - int i = 0; - - /* read data for each active channel */ - for_each_set_bit(bit, active_scan_mask, masklength) - buf[i++] = sensor_get_data(bit) - - iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp); - - iio_trigger_notify_done(trigger); - return IRQ_HANDLED; - } - - /* setup triggered buffer, usually in probe function */ - iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc, - sensor_trigger_handler, - sensor_buffer_setup_ops); - </programlisting> - </para> - The important things to notice here are: - <itemizedlist> - <listitem><function> iio_buffer_setup_ops</function>, the buffer setup - functions to be called at predefined points in the buffer configuration - sequence (e.g. before enable, after disable). If not specified, the - IIO core uses the default <type>iio_triggered_buffer_setup_ops</type>. - </listitem> - <listitem><function>sensor_iio_pollfunc</function>, the function that - will be used as top half of poll function. It should do as little - processing as possible, because it runs in interrupt context. The most - common operation is recording of the current timestamp and for this reason - one can use the IIO core defined <function>iio_pollfunc_store_time - </function> function. - </listitem> - <listitem><function>sensor_trigger_handler</function>, the function that - will be used as bottom half of the poll function. This runs in the - context of a kernel thread and all the processing takes place here. - It usually reads data from the device and stores it in the internal - buffer together with the timestamp recorded in the top half. - </listitem> - </itemizedlist> - </sect2> - </sect1> - </chapter> - <chapter id='iioresources'> - <title> Resources </title> - IIO core may change during time so the best documentation to read is the - source code. There are several locations where you should look: - <itemizedlist> - <listitem> - <filename>drivers/iio/</filename>, contains the IIO core plus - and directories for each sensor type (e.g. accel, magnetometer, - etc.) - </listitem> - <listitem> - <filename>include/linux/iio/</filename>, contains the header - files, nice to read for the internal kernel interfaces. - </listitem> - <listitem> - <filename>include/uapi/linux/iio/</filename>, contains files to be - used by user space applications. - </listitem> - <listitem> - <filename>tools/iio/</filename>, contains tools for rapidly - testing buffers, events and device creation. - </listitem> - <listitem> - <filename>drivers/staging/iio/</filename>, contains code for some - drivers or experimental features that are not yet mature enough - to be moved out. - </listitem> - </itemizedlist> - <para> - Besides the code, there are some good online documentation sources: - <itemizedlist> - <listitem> - <ulink url="http://marc.info/?l=linux-iio"> Industrial I/O mailing - list </ulink> - </listitem> - <listitem> - <ulink url="http://wiki.analog.com/software/linux/docs/iio/iio"> - Analog Device IIO wiki page </ulink> - </listitem> - <listitem> - <ulink url="https://fosdem.org/2015/schedule/event/iiosdr/"> - Using the Linux IIO framework for SDR, Lars-Peter Clausen's - presentation at FOSDEM </ulink> - </listitem> - </itemizedlist> - </para> - </chapter> -</book> - -<!-- -vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 ---> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index f3abca7ec53d..856ac20bf367 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -115,12 +115,12 @@ </para> <para> If the architecture that you are using supports the kernel option - CONFIG_DEBUG_RODATA, you should consider turning it off. This + CONFIG_STRICT_KERNEL_RWX, you should consider turning it off. This option will prevent the use of software breakpoints because it marks certain regions of the kernel's memory space as read-only. If kgdb supports it for the architecture you are using, you can use hardware breakpoints if you desire to run with the - CONFIG_DEBUG_RODATA option turned on, else you need to turn off + CONFIG_STRICT_KERNEL_RWX option turned on, else you need to turn off this option. </para> <para> @@ -135,7 +135,7 @@ <para>Here is an example set of .config symbols to enable or disable for kgdb: <itemizedlist> - <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para># CONFIG_STRICT_KERNEL_RWX is not set</para></listitem> <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> <listitem><para>CONFIG_KGDB=y</para></listitem> <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> @@ -166,7 +166,7 @@ </para> <para>Here is an example set of .config symbols to enable/disable kdb: <itemizedlist> - <listitem><para># CONFIG_DEBUG_RODATA is not set</para></listitem> + <listitem><para># CONFIG_STRICT_KERNEL_RWX is not set</para></listitem> <listitem><para>CONFIG_FRAME_POINTER=y</para></listitem> <listitem><para>CONFIG_KGDB=y</para></listitem> <listitem><para>CONFIG_KGDB_SERIAL_CONSOLE=y</para></listitem> diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index d7fcdc5a4379..0320910b866d 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -1020,7 +1020,7 @@ and other resources, etc. </itemizedlist> <para> - Of errors detected as above, the followings are not ATA/ATAPI + Of errors detected as above, the following are not ATA/ATAPI device errors but ATA bus errors and should be handled according to <xref linkend="excatATAbusErr"/>. </para> diff --git a/Documentation/DocBook/regulator.tmpl b/Documentation/DocBook/regulator.tmpl deleted file mode 100644 index 3b08a085d2c7..000000000000 --- a/Documentation/DocBook/regulator.tmpl +++ /dev/null @@ -1,304 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="regulator-api"> - <bookinfo> - <title>Voltage and current regulator API</title> - - <authorgroup> - <author> - <firstname>Liam</firstname> - <surname>Girdwood</surname> - <affiliation> - <address> - <email>lrg@slimlogic.co.uk</email> - </address> - </affiliation> - </author> - <author> - <firstname>Mark</firstname> - <surname>Brown</surname> - <affiliation> - <orgname>Wolfson Microelectronics</orgname> - <address> - <email>broonie@opensource.wolfsonmicro.com</email> - </address> - </affiliation> - </author> - </authorgroup> - - <copyright> - <year>2007-2008</year> - <holder>Wolfson Microelectronics</holder> - </copyright> - <copyright> - <year>2008</year> - <holder>Liam Girdwood</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - This framework is designed to provide a standard kernel - interface to control voltage and current regulators. - </para> - <para> - The intention is to allow systems to dynamically control - regulator power output in order to save power and prolong - battery life. This applies to both voltage regulators (where - voltage output is controllable) and current sinks (where current - limit is controllable). - </para> - <para> - Note that additional (and currently more complete) documentation - is available in the Linux kernel source under - <filename>Documentation/power/regulator</filename>. - </para> - - <sect1 id="glossary"> - <title>Glossary</title> - <para> - The regulator API uses a number of terms which may not be - familiar: - </para> - <glossary> - - <glossentry> - <glossterm>Regulator</glossterm> - <glossdef> - <para> - Electronic device that supplies power to other devices. Most - regulators can enable and disable their output and some can also - control their output voltage or current. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Consumer</glossterm> - <glossdef> - <para> - Electronic device which consumes power provided by a regulator. - These may either be static, requiring only a fixed supply, or - dynamic, requiring active management of the regulator at - runtime. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Power Domain</glossterm> - <glossdef> - <para> - The electronic circuit supplied by a given regulator, including - the regulator and all consumer devices. The configuration of - the regulator is shared between all the components in the - circuit. - </para> - </glossdef> - </glossentry> - - <glossentry> - <glossterm>Power Management Integrated Circuit</glossterm> - <acronym>PMIC</acronym> - <glossdef> - <para> - An IC which contains numerous regulators and often also other - subsystems. In an embedded system the primary PMIC is often - equivalent to a combination of the PSU and southbridge in a - desktop system. - </para> - </glossdef> - </glossentry> - </glossary> - </sect1> - </chapter> - - <chapter id="consumer"> - <title>Consumer driver interface</title> - <para> - This offers a similar API to the kernel clock framework. - Consumer drivers use <link - linkend='API-regulator-get'>get</link> and <link - linkend='API-regulator-put'>put</link> operations to acquire and - release regulators. Functions are - provided to <link linkend='API-regulator-enable'>enable</link> - and <link linkend='API-regulator-disable'>disable</link> the - regulator and to get and set the runtime parameters of the - regulator. - </para> - <para> - When requesting regulators consumers use symbolic names for their - supplies, such as "Vcc", which are mapped into actual regulator - devices by the machine interface. - </para> - <para> - A stub version of this API is provided when the regulator - framework is not in use in order to minimise the need to use - ifdefs. - </para> - - <sect1 id="consumer-enable"> - <title>Enabling and disabling</title> - <para> - The regulator API provides reference counted enabling and - disabling of regulators. Consumer devices use the <function><link - linkend='API-regulator-enable'>regulator_enable</link></function> - and <function><link - linkend='API-regulator-disable'>regulator_disable</link> - </function> functions to enable and disable regulators. Calls - to the two functions must be balanced. - </para> - <para> - Note that since multiple consumers may be using a regulator and - machine constraints may not allow the regulator to be disabled - there is no guarantee that calling - <function>regulator_disable</function> will actually cause the - supply provided by the regulator to be disabled. Consumer - drivers should assume that the regulator may be enabled at all - times. - </para> - </sect1> - - <sect1 id="consumer-config"> - <title>Configuration</title> - <para> - Some consumer devices may need to be able to dynamically - configure their supplies. For example, MMC drivers may need to - select the correct operating voltage for their cards. This may - be done while the regulator is enabled or disabled. - </para> - <para> - The <function><link - linkend='API-regulator-set-voltage'>regulator_set_voltage</link> - </function> and <function><link - linkend='API-regulator-set-current-limit' - >regulator_set_current_limit</link> - </function> functions provide the primary interface for this. - Both take ranges of voltages and currents, supporting drivers - that do not require a specific value (eg, CPU frequency scaling - normally permits the CPU to use a wider range of supply - voltages at lower frequencies but does not require that the - supply voltage be lowered). Where an exact value is required - both minimum and maximum values should be identical. - </para> - </sect1> - - <sect1 id="consumer-callback"> - <title>Callbacks</title> - <para> - Callbacks may also be <link - linkend='API-regulator-register-notifier'>registered</link> - for events such as regulation failures. - </para> - </sect1> - </chapter> - - <chapter id="driver"> - <title>Regulator driver interface</title> - <para> - Drivers for regulator chips <link - linkend='API-regulator-register'>register</link> the regulators - with the regulator core, providing operations structures to the - core. A <link - linkend='API-regulator-notifier-call-chain'>notifier</link> interface - allows error conditions to be reported to the core. - </para> - <para> - Registration should be triggered by explicit setup done by the - platform, supplying a <link - linkend='API-struct-regulator-init-data'>struct - regulator_init_data</link> for the regulator containing - <link linkend='machine-constraint'>constraint</link> and - <link linkend='machine-supply'>supply</link> information. - </para> - </chapter> - - <chapter id="machine"> - <title>Machine interface</title> - <para> - This interface provides a way to define how regulators are - connected to consumers on a given system and what the valid - operating parameters are for the system. - </para> - - <sect1 id="machine-supply"> - <title>Supplies</title> - <para> - Regulator supplies are specified using <link - linkend='API-struct-regulator-consumer-supply'>struct - regulator_consumer_supply</link>. This is done at - <link linkend='driver'>driver registration - time</link> as part of the machine constraints. - </para> - </sect1> - - <sect1 id="machine-constraint"> - <title>Constraints</title> - <para> - As well as defining the connections the machine interface - also provides constraints defining the operations that - clients are allowed to perform and the parameters that may be - set. This is required since generally regulator devices will - offer more flexibility than it is safe to use on a given - system, for example supporting higher supply voltages than the - consumers are rated for. - </para> - <para> - This is done at <link linkend='driver'>driver - registration time</link> by providing a <link - linkend='API-struct-regulation-constraints'>struct - regulation_constraints</link>. - </para> - <para> - The constraints may also specify an initial configuration for the - regulator in the constraints, which is particularly useful for - use with static consumers. - </para> - </sect1> - </chapter> - - <chapter id="api"> - <title>API reference</title> - <para> - Due to limitations of the kernel documentation framework and the - existing layout of the source code the entire regulator API is - documented here. - </para> -!Iinclude/linux/regulator/consumer.h -!Iinclude/linux/regulator/machine.h -!Iinclude/linux/regulator/driver.h -!Edrivers/regulator/core.c - </chapter> -</book> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl deleted file mode 100644 index 5210f8a577c6..000000000000 --- a/Documentation/DocBook/uio-howto.tmpl +++ /dev/null @@ -1,1112 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" []> - -<book id="index"> -<bookinfo> -<title>The Userspace I/O HOWTO</title> - -<author> - <firstname>Hans-Jürgen</firstname> - <surname>Koch</surname> - <authorblurb><para>Linux developer, Linutronix</para></authorblurb> - <affiliation> - <orgname> - <ulink url="http://www.linutronix.de">Linutronix</ulink> - </orgname> - - <address> - <email>hjk@hansjkoch.de</email> - </address> - </affiliation> -</author> - -<copyright> - <year>2006-2008</year> - <holder>Hans-Jürgen Koch.</holder> -</copyright> -<copyright> - <year>2009</year> - <holder>Red Hat Inc, Michael S. Tsirkin (mst@redhat.com)</holder> -</copyright> - -<legalnotice> -<para> -This documentation is Free Software licensed under the terms of the -GPL version 2. -</para> -</legalnotice> - -<pubdate>2006-12-11</pubdate> - -<abstract> - <para>This HOWTO describes concept and usage of Linux kernel's - Userspace I/O system.</para> -</abstract> - -<revhistory> - <revision> - <revnumber>0.10</revnumber> - <date>2016-10-17</date> - <authorinitials>sch</authorinitials> - <revremark>Added generic hyperv driver - </revremark> - </revision> - <revision> - <revnumber>0.9</revnumber> - <date>2009-07-16</date> - <authorinitials>mst</authorinitials> - <revremark>Added generic pci driver - </revremark> - </revision> - <revision> - <revnumber>0.8</revnumber> - <date>2008-12-24</date> - <authorinitials>hjk</authorinitials> - <revremark>Added name attributes in mem and portio sysfs directories. - </revremark> - </revision> - <revision> - <revnumber>0.7</revnumber> - <date>2008-12-23</date> - <authorinitials>hjk</authorinitials> - <revremark>Added generic platform drivers and offset attribute.</revremark> - </revision> - <revision> - <revnumber>0.6</revnumber> - <date>2008-12-05</date> - <authorinitials>hjk</authorinitials> - <revremark>Added description of portio sysfs attributes.</revremark> - </revision> - <revision> - <revnumber>0.5</revnumber> - <date>2008-05-22</date> - <authorinitials>hjk</authorinitials> - <revremark>Added description of write() function.</revremark> - </revision> - <revision> - <revnumber>0.4</revnumber> - <date>2007-11-26</date> - <authorinitials>hjk</authorinitials> - <revremark>Removed section about uio_dummy.</revremark> - </revision> - <revision> - <revnumber>0.3</revnumber> - <date>2007-04-29</date> - <authorinitials>hjk</authorinitials> - <revremark>Added section about userspace drivers.</revremark> - </revision> - <revision> - <revnumber>0.2</revnumber> - <date>2007-02-13</date> - <authorinitials>hjk</authorinitials> - <revremark>Update after multiple mappings were added.</revremark> - </revision> - <revision> - <revnumber>0.1</revnumber> - <date>2006-12-11</date> - <authorinitials>hjk</authorinitials> - <revremark>First draft.</revremark> - </revision> -</revhistory> -</bookinfo> - -<chapter id="aboutthisdoc"> -<?dbhtml filename="aboutthis.html"?> -<title>About this document</title> - -<sect1 id="translations"> -<?dbhtml filename="translations.html"?> -<title>Translations</title> - -<para>If you know of any translations for this document, or you are -interested in translating it, please email me -<email>hjk@hansjkoch.de</email>. -</para> -</sect1> - -<sect1 id="preface"> -<title>Preface</title> - <para> - For many types of devices, creating a Linux kernel driver is - overkill. All that is really needed is some way to handle an - interrupt and provide access to the memory space of the - device. The logic of controlling the device does not - necessarily have to be within the kernel, as the device does - not need to take advantage of any of other resources that the - kernel provides. One such common class of devices that are - like this are for industrial I/O cards. - </para> - <para> - To address this situation, the userspace I/O system (UIO) was - designed. For typical industrial I/O cards, only a very small - kernel module is needed. The main part of the driver will run in - user space. This simplifies development and reduces the risk of - serious bugs within a kernel module. - </para> - <para> - Please note that UIO is not an universal driver interface. Devices - that are already handled well by other kernel subsystems (like - networking or serial or USB) are no candidates for an UIO driver. - Hardware that is ideally suited for an UIO driver fulfills all of - the following: - </para> -<itemizedlist> -<listitem> - <para>The device has memory that can be mapped. The device can be - controlled completely by writing to this memory.</para> -</listitem> -<listitem> - <para>The device usually generates interrupts.</para> -</listitem> -<listitem> - <para>The device does not fit into one of the standard kernel - subsystems.</para> -</listitem> -</itemizedlist> -</sect1> - -<sect1 id="thanks"> -<title>Acknowledgments</title> - <para>I'd like to thank Thomas Gleixner and Benedikt Spranger of - Linutronix, who have not only written most of the UIO code, but also - helped greatly writing this HOWTO by giving me all kinds of background - information.</para> -</sect1> - -<sect1 id="feedback"> -<title>Feedback</title> - <para>Find something wrong with this document? (Or perhaps something - right?) I would love to hear from you. Please email me at - <email>hjk@hansjkoch.de</email>.</para> -</sect1> -</chapter> - -<chapter id="about"> -<?dbhtml filename="about.html"?> -<title>About UIO</title> - -<para>If you use UIO for your card's driver, here's what you get:</para> - -<itemizedlist> -<listitem> - <para>only one small kernel module to write and maintain.</para> -</listitem> -<listitem> - <para>develop the main part of your driver in user space, - with all the tools and libraries you're used to.</para> -</listitem> -<listitem> - <para>bugs in your driver won't crash the kernel.</para> -</listitem> -<listitem> - <para>updates of your driver can take place without recompiling - the kernel.</para> -</listitem> -</itemizedlist> - -<sect1 id="how_uio_works"> -<title>How UIO works</title> - <para> - Each UIO device is accessed through a device file and several - sysfs attribute files. The device file will be called - <filename>/dev/uio0</filename> for the first device, and - <filename>/dev/uio1</filename>, <filename>/dev/uio2</filename> - and so on for subsequent devices. - </para> - - <para><filename>/dev/uioX</filename> is used to access the - address space of the card. Just use - <function>mmap()</function> to access registers or RAM - locations of your card. - </para> - - <para> - Interrupts are handled by reading from - <filename>/dev/uioX</filename>. A blocking - <function>read()</function> from - <filename>/dev/uioX</filename> will return as soon as an - interrupt occurs. You can also use - <function>select()</function> on - <filename>/dev/uioX</filename> to wait for an interrupt. The - integer value read from <filename>/dev/uioX</filename> - represents the total interrupt count. You can use this number - to figure out if you missed some interrupts. - </para> - <para> - For some hardware that has more than one interrupt source internally, - but not separate IRQ mask and status registers, there might be - situations where userspace cannot determine what the interrupt source - was if the kernel handler disables them by writing to the chip's IRQ - register. In such a case, the kernel has to disable the IRQ completely - to leave the chip's register untouched. Now the userspace part can - determine the cause of the interrupt, but it cannot re-enable - interrupts. Another cornercase is chips where re-enabling interrupts - is a read-modify-write operation to a combined IRQ status/acknowledge - register. This would be racy if a new interrupt occurred - simultaneously. - </para> - <para> - To address these problems, UIO also implements a write() function. It - is normally not used and can be ignored for hardware that has only a - single interrupt source or has separate IRQ mask and status registers. - If you need it, however, a write to <filename>/dev/uioX</filename> - will call the <function>irqcontrol()</function> function implemented - by the driver. You have to write a 32-bit value that is usually either - 0 or 1 to disable or enable interrupts. If a driver does not implement - <function>irqcontrol()</function>, <function>write()</function> will - return with <varname>-ENOSYS</varname>. - </para> - - <para> - To handle interrupts properly, your custom kernel module can - provide its own interrupt handler. It will automatically be - called by the built-in handler. - </para> - - <para> - For cards that don't generate interrupts but need to be - polled, there is the possibility to set up a timer that - triggers the interrupt handler at configurable time intervals. - This interrupt simulation is done by calling - <function>uio_event_notify()</function> - from the timer's event handler. - </para> - - <para> - Each driver provides attributes that are used to read or write - variables. These attributes are accessible through sysfs - files. A custom kernel driver module can add its own - attributes to the device owned by the uio driver, but not added - to the UIO device itself at this time. This might change in the - future if it would be found to be useful. - </para> - - <para> - The following standard attributes are provided by the UIO - framework: - </para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: The name of your device. It is - recommended to use the name of your kernel module for this. - </para> -</listitem> -<listitem> - <para> - <filename>version</filename>: A version string defined by your - driver. This allows the user space part of your driver to deal - with different versions of the kernel module. - </para> -</listitem> -<listitem> - <para> - <filename>event</filename>: The total number of interrupts - handled by the driver since the last time the device node was - read. - </para> -</listitem> -</itemizedlist> -<para> - These attributes appear under the - <filename>/sys/class/uio/uioX</filename> directory. Please - note that this directory might be a symlink, and not a real - directory. Any userspace code that accesses it must be able - to handle this. -</para> -<para> - Each UIO device can make one or more memory regions available for - memory mapping. This is necessary because some industrial I/O cards - require access to more than one PCI memory region in a driver. -</para> -<para> - Each mapping has its own directory in sysfs, the first mapping - appears as <filename>/sys/class/uio/uioX/maps/map0/</filename>. - Subsequent mappings create directories <filename>map1/</filename>, - <filename>map2/</filename>, and so on. These directories will only - appear if the size of the mapping is not 0. -</para> -<para> - Each <filename>mapX/</filename> directory contains four read-only files - that show attributes of the memory: -</para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: A string identifier for this mapping. This - is optional, the string can be empty. Drivers can set this to make it - easier for userspace to find the correct mapping. - </para> -</listitem> -<listitem> - <para> - <filename>addr</filename>: The address of memory that can be mapped. - </para> -</listitem> -<listitem> - <para> - <filename>size</filename>: The size, in bytes, of the memory - pointed to by addr. - </para> -</listitem> -<listitem> - <para> - <filename>offset</filename>: The offset, in bytes, that has to be - added to the pointer returned by <function>mmap()</function> to get - to the actual device memory. This is important if the device's memory - is not page aligned. Remember that pointers returned by - <function>mmap()</function> are always page aligned, so it is good - style to always add this offset. - </para> -</listitem> -</itemizedlist> - -<para> - From userspace, the different mappings are distinguished by adjusting - the <varname>offset</varname> parameter of the - <function>mmap()</function> call. To map the memory of mapping N, you - have to use N times the page size as your offset: -</para> -<programlisting format="linespecific"> -offset = N * getpagesize(); -</programlisting> - -<para> - Sometimes there is hardware with memory-like regions that can not be - mapped with the technique described here, but there are still ways to - access them from userspace. The most common example are x86 ioports. - On x86 systems, userspace can access these ioports using - <function>ioperm()</function>, <function>iopl()</function>, - <function>inb()</function>, <function>outb()</function>, and similar - functions. -</para> -<para> - Since these ioport regions can not be mapped, they will not appear under - <filename>/sys/class/uio/uioX/maps/</filename> like the normal memory - described above. Without information about the port regions a hardware - has to offer, it becomes difficult for the userspace part of the - driver to find out which ports belong to which UIO device. -</para> -<para> - To address this situation, the new directory - <filename>/sys/class/uio/uioX/portio/</filename> was added. It only - exists if the driver wants to pass information about one or more port - regions to userspace. If that is the case, subdirectories named - <filename>port0</filename>, <filename>port1</filename>, and so on, - will appear underneath - <filename>/sys/class/uio/uioX/portio/</filename>. -</para> -<para> - Each <filename>portX/</filename> directory contains four read-only - files that show name, start, size, and type of the port region: -</para> -<itemizedlist> -<listitem> - <para> - <filename>name</filename>: A string identifier for this port region. - The string is optional and can be empty. Drivers can set it to make it - easier for userspace to find a certain port region. - </para> -</listitem> -<listitem> - <para> - <filename>start</filename>: The first port of this region. - </para> -</listitem> -<listitem> - <para> - <filename>size</filename>: The number of ports in this region. - </para> -</listitem> -<listitem> - <para> - <filename>porttype</filename>: A string describing the type of port. - </para> -</listitem> -</itemizedlist> - - -</sect1> -</chapter> - -<chapter id="custom_kernel_module" xreflabel="Writing your own kernel module"> -<?dbhtml filename="custom_kernel_module.html"?> -<title>Writing your own kernel module</title> - <para> - Please have a look at <filename>uio_cif.c</filename> as an - example. The following paragraphs explain the different - sections of this file. - </para> - -<sect1 id="uio_info"> -<title>struct uio_info</title> - <para> - This structure tells the framework the details of your driver, - Some of the members are required, others are optional. - </para> - -<itemizedlist> -<listitem><para> -<varname>const char *name</varname>: Required. The name of your driver as -it will appear in sysfs. I recommend using the name of your module for this. -</para></listitem> - -<listitem><para> -<varname>const char *version</varname>: Required. This string appears in -<filename>/sys/class/uio/uioX/version</filename>. -</para></listitem> - -<listitem><para> -<varname>struct uio_mem mem[ MAX_UIO_MAPS ]</varname>: Required if you -have memory that can be mapped with <function>mmap()</function>. For each -mapping you need to fill one of the <varname>uio_mem</varname> structures. -See the description below for details. -</para></listitem> - -<listitem><para> -<varname>struct uio_port port[ MAX_UIO_PORTS_REGIONS ]</varname>: Required -if you want to pass information about ioports to userspace. For each port -region you need to fill one of the <varname>uio_port</varname> structures. -See the description below for details. -</para></listitem> - -<listitem><para> -<varname>long irq</varname>: Required. If your hardware generates an -interrupt, it's your modules task to determine the irq number during -initialization. If you don't have a hardware generated interrupt but -want to trigger the interrupt handler in some other way, set -<varname>irq</varname> to <varname>UIO_IRQ_CUSTOM</varname>. -If you had no interrupt at all, you could set -<varname>irq</varname> to <varname>UIO_IRQ_NONE</varname>, though this -rarely makes sense. -</para></listitem> - -<listitem><para> -<varname>unsigned long irq_flags</varname>: Required if you've set -<varname>irq</varname> to a hardware interrupt number. The flags given -here will be used in the call to <function>request_irq()</function>. -</para></listitem> - -<listitem><para> -<varname>int (*mmap)(struct uio_info *info, struct vm_area_struct -*vma)</varname>: Optional. If you need a special -<function>mmap()</function> function, you can set it here. If this -pointer is not NULL, your <function>mmap()</function> will be called -instead of the built-in one. -</para></listitem> - -<listitem><para> -<varname>int (*open)(struct uio_info *info, struct inode *inode) -</varname>: Optional. You might want to have your own -<function>open()</function>, e.g. to enable interrupts only when your -device is actually used. -</para></listitem> - -<listitem><para> -<varname>int (*release)(struct uio_info *info, struct inode *inode) -</varname>: Optional. If you define your own -<function>open()</function>, you will probably also want a custom -<function>release()</function> function. -</para></listitem> - -<listitem><para> -<varname>int (*irqcontrol)(struct uio_info *info, s32 irq_on) -</varname>: Optional. If you need to be able to enable or disable -interrupts from userspace by writing to <filename>/dev/uioX</filename>, -you can implement this function. The parameter <varname>irq_on</varname> -will be 0 to disable interrupts and 1 to enable them. -</para></listitem> -</itemizedlist> - -<para> -Usually, your device will have one or more memory regions that can be mapped -to user space. For each region, you have to set up a -<varname>struct uio_mem</varname> in the <varname>mem[]</varname> array. -Here's a description of the fields of <varname>struct uio_mem</varname>: -</para> - -<itemizedlist> -<listitem><para> -<varname>const char *name</varname>: Optional. Set this to help identify -the memory region, it will show up in the corresponding sysfs node. -</para></listitem> - -<listitem><para> -<varname>int memtype</varname>: Required if the mapping is used. Set this to -<varname>UIO_MEM_PHYS</varname> if you you have physical memory on your -card to be mapped. Use <varname>UIO_MEM_LOGICAL</varname> for logical -memory (e.g. allocated with <function>kmalloc()</function>). There's also -<varname>UIO_MEM_VIRTUAL</varname> for virtual memory. -</para></listitem> - -<listitem><para> -<varname>phys_addr_t addr</varname>: Required if the mapping is used. -Fill in the address of your memory block. This address is the one that -appears in sysfs. -</para></listitem> - -<listitem><para> -<varname>resource_size_t size</varname>: Fill in the size of the -memory block that <varname>addr</varname> points to. If <varname>size</varname> -is zero, the mapping is considered unused. Note that you -<emphasis>must</emphasis> initialize <varname>size</varname> with zero for -all unused mappings. -</para></listitem> - -<listitem><para> -<varname>void *internal_addr</varname>: If you have to access this memory -region from within your kernel module, you will want to map it internally by -using something like <function>ioremap()</function>. Addresses -returned by this function cannot be mapped to user space, so you must not -store it in <varname>addr</varname>. Use <varname>internal_addr</varname> -instead to remember such an address. -</para></listitem> -</itemizedlist> - -<para> -Please do not touch the <varname>map</varname> element of -<varname>struct uio_mem</varname>! It is used by the UIO framework -to set up sysfs files for this mapping. Simply leave it alone. -</para> - -<para> -Sometimes, your device can have one or more port regions which can not be -mapped to userspace. But if there are other possibilities for userspace to -access these ports, it makes sense to make information about the ports -available in sysfs. For each region, you have to set up a -<varname>struct uio_port</varname> in the <varname>port[]</varname> array. -Here's a description of the fields of <varname>struct uio_port</varname>: -</para> - -<itemizedlist> -<listitem><para> -<varname>char *porttype</varname>: Required. Set this to one of the predefined -constants. Use <varname>UIO_PORT_X86</varname> for the ioports found in x86 -architectures. -</para></listitem> - -<listitem><para> -<varname>unsigned long start</varname>: Required if the port region is used. -Fill in the number of the first port of this region. -</para></listitem> - -<listitem><para> -<varname>unsigned long size</varname>: Fill in the number of ports in this -region. If <varname>size</varname> is zero, the region is considered unused. -Note that you <emphasis>must</emphasis> initialize <varname>size</varname> -with zero for all unused regions. -</para></listitem> -</itemizedlist> - -<para> -Please do not touch the <varname>portio</varname> element of -<varname>struct uio_port</varname>! It is used internally by the UIO -framework to set up sysfs files for this region. Simply leave it alone. -</para> - -</sect1> - -<sect1 id="adding_irq_handler"> -<title>Adding an interrupt handler</title> - <para> - What you need to do in your interrupt handler depends on your - hardware and on how you want to handle it. You should try to - keep the amount of code in your kernel interrupt handler low. - If your hardware requires no action that you - <emphasis>have</emphasis> to perform after each interrupt, - then your handler can be empty.</para> <para>If, on the other - hand, your hardware <emphasis>needs</emphasis> some action to - be performed after each interrupt, then you - <emphasis>must</emphasis> do it in your kernel module. Note - that you cannot rely on the userspace part of your driver. Your - userspace program can terminate at any time, possibly leaving - your hardware in a state where proper interrupt handling is - still required. - </para> - - <para> - There might also be applications where you want to read data - from your hardware at each interrupt and buffer it in a piece - of kernel memory you've allocated for that purpose. With this - technique you could avoid loss of data if your userspace - program misses an interrupt. - </para> - - <para> - A note on shared interrupts: Your driver should support - interrupt sharing whenever this is possible. It is possible if - and only if your driver can detect whether your hardware has - triggered the interrupt or not. This is usually done by looking - at an interrupt status register. If your driver sees that the - IRQ bit is actually set, it will perform its actions, and the - handler returns IRQ_HANDLED. If the driver detects that it was - not your hardware that caused the interrupt, it will do nothing - and return IRQ_NONE, allowing the kernel to call the next - possible interrupt handler. - </para> - - <para> - If you decide not to support shared interrupts, your card - won't work in computers with no free interrupts. As this - frequently happens on the PC platform, you can save yourself a - lot of trouble by supporting interrupt sharing. - </para> -</sect1> - -<sect1 id="using_uio_pdrv"> -<title>Using uio_pdrv for platform devices</title> - <para> - In many cases, UIO drivers for platform devices can be handled in a - generic way. In the same place where you define your - <varname>struct platform_device</varname>, you simply also implement - your interrupt handler and fill your - <varname>struct uio_info</varname>. A pointer to this - <varname>struct uio_info</varname> is then used as - <varname>platform_data</varname> for your platform device. - </para> - <para> - You also need to set up an array of <varname>struct resource</varname> - containing addresses and sizes of your memory mappings. This - information is passed to the driver using the - <varname>.resource</varname> and <varname>.num_resources</varname> - elements of <varname>struct platform_device</varname>. - </para> - <para> - You now have to set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_pdrv"</varname> to use the generic UIO platform device - driver. This driver will fill the <varname>mem[]</varname> array - according to the resources given, and register the device. - </para> - <para> - The advantage of this approach is that you only have to edit a file - you need to edit anyway. You do not have to create an extra driver. - </para> -</sect1> - -<sect1 id="using_uio_pdrv_genirq"> -<title>Using uio_pdrv_genirq for platform devices</title> - <para> - Especially in embedded devices, you frequently find chips where the - irq pin is tied to its own dedicated interrupt line. In such cases, - where you can be really sure the interrupt is not shared, we can take - the concept of <varname>uio_pdrv</varname> one step further and use a - generic interrupt handler. That's what - <varname>uio_pdrv_genirq</varname> does. - </para> - <para> - The setup for this driver is the same as described above for - <varname>uio_pdrv</varname>, except that you do not implement an - interrupt handler. The <varname>.handler</varname> element of - <varname>struct uio_info</varname> must remain - <varname>NULL</varname>. The <varname>.irq_flags</varname> element - must not contain <varname>IRQF_SHARED</varname>. - </para> - <para> - You will set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_pdrv_genirq"</varname> to use this driver. - </para> - <para> - The generic interrupt handler of <varname>uio_pdrv_genirq</varname> - will simply disable the interrupt line using - <function>disable_irq_nosync()</function>. After doing its work, - userspace can reenable the interrupt by writing 0x00000001 to the UIO - device file. The driver already implements an - <function>irq_control()</function> to make this possible, you must not - implement your own. - </para> - <para> - Using <varname>uio_pdrv_genirq</varname> not only saves a few lines of - interrupt handler code. You also do not need to know anything about - the chip's internal registers to create the kernel part of the driver. - All you need to know is the irq number of the pin the chip is - connected to. - </para> -</sect1> - -<sect1 id="using-uio_dmem_genirq"> -<title>Using uio_dmem_genirq for platform devices</title> - <para> - In addition to statically allocated memory ranges, they may also be - a desire to use dynamically allocated regions in a user space driver. - In particular, being able to access memory made available through the - dma-mapping API, may be particularly useful. The - <varname>uio_dmem_genirq</varname> driver provides a way to accomplish - this. - </para> - <para> - This driver is used in a similar manner to the - <varname>"uio_pdrv_genirq"</varname> driver with respect to interrupt - configuration and handling. - </para> - <para> - Set the <varname>.name</varname> element of - <varname>struct platform_device</varname> to - <varname>"uio_dmem_genirq"</varname> to use this driver. - </para> - <para> - When using this driver, fill in the <varname>.platform_data</varname> - element of <varname>struct platform_device</varname>, which is of type - <varname>struct uio_dmem_genirq_pdata</varname> and which contains the - following elements: - </para> - <itemizedlist> - <listitem><para><varname>struct uio_info uioinfo</varname>: The same - structure used as the <varname>uio_pdrv_genirq</varname> platform - data</para></listitem> - <listitem><para><varname>unsigned int *dynamic_region_sizes</varname>: - Pointer to list of sizes of dynamic memory regions to be mapped into - user space. - </para></listitem> - <listitem><para><varname>unsigned int num_dynamic_regions</varname>: - Number of elements in <varname>dynamic_region_sizes</varname> array. - </para></listitem> - </itemizedlist> - <para> - The dynamic regions defined in the platform data will be appended to - the <varname> mem[] </varname> array after the platform device - resources, which implies that the total number of static and dynamic - memory regions cannot exceed <varname>MAX_UIO_MAPS</varname>. - </para> - <para> - The dynamic memory regions will be allocated when the UIO device file, - <varname>/dev/uioX</varname> is opened. - Similar to static memory resources, the memory region information for - dynamic regions is then visible via sysfs at - <varname>/sys/class/uio/uioX/maps/mapY/*</varname>. - The dynamic memory regions will be freed when the UIO device file is - closed. When no processes are holding the device file open, the address - returned to userspace is ~0. - </para> -</sect1> - -</chapter> - -<chapter id="userspace_driver" xreflabel="Writing a driver in user space"> -<?dbhtml filename="userspace_driver.html"?> -<title>Writing a driver in userspace</title> - <para> - Once you have a working kernel module for your hardware, you can - write the userspace part of your driver. You don't need any special - libraries, your driver can be written in any reasonable language, - you can use floating point numbers and so on. In short, you can - use all the tools and libraries you'd normally use for writing a - userspace application. - </para> - -<sect1 id="getting_uio_information"> -<title>Getting information about your UIO device</title> - <para> - Information about all UIO devices is available in sysfs. The - first thing you should do in your driver is check - <varname>name</varname> and <varname>version</varname> to - make sure your talking to the right device and that its kernel - driver has the version you expect. - </para> - <para> - You should also make sure that the memory mapping you need - exists and has the size you expect. - </para> - <para> - There is a tool called <varname>lsuio</varname> that lists - UIO devices and their attributes. It is available here: - </para> - <para> - <ulink url="http://www.osadl.org/projects/downloads/UIO/user/"> - http://www.osadl.org/projects/downloads/UIO/user/</ulink> - </para> - <para> - With <varname>lsuio</varname> you can quickly check if your - kernel module is loaded and which attributes it exports. - Have a look at the manpage for details. - </para> - <para> - The source code of <varname>lsuio</varname> can serve as an - example for getting information about an UIO device. - The file <filename>uio_helper.c</filename> contains a lot of - functions you could use in your userspace driver code. - </para> -</sect1> - -<sect1 id="mmap_device_memory"> -<title>mmap() device memory</title> - <para> - After you made sure you've got the right device with the - memory mappings you need, all you have to do is to call - <function>mmap()</function> to map the device's memory - to userspace. - </para> - <para> - The parameter <varname>offset</varname> of the - <function>mmap()</function> call has a special meaning - for UIO devices: It is used to select which mapping of - your device you want to map. To map the memory of - mapping N, you have to use N times the page size as - your offset: - </para> -<programlisting format="linespecific"> - offset = N * getpagesize(); -</programlisting> - <para> - N starts from zero, so if you've got only one memory - range to map, set <varname>offset = 0</varname>. - A drawback of this technique is that memory is always - mapped beginning with its start address. - </para> -</sect1> - -<sect1 id="wait_for_interrupts"> -<title>Waiting for interrupts</title> - <para> - After you successfully mapped your devices memory, you - can access it like an ordinary array. Usually, you will - perform some initialization. After that, your hardware - starts working and will generate an interrupt as soon - as it's finished, has some data available, or needs your - attention because an error occurred. - </para> - <para> - <filename>/dev/uioX</filename> is a read-only file. A - <function>read()</function> will always block until an - interrupt occurs. There is only one legal value for the - <varname>count</varname> parameter of - <function>read()</function>, and that is the size of a - signed 32 bit integer (4). Any other value for - <varname>count</varname> causes <function>read()</function> - to fail. The signed 32 bit integer read is the interrupt - count of your device. If the value is one more than the value - you read the last time, everything is OK. If the difference - is greater than one, you missed interrupts. - </para> - <para> - You can also use <function>select()</function> on - <filename>/dev/uioX</filename>. - </para> -</sect1> - -</chapter> - -<chapter id="uio_pci_generic" xreflabel="Using Generic driver for PCI cards"> -<?dbhtml filename="uio_pci_generic.html"?> -<title>Generic PCI UIO driver</title> - <para> - The generic driver is a kernel module named uio_pci_generic. - It can work with any device compliant to PCI 2.3 (circa 2002) and - any compliant PCI Express device. Using this, you only need to - write the userspace driver, removing the need to write - a hardware-specific kernel module. - </para> - -<sect1 id="uio_pci_generic_binding"> -<title>Making the driver recognize the device</title> - <para> -Since the driver does not declare any device ids, it will not get loaded -automatically and will not automatically bind to any devices, you must load it -and allocate id to the driver yourself. For example: - <programlisting> - modprobe uio_pci_generic - echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id - </programlisting> - </para> - <para> -If there already is a hardware specific kernel driver for your device, the -generic driver still won't bind to it, in this case if you want to use the -generic driver (why would you?) you'll have to manually unbind the hardware -specific driver and bind the generic driver, like this: - <programlisting> - echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind - echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind - </programlisting> - </para> - <para> -You can verify that the device has been bound to the driver -by looking for it in sysfs, for example like the following: - <programlisting> - ls -l /sys/bus/pci/devices/0000:00:19.0/driver - </programlisting> -Which if successful should print - <programlisting> - .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic - </programlisting> -Note that the generic driver will not bind to old PCI 2.2 devices. -If binding the device failed, run the following command: - <programlisting> - dmesg - </programlisting> -and look in the output for failure reasons - </para> -</sect1> - -<sect1 id="uio_pci_generic_internals"> -<title>Things to know about uio_pci_generic</title> - <para> -Interrupts are handled using the Interrupt Disable bit in the PCI command -register and Interrupt Status bit in the PCI status register. All devices -compliant to PCI 2.3 (circa 2002) and all compliant PCI Express devices should -support these bits. uio_pci_generic detects this support, and won't bind to -devices which do not support the Interrupt Disable Bit in the command register. - </para> - <para> -On each interrupt, uio_pci_generic sets the Interrupt Disable bit. -This prevents the device from generating further interrupts -until the bit is cleared. The userspace driver should clear this -bit before blocking and waiting for more interrupts. - </para> -</sect1> -<sect1 id="uio_pci_generic_userspace"> -<title>Writing userspace driver using uio_pci_generic</title> - <para> -Userspace driver can use pci sysfs interface, or the -libpci libray that wraps it, to talk to the device and to -re-enable interrupts by writing to the command register. - </para> -</sect1> -<sect1 id="uio_pci_generic_example"> -<title>Example code using uio_pci_generic</title> - <para> -Here is some sample userspace driver code using uio_pci_generic: -<programlisting> -#include <stdlib.h> -#include <stdio.h> -#include <unistd.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <fcntl.h> -#include <errno.h> - -int main() -{ - int uiofd; - int configfd; - int err; - int i; - unsigned icount; - unsigned char command_high; - - uiofd = open("/dev/uio0", O_RDONLY); - if (uiofd < 0) { - perror("uio open:"); - return errno; - } - configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); - if (configfd < 0) { - perror("config open:"); - return errno; - } - - /* Read and cache command value */ - err = pread(configfd, &command_high, 1, 5); - if (err != 1) { - perror("command config read:"); - return errno; - } - command_high &= ~0x4; - - for(i = 0;; ++i) { - /* Print out a message, for debugging. */ - if (i == 0) - fprintf(stderr, "Started uio test driver.\n"); - else - fprintf(stderr, "Interrupts: %d\n", icount); - - /****************************************/ - /* Here we got an interrupt from the - device. Do something to it. */ - /****************************************/ - - /* Re-enable interrupts. */ - err = pwrite(configfd, &command_high, 1, 5); - if (err != 1) { - perror("config write:"); - break; - } - - /* Wait for next interrupt. */ - err = read(uiofd, &icount, 4); - if (err != 4) { - perror("uio read:"); - break; - } - - } - return errno; -} - -</programlisting> - </para> -</sect1> - -</chapter> - -<chapter id="uio_hv_generic" xreflabel="Using Generic driver for Hyper-V VMBUS"> -<?dbhtml filename="uio_hv_generic.html"?> -<title>Generic Hyper-V UIO driver</title> - <para> - The generic driver is a kernel module named uio_hv_generic. - It supports devices on the Hyper-V VMBus similar to uio_pci_generic - on PCI bus. - </para> - -<sect1 id="uio_hv_generic_binding"> -<title>Making the driver recognize the device</title> - <para> -Since the driver does not declare any device GUID's, it will not get loaded -automatically and will not automatically bind to any devices, you must load it -and allocate id to the driver yourself. For example, to use the network device -GUID: - <programlisting> - modprobe uio_hv_generic - echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id - </programlisting> - </para> - <para> -If there already is a hardware specific kernel driver for the device, the -generic driver still won't bind to it, in this case if you want to use the -generic driver (why would you?) you'll have to manually unbind the hardware -specific driver and bind the generic driver, like this: - <programlisting> - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind - echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind - </programlisting> - </para> - <para> -You can verify that the device has been bound to the driver -by looking for it in sysfs, for example like the following: - <programlisting> - ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver - </programlisting> -Which if successful should print - <programlisting> - .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic - </programlisting> - </para> -</sect1> - -<sect1 id="uio_hv_generic_internals"> -<title>Things to know about uio_hv_generic</title> - <para> -On each interrupt, uio_hv_generic sets the Interrupt Disable bit. -This prevents the device from generating further interrupts -until the bit is cleared. The userspace driver should clear this -bit before blocking and waiting for more interrupts. - </para> -</sect1> -</chapter> - -<appendix id="app1"> -<title>Further information</title> -<itemizedlist> - <listitem><para> - <ulink url="http://www.osadl.org"> - OSADL homepage.</ulink> - </para></listitem> - <listitem><para> - <ulink url="http://www.linutronix.de"> - Linutronix homepage.</ulink> - </para></listitem> -</itemizedlist> -</appendix> - -</book> diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.txt index 72292308d0f5..6962cab997ef 100644 --- a/Documentation/IPMI.txt +++ b/Documentation/IPMI.txt @@ -257,7 +257,7 @@ and tell you when they come and go. Creating the User -To user the message handler, you must first create a user using +To use the message handler, you must first create a user using ipmi_create_user. The interface number specifies which SMI you want to connect to, and you must supply callback functions to be called when data comes in. The callback function can run at interrupt level, diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 707c65337ebf..bcf529f6cf9b 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -43,7 +43,7 @@ ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* -loop_cmd = $(echo-cmd) $(cmd_$(1)) +loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # $2 sphinx builder e.g. "html" # $3 name of the build subfolder / e.g. "media", used as: @@ -54,7 +54,8 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) # 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 $2;\ + cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \ + PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(SPHINXBUILD) \ -b $2 \ @@ -63,13 +64,16 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \ $(ALLSPHINXOPTS) \ $(abspath $(srctree)/$(src)/$5) \ - $(abspath $(BUILDDIR)/$3/$4); + $(abspath $(BUILDDIR)/$3/$4) htmldocs: - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) + +linkcheckdocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var))) latexdocs: - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -80,27 +84,34 @@ pdfdocs: else # HAVE_PDFLATEX pdfdocs: latexdocs - $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;) endif # HAVE_PDFLATEX epubdocs: - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) + @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) + +endif # HAVE_SPHINX + +# The following targets are independent of HAVE_SPHINX, and the rules should +# work or silently pass without Sphinx. # no-ops for the Sphinx toolchain sgmldocs: + @: psdocs: + @: mandocs: + @: installmandocs: + @: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean - -endif # HAVE_SPHINX + $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean dochelp: @echo ' Linux kernel internal documentation in different formats (Sphinx):' @@ -109,6 +120,7 @@ dochelp: @echo ' pdfdocs - PDF' @echo ' epubdocs - EPUB' @echo ' xmldocs - XML' + @echo ' linkcheckdocs - check for broken external links (will connect to external hosts)' @echo ' cleandocs - clean all generated files' @echo @echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2' diff --git a/Documentation/PCI/MSI-HOWTO.txt b/Documentation/PCI/MSI-HOWTO.txt index cd9c9f6a7cd9..1e37138027a3 100644 --- a/Documentation/PCI/MSI-HOWTO.txt +++ b/Documentation/PCI/MSI-HOWTO.txt @@ -162,8 +162,6 @@ The following old APIs to enable and disable MSI or MSI-X interrupts should not be used in new code: pci_enable_msi() /* deprecated */ - pci_enable_msi_range() /* deprecated */ - pci_enable_msi_exact() /* deprecated */ pci_disable_msi() /* deprecated */ pci_enable_msix_range() /* deprecated */ pci_enable_msix_exact() /* deprecated */ @@ -268,5 +266,5 @@ or disabled (0). If 0 is found in any of the msi_bus files belonging to bridges between the PCI root and the device, MSIs are disabled. It is also worth checking the device driver to see whether it supports MSIs. -For example, it may contain calls to pci_enable_msi_range() or -pci_enable_msix_range(). +For example, it may contain calls to pci_irq_alloc_vectors() with the +PCI_IRQ_MSI or PCI_IRQ_MSIX flags. diff --git a/Documentation/PCI/PCIEBUS-HOWTO.txt b/Documentation/PCI/PCIEBUS-HOWTO.txt index 6bd5f372adec..15f0bb3b5045 100644 --- a/Documentation/PCI/PCIEBUS-HOWTO.txt +++ b/Documentation/PCI/PCIEBUS-HOWTO.txt @@ -161,21 +161,13 @@ Since all service drivers of a PCI-PCI Bridge Port device are allowed to run simultaneously, below lists a few of possible resource conflicts with proposed solutions. -6.1 MSI Vector Resource - -The MSI capability structure enables a device software driver to call -pci_enable_msi to request MSI based interrupts. Once MSI interrupts -are enabled on a device, it stays in this mode until a device driver -calls pci_disable_msi to disable MSI interrupts and revert back to -INTx emulation mode. Since service drivers of the same PCI-PCI Bridge -port share the same physical device, if an individual service driver -calls pci_enable_msi/pci_disable_msi it may result unpredictable -behavior. For example, two service drivers run simultaneously on the -same physical Root Port. Both service drivers call pci_enable_msi to -request MSI based interrupts. A service driver may not know whether -any other service drivers have run on this Root Port. If either one -of them calls pci_disable_msi, it puts the other service driver -in a wrong interrupt mode. +6.1 MSI and MSI-X Vector Resource + +Once MSI or MSI-X interrupts are enabled on a device, it stays in this +mode until they are disabled again. Since service drivers of the same +PCI-PCI Bridge port share the same physical device, if an individual +service driver enables or disables MSI/MSI-X mode it may result +unpredictable behavior. To avoid this situation all service drivers are not permitted to switch interrupt mode on its device. The PCI Express Port Bus driver @@ -187,17 +179,6 @@ driver. Service drivers should use (struct pcie_device*)dev->irq to call request_irq/free_irq. In addition, the interrupt mode is stored in the field interrupt_mode of struct pcie_device. -6.2 MSI-X Vector Resources - -Similar to the MSI a device driver for an MSI-X capable device can -call pci_enable_msix to request MSI-X interrupts. All service drivers -are not permitted to switch interrupt mode on its device. The PCI -Express Port Bus driver is responsible for determining the interrupt -mode and this should be transparent to service drivers. Any attempt -by service driver to call pci_enable_msix/pci_disable_msix may -result unpredictable behavior. Service drivers should use -(struct pcie_device*)dev->irq and call request_irq/free_irq. - 6.3 PCI Memory/IO Mapped Regions Service drivers for PCI Express Power Management (PME), Advanced diff --git a/Documentation/PCI/pci-error-recovery.txt b/Documentation/PCI/pci-error-recovery.txt index ac26869c7db4..da3b2176d5da 100644 --- a/Documentation/PCI/pci-error-recovery.txt +++ b/Documentation/PCI/pci-error-recovery.txt @@ -78,7 +78,6 @@ struct pci_error_handlers { int (*error_detected)(struct pci_dev *dev, enum pci_channel_state); int (*mmio_enabled)(struct pci_dev *dev); - int (*link_reset)(struct pci_dev *dev); int (*slot_reset)(struct pci_dev *dev); void (*resume)(struct pci_dev *dev); }; @@ -104,8 +103,7 @@ if it implements any, it must implement error_detected(). If a callback is not implemented, the corresponding feature is considered unsupported. For example, if mmio_enabled() and resume() aren't there, then it is assumed that the driver is not doing any direct recovery and requires -a slot reset. If link_reset() is not implemented, the card is assumed to -not care about link resets. Typically a driver will want to know about +a slot reset. Typically a driver will want to know about a slot_reset(). The actual steps taken by a platform to recover from a PCI error @@ -232,25 +230,9 @@ proceeds to STEP 4 (Slot Reset) STEP 3: Link Reset ------------------ -The platform resets the link, and then calls the link_reset() callback -on all affected device drivers. This is a PCI-Express specific state +The platform resets the link. This is a PCI-Express specific step and is done whenever a non-fatal error has been detected that can be -"solved" by resetting the link. This call informs the driver of the -reset and the driver should check to see if the device appears to be -in working condition. - -The driver is not supposed to restart normal driver I/O operations -at this point. It should limit itself to "probing" the device to -check its recoverability status. If all is right, then the platform -will call resume() once all drivers have ack'd link_reset(). - - Result codes: - (identical to STEP 3 (MMIO Enabled) - -The platform then proceeds to either STEP 4 (Slot Reset) or STEP 5 -(Resume Operations). - ->>> The current powerpc implementation does not implement this callback. +"solved" by resetting the link. STEP 4: Slot Reset ------------------ diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt index 77f49dc5be23..611a75e4366e 100644 --- a/Documentation/PCI/pci.txt +++ b/Documentation/PCI/pci.txt @@ -382,18 +382,18 @@ The fundamental difference between MSI and MSI-X is how multiple "vectors" get allocated. MSI requires contiguous blocks of vectors while MSI-X can allocate several individual ones. -MSI capability can be enabled by calling pci_enable_msi() or -pci_enable_msix() before calling request_irq(). This causes -the PCI support to program CPU vector data into the PCI device -capability registers. - -If your PCI device supports both, try to enable MSI-X first. -Only one can be enabled at a time. Many architectures, chip-sets, -or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix -will fail. This is important to note since many drivers have -two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs. -They choose which handler to register with request_irq() based on the -return value from pci_enable_msi/msix(). +MSI capability can be enabled by calling pci_alloc_irq_vectors() with the +PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This +causes the PCI support to program CPU vector data into the PCI device +capability registers. Many architectures, chip-sets, or BIOSes do NOT +support MSI or MSI-X and a call to pci_alloc_irq_vectors with just +the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always +specify PCI_IRQ_LEGACY as well. + +Drivers that have different interrupt handlers for MSI/MSI-X and +legacy INTx should chose the right one based on the msi_enabled +and msix_enabled flags in the pci_dev structure after calling +pci_alloc_irq_vectors. There are (at least) two really good reasons for using MSI: 1) MSI is an exclusive interrupt vector by definition. diff --git a/Documentation/PCI/pcieaer-howto.txt b/Documentation/PCI/pcieaer-howto.txt index ea8cafba255c..acd0dddd6bb8 100644 --- a/Documentation/PCI/pcieaer-howto.txt +++ b/Documentation/PCI/pcieaer-howto.txt @@ -256,7 +256,7 @@ After reboot with new kernel or insert the module, a device file named Then, you need a user space tool named aer-inject, which can be gotten from: - http://www.kernel.org/pub/linux/utils/pci/aer-inject/ + https://git.kernel.org/cgit/linux/kernel/git/gong.chen/aer-inject.git/ More information about aer-inject can be found in the document comes with its source code. diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt index 5f55373dd53b..a3f598e141f2 100644 --- a/Documentation/acpi/method-customizing.txt +++ b/Documentation/acpi/method-customizing.txt @@ -57,7 +57,7 @@ Note: To get the ACPI debug object output (Store (AAAA, Debug)), 3. undo your changes The "undo" operation is not supported for a new inserted method right now, i.e. we can not remove a method currently. - For an overrided method, in order to undo your changes, please + For an overridden method, in order to undo your changes, please save a copy of the method original ASL code in step c) section 1, and redo step c) ~ g) to override the method with the original one. diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt index c2505eefc878..0aba14c8f459 100644 --- a/Documentation/acpi/method-tracing.txt +++ b/Documentation/acpi/method-tracing.txt @@ -152,7 +152,7 @@ tracing facility. Users can enable/disable this debug tracing feature by executing the following command: # echo string > /sys/module/acpi/parameters/trace_state - Where "string" should be one of the followings: + Where "string" should be one of the following: "disable" Disable the method tracing feature. "enable" diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 1b6dfb2b3adb..697a00ccec25 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -17,7 +17,7 @@ What is Linux? loading, shared copy-on-write executables, proper memory management, and multistack networking including IPv4 and IPv6. - It is distributed under the GNU General Public License - see the + It is distributed under the GNU General Public License v2 - see the accompanying COPYING file for more details. On what hardware does it run? @@ -236,7 +236,7 @@ Configuring the kernel - Having unnecessary drivers will make the kernel bigger, and can under some circumstances lead to problems: probing for a - nonexistent controller card may confuse your other controllers + nonexistent controller card may confuse your other controllers. - A kernel with math-emulation compiled in will still use the coprocessor if one is present: the math emulation will just diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index 88adcfdf5b2b..12278a926370 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -93,9 +93,9 @@ Command Language Reference At the lexical level, a command comprises a sequence of words separated by spaces or tabs. So these are all equivalent:: - nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > <debugfs>/dynamic_debug/control - nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > + nullarbor:~ # echo -n ' file svcsock.c line 1603 +p ' > <debugfs>/dynamic_debug/control nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > <debugfs>/dynamic_debug/control diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 14ffef04113c..0464a41cbf3b 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -653,6 +653,9 @@ cpuidle.off=1 [CPU_IDLE] disable the cpuidle sub-system + cpufreq.off=1 [CPU_FREQ] + disable the cpufreq sub-system + cpu_init_udelay=N [X86] Delay for N microsec between assert and de-assert of APIC INIT to start processors. This delay occurs @@ -957,6 +960,12 @@ serial port must already be setup and configured. Options are not yet supported. + lantiq,<addr> + Start an early, polled-mode console on a lantiq serial + (lqasc) port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + lpuart,<addr> lpuart32,<addr> Use early console provided by Freescale LP UART driver @@ -970,9 +979,10 @@ address. The serial port must already be setup and configured. Options are not yet supported. - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k,S390] earlyprintk=vga earlyprintk=efi + earlyprintk=sclp earlyprintk=xen earlyprintk=serial[,ttySn[,baudrate]] earlyprintk=serial[,0x...[,baudrate]] @@ -1007,6 +1017,8 @@ The xen output can only be used by Xen PV guests. + The sclp output can only be used on s390. + edac_report= [HW,EDAC] Control how to report EDAC event Format: {"on" | "off" | "force"} on: enable EDAC to report H/W event. May be overridden @@ -1174,6 +1186,12 @@ functions that can be changed at run time by the set_graph_notrace file in the debugfs tracing directory. + ftrace_graph_max_depth=<uint> + [FTRACE] Used with the function graph tracer. This is + the max depth it will trace into a function. This value + can be changed at run time by the max_graph_depth file + in the tracefs tracing directory. default: 0 (no limit) + gamecon.map[2|3]= [HW,JOY] Multisystem joystick and NES/SNES/PSX pad support via parallel port (up to 5 devices per port) @@ -1192,6 +1210,10 @@ When zero, profiling data is discarded and associated debugfs files are removed at module unload time. + goldfish [X86] Enable the goldfish android emulator platform. + Don't use this when you are not running on the + android emulator + gpt [EFI] Forces disk with valid GPT signature but invalid Protective MBR to be treated as GPT. If the primary GPT is corrupted, it enables the backup/alternate @@ -3681,6 +3703,14 @@ last alloc / free. For more information see Documentation/vm/slub.txt. + slub_memcg_sysfs= [MM, SLUB] + Determines whether to enable sysfs directories for + memory cgroup sub-caches. 1 to enable, 0 to disable. + The default is determined by CONFIG_SLUB_MEMCG_SYSFS_ON. + Enabling this can lead to a very high number of debug + directories and files being created under + /sys/kernel/slub. + slub_max_order= [MM, SLUB] Determines the maximum allowed order for slabs. A high setting may cause OOMs due to memory diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst index e449fb5f277c..1e61bf50595c 100644 --- a/Documentation/admin-guide/md.rst +++ b/Documentation/admin-guide/md.rst @@ -725,3 +725,8 @@ These currently include: to 1. Setting this to 0 disables bypass accounting and requires preread stripes to wait until all full-width stripe- writes are complete. Valid values are 0 to stripe_cache_size. + + journal_mode (currently raid5 only) + The cache mode for raid5. raid5 could include an extra disk for + caching. The mode can be "write-throuth" and "write-back". The + default is "write-through". diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst index 9939348bd4a3..1b90c6f00a92 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/ras.rst @@ -81,7 +81,7 @@ That defines some categories of errors: still run, eventually replacing the affected hardware by a hot spare, if available. - Also, when an error happens on an userspace process, it is also possible to + Also, when an error happens on a userspace process, it is also possible to kill such process and let userspace restart it. The mechanism for handling non-fatal errors is usually complex and may diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi/README index cd0243302bc1..d7b1f016bd62 100644 --- a/Documentation/arm/sunxi/README +++ b/Documentation/arm/sunxi/README @@ -63,10 +63,18 @@ SunXi family + User Manual http://dl.linux-sunxi.org/A33/A33%20user%20manual%20release%201.1.pdf + - Allwinner H2+ (sun8i) + + No document available now, but is known to be working properly with + H3 drivers and memory map. + - Allwinner H3 (sun8i) + Datasheet http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf + - Allwinner V3s (sun8i) + + Datasheet + http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf + * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs - Allwinner A80 + Datasheet diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt new file mode 100644 index 000000000000..61ca21ebef1a --- /dev/null +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -0,0 +1,240 @@ + ARM64 CPU Feature Registers + =========================== + +Author: Suzuki K Poulose <suzuki.poulose@arm.com> + + +This file describes the ABI for exporting the AArch64 CPU ID/feature +registers to userspace. The availability of this ABI is advertised +via the HWCAP_CPUID in HWCAPs. + +1. Motivation +--------------- + +The ARM architecture defines a set of feature registers, which describe +the capabilities of the CPU/system. Access to these system registers is +restricted from EL0 and there is no reliable way for an application to +extract this information to make better decisions at runtime. There is +limited information available to the application via HWCAPs, however +there are some issues with their usage. + + a) Any change to the HWCAPs requires an update to userspace (e.g libc) + to detect the new changes, which can take a long time to appear in + distributions. Exposing the registers allows applications to get the + information without requiring updates to the toolchains. + + b) Access to HWCAPs is sometimes limited (e.g prior to libc, or + when ld is initialised at startup time). + + c) HWCAPs cannot represent non-boolean information effectively. The + architecture defines a canonical format for representing features + in the ID registers; this is well defined and is capable of + representing all valid architecture variations. + + +2. Requirements +----------------- + + a) Safety : + Applications should be able to use the information provided by the + infrastructure to run safely across the system. This has greater + implications on a system with heterogeneous CPUs. + The infrastructure exports a value that is safe across all the + available CPU on the system. + + e.g, If at least one CPU doesn't implement CRC32 instructions, while + others do, we should report that the CRC32 is not implemented. + Otherwise an application could crash when scheduled on the CPU + which doesn't support CRC32. + + b) Security : + Applications should only be able to receive information that is + relevant to the normal operation in userspace. Hence, some of the + fields are masked out(i.e, made invisible) and their values are set to + indicate the feature is 'not supported'. See Section 4 for the list + of visible features. Also, the kernel may manipulate the fields + based on what it supports. e.g, If FP is not supported by the + kernel, the values could indicate that the FP is not available + (even when the CPU provides it). + + c) Implementation Defined Features + The infrastructure doesn't expose any register which is + IMPLEMENTATION DEFINED as per ARMv8-A Architecture. + + d) CPU Identification : + MIDR_EL1 is exposed to help identify the processor. On a + heterogeneous system, this could be racy (just like getcpu()). The + process could be migrated to another CPU by the time it uses the + register value, unless the CPU affinity is set. Hence, there is no + guarantee that the value reflects the processor that it is + currently executing on. The REVIDR is not exposed due to this + constraint, as REVIDR makes sense only in conjunction with the + MIDR. Alternately, MIDR_EL1 and REVIDR_EL1 are exposed via sysfs + at: + + /sys/devices/system/cpu/cpu$ID/regs/identification/ + \- midr + \- revidr + +3. Implementation +-------------------- + +The infrastructure is built on the emulation of the 'MRS' instruction. +Accessing a restricted system register from an application generates an +exception and ends up in SIGILL being delivered to the process. +The infrastructure hooks into the exception handler and emulates the +operation if the source belongs to the supported system register space. + +The infrastructure emulates only the following system register space: + Op0=3, Op1=0, CRn=0, CRm=0,4,5,6,7 + +(See Table C5-6 'System instruction encodings for non-Debug System +register accesses' in ARMv8 ARM DDI 0487A.h, for the list of +registers). + +The following rules are applied to the value returned by the +infrastructure: + + a) The value of an 'IMPLEMENTATION DEFINED' field is set to 0. + b) The value of a reserved field is populated with the reserved + value as defined by the architecture. + c) The value of a 'visible' field holds the system wide safe value + for the particular feature (except for MIDR_EL1, see section 4). + d) All other fields (i.e, invisible fields) are set to indicate + the feature is missing (as defined by the architecture). + +4. List of registers with visible features +------------------------------------------- + + 1) ID_AA64ISAR0_EL1 - Instruction Set Attribute Register 0 + x--------------------------------------------------x + | Name | bits | visible | + |--------------------------------------------------| + | RES0 | [63-32] | n | + |--------------------------------------------------| + | RDM | [31-28] | y | + |--------------------------------------------------| + | ATOMICS | [23-20] | y | + |--------------------------------------------------| + | CRC32 | [19-16] | y | + |--------------------------------------------------| + | SHA2 | [15-12] | y | + |--------------------------------------------------| + | SHA1 | [11-8] | y | + |--------------------------------------------------| + | AES | [7-4] | y | + |--------------------------------------------------| + | RES0 | [3-0] | n | + x--------------------------------------------------x + + + 2) ID_AA64PFR0_EL1 - Processor Feature Register 0 + x--------------------------------------------------x + | Name | bits | visible | + |--------------------------------------------------| + | RES0 | [63-28] | n | + |--------------------------------------------------| + | GIC | [27-24] | n | + |--------------------------------------------------| + | AdvSIMD | [23-20] | y | + |--------------------------------------------------| + | FP | [19-16] | y | + |--------------------------------------------------| + | EL3 | [15-12] | n | + |--------------------------------------------------| + | EL2 | [11-8] | n | + |--------------------------------------------------| + | EL1 | [7-4] | n | + |--------------------------------------------------| + | EL0 | [3-0] | n | + x--------------------------------------------------x + + + 3) MIDR_EL1 - Main ID Register + x--------------------------------------------------x + | Name | bits | visible | + |--------------------------------------------------| + | Implementer | [31-24] | y | + |--------------------------------------------------| + | Variant | [23-20] | y | + |--------------------------------------------------| + | Architecture | [19-16] | y | + |--------------------------------------------------| + | PartNum | [15-4] | y | + |--------------------------------------------------| + | Revision | [3-0] | y | + x--------------------------------------------------x + + NOTE: The 'visible' fields of MIDR_EL1 will contain the value + as available on the CPU where it is fetched and is not a system + wide safe value. + +Appendix I: Example +--------------------------- + +/* + * Sample program to demonstrate the MRS emulation ABI. + * + * Copyright (C) 2015-2016, ARM Ltd + * + * Author: Suzuki K Poulose <suzuki.poulose@arm.com> + * + * 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. + * 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. + */ + +#include <asm/hwcap.h> +#include <stdio.h> +#include <sys/auxv.h> + +#define get_cpu_ftr(id) ({ \ + unsigned long __val; \ + asm("mrs %0, "#id : "=r" (__val)); \ + printf("%-20s: 0x%016lx\n", #id, __val); \ + }) + +int main(void) +{ + + if (!(getauxval(AT_HWCAP) & HWCAP_CPUID)) { + fputs("CPUID registers unavailable\n", stderr); + return 1; + } + + get_cpu_ftr(ID_AA64ISAR0_EL1); + get_cpu_ftr(ID_AA64ISAR1_EL1); + get_cpu_ftr(ID_AA64MMFR0_EL1); + get_cpu_ftr(ID_AA64MMFR1_EL1); + get_cpu_ftr(ID_AA64PFR0_EL1); + get_cpu_ftr(ID_AA64PFR1_EL1); + get_cpu_ftr(ID_AA64DFR0_EL1); + get_cpu_ftr(ID_AA64DFR1_EL1); + + get_cpu_ftr(MIDR_EL1); + get_cpu_ftr(MPIDR_EL1); + get_cpu_ftr(REVIDR_EL1); + +#if 0 + /* Unexposed register access causes SIGILL */ + get_cpu_ftr(ID_MMFR0_EL1); +#endif + + return 0; +} + + + diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index 405da11fc3e4..2f66683500b8 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -42,24 +42,30 @@ file acts as a registry of software workarounds in the Linux Kernel and will be updated when new workarounds are committed and backported to stable kernels. -| Implementor | Component | Erratum ID | Kconfig | -+----------------+-----------------+-----------------+-------------------------+ -| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | -| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | -| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | -| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | -| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | -| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | -| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | -| ARM | Cortex-A57 | #852523 | N/A | -| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | -| ARM | Cortex-A72 | #853709 | N/A | -| ARM | MMU-500 | #841119,#826419 | N/A | -| | | | | -| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | -| Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 | -| 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 | +| Implementor | Component | Erratum ID | Kconfig | ++----------------+-----------------+-----------------+-----------------------------+ +| ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | +| ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | +| ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | +| ARM | Cortex-A53 | #819472 | ARM64_ERRATUM_819472 | +| ARM | Cortex-A53 | #845719 | ARM64_ERRATUM_845719 | +| ARM | Cortex-A53 | #843419 | ARM64_ERRATUM_843419 | +| ARM | Cortex-A57 | #832075 | ARM64_ERRATUM_832075 | +| ARM | Cortex-A57 | #852523 | N/A | +| ARM | Cortex-A57 | #834220 | ARM64_ERRATUM_834220 | +| ARM | Cortex-A72 | #853709 | N/A | +| ARM | MMU-500 | #841119,#826419 | N/A | +| | | | | +| Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | +| Cavium | ThunderX ITS | #23144 | CAVIUM_ERRATUM_23144 | +| 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 | +| | | | | +| Hisilicon | Hip0{5,6,7} | #161010101 | HISILICON_ERRATUM_161010101 | +| | | | | +| Qualcomm Tech. | Falkor v1 | E1003 | QCOM_FALKOR_ERRATUM_1003 | +| Qualcomm Tech. | Falkor v1 | E1009 | QCOM_FALKOR_ERRATUM_1009 | +| Qualcomm Tech. | QDF2400 ITS | E0065 | QCOM_QDF2400_ERRATUM_0065 | diff --git a/Documentation/block/pr.txt b/Documentation/block/pr.txt index d3eb1ca65051..ac9b8e70e64b 100644 --- a/Documentation/block/pr.txt +++ b/Documentation/block/pr.txt @@ -90,7 +90,7 @@ and thus removes any access restriction implied by it. 4. IOC_PR_PREEMPT This ioctl command releases the existing reservation referred to by -old_key and replaces it with a a new reservation of type for the +old_key and replaces it with a new reservation of type for the reservation key new_key. diff --git a/Documentation/blockdev/mflash.txt b/Documentation/blockdev/mflash.txt index 1f610ecf698a..f7e050551487 100644 --- a/Documentation/blockdev/mflash.txt +++ b/Documentation/blockdev/mflash.txt @@ -17,7 +17,7 @@ driver and currently works well under standard IDE subsystem. Actually it's one chip SSD. IO mode is ATA-like custom mode for the host that doesn't have IDE interface. -Followings are brief descriptions about IO mode. +Following are brief descriptions about IO mode. A. IO mode based on ATA protocol and uses some custom command. (read confirm, write confirm) B. IO mode uses SRAM bus interface. diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt index 0535ae1f73e5..4fced8a21307 100644 --- a/Documentation/blockdev/zram.txt +++ b/Documentation/blockdev/zram.txt @@ -161,42 +161,14 @@ Name access description disksize RW show and set the device's disk size initstate RO shows the initialization state of the device reset WO trigger device reset -num_reads RO the number of reads -failed_reads RO the number of failed reads -num_write RO the number of writes -failed_writes RO the number of failed writes -invalid_io RO the number of non-page-size-aligned I/O requests +mem_used_max WO reset the `mem_used_max' counter (see later) +mem_limit WO specifies the maximum amount of memory ZRAM can use + to store the compressed data max_comp_streams RW the number of possible concurrent compress operations comp_algorithm RW show and change the compression algorithm -notify_free RO the number of notifications to free pages (either - slot free notifications or REQ_DISCARD requests) -zero_pages RO the number of zero filled pages written to this disk -orig_data_size RO uncompressed size of data stored in this disk -compr_data_size RO compressed size of data stored in this disk -mem_used_total RO the amount of memory allocated for this disk -mem_used_max RW the maximum amount of memory zram have consumed to - store the data (to reset this counter to the actual - current value, write 1 to this attribute) -mem_limit RW the maximum amount of memory ZRAM can use to store - the compressed data -pages_compacted RO the number of pages freed during compaction - (available only via zram<id>/mm_stat node) compact WO trigger memory compaction debug_stat RO this file is used for zram debugging purposes -WARNING -======= -per-stat sysfs attributes are considered to be deprecated. -The basic strategy is: --- the existing RW nodes will be downgraded to WO nodes (in linux 4.11) --- deprecated RO sysfs nodes will eventually be removed (in linux 4.11) - -The list of deprecated attributes can be found here: -Documentation/ABI/obsolete/sysfs-block-zram - -Basically, every attribute that has its own read accessible sysfs node -(e.g. num_reads) *AND* is accessible via one of the stat files (zram<id>/stat -or zram<id>/io_stat or zram<id>/mm_stat) is considered to be deprecated. User space is advised to use the following files to read the device statistics. @@ -211,22 +183,40 @@ The stat file represents device's I/O statistics not accounted by block layer and, thus, not available in zram<id>/stat file. It consists of a single line of text and contains the following stats separated by whitespace: - failed_reads - failed_writes - invalid_io - notify_free + failed_reads the number of failed reads + failed_writes the number of failed writes + invalid_io the number of non-page-size-aligned I/O requests + notify_free Depending on device usage scenario it may account + a) the number of pages freed because of swap slot free + notifications or b) the number of pages freed because of + REQ_DISCARD requests sent by bio. The former ones are + sent to a swap block device when a swap slot is freed, + which implies that this disk is being used as a swap disk. + The latter ones are sent by filesystem mounted with + discard option, whenever some data blocks are getting + discarded. File /sys/block/zram<id>/mm_stat The stat file represents device's mm statistics. It consists of a single line of text and contains the following stats separated by whitespace: - orig_data_size - compr_data_size - mem_used_total - mem_limit - mem_used_max - zero_pages - num_migrated + orig_data_size uncompressed size of data stored in this disk. + This excludes same-element-filled pages (same_pages) since + no memory is allocated for them. + Unit: bytes + compr_data_size compressed size of data stored in this disk + mem_used_total the amount of memory allocated for this disk. This + includes allocator fragmentation and metadata overhead, + allocated for this disk. So, allocator space efficiency + can be calculated using compr_data_size and this statistic. + Unit: bytes + mem_limit the maximum amount of memory ZRAM can use to store + the compressed data + mem_used_max the maximum amount of memory zram have consumed to + store the data + same_pages the number of same element filled pages written to this disk. + No memory is allocated for such pages. + pages_compacted the number of pages freed during compaction 9) Deactivate: swapoff /dev/zram0 diff --git a/Documentation/cgroup-v1/cpusets.txt b/Documentation/cgroup-v1/cpusets.txt index e5ac5da86682..8402dd6de8df 100644 --- a/Documentation/cgroup-v1/cpusets.txt +++ b/Documentation/cgroup-v1/cpusets.txt @@ -615,7 +615,7 @@ to allocate a page of memory for that task. If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset will have its allowed CPU placement changed immediately. Similarly, -if a task's pid is written to another cpusets 'cpuset.tasks' file, then its +if a task's pid is written to another cpuset's 'tasks' file, then its allowed CPU placement is changed immediately. If such a task had been bound to some subset of its cpuset using the sched_setaffinity() call, the task will be allowed to run on any CPU allowed in its new cpuset, diff --git a/Documentation/cgroup-v1/rdma.txt b/Documentation/cgroup-v1/rdma.txt new file mode 100644 index 000000000000..af618171e0eb --- /dev/null +++ b/Documentation/cgroup-v1/rdma.txt @@ -0,0 +1,109 @@ + RDMA Controller + ---------------- + +Contents +-------- + +1. Overview + 1-1. What is RDMA controller? + 1-2. Why RDMA controller needed? + 1-3. How is RDMA controller implemented? +2. Usage Examples + +1. Overview + +1-1. What is RDMA controller? +----------------------------- + +RDMA controller allows user to limit RDMA/IB specific resources that a given +set of processes can use. These processes are grouped using RDMA controller. + +RDMA controller defines two resources which can be limited for processes of a +cgroup. + +1-2. Why RDMA controller needed? +-------------------------------- + +Currently user space applications can easily take away all the rdma verb +specific resources such as AH, CQ, QP, MR etc. Due to which other applications +in other cgroup or kernel space ULPs may not even get chance to allocate any +rdma resources. This can leads to service unavailability. + +Therefore RDMA controller is needed through which resource consumption +of processes can be limited. Through this controller different rdma +resources can be accounted. + +1-3. How is RDMA controller implemented? +---------------------------------------- + +RDMA cgroup allows limit configuration of resources. Rdma cgroup maintains +resource accounting per cgroup, per device using resource pool structure. +Each such resource pool is limited up to 64 resources in given resource pool +by rdma cgroup, which can be extended later if required. + +This resource pool object is linked to the cgroup css. Typically there +are 0 to 4 resource pool instances per cgroup, per device in most use cases. +But nothing limits to have it more. At present hundreds of RDMA devices per +single cgroup may not be handled optimally, however there is no +known use case or requirement for such configuration either. + +Since RDMA resources can be allocated from any process and can be freed by any +of the child processes which shares the address space, rdma resources are +always owned by the creator cgroup css. This allows process migration from one +to other cgroup without major complexity of transferring resource ownership; +because such ownership is not really present due to shared nature of +rdma resources. Linking resources around css also ensures that cgroups can be +deleted after processes migrated. This allow progress migration as well with +active resources, even though that is not a primary use case. + +Whenever RDMA resource charging occurs, owner rdma cgroup is returned to +the caller. Same rdma cgroup should be passed while uncharging the resource. +This also allows process migrated with active RDMA resource to charge +to new owner cgroup for new resource. It also allows to uncharge resource of +a process from previously charged cgroup which is migrated to new cgroup, +even though that is not a primary use case. + +Resource pool object is created in following situations. +(a) User sets the limit and no previous resource pool exist for the device +of interest for the cgroup. +(b) No resource limits were configured, but IB/RDMA stack tries to +charge the resource. So that it correctly uncharge them when applications are +running without limits and later on when limits are enforced during uncharging, +otherwise usage count will drop to negative. + +Resource pool is destroyed if all the resource limits are set to max and +it is the last resource getting deallocated. + +User should set all the limit to max value if it intents to remove/unconfigure +the resource pool for a particular device. + +IB stack honors limits enforced by the rdma controller. When application +query about maximum resource limits of IB device, it returns minimum of +what is configured by user for a given cgroup and what is supported by +IB device. + +Following resources can be accounted by rdma controller. + hca_handle Maximum number of HCA Handles + hca_object Maximum number of HCA Objects + +2. Usage Examples +----------------- + +(a) Configure resource limit: +echo mlx4_0 hca_handle=2 hca_object=2000 > /sys/fs/cgroup/rdma/1/rdma.max +echo ocrdma1 hca_handle=3 > /sys/fs/cgroup/rdma/2/rdma.max + +(b) Query resource limit: +cat /sys/fs/cgroup/rdma/2/rdma.max +#Output: +mlx4_0 hca_handle=2 hca_object=2000 +ocrdma1 hca_handle=3 hca_object=max + +(c) Query current usage: +cat /sys/fs/cgroup/rdma/2/rdma.current +#Output: +mlx4_0 hca_handle=1 hca_object=20 +ocrdma1 hca_handle=1 hca_object=23 + +(d) Delete resource limit: +echo echo mlx4_0 hca_handle=max hca_object=max > /sys/fs/cgroup/rdma/1/rdma.max diff --git a/Documentation/cgroup-v2.txt b/Documentation/cgroup-v2.txt index 4cc07ce3b8dd..49d7c997fa1e 100644 --- a/Documentation/cgroup-v2.txt +++ b/Documentation/cgroup-v2.txt @@ -47,6 +47,12 @@ CONTENTS 5-3. IO 5-3-1. IO Interface Files 5-3-2. Writeback + 5-4. PID + 5-4-1. PID Interface Files + 5-5. RDMA + 5-5-1. RDMA Interface Files + 5-6. Misc + 5-6-1. perf_event 6. Namespace 6-1. Basics 6-2. The Root and Views @@ -328,14 +334,12 @@ a process with a non-root euid to migrate a target process into a cgroup by writing its PID to the "cgroup.procs" file, the following conditions must be met. -- The writer's euid must match either uid or suid of the target process. - - The writer must have write access to the "cgroup.procs" file. - The writer must have write access to the "cgroup.procs" file of the common ancestor of the source and destination cgroups. -The above three constraints ensure that while a delegatee may migrate +The above two constraints ensure that while a delegatee may migrate processes around freely in the delegated sub-hierarchy it can't pull in from or push out to outside the sub-hierarchy. @@ -350,10 +354,10 @@ all processes under C0 and C1 belong to U0. Let's also say U0 wants to write the PID of a process which is currently in C10 into "C00/cgroup.procs". U0 has write access to the -file and uid match on the process; however, the common ancestor of the -source cgroup C10 and the destination cgroup C00 is above the points -of delegation and U0 would not have write access to its "cgroup.procs" -files and thus the write will be denied with -EACCES. +file; however, the common ancestor of the source cgroup C10 and the +destination cgroup C00 is above the points of delegation and U0 would +not have write access to its "cgroup.procs" files and thus the write +will be denied with -EACCES. 2-6. Guidelines @@ -1119,6 +1123,92 @@ writeback as follows. vm.dirty[_background]_ratio. +5-4. PID + +The process number controller is used to allow a cgroup to stop any +new tasks from being fork()'d or clone()'d after a specified limit is +reached. + +The number of tasks in a cgroup can be exhausted in ways which other +controllers cannot prevent, thus warranting its own controller. For +example, a fork bomb is likely to exhaust the number of tasks before +hitting memory restrictions. + +Note that PIDs used in this controller refer to TIDs, process IDs as +used by the kernel. + + +5-4-1. PID Interface Files + + pids.max + + A read-write single value file which exists on non-root + cgroups. The default is "max". + + Hard limit of number of processes. + + pids.current + + A read-only single value file which exists on all cgroups. + + The number of processes currently in the cgroup and its + descendants. + +Organisational operations are not blocked by cgroup policies, so it is +possible to have pids.current > pids.max. This can be done by either +setting the limit to be smaller than pids.current, or attaching enough +processes to the cgroup such that pids.current is larger than +pids.max. However, it is not possible to violate a cgroup PID policy +through fork() or clone(). These will return -EAGAIN if the creation +of a new process would cause a cgroup policy to be violated. + + +5-5. RDMA + +The "rdma" controller regulates the distribution and accounting of +of RDMA resources. + +5-5-1. RDMA Interface Files + + rdma.max + A readwrite nested-keyed file that exists for all the cgroups + except root that describes current configured resource limit + for a RDMA/IB device. + + Lines are keyed by device name and are not ordered. + Each line contains space separated resource name and its configured + limit that can be distributed. + + The following nested keys are defined. + + hca_handle Maximum number of HCA Handles + hca_object Maximum number of HCA Objects + + An example for mlx4 and ocrdma device follows. + + mlx4_0 hca_handle=2 hca_object=2000 + ocrdma1 hca_handle=3 hca_object=max + + rdma.current + A read-only file that describes current resource usage. + It exists for all the cgroup except root. + + An example for mlx4 and ocrdma device follows. + + mlx4_0 hca_handle=1 hca_object=20 + ocrdma1 hca_handle=1 hca_object=23 + + +5-6. Misc + +5-6-1. perf_event + +perf_event controller, if not mounted on a legacy hierarchy, is +automatically enabled on the v2 hierarchy so that perf events can +always be filtered by cgroup v2 path. The controller can still be +moved to a legacy hierarchy after v2 hierarchy is populated. + + 6. Namespace 6-1. Basics diff --git a/Documentation/conf.py b/Documentation/conf.py index 1ac958c0333d..7fadb3b83293 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -58,7 +58,7 @@ master_doc = 'index' # General information about the project. project = 'The Linux Kernel' -copyright = '2016, The kernel development community' +copyright = 'The kernel development community' author = 'The kernel development community' # The version info for the project you're documenting, acts as replacement for @@ -135,7 +135,7 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -primary_domain = 'C' +primary_domain = 'c' highlight_language = 'none' # -- Options for HTML output ---------------------------------------------- diff --git a/Documentation/core-api/cpu_hotplug.rst b/Documentation/core-api/cpu_hotplug.rst new file mode 100644 index 000000000000..4a50ab7817f7 --- /dev/null +++ b/Documentation/core-api/cpu_hotplug.rst @@ -0,0 +1,372 @@ +========================= +CPU hotplug in the Kernel +========================= + +:Date: December, 2016 +:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>, + Rusty Russell <rusty@rustcorp.com.au>, + Srivatsa Vaddagiri <vatsa@in.ibm.com>, + Ashok Raj <ashok.raj@intel.com>, + Joel Schopp <jschopp@austin.ibm.com> + +Introduction +============ + +Modern advances in system architectures have introduced advanced error +reporting and correction capabilities in processors. There are couple OEMS that +support NUMA hardware which are hot pluggable as well, where physical node +insertion and removal require support for CPU hotplug. + +Such advances require CPUs available to a kernel to be removed either for +provisioning reasons, or for RAS purposes to keep an offending CPU off +system execution path. Hence the need for CPU hotplug support in the +Linux kernel. + +A more novel use of CPU-hotplug support is its use today in suspend resume +support for SMP. Dual-core and HT support makes even a laptop run SMP kernels +which didn't support these methods. + + +Command Line Switches +===================== +``maxcpus=n`` + Restrict boot time CPUs to *n*. Say if you have fourV CPUs, using + ``maxcpus=2`` will only boot two. You can choose to bring the + other CPUs later online. + +``nr_cpus=n`` + Restrict the total amount CPUs the kernel will support. If the number + supplied here is lower than the number of physically available CPUs than + those CPUs can not be brought online later. + +``additional_cpus=n`` + Use this to limit hotpluggable CPUs. This option sets + ``cpu_possible_mask = cpu_present_mask + additional_cpus`` + + This option is limited to the IA64 architecture. + +``possible_cpus=n`` + This option sets ``possible_cpus`` bits in ``cpu_possible_mask``. + + This option is limited to the X86 and S390 architecture. + +``cede_offline={"off","on"}`` + Use this option to disable/enable putting offlined processors to an extended + ``H_CEDE`` state on supported pseries platforms. If nothing is specified, + ``cede_offline`` is set to "on". + + This option is limited to the PowerPC architecture. + +``cpu0_hotplug`` + Allow to shutdown CPU0. + + This option is limited to the X86 architecture. + +CPU maps +======== + +``cpu_possible_mask`` + Bitmap of possible CPUs that can ever be available in the + system. This is used to allocate some boot time memory for per_cpu variables + that aren't designed to grow/shrink as CPUs are made available or removed. + Once set during boot time discovery phase, the map is static, i.e no bits + are added or removed anytime. Trimming it accurately for your system needs + upfront can save some boot time memory. + +``cpu_online_mask`` + Bitmap of all CPUs currently online. Its set in ``__cpu_up()`` + after a CPU is available for kernel scheduling and ready to receive + interrupts from devices. Its cleared when a CPU is brought down using + ``__cpu_disable()``, before which all OS services including interrupts are + migrated to another target CPU. + +``cpu_present_mask`` + Bitmap of CPUs currently present in the system. Not all + of them may be online. When physical hotplug is processed by the relevant + subsystem (e.g ACPI) can change and new bit either be added or removed + from the map depending on the event is hot-add/hot-remove. There are currently + no locking rules as of now. Typical usage is to init topology during boot, + at which time hotplug is disabled. + +You really don't need to manipulate any of the system CPU maps. They should +be read-only for most use. When setting up per-cpu resources almost always use +``cpu_possible_mask`` or ``for_each_possible_cpu()`` to iterate. To macro +``for_each_cpu()`` can be used to iterate over a custom CPU mask. + +Never use anything other than ``cpumask_t`` to represent bitmap of CPUs. + + +Using CPU hotplug +================= +The kernel option *CONFIG_HOTPLUG_CPU* needs to be enabled. It is currently +available on multiple architectures including ARM, MIPS, PowerPC and X86. The +configuration is done via the sysfs interface: :: + + $ ls -lh /sys/devices/system/cpu + total 0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu0 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu1 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu2 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu3 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu4 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu5 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu6 + drwxr-xr-x 9 root root 0 Dec 21 16:33 cpu7 + drwxr-xr-x 2 root root 0 Dec 21 16:33 hotplug + -r--r--r-- 1 root root 4.0K Dec 21 16:33 offline + -r--r--r-- 1 root root 4.0K Dec 21 16:33 online + -r--r--r-- 1 root root 4.0K Dec 21 16:33 possible + -r--r--r-- 1 root root 4.0K Dec 21 16:33 present + +The files *offline*, *online*, *possible*, *present* represent the CPU masks. +Each CPU folder contains an *online* file which controls the logical on (1) and +off (0) state. To logically shutdown CPU4: :: + + $ echo 0 > /sys/devices/system/cpu/cpu4/online + smpboot: CPU 4 is now offline + +Once the CPU is shutdown, it will be removed from */proc/interrupts*, +*/proc/cpuinfo* and should also not be shown visible by the *top* command. To +bring CPU4 back online: :: + + $ echo 1 > /sys/devices/system/cpu/cpu4/online + smpboot: Booting Node 0 Processor 4 APIC 0x1 + +The CPU is usable again. This should work on all CPUs. CPU0 is often special +and excluded from CPU hotplug. On X86 the kernel option +*CONFIG_BOOTPARAM_HOTPLUG_CPU0* has to be enabled in order to be able to +shutdown CPU0. Alternatively the kernel command option *cpu0_hotplug* can be +used. Some known dependencies of CPU0: + +* Resume from hibernate/suspend. Hibernate/suspend will fail if CPU0 is offline. +* PIC interrupts. CPU0 can't be removed if a PIC interrupt is detected. + +Please let Fenghua Yu <fenghua.yu@intel.com> know if you find any dependencies +on CPU0. + +The CPU hotplug coordination +============================ + +The offline case +---------------- +Once a CPU has been logically shutdown the teardown callbacks of registered +hotplug states will be invoked, starting with ``CPUHP_ONLINE`` and terminating +at state ``CPUHP_OFFLINE``. This includes: + +* If tasks are frozen due to a suspend operation then *cpuhp_tasks_frozen* + will be set to true. +* All processes are migrated away from this outgoing CPU to new CPUs. + The new CPU is chosen from each process' current cpuset, which may be + a subset of all online CPUs. +* All interrupts targeted to this CPU are migrated to a new CPU +* timers are also migrated to a new CPU +* Once all services are migrated, kernel calls an arch specific routine + ``__cpu_disable()`` to perform arch specific cleanup. + +Using the hotplug API +--------------------- +It is possible to receive notifications once a CPU is offline or onlined. This +might be important to certain drivers which need to perform some kind of setup +or clean up functions based on the number of available CPUs: :: + + #include <linux/cpuhotplug.h> + + ret = cpuhp_setup_state(CPUHP_AP_ONLINE_DYN, "X/Y:online", + Y_online, Y_prepare_down); + +*X* is the subsystem and *Y* the particular driver. The *Y_online* callback +will be invoked during registration on all online CPUs. If an error +occurs during the online callback the *Y_prepare_down* callback will be +invoked on all CPUs on which the online callback was previously invoked. +After registration completed, the *Y_online* callback will be invoked +once a CPU is brought online and *Y_prepare_down* will be invoked when a +CPU is shutdown. All resources which were previously allocated in +*Y_online* should be released in *Y_prepare_down*. +The return value *ret* is negative if an error occurred during the +registration process. Otherwise a positive value is returned which +contains the allocated hotplug for dynamically allocated states +(*CPUHP_AP_ONLINE_DYN*). It will return zero for predefined states. + +The callback can be remove by invoking ``cpuhp_remove_state()``. In case of a +dynamically allocated state (*CPUHP_AP_ONLINE_DYN*) use the returned state. +During the removal of a hotplug state the teardown callback will be invoked. + +Multiple instances +~~~~~~~~~~~~~~~~~~ +If a driver has multiple instances and each instance needs to perform the +callback independently then it is likely that a ''multi-state'' should be used. +First a multi-state state needs to be registered: :: + + ret = cpuhp_setup_state_multi(CPUHP_AP_ONLINE_DYN, "X/Y:online, + Y_online, Y_prepare_down); + Y_hp_online = ret; + +The ``cpuhp_setup_state_multi()`` behaves similar to ``cpuhp_setup_state()`` +except it prepares the callbacks for a multi state and does not invoke +the callbacks. This is a one time setup. +Once a new instance is allocated, you need to register this new instance: :: + + ret = cpuhp_state_add_instance(Y_hp_online, &d->node); + +This function will add this instance to your previously allocated +*Y_hp_online* state and invoke the previously registered callback +(*Y_online*) on all online CPUs. The *node* element is a ``struct +hlist_node`` member of your per-instance data structure. + +On removal of the instance: :: + cpuhp_state_remove_instance(Y_hp_online, &d->node) + +should be invoked which will invoke the teardown callback on all online +CPUs. + +Manual setup +~~~~~~~~~~~~ +Usually it is handy to invoke setup and teardown callbacks on registration or +removal of a state because usually the operation needs to performed once a CPU +goes online (offline) and during initial setup (shutdown) of the driver. However +each registration and removal function is also available with a ``_nocalls`` +suffix which does not invoke the provided callbacks if the invocation of the +callbacks is not desired. During the manual setup (or teardown) the functions +``get_online_cpus()`` and ``put_online_cpus()`` should be used to inhibit CPU +hotplug operations. + + +The ordering of the events +-------------------------- +The hotplug states are defined in ``include/linux/cpuhotplug.h``: + +* The states *CPUHP_OFFLINE* … *CPUHP_AP_OFFLINE* are invoked before the + CPU is up. +* The states *CPUHP_AP_OFFLINE* … *CPUHP_AP_ONLINE* are invoked + just the after the CPU has been brought up. The interrupts are off and + the scheduler is not yet active on this CPU. Starting with *CPUHP_AP_OFFLINE* + the callbacks are invoked on the target CPU. +* The states between *CPUHP_AP_ONLINE_DYN* and *CPUHP_AP_ONLINE_DYN_END* are + reserved for the dynamic allocation. +* The states are invoked in the reverse order on CPU shutdown starting with + *CPUHP_ONLINE* and stopping at *CPUHP_OFFLINE*. Here the callbacks are + invoked on the CPU that will be shutdown until *CPUHP_AP_OFFLINE*. + +A dynamically allocated state via *CPUHP_AP_ONLINE_DYN* is often enough. +However if an earlier invocation during the bring up or shutdown is required +then an explicit state should be acquired. An explicit state might also be +required if the hotplug event requires specific ordering in respect to +another hotplug event. + +Testing of hotplug states +========================= +One way to verify whether a custom state is working as expected or not is to +shutdown a CPU and then put it online again. It is also possible to put the CPU +to certain state (for instance *CPUHP_AP_ONLINE*) and then go back to +*CPUHP_ONLINE*. This would simulate an error one state after *CPUHP_AP_ONLINE* +which would lead to rollback to the online state. + +All registered states are enumerated in ``/sys/devices/system/cpu/hotplug/states``: :: + + $ tail /sys/devices/system/cpu/hotplug/states + 138: mm/vmscan:online + 139: mm/vmstat:online + 140: lib/percpu_cnt:online + 141: acpi/cpu-drv:online + 142: base/cacheinfo:online + 143: virtio/net:online + 144: x86/mce:online + 145: printk:online + 168: sched:active + 169: online + +To rollback CPU4 to ``lib/percpu_cnt:online`` and back online just issue: :: + + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + $ echo 140 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 140 + +It is important to note that the teardown callbac of state 140 have been +invoked. And now get back online: :: + + $ echo 169 > /sys/devices/system/cpu/cpu4/hotplug/target + $ cat /sys/devices/system/cpu/cpu4/hotplug/state + 169 + +With trace events enabled, the individual steps are visible, too: :: + + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + bash-394 [001] 22.976: cpuhp_enter: cpu: 0004 target: 140 step: 169 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 22.977: cpuhp_enter: cpu: 0004 target: 140 step: 168 (sched_cpu_deactivate) + cpuhp/4-31 [004] 22.990: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + cpuhp/4-31 [004] 22.991: cpuhp_enter: cpu: 0004 target: 140 step: 144 (mce_cpu_pre_down) + cpuhp/4-31 [004] 22.992: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 22.993: cpuhp_multi_enter: cpu: 0004 target: 140 step: 143 (virtnet_cpu_down_prep) + cpuhp/4-31 [004] 22.994: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 22.995: cpuhp_enter: cpu: 0004 target: 140 step: 142 (cacheinfo_cpu_pre_down) + cpuhp/4-31 [004] 22.996: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + bash-394 [001] 22.997: cpuhp_exit: cpu: 0004 state: 140 step: 169 ret: 0 + bash-394 [005] 95.540: cpuhp_enter: cpu: 0004 target: 169 step: 140 (cpuhp_kick_ap_work) + cpuhp/4-31 [004] 95.541: cpuhp_enter: cpu: 0004 target: 169 step: 141 (acpi_soft_cpu_online) + cpuhp/4-31 [004] 95.542: cpuhp_exit: cpu: 0004 state: 141 step: 141 ret: 0 + cpuhp/4-31 [004] 95.543: cpuhp_enter: cpu: 0004 target: 169 step: 142 (cacheinfo_cpu_online) + cpuhp/4-31 [004] 95.544: cpuhp_exit: cpu: 0004 state: 142 step: 142 ret: 0 + cpuhp/4-31 [004] 95.545: cpuhp_multi_enter: cpu: 0004 target: 169 step: 143 (virtnet_cpu_online) + cpuhp/4-31 [004] 95.546: cpuhp_exit: cpu: 0004 state: 143 step: 143 ret: 0 + cpuhp/4-31 [004] 95.547: cpuhp_enter: cpu: 0004 target: 169 step: 144 (mce_cpu_online) + cpuhp/4-31 [004] 95.548: cpuhp_exit: cpu: 0004 state: 144 step: 144 ret: 0 + cpuhp/4-31 [004] 95.549: cpuhp_enter: cpu: 0004 target: 169 step: 145 (console_cpu_notify) + cpuhp/4-31 [004] 95.550: cpuhp_exit: cpu: 0004 state: 145 step: 145 ret: 0 + cpuhp/4-31 [004] 95.551: cpuhp_enter: cpu: 0004 target: 169 step: 168 (sched_cpu_activate) + cpuhp/4-31 [004] 95.552: cpuhp_exit: cpu: 0004 state: 168 step: 168 ret: 0 + bash-394 [005] 95.553: cpuhp_exit: cpu: 0004 state: 169 step: 140 ret: 0 + +As it an be seen, CPU4 went down until timestamp 22.996 and then back up until +95.552. All invoked callbacks including their return codes are visible in the +trace. + +Architecture's requirements +=========================== +The following functions and configurations are required: + +``CONFIG_HOTPLUG_CPU`` + This entry needs to be enabled in Kconfig + +``__cpu_up()`` + Arch interface to bring up a CPU + +``__cpu_disable()`` + Arch interface to shutdown a CPU, no more interrupts can be handled by the + kernel after the routine returns. This includes the shutdown of the timer. + +``__cpu_die()`` + This actually supposed to ensure death of the CPU. Actually look at some + example code in other arch that implement CPU hotplug. The processor is taken + down from the ``idle()`` loop for that specific architecture. ``__cpu_die()`` + typically waits for some per_cpu state to be set, to ensure the processor dead + routine is called to be sure positively. + +User Space Notification +======================= +After CPU successfully onlined or offline udev events are sent. A udev rule like: :: + + SUBSYSTEM=="cpu", DRIVERS=="processor", DEVPATH=="/devices/system/cpu/*", RUN+="the_hotplug_receiver.sh" + +will receive all events. A script like: :: + + #!/bin/sh + + if [ "${ACTION}" = "offline" ] + then + echo "CPU ${DEVPATH##*/} offline" + + elif [ "${ACTION}" = "online" ] + then + echo "CPU ${DEVPATH##*/} online" + + fi + +can process the event further. + +Kernel Inline Documentations Reference +====================================== + +.. kernel-doc:: include/linux/cpuhotplug.h diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 2872ca1a52f1..0d93d8089136 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -13,6 +13,7 @@ Core utilities assoc_array atomic_ops + cpu_hotplug local_ops workqueue diff --git a/Documentation/cpu-freq/user-guide.txt b/Documentation/cpu-freq/user-guide.txt index 107f6fdd7d14..391da64e9492 100644 --- a/Documentation/cpu-freq/user-guide.txt +++ b/Documentation/cpu-freq/user-guide.txt @@ -82,7 +82,9 @@ UltraSPARC-III ------- Several "PowerBook" and "iBook2" notebooks are supported. - +The following POWER processors are supported in powernv mode: +POWER8 +POWER9 1.5 SuperH ---------- diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt deleted file mode 100644 index d02e8a451872..000000000000 --- a/Documentation/cpu-hotplug.txt +++ /dev/null @@ -1,452 +0,0 @@ - CPU hotplug Support in Linux(tm) Kernel - - Maintainers: - CPU Hotplug Core: - Rusty Russell <rusty@rustcorp.com.au> - Srivatsa Vaddagiri <vatsa@in.ibm.com> - i386: - Zwane Mwaikambo <zwanem@gmail.com> - ppc64: - Nathan Lynch <nathanl@austin.ibm.com> - Joel Schopp <jschopp@austin.ibm.com> - ia64/x86_64: - Ashok Raj <ashok.raj@intel.com> - s390: - Heiko Carstens <heiko.carstens@de.ibm.com> - -Authors: Ashok Raj <ashok.raj@intel.com> -Lots of feedback: Nathan Lynch <nathanl@austin.ibm.com>, - Joel Schopp <jschopp@austin.ibm.com> - -Introduction - -Modern advances in system architectures have introduced advanced error -reporting and correction capabilities in processors. CPU architectures permit -partitioning support, where compute resources of a single CPU could be made -available to virtual machine environments. There are couple OEMS that -support NUMA hardware which are hot pluggable as well, where physical -node insertion and removal require support for CPU hotplug. - -Such advances require CPUs available to a kernel to be removed either for -provisioning reasons, or for RAS purposes to keep an offending CPU off -system execution path. Hence the need for CPU hotplug support in the -Linux kernel. - -A more novel use of CPU-hotplug support is its use today in suspend -resume support for SMP. Dual-core and HT support makes even -a laptop run SMP kernels which didn't support these methods. SMP support -for suspend/resume is a work in progress. - -General Stuff about CPU Hotplug --------------------------------- - -Command Line Switches ---------------------- -maxcpus=n Restrict boot time cpus to n. Say if you have 4 cpus, using - maxcpus=2 will only boot 2. You can choose to bring the - other cpus later online, read FAQ's for more info. - -additional_cpus=n (*) Use this to limit hotpluggable cpus. This option sets - cpu_possible_mask = cpu_present_mask + additional_cpus - -cede_offline={"off","on"} Use this option to disable/enable putting offlined - processors to an extended H_CEDE state on - supported pseries platforms. - If nothing is specified, - cede_offline is set to "on". - -(*) Option valid only for following architectures -- ia64 - -ia64 uses the number of disabled local apics in ACPI tables MADT to -determine the number of potentially hot-pluggable cpus. The implementation -should only rely on this to count the # of cpus, but *MUST* not rely -on the apicid values in those tables for disabled apics. In the event -BIOS doesn't mark such hot-pluggable cpus as disabled entries, one could -use this parameter "additional_cpus=x" to represent those cpus in the -cpu_possible_mask. - -possible_cpus=n [s390,x86_64] use this to set hotpluggable cpus. - This option sets possible_cpus bits in - cpu_possible_mask. Thus keeping the numbers of bits set - constant even if the machine gets rebooted. - -CPU maps and such ------------------ -[More on cpumaps and primitive to manipulate, please check -include/linux/cpumask.h that has more descriptive text.] - -cpu_possible_mask: Bitmap of possible CPUs that can ever be available in the -system. This is used to allocate some boot time memory for per_cpu variables -that aren't designed to grow/shrink as CPUs are made available or removed. -Once set during boot time discovery phase, the map is static, i.e no bits -are added or removed anytime. Trimming it accurately for your system needs -upfront can save some boot time memory. See below for how we use heuristics -in x86_64 case to keep this under check. - -cpu_online_mask: Bitmap of all CPUs currently online. It's set in __cpu_up() -after a CPU is available for kernel scheduling and ready to receive -interrupts from devices. It's cleared when a CPU is brought down using -__cpu_disable(), before which all OS services including interrupts are -migrated to another target CPU. - -cpu_present_mask: Bitmap of CPUs currently present in the system. Not all -of them may be online. When physical hotplug is processed by the relevant -subsystem (e.g ACPI) can change and new bit either be added or removed -from the map depending on the event is hot-add/hot-remove. There are currently -no locking rules as of now. Typical usage is to init topology during boot, -at which time hotplug is disabled. - -You really dont need to manipulate any of the system cpu maps. They should -be read-only for most use. When setting up per-cpu resources almost always use -cpu_possible_mask/for_each_possible_cpu() to iterate. - -Never use anything other than cpumask_t to represent bitmap of CPUs. - - #include <linux/cpumask.h> - - for_each_possible_cpu - Iterate over cpu_possible_mask - for_each_online_cpu - Iterate over cpu_online_mask - for_each_present_cpu - Iterate over cpu_present_mask - for_each_cpu(x,mask) - Iterate over some random collection of cpu mask. - - #include <linux/cpu.h> - get_online_cpus() and put_online_cpus(): - -The above calls are used to inhibit cpu hotplug operations. While the -cpu_hotplug.refcount is non zero, the cpu_online_mask will not change. -If you merely need to avoid cpus going away, you could also use -preempt_disable() and preempt_enable() for those sections. -Just remember the critical section cannot call any -function that can sleep or schedule this process away. The preempt_disable() -will work as long as stop_machine_run() is used to take a cpu down. - -CPU Hotplug - Frequently Asked Questions. - -Q: How to enable my kernel to support CPU hotplug? -A: When doing make defconfig, Enable CPU hotplug support - - "Processor type and Features" -> Support for Hotpluggable CPUs - -Make sure that you have CONFIG_SMP turned on as well. - -You would need to enable CONFIG_HOTPLUG_CPU for SMP suspend/resume support -as well. - -Q: What architectures support CPU hotplug? -A: As of 2.6.14, the following architectures support CPU hotplug. - -i386 (Intel), ppc, ppc64, parisc, s390, ia64 and x86_64 - -Q: How to test if hotplug is supported on the newly built kernel? -A: You should now notice an entry in sysfs. - -Check if sysfs is mounted, using the "mount" command. You should notice -an entry as shown below in the output. - - .... - none on /sys type sysfs (rw) - .... - -If this is not mounted, do the following. - - #mkdir /sys - #mount -t sysfs sys /sys - -Now you should see entries for all present cpu, the following is an example -in a 8-way system. - - #pwd - #/sys/devices/system/cpu - #ls -l - total 0 - drwxr-xr-x 10 root root 0 Sep 19 07:44 . - drwxr-xr-x 13 root root 0 Sep 19 07:45 .. - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu0 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu1 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu2 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu3 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu4 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu5 - drwxr-xr-x 3 root root 0 Sep 19 07:44 cpu6 - drwxr-xr-x 3 root root 0 Sep 19 07:48 cpu7 - -Under each directory you would find an "online" file which is the control -file to logically online/offline a processor. - -Q: Does hot-add/hot-remove refer to physical add/remove of cpus? -A: The usage of hot-add/remove may not be very consistently used in the code. -CONFIG_HOTPLUG_CPU enables logical online/offline capability in the kernel. -To support physical addition/removal, one would need some BIOS hooks and -the platform should have something like an attention button in PCI hotplug. -CONFIG_ACPI_HOTPLUG_CPU enables ACPI support for physical add/remove of CPUs. - -Q: How do I logically offline a CPU? -A: Do the following. - - #echo 0 > /sys/devices/system/cpu/cpuX/online - -Once the logical offline is successful, check - - #cat /proc/interrupts - -You should now not see the CPU that you removed. Also online file will report -the state as 0 when a CPU is offline and 1 when it's online. - - #To display the current cpu state. - #cat /sys/devices/system/cpu/cpuX/online - -Q: Why can't I remove CPU0 on some systems? -A: Some architectures may have some special dependency on a certain CPU. - -For e.g in IA64 platforms we have ability to send platform interrupts to the -OS. a.k.a Corrected Platform Error Interrupts (CPEI). In current ACPI -specifications, we didn't have a way to change the target CPU. Hence if the -current ACPI version doesn't support such re-direction, we disable that CPU -by making it not-removable. - -In such cases you will also notice that the online file is missing under cpu0. - -Q: Is CPU0 removable on X86? -A: Yes. If kernel is compiled with CONFIG_BOOTPARAM_HOTPLUG_CPU0=y, CPU0 is -removable by default. Otherwise, CPU0 is also removable by kernel option -cpu0_hotplug. - -But some features depend on CPU0. Two known dependencies are: - -1. Resume from hibernate/suspend depends on CPU0. Hibernate/suspend will fail if -CPU0 is offline and you need to online CPU0 before hibernate/suspend can -continue. -2. PIC interrupts also depend on CPU0. CPU0 can't be removed if a PIC interrupt -is detected. - -It's said poweroff/reboot may depend on CPU0 on some machines although I haven't -seen any poweroff/reboot failure so far after CPU0 is offline on a few tested -machines. - -Please let me know if you know or see any other dependencies of CPU0. - -If the dependencies are under your control, you can turn on CPU0 hotplug feature -either by CONFIG_BOOTPARAM_HOTPLUG_CPU0 or by kernel parameter cpu0_hotplug. - ---Fenghua Yu <fenghua.yu@intel.com> - -Q: How do I find out if a particular CPU is not removable? -A: Depending on the implementation, some architectures may show this by the -absence of the "online" file. This is done if it can be determined ahead of -time that this CPU cannot be removed. - -In some situations, this can be a run time check, i.e if you try to remove the -last CPU, this will not be permitted. You can find such failures by -investigating the return value of the "echo" command. - -Q: What happens when a CPU is being logically offlined? -A: The following happen, listed in no particular order :-) - -- A notification is sent to in-kernel registered modules by sending an event - CPU_DOWN_PREPARE or CPU_DOWN_PREPARE_FROZEN, depending on whether or not the - CPU is being offlined while tasks are frozen due to a suspend operation in - progress -- All processes are migrated away from this outgoing CPU to new CPUs. - The new CPU is chosen from each process' current cpuset, which may be - a subset of all online CPUs. -- All interrupts targeted to this CPU are migrated to a new CPU -- timers/bottom half/task lets are also migrated to a new CPU -- Once all services are migrated, kernel calls an arch specific routine - __cpu_disable() to perform arch specific cleanup. -- Once this is successful, an event for successful cleanup is sent by an event - CPU_DEAD (or CPU_DEAD_FROZEN if tasks are frozen due to a suspend while the - CPU is being offlined). - - "It is expected that each service cleans up when the CPU_DOWN_PREPARE - notifier is called, when CPU_DEAD is called it's expected there is nothing - running on behalf of this CPU that was offlined" - -Q: If I have some kernel code that needs to be aware of CPU arrival and - departure, how to i arrange for proper notification? -A: This is what you would need in your kernel code to receive notifications. - - #include <linux/cpu.h> - static int foobar_cpu_callback(struct notifier_block *nfb, - unsigned long action, void *hcpu) - { - unsigned int cpu = (unsigned long)hcpu; - - switch (action) { - case CPU_ONLINE: - case CPU_ONLINE_FROZEN: - foobar_online_action(cpu); - break; - case CPU_DEAD: - case CPU_DEAD_FROZEN: - foobar_dead_action(cpu); - break; - } - return NOTIFY_OK; - } - - static struct notifier_block foobar_cpu_notifier = - { - .notifier_call = foobar_cpu_callback, - }; - -You need to call register_cpu_notifier() from your init function. -Init functions could be of two types: -1. early init (init function called when only the boot processor is online). -2. late init (init function called _after_ all the CPUs are online). - -For the first case, you should add the following to your init function - - register_cpu_notifier(&foobar_cpu_notifier); - -For the second case, you should add the following to your init function - - register_hotcpu_notifier(&foobar_cpu_notifier); - -You can fail PREPARE notifiers if something doesn't work to prepare resources. -This will stop the activity and send a following CANCELED event back. - -CPU_DEAD should not be failed, its just a goodness indication, but bad -things will happen if a notifier in path sent a BAD notify code. - -Q: I don't see my action being called for all CPUs already up and running? -A: Yes, CPU notifiers are called only when new CPUs are on-lined or offlined. - If you need to perform some action for each CPU already in the system, then - do this: - - for_each_online_cpu(i) { - foobar_cpu_callback(&foobar_cpu_notifier, CPU_UP_PREPARE, i); - foobar_cpu_callback(&foobar_cpu_notifier, CPU_ONLINE, i); - } - - However, if you want to register a hotplug callback, as well as perform - some initialization for CPUs that are already online, then do this: - - Version 1: (Correct) - --------- - - cpu_notifier_register_begin(); - - for_each_online_cpu(i) { - foobar_cpu_callback(&foobar_cpu_notifier, - CPU_UP_PREPARE, i); - foobar_cpu_callback(&foobar_cpu_notifier, - CPU_ONLINE, i); - } - - /* Note the use of the double underscored version of the API */ - __register_cpu_notifier(&foobar_cpu_notifier); - - cpu_notifier_register_done(); - - Note that the following code is *NOT* the right way to achieve this, - because it is prone to an ABBA deadlock between the cpu_add_remove_lock - and the cpu_hotplug.lock. - - Version 2: (Wrong!) - --------- - - get_online_cpus(); - - for_each_online_cpu(i) { - foobar_cpu_callback(&foobar_cpu_notifier, - CPU_UP_PREPARE, i); - foobar_cpu_callback(&foobar_cpu_notifier, - CPU_ONLINE, i); - } - - register_cpu_notifier(&foobar_cpu_notifier); - - put_online_cpus(); - - So always use the first version shown above when you want to register - callbacks as well as initialize the already online CPUs. - - -Q: If I would like to develop CPU hotplug support for a new architecture, - what do I need at a minimum? -A: The following are what is required for CPU hotplug infrastructure to work - correctly. - - - Make sure you have an entry in Kconfig to enable CONFIG_HOTPLUG_CPU - - __cpu_up() - Arch interface to bring up a CPU - - __cpu_disable() - Arch interface to shutdown a CPU, no more interrupts - can be handled by the kernel after the routine - returns. Including local APIC timers etc are - shutdown. - - __cpu_die() - This actually supposed to ensure death of the CPU. - Actually look at some example code in other arch - that implement CPU hotplug. The processor is taken - down from the idle() loop for that specific - architecture. __cpu_die() typically waits for some - per_cpu state to be set, to ensure the processor - dead routine is called to be sure positively. - -Q: I need to ensure that a particular CPU is not removed when there is some - work specific to this CPU in progress. -A: There are two ways. If your code can be run in interrupt context, use - smp_call_function_single(), otherwise use work_on_cpu(). Note that - work_on_cpu() is slow, and can fail due to out of memory: - - int my_func_on_cpu(int cpu) - { - int err; - get_online_cpus(); - if (!cpu_online(cpu)) - err = -EINVAL; - else -#if NEEDS_BLOCKING - err = work_on_cpu(cpu, __my_func_on_cpu, NULL); -#else - smp_call_function_single(cpu, __my_func_on_cpu, &err, - true); -#endif - put_online_cpus(); - return err; - } - -Q: How do we determine how many CPUs are available for hotplug. -A: There is no clear spec defined way from ACPI that can give us that - information today. Based on some input from Natalie of Unisys, - that the ACPI MADT (Multiple APIC Description Tables) marks those possible - CPUs in a system with disabled status. - - Andi implemented some simple heuristics that count the number of disabled - CPUs in MADT as hotpluggable CPUS. In the case there are no disabled CPUS - we assume 1/2 the number of CPUs currently present can be hotplugged. - - Caveat: ACPI MADT can only provide 256 entries in systems with only ACPI 2.0c - or earlier ACPI version supported, because the apicid field in MADT is only - 8 bits. From ACPI 3.0, this limitation was removed since the apicid field - was extended to 32 bits with x2APIC introduced. - -User Space Notification - -Hotplug support for devices is common in Linux today. Its being used today to -support automatic configuration of network, usb and pci devices. A hotplug -event can be used to invoke an agent script to perform the configuration task. - -You can add /etc/hotplug/cpu.agent to handle hotplug notification user space -scripts. - - #!/bin/bash - # $Id: cpu.agent - # Kernel hotplug params include: - #ACTION=%s [online or offline] - #DEVPATH=%s - # - cd /etc/hotplug - . ./hotplug.functions - - case $ACTION in - online) - echo `date` ":cpu.agent" add cpu >> /tmp/hotplug.txt - ;; - offline) - echo `date` ":cpu.agent" remove cpu >>/tmp/hotplug.txt - ;; - *) - debug_mesg CPU $ACTION event not supported - exit 1 - ;; - esac diff --git a/Documentation/crypto/api-digest.rst b/Documentation/crypto/api-digest.rst index 07356fa99200..7a1e670d6ce1 100644 --- a/Documentation/crypto/api-digest.rst +++ b/Documentation/crypto/api-digest.rst @@ -14,7 +14,7 @@ Asynchronous Message Digest API :doc: Asynchronous Message Digest API .. kernel-doc:: include/crypto/hash.h - :functions: crypto_alloc_ahash crypto_free_ahash crypto_ahash_init crypto_ahash_digestsize crypto_ahash_reqtfm crypto_ahash_reqsize crypto_ahash_setkey crypto_ahash_finup crypto_ahash_final crypto_ahash_digest crypto_ahash_export crypto_ahash_import + :functions: crypto_alloc_ahash crypto_free_ahash crypto_ahash_init crypto_ahash_digestsize crypto_ahash_reqtfm crypto_ahash_reqsize crypto_ahash_statesize crypto_ahash_setkey crypto_ahash_finup crypto_ahash_final crypto_ahash_digest crypto_ahash_export crypto_ahash_import Asynchronous Hash Request Handle -------------------------------- diff --git a/Documentation/crypto/api-skcipher.rst b/Documentation/crypto/api-skcipher.rst index b20028a361a9..4eec4a93f7e3 100644 --- a/Documentation/crypto/api-skcipher.rst +++ b/Documentation/crypto/api-skcipher.rst @@ -59,4 +59,4 @@ Synchronous Block Cipher API - Deprecated :doc: Synchronous Block Cipher API .. kernel-doc:: include/linux/crypto.h - :functions: crypto_alloc_blkcipher rypto_free_blkcipher crypto_has_blkcipher crypto_blkcipher_name crypto_blkcipher_ivsize crypto_blkcipher_blocksize crypto_blkcipher_setkey crypto_blkcipher_encrypt crypto_blkcipher_encrypt_iv crypto_blkcipher_decrypt crypto_blkcipher_decrypt_iv crypto_blkcipher_set_iv crypto_blkcipher_get_iv + :functions: crypto_alloc_blkcipher crypto_free_blkcipher crypto_has_blkcipher crypto_blkcipher_name crypto_blkcipher_ivsize crypto_blkcipher_blocksize crypto_blkcipher_setkey crypto_blkcipher_encrypt crypto_blkcipher_encrypt_iv crypto_blkcipher_decrypt crypto_blkcipher_decrypt_iv crypto_blkcipher_set_iv crypto_blkcipher_get_iv diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst index 2c41b713841f..44886c91e112 100644 --- a/Documentation/dev-tools/kcov.rst +++ b/Documentation/dev-tools/kcov.rst @@ -10,7 +10,7 @@ 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). +disabled (e.g. scheduler, locking). Usage ----- diff --git a/Documentation/dev-tools/sparse.rst b/Documentation/dev-tools/sparse.rst index 78aa00a604a0..ffdcc97f6f5a 100644 --- a/Documentation/dev-tools/sparse.rst +++ b/Documentation/dev-tools/sparse.rst @@ -103,3 +103,9 @@ 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. + +Checking RCU annotations +~~~~~~~~~~~~~~~~~~~~~~~~ + +RCU annotations are not checked by default. To enable RCU annotation +checks, include -DCONFIG_SPARSE_RCU_POINTER in your CF flags. diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index 0d199353e477..cd2cb2fc85ea 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -319,7 +319,7 @@ Version History 1.5.2 'mismatch_cnt' is zero unless [last_]sync_action is "check". 1.6.0 Add discard support (and devices_handle_discard_safely module param). 1.7.0 Add support for MD RAID0 mappings. -1.8.0 Explictely check for compatible flags in the superblock metadata +1.8.0 Explicitly check for compatible flags in the superblock metadata and reject to start the raid set if any are set by a newer target version, thus avoiding data corruption on a raid set with a reshape in progress. diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt index 9b2b41ab6817..c246cd2730d9 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.txt +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -40,6 +40,8 @@ Board compatible values: - "hardkernel,odroid-c2" (Meson gxbb) - "amlogic,p200" (Meson gxbb) - "amlogic,p201" (Meson gxbb) + - "wetek,hub" (Meson gxbb) + - "wetek,play2" (Meson gxbb) - "amlogic,p212" (Meson gxl s905x) - "amlogic,p230" (Meson gxl s905d) - "amlogic,p231" (Meson gxl s905d) diff --git a/Documentation/devicetree/bindings/arm/axentia.txt b/Documentation/devicetree/bindings/arm/axentia.txt new file mode 100644 index 000000000000..ea3fb96ae465 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/axentia.txt @@ -0,0 +1,19 @@ +Device tree bindings for Axentia ARM devices +============================================ + +Linea CPU module +---------------- + +Required root node properties: +compatible = "axentia,linea", + "atmel,sama5d31", "atmel,sama5d3", "atmel,sama5"; +and following the rules from atmel-at91.txt for a sama5d31 SoC. + + +TSE-850 v3 board +---------------- + +Required root node properties: +compatible = "axentia,tse850v3", "axentia,linea", + "atmel,sama5d31", "atmel,sama5d3", "atmel,sama5"; +and following the rules from above for the axentia,linea CPU module. diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt index a1bcfeed5f24..698ad1f097fa 100644 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ b/Documentation/devicetree/bindings/arm/cpus.txt @@ -158,6 +158,7 @@ nodes to be present and contain the properties described below. "arm,cortex-a53" "arm,cortex-a57" "arm,cortex-a72" + "arm,cortex-a73" "arm,cortex-m0" "arm,cortex-m0+" "arm,cortex-m1" @@ -202,6 +203,7 @@ nodes to be present and contain the properties described below. "marvell,armada-380-smp" "marvell,armada-390-smp" "marvell,armada-xp-smp" + "marvell,98dx3236-smp" "mediatek,mt6589-smp" "mediatek,mt81xx-tz-smp" "qcom,gcc-msm8660" diff --git a/Documentation/devicetree/bindings/arm/davinci.txt b/Documentation/devicetree/bindings/arm/davinci.txt index f0841ce725b5..715622c36260 100644 --- a/Documentation/devicetree/bindings/arm/davinci.txt +++ b/Documentation/devicetree/bindings/arm/davinci.txt @@ -13,6 +13,10 @@ EnBW AM1808 based CMC board Required root node properties: - compatible = "enbw,cmc", "ti,da850; +LEGO MINDSTORMS EV3 (AM1808 based) +Required root node properties: + - compatible = "lego,ev3", "ti,da850"; + Generic DaVinci Boards ---------------------- diff --git a/Documentation/devicetree/bindings/arm/fsl.txt b/Documentation/devicetree/bindings/arm/fsl.txt index d6ee9c6e1dbb..c9c567ae227f 100644 --- a/Documentation/devicetree/bindings/arm/fsl.txt +++ b/Documentation/devicetree/bindings/arm/fsl.txt @@ -108,7 +108,7 @@ status. - compatible: Should contain a chip-specific compatible string, Chip-specific strings are of the form "fsl,<chip>-scfg", The following <chip>s are known to be supported: - ls1021a, ls1043a, ls1046a, ls2080a. + ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. - reg: should contain base address and length of SCFG memory-mapped registers @@ -126,7 +126,7 @@ core start address and release the secondary core from holdoff and startup. - compatible: Should contain a chip-specific compatible string, Chip-specific strings are of the form "fsl,<chip>-dcfg", The following <chip>s are known to be supported: - ls1021a, ls1043a, ls1046a, ls2080a. + ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. - reg : should contain base address and length of DCFG memory-mapped registers @@ -139,6 +139,22 @@ Example: Freescale ARMv8 based Layerscape SoC family Device Tree Bindings ---------------------------------------------------------------- +LS1012A SoC +Required root node properties: + - compatible = "fsl,ls1012a"; + +LS1012A ARMv8 based RDB Board +Required root node properties: + - compatible = "fsl,ls1012a-rdb", "fsl,ls1012a"; + +LS1012A ARMv8 based FRDM Board +Required root node properties: + - compatible = "fsl,ls1012a-frdm", "fsl,ls1012a"; + +LS1012A ARMv8 based QDS Board +Required root node properties: + - compatible = "fsl,ls1012a-qds", "fsl,ls1012a"; + LS1043A SoC Required root node properties: - compatible = "fsl,ls1043a"; diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index 7df79a715611..f1c1e21a8110 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -1,5 +1,9 @@ Hisilicon Platforms Device Tree Bindings ---------------------------------------------------- +Hi3660 SoC +Required root node properties: + - compatible = "hisilicon,hi3660"; + Hi4511 Board Required root node properties: - compatible = "hisilicon,hi3620-hi4511"; diff --git a/Documentation/devicetree/bindings/arm/marvell/98dx3236-resume-ctrl.txt b/Documentation/devicetree/bindings/arm/marvell/98dx3236-resume-ctrl.txt new file mode 100644 index 000000000000..26eb9d3aa630 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/marvell/98dx3236-resume-ctrl.txt @@ -0,0 +1,16 @@ +Resume Control +-------------- +Available on Marvell SOCs: 98DX3336 and 98DX4251 + +Required properties: + +- compatible: must be "marvell,98dx3336-resume-ctrl" + +- reg: Should contain resume control registers location and length + +Example: + +resume@20980 { + compatible = "marvell,98dx3336-resume-ctrl"; + reg = <0x20980 0x10>; +}; diff --git a/Documentation/devicetree/bindings/arm/marvell/98dx3236.txt b/Documentation/devicetree/bindings/arm/marvell/98dx3236.txt new file mode 100644 index 000000000000..64e8c73fc5ab --- /dev/null +++ b/Documentation/devicetree/bindings/arm/marvell/98dx3236.txt @@ -0,0 +1,23 @@ +Marvell 98DX3236, 98DX3336 and 98DX4251 Platforms Device Tree Bindings +---------------------------------------------------------------------- + +Boards with a SoC of the Marvell 98DX3236, 98DX3336 and 98DX4251 families +shall have the following property: + +Required root node property: + +compatible: must contain "marvell,armadaxp-98dx3236" + +In addition, boards using the Marvell 98DX3336 SoC shall have the +following property: + +Required root node property: + +compatible: must contain "marvell,armadaxp-98dx3336" + +In addition, boards using the Marvell 98DX4251 SoC shall have the +following property: + +Required root node property: + +compatible: must contain "marvell,armadaxp-98dx4251" diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index 05f95c3ed7d4..8219b2c6bb29 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -151,6 +151,9 @@ Boards: - AM335X SBC-T335 : single board computer, built around the Sitara AM3352/4 compatible = "compulab,sbc-t335", "compulab,cm-t335", "ti,am33xx" +- AM335X phyCORE-AM335x: Development kit + compatible = "phytec,am335x-pcm-953", "phytec,am335x-phycore-som", "ti,am33xx" + - OMAP5 EVM : Evaluation Module compatible = "ti,omap5-evm", "ti,omap5" diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt index 253bf9b86690..c9502634316d 100644 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ b/Documentation/devicetree/bindings/arm/shmobile.txt @@ -75,7 +75,7 @@ Boards: compatible = "renesas,rskrza1", "renesas,r7s72100" - Salvator-X (RTP0RC7795SIPB0010S) compatible = "renesas,salvator-x", "renesas,r8a7795"; - - Salvator-X + - Salvator-X (RTP0RC7796SIPB0011S) compatible = "renesas,salvator-x", "renesas,r8a7796"; - SILK (RTP0RC7794LCB00011S) compatible = "renesas,silk", "renesas,r8a7794" diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt index 4d6467cc2aa2..d2c46449b4eb 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.txt +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -12,6 +12,7 @@ using one of the following compatible strings: allwinner,sun8i-a23 allwinner,sun8i-a33 allwinner,sun8i-a83t + allwinner,sun8i-h2-plus allwinner,sun8i-h3 allwinner,sun9i-a80 allwinner,sun50i-a64 diff --git a/Documentation/devicetree/bindings/ata/ahci-da850.txt b/Documentation/devicetree/bindings/ata/ahci-da850.txt new file mode 100644 index 000000000000..5f8193417725 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/ahci-da850.txt @@ -0,0 +1,18 @@ +Device tree binding for the TI DA850 AHCI SATA Controller +--------------------------------------------------------- + +Required properties: + - compatible: must be "ti,da850-ahci" + - reg: physical base addresses and sizes of the two register regions + used by the controller: the register map as defined by the + AHCI 1.1 standard and the Power Down Control Register (PWRDN) + for enabling/disabling the SATA clock receiver + - interrupts: interrupt specifier (refer to the interrupt binding) + +Example: + + sata: sata@218000 { + compatible = "ti,da850-ahci"; + reg = <0x218000 0x2000>, <0x22c018 0x4>; + interrupts = <67>; + }; diff --git a/Documentation/devicetree/bindings/bus/qcom,ebi2.txt b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt index 920681f552db..5a7d567f6833 100644 --- a/Documentation/devicetree/bindings/bus/qcom,ebi2.txt +++ b/Documentation/devicetree/bindings/bus/qcom,ebi2.txt @@ -51,7 +51,7 @@ Required properties: - compatible: should be one of: "qcom,msm8660-ebi2" "qcom,apq8060-ebi2" -- #address-cells: shoule be <2>: the first cell is the chipselect, +- #address-cells: should 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: @@ -64,7 +64,7 @@ Required properties: - 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" +- clock-names: should be "ebi2x", "ebi2" Optional subnodes: - Nodes inside the EBI2 will be considered device nodes. @@ -100,7 +100,7 @@ Optional properties arrays for FAST chip selects: 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 + read transfer. For a single read transfer this will be the time from CS assertion to OE assertion. Valid values 0 thru 15. diff --git a/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt index e56a1df3a9d3..dd906db34b32 100644 --- a/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt +++ b/Documentation/devicetree/bindings/clock/brcm,bcm2835-cprman.txt @@ -16,7 +16,20 @@ Required properties: - #clock-cells: Should be <1>. The permitted clock-specifier values can be found in include/dt-bindings/clock/bcm2835.h - reg: Specifies base physical address and size of the registers -- clocks: The external oscillator clock phandle +- clocks: phandles to the parent clocks used as input to the module, in + the following order: + + - External oscillator + - DSI0 byte clock + - DSI0 DDR2 clock + - DSI0 DDR clock + - DSI1 byte clock + - DSI1 DDR2 clock + - DSI1 DDR clock + + Only external oscillator is required. The DSI clocks may + not be present, in which case their children will be + unusable. Example: diff --git a/Documentation/devicetree/bindings/clock/exynos4415-clock.txt b/Documentation/devicetree/bindings/clock/exynos4415-clock.txt deleted file mode 100644 index 847d98bae8cf..000000000000 --- a/Documentation/devicetree/bindings/clock/exynos4415-clock.txt +++ /dev/null @@ -1,38 +0,0 @@ -* Samsung Exynos4415 Clock Controller - -The Exynos4415 clock controller generates and supplies clock to various -consumer devices within the Exynos4415 SoC. - -Required properties: - -- compatible: should be one of the following: - - "samsung,exynos4415-cmu" - for the main system clocks controller - (CMU_LEFTBUS, CMU_RIGHTBUS, CMU_TOP, CMU_CPU clock domains). - - "samsung,exynos4415-cmu-dmc" - for the Exynos4415 SoC DRAM Memory - Controller (DMC) domain clock controller. - -- reg: physical base address of the 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 -dt-bindings/clock/exynos4415.h header and can be used in device -tree sources. - -Example 1: An example of a clock controller node is listed below. - - cmu: clock-controller@10030000 { - compatible = "samsung,exynos4415-cmu"; - reg = <0x10030000 0x18000>; - #clock-cells = <1>; - }; - - cmu-dmc: clock-controller@105C0000 { - compatible = "samsung,exynos4415-cmu-dmc"; - reg = <0x105C0000 0x3000>; - #clock-cells = <1>; - }; diff --git a/Documentation/devicetree/bindings/clock/hi3660-clock.txt b/Documentation/devicetree/bindings/clock/hi3660-clock.txt new file mode 100644 index 000000000000..cc9b86c35758 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/hi3660-clock.txt @@ -0,0 +1,42 @@ +* Hisilicon Hi3660 Clock Controller + +The Hi3660 clock controller generates and supplies clock to various +controllers within the Hi3660 SoC. + +Required Properties: + +- compatible: the compatible should be one of the following strings to + indicate the clock controller functionality. + + - "hisilicon,hi3660-crgctrl" + - "hisilicon,hi3660-pctrl" + - "hisilicon,hi3660-pmuctrl" + - "hisilicon,hi3660-sctrl" + - "hisilicon,hi3660-iomcu" + +- reg: physical base address of the controller and length of memory mapped + region. + +- #clock-cells: should be 1. + +Each clock is assigned an identifier and client nodes use this identifier +to specify the clock which they consume. + +All these identifier could be found in <dt-bindings/clock/hi3660-clock.h>. + +Examples: + crg_ctrl: clock-controller@fff35000 { + compatible = "hisilicon,hi3660-crgctrl", "syscon"; + reg = <0x0 0xfff35000 0x0 0x1000>; + #clock-cells = <1>; + }; + + uart0: serial@fdf02000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0x0 0xfdf02000 0x0 0x1000>; + interrupts = <GIC_SPI 74 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&crg_ctrl HI3660_CLK_MUX_UART0>, + <&crg_ctrl HI3660_PCLK>; + clock-names = "uartclk", "apb_pclk"; + status = "disabled"; + }; diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.txt b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt new file mode 100644 index 000000000000..87e9c47a89a3 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.txt @@ -0,0 +1,65 @@ +Binding for IDT VersaClock5 programmable i2c clock generator. + +The IDT VersaClock5 are programmable i2c clock generators providing +from 3 to 12 output clocks. + +==I2C device node== + +Required properties: +- compatible: shall be one of "idt,5p49v5923" , "idt,5p49v5933". +- reg: i2c device address, shall be 0x68 or 0x6a. +- #clock-cells: from common clock binding; shall be set to 1. +- clocks: from common clock binding; list of parent clock handles, + - 5p49v5923: (required) either or both of XTAL or CLKIN + reference clock. + - 5p49v5933: (optional) property not present (internal + Xtal used) or CLKIN reference + clock. +- clock-names: from common clock binding; clock input names, can be + - 5p49v5923: (required) either or both of "xin", "clkin". + - 5p49v5933: (optional) property not present or "clkin". + +==Mapping between clock specifier and physical pins== + +When referencing the provided clock in the DT using phandle and +clock specifier, the following mapping applies: + +5P49V5923: + 0 -- OUT0_SEL_I2CB + 1 -- OUT1 + 2 -- OUT2 + +5P49V5933: + 0 -- OUT0_SEL_I2CB + 1 -- OUT1 + 2 -- OUT4 + +==Example== + +/* 25MHz reference crystal */ +ref25: ref25m { + compatible = "fixed-clock"; + #clock-cells = <0>; + clock-frequency = <25000000>; +}; + +i2c-master-node { + + /* IDT 5P49V5923 i2c clock generator */ + vc5: clock-generator@6a { + compatible = "idt,5p49v5923"; + reg = <0x6a>; + #clock-cells = <1>; + + /* Connect XIN input to 25MHz reference */ + clocks = <&ref25m>; + clock-names = "xin"; + }; +}; + +/* Consumer referencing the 5P49V5923 pin OUT1 */ +consumer { + ... + clocks = <&vc5 1>; + ... +} diff --git a/Documentation/devicetree/bindings/clock/mvebu-corediv-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-corediv-clock.txt index 520562a7dc2a..c7b4e3a6b2c6 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-corediv-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-corediv-clock.txt @@ -7,6 +7,7 @@ Required properties: - compatible : must be "marvell,armada-370-corediv-clock", "marvell,armada-375-corediv-clock", "marvell,armada-380-corediv-clock", + "marvell,mv98dx3236-corediv-clock", - reg : must be the register address of Core Divider control register - #clock-cells : from common clock binding; shall be set to 1 diff --git a/Documentation/devicetree/bindings/clock/mvebu-cpu-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-cpu-clock.txt index 99c214660bdc..7f28506eaee7 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-cpu-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-cpu-clock.txt @@ -3,6 +3,7 @@ Device Tree Clock bindings for cpu clock of Marvell EBU platforms Required properties: - compatible : shall be one of the following: "marvell,armada-xp-cpu-clock" - cpu clocks for Armada XP + "marvell,mv98dx3236-cpu-clock" - cpu clocks for 98DX3236 SoC - reg : Address and length of the clock complex register set, followed by address and length of the PMU DFS registers - #clock-cells : should be set to 1. diff --git a/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt b/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt index cb8542d910b3..5142efc8099d 100644 --- a/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt +++ b/Documentation/devicetree/bindings/clock/mvebu-gated-clock.txt @@ -117,7 +117,7 @@ ID Clock Peripheral 25 tdm Time Division Mplx 28 xor1 XOR DMA 1 29 sata1lnk -30 sata1 SATA Host 0 +30 sata1 SATA Host 1 The following is a list of provided IDs for Dove: ID Clock Peripheral diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt index 87d3714b956a..a7235e9e1c97 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt @@ -11,6 +11,7 @@ Required properties : compatible "qcom,rpmcc" should be also included. "qcom,rpmcc-msm8916", "qcom,rpmcc" + "qcom,rpmcc-msm8974", "qcom,rpmcc" "qcom,rpmcc-apq8064", "qcom,rpmcc" - #clock-cells : shall contain 1 diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index df9cb5ac5f72..aa3526f229a7 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -31,6 +31,7 @@ Required properties: * "fsl,t4240-clockgen" * "fsl,b4420-clockgen" * "fsl,b4860-clockgen" + * "fsl,ls1012a-clockgen" * "fsl,ls1021a-clockgen" * "fsl,ls1043a-clockgen" * "fsl,ls1046a-clockgen" diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt index c46919412953..f4f944d81308 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -42,6 +42,10 @@ Required Properties: Domain bindings in Documentation/devicetree/bindings/power/power_domain.txt. + - #reset-cells: Must be 1 + - The single reset specifier cell must be the module number, as defined + in the datasheet. + Examples -------- @@ -55,6 +59,7 @@ Examples clock-names = "extal", "extalr"; #clock-cells = <2>; #power-domain-cells = <0>; + #reset-cells = <1>; }; @@ -69,5 +74,6 @@ Examples dmas = <&dmac1 0x13>, <&dmac1 0x12>; dma-names = "tx", "rx"; power-domains = <&cpg>; + resets = <&cpg 310>; status = "disabled"; }; diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt new file mode 100644 index 000000000000..e71c675ba5da --- /dev/null +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3328-cru.txt @@ -0,0 +1,57 @@ +* Rockchip RK3328 Clock and Reset Unit + +The RK3328 clock controller generates and supplies clock to various +controllers within the SoC and also implements a reset controller for SoC +peripherals. + +Required Properties: + +- compatible: should be "rockchip,rk3328-cru" +- reg: physical base address of the controller and length of memory mapped + region. +- #clock-cells: should be 1. +- #reset-cells: should be 1. + +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files" + If missing pll rates are not changeable, due to the missing pll lock status. + +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/rk3328-cru.h headers and can be +used in device tree sources. Similar macros exist for the reset sources in +these files. + +External clocks: + +There are several clocks that are generated outside the SoC. It is expected +that they are defined using standard clock bindings with following +clock-output-names: + - "xin24m" - crystal input - required, + - "clkin_i2s" - external I2S clock - optional, + - "gmac_clkin" - external GMAC clock - optional + - "phy_50m_out" - output clock of the pll in the mac phy + +Example: Clock controller node: + + cru: clock-controller@ff440000 { + compatible = "rockchip,rk3328-cru"; + reg = <0x0 0xff440000 0x0 0x1000>; + rockchip,grf = <&grf>; + + #clock-cells = <1>; + #reset-cells = <1>; + }; + +Example: UART controller node that consumes the clock generated by the clock + controller: + + uart0: serial@ff120000 { + compatible = "snps,dw-apb-uart"; + reg = <0xff120000 0x100>; + interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>; + reg-shift = <2>; + reg-io-width = <4>; + clocks = <&cru SCLK_UART0>; + }; diff --git a/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt b/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt index 3888dd33fcbd..3bc56fae90ac 100644 --- a/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt +++ b/Documentation/devicetree/bindings/clock/rockchip,rk3399-cru.txt @@ -13,6 +13,12 @@ Required Properties: - #clock-cells: should be 1. - #reset-cells: should be 1. +Optional Properties: + +- rockchip,grf: phandle to the syscon managing the "general register files". + It is used for GRF muxes, if missing any muxes present in the GRF will not + be available. + 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/rk3399-cru.h headers and can be diff --git a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt index 0532d815dae3..b240121d2ac9 100644 --- a/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt +++ b/Documentation/devicetree/bindings/clock/st,stm32-rcc.txt @@ -10,6 +10,7 @@ Required properties: - compatible: Should be: "st,stm32f42xx-rcc" "st,stm32f469-rcc" + "st,stm32f746-rcc" - reg: should be register base and length as documented in the datasheet - #reset-cells: 1, see below @@ -17,6 +18,9 @@ Required properties: 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 use. +- clocks: External oscillator clock phandle + - high speed external clock signal (HSE) + - external I2S clock (I2S_CKIN) Example: @@ -25,6 +29,7 @@ Example: #clock-cells = <2> compatible = "st,stm32f42xx-rcc", "st,stm32-rcc"; reg = <0x40023800 0x400>; + clocks = <&clk_hse>, <&clk_i2s_ckin>; }; Specifying gated clocks @@ -66,6 +71,38 @@ The secondary index is bound with the following magic numbers: 0 SYSTICK 1 FCLK + 2 CLK_LSI (low-power clock source) + 3 CLK_LSE (generated from a 32.768 kHz low-speed external + crystal or ceramic resonator) + 4 CLK_HSE_RTC (HSE division factor for RTC clock) + 5 CLK_RTC (real-time clock) + 6 PLL_VCO_I2S (vco frequency of I2S pll) + 7 PLL_VCO_SAI (vco frequency of SAI pll) + 8 CLK_LCD (LCD-TFT) + 9 CLK_I2S (I2S clocks) + 10 CLK_SAI1 (audio clocks) + 11 CLK_SAI2 + 12 CLK_I2SQ_PDIV (post divisor of pll i2s q divisor) + 13 CLK_SAIQ_PDIV (post divisor of pll sai q divisor) + + 14 CLK_HSI (Internal ocscillator clock) + 15 CLK_SYSCLK (System Clock) + 16 CLK_HDMI_CEC (HDMI-CEC clock) + 17 CLK_SPDIF (SPDIF-Rx clock) + 18 CLK_USART1 (U(s)arts clocks) + 19 CLK_USART2 + 20 CLK_USART3 + 21 CLK_UART4 + 22 CLK_UART5 + 23 CLK_USART6 + 24 CLK_UART7 + 25 CLK_UART8 + 26 CLK_I2C1 (I2S clocks) + 27 CLK_I2C2 + 28 CLK_I2C3 + 29 CLK_I2C4 + 30 CLK_LPTIMER (LPTimer1 clock) +) Example: diff --git a/Documentation/devicetree/bindings/clock/stericsson,abx500.txt b/Documentation/devicetree/bindings/clock/stericsson,abx500.txt new file mode 100644 index 000000000000..dbaa886b223e --- /dev/null +++ b/Documentation/devicetree/bindings/clock/stericsson,abx500.txt @@ -0,0 +1,20 @@ +Clock bindings for ST-Ericsson ABx500 clocks + +Required properties : +- compatible : shall contain the following: + "stericsson,ab8500-clk" +- #clock-cells should be <1> + +The ABx500 clocks need to be placed as a subnode of an AB8500 +device node, see mfd/ab8500.txt + +All available clocks are defined as preprocessor macros in +dt-bindings/clock/ste-ab8500.h header and can be used in device +tree sources. + +Example: + +clock-controller { + compatible = "stericsson,ab8500-clk"; + #clock-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/sun9i-de.txt b/Documentation/devicetree/bindings/clock/sun9i-de.txt new file mode 100644 index 000000000000..fb18f327b97a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sun9i-de.txt @@ -0,0 +1,28 @@ +Allwinner A80 Display Engine Clock Control Binding +-------------------------------------------------- + +Required properties : +- compatible: must contain one of the following compatibles: + - "allwinner,sun9i-a80-de-clks" + +- reg: Must contain the registers base address and length +- clocks: phandle to the clocks feeding the display engine subsystem. + Three are needed: + - "mod": the display engine module clock + - "dram": the DRAM bus clock for the system + - "bus": the bus clock for the whole display engine subsystem +- clock-names: Must contain the clock names described just above +- resets: phandle to the reset control for the display engine subsystem. +- #clock-cells : must contain 1 +- #reset-cells : must contain 1 + +Example: +de_clocks: clock@3000000 { + compatible = "allwinner,sun9i-a80-de-clks"; + reg = <0x03000000 0x30>; + clocks = <&ccu CLK_DE>, <&ccu CLK_SDRAM>, <&ccu CLK_BUS_DE>; + clock-names = "mod", "dram", "bus"; + resets = <&ccu RST_BUS_DE>; + #clock-cells = <1>; + #reset-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/sun9i-usb.txt b/Documentation/devicetree/bindings/clock/sun9i-usb.txt new file mode 100644 index 000000000000..3564bd4f2a20 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/sun9i-usb.txt @@ -0,0 +1,24 @@ +Allwinner A80 USB Clock Control Binding +--------------------------------------- + +Required properties : +- compatible: must contain one of the following compatibles: + - "allwinner,sun9i-a80-usb-clocks" + +- reg: Must contain the registers base address and length +- clocks: phandle to the clocks feeding the USB subsystem. Two are needed: + - "bus": the bus clock for the whole USB subsystem + - "hosc": the high frequency oscillator (usually at 24MHz) +- clock-names: Must contain the clock names described just above +- #clock-cells : must contain 1 +- #reset-cells : must contain 1 + +Example: +usb_clocks: clock@a08000 { + compatible = "allwinner,sun9i-a80-usb-clks"; + reg = <0x00a08000 0x8>; + clocks = <&ccu CLK_BUS_USB>, <&osc24M>; + clock-names = "bus", "hosc"; + #clock-cells = <1>; + #reset-cells = <1>; +}; diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt index 74d44a4273f2..bae5668cf427 100644 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt @@ -7,6 +7,8 @@ Required properties : - "allwinner,sun8i-a23-ccu" - "allwinner,sun8i-a33-ccu" - "allwinner,sun8i-h3-ccu" + - "allwinner,sun8i-v3s-ccu" + - "allwinner,sun9i-a80-ccu" - "allwinner,sun50i-a64-ccu" - reg: Must contain the registers base address and length diff --git a/Documentation/devicetree/bindings/clock/ti,cdce925.txt b/Documentation/devicetree/bindings/clock/ti,cdce925.txt index 4c7669ad681b..0d01f2d5cc36 100644 --- a/Documentation/devicetree/bindings/clock/ti,cdce925.txt +++ b/Documentation/devicetree/bindings/clock/ti,cdce925.txt @@ -1,15 +1,22 @@ -Binding for TO CDCE925 programmable I2C clock synthesizers. +Binding for TI CDCE913/925/937/949 programmable I2C clock synthesizers. Reference This binding uses the common clock binding[1]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt -[2] http://www.ti.com/product/cdce925 +[2] http://www.ti.com/product/cdce913 +[3] http://www.ti.com/product/cdce925 +[4] http://www.ti.com/product/cdce937 +[5] http://www.ti.com/product/cdce949 The driver provides clock sources for each output Y1 through Y5. Required properties: - - compatible: Shall be "ti,cdce925" + - compatible: Shall be one of the following: + - "ti,cdce913": 1-PLL, 3 Outputs + - "ti,cdce925": 2-PLL, 5 Outputs + - "ti,cdce937": 3-PLL, 7 Outputs + - "ti,cdce949": 4-PLL, 9 Outputs - reg: I2C device address. - clocks: Points to a fixed parent clock that provides the input frequency. - #clock-cells: From common clock bindings: Shall be 1. @@ -18,7 +25,7 @@ Optional properties: - xtal-load-pf: Crystal load-capacitor value to fine-tune performance on a board, or to compensate for external influences. -For both PLL1 and PLL2 an optional child node can be used to specify spread +For all PLL1, PLL2, ... an optional child node can be used to specify spread spectrum clocking parameters for a board. - spread-spectrum: SSC mode as defined in the data sheet. - spread-spectrum-center: Use "centered" mode instead of "max" mode. When diff --git a/Documentation/devicetree/bindings/clock/zx296718-clk.txt b/Documentation/devicetree/bindings/clock/zx296718-clk.txt index 8c18b7b237bf..4ad703808407 100644 --- a/Documentation/devicetree/bindings/clock/zx296718-clk.txt +++ b/Documentation/devicetree/bindings/clock/zx296718-clk.txt @@ -13,6 +13,9 @@ Required properties: "zte,zx296718-lsp1crm": zx296718 device level clock selection and gating + "zte,zx296718-audiocrm": + zx296718 audio clock selection, divider and gating + - reg: Address and length of the register set The clock consumer should specify the desired clock by having the clock diff --git a/Documentation/devicetree/bindings/crypto/brcm,spu-crypto.txt b/Documentation/devicetree/bindings/crypto/brcm,spu-crypto.txt new file mode 100644 index 000000000000..29b6007568eb --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/brcm,spu-crypto.txt @@ -0,0 +1,22 @@ +The Broadcom Secure Processing Unit (SPU) hardware supports symmetric +cryptographic offload for Broadcom SoCs. A SoC may have multiple SPU hardware +blocks. + +Required properties: +- compatible: Should be one of the following: + brcm,spum-crypto - for devices with SPU-M hardware + brcm,spu2-crypto - for devices with SPU2 hardware + brcm,spu2-v2-crypto - for devices with enhanced SPU2 hardware features like SHA3 + and Rabin Fingerprint support + brcm,spum-nsp-crypto - for the Northstar Plus variant of the SPU-M hardware + +- reg: Should contain SPU registers location and length. +- mboxes: The mailbox channel to be used to communicate with the SPU. + Mailbox channels correspond to DMA rings on the device. + +Example: + crypto@612d0000 { + compatible = "brcm,spum-crypto"; + reg = <0 0x612d0000 0 0x900>; + mboxes = <&pdc0 0>; + }; diff --git a/Documentation/devicetree/bindings/crypto/mediatek-crypto.txt b/Documentation/devicetree/bindings/crypto/mediatek-crypto.txt new file mode 100644 index 000000000000..c204725e5873 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/mediatek-crypto.txt @@ -0,0 +1,27 @@ +MediaTek cryptographic accelerators + +Required properties: +- compatible: Should be "mediatek,eip97-crypto" +- reg: Address and length of the register set for the device +- interrupts: Should contain the five crypto engines interrupts in numeric + order. These are global system and four descriptor rings. +- clocks: the clock used by the core +- clock-names: the names of the clock listed in the clocks property. These are + "ethif", "cryp" +- power-domains: Must contain a reference to the PM domain. + + +Example: + crypto: crypto@1b240000 { + compatible = "mediatek,eip97-crypto"; + reg = <0 0x1b240000 0 0x20000>; + interrupts = <GIC_SPI 82 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 83 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 84 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 91 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 97 IRQ_TYPE_LEVEL_LOW>; + clocks = <&topckgen CLK_TOP_ETHIF_SEL>, + <ðsys CLK_ETHSYS_CRYPTO>; + clock-names = "ethif","cryp"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_ETH>; + }; diff --git a/Documentation/devicetree/bindings/display/arm,pl11x.txt b/Documentation/devicetree/bindings/display/arm,pl11x.txt index 3e3039a8a253..ef89ab46b2c9 100644 --- a/Documentation/devicetree/bindings/display/arm,pl11x.txt +++ b/Documentation/devicetree/bindings/display/arm,pl11x.txt @@ -22,7 +22,7 @@ Required properties: - clocks: contains phandle and clock specifier pairs for the entries in the clock-names property. See - Documentation/devicetree/binding/clock/clock-bindings.txt + Documentation/devicetree/bindings/clock/clock-bindings.txt Optional properties: diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt index e2768703ac2b..34c7fddcea39 100644 --- a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt +++ b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt @@ -56,6 +56,18 @@ Required properties for V3D: - interrupts: The interrupt number See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt +Required properties for DSI: +- compatible: Should be "brcm,bcm2835-dsi0" or "brcm,bcm2835-dsi1" +- reg: Physical base address and length of the DSI block's registers +- interrupts: The interrupt number + See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt +- clocks: a) phy: The DSI PLL clock feeding the DSI analog PHY + b) escape: The DSI ESC clock from CPRMAN + c) pixel: The DSI pixel clock from CPRMAN +- clock-output-names: + The 3 clocks output from the DSI analog PHY: dsi[01]_byte, + dsi[01]_ddr2, and dsi[01]_ddr + [1] Documentation/devicetree/bindings/media/video-interfaces.txt Example: @@ -99,6 +111,29 @@ dpi: dpi@7e208000 { }; }; +dsi1: dsi@7e700000 { + compatible = "brcm,bcm2835-dsi1"; + reg = <0x7e700000 0x8c>; + interrupts = <2 12>; + #address-cells = <1>; + #size-cells = <0>; + #clock-cells = <1>; + + clocks = <&clocks BCM2835_PLLD_DSI1>, + <&clocks BCM2835_CLOCK_DSI1E>, + <&clocks BCM2835_CLOCK_DSI1P>; + clock-names = "phy", "escape", "pixel"; + + clock-output-names = "dsi1_byte", "dsi1_ddr2", "dsi1_ddr"; + + pitouchscreen: panel@0 { + compatible = "raspberrypi,touchscreen"; + reg = <0>; + + <...> + }; +}; + vec: vec@7e806000 { compatible = "brcm,bcm2835-vec"; reg = <0x7e806000 0x1000>; diff --git a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt index 6532a59c9b43..00ea670b8c4d 100644 --- a/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt +++ b/Documentation/devicetree/bindings/display/bridge/adi,adv7511.txt @@ -38,10 +38,22 @@ The following input format properties are required except in "rgb 1x" and - adi,input-justification: The input bit justification ("left", "evenly", "right"). +- avdd-supply: A 1.8V supply that powers up the AVDD pin on the chip. +- dvdd-supply: A 1.8V supply that powers up the DVDD pin on the chip. +- pvdd-supply: A 1.8V supply that powers up the PVDD pin on the chip. +- dvdd-3v-supply: A 3.3V supply that powers up the pin called DVDD_3V + on the chip. +- bgvdd-supply: A 1.8V supply that powers up the BGVDD pin. This is + needed only for ADV7511. + The following properties are required for ADV7533: - adi,dsi-lanes: Number of DSI data lanes connected to the DSI host. It should be one of 1, 2, 3 or 4. +- a2vdd-supply: 1.8V supply that powers up the A2VDD pin on the chip. +- v3p3-supply: A 3.3V supply that powers up the V3P3 pin on the chip. +- v1p2-supply: A supply that powers up the V1P2 pin on the chip. It can be + either 1.2V or 1.8V. Optional properties: diff --git a/Documentation/devicetree/bindings/display/bridge/analogix_dp.txt b/Documentation/devicetree/bindings/display/bridge/analogix_dp.txt index 4a0f4f7682ad..0c7473dd0e51 100644 --- a/Documentation/devicetree/bindings/display/bridge/analogix_dp.txt +++ b/Documentation/devicetree/bindings/display/bridge/analogix_dp.txt @@ -33,7 +33,7 @@ Optional properties for dp-controller: in Documentation/devicetree/bindings/media/video-interfaces.txt, please refer to the SoC specific binding document: * Documentation/devicetree/bindings/display/exynos/exynos_dp.txt - * Documentation/devicetree/bindings/video/analogix_dp-rockchip.txt + * Documentation/devicetree/bindings/display/rockchip/analogix_dp-rockchip.txt [1]: Documentation/devicetree/bindings/media/video-interfaces.txt ------------------------------------------------------------------------------- diff --git a/Documentation/devicetree/bindings/video/bridge/anx7814.txt b/Documentation/devicetree/bindings/display/bridge/anx7814.txt index b2a22c28c9b3..b2a22c28c9b3 100644 --- a/Documentation/devicetree/bindings/video/bridge/anx7814.txt +++ b/Documentation/devicetree/bindings/display/bridge/anx7814.txt diff --git a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt index 5e9a84d6e5f1..33bf981fbe33 100644 --- a/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt +++ b/Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt @@ -1,52 +1,33 @@ -DesignWare HDMI bridge bindings - -Required properties: -- compatible: platform specific such as: - * "snps,dw-hdmi-tx" - * "fsl,imx6q-hdmi" - * "fsl,imx6dl-hdmi" - * "rockchip,rk3288-dw-hdmi" -- reg: Physical base address and length of the controller's registers. -- interrupts: The HDMI interrupt number -- clocks, clock-names : must have the phandles to the HDMI iahb and isfr clocks, - as described in Documentation/devicetree/bindings/clock/clock-bindings.txt, - the clocks are soc specific, the clock-names should be "iahb", "isfr" --port@[X]: SoC specific port nodes with endpoint definitions as defined - in Documentation/devicetree/bindings/media/video-interfaces.txt, - please refer to the SoC specific binding document: - * Documentation/devicetree/bindings/display/imx/hdmi.txt - * Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt - -Optional properties -- reg-io-width: the width of the reg:1,4, default set to 1 if not present -- ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing, - if the property is omitted, a functionally reduced I2C bus - controller on DW HDMI is probed -- clocks, clock-names: phandle to the HDMI CEC clock, name should be "cec" - -Example: - hdmi: hdmi@0120000 { - compatible = "fsl,imx6q-hdmi"; - reg = <0x00120000 0x9000>; - interrupts = <0 115 0x04>; - gpr = <&gpr>; - clocks = <&clks 123>, <&clks 124>; - clock-names = "iahb", "isfr"; - ddc-i2c-bus = <&i2c2>; - - port@0 { - reg = <0>; - - hdmi_mux_0: endpoint { - remote-endpoint = <&ipu1_di0_hdmi>; - }; - }; - - port@1 { - reg = <1>; - - hdmi_mux_1: endpoint { - remote-endpoint = <&ipu1_di1_hdmi>; - }; - }; - }; +Synopsys DesignWare HDMI TX Encoder +=================================== + +This document defines device tree properties for the Synopsys DesignWare HDMI +TX Encoder (DWC HDMI TX). It doesn't constitue a device tree binding +specification by itself but is meant to be referenced by platform-specific +device tree bindings. + +When referenced from platform device tree bindings the properties defined in +this document are defined as follows. The platform device tree bindings are +responsible for defining whether each property is required or optional. + +- reg: Memory mapped base address and length of the DWC HDMI TX registers. + +- reg-io-width: Width of the registers specified by the reg property. The + value is expressed in bytes and must be equal to 1 or 4 if specified. The + register width defaults to 1 if the property is not present. + +- interrupts: Reference to the DWC HDMI TX interrupt. + +- clocks: References to all the clocks specified in the clock-names property + as specified in Documentation/devicetree/bindings/clock/clock-bindings.txt. + +- clock-names: The DWC HDMI TX uses the following clocks. + + - "iahb" is the bus clock for either AHB and APB (mandatory). + - "isfr" is the internal register configuration clock (mandatory). + - "cec" is the HDMI CEC controller main clock (optional). + +- ports: The connectivity of the DWC HDMI TX with the rest of the system is + expressed in using ports as specified in the device graph bindings defined + in Documentation/devicetree/bindings/graph.txt. The numbering of the ports + is platform-specific. diff --git a/Documentation/devicetree/bindings/video/bridge/sil-sii8620.txt b/Documentation/devicetree/bindings/display/bridge/sil-sii8620.txt index 9409d9c6a260..9409d9c6a260 100644 --- a/Documentation/devicetree/bindings/video/bridge/sil-sii8620.txt +++ b/Documentation/devicetree/bindings/display/bridge/sil-sii8620.txt diff --git a/Documentation/devicetree/bindings/display/bridge/ti,ths8135.txt b/Documentation/devicetree/bindings/display/bridge/ti,ths8135.txt new file mode 100644 index 000000000000..6ec1a880ac18 --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/ti,ths8135.txt @@ -0,0 +1,46 @@ +THS8135 Video DAC +----------------- + +This is the binding for Texas Instruments THS8135 Video DAC bridge. + +Required properties: + +- compatible: Must be "ti,ths8135" + +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 +------- + +vga-bridge { + compatible = "ti,ths8135"; + #address-cells = <1>; + #size-cells = <0>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + vga_bridge_in: endpoint { + remote-endpoint = <&lcdc_out_vga>; + }; + }; + + port@1 { + reg = <1>; + + vga_bridge_out: endpoint { + remote-endpoint = <&vga_con_in>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt index e9c65746e2f1..b0e506610400 100644 --- a/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt +++ b/Documentation/devicetree/bindings/display/cirrus,clps711x-fb.txt @@ -6,7 +6,7 @@ Required properties: location and size of the framebuffer memory. - clocks : phandle + clock specifier pair of the FB reference clock. - display : phandle to a display node as described in - Documentation/devicetree/bindings/display/display-timing.txt. + Documentation/devicetree/bindings/display/panel/display-timing.txt. Additionally, the display node has to define properties: - bits-per-pixel: Bits per pixel. - ac-prescale : LCD AC bias frequency. This frequency is the required diff --git a/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt b/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt index 3938caacf11c..9e2e7f6f7609 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos7-decon.txt @@ -33,12 +33,12 @@ Required properties: - i80-if-timings: timing configuration for lcd i80 interface support. Optional Properties: -- samsung,power-domain: a phandle to DECON power domain node. +- power-domains: a phandle to DECON power domain node. - display-timings: timing settings for DECON, as described in document [1]. Can be used in case timings cannot be provided otherwise or to override timings provided by the panel. -[1]: Documentation/devicetree/bindings/display/display-timing.txt +[1]: Documentation/devicetree/bindings/display/panel/display-timing.txt Example: diff --git a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt index c7c6b9af87ac..18645e0228b0 100644 --- a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt +++ b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt @@ -83,7 +83,7 @@ in [2]. The following are properties specific to those nodes: 3 - for parallel output, 4 - for write-back interface -[1]: Documentation/devicetree/bindings/display/display-timing.txt +[1]: Documentation/devicetree/bindings/display/panel/display-timing.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: diff --git a/Documentation/devicetree/bindings/display/hisilicon/hisi-ade.txt b/Documentation/devicetree/bindings/display/hisilicon/hisi-ade.txt index 38dc9d60eef8..305a0e72a900 100644 --- a/Documentation/devicetree/bindings/display/hisilicon/hisi-ade.txt +++ b/Documentation/devicetree/bindings/display/hisilicon/hisi-ade.txt @@ -16,7 +16,7 @@ Required properties: "clk_ade_core" for the ADE core clock. "clk_codec_jpeg" for the media NOC QoS clock, which use the same clock with jpeg codec. - "clk_ade_pix" for the ADE pixel clok. + "clk_ade_pix" for the ADE pixel clock. - assigned-clocks: Should contain "clk_ade_core" and "clk_codec_jpeg" clocks' phandle + clock-specifier pairs. - assigned-clock-rates: clock rates, one for each entry in assigned-clocks. diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt b/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt index 00d5f8ea7ec6..7a5c0e204c8e 100644 --- a/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx-fb.txt @@ -9,7 +9,7 @@ Required properties: Required nodes: - display: Phandle to a display node as described in - Documentation/devicetree/bindings/display/display-timing.txt + Documentation/devicetree/bindings/display/panel/display-timing.txt Additional, the display node has to define properties: - bits-per-pixel: Bits per pixel - fsl,pcr: LCDC PCR value diff --git a/Documentation/devicetree/bindings/display/imx/hdmi.txt b/Documentation/devicetree/bindings/display/imx/hdmi.txt index 1b756cf9afb0..66a8f86e5d12 100644 --- a/Documentation/devicetree/bindings/display/imx/hdmi.txt +++ b/Documentation/devicetree/bindings/display/imx/hdmi.txt @@ -1,29 +1,36 @@ -Device-Tree bindings for HDMI Transmitter +Freescale i.MX6 DWC HDMI TX Encoder +=================================== -HDMI Transmitter -================ +The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP +with a companion PHY IP. + +These DT bindings follow the Synopsys DWC HDMI TX bindings defined in +Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the +following device-specific properties. -The HDMI Transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP -with accompanying PHY IP. Required properties: - - #address-cells : should be <1> - - #size-cells : should be <0> - - compatible : should be "fsl,imx6q-hdmi" or "fsl,imx6dl-hdmi". - - gpr : should be <&gpr>. - The phandle points to the iomuxc-gpr region containing the HDMI - multiplexer control register. - - clocks, clock-names : phandles to the HDMI iahb and isrf clocks, as described - in Documentation/devicetree/bindings/clock/clock-bindings.txt and - Documentation/devicetree/bindings/clock/imx6q-clock.txt. - - port@[0-4]: Up to four port nodes with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt, - corresponding to the four inputs to the HDMI multiplexer. - -Optional properties: - - ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing - -example: + +- compatible : Shall be one of "fsl,imx6q-hdmi" or "fsl,imx6dl-hdmi". +- reg: See dw_hdmi.txt. +- interrupts: HDMI interrupt number +- clocks: See dw_hdmi.txt. +- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. +- ports: See dw_hdmi.txt. The DWC HDMI shall have between one and four ports, + numbered 0 to 3, corresponding to the four inputs of the HDMI multiplexer. + Each port shall have a single endpoint. +- gpr : Shall contain a phandle to the iomuxc-gpr region containing the HDMI + multiplexer control register. + +Optional properties + +- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master + or the functionally-reduced I2C master contained in the DWC HDMI. When + connected to a system I2C master this property contains a phandle to that + I2C master controller. + + +Example: gpr: iomuxc-gpr@020e0000 { /* ... */ diff --git a/Documentation/devicetree/bindings/display/imx/ldb.txt b/Documentation/devicetree/bindings/display/imx/ldb.txt index a407462c885e..38c637fa39dd 100644 --- a/Documentation/devicetree/bindings/display/imx/ldb.txt +++ b/Documentation/devicetree/bindings/display/imx/ldb.txt @@ -64,7 +64,7 @@ Required properties: Optional properties (required if display-timings are used): - ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing - display-timings : A node that describes the display timings as defined in - Documentation/devicetree/bindings/display/display-timing.txt. + Documentation/devicetree/bindings/display/panel/display-timing.txt. - fsl,data-mapping : should be "spwg" or "jeida" This describes how the color bits are laid out in the serialized LVDS signal. diff --git a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt index db6e77edbea8..708f5664a316 100644 --- a/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt +++ b/Documentation/devicetree/bindings/display/mediatek/mediatek,disp.txt @@ -55,7 +55,7 @@ Required properties (DMA function blocks): "mediatek,<chip>-disp-rdma" "mediatek,<chip>-disp-wdma" - larb: Should contain a phandle pointing to the local arbiter device as defined - in Documentation/devicetree/bindings/soc/mediatek/mediatek,smi-larb.txt + in Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt - iommus: Should point to the respective IOMMU block with master port as argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt for details. diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index 6b1cab17f52d..fa00e62e1cf6 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -108,7 +108,7 @@ Optional properties: - qcom,dsi-phy-regulator-ldo-mode: Boolean value indicating if the LDO mode PHY regulator is wanted. -[1] Documentation/devicetree/bindings/clocks/clock-bindings.txt +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt [2] Documentation/devicetree/bindings/graph.txt [3] Documentation/devicetree/bindings/media/video-interfaces.txt [4] Documentation/devicetree/bindings/display/panel/ diff --git a/Documentation/devicetree/bindings/display/msm/edp.txt b/Documentation/devicetree/bindings/display/msm/edp.txt index 3a20f6ea5898..e63032be5401 100644 --- a/Documentation/devicetree/bindings/display/msm/edp.txt +++ b/Documentation/devicetree/bindings/display/msm/edp.txt @@ -10,7 +10,7 @@ Required properties: - interrupts: The interrupt signal from the eDP block. - power-domains: Should be <&mmcc MDSS_GDSC>. - clocks: device clocks - See Documentation/devicetree/bindings/clocks/clock-bindings.txt for details. + See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. - clock-names: the following clocks are required: * "core_clk" * "iface_clk" diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 67d0a58dbb77..43fac0fe09bb 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -1,23 +1,19 @@ Qualcomm adreno/snapdragon GPU Required properties: -- compatible: "qcom,adreno-3xx" +- compatible: "qcom,adreno-XYZ.W", "qcom,adreno" + for example: "qcom,adreno-306.0", "qcom,adreno" + Note that you need to list the less specific "qcom,adreno" (since this + is what the device is matched on), in addition to the more specific + with the chip-id. - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt signal from the gpu. - clocks: device clocks See ../clocks/clock-bindings.txt for details. - clock-names: the following clocks are required: - * "core_clk" - * "iface_clk" - * "mem_iface_clk" -- qcom,chipid: gpu chip-id. Note this may become optional for future - devices if we can reliably read the chipid from hw -- qcom,gpu-pwrlevels: list of operating points - - compatible: "qcom,gpu-pwrlevels" - - for each qcom,gpu-pwrlevel: - - qcom,gpu-freq: requested gpu clock speed - - NOTE: downstream android driver defines additional parameters to - configure memory bandwidth scaling per OPP. + * "core" + * "iface" + * "mem_iface" Example: @@ -25,28 +21,18 @@ Example: ... gpu: qcom,kgsl-3d0@4300000 { - compatible = "qcom,adreno-3xx"; + compatible = "qcom,adreno-320.2", "qcom,adreno"; reg = <0x04300000 0x20000>; reg-names = "kgsl_3d0_reg_memory"; interrupts = <GIC_SPI 80 0>; interrupt-names = "kgsl_3d0_irq"; clock-names = - "core_clk", - "iface_clk", - "mem_iface_clk"; + "core", + "iface", + "mem_iface"; clocks = <&mmcc GFX3D_CLK>, <&mmcc GFX3D_AHB_CLK>, <&mmcc MMSS_IMEM_AHB_CLK>; - qcom,chipid = <0x03020100>; - qcom,gpu-pwrlevels { - compatible = "qcom,gpu-pwrlevels"; - qcom,gpu-pwrlevel@0 { - qcom,gpu-freq = <450000000>; - }; - qcom,gpu-pwrlevel@1 { - qcom,gpu-freq = <27000000>; - }; - }; }; }; diff --git a/Documentation/devicetree/bindings/display/msm/hdmi.txt b/Documentation/devicetree/bindings/display/msm/hdmi.txt index 2ad578984fcf..2d306f402d18 100644 --- a/Documentation/devicetree/bindings/display/msm/hdmi.txt +++ b/Documentation/devicetree/bindings/display/msm/hdmi.txt @@ -49,7 +49,7 @@ Required properties: * "hdmi_tx_l4" - power-domains: Should be <&mmcc MDSS_GDSC>. - clocks: device clocks - See Documentation/devicetree/bindings/clocks/clock-bindings.txt for details. + See Documentation/devicetree/bindings/clock/clock-bindings.txt for details. - core-vdda-supply: phandle to vdda regulator device node Example: diff --git a/Documentation/devicetree/bindings/display/multi-inno,mi0283qt.txt b/Documentation/devicetree/bindings/display/multi-inno,mi0283qt.txt new file mode 100644 index 000000000000..eed48c3d4875 --- /dev/null +++ b/Documentation/devicetree/bindings/display/multi-inno,mi0283qt.txt @@ -0,0 +1,27 @@ +Multi-Inno MI0283QT display panel + +Required properties: +- compatible: "multi-inno,mi0283qt". + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in ../spi/spi-bus.txt must be specified. + +Optional properties: +- dc-gpios: D/C pin. The presence/absence of this GPIO determines + the panel interface mode (IM[3:0] pins): + - present: IM=x110 4-wire 8-bit data serial interface + - absent: IM=x101 3-wire 9-bit data serial interface +- reset-gpios: Reset pin +- power-supply: A regulator node for the supply voltage. +- backlight: phandle of the backlight device attached to the panel +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) + +Example: + mi0283qt@0{ + compatible = "multi-inno,mi0283qt"; + reg = <0>; + spi-max-frequency = <32000000>; + rotation = <90>; + dc-gpios = <&gpio 25 0>; + backlight = <&backlight>; + }; diff --git a/Documentation/devicetree/bindings/display/panel/boe,nv101wxmn51.txt b/Documentation/devicetree/bindings/display/panel/boe,nv101wxmn51.txt new file mode 100644 index 000000000000..b258d6a91ec6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/boe,nv101wxmn51.txt @@ -0,0 +1,7 @@ +BOE OPTOELECTRONICS TECHNOLOGY 10.1" WXGA TFT LCD panel + +Required properties: +- compatible: should be "boe,nv101wxmn51" + +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/netron-dy,e231732.txt b/Documentation/devicetree/bindings/display/panel/netron-dy,e231732.txt new file mode 100644 index 000000000000..c6d06b5eab51 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/netron-dy,e231732.txt @@ -0,0 +1,7 @@ +Netron-DY E231732 7.0" WSVGA TFT LCD panel + +Required properties: +- compatible: should be "netron-dy,e231732" + +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/panel-dpi.txt b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt index b52ac52757df..d4add13e592d 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-dpi.txt +++ b/Documentation/devicetree/bindings/display/panel/panel-dpi.txt @@ -12,7 +12,7 @@ Optional properties: Required nodes: - "panel-timing" containing video timings - (Documentation/devicetree/bindings/display/display-timing.txt) + (Documentation/devicetree/bindings/display/panel/display-timing.txt) - Video port for DPI input Example diff --git a/Documentation/devicetree/bindings/display/panel/panel.txt b/Documentation/devicetree/bindings/display/panel/panel.txt new file mode 100644 index 000000000000..e2e6867852b8 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/panel.txt @@ -0,0 +1,4 @@ +Common display properties +------------------------- + +- rotation: Display rotation in degrees counter clockwise (0,90,180,270) diff --git a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt index fc595d9b985b..354d4d1df4ff 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,ld9040.txt @@ -20,7 +20,7 @@ The device node can contain one 'port' child node with one child 'endpoint' node, according to the bindings defined in [3]. This node should describe panel's video bus. -[1]: Documentation/devicetree/bindings/display/display-timing.txt +[1]: Documentation/devicetree/bindings/display/panel/display-timing.txt [2]: Documentation/devicetree/bindings/spi/spi-bus.txt [3]: Documentation/devicetree/bindings/media/video-interfaces.txt diff --git a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt index 25701c81b5e0..9e766c5f86da 100644 --- a/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6e8aa0.txt @@ -21,7 +21,7 @@ The device node can contain one 'port' child node with one child 'endpoint' node, according to the bindings defined in [2]. This node should describe panel's video bus. -[1]: Documentation/devicetree/bindings/display/display-timing.txt +[1]: Documentation/devicetree/bindings/display/panel/display-timing.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt Example: diff --git a/Documentation/devicetree/bindings/display/panel/tianma,tm070jdhg30.txt b/Documentation/devicetree/bindings/display/panel/tianma,tm070jdhg30.txt new file mode 100644 index 000000000000..eb9501a82e25 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/tianma,tm070jdhg30.txt @@ -0,0 +1,7 @@ +Tianma Micro-electronics TM070JDHG30 7.0" WXGA TFT LCD panel + +Required properties: +- compatible: should be "tianma,tm070jdhg30" + +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/rockchip/analogix_dp-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/analogix_dp-rockchip.txt index 01cced1c2a18..47665a12786f 100644 --- a/Documentation/devicetree/bindings/display/rockchip/analogix_dp-rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/analogix_dp-rockchip.txt @@ -35,7 +35,7 @@ Optional property for different chips: Required elements: "grf" For the below properties, please refer to Analogix DP binding document: - * Documentation/devicetree/bindings/drm/bridge/analogix_dp.txt + * Documentation/devicetree/bindings/display/bridge/analogix_dp.txt - phys (required) - phy-names (required) - hpd-gpios (optional) diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt index 668091f27674..046076c6b277 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt @@ -1,24 +1,39 @@ -Rockchip specific extensions to the Synopsys Designware HDMI -================================ +Rockchip DWC HDMI TX Encoder +============================ + +The HDMI transmitter is a Synopsys DesignWare HDMI 1.4 TX controller IP +with a companion PHY IP. + +These DT bindings follow the Synopsys DWC HDMI TX bindings defined in +Documentation/devicetree/bindings/display/bridge/dw_hdmi.txt with the +following device-specific properties. + Required properties: -- compatible: "rockchip,rk3288-dw-hdmi"; -- reg: Physical base address and length of the controller's registers. -- clocks: phandle to hdmi iahb and isfr clocks. -- clock-names: should be "iahb" "isfr" -- rockchip,grf: this soc should set GRF regs to mux vopl/vopb. + +- compatible: Shall contain "rockchip,rk3288-dw-hdmi". +- reg: See dw_hdmi.txt. +- reg-io-width: See dw_hdmi.txt. Shall be 4. - interrupts: HDMI interrupt number -- ports: contain a port node with endpoint definitions as defined in - Documentation/devicetree/bindings/media/video-interfaces.txt. For - vopb,set the reg = <0> and set the reg = <1> for vopl. -- reg-io-width: the width of the reg:1,4, the value should be 4 on - rk3288 platform +- clocks: See dw_hdmi.txt. +- clock-names: Shall contain "iahb" and "isfr" as defined in dw_hdmi.txt. +- ports: See dw_hdmi.txt. The DWC HDMI shall have a single port numbered 0 + corresponding to the video input of the controller. The port shall have two + endpoints, numbered 0 and 1, connected respectively to the vopb and vopl. +- rockchip,grf: Shall reference the GRF to mux vopl/vopb. Optional properties -- ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing -- clocks, clock-names: phandle to the HDMI CEC clock, name should be "cec" + +- ddc-i2c-bus: The HDMI DDC bus can be connected to either a system I2C master + or the functionally-reduced I2C master contained in the DWC HDMI. When + connected to a system I2C master this property contains a phandle to that + I2C master controller. +- clock-names: See dw_hdmi.txt. The "cec" clock is optional. +- clock-names: May contain "cec" as defined in dw_hdmi.txt. + Example: + hdmi: hdmi@ff980000 { compatible = "rockchip,rk3288-dw-hdmi"; reg = <0xff980000 0x20000>; diff --git a/Documentation/devicetree/bindings/display/ssd1307fb.txt b/Documentation/devicetree/bindings/display/ssd1307fb.txt index eb31ed47a283..209d931ef16c 100644 --- a/Documentation/devicetree/bindings/display/ssd1307fb.txt +++ b/Documentation/devicetree/bindings/display/ssd1307fb.txt @@ -8,14 +8,15 @@ Required properties: 0x3c or 0x3d - pwm: Should contain the pwm to use according to the OF device tree PWM specification [0]. Only required for the ssd1307. - - reset-gpios: Should contain the GPIO used to reset the OLED display - solomon,height: Height in pixel of the screen driven by the controller - solomon,width: Width in pixel of the screen driven by the controller - solomon,page-offset: Offset of pages (band of 8 pixels) that the screen is mapped to. Optional properties: - - reset-active-low: Is the reset gpio is active on physical low? + - reset-gpios: The GPIO used to reset the OLED display, if available. See + Documentation/devicetree/bindings/gpio/gpio.txt for details. + - vbat-supply: The supply for VBAT - solomon,segment-no-remap: Display needs normal (non-inverted) data column to segment mapping - solomon,com-seq: Display uses sequential COM pin configuration diff --git a/Documentation/devicetree/bindings/display/tilcdc/panel.txt b/Documentation/devicetree/bindings/display/tilcdc/panel.txt index f20b31cdc59a..808216310ea2 100644 --- a/Documentation/devicetree/bindings/display/tilcdc/panel.txt +++ b/Documentation/devicetree/bindings/display/tilcdc/panel.txt @@ -15,7 +15,7 @@ Required properties: - display-timings: typical videomode of lcd panel. Multiple video modes can be listed if the panel supports multiple timings, but the 'native-mode' should be the preferred/default resolution. Refer to - Documentation/devicetree/bindings/display/display-timing.txt for display + Documentation/devicetree/bindings/display/panel/display-timing.txt for display timing binding details. Optional properties: diff --git a/Documentation/devicetree/bindings/display/zte,vou.txt b/Documentation/devicetree/bindings/display/zte,vou.txt index 740e5bd2e4f7..9c356284232b 100644 --- a/Documentation/devicetree/bindings/display/zte,vou.txt +++ b/Documentation/devicetree/bindings/display/zte,vou.txt @@ -49,6 +49,15 @@ Required properties: "osc_clk" "xclk" +* TV Encoder output device + +Required properties: + - compatible: should be "zte,zx296718-tvenc" + - reg: Physical base address and length of the TVENC device IO region + - zte,tvenc-power-control: the phandle to SYSCTRL block followed by two + integer cells. The first cell is the offset of SYSCTRL register used + to control TV Encoder DAC power, and the second cell is the bit mask. + Example: vou: vou@1440000 { @@ -81,4 +90,10 @@ vou: vou@1440000 { <&topcrm HDMI_XCLK>; clock-names = "osc_cec", "osc_clk", "xclk"; }; + + tvenc: tvenc@2000 { + compatible = "zte,zx296718-tvenc"; + reg = <0x2000 0x1000>; + zte,tvenc-power-control = <&sysctrl 0x170 0x10>; + }; }; diff --git a/Documentation/devicetree/bindings/eeprom/eeprom.txt b/Documentation/devicetree/bindings/eeprom/eeprom.txt index 735bc94444bb..5696eb508e95 100644 --- a/Documentation/devicetree/bindings/eeprom/eeprom.txt +++ b/Documentation/devicetree/bindings/eeprom/eeprom.txt @@ -10,6 +10,8 @@ Required properties: "catalyst,24c32" + "microchip,24c128" + "ramtron,24c64" "renesas,r1ex24002" diff --git a/Documentation/devicetree/bindings/gpio/cortina,gemini-gpio.txt b/Documentation/devicetree/bindings/gpio/cortina,gemini-gpio.txt new file mode 100644 index 000000000000..5c9246c054e5 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/cortina,gemini-gpio.txt @@ -0,0 +1,24 @@ +Cortina Systems Gemini GPIO Controller + +Required properties: + +- compatible : Must be "cortina,gemini-gpio" +- reg : Should contain registers location and length +- interrupts : Should contain the interrupt line for the GPIO block +- gpio-controller : marks this as a GPIO controller +- #gpio-cells : Should be 2, see gpio/gpio.txt +- interrupt-controller : marks this as an interrupt controller +- #interrupt-cells : a standard two-cell interrupt flag, see + interrupt-controller/interrupts.txt + +Example: + +gpio@4d000000 { + compatible = "cortina,gemini-gpio"; + reg = <0x4d000000 0x100>; + interrupts = <22 IRQ_TYPE_LEVEL_HIGH>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index 08dd15f89ba9..e63935710011 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -29,6 +29,10 @@ Required properties: onsemi,pca9654 exar,xra1202 +Optional properties: + - reset-gpios: GPIO specification for the RESET input. This is an + active low signal to the PCA953x. + Example: diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index 68d28f62a6f4..84ede036f73d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -187,10 +187,10 @@ gpio-controller's driver probe function. Each GPIO hog definition is represented as a child node of the GPIO controller. Required properties: -- gpio-hog: A property specifying that this child node represent a GPIO hog. -- gpios: Store the GPIO information (id, flags, ...). Shall contain the - number of cells specified in its parent node (GPIO controller - node). +- gpio-hog: A property specifying that this child node represents a GPIO hog. +- gpios: Store the GPIO information (id, flags, ...) for each GPIO to + affect. Shall contain an integer multiple of the number of cells + specified in its parent node (GPIO controller node). Only one of the following properties scanned in the order shown below. This means that when multiple properties are present they will be searched in the order presented below and the first match is taken as the intended diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt new file mode 100644 index 000000000000..476f5ea6c627 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt @@ -0,0 +1,81 @@ +ARM Mali Utgard GPU +=================== + +Required properties: + - compatible + * Must be one of the following: + + "arm,mali-300" + + "arm,mali-400" + + "arm,mali-450" + * And, optionally, one of the vendor specific compatible: + + allwinner,sun4i-a10-mali + + allwinner,sun7i-a20-mali + + amlogic,meson-gxbb-mali + + amlogic,meson-gxl-mali + + stericsson,db8500-mali + + - reg: Physical base address and length of the GPU registers + + - interrupts: an entry for each entry in interrupt-names. + See ../interrupt-controller/interrupts.txt for details. + + - interrupt-names: + * ppX: Pixel Processor X interrupt (X from 0 to 7) + * ppmmuX: Pixel Processor X MMU interrupt (X from 0 to 7) + * pp: Pixel Processor broadcast interrupt (mali-450 only) + * gp: Geometry Processor interrupt + * gpmmu: Geometry Processor MMU interrupt + + - clocks: an entry for each entry in clock-names + - clock-names: + * bus: bus clock for the GPU + * core: clock driving the GPU itself + +Optional properties: + - interrupt-names and interrupts: + * pmu: Power Management Unit interrupt, if implemented in hardware + +Vendor-specific bindings +------------------------ + +The Mali GPU is integrated very differently from one SoC to +another. In order to accomodate those differences, you have the option +to specify one more vendor-specific compatible, among: + + - allwinner,sun4i-a10-mali + Required properties: + * resets: phandle to the reset line for the GPU + + - allwinner,sun7i-a20-mali + Required properties: + * resets: phandle to the reset line for the GPU + + - stericsson,db8500-mali + Required properties: + * interrupt-names and interrupts: + + combined: combined interrupt of all of the above lines + +Example: + +mali: gpu@1c40000 { + compatible = "allwinner,sun7i-a20-mali", "arm,mali-400"; + reg = <0x01c40000 0x10000>; + interrupts = <GIC_SPI 97 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 98 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 99 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 100 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 102 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 103 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 101 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "gp", + "gpmmu", + "pp0", + "ppmmu0", + "pp1", + "ppmmu1", + "pmu"; + clocks = <&ccu CLK_BUS_GPU>, <&ccu CLK_GPU>; + clock-names = "bus", "core"; + resets = <&ccu RST_BUS_GPU>; +}; + diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt index cf53d5fba20a..aa097045a10e 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt @@ -19,7 +19,14 @@ Optional Properties: - i2c-mux-idle-disconnect: Boolean; if defined, forces mux to disconnect all children in idle state. This is necessary for example, if there are several multiplexers on the bus and the devices behind them use same I2C addresses. - + - interrupt-parent: Phandle for the interrupt controller that services + interrupts for this device. + - interrupts: Interrupt mapping for IRQ. + - interrupt-controller: Marks the device node as an interrupt controller. + - #interrupt-cells : Should be two. + - first cell is the pin number + - second cell is used to specify flags. + See also Documentation/devicetree/bindings/interrupt-controller/interrupts.txt Example: @@ -29,6 +36,11 @@ Example: #size-cells = <0>; reg = <0x74>; + interrupt-parent = <&ipic>; + interrupts = <17 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + i2c@2 { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index 7716acc55dec..ae9c2a735f39 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -10,6 +10,7 @@ Required properties: - "renesas,iic-r8a7793" (R-Car M2-N) - "renesas,iic-r8a7794" (R-Car E2) - "renesas,iic-r8a7795" (R-Car H3) + - "renesas,iic-r8a7796" (R-Car M3-W) - "renesas,iic-sh73a0" (SH-Mobile AG5) - "renesas,rcar-gen2-iic" (generic R-Car Gen2 compatible device) - "renesas,rcar-gen3-iic" (generic R-Car Gen3 compatible device) diff --git a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt new file mode 100644 index 000000000000..78eaf7b718ed --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt @@ -0,0 +1,33 @@ +* I2C controller embedded in STMicroelectronics STM32 I2C platform + +Required properties : +- compatible : Must be "st,stm32f4-i2c" +- reg : Offset and length of the register set for the device +- interrupts : Must contain the interrupt id for I2C event and then the + interrupt id for I2C error. +- resets: Must contain the phandle to the reset controller. +- clocks: Must contain the input clock of the I2C instance. +- A pinctrl state named "default" must be defined to set pins in mode of + operation for I2C transfer +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties : +- clock-frequency : Desired I2C bus clock frequency in Hz. If not specified, + the default 100 kHz frequency will be used. As only Normal and Fast modes + are supported, possible values are 100000 and 400000. + +Example : + + i2c@40005400 { + compatible = "st,stm32f4-i2c"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x40005400 0x400>; + interrupts = <31>, + <32>; + resets = <&rcc 277>; + clocks = <&rcc 0 149>; + pinctrl-0 = <&i2c1_sda_pin>, <&i2c1_scl_pin>; + pinctrl-names = "default"; + }; diff --git a/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt new file mode 100644 index 000000000000..ab240e10debc --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/nvidia,tegra186-bpmp-i2c.txt @@ -0,0 +1,42 @@ +NVIDIA Tegra186 BPMP I2C controller + +In Tegra186, the BPMP (Boot and Power Management Processor) owns certain HW +devices, such as the I2C controller for the power management I2C bus. Software +running on other CPUs must perform IPC to the BPMP in order to execute +transactions on that I2C bus. This binding describes an I2C bus that is +accessed in such a fashion. + +The BPMP I2C node must be located directly inside the main BPMP node. See +../firmware/nvidia,tegra186-bpmp.txt for details of the BPMP binding. + +This node represents an I2C controller. See ../i2c/i2c.txt for details of the +core I2C binding. + +Required properties: +- compatible: + Array of strings. + One of: + - "nvidia,tegra186-bpmp-i2c". +- #address-cells: Address cells for I2C device address. + Single-cell integer. + Must be <1>. +- #size-cells: + Single-cell integer. + Must be <0>. +- nvidia,bpmp-bus-id: + Single-cell integer. + Indicates the I2C bus number this DT node represent, as defined by the + BPMP firmware. + +Example: + +bpmp { + ... + + i2c { + compatible = "nvidia,tegra186-bpmp-i2c"; + #address-cells = <1>; + #size-cells = <0>; + nvidia,bpmp-bus-id = <5>; + }; +}; diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index cdd7b48826c3..ad10fbe61562 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -36,6 +36,7 @@ dallas,ds1775 Tiny Digital Thermometer and Thermostat dallas,ds3232 Extremely Accurate I²C RTC with Integrated Crystal and SRAM dallas,ds4510 CPU Supervisor with Nonvolatile Memory and Programmable I/O dallas,ds75 Digital Thermometer and Thermostat +devantech,srf08 Devantech SRF08 ultrasonic ranger 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 diff --git a/Documentation/devicetree/bindings/iio/accel/lis302.txt b/Documentation/devicetree/bindings/iio/accel/lis302.txt index 2a19bff9693f..dfdce67826ba 100644 --- a/Documentation/devicetree/bindings/iio/accel/lis302.txt +++ b/Documentation/devicetree/bindings/iio/accel/lis302.txt @@ -5,7 +5,7 @@ that apply in on the generic device (independent from the bus). Required properties for the SPI bindings: - - compatible: should be set to "st,lis3lv02d_spi" + - compatible: should be set to "st,lis3lv02d-spi" - reg: the chipselect index - spi-max-frequency: maximal bus speed, should be set to 1000000 unless constrained by external circuitry diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt new file mode 100644 index 000000000000..f9e3ff2c656e --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -0,0 +1,32 @@ +* Amlogic Meson SAR (Successive Approximation Register) A/D converter + +Required properties: +- compatible: depending on the SoC this should be one of: + - "amlogic,meson-gxbb-saradc" for GXBB + - "amlogic,meson-gxl-saradc" for GXL + - "amlogic,meson-gxm-saradc" for GXM + along with the generic "amlogic,meson-saradc" +- reg: the physical base address and length of the registers +- clocks: phandle and clock identifier (see clock-names) +- clock-names: mandatory clocks: + - "clkin" for the reference clock (typically XTAL) + - "core" for the SAR ADC core clock + optional clocks: + - "sana" for the analog clock + - "adc_clk" for the ADC (sampling) clock + - "adc_sel" for the ADC (sampling) clock mux +- vref-supply: the regulator supply for the ADC reference voltage +- #io-channel-cells: must be 1, see ../iio-bindings.txt + +Example: + saradc: adc@8680 { + compatible = "amlogic,meson-gxl-saradc", "amlogic,meson-saradc"; + #io-channel-cells = <1>; + reg = <0x0 0x8680 0x0 0x34>; + clocks = <&xtal>, + <&clkc CLKID_SAR_ADC>, + <&clkc CLKID_SANA>, + <&clkc CLKID_SAR_ADC_CLK>, + <&clkc CLKID_SAR_ADC_SEL>; + clock-names = "clkin", "core", "sana", "adc_clk", "adc_sel"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt b/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt new file mode 100644 index 000000000000..b3629405f568 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/avia-hx711.txt @@ -0,0 +1,18 @@ +* AVIA HX711 ADC chip for weight cells + Bit-banging driver + +Required properties: + - compatible: Should be "avia,hx711" + - sck-gpios: Definition of the GPIO for the clock + - dout-gpios: Definition of the GPIO for data-out + See Documentation/devicetree/bindings/gpio/gpio.txt + - avdd-supply: Definition of the regulator used as analog supply + +Example: +weight@0 { + compatible = "avia,hx711"; + sck-gpios = <&gpio3 10 GPIO_ACTIVE_HIGH>; + dout-gpios = <&gpio0 7 GPIO_ACTIVE_HIGH>; + avdd-suppy = <&avdd>; +}; + diff --git a/Documentation/devicetree/bindings/iio/adc/max11100.txt b/Documentation/devicetree/bindings/iio/adc/max11100.txt new file mode 100644 index 000000000000..b7f7177b8aca --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/max11100.txt @@ -0,0 +1,18 @@ +* Maxim max11100 Analog to Digital Converter (ADC) + +Required properties: + - compatible: Should be "maxim,max11100" + - reg: the adc unit address + - vref-supply: phandle to the regulator that provides reference voltage + +Optional properties: + - spi-max-frequency: SPI maximum frequency + +Example: + +max11100: adc@0 { + compatible = "maxim,max11100"; + reg = <0>; + vref-supply = <&adc0_vref>; + spi-max-frequency = <240000>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt new file mode 100644 index 000000000000..53cd146d8096 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/qcom,pm8xxx-xoadc.txt @@ -0,0 +1,149 @@ +Qualcomm's PM8xxx voltage XOADC + +The Qualcomm PM8xxx PMICs contain a HK/XO ADC (Housekeeping/Crystal +oscillator ADC) encompassing PM8018, PM8038, PM8058 and PM8921. + +Required properties: + +- compatible: should be one of: + "qcom,pm8018-adc" + "qcom,pm8038-adc" + "qcom,pm8058-adc" + "qcom,pm8921-adc" + +- reg: should contain the ADC base address in the PMIC, typically + 0x197. + +- xoadc-ref-supply: should reference a regulator that can supply + a reference voltage on demand. The reference voltage may vary + with PMIC variant but is typically something like 2.2 or 1.8V. + +The following required properties are standard for IO channels, see +iio-bindings.txt for more details: + +- #address-cells: should be set to <1> + +- #size-cells: should be set to <0> + +- #io-channel-cells: should be set to <1> + +- interrupts: should refer to the parent PMIC interrupt controller + and reference the proper ADC interrupt. + +Required subnodes: + +The ADC channels are configured as subnodes of the ADC. Since some of +them are used for calibrating the ADC, these nodes are compulsory: + +adc-channel@c { + reg = <0x0c>; +}; + +adc-channel@d { + reg = <0x0d>; +}; + +adc-channel@f { + reg = <0x0f>; +}; + +These three nodes are used for absolute and ratiometric calibration +and only need to have these reg values: they are by hardware definition +1:1 ratio converters that sample 625, 1250 and 0 milliV and create +an interpolation calibration for all other ADCs. + +Optional subnodes: any channels other than channel 0x0c, 0x0d and +0x0f are optional. + +Required channel node properties: + +- reg: should contain the hardware channel number in the range + 0 .. 0x0f (4 bits). The hardware only supports 16 channels. + +Optional channel node properties: + +- qcom,decimation: + Value type: <u32> + Definition: This parameter is used to decrease the ADC sampling rate. + Quicker measurements can be made by reducing the decimation ratio. + Valid values are 512, 1024, 2048, 4096. + If the property is not found, a default value of 512 will be used. + +- qcom,ratiometric: + Value type: <u32> + Definition: Channel calibration type. If this property is specified + VADC will use a special voltage references for channel + calibration. The available references are specified in the + as a u32 value setting (see below) and it is compulsory + to also specify this reference if ratiometric calibration + is selected. + + If the property is not found, the channel will be + calibrated with the 0.625V and 1.25V reference channels, also + known as an absolute calibration. + The reference voltage pairs when using ratiometric calibration: + 0 = XO_IN/XOADC_GND + 1 = PMIC_IN/XOADC_GND + 2 = PMIC_IN/BMS_CSP + 3 (invalid) + 4 = XOADC_GND/XOADC_GND + 5 = XOADC_VREF/XOADC_GND + +Example: + +xoadc: xoadc@197 { + compatible = "qcom,pm8058-adc"; + reg = <0x197>; + interrupt-parent = <&pm8058>; + interrupts = <76 1>; + #address-cells = <1>; + #size-cells = <0>; + #io-channel-cells = <1>; + + vcoin: adc-channel@0 { + reg = <0x00>; + }; + vbat: adc-channel@1 { + reg = <0x01>; + }; + dcin: adc-channel@2 { + reg = <0x02>; + }; + ichg: adc-channel@3 { + reg = <0x03>; + }; + vph_pwr: adc-channel@4 { + reg = <0x04>; + }; + usb_vbus: adc-channel@a { + reg = <0x0a>; + }; + die_temp: adc-channel@b { + reg = <0x0b>; + }; + ref_625mv: adc-channel@c { + reg = <0x0c>; + }; + ref_1250mv: adc-channel@d { + reg = <0x0d>; + }; + ref_325mv: adc-channel@e { + reg = <0x0e>; + }; + ref_muxoff: adc-channel@f { + reg = <0x0f>; + }; +}; + + +/* IIO client node */ +iio-hwmon { + compatible = "iio-hwmon"; + io-channels = <&xoadc 0x01>, /* Battery */ + <&xoadc 0x02>, /* DC in (charger) */ + <&xoadc 0x04>, /* VPH the main system voltage */ + <&xoadc 0x0b>, /* Die temperature */ + <&xoadc 0x0c>, /* Reference voltage 1.25V */ + <&xoadc 0x0d>, /* Reference voltage 0.625V */ + <&xoadc 0x0e>; /* Reference voltage 0.325V */ +}; diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,gyroadc.txt b/Documentation/devicetree/bindings/iio/adc/renesas,gyroadc.txt new file mode 100644 index 000000000000..f5b0adae6010 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/renesas,gyroadc.txt @@ -0,0 +1,99 @@ +* Renesas RCar GyroADC device driver + +The GyroADC block is a reduced SPI block with up to 8 chipselect lines, +which supports the SPI protocol of a selected few SPI ADCs. The SPI ADCs +are sampled by the GyroADC block in a round-robin fashion and the result +presented in the GyroADC registers. + +Required properties: +- compatible: Should be "<soc-specific>", "renesas,rcar-gyroadc". + The <soc-specific> should be one of: + renesas,r8a7791-gyroadc - for the GyroADC block present + in r8a7791 SoC + renesas,r8a7792-gyroadc - for the GyroADC with interrupt + block present in r8a7792 SoC +- reg: Address and length of the register set for the device +- clocks: References to all the clocks specified in the clock-names + property as specified in + Documentation/devicetree/bindings/clock/clock-bindings.txt. +- clock-names: Shall contain "fck" and "if". The "fck" is the GyroADC block + clock, the "if" is the interface clock. +- power-domains: Must contain a reference to the PM domain, if available. +- #address-cells: Should be <1> (setting for the subnodes) for all ADCs + except for "fujitsu,mb88101a". Should be <0> (setting for + only subnode) for "fujitsu,mb88101a". +- #size-cells: Should be <0> (setting for the subnodes) + +Sub-nodes: +You must define subnode(s) which select the connected ADC type and reference +voltage for the GyroADC channels. + +Required properties for subnodes: +- compatible: Should be either of: + "fujitsu,mb88101a" + - Fujitsu MB88101A compatible mode, + 12bit sampling, up to 4 channels can be sampled in + round-robin fashion. One Fujitsu chip supplies four + GyroADC channels with data as it contains four ADCs + on the chip and thus for 4-channel operation, single + MB88101A is required. The Cx chipselect lines of the + MB88101A connect directly to two CHS lines of the + GyroADC, no demuxer is required. The data out line + of each MB88101A connects to a shared input pin of + the GyroADC. + "ti,adcs7476" or "ti,adc121" or "adi,ad7476" + - TI ADCS7476 / TI ADC121 / ADI AD7476 compatible mode, + 15bit sampling, up to 8 channels can be sampled in + round-robin fashion. One TI/ADI chip supplies single + ADC channel with data, thus for 8-channel operation, + 8 chips are required. A 3:8 chipselect demuxer is + required to connect the nCS line of the TI/ADI chips + to the GyroADC, while MISO line of each TI/ADI ADC + connects to a shared input pin of the GyroADC. + "maxim,max1162" or "maxim,max11100" + - Maxim MAX1162 / Maxim MAX11100 compatible mode, + 16bit sampling, up to 8 channels can be sampled in + round-robin fashion. One Maxim chip supplies single + ADC channel with data, thus for 8-channel operation, + 8 chips are required. A 3:8 chipselect demuxer is + required to connect the nCS line of the MAX chips + to the GyroADC, while MISO line of each Maxim ADC + connects to a shared input pin of the GyroADC. +- reg: Should be the number of the analog input. Should be present + for all ADCs except "fujitsu,mb88101a". +- vref-supply: Reference to the channel reference voltage regulator. + +Example: + vref_max1162: regulator-vref-max1162 { + compatible = "regulator-fixed"; + + regulator-name = "MAX1162 Vref"; + regulator-min-microvolt = <4096000>; + regulator-max-microvolt = <4096000>; + }; + + adc@e6e54000 { + compatible = "renesas,r8a7791-gyroadc", "renesas,rcar-gyroadc"; + reg = <0 0xe6e54000 0 64>; + clocks = <&mstp9_clks R8A7791_CLK_GYROADC>, <&clk_65m>; + clock-names = "fck", "if"; + power-domains = <&sysc R8A7791_PD_ALWAYS_ON>; + + pinctrl-0 = <&adc_pins>; + pinctrl-names = "default"; + + #address-cells = <1>; + #size-cells = <0>; + + adc@0 { + reg = <0>; + compatible = "maxim,max1162"; + vref-supply = <&vref_max1162>; + }; + + adc@1 { + reg = <1>; + compatible = "maxim,max1162"; + vref-supply = <&vref_max1162>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt index 49ed82e89870..5dfc88ec24a4 100644 --- a/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/st,stm32-adc.txt @@ -53,6 +53,11 @@ Required properties: - #io-channel-cells = <1>: See the IIO bindings section "IIO consumers" in Documentation/devicetree/bindings/iio/iio-bindings.txt +Optional properties: +- dmas: Phandle to dma channel for this ADC instance. + See ../../dma/dma.txt for details. +- dma-names: Must be "rx" when dmas property is being used. + Example: adc: adc@40012000 { compatible = "st,stm32f4-adc-core"; @@ -77,6 +82,8 @@ Example: interrupt-parent = <&adc>; interrupts = <0>; st,adc-channels = <8>; + dmas = <&dma2 0 0 0x400 0x0>; + dma-names = "rx"; }; ... other adc child nodes follow... diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads7950.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads7950.txt new file mode 100644 index 000000000000..e77a6f7e1001 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-ads7950.txt @@ -0,0 +1,23 @@ +* Texas Instruments ADS7950 family of A/DC chips + +Required properties: + - compatible: Must be one of "ti,ads7950", "ti,ads7951", "ti,ads7952", + "ti,ads7953", "ti,ads7954", "ti,ads7955", "ti,ads7956", "ti,ads7957", + "ti,ads7958", "ti,ads7959", "ti,ads7960", or "ti,ads7961" + - reg: SPI chip select number for the device + - #io-channel-cells: Must be 1 as per ../iio-bindings.txt + - vref-supply: phandle to a regulator node that supplies the 2.5V or 5V + reference voltage + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: +adc@0 { + compatible = "ti,ads7957"; + reg = <0>; + #io-channel-cells = <1>; + vref-supply = <&refin_supply>; + spi-max-frequency = <10000000>; +}; diff --git a/Documentation/devicetree/bindings/iio/imu/bmi160.txt b/Documentation/devicetree/bindings/iio/imu/bmi160.txt new file mode 100644 index 000000000000..ae0112c7debc --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/bmi160.txt @@ -0,0 +1,36 @@ +Bosch BMI160 - Inertial Measurement Unit with Accelerometer, Gyroscope +and externally connectable Magnetometer + +https://www.bosch-sensortec.com/bst/products/all_products/bmi160 + +Required properties: + - compatible : should be "bosch,bmi160" + - reg : the I2C address or SPI chip select number of the sensor + - spi-max-frequency : set maximum clock frequency (only for SPI) + +Optional properties: + - interrupt-parent : should be the phandle of the interrupt controller + - interrupts : interrupt mapping for IRQ, must be IRQ_TYPE_LEVEL_LOW + - interrupt-names : set to "INT1" if INT1 pin should be used as interrupt + input, set to "INT2" if INT2 pin should be used instead + +Examples: + +bmi160@68 { + compatible = "bosch,bmi160"; + reg = <0x68>; + + interrupt-parent = <&gpio4>; + interrupts = <12 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "INT1"; +}; + +bmi160@0 { + compatible = "bosch,bmi160"; + reg = <0>; + spi-max-frequency = <10000000>; + + interrupt-parent = <&gpio2>; + interrupts = <12 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "INT2"; +}; diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt new file mode 100644 index 000000000000..cf81afdf7803 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -0,0 +1,26 @@ +* ST_LSM6DSx driver for STM 6-axis (acc + gyro) imu Mems sensors + +Required properties: +- compatible: must be one of: + "st,lsm6ds3" + "st,lsm6dsm" +- reg: i2c address of the sensor / spi cs line + +Optional properties: +- st,drdy-int-pin: the pin on the package that will be used to signal + "data ready" (valid values: 1 or 2). +- interrupt-parent: should be the phandle for the interrupt controller +- interrupts: interrupt mapping for IRQ. It should be configured with + flags IRQ_TYPE_LEVEL_HIGH or IRQ_TYPE_EDGE_RISING. + + Refer to interrupt-controller/interrupts.txt for generic interrupt + client node bindings. + +Example: + +lsm6dsm@6b { + compatible = "st,lsm6dsm"; + reg = <0x6b>; + interrupt-parent = <&gpio0>; + interrupts = <0 IRQ_TYPE_EDGE_RISING>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/cm3605.txt b/Documentation/devicetree/bindings/iio/light/cm3605.txt new file mode 100644 index 000000000000..56331a79f9ab --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/cm3605.txt @@ -0,0 +1,41 @@ +Capella Microsystems CM3605 +Ambient Light and Short Distance Proximity Sensor + +The CM3605 is an entirely analog part which however require quite a bit of +software logic to interface a host operating system. + +This ALS and proximity sensor was one of the very first deployed in mobile +handsets, notably it is used in the very first Nexus One Android phone from +2010. + +Required properties: +- compatible: must be: "capella,cm3605" +- aset-gpios: GPIO line controlling the ASET line (drive low + to activate the ALS, should be flagged GPIO_ACTIVE_LOW) +- interrupts: the IRQ line (such as a GPIO) that is connected to + the POUT (proximity sensor out) line. The edge detection must + be set to IRQ_TYPE_EDGE_BOTH so as to detect movements toward + and away from the proximity sensor. +- io-channels: the ADC channel used for converting the voltage from + AOUT to a digital representation. +- io-channel-names: must be "aout" + +Optional properties: +- vdd-supply: regulator supplying VDD power to the component. +- capella,aset-resistance-ohms: the sensitivity calibration resistance, + in Ohms. Valid values are: 50000, 100000, 300000 and 600000, + as these are the resistance values that we are supplied with + calibration curves for. If not supplied, 100 kOhm will be assumed + but it is strongly recommended to supply this. + +Example: + +cm3605 { + compatible = "capella,cm3605"; + vdd-supply = <&foo_reg>; + aset-gpios = <&foo_gpio 1 GPIO_ACTIVE_LOW>; + capella,aset-resistance-ohms = <100000>; + interrupts = <1 IRQ_TYPE_EDGE_BOTH>; + io-channels = <&adc 0x01>; + io-channel-names = "aout"; +}; diff --git a/Documentation/devicetree/bindings/iio/potentiometer/max5481.txt b/Documentation/devicetree/bindings/iio/potentiometer/max5481.txt new file mode 100644 index 000000000000..6a91b106e076 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/potentiometer/max5481.txt @@ -0,0 +1,23 @@ +* Maxim Linear-Taper Digital Potentiometer MAX5481-MAX5484 + +The node for this driver must be a child node of a SPI controller, hence +all mandatory properties described in + + Documentation/devicetree/bindings/spi/spi-bus.txt + +must be specified. + +Required properties: + - compatible: Must be one of the following, depending on the + model: + "maxim,max5481" + "maxim,max5482" + "maxim,max5483" + "maxim,max5484" + +Example: +max548x: max548x@0 { + compatible = "maxim,max5482"; + spi-max-frequency = <7000000>; + reg = <0>; /* chip-select */ +}; diff --git a/Documentation/devicetree/bindings/iio/st-sensors.txt b/Documentation/devicetree/bindings/iio/st-sensors.txt index c040c9ad1889..eaa8fbba34e2 100644 --- a/Documentation/devicetree/bindings/iio/st-sensors.txt +++ b/Documentation/devicetree/bindings/iio/st-sensors.txt @@ -27,6 +27,8 @@ standard bindings from pinctrl/pinctrl-bindings.txt. Valid compatible strings: Accelerometers: +- st,lis3lv02d (deprecated, use st,lis3lv02dl-accel) +- st,lis302dl-spi (deprecated, use st,lis3lv02dl-accel) - st,lis3lv02dl-accel - st,lsm303dlh-accel - st,lsm303dlhc-accel diff --git a/Documentation/devicetree/bindings/iio/temperature/tmp007.txt b/Documentation/devicetree/bindings/iio/temperature/tmp007.txt new file mode 100644 index 000000000000..b63aba91ef03 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/temperature/tmp007.txt @@ -0,0 +1,35 @@ +* TI TMP007 - IR thermopile sensor with integrated math engine + +Link to datasheet: http://www.ti.com/lit/ds/symlink/tmp007.pdf + +Required properties: + + - compatible: should be "ti,tmp007" + - reg: the I2C address of the sensor (changeable via ADR pins) + ------------------------------ + |ADR1 | ADR0 | Device Address| + ------------------------------ + 0 0 0x40 + 0 1 0x41 + 0 SDA 0x42 + 0 SCL 0x43 + 1 0 0x44 + 1 1 0x45 + 1 SDA 0x46 + 1 SCL 0x47 + +Optional properties: + + - interrupt-parent: should be the phandle for the interrupt controller + + - interrupts: interrupt mapping for GPIO IRQ (level active low) + +Example: + +tmp007@40 { + compatible = "ti,tmp007"; + reg = <0x40>; + interrupt-parent = <&gpio0>; + interrupts = <5 0x08>; +}; + diff --git a/Documentation/devicetree/bindings/iio/timer/stm32-timer-trigger.txt b/Documentation/devicetree/bindings/iio/timer/stm32-timer-trigger.txt new file mode 100644 index 000000000000..55a653d15303 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/timer/stm32-timer-trigger.txt @@ -0,0 +1,23 @@ +STMicroelectronics STM32 Timers IIO timer bindings + +Must be a sub-node of an STM32 Timers device tree node. +See ../mfd/stm32-timers.txt for details about the parent node. + +Required parameters: +- compatible: Must be "st,stm32-timer-trigger". +- reg: Identify trigger hardware block. + +Example: + timers@40010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32-timers"; + reg = <0x40010000 0x400>; + clocks = <&rcc 0 160>; + clock-names = "clk_int"; + + timer@0 { + compatible = "st,stm32-timer-trigger"; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/cypress,tm2-touchkey.txt b/Documentation/devicetree/bindings/input/cypress,tm2-touchkey.txt new file mode 100644 index 000000000000..635f62c756ee --- /dev/null +++ b/Documentation/devicetree/bindings/input/cypress,tm2-touchkey.txt @@ -0,0 +1,27 @@ +Samsung tm2-touchkey + +Required properties: +- compatible: must be "cypress,tm2-touchkey" +- reg: I2C address of the chip. +- interrupt-parent: a phandle for the interrupt controller (see interrupt + binding[0]). +- interrupts: interrupt to which the chip is connected (see interrupt + binding[0]). +- vcc-supply : internal regulator output. 1.8V +- vdd-supply : power supply for IC 3.3V + +[0]: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Example: + &i2c0 { + /* ... */ + + touchkey@20 { + compatible = "cypress,tm2-touchkey"; + reg = <0x20>; + interrupt-parent = <&gpa3>; + interrupts = <2 IRQ_TYPE_EDGE_FALLING>; + vcc-supply=<&ldo32_reg>; + vdd-supply=<&ldo33_reg>; + }; + }; diff --git a/Documentation/devicetree/bindings/input/mpr121-touchkey.txt b/Documentation/devicetree/bindings/input/mpr121-touchkey.txt new file mode 100644 index 000000000000..b7c61ee5841b --- /dev/null +++ b/Documentation/devicetree/bindings/input/mpr121-touchkey.txt @@ -0,0 +1,30 @@ +* Freescale MPR121 Controllor + +Required Properties: +- compatible: Should be "fsl,mpr121-touchkey" +- reg: The I2C slave address of the device. +- interrupts: The interrupt number to the cpu. +- vdd-supply: Phandle to the Vdd power supply. +- linux,keycodes: Specifies an array of numeric keycode values to + be used for reporting button presses. The array can + contain up to 12 entries. + +Optional Properties: +- wakeup-source: Use any event on keypad as wakeup event. +- autorepeat: Enable autorepeat feature. + +Example: + +#include "dt-bindings/input/input.h" + + touchkey: mpr121@5a { + compatible = "fsl,mpr121-touchkey"; + reg = <0x5a>; + interrupt-parent = <&gpio1>; + interrupts = <28 2>; + autorepeat; + vdd-supply = <&ldo4_reg>; + linux,keycodes = <KEY_0>, <KEY_1>, <KEY_2>, <KEY_3>, + <KEY_4> <KEY_5>, <KEY_6>, <KEY_7>, + <KEY_8>, <KEY_9>, <KEY_A>, <KEY_B>; + }; diff --git a/Documentation/devicetree/bindings/input/pwm-beeper.txt b/Documentation/devicetree/bindings/input/pwm-beeper.txt index be332ae4f2d6..529408b4431a 100644 --- a/Documentation/devicetree/bindings/input/pwm-beeper.txt +++ b/Documentation/devicetree/bindings/input/pwm-beeper.txt @@ -5,3 +5,19 @@ Registers a PWM device as beeper. Required properties: - compatible: should be "pwm-beeper" - pwms: phandle to the physical PWM device + +Optional properties: +- amp-supply: phandle to a regulator that acts as an amplifier for the beeper + +Example: + +beeper_amp: amplifier { + compatible = "fixed-regulator"; + gpios = <&gpio0 1 GPIO_ACTIVE_HIGH>; +}; + +beeper { + compatible = "pwm-beeper"; + pwms = <&pwm0>; + amp-supply = <&beeper_amp>; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt b/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt new file mode 100644 index 000000000000..fe6a1feef703 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/zet6223.txt @@ -0,0 +1,32 @@ +Zeitec ZET6223 I2C touchscreen controller + +Required properties: +- compatible : "zeitec,zet6223" +- reg : I2C slave address of the chip (0x76) +- interrupt-parent : a phandle pointing to the interrupt controller + serving the interrupt for this chip +- interrupts : interrupt specification for the zet6223 interrupt + +Optional properties: + +- vio-supply : Specification for VIO supply (1.8V or 3.3V, + depending on system interface needs). +- vcc-supply : Specification for 3.3V VCC supply. +- touchscreen-size-x : See touchscreen.txt +- touchscreen-size-y : See touchscreen.txt +- touchscreen-inverted-x : See touchscreen.txt +- touchscreen-inverted-y : See touchscreen.txt +- touchscreen-swapped-x-y : See touchscreen.txt + +Example: + +i2c@00000000 { + + zet6223: touchscreen@76 { + compatible = "zeitec,zet6223"; + reg = <0x76>; + interrupt-parent = <&pio>; + interrupts = <6 11 IRQ_TYPE_EDGE_FALLING> + }; + +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt index 5393e2a45a42..560d8a727b8f 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic.txt @@ -111,7 +111,7 @@ Example: #interrupt-cells = <3>; interrupt-controller; reg = <0x2c001000 0x1000>, - <0x2c002000 0x1000>, + <0x2c002000 0x2000>, <0x2c004000 0x2000>, <0x2c006000 0x2000>; interrupts = <1 9 0xf04>; diff --git a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt index 944657684d73..8b46a34e05f1 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/snps,archs-idu-intc.txt @@ -8,15 +8,11 @@ Properties: - compatible: "snps,archs-idu-intc" - interrupt-controller: This is an interrupt controller. - interrupt-parent: <reference to parent core intc> -- #interrupt-cells: Must be <2>. -- interrupts: <...> specifies the upstream core irqs +- #interrupt-cells: Must be <1>. - First cell specifies the "common" IRQ from peripheral to IDU - Second cell specifies the irq distribution mode to cores - 0=Round Robin; 1=cpu0, 2=cpu1, 4=cpu2, 8=cpu3 - - The second cell in interrupts property is deprecated and may be ignored by - the kernel. + Value of the cell specifies the "common" IRQ from peripheral to IDU. Number N + of the particular interrupt line of IDU corresponds to the line N+24 of the + core interrupt controller. intc accessed via the special ARC AUX register interface, hence "reg" property is not specified. @@ -32,18 +28,10 @@ Example: compatible = "snps,archs-idu-intc"; interrupt-controller; interrupt-parent = <&core_intc>; - - /* - * <hwirq distribution> - * distribution: 0=RR; 1=cpu0, 2=cpu1, 4=cpu2, 8=cpu3 - */ - #interrupt-cells = <2>; - - /* upstream core irqs: downstream these are "COMMON" irq 0,1.. */ - interrupts = <24 25 26 27 28 29 30 31>; + #interrupt-cells = <1>; }; some_device: serial@c0fc1000 { interrupt-parent = <&idu_intc>; - interrupts = <0 0>; /* upstream idu IRQ #24, Round Robin */ + interrupts = <0>; /* upstream idu IRQ #24 */ }; diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt index e862d1485205..6cdf32d037fc 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt @@ -36,15 +36,15 @@ conditions. combined interrupt, it must be listed multiple times. - #iommu-cells : See Documentation/devicetree/bindings/iommu/iommu.txt - for details. With a value of 1, each "iommus" entry + for details. With a value of 1, each IOMMU specifier 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. + may use a value of 2, where the second cell of the + IOMMU specifier 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: diff --git a/Documentation/devicetree/bindings/mfd/as3722.txt b/Documentation/devicetree/bindings/mfd/as3722.txt index 4f64b2a73169..0b2a6099aa20 100644 --- a/Documentation/devicetree/bindings/mfd/as3722.txt +++ b/Documentation/devicetree/bindings/mfd/as3722.txt @@ -122,8 +122,7 @@ Following are properties of regulator subnode. Power-off: ========= -AS3722 supports the system power off by turning off all its rail. This -is provided through pm_power_off. +AS3722 supports the system power off by turning off all its rails. The device node should have the following properties to enable this functionality ams,system-power-controller: Boolean, to enable the power off functionality diff --git a/Documentation/devicetree/bindings/mfd/aspeed-gfx.txt b/Documentation/devicetree/bindings/mfd/aspeed-gfx.txt new file mode 100644 index 000000000000..aea5370efd97 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/aspeed-gfx.txt @@ -0,0 +1,17 @@ +* Device tree bindings for Aspeed SoC Display Controller (GFX) + +The Aspeed SoC Display Controller primarily does as its name suggests, but also +participates in pinmux requests on the g5 SoCs. It is therefore considered a +syscon device. + +Required properties: +- compatible: "aspeed,ast2500-gfx", "syscon" +- reg: contains offset/length value of the GFX memory + region. + +Example: + +gfx: display@1e6e6000 { + compatible = "aspeed,ast2500-gfx", "syscon"; + reg = <0x1e6e6000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt new file mode 100644 index 000000000000..514d82ced95b --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -0,0 +1,137 @@ +====================================================================== +Device tree bindings for the Aspeed Low Pin Count (LPC) Bus Controller +====================================================================== + +The LPC bus is a means to bridge a host CPU to a number of low-bandwidth +peripheral devices, replacing the use of the ISA bus in the age of PCI[0]. The +primary use case of the Aspeed LPC controller is as a slave on the bus +(typically in a Baseboard Management Controller SoC), but under certain +conditions it can also take the role of bus master. + +The LPC controller is represented as a multi-function device to account for the +mix of functionality it provides. The principle split is between the register +layout at the start of the I/O space which is, to quote the Aspeed datasheet, +"basically compatible with the [LPC registers from the] popular BMC controller +H8S/2168[1]", and everything else, where everything else is an eclectic +collection of functions with a esoteric register layout. "Everything else", +here labeled the "host" portion of the controller, includes, but is not limited +to: + +* An IPMI Block Transfer[2] Controller + +* An LPC Host Controller: Manages LPC functions such as host vs slave mode, the + physical properties of some LPC pins, configuration of serial IRQs, and + APB-to-LPC bridging amonst other functions. + +* An LPC Host Interface Controller: Manages functions exposed to the host such + as LPC firmware hub cycles, configuration of the LPC-to-AHB mapping, UART + management and bus snoop configuration. + +* A set of SuperIO[3] scratch registers: Enables implementation of e.g. custom + hardware management protocols for handover between the host and baseboard + management controller. + +Additionally the state of the LPC controller influences the pinmux +configuration, therefore the host portion of the controller is exposed as a +syscon as a means to arbitrate access. + +[0] http://www.intel.com/design/chipsets/industry/25128901.pdf +[1] https://www.renesas.com/en-sg/doc/products/mpumcu/001/rej09b0078_h8s2168.pdf?key=7c88837454702128622bee53acbda8f4 +[2] http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf +[3] https://en.wikipedia.org/wiki/Super_I/O + +Required properties +=================== + +- compatible: One of: + "aspeed,ast2400-lpc", "simple-mfd" + "aspeed,ast2500-lpc", "simple-mfd" + +- reg: contains the physical address and length values of the Aspeed + LPC memory region. + +- #address-cells: <1> +- #size-cells: <1> +- ranges: Maps 0 to the physical address and length of the LPC memory + region + +Required LPC Child nodes +======================== + +BMC Node +-------- + +- compatible: One of: + "aspeed,ast2400-lpc-bmc" + "aspeed,ast2500-lpc-bmc" + +- reg: contains the physical address and length values of the + H8S/2168-compatible LPC controller memory region + +Host Node +--------- + +- compatible: One of: + "aspeed,ast2400-lpc-host", "simple-mfd", "syscon" + "aspeed,ast2500-lpc-host", "simple-mfd", "syscon" + +- reg: contains the address and length values of the host-related + register space for the Aspeed LPC controller + +- #address-cells: <1> +- #size-cells: <1> +- ranges: Maps 0 to the address and length of the host-related LPC memory + region + +Example: + +lpc: lpc@1e789000 { + compatible = "aspeed,ast2500-lpc", "simple-mfd"; + reg = <0x1e789000 0x1000>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x1e789000 0x1000>; + + lpc_bmc: lpc-bmc@0 { + compatible = "aspeed,ast2500-lpc-bmc"; + reg = <0x0 0x80>; + }; + + lpc_host: lpc-host@80 { + compatible = "aspeed,ast2500-lpc-host", "simple-mfd", "syscon"; + reg = <0x80 0x1e0>; + reg-io-width = <4>; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x80 0x1e0>; + }; +}; + +Host Node Children +================== + +LPC Host Controller +------------------- + +The Aspeed LPC Host Controller configures the Low Pin Count (LPC) bus behaviour +between the host and the baseboard management controller. The registers exist +in the "host" portion of the Aspeed LPC controller, which must be the parent of +the LPC host controller node. + +Required properties: + +- compatible: One of: + "aspeed,ast2400-lhc"; + "aspeed,ast2500-lhc"; + +- reg: contains offset/length values of the LHC memory regions. In the + AST2400 and AST2500 there are two regions. + +Example: + +lhc: lhc@20 { + compatible = "aspeed,ast2500-lhc"; + reg = <0x20 0x24 0x48 0x8>; +}; diff --git a/Documentation/devicetree/bindings/mfd/mfd.txt b/Documentation/devicetree/bindings/mfd/mfd.txt index af9d6931a1a2..bcb6abb9d413 100644 --- a/Documentation/devicetree/bindings/mfd/mfd.txt +++ b/Documentation/devicetree/bindings/mfd/mfd.txt @@ -19,12 +19,22 @@ Optional properties: - compatible : "simple-mfd" - this signifies that the operating system should consider all subnodes of the MFD device as separate devices akin to how - "simple-bus" inidicates when to see subnodes as children for a simple + "simple-bus" indicates when to see subnodes as children for a simple memory-mapped bus. For more complex devices, when the nexus driver has to probe registers to figure out what child devices exist etc, this should not be used. In the latter case the child devices will be determined by the operating system. +- ranges: Describes the address mapping relationship to the parent. Should set + the child's base address to 0, the physical address within parent's address + space, and the length of the address map. + +- #address-cells: Specifies the number of cells used to represent physical base + addresses. Must be present if ranges is used. + +- #size-cells: Specifies the number of cells used to represent the size of an + address. Must be present if ranges is used. + Example: foo@1000 { diff --git a/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt b/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt new file mode 100644 index 000000000000..15bc885f9df4 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/motorola-cpcap.txt @@ -0,0 +1,31 @@ +Motorola CPCAP PMIC device tree binding + +Required properties: +- compatible : One or both of "motorola,cpcap" or "ste,6556002" +- reg : SPI chip select +- interrupt-parent : The parent interrupt controller +- interrupts : The interrupt line the device is connected to +- interrupt-controller : Marks the device node as an interrupt controller +- #interrupt-cells : The number of cells to describe an IRQ, should be 2 +- #address-cells : Child device offset number of cells, should be 1 +- #size-cells : Child device size number of cells, should be 0 +- spi-max-frequency : Typically set to 3000000 +- spi-cs-high : SPI chip select direction + +Example: + +&mcspi1 { + cpcap: pmic@0 { + compatible = "motorola,cpcap", "ste,6556002"; + reg = <0>; /* cs0 */ + interrupt-parent = <&gpio1>; + interrupts = <7 IRQ_TYPE_EDGE_RISING>; + interrupt-controller; + #interrupt-cells = <2>; + #address-cells = <1>; + #size-cells = <0>; + spi-max-frequency = <3000000>; + spi-cs-high; + }; +}; + diff --git a/Documentation/devicetree/bindings/mfd/mt6397.txt b/Documentation/devicetree/bindings/mfd/mt6397.txt index 949c85f8d02c..c568d52af5af 100644 --- a/Documentation/devicetree/bindings/mfd/mt6397.txt +++ b/Documentation/devicetree/bindings/mfd/mt6397.txt @@ -34,6 +34,10 @@ Optional subnodes: - clk Required properties: - compatible: "mediatek,mt6397-clk" +- led + Required properties: + - compatible: "mediatek,mt6323-led" + see Documentation/devicetree/bindings/leds/leds-mt6323.txt Example: pwrap: pwrap@1000f000 { diff --git a/Documentation/devicetree/bindings/mfd/omap-usb-host.txt b/Documentation/devicetree/bindings/mfd/omap-usb-host.txt index 4721b2d521e4..aa1eaa59581b 100644 --- a/Documentation/devicetree/bindings/mfd/omap-usb-host.txt +++ b/Documentation/devicetree/bindings/mfd/omap-usb-host.txt @@ -64,8 +64,8 @@ Required properties if child node exists: Properties for children: The OMAP HS USB Host subsystem contains EHCI and OHCI controllers. -See Documentation/devicetree/bindings/usb/omap-ehci.txt and -omap3-ohci.txt +See Documentation/devicetree/bindings/usb/ehci-omap.txt and +Documentation/devicetree/bindings/usb/ohci-omap3.txt. Example for OMAP4: diff --git a/Documentation/devicetree/bindings/mfd/qcom-rpm.txt b/Documentation/devicetree/bindings/mfd/qcom-rpm.txt index 485bc59fcc48..3c91ad430eea 100644 --- a/Documentation/devicetree/bindings/mfd/qcom-rpm.txt +++ b/Documentation/devicetree/bindings/mfd/qcom-rpm.txt @@ -234,7 +234,7 @@ see regulator.txt - with additional custom properties described below: - qcom,switch-mode-frequency: Usage: required Value type: <u32> - Definition: Frequency (Hz) of the swith mode power supply; + Definition: Frequency (Hz) of the switch mode power supply; must be one of: 19200000, 9600000, 6400000, 4800000, 3840000, 3200000, 2740000, 2400000, 2130000, 1920000, 1750000, 1600000, diff --git a/Documentation/devicetree/bindings/mfd/stm32-timers.txt b/Documentation/devicetree/bindings/mfd/stm32-timers.txt new file mode 100644 index 000000000000..bbd083f5600a --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/stm32-timers.txt @@ -0,0 +1,46 @@ +STM32 Timers driver bindings + +This IP provides 3 types of timer along with PWM functionality: +- advanced-control timers consist of a 16-bit auto-reload counter driven by a programmable + prescaler, break input feature, PWM outputs and complementary PWM ouputs channels. +- general-purpose timers consist of a 16-bit or 32-bit auto-reload counter driven by a + programmable prescaler and PWM outputs. +- basic timers consist of a 16-bit auto-reload counter driven by a programmable prescaler. + +Required parameters: +- compatible: must be "st,stm32-timers" + +- reg: Physical base address and length of the controller's + registers. +- clock-names: Set to "int". +- clocks: Phandle to the clock used by the timer module. + For Clk properties, please refer to ../clock/clock-bindings.txt + +Optional parameters: +- resets: Phandle to the parent reset controller. + See ../reset/st,stm32-rcc.txt + +Optional subnodes: +- pwm: See ../pwm/pwm-stm32.txt +- timer: See ../iio/timer/stm32-timer-trigger.txt + +Example: + timers@40010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32-timers"; + reg = <0x40010000 0x400>; + clocks = <&rcc 0 160>; + clock-names = "clk_int"; + + pwm { + compatible = "st,stm32-pwm"; + pinctrl-0 = <&pwm1_pins>; + pinctrl-names = "default"; + }; + + timer@0 { + compatible = "st,stm32-timer-trigger"; + reg = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/misc/atmel-ssc.txt b/Documentation/devicetree/bindings/misc/atmel-ssc.txt index efc98ea1f23d..f8629bb73945 100644 --- a/Documentation/devicetree/bindings/misc/atmel-ssc.txt +++ b/Documentation/devicetree/bindings/misc/atmel-ssc.txt @@ -24,6 +24,8 @@ Optional properties: this parameter to choose where the clock from. - By default the clock is from TK pin, if the clock from RK pin, this property is needed. + - #sound-dai-cells: Should contain <0>. + - This property makes the SSC into an automatically registered DAI. Examples: - PDC transfer: diff --git a/Documentation/devicetree/bindings/misc/idt_89hpesx.txt b/Documentation/devicetree/bindings/misc/idt_89hpesx.txt new file mode 100644 index 000000000000..b9093b79ab7d --- /dev/null +++ b/Documentation/devicetree/bindings/misc/idt_89hpesx.txt @@ -0,0 +1,44 @@ +EEPROM / CSR SMBus-slave interface of IDT 89HPESx devices + +Required properties: + - compatible : should be "<manufacturer>,<type>" + Basically there is only one manufacturer: idt, but some + compatible devices may be produced in future. Following devices + are supported: 89hpes8nt2, 89hpes12nt3, 89hpes24nt6ag2, + 89hpes32nt8ag2, 89hpes32nt8bg2, 89hpes12nt12g2, 89hpes16nt16g2, + 89hpes24nt24g2, 89hpes32nt24ag2, 89hpes32nt24bg2; + 89hpes12n3, 89hpes12n3a, 89hpes24n3, 89hpes24n3a; + 89hpes32h8, 89hpes32h8g2, 89hpes48h12, 89hpes48h12g2, + 89hpes48h12ag2, 89hpes16h16, 89hpes22h16, 89hpes22h16g2, + 89hpes34h16, 89hpes34h16g2, 89hpes64h16, 89hpes64h16g2, + 89hpes64h16ag2; + 89hpes12t3g2, 89hpes24t3g2, 89hpes16t4, 89hpes4t4g2, + 89hpes10t4g2, 89hpes16t4g2, 89hpes16t4ag2, 89hpes5t5, + 89hpes6t5, 89hpes8t5, 89hpes8t5a, 89hpes24t6, 89hpes6t6g2, + 89hpes24t6g2, 89hpes16t7, 89hpes32t8, 89hpes32t8g2, + 89hpes48t12, 89hpes48t12g2. + - reg : I2C address of the IDT 89HPESx device. + +Optionally there can be EEPROM-compatible subnode: + - compatible: There are five EEPROM devices supported: 24c32, 24c64, 24c128, + 24c256 and 24c512 differed by size. + - reg: Custom address of EEPROM device (If not specified IDT 89HPESx + (optional) device will try to communicate with EEPROM sited by default + address - 0x50) + - read-only : Parameterless property disables writes to the EEPROM + (optional) + +Example: + idt@60 { + compatible = "idt,89hpes32nt8ag2"; + reg = <0x74>; + #address-cells = <1>; + #size-cells = <0>; + + eeprom@50 { + compatible = "onsemi,24c64"; + reg = <0x50>; + read-only; + }; + }; + 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 fb40891ee606..9a734d808aa7 100644 --- a/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt +++ b/Documentation/devicetree/bindings/net/brcm,bcm7445-switch-v4.0.txt @@ -2,7 +2,7 @@ Required properties: -- compatible: should be "brcm,bcm7445-switch-v4.0" +- compatible: should be "brcm,bcm7445-switch-v4.0" or "brcm,bcm7278-switch-v4.0" - 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 @@ -41,6 +41,13 @@ Optional properties: Admission Control Block supports reporting the number of packets in-flight in a switch queue +Port subnodes: + +Optional properties: + +- brcm,use-bcm-hdr: boolean property, if present, indicates that the switch + port has Broadcom tags enabled (per-packet metadata) + Example: switch_top@f0b00000 { @@ -114,6 +121,7 @@ switch_top@f0b00000 { port@0 { label = "gphy"; reg = <0>; + brcm,use-bcm-hdr; }; ... }; diff --git a/Documentation/devicetree/bindings/net/brcm,systemport.txt b/Documentation/devicetree/bindings/net/brcm,systemport.txt index 877da34145b0..83f29e0e11ba 100644 --- a/Documentation/devicetree/bindings/net/brcm,systemport.txt +++ b/Documentation/devicetree/bindings/net/brcm,systemport.txt @@ -1,7 +1,10 @@ * Broadcom BCM7xxx Ethernet Systemport Controller (SYSTEMPORT) Required properties: -- compatible: should be one of "brcm,systemport-v1.00" or "brcm,systemport" +- compatible: should be one of: + "brcm,systemport-v1.00" + "brcm,systemportlite-v1.00" or + "brcm,systemport" - reg: address and length of the register set for the device. - interrupts: interrupts for the device, first cell must be for the rx interrupts, and the second cell should be for the transmit queues. An diff --git a/Documentation/devicetree/bindings/net/btusb.txt b/Documentation/devicetree/bindings/net/btusb.txt new file mode 100644 index 000000000000..01fa2d4188d4 --- /dev/null +++ b/Documentation/devicetree/bindings/net/btusb.txt @@ -0,0 +1,43 @@ +Generic Bluetooth controller over USB (btusb driver) +--------------------------------------------------- + +Required properties: + + - compatible : should comply with the format "usbVID,PID" specified in + Documentation/devicetree/bindings/usb/usb-device.txt + At the time of writing, the only OF supported devices + (more may be added later) are: + + "usb1286,204e" (Marvell 8997) + +Also, vendors that use btusb may have device additional properties, e.g: +Documentation/devicetree/bindings/net/marvell-bt-8xxx.txt + +Optional properties: + + - interrupt-parent: phandle of the parent interrupt controller + - interrupt-names: (see below) + - interrupts : The interrupt specified by the name "wakeup" is the interrupt + that shall be used for out-of-band wake-on-bt. Driver will + request this interrupt for wakeup. During system suspend, the + irq will be enabled so that the bluetooth chip can wakeup host + platform out of band. During system resume, the irq will be + disabled to make sure unnecessary interrupt is not received. + +Example: + +Following example uses irq pin number 3 of gpio0 for out of band wake-on-bt: + +&usb_host1_ehci { + status = "okay"; + #address-cells = <1>; + #size-cells = <0>; + + mvl_bt1: bt@1 { + compatible = "usb1286,204e"; + reg = <1>; + interrupt-parent = <&gpio0>; + interrupt-name = "wakeup"; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index ebda7c93453a..7cc15c96ea95 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -23,7 +23,6 @@ Required properties: Optional properties: - ti,hwmods : Must be "cpgmac0" -- no_bd_ram : Must be 0 or 1 - dual_emac : Specifies Switch to act as Dual EMAC - syscon : Phandle to the system control device node, which is the control module device of the am33x @@ -70,7 +69,6 @@ Examples: cpdma_channels = <8>; ale_entries = <1024>; bd_ram_size = <0x2000>; - no_bd_ram = <0>; rx_descs = <64>; mac_control = <0x20>; slaves = <2>; @@ -99,7 +97,6 @@ Examples: cpdma_channels = <8>; ale_entries = <1024>; bd_ram_size = <0x2000>; - no_bd_ram = <0>; rx_descs = <64>; mac_control = <0x20>; slaves = <2>; diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index a4a570fb2494..cfe8f64eca4f 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -34,13 +34,9 @@ Required properties: Each port children node must have the following mandatory properties: - reg : Describes the port address in the switch -- label : Describes the label associated with this port, which - will become the netdev name. Special labels are - "cpu" to indicate a CPU port and "dsa" to - indicate an uplink/downlink port between switches in - the cluster. -A port labelled "dsa" has the following mandatory property: +An uplink/downlink port between switches in the cluster has the following +mandatory property: - link : Should be a list of phandles to other switch's DSA port. This port is used as the outgoing port @@ -48,12 +44,17 @@ A port labelled "dsa" has the following mandatory property: information must be given, not just the one hop routes to neighbouring switches. -A port labelled "cpu" has the following mandatory property: +A CPU port has the following mandatory property: - ethernet : Should be a phandle to a valid Ethernet device node. This host device is what the switch port is connected to. +A user port has the following optional property: + +- label : Describes the label associated with this port, which + will become the netdev name. + Port child nodes may also contain the following optional standardised properties, described in binding documents: @@ -107,7 +108,6 @@ linked into one DSA cluster. switch0port5: port@5 { reg = <5>; - label = "dsa"; phy-mode = "rgmii-txid"; link = <&switch1port6 &switch2port9>; @@ -119,7 +119,6 @@ linked into one DSA cluster. port@6 { reg = <6>; - label = "cpu"; ethernet = <&fec1>; fixed-link { speed = <100>; @@ -165,7 +164,6 @@ linked into one DSA cluster. switch1port5: port@5 { reg = <5>; - label = "dsa"; link = <&switch2port9>; phy-mode = "rgmii-txid"; fixed-link { @@ -176,7 +174,6 @@ linked into one DSA cluster. switch1port6: port@6 { reg = <6>; - label = "dsa"; phy-mode = "rgmii-txid"; link = <&switch0port5>; fixed-link { @@ -255,7 +252,6 @@ linked into one DSA cluster. switch2port9: port@9 { reg = <9>; - label = "dsa"; phy-mode = "rgmii-txid"; link = <&switch1port5 &switch0port5>; diff --git a/Documentation/devicetree/bindings/net/dsa/marvell.txt b/Documentation/devicetree/bindings/net/dsa/marvell.txt index b3dd6b40e0de..7ef9dbb08957 100644 --- a/Documentation/devicetree/bindings/net/dsa/marvell.txt +++ b/Documentation/devicetree/bindings/net/dsa/marvell.txt @@ -14,9 +14,9 @@ The properties described here are those specific to Marvell devices. Additional required and optional properties can be found in dsa.txt. Required properties: -- compatible : Should be one of "marvell,mv88e6085" or - "marvell,mv88e6190" -- reg : Address on the MII bus for the switch. +- compatible : Should be one of "marvell,mv88e6085" or + "marvell,mv88e6190" +- reg : Address on the MII bus for the switch. Optional properties: @@ -26,30 +26,67 @@ Optional properties: - interrupt-controller : Indicates the switch is itself an interrupt controller. This is used for the PHY interrupts. #interrupt-cells = <2> : Controller uses two cells, number and flag -- mdio : container of PHY and devices on the switches MDIO - bus +- mdio : Container of PHY and devices on the switches MDIO + bus. +- mdio? : Container of PHYs and devices on the external MDIO + bus. The node must contains a compatible string of + "marvell,mv88e6xxx-mdio-external" + Example: - mdio { - #address-cells = <1>; - #size-cells = <0>; - interrupt-parent = <&gpio0>; - interrupts = <27 IRQ_TYPE_LEVEL_LOW>; - interrupt-controller; - #interrupt-cells = <2>; - - switch0: switch@0 { - compatible = "marvell,mv88e6085"; - reg = <0>; - reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; - }; - mdio { - #address-cells = <1>; - #size-cells = <0>; - switch1phy0: switch1phy0@0 { - reg = <0>; - interrupt-parent = <&switch0>; - interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; - }; - }; - }; + mdio { + #address-cells = <1>; + #size-cells = <0>; + interrupt-parent = <&gpio0>; + interrupts = <27 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + + switch0: switch@0 { + compatible = "marvell,mv88e6085"; + reg = <0>; + reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; + }; + mdio { + #address-cells = <1>; + #size-cells = <0>; + switch1phy0: switch1phy0@0 { + reg = <0>; + interrupt-parent = <&switch0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + }; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + interrupt-parent = <&gpio0>; + interrupts = <27 IRQ_TYPE_LEVEL_LOW>; + interrupt-controller; + #interrupt-cells = <2>; + + switch0: switch@0 { + compatible = "marvell,mv88e6390"; + reg = <0>; + reset-gpios = <&gpio5 1 GPIO_ACTIVE_LOW>; + }; + mdio { + #address-cells = <1>; + #size-cells = <0>; + switch1phy0: switch1phy0@0 { + reg = <0>; + interrupt-parent = <&switch0>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + }; + }; + + mdio1 { + compatible = "marvell,mv88e6xxx-mdio-external"; + #address-cells = <1>; + #size-cells = <0>; + switch1phy9: switch1phy0@9 { + reg = <9>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index 05150957ecfd..3a6916909d90 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -29,6 +29,9 @@ The following properties are common to the Ethernet controllers: * "smii" * "xgmii" * "trgmii" + * "2000base-x", + * "2500base-x", + * "rxaui" - 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/marvell,prestera.txt b/Documentation/devicetree/bindings/net/marvell,prestera.txt new file mode 100644 index 000000000000..5fbab29718e8 --- /dev/null +++ b/Documentation/devicetree/bindings/net/marvell,prestera.txt @@ -0,0 +1,50 @@ +Marvell Prestera Switch Chip bindings +------------------------------------- + +Required properties: +- compatible: one of the following + "marvell,prestera-98dx3236", + "marvell,prestera-98dx3336", + "marvell,prestera-98dx4251", +- reg: address and length of the register set for the device. +- interrupts: interrupt for the device + +Optional properties: +- dfx: phandle reference to the "DFX Server" node + +Example: + +switch { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 MBUS_ID(0x03, 0x00) 0 0x100000>; + + packet-processor@0 { + compatible = "marvell,prestera-98dx3236"; + reg = <0 0x4000000>; + interrupts = <33>, <34>, <35>; + dfx = <&dfx>; + }; +}; + +DFX Server bindings +------------------- + +Required properties: +- compatible: must be "marvell,dfx-server" +- reg: address and length of the register set for the device. + +Example: + +dfx-registers { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 MBUS_ID(0x08, 0x00) 0 0x100000>; + + dfx: dfx@0 { + compatible = "marvell,dfx-server"; + reg = <0 0x100000>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt index 7aa840c8768d..ae4234ca4ee4 100644 --- a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt +++ b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt @@ -1,7 +1,7 @@ * Marvell Armada 370 / Armada XP / Armada 3700 Ethernet Controller (NETA) Required properties: -- compatible: could be one of the followings +- compatible: could be one of the following: "marvell,armada-370-neta" "marvell,armada-xp-neta" "marvell,armada-3700-neta" diff --git a/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt b/Documentation/devicetree/bindings/net/marvell-bt-8xxx.txt index 6a9a63cb0543..9be1059ff03f 100644 --- a/Documentation/devicetree/bindings/net/marvell-bt-sd8xxx.txt +++ b/Documentation/devicetree/bindings/net/marvell-bt-8xxx.txt @@ -1,16 +1,21 @@ -Marvell 8897/8997 (sd8897/sd8997) bluetooth SDIO devices +Marvell 8897/8997 (sd8897/sd8997) bluetooth devices (SDIO or USB based) ------ +The 8997 devices supports multiple interfaces. When used on SDIO interfaces, +the btmrvl driver is used and when used on USB interface, the btusb driver is +used. Required properties: - compatible : should be one of the following: - * "marvell,sd8897-bt" - * "marvell,sd8997-bt" + * "marvell,sd8897-bt" (for SDIO) + * "marvell,sd8997-bt" (for SDIO) + * "usb1286,204e" (for USB) Optional properties: - marvell,cal-data: Calibration data downloaded to the device during initialization. This is an array of 28 values(u8). + This is only applicable to SDIO devices. - marvell,wakeup-pin: It represents wakeup pin number of the bluetooth chip. firmware will use the pin to wakeup host system (u16). @@ -18,10 +23,15 @@ Optional properties: platform. The value will be configured to firmware. This is needed to work chip's sleep feature as expected (u16). - interrupt-parent: phandle of the parent interrupt controller - - interrupts : interrupt pin number to the cpu. Driver will request an irq based - on this interrupt number. During system suspend, the irq will be - enabled so that the bluetooth chip can wakeup host platform under - certain condition. During system resume, the irq will be disabled + - interrupt-names: Used only for USB based devices (See below) + - interrupts : specifies the interrupt pin number to the cpu. For SDIO, the + driver will use the first interrupt specified in the interrupt + array. For USB based devices, the driver will use the interrupt + named "wakeup" from the interrupt-names and interrupt arrays. + The driver will request an irq based on this interrupt number. + During system suspend, the irq will be enabled so that the + bluetooth chip can wakeup host platform under certain + conditions. During system resume, the irq will be disabled to make sure unnecessary interrupt is not received. Example: @@ -29,7 +39,9 @@ Example: IRQ pin 119 is used as system wakeup source interrupt. wakeup pin 13 and gap 100ms are configured so that firmware can wakeup host using this device side pin and wakeup latency. -calibration data is also available in below example. + +Example for SDIO device follows (calibration data is also available in +below example). &mmc3 { status = "okay"; @@ -54,3 +66,21 @@ calibration data is also available in below example. marvell,wakeup-gap-ms = /bits/ 16 <0x64>; }; }; + +Example for USB device: + +&usb_host1_ohci { + status = "okay"; + #address-cells = <1>; + #size-cells = <0>; + + mvl_bt1: bt@1 { + compatible = "usb1286,204e"; + reg = <1>; + interrupt-parent = <&gpio0>; + interrupt-names = "wakeup"; + interrupts = <119 IRQ_TYPE_LEVEL_LOW>; + marvell,wakeup-pin = /bits/ 16 <0x0d>; + marvell,wakeup-gap-ms = /bits/ 16 <0x64>; + }; +}; diff --git a/Documentation/devicetree/bindings/net/marvell-pp2.txt b/Documentation/devicetree/bindings/net/marvell-pp2.txt index aa4f4230bfd7..4754364df4c6 100644 --- a/Documentation/devicetree/bindings/net/marvell-pp2.txt +++ b/Documentation/devicetree/bindings/net/marvell-pp2.txt @@ -27,9 +27,7 @@ Optional properties (port): - marvell,loopback: port is loopback mode - phy: a phandle to a phy node defining the PHY address (as the reg - property, a single integer). Note: if this property isn't present, - then fixed link is assumed, and the 'fixed-link' property is - mandatory. + property, a single integer). Example: diff --git a/Documentation/devicetree/bindings/net/meson-dwmac.txt b/Documentation/devicetree/bindings/net/meson-dwmac.txt index 89e62ddc69ca..0703ad3f3c1e 100644 --- a/Documentation/devicetree/bindings/net/meson-dwmac.txt +++ b/Documentation/devicetree/bindings/net/meson-dwmac.txt @@ -25,6 +25,22 @@ Required properties on Meson8b and newer: - "clkin0" - first parent clock of the internal mux - "clkin1" - second parent clock of the internal mux +Optional properties on Meson8b and newer: +- amlogic,tx-delay-ns: The internal RGMII TX clock delay (provided + by this driver) in nanoseconds. Allowed values + are: 0ns, 2ns, 4ns, 6ns. + When phy-mode is set to "rgmii" then the TX + delay should be explicitly configured. When + not configured a fallback of 2ns is used. + When the phy-mode is set to either "rgmii-id" + or "rgmii-txid" the TX clock delay is already + provided by the PHY. In that case this + property should be set to 0ns (which disables + the TX clock delay in the MAC to prevent the + clock from going off because both PHY and MAC + are adding a delay). + Any configuration is ignored when the phy-mode + is set to "rmii". Example for Meson6: diff --git a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt index bdefefc66594..0eedabe22cc3 100644 --- a/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt +++ b/Documentation/devicetree/bindings/net/mscc-phy-vsc8531.txt @@ -27,6 +27,14 @@ Optional properties: 'vddmac'. Default value is 0%. Ref: Table:1 - Edge rate change (below). +- vsc8531,led-0-mode : LED mode. Specify how the LED[0] should behave. + Allowed values are define in + "include/dt-bindings/net/mscc-phy-vsc8531.h". + Default value is VSC8531_LINK_1000_ACTIVITY (1). +- vsc8531,led-1-mode : LED mode. Specify how the LED[1] should behave. + Allowed values are define in + "include/dt-bindings/net/mscc-phy-vsc8531.h". + Default value is VSC8531_LINK_100_ACTIVITY (2). Table: 1 - Edge rate change ----------------------------------------------------------------| @@ -60,4 +68,6 @@ Example: compatible = "ethernet-phy-id0007.0570"; vsc8531,vddmac = <3300>; vsc8531,edge-slowdown = <7>; + vsc8531,led-0-mode = <LINK_1000_ACTIVITY>; + vsc8531,led-1-mode = <LINK_100_ACTIVITY>; }; diff --git a/Documentation/devicetree/bindings/net/phy.txt b/Documentation/devicetree/bindings/net/phy.txt index fb5056b22685..b55857696fc3 100644 --- a/Documentation/devicetree/bindings/net/phy.txt +++ b/Documentation/devicetree/bindings/net/phy.txt @@ -39,6 +39,10 @@ Optional Properties: - enet-phy-lane-swap: If set, indicates the PHY will swap the TX/RX lanes to compensate for the board being designed with the lanes swapped. +- enet-phy-lane-no-swap: If set, indicates that PHY will disable swap of the + TX/RX lanes. This property allows the PHY to work correcly after e.g. wrong + bootstrap configuration caused by issues in PCB layout design. + - eee-broken-100tx: - eee-broken-1000t: - eee-broken-10gt: diff --git a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt index 95383c5131fc..8f427550720a 100644 --- a/Documentation/devicetree/bindings/net/rockchip-dwmac.txt +++ b/Documentation/devicetree/bindings/net/rockchip-dwmac.txt @@ -6,6 +6,7 @@ Required properties: - compatible: should be "rockchip,<name>-gamc" "rockchip,rk3228-gmac": found on RK322x SoCs "rockchip,rk3288-gmac": found on RK3288 SoCs + "rockchip,rk3328-gmac": found on RK3328 SoCs "rockchip,rk3366-gmac": found on RK3366 SoCs "rockchip,rk3368-gmac": found on RK3368 SoCs "rockchip,rk3399-gmac": found on RK3399 SoCs diff --git a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt index d93f71ce8346..21d27aa4c68c 100644 --- a/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt +++ b/Documentation/devicetree/bindings/net/snps,dwc-qos-ethernet.txt @@ -1,5 +1,8 @@ * Synopsys DWC Ethernet QoS IP version 4.10 driver (GMAC) +This binding is deprecated, but it continues to be supported, but new +features should be preferably added to the stmmac binding document. + 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 diff --git a/Documentation/devicetree/bindings/net/stmmac.txt b/Documentation/devicetree/bindings/net/stmmac.txt index 128da752fec9..d3bfc2b30fb5 100644 --- a/Documentation/devicetree/bindings/net/stmmac.txt +++ b/Documentation/devicetree/bindings/net/stmmac.txt @@ -49,6 +49,8 @@ Optional properties: - snps,force_sf_dma_mode Force DMA to use the Store and Forward mode for both tx and rx. This flag is ignored if force_thresh_dma_mode is set. +- snps,en-tx-lpi-clockgating Enable gating of the MAC TX clock during + TX low-power mode - snps,multicast-filter-bins: Number of multicast filter hash bins supported by this device instance - snps,perfect-filter-entries: Number of perfect filter entries supported @@ -65,7 +67,6 @@ Optional properties: - snps,wr_osr_lmt: max write outstanding req. limit - snps,rd_osr_lmt: max read outstanding req. limit - snps,kbbe: do not cross 1KiB boundary. - - snps,axi_all: align address - snps,blen: this is a vector of supported burst length. - snps,fb: fixed-burst - snps,mb: mixed-burst diff --git a/Documentation/devicetree/bindings/net/wireless/ieee80211.txt b/Documentation/devicetree/bindings/net/wireless/ieee80211.txt new file mode 100644 index 000000000000..f6442b1397f5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/wireless/ieee80211.txt @@ -0,0 +1,24 @@ +Common IEEE 802.11 properties + +This provides documentation of common properties that are valid for all wireless +devices. + +Optional properties: + - ieee80211-freq-limit : list of supported frequency ranges in KHz. This can be + used for devices that in a given config support less channels than + normally. It may happen chipset supports a wide wireless band but it is + limited to some part of it due to used antennas or power amplifier. + An example case for this can be tri-band wireless router with two + identical chipsets used for two different 5 GHz subbands. Using them + incorrectly could not work or decrease performance noticeably. + +Example: + +pcie@0,0 { + reg = <0x0000 0 0 0 0>; + wifi@0,0 { + reg = <0x0000 0 0 0 0>; + ieee80211-freq-limit = <2402000 2482000>, + <5170000 5250000>; + }; +}; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 383d5889e95a..966a72ecc6bd 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -1,13 +1,15 @@ Freescale i.MX6 On-Chip OTP Controller (OCOTP) device tree bindings This binding represents the on-chip eFuse OTP controller found on -i.MX6Q/D, i.MX6DL/S, i.MX6SL, and i.MX6SX SoCs. +i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX and i.MX6UL SoCs. Required properties: - compatible: should be one of "fsl,imx6q-ocotp" (i.MX6Q/D/DL/S), "fsl,imx6sl-ocotp" (i.MX6SL), or - "fsl,imx6sx-ocotp" (i.MX6SX), followed by "syscon". + "fsl,imx6sx-ocotp" (i.MX6SX), + "fsl,imx6ul-ocotp" (i.MX6UL), + followed by "syscon". - reg: Should contain the register base and length. - clocks: Should contain a phandle pointing to the gated peripheral clock. diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index 9f5ca4457b5f..63725498bd20 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -136,7 +136,7 @@ Optional properties: larger OPP table, based on what version of the hardware we are running on. We still can't have multiple nodes with the same opp-hz value in OPP table. - It's an user defined array containing a hierarchy of hardware version numbers, + It's a user defined array containing a hierarchy of hardware version numbers, supported by the OPP. For example: a platform with hierarchy of three levels of versions (A, B and C), this field should be like <X Y Z>, where X corresponds to Version hierarchy A, Y corresponds to version hierarchy B and Z @@ -188,14 +188,14 @@ Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000 975000 985000>; + opp-microvolt = <975000 970000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <980000 1000000 1010000>; + opp-microvolt = <1000000 980000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; @@ -267,14 +267,14 @@ independently. opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000 975000 985000>; + opp-microvolt = <975000 970000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <980000 1000000 1010000>; + opp-microvolt = <1000000 980000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; @@ -343,14 +343,14 @@ DVFS state together. opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000 975000 985000>; + opp-microvolt = <975000 970000 985000>; opp-microamp = <70000>; clock-latency-ns = <300000>; opp-suspend; }; opp@1100000000 { opp-hz = /bits/ 64 <1100000000>; - opp-microvolt = <980000 1000000 1010000>; + opp-microvolt = <1000000 980000 1010000>; opp-microamp = <80000>; clock-latency-ns = <310000>; }; @@ -369,7 +369,7 @@ DVFS state together. opp@1300000000 { opp-hz = /bits/ 64 <1300000000>; - opp-microvolt = <1045000 1050000 1055000>; + opp-microvolt = <1050000 1045000 1055000>; opp-microamp = <95000>; clock-latency-ns = <400000>; opp-suspend; @@ -382,7 +382,7 @@ DVFS state together. }; opp@1500000000 { opp-hz = /bits/ 64 <1500000000>; - opp-microvolt = <1010000 1100000 1110000>; + opp-microvolt = <1100000 1010000 1110000>; opp-microamp = <95000>; clock-latency-ns = <400000>; turbo-mode; @@ -424,9 +424,9 @@ Example 4: Handling multiple regulators opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000 975000 985000>, /* Supply 0 */ - <960000 965000 975000>, /* Supply 1 */ - <960000 965000 975000>; /* Supply 2 */ + opp-microvolt = <975000 970000 985000>, /* Supply 0 */ + <965000 960000 975000>, /* Supply 1 */ + <965000 960000 975000>; /* Supply 2 */ opp-microamp = <70000>, /* Supply 0 */ <70000>, /* Supply 1 */ <70000>; /* Supply 2 */ @@ -437,9 +437,9 @@ Example 4: Handling multiple regulators opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt = <970000 975000 985000>, /* Supply 0 */ - <960000 965000 975000>, /* Supply 1 */ - <960000 965000 975000>; /* Supply 2 */ + opp-microvolt = <975000 970000 985000>, /* Supply 0 */ + <965000 960000 975000>, /* Supply 1 */ + <965000 960000 975000>; /* Supply 2 */ opp-microamp = <70000>, /* Supply 0 */ <0>, /* Supply 1 doesn't need this */ <70000>; /* Supply 2 */ @@ -474,7 +474,7 @@ Example 5: opp-supported-hw */ opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF> opp-hz = /bits/ 64 <600000000>; - opp-microvolt = <900000 915000 925000>; + opp-microvolt = <915000 900000 925000>; ... }; @@ -487,7 +487,7 @@ Example 5: opp-supported-hw */ opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0> opp-hz = /bits/ 64 <800000000>; - opp-microvolt = <900000 915000 925000>; + opp-microvolt = <915000 900000 925000>; ... }; }; @@ -512,18 +512,18 @@ Example 6: opp-microvolt-<name>, opp-microamp-<name>: opp@1000000000 { opp-hz = /bits/ 64 <1000000000>; - opp-microvolt-slow = <900000 915000 925000>; - opp-microvolt-fast = <970000 975000 985000>; + opp-microvolt-slow = <915000 900000 925000>; + opp-microvolt-fast = <975000 970000 985000>; opp-microamp-slow = <70000>; opp-microamp-fast = <71000>; }; opp@1200000000 { opp-hz = /bits/ 64 <1200000000>; - opp-microvolt-slow = <900000 915000 925000>, /* Supply vcc0 */ - <910000 925000 935000>; /* Supply vcc1 */ - opp-microvolt-fast = <970000 975000 985000>, /* Supply vcc0 */ - <960000 965000 975000>; /* Supply vcc1 */ + opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */ + <925000 910000 935000>; /* Supply vcc1 */ + opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */ + <965000 960000 975000>; /* Supply vcc1 */ opp-microamp = <70000>; /* Will be used for both slow/fast */ }; }; diff --git a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt index 59c2f47aa303..b7fa3b97986d 100644 --- a/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt +++ b/Documentation/devicetree/bindings/pci/hisilicon-pcie.txt @@ -42,3 +42,40 @@ Hip05 Example (note that Hip06 is the same except compatible): 0x0 0 0 4 &mbigen_pcie 4 13>; status = "ok"; }; + +HiSilicon Hip06/Hip07 PCIe host bridge DT (almost-ECAM) description. +The properties and their meanings are identical to those described in +host-generic-pci.txt except as listed below. + +Properties of the host controller node that differ from +host-generic-pci.txt: + +- compatible : Must be "hisilicon,pcie-almost-ecam" + +- reg : Two entries: First the ECAM configuration space for any + other bus underneath the root bus. Second, the base + and size of the HiSilicon host bridge registers include + the RC's own config space. + +Example: + pcie0: pcie@a0090000 { + compatible = "hisilicon,pcie-almost-ecam"; + reg = <0 0xb0000000 0 0x2000000>, /* ECAM configuration space */ + <0 0xa0090000 0 0x10000>; /* host bridge registers */ + bus-range = <0 31>; + msi-map = <0x0000 &its_dsa 0x0000 0x2000>; + msi-map-mask = <0xffff>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + dma-coherent; + ranges = <0x02000000 0 0xb2000000 0x0 0xb2000000 0 0x5ff0000 + 0x01000000 0 0 0 0xb7ff0000 0 0x10000>; + #interrupt-cells = <1>; + interrupt-map-mask = <0xf800 0 0 7>; + interrupt-map = <0x0 0 0 1 &mbigen_pcie0 650 4 + 0x0 0 0 2 &mbigen_pcie0 650 4 + 0x0 0 0 3 &mbigen_pcie0 650 4 + 0x0 0 0 4 &mbigen_pcie0 650 4>; + status = "ok"; + }; diff --git a/Documentation/devicetree/bindings/pci/mvebu-pci.txt b/Documentation/devicetree/bindings/pci/mvebu-pci.txt index 08c716b2c6b6..2de6f65ecfb1 100644 --- a/Documentation/devicetree/bindings/pci/mvebu-pci.txt +++ b/Documentation/devicetree/bindings/pci/mvebu-pci.txt @@ -78,7 +78,8 @@ and the following optional properties: multiple lanes. If this property is not found, we assume that the value is 0. - reset-gpios: optional gpio to PERST# -- reset-delay-us: delay in us to wait after reset de-assertion +- reset-delay-us: delay in us to wait after reset de-assertion, if not + specified will default to 100ms, as required by the PCIe specification. Example: diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt index 56c829621b9a..0def586fdcdf 100644 --- a/Documentation/devicetree/bindings/pci/pci-iommu.txt +++ b/Documentation/devicetree/bindings/pci/pci-iommu.txt @@ -32,17 +32,17 @@ PCI root complex Optional properties ------------------- -- iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier +- 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). + 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. + mapped to an IOMMU specifier per the iommu-map property. Example (1) diff --git a/Documentation/devicetree/bindings/pci/rcar-pci.txt b/Documentation/devicetree/bindings/pci/rcar-pci.txt index eee518db90b9..34712d6fd253 100644 --- a/Documentation/devicetree/bindings/pci/rcar-pci.txt +++ b/Documentation/devicetree/bindings/pci/rcar-pci.txt @@ -6,6 +6,7 @@ compatible: "renesas,pcie-r8a7779" for the R8A7779 SoC; "renesas,pcie-r8a7791" for the R8A7791 SoC; "renesas,pcie-r8a7793" for the R8A7793 SoC; "renesas,pcie-r8a7795" for the R8A7795 SoC; + "renesas,pcie-r8a7796" for the R8A7796 SoC; "renesas,pcie-rcar-gen2" for a generic R-Car Gen2 compatible device. "renesas,pcie-rcar-gen3" for a generic R-Car Gen3 compatible device. diff --git a/Documentation/devicetree/bindings/pci/rockchip-pcie.txt b/Documentation/devicetree/bindings/pci/rockchip-pcie.txt index 71aeda1ca055..1453a734c2f5 100644 --- a/Documentation/devicetree/bindings/pci/rockchip-pcie.txt +++ b/Documentation/devicetree/bindings/pci/rockchip-pcie.txt @@ -43,6 +43,8 @@ Required properties: - interrupt-map-mask and interrupt-map: standard PCI properties Optional Property: +- aspm-no-l0s: RC won't support ASPM L0s. This property is needed if + using 24MHz OSC for RC's PHY. - 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. diff --git a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt index 4f9d23d2ed67..7d3b09474657 100644 --- a/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt +++ b/Documentation/devicetree/bindings/pci/samsung,exynos5440-pcie.txt @@ -7,8 +7,19 @@ Required properties: - compatible: "samsung,exynos5440-pcie" - reg: base addresses and lengths of the pcie controller, the phy controller, additional register for the phy controller. + (Registers for the phy controller are DEPRECATED. + Use the PHY framework.) +- reg-names : First name should be set to "elbi". + And use the "config" instead of getting the confgiruation address space + from "ranges". + NOTE: When use the "config" property, reg-names must be set. - interrupts: A list of interrupt outputs for level interrupt, pulse interrupt, special interrupt. +- phys: From PHY binding. Phandle for the Generic PHY. + Refer to Documentation/devicetree/bindings/phy/samsung-phy.txt + +Other common properties refer to + Documentation/devicetree/binding/pci/designware-pcie.txt Example: @@ -54,6 +65,24 @@ SoC specific DT Entry: num-lanes = <4>; }; +With using PHY framework: + pcie_phy0: pcie-phy@270000 { + ... + reg = <0x270000 0x1000>, <0x271000 0x40>; + reg-names = "phy", "block"; + ... + }; + + pcie@290000 { + ... + reg = <0x290000 0x1000>, <0x40000000 0x1000>; + reg-names = "elbi", "config"; + phys = <&pcie_phy0>; + ranges = <0x81000000 0 0 0x60001000 0 0x00010000 + 0x82000000 0 0x60011000 0x60011000 0 0x1ffef000>; + ... + }; + Board specific DT Entry: pcie@290000 { diff --git a/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt b/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt new file mode 100644 index 000000000000..e68ae5dec9c9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/brcm,nsp-usb3-phy.txt @@ -0,0 +1,39 @@ +Broadcom USB3 phy binding for northstar plus SoC +The USB3 phy is internal to the SoC and is accessed using mdio interface. + +Required mdio bus properties: +- reg: Should be 0x0 for SoC internal USB3 phy +- #address-cells: must be 1 +- #size-cells: must be 0 + +Required USB3 PHY properties: +- compatible: should be "brcm,nsp-usb3-phy" +- reg: USB3 Phy address on SoC internal MDIO bus and it should be 0x10. +- usb3-ctrl-syscon: handler of syscon node defining physical address + of usb3 control register. +- #phy-cells: must be 0 + +Required usb3 control properties: +- compatible: should be "brcm,nsp-usb3-ctrl" +- reg: offset and length of the control registers + +Example: + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + + usb3_phy: usb-phy@10 { + compatible = "brcm,nsp-usb3-phy"; + reg = <0x10>; + usb3-ctrl-syscon = <&usb3_ctrl>; + #phy-cells = <0>; + status = "disabled"; + }; + }; + + usb3_ctrl: syscon@104408 { + compatible = "brcm,nsp-usb3-ctrl", "syscon"; + reg = <0x104408 0x3fc>; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-hs-phy.txt b/Documentation/devicetree/bindings/phy/qcom,usb-hs-phy.txt new file mode 100644 index 000000000000..b3b75c1e6285 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,usb-hs-phy.txt @@ -0,0 +1,84 @@ +Qualcomm's USB HS PHY + +PROPERTIES + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,usb-hs-phy" and more specifically one of the + following: + + "qcom,usb-hs-phy-apq8064" + "qcom,usb-hs-phy-msm8916" + "qcom,usb-hs-phy-msm8974" + +- #phy-cells: + Usage: required + Value type: <u32> + Definition: Should contain 0 + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: Should contain clock specifier for the reference and sleep + clocks + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: Should contain "ref" and "sleep" for the reference and sleep + clocks respectively + +- resets: + Usage: required + Value type: <prop-encoded-array> + Definition: Should contain the phy and POR resets + +- reset-names: + Usage: required + Value type: <stringlist> + Definition: Should contain "phy" and "por" for the phy and POR resets + respectively + +- v3p3-supply: + Usage: required + Value type: <phandle> + Definition: Should contain a reference to the 3.3V supply + +- v1p8-supply: + Usage: required + Value type: <phandle> + Definition: Should contain a reference to the 1.8V supply + +- extcon: + Usage: optional + Value type: <prop-encoded-array> + Definition: Should contain the vbus extcon + +- qcom,init-seq: + Usage: optional + Value type: <u8 array> + Definition: Should contain a sequence of ULPI address and value pairs to + program into the ULPI_EXT_VENDOR_SPECIFIC area. This is related + to Device Mode Eye Diagram test. The addresses are offsets + from the ULPI_EXT_VENDOR_SPECIFIC address, for example, + <0x1 0x53> would mean "write the value 0x53 to address 0x81". + +EXAMPLE + +otg: usb-controller { + ulpi { + phy { + compatible = "qcom,usb-hs-phy-msm8974", "qcom,usb-hs-phy"; + #phy-cells = <0>; + clocks = <&xo_board>, <&gcc GCC_USB2A_PHY_SLEEP_CLK>; + clock-names = "ref", "sleep"; + resets = <&gcc GCC_USB2A_PHY_BCR>, <&otg 0>; + reset-names = "phy", "por"; + v3p3-supply = <&pm8941_l24>; + v1p8-supply = <&pm8941_l6>; + extcon = <&smbb>; + qcom,init-seq = /bits/ 8 <0x1 0x63>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/qcom,usb-hsic-phy.txt b/Documentation/devicetree/bindings/phy/qcom,usb-hsic-phy.txt new file mode 100644 index 000000000000..3c7cb2be4b12 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,usb-hsic-phy.txt @@ -0,0 +1,65 @@ +Qualcomm's USB HSIC PHY + +PROPERTIES + +- compatible: + Usage: required + Value type: <string> + Definition: Should contain "qcom,usb-hsic-phy" and more specifically one of the + following: + + "qcom,usb-hsic-phy-mdm9615" + "qcom,usb-hsic-phy-msm8974" + +- #phy-cells: + Usage: required + Value type: <u32> + Definition: Should contain 0 + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: Should contain clock specifier for phy, calibration and + a calibration sleep clock + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: Should contain "phy, "cal" and "cal_sleep" + +- pinctrl-names: + Usage: required + Value type: <stringlist> + Definition: Should contain "init" and "default" in that order + +- pinctrl-0: + Usage: required + Value type: <prop-encoded-array> + Definition: List of pinctrl settings to apply to keep HSIC pins in a glitch + free state + +- pinctrl-1: + Usage: required + Value type: <prop-encoded-array> + Definition: List of pinctrl settings to apply to mux out the HSIC pins + +EXAMPLE + +usb-controller { + ulpi { + phy { + compatible = "qcom,usb-hsic-phy-msm8974", + "qcom,usb-hsic-phy"; + #phy-cells = <0>; + pinctrl-names = "init", "default"; + pinctrl-0 = <&hsic_sleep>; + pinctrl-1 = <&hsic_default>; + clocks = <&gcc GCC_USB_HSIC_CLK>, + <&gcc GCC_USB_HSIC_IO_CAL_CLK>, + <&gcc GCC_USB_HSIC_IO_CAL_SLEEP_CLK>; + clock-names = "phy", "cal", "cal_sleep"; + assigned-clocks = <&gcc GCC_USB_HSIC_IO_CAL_CLK>; + assigned-clock-rates = <960000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/phy/samsung-phy.txt b/Documentation/devicetree/bindings/phy/samsung-phy.txt index 9872ba8546bd..ab80bfe31cb3 100644 --- a/Documentation/devicetree/bindings/phy/samsung-phy.txt +++ b/Documentation/devicetree/bindings/phy/samsung-phy.txt @@ -191,3 +191,20 @@ Example: usbdrdphy0 = &usb3_phy0; usbdrdphy1 = &usb3_phy1; }; + +Samsung Exynos SoC series PCIe PHY controller +-------------------------------------------------- +Required properties: +- compatible : Should be set to "samsung,exynos5440-pcie-phy" +- #phy-cells : Must be zero +- reg : a register used by phy driver. + - First is for phy register, second is for block register. +- reg-names : Must be set to "phy" and "block". + +Example: + pcie_phy0: pcie-phy@270000 { + #phy-cells = <0>; + compatible = "samsung,exynos5440-pcie-phy"; + reg = <0x270000 0x1000>, <0x271000 0x40>; + reg-names = "phy", "block"; + }; diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index 287150db6db4..e42334258185 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,sun8i-v3s-usb-phy * allwinner,sun50i-a64-usb-phy - reg : a list of offset + length pairs - reg-names : diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 7c85dca4221a..2fd688c8dbdb 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -6,7 +6,7 @@ the first two functions being GPIO in and out. The configuration on the pins includes drive strength and pull-up. Required properties: -- compatible: Should be one of the followings (depending on you SoC): +- compatible: Should be one of the following (depending on your SoC): "allwinner,sun4i-a10-pinctrl" "allwinner,sun5i-a10s-pinctrl" "allwinner,sun5i-a13-pinctrl" diff --git a/Documentation/devicetree/bindings/power/pd-samsung.txt b/Documentation/devicetree/bindings/power/pd-samsung.txt index 4e947372a693..549f7dee9b9d 100644 --- a/Documentation/devicetree/bindings/power/pd-samsung.txt +++ b/Documentation/devicetree/bindings/power/pd-samsung.txt @@ -6,12 +6,15 @@ to gate power to one or more peripherals on the processor. Required Properties: - compatible: should be one of the following. * samsung,exynos4210-pd - for exynos4210 type power domain. + * samsung,exynos5433-pd - for exynos5433 type power domain. - reg: physical base address of the controller and length of memory mapped region. - #power-domain-cells: number of cells in power domain specifier; must be 0. Optional Properties: +- label: Human readable string with domain name. Will be visible in userspace + to let user to distinguish between multiple domains in SoC. - clocks: List of clock handles. The parent clocks of the input clocks to the devices in this power domain are set to oscclk before power gating and restored back after powering on a domain. This is required for @@ -20,7 +23,7 @@ Optional Properties: - clock-names: The following clocks can be specified: - oscclk: Oscillator clock. - clkN: Input clocks to the devices in this power domain. These clocks - will be reparented to oscclk before swithing power domain off. + will be reparented to oscclk before switching power domain off. Their original parent will be brought back after turning on the domain. Maximum of 4 clocks (N = 0 to 3) are supported. - asbN: Clocks required by asynchronous bridges (ASB) present in @@ -38,6 +41,7 @@ Example: compatible = "samsung,exynos4210-pd"; reg = <0x10023C00 0x10>; #power-domain-cells = <0>; + label = "LCD0"; }; mfc_pd: power-domain@10044060 { @@ -46,6 +50,7 @@ Example: clocks = <&clock CLK_FIN_PLL>, <&clock CLK_MOUT_USER_ACLK333>; clock-names = "oscclk", "clk0"; #power-domain-cells = <0>; + label = "MFC"; }; See Documentation/devicetree/bindings/power/power_domain.txt for description diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt index d4eab9227ea4..e62d53d844cc 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt @@ -2,12 +2,12 @@ Driver a GPIO line that can be used to turn the power off. The driver supports both level triggered and edge triggered power off. At driver load time, the driver will request the given gpio line and -install a pm_power_off handler. If the optional properties 'input' is -not found, the GPIO line will be driven in the inactive +install a handler to power off the system. If the optional properties +'input' is not found, the GPIO line will be driven in the inactive state. Otherwise its configured as an input. -When the pm_power_off is called, the gpio is configured as an output, -and drive active, so triggering a level triggered power off +When the power-off handler is called, the gpio is configured as an +output, and drive active, so triggering a level triggered power off condition. This will also cause an inactive->active edge condition, so triggering positive edge triggered power off. After a delay of 100ms, the GPIO is set to inactive, thus causing an active->inactive edge, @@ -24,7 +24,7 @@ Required properties: Optional properties: - input : Initially configure the GPIO line as an input. Only reconfigure - it to an output when the pm_power_off function is called. If this optional + it to an output when the power-off handler is called. If this optional property is not specified, the GPIO is initialized as an output in its inactive state. diff --git a/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt b/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt index af25e77c0e0c..c363d7173129 100644 --- a/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/qnap-poweroff.txt @@ -3,8 +3,7 @@ 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. +microcontroller to turn the power off. Synology NAS devices use a similar scheme, but a different baud rate, 9600, and a different character, '1'. diff --git a/Documentation/devicetree/bindings/powerpc/4xx/emac.txt b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt index 712baf6c3e24..44b842b6ca15 100644 --- a/Documentation/devicetree/bindings/powerpc/4xx/emac.txt +++ b/Documentation/devicetree/bindings/powerpc/4xx/emac.txt @@ -71,6 +71,9 @@ For Axon it can be absent, though my current driver doesn't handle phy-address yet so for now, keep 0x00ffffff in it. + - phy-handle : Used to describe configurations where a external PHY + is used. Please refer to: + Documentation/devicetree/bindings/net/ethernet.txt - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec operations (if absent the value is the same as rx-fifo-size). For Axon, either absent or 2048. @@ -81,8 +84,22 @@ offload, phandle of the TAH device node. - tah-channel : 1 cell, optional. If appropriate, channel used on the TAH engine. + - fixed-link : Fixed-link subnode describing a link to a non-MDIO + managed entity. See + Documentation/devicetree/bindings/net/fixed-link.txt + for details. + - mdio subnode : When the EMAC has a phy connected to its local + mdio, which us supported by the kernel's network + PHY library in drivers/net/phy, there must be device + tree subnode with the following required properties: + - #address-cells: Must be <1>. + - #size-cells: Must be <0>. - Example: + For PHY definitions: Please refer to + Documentation/devicetree/bindings/net/phy.txt and + Documentation/devicetree/bindings/net/ethernet.txt + + Examples: EMAC0: ethernet@40000800 { device_type = "network"; @@ -104,6 +121,48 @@ zmii-channel = <0>; }; + EMAC1: ethernet@ef600c00 { + device_type = "network"; + compatible = "ibm,emac-apm821xx", "ibm,emac4sync"; + interrupt-parent = <&EMAC1>; + interrupts = <0 1>; + #interrupt-cells = <1>; + #address-cells = <0>; + #size-cells = <0>; + interrupt-map = <0 &UIC2 0x10 IRQ_TYPE_LEVEL_HIGH /* Status */ + 1 &UIC2 0x14 IRQ_TYPE_LEVEL_HIGH /* Wake */>; + reg = <0xef600c00 0x000000c4>; + local-mac-address = [000000000000]; /* Filled in by U-Boot */ + mal-device = <&MAL0>; + mal-tx-channel = <0>; + mal-rx-channel = <0>; + cell-index = <0>; + max-frame-size = <9000>; + rx-fifo-size = <16384>; + tx-fifo-size = <2048>; + fifo-entry-size = <10>; + phy-mode = "rgmii"; + phy-handle = <&phy0>; + phy-map = <0x00000000>; + rgmii-device = <&RGMII0>; + rgmii-channel = <0>; + tah-device = <&TAH0>; + tah-channel = <0>; + has-inverted-stacr-oc; + has-new-stacr-staopc; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + phy0: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <0>; + }; + }; + }; + + ii) McMAL node Required properties: @@ -145,4 +204,3 @@ - revision : as provided by the RGMII new version register if available. For Axon: 0x0000012a - diff --git a/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt b/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt index c41b2187eaa8..dc9bb3182525 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/l2cache.txt @@ -5,8 +5,46 @@ The cache bindings explained below are ePAPR compliant Required Properties: -- compatible : Should include "fsl,chip-l2-cache-controller" and "cache" - where chip is the processor (bsc9132, npc8572 etc.) +- compatible : Should include one of the following: + "fsl,8540-l2-cache-controller" + "fsl,8541-l2-cache-controller" + "fsl,8544-l2-cache-controller" + "fsl,8548-l2-cache-controller" + "fsl,8555-l2-cache-controller" + "fsl,8568-l2-cache-controller" + "fsl,b4420-l2-cache-controller" + "fsl,b4860-l2-cache-controller" + "fsl,bsc9131-l2-cache-controller" + "fsl,bsc9132-l2-cache-controller" + "fsl,c293-l2-cache-controller" + "fsl,mpc8536-l2-cache-controller" + "fsl,mpc8540-l2-cache-controller" + "fsl,mpc8541-l2-cache-controller" + "fsl,mpc8544-l2-cache-controller" + "fsl,mpc8548-l2-cache-controller" + "fsl,mpc8555-l2-cache-controller" + "fsl,mpc8560-l2-cache-controller" + "fsl,mpc8568-l2-cache-controller" + "fsl,mpc8569-l2-cache-controller" + "fsl,mpc8572-l2-cache-controller" + "fsl,p1010-l2-cache-controller" + "fsl,p1011-l2-cache-controller" + "fsl,p1012-l2-cache-controller" + "fsl,p1013-l2-cache-controller" + "fsl,p1014-l2-cache-controller" + "fsl,p1015-l2-cache-controller" + "fsl,p1016-l2-cache-controller" + "fsl,p1020-l2-cache-controller" + "fsl,p1021-l2-cache-controller" + "fsl,p1022-l2-cache-controller" + "fsl,p1023-l2-cache-controller" + "fsl,p1024-l2-cache-controller" + "fsl,p1025-l2-cache-controller" + "fsl,p2010-l2-cache-controller" + "fsl,p2020-l2-cache-controller" + "fsl,t2080-l2-cache-controller" + "fsl,t4240-l2-cache-controller" + and "cache". - reg : Address and size of L2 cache controller registers - cache-size : Size of the entire L2 cache - interrupts : Error interrupt of L2 controller diff --git a/Documentation/devicetree/bindings/powerpc/opal/power-mgt.txt b/Documentation/devicetree/bindings/powerpc/opal/power-mgt.txt new file mode 100644 index 000000000000..9d619e955576 --- /dev/null +++ b/Documentation/devicetree/bindings/powerpc/opal/power-mgt.txt @@ -0,0 +1,118 @@ +IBM Power-Management Bindings +============================= + +Linux running on baremetal POWER machines has access to the processor +idle states. The description of these idle states is exposed via the +node @power-mgt in the device-tree by the firmware. + +Definitions: +---------------- +Typically each idle state has the following associated properties: + +- name: The name of the idle state as defined by the firmware. + +- flags: indicating some aspects of this idle states such as the + extent of state-loss, whether timebase is stopped on this + idle states and so on. The flag bits are as follows: + +- exit-latency: The latency involved in transitioning the state of the + CPU from idle to running. + +- target-residency: The minimum time that the CPU needs to reside in + this idle state in order to accrue power-savings + benefit. + +Properties +---------------- +The following properties provide details about the idle states. These +properties are exposed as arrays. Each entry in the property array +provides the value of that property for the idle state associated with +the array index of that entry. + +If idle-states are defined, then the properties +"ibm,cpu-idle-state-names" and "ibm,cpu-idle-state-flags" are +required. The other properties are required unless mentioned +otherwise. The length of all the property arrays must be the same. + +- ibm,cpu-idle-state-names: + Array of strings containing the names of the idle states. + +- ibm,cpu-idle-state-flags: + Array of unsigned 32-bit values containing the values of the + flags associated with the the aforementioned idle-states. The + flag bits are as follows: + 0x00000001 /* Decrementer would stop */ + 0x00000002 /* Needs timebase restore */ + 0x00001000 /* Restore GPRs like nap */ + 0x00002000 /* Restore hypervisor resource from PACA pointer */ + 0x00004000 /* Program PORE to restore PACA pointer */ + 0x00010000 /* This is a nap state (POWER7,POWER8) */ + 0x00020000 /* This is a fast-sleep state (POWER8)*/ + 0x00040000 /* This is a winkle state (POWER8) */ + 0x00080000 /* This is a fast-sleep state which requires a */ + /* software workaround for restoring the */ + /* timebase (POWER8) */ + 0x00800000 /* This state uses SPR PMICR instruction */ + /* (POWER8)*/ + 0x00100000 /* This is a fast stop state (POWER9) */ + 0x00200000 /* This is a deep-stop state (POWER9) */ + +- ibm,cpu-idle-state-latencies-ns: + Array of unsigned 32-bit values containing the values of the + exit-latencies (in ns) for the idle states in + ibm,cpu-idle-state-names. + +- ibm,cpu-idle-state-residency-ns: + Array of unsigned 32-bit values containing the values of the + target-residency (in ns) for the idle states in + ibm,cpu-idle-state-names. On POWER8 this is an optional + property. If the property is absent, the target residency for + the "Nap", "FastSleep" are defined to 10000 and 300000000 + respectively by the kernel. On POWER9 this property is required. + +- ibm,cpu-idle-state-psscr: + Array of unsigned 64-bit values containing the values for the + PSSCR for each of the idle states in ibm,cpu-idle-state-names. + This property is required on POWER9 and absent on POWER8. + +- ibm,cpu-idle-state-psscr-mask: + Array of unsigned 64-bit values containing the masks + indicating which psscr fields are set in the corresponding + entries of ibm,cpu-idle-state-psscr. This property is + required on POWER9 and absent on POWER8. + + Whenever the firmware sets an entry in + ibm,cpu-idle-state-psscr-mask value to 0xf, it implies that + only the Requested Level (RL) field of the corresponding entry + in ibm,cpu-idle-state-psscr should be considered by the + kernel. For such idle states, the kernel would set the + remaining fields of the psscr to the following sane-default + values. + + - ESL and EC bits are to 1. So wakeup from any stop + state will be at vector 0x100. + + - MTL and PSLL are set to the maximum allowed value as + per the ISA, i.e. 15. + + - The Transition Rate, TR is set to the Maximum value + 3. + + For all the other values of the entry in + ibm,cpu-idle-state-psscr-mask, the kernel expects all the + psscr fields of the corresponding entry in + ibm,cpu-idle-state-psscr to be correctly set by the firmware. + +- ibm,cpu-idle-state-pmicr: + Array of unsigned 64-bit values containing the pmicr values + for the idle states in ibm,cpu-idle-state-names. This 64-bit + register value is to be set in pmicr for the corresponding + state if the flag indicates that pmicr SPR should be set. This + is an optional property on POWER8 and is absent on + POWER9. + +- ibm,cpu-idle-state-pmicr-mask: + Array of unsigned 64-bit values containing the mask indicating + which of the fields of the PMICR are set in the corresponding + entries in ibm,cpu-idle-state-pmicr. This is an optional + property on POWER8 and is absent on POWER9. diff --git a/Documentation/devicetree/bindings/pwm/imx-pwm.txt b/Documentation/devicetree/bindings/pwm/imx-pwm.txt index e00c2e9f484d..c61bdf8cd41b 100644 --- a/Documentation/devicetree/bindings/pwm/imx-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/imx-pwm.txt @@ -6,8 +6,8 @@ Required properties: - "fsl,imx1-pwm" for PWM compatible with the one integrated on i.MX1 - "fsl,imx27-pwm" for PWM compatible with the one integrated on i.MX27 - reg: physical base address and length of the controller's registers -- #pwm-cells: should be 2. See pwm.txt in this directory for a description of - the cells format. +- #pwm-cells: 2 for i.MX1 and 3 for i.MX27 and newer SoCs. See pwm.txt + in this directory for a description of the cells format. - clocks : Clock specifiers for both ipg and per clocks. - clock-names : Clock names should include both "ipg" and "per" See the clock consumer binding, @@ -17,7 +17,7 @@ See the clock consumer binding, Example: pwm1: pwm@53fb4000 { - #pwm-cells = <2>; + #pwm-cells = <3>; compatible = "fsl,imx53-pwm", "fsl,imx27-pwm"; reg = <0x53fb4000 0x4000>; clocks = <&clks IMX5_CLK_PWM1_IPG_GATE>, diff --git a/Documentation/devicetree/bindings/pwm/pwm-stm32.txt b/Documentation/devicetree/bindings/pwm/pwm-stm32.txt new file mode 100644 index 000000000000..6dd040363e5e --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/pwm-stm32.txt @@ -0,0 +1,35 @@ +STMicroelectronics STM32 Timers PWM bindings + +Must be a sub-node of an STM32 Timers device tree node. +See ../mfd/stm32-timers.txt for details about the parent node. + +Required parameters: +- compatible: Must be "st,stm32-pwm". +- pinctrl-names: Set to "default". +- pinctrl-0: List of phandles pointing to pin configuration nodes for PWM module. + For Pinctrl properties see ../pinctrl/pinctrl-bindings.txt + +Optional parameters: +- st,breakinput: One or two <index level filter> to describe break input configurations. + "index" indicates on which break input (0 or 1) the configuration + should be applied. + "level" gives the active level (0=low or 1=high) of the input signal + for this configuration. + "filter" gives the filtering value to be applied. + +Example: + timers@40010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "st,stm32-timers"; + reg = <0x40010000 0x400>; + clocks = <&rcc 0 160>; + clock-names = "clk_int"; + + pwm { + compatible = "st,stm32-pwm"; + pinctrl-0 = <&pwm1_pins>; + pinctrl-names = "default"; + st,breakinput = <0 1 5>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/ti-abb-regulator.txt b/Documentation/devicetree/bindings/regulator/ti-abb-regulator.txt index c3f6546ebac7..6a23ad9ac53a 100644 --- a/Documentation/devicetree/bindings/regulator/ti-abb-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/ti-abb-regulator.txt @@ -45,7 +45,7 @@ Required Properties: Optional Properties: - reg-names: In addition to the required properties, the following are optional - "efuse-address" - Contains efuse base address used to pick up ABB info. - - "ldo-address" - Contains address of ABB LDO overide register address. + - "ldo-address" - Contains address of ABB LDO override register. "efuse-address" is required for this. - ti,ldovbb-vset-mask - Required if ldo-address is set, mask for LDO override register to provide override vset value. diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt index b85885a298d8..75ad7b8df0b1 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt @@ -9,6 +9,7 @@ on the Qualcomm ADSP Hexagon core. Definition: must be one of: "qcom,msm8974-adsp-pil" "qcom,msm8996-adsp-pil" + "qcom,msm8996-slpi-pil" - interrupts-extended: Usage: required @@ -24,13 +25,13 @@ on the Qualcomm ADSP Hexagon core. - clocks: Usage: required Value type: <prop-encoded-array> - Definition: reference to the xo clock to be held on behalf of the - booting Hexagon core + Definition: reference to the xo clock and optionally aggre2 clock to be + held on behalf of the booting Hexagon core - clock-names: Usage: required Value type: <stringlist> - Definition: must be "xo" + Definition: must be "xo" and optionally include "aggre2" - cx-supply: Usage: required @@ -38,6 +39,12 @@ on the Qualcomm ADSP Hexagon core. Definition: reference to the regulator to be held on behalf of the booting Hexagon core +- px-supply: + Usage: required + Value type: <phandle> + Definition: reference to the px regulator to be held on behalf of the + booting Hexagon core + - memory-region: Usage: required Value type: <phandle> @@ -96,3 +103,31 @@ ADSP, as it is found on MSM8974 boards. qcom,smd-edge = <1>; }; }; + +The following example describes the resources needed to boot control the +SLPI, as it is found on MSM8996 boards. + + slpi { + compatible = "qcom,msm8996-slpi-pil"; + interrupts-extended = <&intc 0 390 IRQ_TYPE_EDGE_RISING>, + <&slpi_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, + <&slpi_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, + <&slpi_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, + <&slpi_smp2p_in 3 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", + "fatal", + "ready", + "handover", + "stop-ack"; + + clocks = <&rpmcc MSM8996_RPM_SMD_XO_CLK_SRC>, + <&rpmcc MSM8996_RPM_SMD_AGGR2_NOC_CLK>; + clock-names = "xo", "aggre2"; + + cx-supply = <&pm8994_l26>; + px-supply = <&pm8994_lvs2>; + + memory-region = <&slpi_region>; + qcom,smem-states = <&slpi_smp2p_out 0>; + qcom,smem-state-names = "stop"; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt index 57cb49ec55ca..92347fe6890e 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt @@ -7,7 +7,9 @@ on the Qualcomm Hexagon core. Usage: required Value type: <string> Definition: must be one of: - "qcom,q6v5-pil" + "qcom,q6v5-pil", + "qcom,msm8916-mss-pil", + "qcom,msm8974-mss-pil" - reg: Usage: required diff --git a/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt new file mode 100644 index 000000000000..2bf3344b2a02 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/hisilicon,hi3660-reset.txt @@ -0,0 +1,43 @@ +Hisilicon System Reset Controller +====================================== + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +The reset controller registers are part of the system-ctl block on +hi3660 SoC. + +Required properties: +- compatible: should be + "hisilicon,hi3660-reset" +- hisi,rst-syscon: phandle of the reset's syscon. +- #reset-cells : Specifies the number of cells needed to encode a + reset source. The type shall be a <u32> and the value shall be 2. + + Cell #1 : offset of the reset assert control + register from the syscon register base + offset + 4: deassert control register + offset + 8: status control register + Cell #2 : bit position of the reset in the reset control register + +Example: + iomcu: iomcu@ffd7e000 { + compatible = "hisilicon,hi3660-iomcu", "syscon"; + reg = <0x0 0xffd7e000 0x0 0x1000>; + }; + + iomcu_rst: iomcu_rst_controller { + compatible = "hisilicon,hi3660-reset"; + hisi,rst-syscon = <&iomcu>; + #reset-cells = <2>; + }; + +Specifying reset lines connected to IP modules +============================================== +example: + + i2c0: i2c@..... { + ... + resets = <&iomcu_rst 0x20 3>; /* offset: 0x20; bit: 3 */ + ... + }; diff --git a/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt b/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt index 164c7f34c451..c516d24959f2 100644 --- a/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt +++ b/Documentation/devicetree/bindings/reset/ti-syscon-reset.txt @@ -63,7 +63,7 @@ Example: -------- The following example demonstrates a syscon node, the reset controller node using the syscon node, and a consumer (a DSP device) on the TI Keystone 2 -Edison SoC. +66AK2E SoC. / { soc { @@ -71,13 +71,13 @@ Edison SoC. compatible = "syscon", "simple-mfd"; reg = <0x02350000 0x1000>; - pscrst: psc-reset { + pscrst: reset-controller { compatible = "ti,k2e-pscrst", "ti,syscon-reset"; #reset-cells = <1>; ti,reset-bits = < - 0xa3c 8 0xa3c 8 0x83c 8 (ASSERT_SET|DEASSERT_CLEAR|STATUS_SET) /* 0: pcrst-dsp0 */ - 0xa40 5 0xa44 3 0 0 (ASSERT_SET|DEASSERT_CLEAR|STATUS_NONE) /* 1: pcrst-example */ + 0xa3c 8 0xa3c 8 0x83c 8 (ASSERT_CLEAR | DEASSERT_SET | STATUS_CLEAR) /* 0: dsp0 */ + 0xa40 5 0xa44 3 0 0 (ASSERT_SET | DEASSERT_CLEAR | STATUS_NONE) /* 1: example */ >; }; }; diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt index 5020524cddeb..83ab0f599c40 100644 --- a/Documentation/devicetree/bindings/reset/uniphier-reset.txt +++ b/Documentation/devicetree/bindings/reset/uniphier-reset.txt @@ -6,14 +6,14 @@ System reset Required properties: - compatible: should be one of the following: - "socionext,uniphier-sld3-reset" - for sLD3 SoC. - "socionext,uniphier-ld4-reset" - for LD4 SoC. - "socionext,uniphier-pro4-reset" - for Pro4 SoC. - "socionext,uniphier-sld8-reset" - for sLD8 SoC. - "socionext,uniphier-pro5-reset" - for Pro5 SoC. - "socionext,uniphier-pxs2-reset" - for PXs2/LD6b SoC. - "socionext,uniphier-ld11-reset" - for LD11 SoC. - "socionext,uniphier-ld20-reset" - for LD20 SoC. + "socionext,uniphier-sld3-reset" - for sLD3 SoC + "socionext,uniphier-ld4-reset" - for LD4 SoC + "socionext,uniphier-pro4-reset" - for Pro4 SoC + "socionext,uniphier-sld8-reset" - for sLD8 SoC + "socionext,uniphier-pro5-reset" - for Pro5 SoC + "socionext,uniphier-pxs2-reset" - for PXs2/LD6b SoC + "socionext,uniphier-ld11-reset" - for LD11 SoC + "socionext,uniphier-ld20-reset" - for LD20 SoC - #reset-cells: should be 1. Example: @@ -37,14 +37,15 @@ Media I/O (MIO) reset, SD reset Required properties: - compatible: should be one of the following: - "socionext,uniphier-sld3-mio-reset" - for sLD3 SoC. - "socionext,uniphier-ld4-mio-reset" - for LD4 SoC. - "socionext,uniphier-pro4-mio-reset" - for Pro4 SoC. - "socionext,uniphier-sld8-mio-reset" - for sLD8 SoC. - "socionext,uniphier-pro5-sd-reset" - for Pro5 SoC. - "socionext,uniphier-pxs2-sd-reset" - for PXs2/LD6b SoC. - "socionext,uniphier-ld11-mio-reset" - for LD11 SoC. - "socionext,uniphier-ld20-sd-reset" - for LD20 SoC. + "socionext,uniphier-sld3-mio-reset" - for sLD3 SoC + "socionext,uniphier-ld4-mio-reset" - for LD4 SoC + "socionext,uniphier-pro4-mio-reset" - for Pro4 SoC + "socionext,uniphier-sld8-mio-reset" - for sLD8 SoC + "socionext,uniphier-pro5-sd-reset" - for Pro5 SoC + "socionext,uniphier-pxs2-sd-reset" - for PXs2/LD6b SoC + "socionext,uniphier-ld11-mio-reset" - for LD11 SoC (MIO) + "socionext,uniphier-ld11-sd-reset" - for LD11 SoC (SD) + "socionext,uniphier-ld20-sd-reset" - for LD20 SoC - #reset-cells: should be 1. Example: @@ -68,13 +69,13 @@ Peripheral reset Required properties: - compatible: should be one of the following: - "socionext,uniphier-ld4-peri-reset" - for LD4 SoC. - "socionext,uniphier-pro4-peri-reset" - for Pro4 SoC. - "socionext,uniphier-sld8-peri-reset" - for sLD8 SoC. - "socionext,uniphier-pro5-peri-reset" - for Pro5 SoC. - "socionext,uniphier-pxs2-peri-reset" - for PXs2/LD6b SoC. - "socionext,uniphier-ld11-peri-reset" - for LD11 SoC. - "socionext,uniphier-ld20-peri-reset" - for LD20 SoC. + "socionext,uniphier-ld4-peri-reset" - for LD4 SoC + "socionext,uniphier-pro4-peri-reset" - for Pro4 SoC + "socionext,uniphier-sld8-peri-reset" - for sLD8 SoC + "socionext,uniphier-pro5-peri-reset" - for Pro5 SoC + "socionext,uniphier-pxs2-peri-reset" - for PXs2/LD6b SoC + "socionext,uniphier-ld11-peri-reset" - for LD11 SoC + "socionext,uniphier-ld20-peri-reset" - for LD20 SoC - #reset-cells: should be 1. Example: diff --git a/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt b/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt new file mode 100644 index 000000000000..b015508f9780 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/zte,zx2967-reset.txt @@ -0,0 +1,20 @@ +ZTE zx2967 SoCs Reset Controller +======================================= + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +Required properties: +- compatible: should be one of the following. + * zte,zx296718-reset +- reg: physical base address of the controller and length of memory mapped + region. +- #reset-cells: must be 1. + +example: + + reset: reset-controller@1461060 { + compatible = "zte,zx296718-reset"; + reg = <0x01461060 0x8>; + #reset-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt b/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt index 2eb9d4ee7dc0..c3c9a1226f9a 100644 --- a/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/armada-380-rtc.txt @@ -1,9 +1,11 @@ -* Real Time Clock of the Armada 38x SoCs +* Real Time Clock of the Armada 38x/7K/8K SoCs -RTC controller for the Armada 38x SoCs +RTC controller for the Armada 38x, 7K and 8K SoCs Required properties: -- compatible : Should be "marvell,armada-380-rtc" +- compatible : Should be one of the following: + "marvell,armada-380-rtc" for Armada 38x SoC + "marvell,armada-8k-rtc" for Aramda 7K/8K SoCs - reg: a list of base address and size pairs, one for each entry in reg-names - reg names: should contain: diff --git a/Documentation/devicetree/bindings/rtc/cortina,gemini.txt b/Documentation/devicetree/bindings/rtc/cortina,gemini.txt new file mode 100644 index 000000000000..4ce4e794ddbb --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/cortina,gemini.txt @@ -0,0 +1,14 @@ +* Cortina Systems Gemini RTC + +Gemini SoC real-time clock. + +Required properties: +- compatible : Should be "cortina,gemini-rtc" + +Examples: + +rtc@45000000 { + compatible = "cortina,gemini-rtc"; + reg = <0x45000000 0x100>; + interrupts = <17 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt b/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt index c9d80d7da141..323cf26374cb 100644 --- a/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/imxdi-rtc.txt @@ -8,10 +8,13 @@ Required properties: region. - interrupts: rtc alarm interrupt +Optional properties: +- interrupts: dryice security violation interrupt + Example: rtc@80056000 { compatible = "fsl,imx53-rtc", "fsl,imx25-rtc"; reg = <0x80056000 2000>; - interrupts = <29>; + interrupts = <29 56>; }; diff --git a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt index 1ad4c1c2b3b3..85be53a42180 100644 --- a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt +++ b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt @@ -1,7 +1,8 @@ * Maxim DS3231 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst +- compatible: Should contain "maxim,ds3231". +- reg: I2C address for chip. Optional property: - #clock-cells: Should be 1. diff --git a/Documentation/devicetree/bindings/rtc/pcf8563.txt b/Documentation/devicetree/bindings/rtc/pcf8563.txt index 086c998c5561..36984acbb383 100644 --- a/Documentation/devicetree/bindings/rtc/pcf8563.txt +++ b/Documentation/devicetree/bindings/rtc/pcf8563.txt @@ -3,7 +3,8 @@ Philips PCF8563/Epson RTC8564 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst +- compatible: Should contain "nxp,pcf8563". +- reg: I2C address for chip. Optional property: - #clock-cells: Should be 0. diff --git a/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt new file mode 100644 index 000000000000..e2837b951237 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/st,stm32-rtc.txt @@ -0,0 +1,27 @@ +STM32 Real Time Clock + +Required properties: +- compatible: "st,stm32-rtc". +- reg: address range of rtc register set. +- clocks: reference to the clock entry ck_rtc. +- interrupt-parent: phandle for the interrupt controller. +- interrupts: rtc alarm interrupt. +- st,syscfg: phandle for pwrcfg, mandatory to disable/enable backup domain + (RTC registers) write protection. + +Optional properties (to override default ck_rtc parent clock): +- assigned-clocks: reference to the ck_rtc clock entry. +- assigned-clock-parents: phandle of the new parent clock of ck_rtc. + +Example: + + rtc: rtc@40002800 { + compatible = "st,stm32-rtc"; + reg = <0x40002800 0x400>; + clocks = <&rcc 1 CLK_RTC>; + assigned-clocks = <&rcc 1 CLK_RTC>; + assigned-clock-parents = <&rcc 1 CLK_LSE>; + interrupt-parent = <&exti>; + interrupts = <17 1>; + st,syscfg = <&pwrcfg>; + }; diff --git a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt index f007e428a1ab..945934918b71 100644 --- a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt @@ -8,10 +8,20 @@ Required properties: memory mapped region. - interrupts : IRQ lines for the RTC alarm 0 and alarm 1, in that order. +Required properties for new device trees +- clocks : phandle to the 32kHz external oscillator +- clock-output-names : name of the LOSC clock created +- #clock-cells : must be equals to 1. The RTC provides two clocks: the + LOSC and its external output, with index 0 and 1 + respectively. + Example: rtc: rtc@01f00000 { compatible = "allwinner,sun6i-a31-rtc"; reg = <0x01f00000 0x54>; interrupts = <0 40 4>, <0 41 4>; + clock-output-names = "osc32k"; + clocks = <&ext_osc32k>; + #clock-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/serial/8250.txt b/Documentation/devicetree/bindings/serial/8250.txt index f86bb06c39e9..10276a46ecef 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -19,6 +19,7 @@ Required properties: - "altr,16550-FIFO128" - "fsl,16550-FIFO64" - "fsl,ns16550" + - "ti,da830-uart" - "serial" if the port type is unknown. - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt index 1e82802d8e32..574c3a2c77d5 100644 --- a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -6,11 +6,13 @@ Required properties: - interrupts : Should contain uart interrupt Optional properties: -- uart-has-rtscts : Indicate the uart has rts and cts - fsl,irda-mode : Indicate the uart supports irda mode - fsl,dte-mode : Indicate the uart works in DTE mode. The uart works in DCE mode by default. +Please check Documentation/devicetree/bindings/serial/serial.txt +for the complete list of generic properties. + Note: Each uart controller should have an alias correctly numbered in "aliases" node. diff --git a/Documentation/devicetree/bindings/serial/serial.txt b/Documentation/devicetree/bindings/serial/serial.txt index fd970f76a7b8..b542a0ecf06e 100644 --- a/Documentation/devicetree/bindings/serial/serial.txt +++ b/Documentation/devicetree/bindings/serial/serial.txt @@ -23,7 +23,8 @@ Optional properties: they are available for use (wired and enabled by pinmux configuration). This depends on both the UART hardware and the board wiring. Note that this property is mutually-exclusive with "cts-gpios" and - "rts-gpios" above. + "rts-gpios" above, unless support is provided to switch between modes + dynamically. Examples: diff --git a/Documentation/devicetree/bindings/serial/slave-device.txt b/Documentation/devicetree/bindings/serial/slave-device.txt new file mode 100644 index 000000000000..f66037928f5f --- /dev/null +++ b/Documentation/devicetree/bindings/serial/slave-device.txt @@ -0,0 +1,36 @@ +Serial Slave Device DT binding + +This documents the binding structure and common properties for serial +attached devices. Common examples include Bluetooth, WiFi, NFC and GPS +devices. + +Serial attached devices shall be a child node of the host UART device the +slave device is attached to. It is expected that the attached device is +the only child node of the UART device. The slave device node name shall +reflect the generic type of device for the node. + +Required Properties: + +- compatible : A string reflecting the vendor and specific device the node + represents. + +Optional Properties: + +- max-speed : The maximum baud rate the device operates at. This should + only be present if the maximum is less than the slave device + can support. For example, a particular board has some signal + quality issue or the host processor can't support higher + baud rates. + +Example: + +serial@1234 { + compatible = "ns16550a"; + interrupts = <1>; + + bluetooth { + compatible = "brcm,bcm43341-bt"; + interrupt-parent = <&gpio>; + interrupts = <10>; + }; +}; diff --git a/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt index 47e46ccbc170..5a34f3ab7bea 100644 --- a/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt +++ b/Documentation/devicetree/bindings/soc/fsl/qman-portals.txt @@ -5,7 +5,6 @@ Copyright (C) 2008 - 2014 Freescale Semiconductor Inc. CONTENTS - QMan Portal - - QMan Pool Channel - Example QMan Portal Node @@ -82,25 +81,6 @@ These subnodes should have the following properties: Definition: The phandle to the particular hardware device that this portal is connected to. -DPAA QMan Pool Channel Nodes - -Pool Channels are defined with the following properties. - -PROPERTIES - -- compatible - Usage: Required - Value type: <stringlist> - Definition: Must include "fsl,qman-pool-channel" - May include "fsl,<SoC>-qman-pool-channel" - -- fsl,qman-channel-id - Usage: Required - Value type: <u32> - Definition: The hardware index of the channel. This can also be - determined by dividing any of the channel's 8 work queue - IDs by 8 - EXAMPLE The example below shows a (P4080) QMan portals container/bus node with two portals diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.txt b/Documentation/devicetree/bindings/soc/rockchip/grf.txt index 013e71a2cdc7..a0685c209218 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.txt +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.txt @@ -5,20 +5,24 @@ is composed of many registers for system control. From RK3368 SoCs, the GRF is divided into two sections, - GRF, used for general non-secure system, +- SGRF, used for general secure system, - PMUGRF, used for always on system Required Properties: -- compatible: GRF should be one of the followings +- compatible: GRF should be one of the following: + - "rockchip,rk3036-grf", "syscon": for rk3036 - "rockchip,rk3066-grf", "syscon": for rk3066 - "rockchip,rk3188-grf", "syscon": for rk3188 - "rockchip,rk3228-grf", "syscon": for rk3228 - "rockchip,rk3288-grf", "syscon": for rk3288 - "rockchip,rk3368-grf", "syscon": for rk3368 - "rockchip,rk3399-grf", "syscon": for rk3399 -- compatible: PMUGRF should be one of the followings +- compatible: PMUGRF should be one of the following: - "rockchip,rk3368-pmugrf", "syscon": for rk3368 - "rockchip,rk3399-pmugrf", "syscon": for rk3399 +- compatible: SGRF should be one of the following + - "rockchip,rk3288-sgrf", "syscon": for rk3288 - reg: physical base address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt index f909ce06afc4..01bfb6745fbd 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt +++ b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt @@ -6,6 +6,7 @@ powered up/down by software based on different application scenes to save power. Required properties for power domain controller: - compatible: Should be one of the following. "rockchip,rk3288-power-controller" - for RK3288 SoCs. + "rockchip,rk3328-power-controller" - for RK3328 SoCs. "rockchip,rk3368-power-controller" - for RK3368 SoCs. "rockchip,rk3399-power-controller" - for RK3399 SoCs. - #power-domain-cells: Number of cells in a power-domain specifier. @@ -16,6 +17,7 @@ Required properties for power domain controller: Required properties for power domain sub nodes: - reg: index of the power domain, should use macros in: "include/dt-bindings/power/rk3288-power.h" - for RK3288 type power domain. + "include/dt-bindings/power/rk3328-power.h" - for RK3328 type power domain. "include/dt-bindings/power/rk3368-power.h" - for RK3368 type power domain. "include/dt-bindings/power/rk3399-power.h" - for RK3399 type power domain. - clocks (optional): phandles to clocks which need to be enabled while power domain @@ -90,6 +92,7 @@ containing a phandle to the power device node and an index specifying which power domain to use. The index should use macros in: "include/dt-bindings/power/rk3288-power.h" - for rk3288 type power domain. + "include/dt-bindings/power/rk3328-power.h" - for rk3328 type power domain. "include/dt-bindings/power/rk3368-power.h" - for rk3368 type power domain. "include/dt-bindings/power/rk3399-power.h" - for rk3399 type power domain. diff --git a/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt b/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt new file mode 100644 index 000000000000..7629de1c2c72 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/zte/pd-2967xx.txt @@ -0,0 +1,19 @@ +* ZTE zx2967 family Power Domains + +zx2967 family includes support for multiple power domains which are used +to gate power to one or more peripherals on the processor. + +Required Properties: + - compatible: should be one of the following. + * zte,zx296718-pcu - for zx296718 power domain. + - reg: physical base address of the controller and length of memory mapped + region. + - #power-domain-cells: Must be 1. + +Example: + + pcu_domain: pcu@117000 { + compatible = "zte,zx296718-pcu"; + reg = <0x00117000 0x1000>; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt b/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt index 5b9b38f578bb..fdb25b492514 100644 --- a/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt +++ b/Documentation/devicetree/bindings/sound/axentia,tse850-pcm5142.txt @@ -2,8 +2,7 @@ Devicetree bindings for the Axentia TSE-850 audio complex Required properties: - compatible: "axentia,tse850-pcm5142" - - axentia,ssc-controller: The phandle of the atmel SSC controller used as - cpu dai. + - axentia,cpu-dai: The phandle of the cpu dai. - axentia,audio-codec: The phandle of the PCM5142 codec. - axentia,add-gpios: gpio specifier that controls the mixer. - axentia,loop1-gpios: gpio specifier that controls loop relays on channel 1. @@ -43,6 +42,12 @@ the PCM5142 codec. Example: + &ssc0 { + #sound-dai-cells = <0>; + + status = "okay"; + }; + &i2c { codec: pcm5142@4c { compatible = "ti,pcm5142"; @@ -77,7 +82,7 @@ Example: sound { compatible = "axentia,tse850-pcm5142"; - axentia,ssc-controller = <&ssc0>; + axentia,cpu-dai = <&ssc0>; axentia,audio-codec = <&codec>; axentia,add-gpios = <&pioA 8 GPIO_ACTIVE_LOW>; diff --git a/Documentation/devicetree/bindings/sound/es8328.txt b/Documentation/devicetree/bindings/sound/es8328.txt index 30ea8a318ae9..33fbf058c997 100644 --- a/Documentation/devicetree/bindings/sound/es8328.txt +++ b/Documentation/devicetree/bindings/sound/es8328.txt @@ -4,7 +4,7 @@ This device supports both I2C and SPI. Required properties: - - compatible : "everest,es8328" + - compatible : Should be "everest,es8328" or "everest,es8388" - DVDD-supply : Regulator providing digital core supply voltage 1.8 - 3.6V - AVDD-supply : Regulator providing analog supply voltage 3.3V - PVDD-supply : Regulator providing digital IO supply voltage 1.8 - 3.6V diff --git a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt index 3e623a724e55..9800a560e0c2 100644 --- a/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt +++ b/Documentation/devicetree/bindings/sound/mt2701-afe-pcm.txt @@ -4,6 +4,7 @@ Required properties: - compatible = "mediatek,mt2701-audio"; - reg: register location and size - interrupts: Should contain AFE interrupt +- power-domains: should define the power domain - clock-names: should have these clock names: "infra_sys_audio_clk", "top_audio_mux1_sel", @@ -58,6 +59,7 @@ Example: <0 0x112A0000 0 0x20000>; interrupts = <GIC_SPI 104 IRQ_TYPE_LEVEL_LOW>, <GIC_SPI 132 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT2701_POWER_DOMAIN_IFR_MSC>; clocks = <&infracfg CLK_INFRA_AUDIO>, <&topckgen CLK_TOP_AUD_MUX1_SEL>, <&topckgen CLK_TOP_AUD_MUX2_SEL>, diff --git a/Documentation/devicetree/bindings/sound/nau8540.txt b/Documentation/devicetree/bindings/sound/nau8540.txt new file mode 100644 index 000000000000..307a76528320 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/nau8540.txt @@ -0,0 +1,16 @@ +NAU85L40 audio CODEC + +This device supports I2C only. + +Required properties: + + - compatible : "nuvoton,nau8540" + + - reg : the I2C address of the device. + +Example: + +codec: nau8540@1c { + compatible = "nuvoton,nau8540"; + reg = <0x1c>; +}; diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt new file mode 100644 index 000000000000..2539e1d68107 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3288-hdmi-analog.txt @@ -0,0 +1,36 @@ +ROCKCHIP RK3288 with HDMI and analog audio + +Required properties: +- compatible: "rockchip,rk3288-hdmi-analog" +- rockchip,model: The user-visible name of this sound complex +- rockchip,i2s-controller: The phandle of the Rockchip I2S controller that's + connected to the CODEC +- rockchip,audio-codec: The phandle of the analog audio codec. +- rockchip,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. For this driver the first string should always be + "Analog". + +Optionnal properties: +- rockchip,hp-en-gpios = The phandle of the GPIO that power up/down the + headphone (when the analog output is an headphone). +- rockchip,hp-det-gpios = The phandle of the GPIO that detects the headphone + (when the analog output is an headphone). +- pinctrl-names, pinctrl-0: Please refer to pinctrl-bindings.txt + +Example: + +sound { + compatible = "rockchip,rockchip-audio-es8388"; + rockchip,model = "Analog audio output"; + rockchip,i2s-controller = <&i2s>; + rockchip,audio-codec = <&es8388>; + rockchip,routing = "Analog", "LOUT2", + "Analog", "ROUT2"; + rockchip,hp-en-gpios = <&gpio8 0 GPIO_ACTIVE_HIGH>; + rockchip,hp-det-gpios = <&gpio7 7 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&headphone>; +}; + diff --git a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt index 4ea29aa9af59..a6600f6dea64 100644 --- a/Documentation/devicetree/bindings/sound/rockchip-i2s.txt +++ b/Documentation/devicetree/bindings/sound/rockchip-i2s.txt @@ -5,7 +5,7 @@ audio data transfer between devices in the system. Required properties: -- compatible: should be one of the followings +- compatible: should be one of the following: - "rockchip,rk3066-i2s": for rk3066 - "rockchip,rk3188-i2s", "rockchip,rk3066-i2s": for rk3188 - "rockchip,rk3288-i2s", "rockchip,rk3066-i2s": for rk3288 @@ -17,7 +17,7 @@ Required properties: Documentation/devicetree/bindings/dma/dma.txt - dma-names: should include "tx" and "rx". - clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. -- clock-names: should contain followings: +- clock-names: should contain the following: - "i2s_hclk": clock for I2S BUS - "i2s_clk" : clock for I2S controller - rockchip,playback-channels: max playback channels, if not set, 8 channels default. diff --git a/Documentation/devicetree/bindings/sound/rt5665.txt b/Documentation/devicetree/bindings/sound/rt5665.txt index 419c89219681..419c89219681 100755..100644 --- a/Documentation/devicetree/bindings/sound/rt5665.txt +++ b/Documentation/devicetree/bindings/sound/rt5665.txt diff --git a/Documentation/devicetree/bindings/sound/sun4i-codec.txt b/Documentation/devicetree/bindings/sound/sun4i-codec.txt index 3033bd8aab0f..3863531d1e6d 100644 --- a/Documentation/devicetree/bindings/sound/sun4i-codec.txt +++ b/Documentation/devicetree/bindings/sound/sun4i-codec.txt @@ -14,7 +14,7 @@ Required properties: - dma-names: should include "tx" and "rx". - clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. -- clock-names: should contain followings: +- clock-names: should contain the following: - "apb": the parent APB clock for this controller - "codec": the parent module clock diff --git a/Documentation/devicetree/bindings/sound/sun4i-i2s.txt b/Documentation/devicetree/bindings/sound/sun4i-i2s.txt index 7b526ec64991..ee21da865771 100644 --- a/Documentation/devicetree/bindings/sound/sun4i-i2s.txt +++ b/Documentation/devicetree/bindings/sound/sun4i-i2s.txt @@ -5,8 +5,9 @@ audio data transfer between devices in the system. Required properties: -- compatible: should be one of the followings +- compatible: should be one of the following: - "allwinner,sun4i-a10-i2s" + - "allwinner,sun6i-a31-i2s" - reg: physical base address of the controller and length of memory mapped region. - interrupts: should contain the I2S interrupt. @@ -14,11 +15,15 @@ Required properties: Documentation/devicetree/bindings/dma/dma.txt - dma-names: should include "tx" and "rx". - clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. -- clock-names: should contain followings: +- clock-names: should contain the following: - "apb" : clock for the I2S bus interface - "mod" : module clock for the I2S controller - #sound-dai-cells : Must be equal to 0 +Required properties for the following compatibles: + - "allwinner,sun6i-a31-i2s" +- resets: phandle to the reset line for this codec + Example: i2s0: i2s@01c22400 { diff --git a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt new file mode 100644 index 000000000000..399b1b4bae22 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt @@ -0,0 +1,63 @@ +Allwinner SUN8I audio codec +------------------------------------ + +On Sun8i-A33 SoCs, the audio is separated in different parts: + - A DAI driver. It uses the "sun4i-i2s" driver which is + documented here: + Documentation/devicetree/bindings/sound/sun4i-i2s.txt + - An analog part of the codec which is handled as PRCM registers. + See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt + - An digital part of the codec which is documented in this current + binding documentation. + - And finally, an audio card which links all the above components. + The simple-audio card will be used. + See Documentation/devicetree/bindings/sound/simple-card.txt + +This bindings documentation exposes Sun8i codec (digital part). + +Required properties: +- compatible: must be "allwinner,sun8i-a33-codec" +- reg: must contain the registers location and length +- interrupts: must contain the codec interrupt +- clocks: a list of phandle + clock-specifer pairs, one for each entry + in clock-names. +- clock-names: should contain followings: + - "bus": the parent APB clock for this controller + - "mod": the parent module clock + +Here is an example to add a sound card and the codec binding on sun8i SoCs that +are similar to A33 using simple-card: + + sound { + compatible = "simple-audio-card"; + simple-audio-card,name = "sun8i-a33-audio"; + simple-audio-card,format = "i2s"; + simple-audio-card,frame-master = <&link_codec>; + simple-audio-card,bitclock-master = <&link_codec>; + simple-audio-card,mclk-fs = <512>; + simple-audio-card,aux-devs = <&codec_analog>; + simple-audio-card,routing = + "Left DAC", "Digital Left DAC", + "Right DAC", "Digital Right DAC"; + + simple-audio-card,cpu { + sound-dai = <&dai>; + }; + + link_codec: simple-audio-card,codec { + sound-dai = <&codec>; + }; + + soc@01c00000 { + [...] + + audio-codec@1c22e00 { + #sound-dai-cells = <0>; + compatible = "allwinner,sun8i-a33-codec"; + reg = <0x01c22e00 0x400>; + interrupts = <GIC_SPI 29 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_CODEC>, <&ccu CLK_AC_DIG>; + clock-names = "bus", "mod"; + }; + }; + diff --git a/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt index 0230c4d20506..fe0a65e6d629 100644 --- a/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt +++ b/Documentation/devicetree/bindings/sound/sunxi,sun4i-spdif.txt @@ -10,6 +10,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 + - "allwinner,sun8i-h3-spdif": for the Allwinner H3 SoC - reg : Offset and length of the register set for the device. diff --git a/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt b/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt index 7e5aa6f6b5a1..292ad5083704 100644 --- a/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt +++ b/Documentation/devicetree/bindings/sound/zte,zx-i2s.txt @@ -1,10 +1,12 @@ ZTE ZX296702 I2S controller Required properties: - - compatible : Must be "zte,zx296702-i2s" + - compatible : Must be one of: + "zte,zx296718-i2s", "zte,zx296702-i2s" + "zte,zx296702-i2s" - reg : Must contain I2S core's registers location and length - clocks : Pairs of phandle and specifier referencing the controller's clocks. - - clock-names: "tx" for the clock to the I2S interface. + - clock-names: "wclk" for the wclk, "pclk" for the pclk to the I2S interface. - dmas: Pairs of phandle and specifier for the DMA channel that is used by the core. The core expects two dma channels for transmit. - dma-names : Must be "tx" and "rx" @@ -16,12 +18,12 @@ please check: * dma/dma.txt Example: - i2s0: i2s0@0b005000 { + i2s0: i2s@b005000 { #sound-dai-cells = <0>; - compatible = "zte,zx296702-i2s"; + compatible = "zte,zx296718-i2s", "zte,zx296702-i2s"; reg = <0x0b005000 0x1000>; - clocks = <&lsp0clk ZX296702_I2S0_DIV>; - clock-names = "tx"; + clocks = <&audiocrm AUDIO_I2S0_WCLK>, <&audiocrm AUDIO_I2S0_PCLK>; + clock-names = "wclk", "pclk"; interrupts = <GIC_SPI 22 IRQ_TYPE_LEVEL_HIGH>; dmas = <&dma 5>, <&dma 6>; dma-names = "tx", "rx"; diff --git a/Documentation/devicetree/bindings/sram/sram.txt b/Documentation/devicetree/bindings/sram/sram.txt index 068c2c03c38f..267da4410aef 100644 --- a/Documentation/devicetree/bindings/sram/sram.txt +++ b/Documentation/devicetree/bindings/sram/sram.txt @@ -42,6 +42,12 @@ Optional properties in the area nodes: and in use by another device or devices - export : indicates that the reserved SRAM area may be accessed outside of the kernel, e.g. by bootloader or userspace +- protect-exec : Same as 'pool' above but with the additional + constraint that code wil be run from the region and + that the memory is maintained as read-only, executable + during code execution. NOTE: This region must be page + aligned on start and end in order to properly allow + manipulation of the page attributes. - label : the name for the reserved partition, if omitted, the label is taken from the node name excluding the unit address. diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt index 66223d561972..20ca4ef9d776 100644 --- a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt @@ -17,6 +17,12 @@ Required properties: calibration data, as specified by the SoC reference manual. The first cell of each pair is the value to be written to TTCFGR, and the second is the value to be written to TSCFGR. +- #thermal-sensor-cells : Must be 1. The sensor specifier is the monitoring + site ID, and represents the "n" in TRITSRn and TRATSRn. + +Optional property: +- little-endian : If present, the TMU registers are little endian. If absent, + the default is big endian. Example: @@ -60,4 +66,5 @@ tmu@f0000 { 0x00030000 0x00000012 0x00030001 0x0000001d>; + #thermal-sensor-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt new file mode 100644 index 000000000000..07a9713ae6a7 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt @@ -0,0 +1,56 @@ +* DT bindings for Renesas R-Car Gen3 Thermal Sensor driver + +On R-Car Gen3 SoCs, the thermal sensor controllers (TSC) control the thermal +sensors (THS) which are the analog circuits for measuring temperature (Tj) +inside the LSI. + +Required properties: +- compatible : "renesas,<soctype>-thermal", + Examples with soctypes are: + - "renesas,r8a7795-thermal" (R-Car H3) + - "renesas,r8a7796-thermal" (R-Car M3-W) +- reg : Address ranges of the thermal registers. Each sensor + needs one address range. Sorting must be done in + increasing order according to datasheet, i.e. + TSC1, TSC2, ... +- clocks : Must contain a reference to the functional clock. +- #thermal-sensor-cells : must be <1>. + +Optional properties: + +- interrupts : interrupts routed to the TSC (3 for H3 and M3-W) +- power-domain : Must contain a reference to the power domain. This + property is mandatory if the thermal sensor instance + is part of a controllable power domain. + +Example: + + tsc: thermal@e6198000 { + compatible = "renesas,r8a7795-thermal"; + reg = <0 0xe6198000 0 0x68>, + <0 0xe61a0000 0 0x5c>, + <0 0xe61a8000 0 0x5c>; + interrupts = <GIC_SPI 67 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 68 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 69 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cpg CPG_MOD 522>; + power-domains = <&sysc R8A7795_PD_ALWAYS_ON>; + #thermal-sensor-cells = <1>; + status = "okay"; + }; + + thermal-zones { + sensor_thermal1: sensor-thermal1 { + polling-delay-passive = <250>; + polling-delay = <1000>; + thermal-sensors = <&tsc 0>; + + trips { + sensor1_crit: sensor1-crit { + temperature = <90000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/zx2967-thermal.txt b/Documentation/devicetree/bindings/thermal/zx2967-thermal.txt new file mode 100644 index 000000000000..3dc1c6bf0478 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/zx2967-thermal.txt @@ -0,0 +1,116 @@ +* ZTE zx2967 family Thermal + +Required Properties: +- compatible: should be one of the following. + * zte,zx296718-thermal +- reg: physical base address of the controller and length of memory mapped + region. +- clocks : Pairs of phandle and specifier referencing the controller's clocks. +- clock-names: "topcrm" for the topcrm clock. + "apb" for the apb clock. +- #thermal-sensor-cells: must be 0. + +Please note: slope coefficient defined in thermal-zones section need to be +multiplied by 1000. + +Example for tempsensor: + + tempsensor: tempsensor@148a000 { + compatible = "zte,zx296718-thermal"; + reg = <0x0148a000 0x20>; + clocks = <&topcrm TEMPSENSOR_GATE>, <&audiocrm AUDIO_TS_PCLK>; + clock-names = "topcrm", "apb"; + #thermal-sensor-cells = <0>; + }; + +Example for cooling device: + + cooling_dev: cooling_dev { + cluster0_cooling_dev: cluster0-cooling-dev { + #cooling-cells = <2>; + cpumask = <0xf>; + capacitance = <1500>; + }; + + cluster1_cooling_dev: cluster1-cooling-dev { + #cooling-cells = <2>; + cpumask = <0x30>; + capacitance = <2000>; + }; + }; + +Example for thermal zones: + + thermal-zones { + zx296718_thermal: zx296718_thermal { + polling-delay-passive = <500>; + polling-delay = <1000>; + sustainable-power = <6500>; + + thermal-sensors = <&tempsensor 0>; + /* + * slope need to be multiplied by 1000. + */ + coefficients = <1951 (-922)>; + + trips { + trip0: switch_on_temperature { + temperature = <90000>; + hysteresis = <2000>; + type = "passive"; + }; + + trip1: desired_temperature { + temperature = <100000>; + hysteresis = <2000>; + type = "passive"; + }; + + crit: critical_temperature { + temperature = <110000>; + hysteresis = <2000>; + type = "critical"; + }; + }; + + cooling-maps { + map0 { + trip = <&trip0>; + cooling-device = <&gpu 2 5>; + }; + + map1 { + trip = <&trip0>; + cooling-device = <&cluster0_cooling_dev 1 2>; + }; + + map2 { + trip = <&trip1>; + cooling-device = <&cluster0_cooling_dev 1 2>; + }; + + map3 { + trip = <&crit>; + cooling-device = <&cluster0_cooling_dev 1 2>; + }; + + map4 { + trip = <&trip0>; + cooling-device = <&cluster1_cooling_dev 1 2>; + contribution = <9000>; + }; + + map5 { + trip = <&trip1>; + cooling-device = <&cluster1_cooling_dev 1 2>; + contribution = <4096>; + }; + + map6 { + trip = <&crit>; + cooling-device = <&cluster1_cooling_dev 1 2>; + contribution = <4096>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt index b6b5130e5f65..1f69ee1a61ea 100644 --- a/Documentation/devicetree/bindings/ufs/ufs-qcom.txt +++ b/Documentation/devicetree/bindings/ufs/ufs-qcom.txt @@ -29,7 +29,6 @@ Optional properties: - vdda-pll-max-microamp : specifies max. load that can be drawn from pll supply - vddp-ref-clk-supply : phandle to UFS device ref_clk pad power supply - vddp-ref-clk-max-microamp : specifies max. load that can be drawn from this supply -- vddp-ref-clk-always-on : specifies if this supply needs to be kept always on Example: diff --git a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.txt b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.txt index 862cd7c79805..d9b42da016f3 100644 --- a/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.txt +++ b/Documentation/devicetree/bindings/usb/allwinner,sun4i-a10-musb.txt @@ -2,8 +2,8 @@ Allwinner sun4i A10 musb DRC/OTG controller ------------------------------------------- Required properties: - - compatible : "allwinner,sun4i-a10-musb", "allwinner,sun6i-a31-musb" - or "allwinner,sun8i-a33-musb" + - compatible : "allwinner,sun4i-a10-musb", "allwinner,sun6i-a31-musb", + "allwinner,sun8i-a33-musb" or "allwinner,sun8i-h3-musb" - reg : mmio address range of the musb controller - clocks : clock specifier for the musb controller ahb gate clock - reset : reset specifier for the ahb reset (A31 and newer only) diff --git a/Documentation/devicetree/bindings/usb/dwc3-st.txt b/Documentation/devicetree/bindings/usb/dwc3-st.txt index 01c71b1258f4..50dee3b44665 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-st.txt +++ b/Documentation/devicetree/bindings/usb/dwc3-st.txt @@ -20,10 +20,10 @@ See: Documentation/devicetree/bindings/reset/reset.txt with 'reg' property - pinctl-names : A pinctrl state named "default" must be defined -See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt +See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - pinctrl-0 : Pin control group -See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt +See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - ranges : allows valid 1:1 translation between child's address space and parent's address space diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index e3e6983288e3..f658f394c2d3 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -56,6 +56,10 @@ Optional properties: - <DEPRECATED> tx-fifo-resize: determines if the FIFO *has* to be reallocated. + - in addition all properties from usb-xhci.txt from the current directory are + supported as well + + This is usually a subnode to DWC3 glue to which it is connected. dwc3@4a030000 { diff --git a/Documentation/devicetree/bindings/usb/ehci-omap.txt b/Documentation/devicetree/bindings/usb/ehci-omap.txt index 3dc231c832b0..d77e11a975a2 100644 --- a/Documentation/devicetree/bindings/usb/ehci-omap.txt +++ b/Documentation/devicetree/bindings/usb/ehci-omap.txt @@ -29,4 +29,3 @@ usbhsehci: ehci@4a064c00 { &usbhsehci { phys = <&hsusb1_phy 0 &hsusb3_phy>; }; - diff --git a/Documentation/devicetree/bindings/usb/ehci-st.txt b/Documentation/devicetree/bindings/usb/ehci-st.txt index fb45fa5770bb..410d922cfdd7 100644 --- a/Documentation/devicetree/bindings/usb/ehci-st.txt +++ b/Documentation/devicetree/bindings/usb/ehci-st.txt @@ -7,7 +7,7 @@ Required properties: - interrupts : one EHCI interrupt should be described here - pinctrl-names : a pinctrl state named "default" must be defined - pinctrl-0 : phandle referencing pin configuration of the USB controller -See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt +See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - clocks : phandle list of usb clocks - clock-names : should be "ic" for interconnect clock and "clk48" See: Documentation/devicetree/bindings/clock/clock-bindings.txt diff --git a/Documentation/devicetree/bindings/usb/mt8173-mtu3.txt b/Documentation/devicetree/bindings/usb/mt8173-mtu3.txt index e049d199bf0d..1d7c3bc677f7 100644 --- a/Documentation/devicetree/bindings/usb/mt8173-mtu3.txt +++ b/Documentation/devicetree/bindings/usb/mt8173-mtu3.txt @@ -10,7 +10,7 @@ Required properties: - vusb33-supply : regulator of USB avdd3.3v - clocks : a list of phandle + clock-specifier pairs, one for each entry in clock-names - - clock-names : must contain "sys_ck" for clock of controller; + - clock-names : must contain "sys_ck" and "ref_ck" for clock of controller; "wakeup_deb_p0" and "wakeup_deb_p1" are optional, they are depends on "mediatek,enable-wakeup" - phys : a list of phandle + phy specifier pairs @@ -30,7 +30,7 @@ Optional properties: "id_float" and "id_ground" are optinal which depends on "mediatek,enable-manual-drd" - pinctrl-0 : pin control group - See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt - maximum-speed : valid arguments are "super-speed", "high-speed" and "full-speed"; refer to usb/generic.txt @@ -56,10 +56,10 @@ ssusb: usb@11271000 { phys = <&phy_port0 PHY_TYPE_USB3>, <&phy_port1 PHY_TYPE_USB2>; power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>, <&pericfg CLK_PERI_USB0>, <&pericfg CLK_PERI_USB1>; - clock-names = "sys_ck", + clock-names = "sys_ck", "ref_ck", "wakeup_deb_p0", "wakeup_deb_p1"; vusb33-supply = <&mt6397_vusb_reg>; @@ -79,8 +79,8 @@ ssusb: usb@11271000 { reg-names = "mac"; interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>; - clock-names = "sys_ck"; + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; + clock-names = "sys_ck", "ref_ck"; vusb33-supply = <&mt6397_vusb_reg>; status = "disabled"; }; diff --git a/Documentation/devicetree/bindings/usb/mt8173-xhci.txt b/Documentation/devicetree/bindings/usb/mt8173-xhci.txt index 2a930bd52b94..0acfc8acbea1 100644 --- a/Documentation/devicetree/bindings/usb/mt8173-xhci.txt +++ b/Documentation/devicetree/bindings/usb/mt8173-xhci.txt @@ -23,6 +23,7 @@ Required properties: entry in clock-names - clock-names : must contain "sys_ck": for clock of xHCI MAC + "ref_ck": for reference clock of xHCI MAC "wakeup_deb_p0": for USB wakeup debounce clock of port0 "wakeup_deb_p1": for USB wakeup debounce clock of port1 @@ -37,7 +38,7 @@ Optional properties: - usb3-lpm-capable : supports USB3.0 LPM - pinctrl-names : a pinctrl state named "default" must be defined - pinctrl-0 : pin control group - See: Documentation/devicetree/bindings/pinctrl/pinctrl-binding.txt + See: Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt Example: usb30: usb@11270000 { @@ -47,10 +48,10 @@ usb30: usb@11270000 { reg-names = "mac", "ippc"; interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>, + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>, <&pericfg CLK_PERI_USB0>, <&pericfg CLK_PERI_USB1>; - clock-names = "sys_ck", + clock-names = "sys_ck", "ref_ck", "wakeup_deb_p0", "wakeup_deb_p1"; phys = <&phy_port0 PHY_TYPE_USB3>, @@ -67,7 +68,7 @@ usb30: usb@11270000 { In the case, xhci is added as subnode to mtu3. An example and the DT binding details of mtu3 can be found in: -Documentation/devicetree/bindings/usb/mtu3.txt +Documentation/devicetree/bindings/usb/mt8173-mtu3.txt Required properties: - compatible : should contain "mediatek,mt8173-xhci" @@ -82,6 +83,7 @@ Required properties: entry in clock-names - clock-names : must be "sys_ck": for clock of xHCI MAC + "ref_ck": for reference clock of xHCI MAC Optional properties: - vbus-supply : reference to the VBUS regulator; @@ -94,8 +96,8 @@ usb30: usb@11270000 { reg-names = "mac"; interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>; power-domains = <&scpsys MT8173_POWER_DOMAIN_USB>; - clocks = <&topckgen CLK_TOP_USB30_SEL>; - clock-names = "sys_ck"; + clocks = <&topckgen CLK_TOP_USB30_SEL>, <&clk26m>; + clock-names = "sys_ck", "ref_ck"; vusb33-supply = <&mt6397_vusb_reg>; usb3-lpm-capable; }; diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt index 39acb084bce9..73cc0963e823 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt @@ -18,7 +18,7 @@ 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/qcom,dwc3-usb-phy.txt +Documentation/devicetree/bindings/phy/qcom-dwc3-usb-phy.txt Example device nodes: diff --git a/Documentation/devicetree/bindings/usb/ulpi.txt b/Documentation/devicetree/bindings/usb/ulpi.txt new file mode 100644 index 000000000000..ca179dc4bd50 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ulpi.txt @@ -0,0 +1,20 @@ +ULPI bus binding +---------------- + +Phys that are behind a ULPI connection can be described with the following +binding. The host controller shall have a "ulpi" named node as a child, and +that node shall have one enabled node underneath it representing the ulpi +device on the bus. + +EXAMPLE +------- + +usb { + compatible = "vendor,usb-controller"; + + ulpi { + phy { + compatible = "vendor,phy"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index 0b7d8576001c..2d80b60eeabe 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -27,6 +27,7 @@ Required properties: Optional properties: - clocks: reference to a clock - usb3-lpm-capable: determines if platform is USB3 LPM capable + - quirk-broken-port-ped: set if the controller has broken port disable mechanism Example: usb@f0931000 { diff --git a/Documentation/devicetree/bindings/usb/usb251xb.txt b/Documentation/devicetree/bindings/usb/usb251xb.txt new file mode 100644 index 000000000000..3957d4edaa74 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb251xb.txt @@ -0,0 +1,66 @@ +Microchip USB 2.0 Hi-Speed Hub Controller + +The device node for the configuration of a Microchip USB251xB/xBi USB 2.0 +Hi-Speed Controller. + +Required properties : + - compatible : Should be "microchip,usb251xb" or one of the specific types: + "microchip,usb2512b", "microchip,usb2512bi", "microchip,usb2513b", + "microchip,usb2513bi", "microchip,usb2514b", "microchip,usb2514bi" + - reset-gpios : Should specify the gpio for hub reset + - reg : I2C address on the selected bus (default is <0x2C>) + +Optional properties : + - skip-config : Skip Hub configuration, but only send the USB-Attach command + - vendor-id : Set USB Vendor ID of the hub (16 bit, default is 0x0424) + - product-id : Set USB Product ID of the hub (16 bit, default depends on type) + - device-id : Set USB Device ID of the hub (16 bit, default is 0x0bb3) + - language-id : Set USB Language ID (16 bit, default is 0x0000) + - manufacturer : Set USB Manufacturer string (max 31 characters long) + - product : Set USB Product string (max 31 characters long) + - serial : Set USB Serial string (max 31 characters long) + - {bus,self}-powered : selects between self- and bus-powered operation (default + is self-powered) + - disable-hi-speed : disable USB Hi-Speed support + - {multi,single}-tt : selects between multi- and single-transaction-translator + (default is multi-tt) + - disable-eop : disable End of Packet generation in full-speed mode + - {ganged,individual}-sensing : select over-current sense type in self-powered + mode (default is individual) + - {ganged,individual}-port-switching : select port power switching mode + (default is individual) + - dynamic-power-switching : enable auto-switching from self- to bus-powered + operation if the local power source is removed or unavailable + - oc-delay-us : Delay time (in microseconds) for filtering the over-current + sense inputs. Valid values are 100, 4000, 8000 (default) and 16000. If + an invalid value is given, the default is used instead. + - compound-device : indicate the hub is part of a compound device + - port-mapping-mode : enable port mapping mode + - string-support : enable string descriptor support (required for manufacturer, + product and serial string configuration) + - non-removable-ports : Should specify the ports which have a non-removable + device connected. + - sp-disabled-ports : Specifies the ports which will be self-power disabled + - bp-disabled-ports : Specifies the ports which will be bus-power disabled + - power-on-time-ms : Specifies the time it takes from the time the host + initiates the power-on sequence to a port until the port has adequate + power. The value is given in ms in a 0 - 510 range (default is 100ms). + +Examples: + usb2512b@2c { + compatible = "microchip,usb2512b"; + reg = <0x2c>; + reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; + }; + + usb2514b@2c { + compatible = "microchip,usb2514b"; + reg = <0x2c>; + reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>; + vendor-id = /bits/ 16 <0x0000>; + product-id = /bits/ 16 <0x0000>; + string-support; + manufacturer = "Foo"; + product = "Foo-Bar"; + serial = "1234567890A"; + }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 16d3b5e7f5d1..ec0bfb9bbebd 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -40,6 +40,7 @@ atmel Atmel Corporation auo AU Optronics Corporation auvidea Auvidea GmbH avago Avago Technologies +avia avia semiconductor avic Shanghai AVIC Optoelectronics Co., Ltd. axentia Axentia Technologies AB axis Axis Communications AB @@ -75,6 +76,7 @@ dallas Maxim Integrated Products (formerly Dallas Semiconductor) davicom DAVICOM Semiconductor, Inc. delta Delta Electronics, Inc. denx Denx Software Engineering +devantech Devantech, Ltd. digi Digi International Inc. digilent Diglent, Inc. dlg Dialog Semiconductor @@ -102,11 +104,13 @@ everest Everest Semiconductor Co. Ltd. everspin Everspin Technologies, Inc. excito Excito ezchip EZchip Semiconductor +faraday Faraday Technology Corporation fcs Fairchild Semiconductor firefly Firefly focaltech FocalTech Systems Co.,Ltd friendlyarm Guangzhou FriendlyARM Computer Tech Co., Ltd fsl Freescale Semiconductor +fujitsu Fujitsu Ltd. ge General Electric Company geekbuying GeekBuying gef GE Fanuc Intelligent Platforms Embedded Systems, Inc. @@ -118,6 +122,7 @@ gmt Global Mixed-mode Technology, Inc. goodix Shenzhen Huiding Technology Co., Ltd. google Google, Inc. grinn Grinn +grmn Garmin Limited gumstix Gumstix, Inc. gw Gateworks Corporation hannstar HannStar Display Corporation @@ -159,11 +164,14 @@ kosagi Sutajio Ko-Usagi PTE Ltd. kyo Kyocera Corporation lacie LaCie lantiq Lantiq Semiconductor +lego LEGO Systems A/S lenovo Lenovo Group Ltd. lg LG Corporation +licheepi Lichee Pi linux Linux-specific binding lltc Linear Technology Corporation lsi LSI Corp. (LSI Logic) +lwn Liebherr-Werk Nenzing GmbH macnica Macnica Americas marvell Marvell Technology Group Ltd. maxim Maxim Integrated Products @@ -187,6 +195,7 @@ mpl MPL AG mqmaker mqmaker Inc. msi Micro-Star International Co. Ltd. mti Imagination Technologies Ltd. (formerly MIPS Technologies Inc.) +multi-inno Multi-Inno Technology Co.,Ltd mundoreader Mundo Reader S.L. murata Murata Manufacturing Co., Ltd. mxicy Macronix International Co., Ltd. @@ -196,6 +205,7 @@ nec NEC LCD Technologies, Ltd. neonode Neonode Inc. netgear NETGEAR netlogic Broadcom Corporation (formerly NetLogic Microsystems) +netron-dy Netron DY netxeon Shenzhen Netxeon Technology CO., LTD nexbox Nexbox newhaven Newhaven Display International @@ -227,6 +237,7 @@ pine64 Pine64 pixcir PIXCIR MICROELECTRONICS Co., Ltd plathome Plat'Home Co., Ltd. plda PLDA +poslab Poslab Technology Co., Ltd. powervr PowerVR (deprecated, use img) pulsedlight PulsedLight, Inc qca Qualcomm Atheros, Inc. @@ -296,6 +307,7 @@ technologic Technologic Systems terasic Terasic Inc. thine THine Electronics, Inc. ti Texas Instruments +tianma Tianma Micro-electronics Co., Ltd. tlm Trusted Logic Mobility topeet Topeet toradex Toradex AG @@ -320,6 +332,7 @@ virtio Virtual I/O Device Specification, developed by the OASIS consortium vivante Vivante Corporation voipac Voipac Technologies s.r.o. wd Western Digital Corp. +wetek WeTek Electronics, limited. wexler Wexler winbond Winbond Electronics corp. wlf Wolfson Microelectronics @@ -328,7 +341,9 @@ x-powers X-Powers xes Extreme Engineering Solutions (X-ES) xillybus Xillybus Ltd. xlnx Xilinx +xunlong Shenzhen Xunlong Software CO.,Limited zarlink Zarlink Semiconductor +zeitec ZEITEC Semiconductor Co., LTD. zii Zodiac Inflight Innovations zte ZTE Corp. zyxel ZyXEL Communications Corp. diff --git a/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt b/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt new file mode 100644 index 000000000000..bc4b865d178b --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/cortina,gemin-watchdog.txt @@ -0,0 +1,17 @@ +Cortina Systems Gemini SoC Watchdog + +Required properties: +- compatible : must be "cortina,gemini-watchdog" +- reg : shall contain base register location and length +- interrupts : shall contain the interrupt for the watchdog + +Optional properties: +- timeout-sec : the default watchdog timeout in seconds. + +Example: + +watchdog@41000000 { + compatible = "cortina,gemini-watchdog"; + reg = <0x41000000 0x1000>; + interrupts = <3 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt index 8f3d96af81d7..1f6e101e299a 100644 --- a/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/samsung-wdt.txt @@ -6,10 +6,11 @@ occurred. Required properties: - compatible : should be one among the following - (a) "samsung,s3c2410-wdt" for Exynos4 and previous SoCs - (b) "samsung,exynos5250-wdt" for Exynos5250 - (c) "samsung,exynos5420-wdt" for Exynos5420 - (c) "samsung,exynos7-wdt" for Exynos7 + - "samsung,s3c2410-wdt" for S3C2410 + - "samsung,s3c6410-wdt" for S3C6410, S5PV210 and Exynos4 + - "samsung,exynos5250-wdt" for Exynos5250 + - "samsung,exynos5420-wdt" for Exynos5420 + - "samsung,exynos7-wdt" for Exynos7 - reg : base physical address of the controller and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt b/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt new file mode 100644 index 000000000000..06ce67766756 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/zte,zx2967-wdt.txt @@ -0,0 +1,32 @@ +ZTE zx2967 Watchdog timer + +Required properties: + +- compatible : should be one of the following. + * zte,zx296718-wdt +- reg : Specifies base physical address and size of the registers. +- clocks : Pairs of phandle and specifier referencing the controller's clocks. +- resets : Reference to the reset controller controlling the watchdog + controller. + +Optional properties: + +- timeout-sec : Contains the watchdog timeout in seconds. +- zte,wdt-reset-sysctrl : Directs how to reset system by the watchdog. + if we don't want to restart system when watchdog been triggered, + it's not required, vice versa. + It should include following fields. + * phandle of aon-sysctrl. + * offset of register that be written, should be 0xb0. + * configure value that be written to aon-sysctrl. + * bit mask, corresponding bits will be affected. + +Example: + +wdt: watchdog@1465000 { + compatible = "zte,zx296718-wdt"; + reg = <0x1465000 0x1000>; + clocks = <&topcrm WDT_WCLK>; + resets = <&toprst 35>; + zte,wdt-reset-sysctrl = <&aon_sysctrl 0xb0 1 0x115>; +}; diff --git a/Documentation/dma-buf-sharing.txt b/Documentation/dma-buf-sharing.txt deleted file mode 100644 index ca44c5820585..000000000000 --- a/Documentation/dma-buf-sharing.txt +++ /dev/null @@ -1,482 +0,0 @@ - DMA Buffer Sharing API Guide - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Sumit Semwal - <sumit dot semwal at linaro dot org> - <sumit dot semwal at ti dot com> - -This document serves as a guide to device-driver writers on what is the dma-buf -buffer sharing API, how to use it for exporting and using shared buffers. - -Any device driver which wishes to be a part of DMA buffer sharing, can do so as -either the 'exporter' of buffers, or the 'user' of buffers. - -Say a driver A wants to use buffers created by driver B, then we call B as the -exporter, and A as buffer-user. - -The exporter -- implements and manages operations[1] for the buffer -- allows other users to share the buffer by using dma_buf sharing APIs, -- manages the details of buffer allocation, -- decides about the actual backing storage where this allocation happens, -- takes care of any migration of scatterlist - for all (shared) users of this - buffer, - -The buffer-user -- is one of (many) sharing users of the buffer. -- doesn't need to worry about how the buffer is allocated, or where. -- needs a mechanism to get access to the scatterlist that makes up this buffer - in memory, mapped into its own address space, so it can access the same area - of memory. - -dma-buf operations for device dma only --------------------------------------- - -The dma_buf buffer sharing API usage contains the following steps: - -1. Exporter announces that it wishes to export a buffer -2. Userspace gets the file descriptor associated with the exported buffer, and - passes it around to potential buffer-users based on use case -3. Each buffer-user 'connects' itself to the buffer -4. When needed, buffer-user requests access to the buffer from exporter -5. When finished with its use, the buffer-user notifies end-of-DMA to exporter -6. when buffer-user is done using this buffer completely, it 'disconnects' - itself from the buffer. - - -1. Exporter's announcement of buffer export - - The buffer exporter announces its wish to export a buffer. In this, it - connects its own private buffer data, provides implementation for operations - that can be performed on the exported dma_buf, and flags for the file - associated with this buffer. All these fields are filled in struct - dma_buf_export_info, defined via the DEFINE_DMA_BUF_EXPORT_INFO macro. - - Interface: - DEFINE_DMA_BUF_EXPORT_INFO(exp_info) - struct dma_buf *dma_buf_export(struct dma_buf_export_info *exp_info) - - If this succeeds, dma_buf_export allocates a dma_buf structure, and - returns a pointer to the same. It also associates an anonymous file with this - buffer, so it can be exported. On failure to allocate the dma_buf object, - it returns NULL. - - 'exp_name' in struct dma_buf_export_info is the name of exporter - to - facilitate information while debugging. It is set to KBUILD_MODNAME by - default, so exporters don't have to provide a specific name, if they don't - wish to. - - DEFINE_DMA_BUF_EXPORT_INFO macro defines the struct dma_buf_export_info, - zeroes it out and pre-populates exp_name in it. - - -2. Userspace gets a handle to pass around to potential buffer-users - - Userspace entity requests for a file-descriptor (fd) which is a handle to the - anonymous file associated with the buffer. It can then share the fd with other - drivers and/or processes. - - Interface: - int dma_buf_fd(struct dma_buf *dmabuf, int flags) - - This API installs an fd for the anonymous file associated with this buffer; - returns either 'fd', or error. - -3. Each buffer-user 'connects' itself to the buffer - - Each buffer-user now gets a reference to the buffer, using the fd passed to - it. - - Interface: - struct dma_buf *dma_buf_get(int fd) - - This API will return a reference to the dma_buf, and increment refcount for - it. - - After this, the buffer-user needs to attach its device with the buffer, which - helps the exporter to know of device buffer constraints. - - Interface: - struct dma_buf_attachment *dma_buf_attach(struct dma_buf *dmabuf, - struct device *dev) - - This API returns reference to an attachment structure, which is then used - for scatterlist operations. It will optionally call the 'attach' dma_buf - operation, if provided by the exporter. - - The dma-buf sharing framework does the bookkeeping bits related to managing - the list of all attachments to a buffer. - -Until this stage, the buffer-exporter has the option to choose not to actually -allocate the backing storage for this buffer, but wait for the first buffer-user -to request use of buffer for allocation. - - -4. When needed, buffer-user requests access to the buffer - - Whenever a buffer-user wants to use the buffer for any DMA, it asks for - access to the buffer using dma_buf_map_attachment API. At least one attach to - the buffer must have happened before map_dma_buf can be called. - - Interface: - struct sg_table * dma_buf_map_attachment(struct dma_buf_attachment *, - enum dma_data_direction); - - This is a wrapper to dma_buf->ops->map_dma_buf operation, which hides the - "dma_buf->ops->" indirection from the users of this interface. - - In struct dma_buf_ops, map_dma_buf is defined as - struct sg_table * (*map_dma_buf)(struct dma_buf_attachment *, - enum dma_data_direction); - - It is one of the buffer operations that must be implemented by the exporter. - It should return the sg_table containing scatterlist for this buffer, mapped - into caller's address space. - - If this is being called for the first time, the exporter can now choose to - scan through the list of attachments for this buffer, collate the requirements - of the attached devices, and choose an appropriate backing storage for the - buffer. - - Based on enum dma_data_direction, it might be possible to have multiple users - accessing at the same time (for reading, maybe), or any other kind of sharing - that the exporter might wish to make available to buffer-users. - - map_dma_buf() operation can return -EINTR if it is interrupted by a signal. - - -5. When finished, the buffer-user notifies end-of-DMA to exporter - - Once the DMA for the current buffer-user is over, it signals 'end-of-DMA' to - the exporter using the dma_buf_unmap_attachment API. - - Interface: - void dma_buf_unmap_attachment(struct dma_buf_attachment *, - struct sg_table *); - - This is a wrapper to dma_buf->ops->unmap_dma_buf() operation, which hides the - "dma_buf->ops->" indirection from the users of this interface. - - In struct dma_buf_ops, unmap_dma_buf is defined as - void (*unmap_dma_buf)(struct dma_buf_attachment *, - struct sg_table *, - enum dma_data_direction); - - unmap_dma_buf signifies the end-of-DMA for the attachment provided. Like - map_dma_buf, this API also must be implemented by the exporter. - - -6. when buffer-user is done using this buffer, it 'disconnects' itself from the - buffer. - - After the buffer-user has no more interest in using this buffer, it should - disconnect itself from the buffer: - - - it first detaches itself from the buffer. - - Interface: - void dma_buf_detach(struct dma_buf *dmabuf, - struct dma_buf_attachment *dmabuf_attach); - - This API removes the attachment from the list in dmabuf, and optionally calls - dma_buf->ops->detach(), if provided by exporter, for any housekeeping bits. - - - Then, the buffer-user returns the buffer reference to exporter. - - Interface: - void dma_buf_put(struct dma_buf *dmabuf); - - This API then reduces the refcount for this buffer. - - If, as a result of this call, the refcount becomes 0, the 'release' file - operation related to this fd is called. It calls the dmabuf->ops->release() - operation in turn, and frees the memory allocated for dmabuf when exported. - -NOTES: -- Importance of attach-detach and {map,unmap}_dma_buf operation pairs - The attach-detach calls allow the exporter to figure out backing-storage - constraints for the currently-interested devices. This allows preferential - allocation, and/or migration of pages across different types of storage - available, if possible. - - Bracketing of DMA access with {map,unmap}_dma_buf operations is essential - to allow just-in-time backing of storage, and migration mid-way through a - use-case. - -- Migration of backing storage if needed - If after - - at least one map_dma_buf has happened, - - and the backing storage has been allocated for this buffer, - another new buffer-user intends to attach itself to this buffer, it might - be allowed, if possible for the exporter. - - In case it is allowed by the exporter: - if the new buffer-user has stricter 'backing-storage constraints', and the - exporter can handle these constraints, the exporter can just stall on the - map_dma_buf until all outstanding access is completed (as signalled by - unmap_dma_buf). - Once all users have finished accessing and have unmapped this buffer, the - exporter could potentially move the buffer to the stricter backing-storage, - and then allow further {map,unmap}_dma_buf operations from any buffer-user - from the migrated backing-storage. - - If the exporter cannot fulfill the backing-storage constraints of the new - buffer-user device as requested, dma_buf_attach() would return an error to - denote non-compatibility of the new buffer-sharing request with the current - buffer. - - If the exporter chooses not to allow an attach() operation once a - map_dma_buf() API has been called, it simply returns an error. - -Kernel cpu access to a dma-buf buffer object --------------------------------------------- - -The motivation to allow cpu access from the kernel to a dma-buf object from the -importers side are: -- fallback operations, e.g. if the devices is connected to a usb bus and the - kernel needs to shuffle the data around first before sending it away. -- full transparency for existing users on the importer side, i.e. userspace - should not notice the difference between a normal object from that subsystem - and an imported one backed by a dma-buf. This is really important for drm - opengl drivers that expect to still use all the existing upload/download - paths. - -Access to a dma_buf from the kernel context involves three steps: - -1. Prepare access, which invalidate any necessary caches and make the object - available for cpu access. -2. Access the object page-by-page with the dma_buf map apis -3. Finish access, which will flush any necessary cpu caches and free reserved - resources. - -1. Prepare access - - Before an importer can access a dma_buf object with the cpu from the kernel - context, it needs to notify the exporter of the access that is about to - happen. - - Interface: - int dma_buf_begin_cpu_access(struct dma_buf *dmabuf, - enum dma_data_direction direction) - - This allows the exporter to ensure that the memory is actually available for - cpu access - the exporter might need to allocate or swap-in and pin the - backing storage. The exporter also needs to ensure that cpu access is - coherent for the access direction. The direction can be used by the exporter - to optimize the cache flushing, i.e. access with a different direction (read - instead of write) might return stale or even bogus data (e.g. when the - exporter needs to copy the data to temporary storage). - - This step might fail, e.g. in oom conditions. - -2. Accessing the buffer - - To support dma_buf objects residing in highmem cpu access is page-based using - an api similar to kmap. Accessing a dma_buf is done in aligned chunks of - PAGE_SIZE size. Before accessing a chunk it needs to be mapped, which returns - a pointer in kernel virtual address space. Afterwards the chunk needs to be - unmapped again. There is no limit on how often a given chunk can be mapped - and unmapped, i.e. the importer does not need to call begin_cpu_access again - before mapping the same chunk again. - - Interfaces: - void *dma_buf_kmap(struct dma_buf *, unsigned long); - void dma_buf_kunmap(struct dma_buf *, unsigned long, void *); - - There are also atomic variants of these interfaces. Like for kmap they - facilitate non-blocking fast-paths. Neither the importer nor the exporter (in - the callback) is allowed to block when using these. - - Interfaces: - void *dma_buf_kmap_atomic(struct dma_buf *, unsigned long); - void dma_buf_kunmap_atomic(struct dma_buf *, unsigned long, void *); - - For importers all the restrictions of using kmap apply, like the limited - supply of kmap_atomic slots. Hence an importer shall only hold onto at most 2 - atomic dma_buf kmaps at the same time (in any given process context). - - dma_buf kmap calls outside of the range specified in begin_cpu_access are - undefined. If the range is not PAGE_SIZE aligned, kmap needs to succeed on - the partial chunks at the beginning and end but may return stale or bogus - data outside of the range (in these partial chunks). - - Note that these calls need to always succeed. The exporter needs to complete - any preparations that might fail in begin_cpu_access. - - For some cases the overhead of kmap can be too high, a vmap interface - is introduced. This interface should be used very carefully, as vmalloc - space is a limited resources on many architectures. - - Interfaces: - void *dma_buf_vmap(struct dma_buf *dmabuf) - void dma_buf_vunmap(struct dma_buf *dmabuf, void *vaddr) - - The vmap call can fail if there is no vmap support in the exporter, or if it - runs out of vmalloc space. Fallback to kmap should be implemented. Note that - the dma-buf layer keeps a reference count for all vmap access and calls down - into the exporter's vmap function only when no vmapping exists, and only - unmaps it once. Protection against concurrent vmap/vunmap calls is provided - by taking the dma_buf->lock mutex. - -3. Finish access - - When the importer is done accessing the CPU, it needs to announce this to - the exporter (to facilitate cache flushing and unpinning of any pinned - resources). The result of any dma_buf kmap calls after end_cpu_access is - undefined. - - Interface: - void dma_buf_end_cpu_access(struct dma_buf *dma_buf, - enum dma_data_direction dir); - - -Direct Userspace Access/mmap Support ------------------------------------- - -Being able to mmap an export dma-buf buffer object has 2 main use-cases: -- CPU fallback processing in a pipeline and -- supporting existing mmap interfaces in importers. - -1. CPU fallback processing in a pipeline - - In many processing pipelines it is sometimes required that the cpu can access - the data in a dma-buf (e.g. for thumbnail creation, snapshots, ...). To avoid - the need to handle this specially in userspace frameworks for buffer sharing - it's ideal if the dma_buf fd itself can be used to access the backing storage - from userspace using mmap. - - Furthermore Android's ION framework already supports this (and is otherwise - rather similar to dma-buf from a userspace consumer side with using fds as - handles, too). So it's beneficial to support this in a similar fashion on - dma-buf to have a good transition path for existing Android userspace. - - No special interfaces, userspace simply calls mmap on the dma-buf fd, making - sure that the cache synchronization ioctl (DMA_BUF_IOCTL_SYNC) is *always* - used when the access happens. Note that DMA_BUF_IOCTL_SYNC can fail with - -EAGAIN or -EINTR, in which case it must be restarted. - - Some systems might need some sort of cache coherency management e.g. when - CPU and GPU domains are being accessed through dma-buf at the same time. To - circumvent this problem there are begin/end coherency markers, that forward - directly to existing dma-buf device drivers vfunc hooks. Userspace can make - use of those markers through the DMA_BUF_IOCTL_SYNC ioctl. The sequence - would be used like following: - - mmap dma-buf fd - - for each drawing/upload cycle in CPU 1. SYNC_START ioctl, 2. read/write - to mmap area 3. SYNC_END ioctl. This can be repeated as often as you - want (with the new data being consumed by the GPU or say scanout device) - - munmap once you don't need the buffer any more - - For correctness and optimal performance, it is always required to use - SYNC_START and SYNC_END before and after, respectively, when accessing the - mapped address. Userspace cannot rely on coherent access, even when there - are systems where it just works without calling these ioctls. - -2. Supporting existing mmap interfaces in importers - - Similar to the motivation for kernel cpu access it is again important that - the userspace code of a given importing subsystem can use the same interfaces - with a imported dma-buf buffer object as with a native buffer object. This is - especially important for drm where the userspace part of contemporary OpenGL, - X, and other drivers is huge, and reworking them to use a different way to - mmap a buffer rather invasive. - - The assumption in the current dma-buf interfaces is that redirecting the - initial mmap is all that's needed. A survey of some of the existing - subsystems shows that no driver seems to do any nefarious thing like syncing - up with outstanding asynchronous processing on the device or allocating - special resources at fault time. So hopefully this is good enough, since - adding interfaces to intercept pagefaults and allow pte shootdowns would - increase the complexity quite a bit. - - Interface: - int dma_buf_mmap(struct dma_buf *, struct vm_area_struct *, - unsigned long); - - If the importing subsystem simply provides a special-purpose mmap call to set - up a mapping in userspace, calling do_mmap with dma_buf->file will equally - achieve that for a dma-buf object. - -3. Implementation notes for exporters - - Because dma-buf buffers have invariant size over their lifetime, the dma-buf - core checks whether a vma is too large and rejects such mappings. The - exporter hence does not need to duplicate this check. - - Because existing importing subsystems might presume coherent mappings for - userspace, the exporter needs to set up a coherent mapping. If that's not - possible, it needs to fake coherency by manually shooting down ptes when - leaving the cpu domain and flushing caches at fault time. Note that all the - dma_buf files share the same anon inode, hence the exporter needs to replace - the dma_buf file stored in vma->vm_file with it's own if pte shootdown is - required. This is because the kernel uses the underlying inode's address_space - for vma tracking (and hence pte tracking at shootdown time with - unmap_mapping_range). - - If the above shootdown dance turns out to be too expensive in certain - scenarios, we can extend dma-buf with a more explicit cache tracking scheme - for userspace mappings. But the current assumption is that using mmap is - always a slower path, so some inefficiencies should be acceptable. - - Exporters that shoot down mappings (for any reasons) shall not do any - synchronization at fault time with outstanding device operations. - Synchronization is an orthogonal issue to sharing the backing storage of a - buffer and hence should not be handled by dma-buf itself. This is explicitly - mentioned here because many people seem to want something like this, but if - different exporters handle this differently, buffer sharing can fail in - interesting ways depending upong the exporter (if userspace starts depending - upon this implicit synchronization). - -Other Interfaces Exposed to Userspace on the dma-buf FD ------------------------------------------------------- - -- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only - with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow - the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other - llseek operation will report -EINVAL. - - If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all - cases. Userspace can use this to detect support for discovering the dma-buf - size using llseek. - -Miscellaneous notes -------------------- - -- Any exporters or users of the dma-buf buffer sharing framework must have - a 'select DMA_SHARED_BUFFER' in their respective Kconfigs. - -- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set - on the file descriptor. This is not just a resource leak, but a - potential security hole. It could give the newly exec'd application - access to buffers, via the leaked fd, to which it should otherwise - not be permitted access. - - The problem with doing this via a separate fcntl() call, versus doing it - atomically when the fd is created, is that this is inherently racy in a - multi-threaded app[3]. The issue is made worse when it is library code - opening/creating the file descriptor, as the application may not even be - aware of the fd's. - - To avoid this problem, userspace must have a way to request O_CLOEXEC - flag be set when the dma-buf fd is created. So any API provided by - the exporting driver to create a dmabuf fd must provide a way to let - userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd(). - -- If an exporter needs to manually flush caches and hence needs to fake - coherency for mmap support, it needs to be able to zap all the ptes pointing - at the backing storage. Now linux mm needs a struct address_space associated - with the struct file stored in vma->vm_file to do that with the function - unmap_mapping_range. But the dma_buf framework only backs every dma_buf fd - with the anon_file struct file, i.e. all dma_bufs share the same file. - - Hence exporters need to setup their own file (and address_space) association - by setting vma->vm_file and adjusting vma->vm_pgoff in the dma_buf mmap - callback. In the specific case of a gem driver the exporter could use the - shmem file already provided by gem (and set vm_pgoff = 0). Exporters can then - zap ptes by unmapping the corresponding range of the struct address_space - associated with their own file. - -References: -[1] struct dma_buf_ops in include/linux/dma-buf.h -[2] All interfaces mentioned above defined in include/linux/dma-buf.h -[3] https://lwn.net/Articles/236486/ diff --git a/Documentation/dontdiff b/Documentation/dontdiff index a23edccd2059..77b92221f951 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -116,9 +116,11 @@ crc32table.h* cscope.* defkeymap.c devlist.h* +devicetable-offsets.h dnotify_test docproc dslm +dtc elf2ecoff elfconfig.h* evergreen_reg_safe.h @@ -153,8 +155,8 @@ keywords.c ksym.c* ksym.h* kxgettext -lex.c -lex.*.c +*lex.c +*lex.*.c linux logo_*.c logo_*_clut224.c @@ -215,6 +217,7 @@ series setup setup.bin setup.elf +sortextable sImage sm_tbl* split-include diff --git a/Documentation/driver-api/80211/cfg80211.rst b/Documentation/driver-api/80211/cfg80211.rst index b1e149ea6fee..eca534ab6172 100644 --- a/Documentation/driver-api/80211/cfg80211.rst +++ b/Documentation/driver-api/80211/cfg80211.rst @@ -45,6 +45,9 @@ Device registration :functions: wiphy_new .. kernel-doc:: include/net/cfg80211.h + :functions: wiphy_read_of_freq_limits + +.. kernel-doc:: include/net/cfg80211.h :functions: wiphy_register .. kernel-doc:: include/net/cfg80211.h diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst new file mode 100644 index 000000000000..b00b23903078 --- /dev/null +++ b/Documentation/driver-api/device-io.rst @@ -0,0 +1,201 @@ +.. Copyright 2001 Matthew Wilcox +.. +.. 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. + +=============================== +Bus-Independent Device Accesses +=============================== + +:Author: Matthew Wilcox +:Author: Alan Cox + +Introduction +============ + +Linux provides an API which abstracts performing IO across all busses +and devices, allowing device drivers to be written independently of bus +type. + +Memory Mapped IO +================ + +Getting Access to the Device +---------------------------- + +The most widely supported form of IO is memory mapped IO. That is, a +part of the CPU's address space is interpreted not as accesses to +memory, but as accesses to a device. Some architectures define devices +to be at a fixed address, but most have some method of discovering +devices. The PCI bus walk is a good example of such a scheme. This +document does not cover how to receive such an address, but assumes you +are starting with one. Physical addresses are of type unsigned long. + +This address should not be used directly. Instead, to get an address +suitable for passing to the accessor functions described below, you +should call :c:func:`ioremap()`. An address suitable for accessing +the device will be returned to you. + +After you've finished using the device (say, in your module's exit +routine), call :c:func:`iounmap()` in order to return the address +space to the kernel. Most architectures allocate new address space each +time you call :c:func:`ioremap()`, and they can run out unless you +call :c:func:`iounmap()`. + +Accessing the device +-------------------- + +The part of the interface most used by drivers is reading and writing +memory-mapped registers on the device. Linux provides interfaces to read +and write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a +historical accident, these are named byte, word, long and quad accesses. +Both read and write accesses are supported; there is no prefetch support +at this time. + +The functions are named readb(), readw(), readl(), readq(), +readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), +writeb(), writew(), writel() and writeq(). + +Some devices (such as framebuffers) would like to use larger transfers than +8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, +:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are +provided. Do not use memset or memcpy on IO addresses; they are not +guaranteed to copy data in order. + +The read and write functions are defined to be ordered. That is the +compiler is not permitted to reorder the I/O sequence. When the ordering +can be compiler optimised, you can use __readb() and friends to +indicate the relaxed ordering. Use this with care. + +While the basic functions are defined to be synchronous with respect to +each other and ordered with respect to each other the busses the devices +sit on may themselves have asynchronicity. In particular many authors +are burned by the fact that PCI bus writes are posted asynchronously. A +driver author must issue a read from the same device to ensure that +writes have occurred in the specific cases the author cares. This kind +of property cannot be hidden from driver writers in the API. In some +cases, the read used to flush the device may be expected to fail (if the +card is resetting, for example). In that case, the read should be done +from config space, which is guaranteed to soft-fail if the card doesn't +respond. + +The following is an example of flushing a write to a device when the +driver would like to ensure the write's effects are visible prior to +continuing execution:: + + static inline void + qla1280_disable_intrs(struct scsi_qla_host *ha) + { + struct device_reg *reg; + + reg = ha->iobase; + /* disable risc and host interrupts */ + WRT_REG_WORD(®->ictrl, 0); + /* + * The following read will ensure that the above write + * has been received by the device before we return from this + * function. + */ + RD_REG_WORD(®->ictrl); + ha->flags.ints_enabled = 0; + } + +In addition to write posting, on some large multiprocessing systems +(e.g. SGI Challenge, Origin and Altix machines) posted writes won't be +strongly ordered coming from different CPUs. Thus it's important to +properly protect parts of your driver that do memory-mapped writes with +locks and use the :c:func:`mmiowb()` to make sure they arrive in the +order intended. Issuing a regular readX() will also ensure write ordering, +but should only be used when the +driver has to be sure that the write has actually arrived at the device +(not that it's simply ordered with respect to other writes), since a +full readX() is a relatively expensive operation. + +Generally, one should use :c:func:`mmiowb()` prior to releasing a spinlock +that protects regions using :c:func:`writeb()` or similar functions that +aren't surrounded by readb() calls, which will ensure ordering +and flushing. The following pseudocode illustrates what might occur if +write ordering isn't guaranteed via :c:func:`mmiowb()` or one of the +readX() functions:: + + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: writel(newval2, ring_ptr); + CPU B: ... + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +In the case above, newval2 could be written to ring_ptr before newval. +Fixing it is easy though:: + + CPU A: spin_lock_irqsave(&dev_lock, flags) + CPU A: ... + CPU A: writel(newval, ring_ptr); + CPU A: mmiowb(); /* ensure no other writes beat us to the device */ + CPU A: spin_unlock_irqrestore(&dev_lock, flags) + ... + CPU B: spin_lock_irqsave(&dev_lock, flags) + CPU B: writel(newval2, ring_ptr); + CPU B: ... + CPU B: mmiowb(); + CPU B: spin_unlock_irqrestore(&dev_lock, flags) + +See tg3.c for a real world example of how to use :c:func:`mmiowb()` + +PCI ordering rules also guarantee that PIO read responses arrive after any +outstanding DMA writes from that bus, since for some devices the result of +a readb() call may signal to the driver that a DMA transaction is +complete. In many cases, however, the driver may want to indicate that the +next readb() call has no relation to any previous DMA writes +performed by the device. The driver can use readb_relaxed() for +these cases, although only some platforms will honor the relaxed +semantics. Using the relaxed read functions will provide significant +performance benefits on platforms that support it. The qla2xxx driver +provides examples of how to use readX_relaxed(). In many cases, a majority +of the driver's readX() calls can safely be converted to readX_relaxed() +calls, since only a few will indicate or depend on DMA completion. + +Port Space Accesses +=================== + +Port Space Explained +-------------------- + +Another form of IO commonly supported is Port Space. This is a range of +addresses separate to the normal memory address space. Access to these +addresses is generally not as fast as accesses to the memory mapped +addresses, and it also has a potentially smaller address space. + +Unlike memory mapped IO, no preparation is required to access port +space. + +Accessing Port Space +-------------------- + +Accesses to this space are provided through a set of functions which +allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and +long. These functions are :c:func:`inb()`, :c:func:`inw()`, +:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and +:c:func:`outl()`. + +Some variants are provided for these functions. Some devices require +that accesses to their ports are slowed down. This functionality is +provided by appending a ``_p`` to the end of the function. +There are also equivalents to memcpy. The :c:func:`ins()` and +:c:func:`outs()` functions copy bytes, words or longs to the given +port. + +Public Functions Provided +========================= + +.. kernel-doc:: arch/x86/include/asm/io.h + :internal: + +.. kernel-doc:: lib/pci_iomap.c + :export: diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst index 5f5713448703..70e328e16aad 100644 --- a/Documentation/driver-api/device_link.rst +++ b/Documentation/driver-api/device_link.rst @@ -1,3 +1,6 @@ +.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` +.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>` + ============ Device links ============ @@ -120,12 +123,11 @@ Examples is the same as if the MMU was the parent of the master device. The fact that both devices share the same power domain would normally - suggest usage of a :c:type:`struct dev_pm_domain` or :c:type:`struct - generic_pm_domain`, however these are not independent devices that - happen to share a power switch, but rather the MMU device serves the - busmaster device and is useless without it. A device link creates a - synthetic hierarchical relationship between the devices and is thus - more apt. + suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|, + however these are not independent devices that happen to share a power + switch, but rather the MMU device serves the busmaster device and is + useless without it. A device link creates a synthetic hierarchical + relationship between the devices and is thus more apt. * A Thunderbolt host controller comprises a number of PCIe hotplug ports and an NHI device to manage the PCIe switch. On resume from system sleep, @@ -157,7 +159,7 @@ Examples Alternatives ============ -* A :c:type:`struct dev_pm_domain` can be used to override the bus, +* A |struct dev_pm_domain| can be used to override the bus, class or device type callbacks. It is intended for devices sharing a single on/off switch, however it does not guarantee a specific suspend/resume ordering, this needs to be implemented separately. @@ -166,7 +168,7 @@ Alternatives suspended. Furthermore it cannot be used to enforce a specific shutdown ordering or a driver presence dependency. -* A :c:type:`struct generic_pm_domain` is a lot more heavyweight than a +* A |struct generic_pm_domain| is a lot more heavyweight than a device link and does not allow for shutdown ordering or driver presence dependencies. It also cannot be used on ACPI systems. diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index a9b457a4b949..31671b469627 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -17,6 +17,98 @@ shared or exclusive fence(s) associated with the buffer. Shared DMA Buffers ------------------ +This document serves as a guide to device-driver writers on what is the dma-buf +buffer sharing API, how to use it for exporting and using shared buffers. + +Any device driver which wishes to be a part of DMA buffer sharing, can do so as +either the 'exporter' of buffers, or the 'user' or 'importer' of buffers. + +Say a driver A wants to use buffers created by driver B, then we call B as the +exporter, and A as buffer-user/importer. + +The exporter + + - implements and manages operations in :c:type:`struct dma_buf_ops + <dma_buf_ops>` for the buffer, + - allows other users to share the buffer by using dma_buf sharing APIs, + - manages the details of buffer allocation, wrapped int a :c:type:`struct + dma_buf <dma_buf>`, + - decides about the actual backing storage where this allocation happens, + - and takes care of any migration of scatterlist - for all (shared) users of + this buffer. + +The buffer-user + + - is one of (many) sharing users of the buffer. + - doesn't need to worry about how the buffer is allocated, or where. + - and needs a mechanism to get access to the scatterlist that makes up this + buffer in memory, mapped into its own address space, so it can access the + same area of memory. This interface is provided by :c:type:`struct + dma_buf_attachment <dma_buf_attachment>`. + +Any exporters or users of the dma-buf buffer sharing framework must have a +'select DMA_SHARED_BUFFER' in their respective Kconfigs. + +Userspace Interface Notes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Mostly a DMA buffer file descriptor is simply an opaque object for userspace, +and hence the generic interface exposed is very minimal. There's a few things to +consider though: + +- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only + with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow + the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other + llseek operation will report -EINVAL. + + If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all + cases. Userspace can use this to detect support for discovering the dma-buf + size using llseek. + +- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set + on the file descriptor. This is not just a resource leak, but a + potential security hole. It could give the newly exec'd application + access to buffers, via the leaked fd, to which it should otherwise + not be permitted access. + + The problem with doing this via a separate fcntl() call, versus doing it + atomically when the fd is created, is that this is inherently racy in a + multi-threaded app[3]. The issue is made worse when it is library code + opening/creating the file descriptor, as the application may not even be + aware of the fd's. + + To avoid this problem, userspace must have a way to request O_CLOEXEC + flag be set when the dma-buf fd is created. So any API provided by + the exporting driver to create a dmabuf fd must provide a way to let + userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd(). + +- Memory mapping the contents of the DMA buffer is also supported. See the + discussion below on `CPU Access to DMA Buffer Objects`_ for the full details. + +- The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for + details. + +Basic Operation and Device DMA Access +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :doc: dma buf device access + +CPU Access to DMA Buffer Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :doc: cpu access + +Fence Poll Support +~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/dma-buf/dma-buf.c + :doc: fence polling + +Kernel Functions and Structures Reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. kernel-doc:: drivers/dma-buf/dma-buf.c :export: diff --git a/Documentation/driver-api/firmware/built-in-fw.rst b/Documentation/driver-api/firmware/built-in-fw.rst new file mode 100644 index 000000000000..7300e66857f8 --- /dev/null +++ b/Documentation/driver-api/firmware/built-in-fw.rst @@ -0,0 +1,38 @@ +================= +Built-in firmware +================= + +Firmware can be built-in to the kernel, this means building the firmware +into vmlinux directly, to enable avoiding having to look for firmware from +the filesystem. Instead, firmware can be looked for inside the kernel +directly. You can enable built-in firmware using the kernel configuration +options: + + * CONFIG_EXTRA_FIRMWARE + * CONFIG_EXTRA_FIRMWARE_DIR + +This should not be confused with CONFIG_FIRMWARE_IN_KERNEL, this is for drivers +which enables firmware to be built as part of the kernel build process. This +option, CONFIG_FIRMWARE_IN_KERNEL, will build all firmware for all drivers +enabled which ship its firmware inside the Linux kernel source tree. + +There are a few reasons why you might want to consider building your firmware +into the kernel with CONFIG_EXTRA_FIRMWARE though: + +* Speed +* Firmware is needed for accessing the boot device, and the user doesn't + want to stuff the firmware into the boot initramfs. + +Even if you have these needs there are a few reasons why you may not be +able to make use of built-in firmware: + +* Legalese - firmware is non-GPL compatible +* Some firmware may be optional +* Firmware upgrades are possible, therefore a new firmware would implicate + a complete kernel rebuild. +* Some firmware files may be really large in size. The remote-proc subsystem + is an example subsystem which deals with these sorts of firmware +* The firmware may need to be scraped out from some device specific location + dynamically, an example is calibration data for for some WiFi chipsets. This + calibration data can be unique per sold device. + diff --git a/Documentation/driver-api/firmware/core.rst b/Documentation/driver-api/firmware/core.rst new file mode 100644 index 000000000000..1d1688cbc078 --- /dev/null +++ b/Documentation/driver-api/firmware/core.rst @@ -0,0 +1,16 @@ +========================== +Firmware API core features +========================== + +The firmware API has a rich set of core features available. This section +documents these features. + +.. toctree:: + + fw_search_path + built-in-fw + firmware_cache + direct-fs-lookup + fallback-mechanisms + lookup-order + diff --git a/Documentation/driver-api/firmware/direct-fs-lookup.rst b/Documentation/driver-api/firmware/direct-fs-lookup.rst new file mode 100644 index 000000000000..82b4d585a213 --- /dev/null +++ b/Documentation/driver-api/firmware/direct-fs-lookup.rst @@ -0,0 +1,30 @@ +======================== +Direct filesystem lookup +======================== + +Direct filesystem lookup is the most common form of firmware lookup performed +by the kernel. The kernel looks for the firmware directly on the root +filesystem in the paths documented in the section 'Firmware search paths'. +The filesystem lookup is implemented in fw_get_filesystem_firmware(), it +uses common core kernel file loader facility kernel_read_file_from_path(). +The max path allowed is PATH_MAX -- currently this is 4096 characters. + +It is recommended you keep /lib/firmware paths on your root filesystem, +avoid having a separate partition for them in order to avoid possible +races with lookups and avoid uses of the custom fallback mechanisms +documented below. + +Firmware and initramfs +---------------------- + +Drivers which are built-in to the kernel should have the firmware integrated +also as part of the initramfs used to boot the kernel given that otherwise +a race is possible with loading the driver and the real rootfs not yet being +available. Stuffing the firmware into initramfs resolves this race issue, +however note that using initrd does not suffice to address the same race. + +There are circumstances that justify not wanting to include firmware into +initramfs, such as dealing with large firmware firmware files for the +remote-proc subsystem. For such cases using a userspace fallback mechanism +is currently the only viable solution as only userspace can know for sure +when the real rootfs is ready and mounted. diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst new file mode 100644 index 000000000000..d19354794e67 --- /dev/null +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst @@ -0,0 +1,195 @@ +=================== +Fallback mechanisms +=================== + +A fallback mechanism is supported to allow to overcome failures to do a direct +filesystem lookup on the root filesystem or when the firmware simply cannot be +installed for practical reasons on the root filesystem. The kernel +configuration options related to supporting the firmware fallback mechanism are: + + * CONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback + mechanism. Most distributions enable this option today. If enabled but + CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback + mechanism is available and for the request_firmware_nowait() call. + * CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to + enable the kobject uevent fallback mechanism on all firmware API calls + except request_firmware_direct(). Most distributions disable this option + today. The call request_firmware_nowait() allows for one alternative + fallback mechanism: if this kconfig option is enabled and your second + argument to request_firmware_nowait(), uevent, is set to false you are + informing the kernel that you have a custom fallback mechanism and it will + manually load the firmware. Read below for more details. + +Note that this means when having this configuration: + +CONFIG_FW_LOADER_USER_HELPER=y +CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n + +the kobject uevent fallback mechanism will never take effect even +for request_firmware_nowait() when uevent is set to true. + +Justifying the firmware fallback mechanism +========================================== + +Direct filesystem lookups may fail for a variety of reasons. Known reasons for +this are worth itemizing and documenting as it justifies the need for the +fallback mechanism: + +* Race against access with the root filesystem upon bootup. + +* Races upon resume from suspend. This is resolved by the firmware cache, but + the firmware cache is only supported if you use uevents, and its not + supported for request_firmware_into_buf(). + +* Firmware is not accessible through typical means: + * It cannot be installed into the root filesystem + * The firmware provides very unique device specific data tailored for + the unit gathered with local information. An example is calibration + data for WiFi chipsets for mobile devices. This calibration data is + not common to all units, but tailored per unit. Such information may + be installed on a separate flash partition other than where the root + filesystem is provided. + +Types of fallback mechanisms +============================ + +There are really two fallback mechanisms available using one shared sysfs +interface as a loading facility: + +* Kobject uevent fallback mechanism +* Custom fallback mechanism + +First lets document the shared sysfs loading facility. + +Firmware sysfs loading facility +=============================== + +In order to help device drivers upload firmware using a fallback mechanism +the firmware infrastructure creates a sysfs interface to enable userspace +to load and indicate when firmware is ready. The sysfs directory is created +via fw_create_instance(). This call creates a new struct device named after +the firmware requested, and establishes it in the device hierarchy by +associating the device used to make the request as the device's parent. +The sysfs directory's file attributes are defined and controlled through +the new device's class (firmare_class) and group (fw_dev_attr_groups). +This is actually where the original firmware_class.c file name comes from, +as originally the only firmware loading mechanism available was the +mechanism we now use as a fallback mechanism. + +To load firmware using the sysfs interface we expose a loading indicator, +and a file upload firmware into: + + * /sys/$DEVPATH/loading + * /sys/$DEVPATH/data + +To upload firmware you will echo 1 onto the loading file to indicate +you are loading firmware. You then cat the firmware into the data file, +and you notify the kernel the firmware is ready by echo'ing 0 onto +the loading file. + +The firmware device used to help load firmware using sysfs is only created if +direct firmware loading fails and if the fallback mechanism is enabled for your +firmware request, this is set up with fw_load_from_user_helper(). It is +important to re-iterate that no device is created if a direct filesystem lookup +succeeded. + +Using:: + + echo 1 > /sys/$DEVPATH/loading + +Will clean any previous partial load at once and make the firmware API +return an error. When loading firmware the firmware_class grows a buffer +for the firmware in PAGE_SIZE increments to hold the image as it comes in. + +firmware_data_read() and firmware_loading_show() are just provided for the +test_firmware driver for testing, they are not called in normal use or +expected to be used regularly by userspace. + +Firmware kobject uevent fallback mechanism +========================================== + +Since a device is created for the sysfs interface to help load firmware as a +fallback mechanism userspace can be informed of the addition of the device by +relying on kobject uevents. The addition of the device into the device +hierarchy means the fallback mechanism for firmware loading has been initiated. +For details of implementation refer to _request_firmware_load(), in particular +on the use of dev_set_uevent_suppress() and kobject_uevent(). + +The kernel's kobject uevent mechanism is implemented in lib/kobject_uevent.c, +it issues uevents to userspace. As a supplement to kobject uevents Linux +distributions could also enable CONFIG_UEVENT_HELPER_PATH, which makes use of +core kernel's usermode helper (UMH) functionality to call out to a userspace +helper for kobject uevents. In practice though no standard distribution has +ever used the CONFIG_UEVENT_HELPER_PATH. If CONFIG_UEVENT_HELPER_PATH is +enabled this binary would be called each time kobject_uevent_env() gets called +in the kernel for each kobject uevent triggered. + +Different implementations have been supported in userspace to take advantage of +this fallback mechanism. When firmware loading was only possible using the +sysfs mechanism the userspace component "hotplug" provided the functionality of +monitoring for kobject events. Historically this was superseded be systemd's +udev, however firmware loading support was removed from udev as of systemd +commit be2ea723b1d0 ("udev: remove userspace firmware loading support") +as of v217 on August, 2014. This means most Linux distributions today are +not using or taking advantage of the firmware fallback mechanism provided +by kobject uevents. This is specially exacerbated due to the fact that most +distributions today disable CONFIG_FW_LOADER_USER_HELPER_FALLBACK. + +Refer to do_firmware_uevent() for details of the kobject event variables +setup. Variables passwdd with a kobject add event: + +* FIRMWARE=firmware name +* TIMEOUT=timeout value +* ASYNC=whether or not the API request was asynchronous + +By default DEVPATH is set by the internal kernel kobject infrastructure. +Below is an example simple kobject uevent script:: + + # Both $DEVPATH and $FIRMWARE are already provided in the environment. + MY_FW_DIR=/lib/firmware/ + echo 1 > /sys/$DEVPATH/loading + cat $MY_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data + echo 0 > /sys/$DEVPATH/loading + +Firmware custom fallback mechanism +================================== + +Users of the request_firmware_nowait() call have yet another option available +at their disposal: rely on the sysfs fallback mechanism but request that no +kobject uevents be issued to userspace. The original logic behind this +was that utilities other than udev might be required to lookup firmware +in non-traditional paths -- paths outside of the listing documented in the +section 'Direct filesystem lookup'. This option is not available to any of +the other API calls as uevents are always forced for them. + +Since uevents are only meaningful if the fallback mechanism is enabled +in your kernel it would seem odd to enable uevents with kernels that do not +have the fallback mechanism enabled in their kernels. Unfortunately we also +rely on the uevent flag which can be disabled by request_firmware_nowait() to +also setup the firmware cache for firmware requests. As documented above, +the firmware cache is only set up if uevent is enabled for an API call. +Although this can disable the firmware cache for request_firmware_nowait() +calls, users of this API should not use it for the purposes of disabling +the cache as that was not the original purpose of the flag. Not setting +the uevent flag means you want to opt-in for the firmware fallback mechanism +but you want to suppress kobject uevents, as you have a custom solution which +will monitor for your device addition into the device hierarchy somehow and +load firmware for you through a custom path. + +Firmware fallback timeout +========================= + +The firmware fallback mechanism has a timeout. If firmware is not loaded +onto the sysfs interface by the timeout value an error is sent to the +driver. By default the timeout is set to 60 seconds if uevents are +desirable, otherwise MAX_JIFFY_OFFSET is used (max timeout possible). +The logic behind using MAX_JIFFY_OFFSET for non-uevents is that a custom +solution will have as much time as it needs to load firmware. + +You can customize the firmware timeout by echo'ing your desired timeout into +the following file: + +* /sys/class/firmware/timeout + +If you echo 0 into it means MAX_JIFFY_OFFSET will be used. The data type +for the timeout is an int. diff --git a/Documentation/driver-api/firmware/firmware_cache.rst b/Documentation/driver-api/firmware/firmware_cache.rst new file mode 100644 index 000000000000..2210e5bfb332 --- /dev/null +++ b/Documentation/driver-api/firmware/firmware_cache.rst @@ -0,0 +1,51 @@ +============== +Firmware cache +============== + +When Linux resumes from suspend some device drivers require firmware lookups to +re-initialize devices. During resume there may be a period of time during which +firmware lookups are not possible, during this short period of time firmware +requests will fail. Time is of essence though, and delaying drivers to wait for +the root filesystem for firmware delays user experience with device +functionality. In order to support these requirements the firmware +infrastructure implements a firmware cache for device drivers for most API +calls, automatically behind the scenes. + +The firmware cache makes using certain firmware API calls safe during a device +driver's suspend and resume callback. Users of these API calls needn't cache +the firmware by themselves for dealing with firmware loss during system resume. + +The firmware cache works by requesting for firmware prior to suspend and +caching it in memory. Upon resume device drivers using the firmware API will +have access to the firmware immediately, without having to wait for the root +filesystem to mount or dealing with possible race issues with lookups as the +root filesystem mounts. + +Some implementation details about the firmware cache setup: + +* The firmware cache is setup by adding a devres entry for each device that + uses all synchronous call except :c:func:`request_firmware_into_buf`. + +* If an asynchronous call is used the firmware cache is only set up for a + device if if the second argument (uevent) to request_firmware_nowait() is + true. When uevent is true it requests that a kobject uevent be sent to + userspace for the firmware request. For details refer to the Fackback + mechanism documented below. + +* If the firmware cache is determined to be needed as per the above two + criteria the firmware cache is setup by adding a devres entry for the + device making the firmware request. + +* The firmware devres entry is maintained throughout the lifetime of the + device. This means that even if you release_firmware() the firmware cache + will still be used on resume from suspend. + +* The timeout for the fallback mechanism is temporarily reduced to 10 seconds + as the firmware cache is set up during suspend, the timeout is set back to + the old value you had configured after the cache is set up. + +* Upon suspend any pending non-uevent firmware requests are killed to avoid + stalling the kernel, this is done with kill_requests_without_uevent(). Kernel + calls requiring the non-uevent therefore need to implement their own firmware + cache mechanism but must not use the firmware API on suspend. + diff --git a/Documentation/driver-api/firmware/fw_search_path.rst b/Documentation/driver-api/firmware/fw_search_path.rst new file mode 100644 index 000000000000..a360f1009fa3 --- /dev/null +++ b/Documentation/driver-api/firmware/fw_search_path.rst @@ -0,0 +1,26 @@ +===================== +Firmware search paths +===================== + +The following search paths are used to look for firmware on your +root filesystem. + +* fw_path_para - module parameter - default is empty so this is ignored +* /lib/firmware/updates/UTS_RELEASE/ +* /lib/firmware/updates/ +* /lib/firmware/UTS_RELEASE/ +* /lib/firmware/ + +The module parameter ''path'' can be passed to the firmware_class module +to activate the first optional custom fw_path_para. The custom path can +only be up to 256 characters long. The kernel parameter passed would be: + +* 'firmware_class.path=$CUSTOMIZED_PATH' + +There is an alternative to customize the path at run time after bootup, you +can use the file: + +* /sys/module/firmware_class/parameters/path + +You would echo into it your custom path and firmware requested will be +searched for there first. diff --git a/Documentation/driver-api/firmware/index.rst b/Documentation/driver-api/firmware/index.rst new file mode 100644 index 000000000000..1abe01793031 --- /dev/null +++ b/Documentation/driver-api/firmware/index.rst @@ -0,0 +1,16 @@ +================== +Linux Firmware API +================== + +.. toctree:: + + introduction + core + request_firmware + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/firmware/introduction.rst b/Documentation/driver-api/firmware/introduction.rst new file mode 100644 index 000000000000..211cb44eb972 --- /dev/null +++ b/Documentation/driver-api/firmware/introduction.rst @@ -0,0 +1,27 @@ +============ +Introduction +============ + +The firmware API enables kernel code to request files required +for functionality from userspace, the uses vary: + +* Microcode for CPU errata +* Device driver firmware, required to be loaded onto device + microcontrollers +* Device driver information data (calibration data, EEPROM overrides), + some of which can be completely optional. + +Types of firmware requests +========================== + +There are two types of calls: + +* Synchronous +* Asynchronous + +Which one you use vary depending on your requirements, the rule of thumb +however is you should strive to use the asynchronous APIs unless you also +are already using asynchronous initialization mechanisms which will not +stall or delay boot. Even if loading firmware does not take a lot of time +processing firmware might, and this can still delay boot or initialization, +as such mechanisms such as asynchronous probe can help supplement drivers. diff --git a/Documentation/driver-api/firmware/lookup-order.rst b/Documentation/driver-api/firmware/lookup-order.rst new file mode 100644 index 000000000000..88c81739683c --- /dev/null +++ b/Documentation/driver-api/firmware/lookup-order.rst @@ -0,0 +1,18 @@ +===================== +Firmware lookup order +===================== + +Different functionality is available to enable firmware to be found. +Below is chronological order of how firmware will be looked for once +a driver issues a firmware API call. + +* The ''Built-in firmware'' is checked first, if the firmware is present we + return it immediately +* The ''Firmware cache'' is looked at next. If the firmware is found we + return it immediately +* The ''Direct filesystem lookup'' is performed next, if found we + return it immediately +* If no firmware has been found and the fallback mechanism was enabled + the sysfs interface is created. After this either a kobject uevent + is issued or the custom firmware loading is relied upon for firmware + loading up to the timeout value. diff --git a/Documentation/driver-api/firmware/request_firmware.rst b/Documentation/driver-api/firmware/request_firmware.rst new file mode 100644 index 000000000000..cc0aea880824 --- /dev/null +++ b/Documentation/driver-api/firmware/request_firmware.rst @@ -0,0 +1,56 @@ +==================== +request_firmware API +==================== + +You would typically load firmware and then load it into your device somehow. +The typical firmware work flow is reflected below:: + + if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) + copy_fw_to_device(fw_entry->data, fw_entry->size); + release_firmware(fw_entry); + +Synchronous firmware requests +============================= + +Synchronous firmware requests will wait until the firmware is found or until +an error is returned. + +request_firmware +---------------- +.. kernel-doc:: drivers/base/firmware_class.c + :functions: request_firmware + +request_firmware_direct +----------------------- +.. kernel-doc:: drivers/base/firmware_class.c + :functions: request_firmware_direct + +request_firmware_into_buf +------------------------- +.. kernel-doc:: drivers/base/firmware_class.c + :functions: request_firmware_into_buf + +Asynchronous firmware requests +============================== + +Asynchronous firmware requests allow driver code to not have to wait +until the firmware or an error is returned. Function callbacks are +provided so that when the firmware or an error is found the driver is +informed through the callback. request_firmware_nowait() cannot be called +in atomic contexts. + +request_firmware_nowait +----------------------- +.. kernel-doc:: drivers/base/firmware_class.c + :functions: request_firmware_nowait + +request firmware API expected driver use +======================================== + +Once an API call returns you process the firmware and then release the +firmware. For example if you used request_firmware() and it returns, +the driver has the firmware image accessible in fw_entry->{data,size}. +If something went wrong request_firmware() returns non-zero and fw_entry +is set to NULL. Once your driver is done with processing the firmware it +can call call release_firmware(fw_entry) to release the firmware image +and any related resource. diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst new file mode 100644 index 000000000000..02c99a6bee18 --- /dev/null +++ b/Documentation/driver-api/iio/buffers.rst @@ -0,0 +1,125 @@ +======= +Buffers +======= + +* struct :c:type:`iio_buffer` — general buffer structure +* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel + is selected +* :c:func:`iio_buffer_get` — Grab a reference to the buffer +* :c:func:`iio_buffer_put` — Release the reference to the buffer + +The Industrial I/O core offers a way for continuous data capture based on a +trigger source. Multiple data channels can be read at once from +:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load. + +IIO buffer sysfs interface +========================== +An IIO buffer has an associated attributes directory under +:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing +attributes: + +* :file:`length`, the total number of data samples (capacity) that can be + stored by the buffer. +* :file:`enable`, activate buffer capture. + +IIO buffer setup +================ + +The meta information associated with a channel reading placed in a buffer is +called a scan element . The important bits configuring scan elements are +exposed to userspace applications via the +:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains +attributes of the following form: + +* :file:`enable`, used for enabling a channel. If and only if its attribute + is non *zero*, then a triggered capture will contain data samples for this + channel. +* :file:`type`, description of the scan element data storage within the buffer + and hence the form in which it is read from user space. + Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + * *be* or *le*, specifies big or little endian. + * *s* or *u*, specifies if signed (2's complement) or unsigned. + * *bits*, is the number of valid data bits. + * *storagebits*, is the number of bits (after padding) that it occupies in the + buffer. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. + * *repeat*, specifies the number of bits/storagebits repetitions. When the + repeat element is 0 or 1, then the repeat value is omitted. + +For example, a driver for a 3-axis accelerometer with 12 bit resolution where +data is stored in two 8-bits registers as follows:: + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) + +---+---+---+---+---+---+---+---+ + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) + +---+---+---+---+---+---+---+---+ + +will have the following scan element type for each axis:: + + $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type + le:s12/16>>4 + +A user space application will interpret data samples read from the buffer as +two byte little endian signed data, that needs a 4 bits right shift before +masking out the 12 valid bits of data. + +For implementing buffer support a driver should initialize the following +fields in iio_chan_spec definition:: + + struct iio_chan_spec { + /* other members */ + int scan_index + struct { + char sign; + u8 realbits; + u8 storagebits; + u8 shift; + u8 repeat; + enum iio_endian endianness; + } scan_type; + }; + +The driver implementing the accelerometer described above will have the +following channel definition:: + + struct struct iio_chan_spec accel_channels[] = { + { + .type = IIO_ACCEL, + .modified = 1, + .channel2 = IIO_MOD_X, + /* other stuff here */ + .scan_index = 0, + .scan_type = { + .sign = 's', + .realbits = 12, + .storagebits = 16, + .shift = 4, + .endianness = IIO_LE, + }, + } + /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) + * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis + */ + } + +Here **scan_index** defines the order in which the enabled channels are placed +inside the buffer. Channels with a lower **scan_index** will be placed before +channels with a higher index. Each channel needs to have a unique +**scan_index**. + +Setting **scan_index** to -1 can be used to indicate that the specific channel +does not support buffered capture. In this case no entries will be created for +the channel in the scan_elements directory. + +More details +============ +.. kernel-doc:: include/linux/iio/buffer.h +.. kernel-doc:: drivers/iio/industrialio-buffer.c + :export: + diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst new file mode 100644 index 000000000000..9a34ae03b679 --- /dev/null +++ b/Documentation/driver-api/iio/core.rst @@ -0,0 +1,182 @@ +============= +Core elements +============= + +The Industrial I/O core offers a unified framework for writing drivers for +many different types of embedded sensors. a standard interface to user space +applications manipulating sensors. The implementation can be found under +:file:`drivers/iio/industrialio-*` + +Industrial I/O Devices +---------------------- + +* struct :c:type:`iio_dev` - industrial I/O device +* :c:func:`iio_device_alloc()` - alocate an :c:type:`iio_dev` from a driver +* :c:func:`iio_device_free()` - free an :c:type:`iio_dev` from a driver +* :c:func:`iio_device_register()` - register a device with the IIO subsystem +* :c:func:`iio_device_unregister()` - unregister a device from the IIO + subsystem + +An IIO device usually corresponds to a single hardware sensor and it +provides all the information needed by a driver handling a device. +Let's first have a look at the functionality embedded in an IIO device +then we will show how a device driver makes use of an IIO device. + +There are two ways for a user space application to interact with an IIO driver. + +1. :file:`/sys/bus/iio/iio:device{X}/`, this represents a hardware sensor + and groups together the data channels of the same chip. +2. :file:`/dev/iio:device{X}`, character device node interface used for + buffered data transfer and for events information retrieval. + +A typical IIO driver will register itself as an :doc:`I2C <../i2c>` or +:doc:`SPI <../spi>` driver and will create two routines, probe and remove. + +At probe: + +1. Call :c:func:`iio_device_alloc()`, which allocates memory for an IIO device. +2. Initialize IIO device fields with driver specific information (e.g. + device name, device channels). +3. Call :c:func:`iio_device_register()`, this registers the device with the + IIO core. After this call the device is ready to accept requests from user + space applications. + +At remove, we free the resources allocated in probe in reverse order: + +1. :c:func:`iio_device_unregister()`, unregister the device from the IIO core. +2. :c:func:`iio_device_free()`, free the memory allocated for the IIO device. + +IIO device sysfs interface +========================== + +Attributes are sysfs files used to expose chip info and also allowing +applications to set various configuration parameters. For device with +index X, attributes can be found under /sys/bus/iio/iio:deviceX/ directory. +Common attributes are: + +* :file:`name`, description of the physical chip. +* :file:`dev`, shows the major:minor pair associated with + :file:`/dev/iio:deviceX` node. +* :file:`sampling_frequency_available`, available discrete set of sampling + frequency values for device. +* Available standard attributes for IIO devices are described in the + :file:`Documentation/ABI/testing/sysfs-bus-iio` file in the Linux kernel + sources. + +IIO device channels +=================== + +struct :c:type:`iio_chan_spec` - specification of a single channel + +An IIO device channel is a representation of a data channel. An IIO device can +have one or multiple channels. For example: + +* a thermometer sensor has one channel representing the temperature measurement. +* a light sensor with two channels indicating the measurements in the visible + and infrared spectrum. +* an accelerometer can have up to 3 channels representing acceleration on X, Y + and Z axes. + +An IIO channel is described by the struct :c:type:`iio_chan_spec`. +A thermometer driver for the temperature sensor in the example above would +have to describe its channel as follows:: + + static const struct iio_chan_spec temp_channel[] = { + { + .type = IIO_TEMP, + .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), + }, + }; + +Channel sysfs attributes exposed to userspace are specified in the form of +bitmasks. Depending on their shared info, attributes can be set in one of the +following masks: + +* **info_mask_separate**, attributes will be specific to + this channel +* **info_mask_shared_by_type**, attributes are shared by all channels of the + same type +* **info_mask_shared_by_dir**, attributes are shared by all channels of the same + direction +* **info_mask_shared_by_all**, attributes are shared by all channels + +When there are multiple data channels per channel type we have two ways to +distinguish between them: + +* set **.modified** field of :c:type:`iio_chan_spec` to 1. Modifiers are + specified using **.channel2** field of the same :c:type:`iio_chan_spec` + structure and are used to indicate a physically unique characteristic of the + channel such as its direction or spectral response. For example, a light + sensor can have two channels, one for infrared light and one for both + infrared and visible light. +* set **.indexed** field of :c:type:`iio_chan_spec` to 1. In this case the + channel is simply another instance with an index specified by the **.channel** + field. + +Here is how we can make use of the channel's modifiers:: + + static const struct iio_chan_spec light_channels[] = { + { + .type = IIO_INTENSITY, + .modified = 1, + .channel2 = IIO_MOD_LIGHT_IR, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + { + .type = IIO_INTENSITY, + .modified = 1, + .channel2 = IIO_MOD_LIGHT_BOTH, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + { + .type = IIO_LIGHT, + .info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED), + .info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ), + }, + } + +This channel's definition will generate two separate sysfs files for raw data +retrieval: + +* :file:`/sys/bus/iio/iio:device{X}/in_intensity_ir_raw` +* :file:`/sys/bus/iio/iio:device{X}/in_intensity_both_raw` + +one file for processed data: + +* :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input` + +and one shared sysfs file for sampling frequency: + +* :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`. + +Here is how we can make use of the channel's indexing:: + + static const struct iio_chan_spec light_channels[] = { + { + .type = IIO_VOLTAGE, + .indexed = 1, + .channel = 0, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + }, + { + .type = IIO_VOLTAGE, + .indexed = 1, + .channel = 1, + .info_mask_separate = BIT(IIO_CHAN_INFO_RAW), + }, + } + +This will generate two separate attributes files for raw data retrieval: + +* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage0_raw`, representing + voltage measurement for channel 0. +* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage1_raw`, representing + voltage measurement for channel 1. + +More details +============ +.. kernel-doc:: include/linux/iio/iio.h +.. kernel-doc:: drivers/iio/industrialio-core.c + :export: diff --git a/Documentation/driver-api/iio/index.rst b/Documentation/driver-api/iio/index.rst new file mode 100644 index 000000000000..e5c3922d1b6f --- /dev/null +++ b/Documentation/driver-api/iio/index.rst @@ -0,0 +1,17 @@ +.. include:: <isonum.txt> + +Industrial I/O +============== + +**Copyright** |copy| 2015 Intel Corporation + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + core + buffers + triggers + triggered-buffers diff --git a/Documentation/driver-api/iio/intro.rst b/Documentation/driver-api/iio/intro.rst new file mode 100644 index 000000000000..3653fbd57069 --- /dev/null +++ b/Documentation/driver-api/iio/intro.rst @@ -0,0 +1,33 @@ +.. include:: <isonum.txt> + +============ +Introduction +============ + +The main purpose of the Industrial I/O subsystem (IIO) is to provide support +for devices that in some sense perform either +analog-to-digital conversion (ADC) or digital-to-analog conversion (DAC) +or both. The aim is to fill the gap between the somewhat similar hwmon and +:doc:`input <../input>` subsystems. Hwmon is directed at low sample rate +sensors used to monitor and control the system itself, like fan speed control +or temperature measurement. :doc:`Input <../input>` is, as its name suggests, +focused on human interaction input devices (keyboard, mouse, touchscreen). +In some cases there is considerable overlap between these and IIO. + +Devices that fall into this category include: + +* analog to digital converters (ADCs) +* accelerometers +* capacitance to digital converters (CDCs) +* digital to analog converters (DACs) +* gyroscopes +* inertial measurement units (IMUs) +* color and light sensors +* magnetometers +* pressure sensors +* proximity sensors +* temperature sensors + +Usually these sensors are connected via :doc:`SPI <../spi>` or +:doc:`I2C <../i2c>`. A common use case of the sensors devices is to have +combined functionality (e.g. light plus proximity sensor). diff --git a/Documentation/driver-api/iio/triggered-buffers.rst b/Documentation/driver-api/iio/triggered-buffers.rst new file mode 100644 index 000000000000..0db12660cc90 --- /dev/null +++ b/Documentation/driver-api/iio/triggered-buffers.rst @@ -0,0 +1,69 @@ +================= +Triggered Buffers +================= + +Now that we know what buffers and triggers are let's see how they work together. + +IIO triggered buffer setup +========================== + +* :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc +* :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by + :c:func:`iio_triggered_buffer_setup` +* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks + +A typical triggered buffer setup looks like this:: + + const struct iio_buffer_setup_ops sensor_buffer_setup_ops = { + .preenable = sensor_buffer_preenable, + .postenable = sensor_buffer_postenable, + .postdisable = sensor_buffer_postdisable, + .predisable = sensor_buffer_predisable, + }; + + irqreturn_t sensor_iio_pollfunc(int irq, void *p) + { + pf->timestamp = iio_get_time_ns((struct indio_dev *)p); + return IRQ_WAKE_THREAD; + } + + irqreturn_t sensor_trigger_handler(int irq, void *p) + { + u16 buf[8]; + int i = 0; + + /* read data for each active channel */ + for_each_set_bit(bit, active_scan_mask, masklength) + buf[i++] = sensor_get_data(bit) + + iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp); + + iio_trigger_notify_done(trigger); + return IRQ_HANDLED; + } + + /* setup triggered buffer, usually in probe function */ + iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc, + sensor_trigger_handler, + sensor_buffer_setup_ops); + +The important things to notice here are: + +* :c:type:`iio_buffer_setup_ops`, the buffer setup functions to be called at + predefined points in the buffer configuration sequence (e.g. before enable, + after disable). If not specified, the IIO core uses the default + iio_triggered_buffer_setup_ops. +* **sensor_iio_pollfunc**, the function that will be used as top half of poll + function. It should do as little processing as possible, because it runs in + interrupt context. The most common operation is recording of the current + timestamp and for this reason one can use the IIO core defined + :c:func:`iio_pollfunc_store_time` function. +* **sensor_trigger_handler**, the function that will be used as bottom half of + the poll function. This runs in the context of a kernel thread and all the + processing takes place here. It usually reads data from the device and + stores it in the internal buffer together with the timestamp recorded in the + top half. + +More details +============ +.. kernel-doc:: drivers/iio/buffer/industrialio-triggered-buffer.c diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst new file mode 100644 index 000000000000..f89d37e7dd82 --- /dev/null +++ b/Documentation/driver-api/iio/triggers.rst @@ -0,0 +1,80 @@ +======== +Triggers +======== + +* struct :c:type:`iio_trigger` — industrial I/O trigger device +* :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc +* :c:func:`devm_iio_trigger_free` — Resource-managed iio_trigger_free +* :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register +* :c:func:`devm_iio_trigger_unregister` — Resource-managed + iio_trigger_unregister +* :c:func:`iio_trigger_validate_own_device` — Check if a trigger and IIO + device belong to the same device + +In many situations it is useful for a driver to be able to capture data based +on some external event (trigger) as opposed to periodically polling for data. +An IIO trigger can be provided by a device driver that also has an IIO device +based on hardware generated events (e.g. data ready or threshold exceeded) or +provided by a separate driver from an independent interrupt source (e.g. GPIO +line connected to some external system, timer interrupt or user space writing +a specific file in sysfs). A trigger may initiate data capture for a number of +sensors and also it may be completely unrelated to the sensor itself. + +IIO trigger sysfs interface +=========================== + +There are two locations in sysfs related to triggers: + +* :file:`/sys/bus/iio/devices/trigger{Y}/*`, this file is created once an + IIO trigger is registered with the IIO core and corresponds to trigger + with index Y. + Because triggers can be very different depending on type there are few + standard attributes that we can describe here: + + * :file:`name`, trigger name that can be later used for association with a + device. + * :file:`sampling_frequency`, some timer based triggers use this attribute to + specify the frequency for trigger calls. + +* :file:`/sys/bus/iio/devices/iio:device{X}/trigger/*`, this directory is + created once the device supports a triggered buffer. We can associate a + trigger with our device by writing the trigger's name in the + :file:`current_trigger` file. + +IIO trigger setup +================= + +Let's see a simple example of how to setup a trigger to be used by a driver:: + + struct iio_trigger_ops trigger_ops = { + .set_trigger_state = sample_trigger_state, + .validate_device = sample_validate_device, + } + + struct iio_trigger *trig; + + /* first, allocate memory for our trigger */ + trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx); + + /* setup trigger operations field */ + trig->ops = &trigger_ops; + + /* now register the trigger with the IIO core */ + iio_trigger_register(trig); + +IIO trigger ops +=============== + +* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger. + +Notice that a trigger has a set of operations attached: + +* :file:`set_trigger_state`, switch the trigger on/off on demand. +* :file:`validate_device`, function to validate the device when the current + trigger gets changed. + +More details +============ +.. kernel-doc:: include/linux/iio/trigger.h +.. kernel-doc:: drivers/iio/industrialio-trigger.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 5475a2807e7a..60db00d1532b 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -16,11 +16,15 @@ available subsections can be seen below. basics infrastructure + pm/index + device-io dma-buf device_link message-based sound frame-buffer + regulator + iio/index input usb spi @@ -30,6 +34,8 @@ available subsections can be seen below. miscellaneous vme 80211/index + uio-howto + firmware/index .. only:: subproject and html diff --git a/Documentation/driver-api/pm/conf.py b/Documentation/driver-api/pm/conf.py new file mode 100644 index 000000000000..a89fac11272f --- /dev/null +++ b/Documentation/driver-api/pm/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Device Power Management" + +tags.add("subproject") + +latex_documents = [ + ('index', 'pm.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst new file mode 100644 index 000000000000..bedd32388dac --- /dev/null +++ b/Documentation/driver-api/pm/devices.rst @@ -0,0 +1,736 @@ +.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` +.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` +.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>` +.. |struct device_type| replace:: :c:type:`struct device_type <device_type>` +.. |struct class| replace:: :c:type:`struct class <class>` +.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>` +.. |struct device| replace:: :c:type:`struct device <device>` + +============================== +Device Power Management Basics +============================== + +:: + + Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. + Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> + Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +Most of the code in Linux is device drivers, so most of the Linux power +management (PM) code is also driver-specific. Most drivers will do very +little; others, especially for platforms with small batteries (like cell +phones), will do a lot. + +This writeup gives an overview of how drivers interact with system-wide +power management goals, emphasizing the models and interfaces that are +shared by everything that hooks up to the driver model core. Read it as +background for the domain-specific work you'd do with any specific driver. + + +Two Models for Device Power Management +====================================== + +Drivers will use one or both of these models to put devices into low-power +states: + + System Sleep model: + + Drivers can enter low-power states as part of entering system-wide + low-power states like "suspend" (also known as "suspend-to-RAM"), or + (mostly for systems with disks) "hibernation" (also known as + "suspend-to-disk"). + + This is something that device, bus, and class drivers collaborate on + by implementing various role-specific suspend and resume methods to + cleanly power down hardware and software subsystems, then reactivate + them without loss of data. + + Some drivers can manage hardware wakeup events, which make the system + leave the low-power state. This feature may be enabled or disabled + using the relevant :file:`/sys/devices/.../power/wakeup` file (for + Ethernet drivers the ioctl interface used by ethtool may also be used + for this purpose); enabling it may cost some power usage, but let the + whole system enter low-power states more often. + + Runtime Power Management model: + + Devices may also be put into low-power states while the system is + running, independently of other power management activity in principle. + However, devices are not generally independent of each other (for + example, a parent device cannot be suspended unless all of its child + devices have been suspended). Moreover, depending on the bus type the + device is on, it may be necessary to carry out some bus-specific + operations on the device for this purpose. Devices put into low power + states at run time may require special handling during system-wide power + transitions (suspend or hibernation). + + For these reasons not only the device driver itself, but also the + appropriate subsystem (bus type, device type or device class) driver and + the PM core are involved in runtime power management. As in the system + sleep power management case, they need to collaborate by implementing + various role-specific suspend and resume methods, so that the hardware + is cleanly powered down and reactivated without data or service loss. + +There's not a lot to be said about those low-power states except that they are +very system-specific, and often device-specific. Also, that if enough devices +have been put into low-power states (at runtime), the effect may be very similar +to entering some system-wide low-power state (system sleep) ... and that +synergies exist, so that several drivers using runtime PM might put the system +into a state where even deeper power saving options are available. + +Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except +for wakeup events), no more data read or written, and requests from upstream +drivers are no longer accepted. A given bus or platform may have different +requirements though. + +Examples of hardware wakeup events include an alarm from a real time clock, +network wake-on-LAN packets, keyboard or mouse activity, and media insertion +or removal (for PCMCIA, MMC/SD, USB, and so on). + +Interfaces for Entering System Sleep States +=========================================== + +There are programming interfaces provided for subsystems (bus type, device type, +device class) and device drivers to allow them to participate in the power +management of devices they are concerned with. These interfaces cover both +system sleep and runtime power management. + + +Device Power Management Operations +---------------------------------- + +Device power management operations, at the subsystem level as well as at the +device driver level, are implemented by defining and populating objects of type +|struct dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the +methods included in it will be explained in what follows. For now, it should be +sufficient to remember that the last three methods are specific to runtime power +management while the remaining ones are used during system-wide power +transitions. + +There also is a deprecated "old" or "legacy" interface for power management +operations available at least for some subsystems. This approach does not use +|struct dev_pm_ops| objects and it is suitable only for implementing system +sleep power management methods in a limited way. Therefore it is not described +in this document, so please refer directly to the source code for more +information about it. + + +Subsystem-Level Methods +----------------------- + +The core methods to suspend and resume devices reside in +|struct dev_pm_ops| pointed to by the :c:member:`ops` member of +|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|, +|struct device_type| and |struct class|. They are mostly of interest to the +people writing infrastructure for platforms and buses, like PCI or USB, or +device type and device class drivers. They also are relevant to the writers of +device drivers whose subsystems (PM domains, device types, device classes and +bus types) don't provide all power management methods. + +Bus drivers implement these methods as appropriate for the hardware and the +drivers using it; PCI works differently from USB, and so on. Not many people +write subsystem-level drivers; most driver code is a "device driver" that builds +on top of bus-specific framework code. + +For more information on these driver calls, see the description later; +they are called in phases for every device, respecting the parent-child +sequencing in the driver model tree. + + +:file:`/sys/devices/.../power/wakeup` files +------------------------------------------- + +All device objects in the driver model contain fields that control the handling +of system wakeup events (hardware signals that can force the system out of a +sleep state). These fields are initialized by bus or device driver code using +:c:func:`device_set_wakeup_capable()` and :c:func:`device_set_wakeup_enable()`, +defined in :file:`include/linux/pm_wakeup.h`. + +The :c:member:`power.can_wakeup` flag just records whether the device (and its +driver) can physically support wakeup events. The +:c:func:`device_set_wakeup_capable()` routine affects this flag. The +:c:member:`power.wakeup` field is a pointer to an object of type +|struct wakeup_source| used for controlling whether or not the device should use +its system wakeup mechanism and for notifying the PM core of system wakeup +events signaled by the device. This object is only present for wakeup-capable +devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created +(or removed) by :c:func:`device_set_wakeup_capable()`. + +Whether or not a device is capable of issuing wakeup events is a hardware +matter, and the kernel is responsible for keeping track of it. By contrast, +whether or not a wakeup-capable device should issue wakeup events is a policy +decision, and it is managed by user space through a sysfs attribute: the +:file:`power/wakeup` file. User space can write the "enabled" or "disabled" +strings to it to indicate whether or not, respectively, the device is supposed +to signal system wakeup. This file is only present if the +:c:member:`power.wakeup` object exists for the given device and is created (or +removed) along with that object, by :c:func:`device_set_wakeup_capable()`. +Reads from the file will return the corresponding string. + +The initial value in the :file:`power/wakeup` file is "disabled" for the +majority of devices; the major exceptions are power buttons, keyboards, and +Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool. +It should also default to "enabled" for devices that don't generate wakeup +requests on their own but merely forward wakeup requests from one bus to another +(like PCI Express ports). + +The :c:func:`device_may_wakeup()` routine returns true only if the +:c:member:`power.wakeup` object exists and the corresponding :file:`power/wakeup` +file contains the "enabled" string. This information is used by subsystems, +like the PCI bus type code, to see whether or not to enable the devices' wakeup +mechanisms. If device wakeup mechanisms are enabled or disabled directly by +drivers, they also should use :c:func:`device_may_wakeup()` to decide what to do +during a system sleep transition. Device drivers, however, are not expected to +call :c:func:`device_set_wakeup_enable()` directly in any case. + +It ought to be noted that system wakeup is conceptually different from "remote +wakeup" used by runtime power management, although it may be supported by the +same physical mechanism. Remote wakeup is a feature allowing devices in +low-power states to trigger specific interrupts to signal conditions in which +they should be put into the full-power state. Those interrupts may or may not +be used to signal system wakeup events, depending on the hardware design. On +some systems it is impossible to trigger them from system sleep states. In any +case, remote wakeup should always be enabled for runtime power management for +all devices and drivers that support it. + + +:file:`/sys/devices/.../power/control` files +-------------------------------------------- + +Each device in the driver model has a flag to control whether it is subject to +runtime power management. This flag, :c:member:`runtime_auto`, is initialized +by the bus type (or generally subsystem) code using :c:func:`pm_runtime_allow()` +or :c:func:`pm_runtime_forbid()`; the default is to allow runtime power +management. + +The setting can be adjusted by user space by writing either "on" or "auto" to +the device's :file:`power/control` sysfs file. Writing "auto" calls +:c:func:`pm_runtime_allow()`, setting the flag and allowing the device to be +runtime power-managed by its driver. Writing "on" calls +:c:func:`pm_runtime_forbid()`, clearing the flag, returning the device to full +power if it was in a low-power state, and preventing the +device from being runtime power-managed. User space can check the current value +of the :c:member:`runtime_auto` flag by reading that file. + +The device's :c:member:`runtime_auto` flag has no effect on the handling of +system-wide power transitions. In particular, the device can (and in the +majority of cases should and will) be put into a low-power state during a +system-wide transition to a sleep state even though its :c:member:`runtime_auto` +flag is clear. + +For more information about the runtime power management framework, refer to +:file:`Documentation/power/runtime_pm.txt`. + + +Calling Drivers to Enter and Leave System Sleep States +====================================================== + +When the system goes into a sleep state, each device's driver is asked to +suspend the device by putting it into a state compatible with the target +system state. That's usually some version of "off", but the details are +system-specific. Also, wakeup-enabled devices will usually stay partly +functional in order to wake the system. + +When the system leaves that low-power state, the device's driver is asked to +resume it by returning it to full power. The suspend and resume operations +always go together, and both are multi-phase operations. + +For simple drivers, suspend might quiesce the device using class code +and then turn its hardware as "off" as possible during suspend_noirq. The +matching resume calls would then completely reinitialize the hardware +before reactivating its class I/O queues. + +More power-aware drivers might prepare the devices for triggering system wakeup +events. + + +Call Sequence Guarantees +------------------------ + +To ensure that bridges and similar links needing to talk to a device are +available when the device is suspended or resumed, the device hierarchy is +walked in a bottom-up order to suspend devices. A top-down order is +used to resume those devices. + +The ordering of the device hierarchy is defined by the order in which devices +get registered: a child can never be registered, probed or resumed before +its parent; and can't be removed or suspended after that parent. + +The policy is that the device hierarchy should match hardware bus topology. +[Or at least the control bus, for devices which use multiple busses.] +In particular, this means that a device registration may fail if the parent of +the device is suspending (i.e. has been chosen by the PM core as the next +device to suspend) or has already suspended, as well as after all of the other +devices have been suspended. Device drivers must be prepared to cope with such +situations. + + +System Power Management Phases +------------------------------ + +Suspending or resuming the system is done in several phases. Different phases +are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM") +sleep states and the hibernation state ("suspend-to-disk"). Each phase involves +executing callbacks for every device before the next phase begins. Not all +buses or classes support all these callbacks and not all drivers use all the +callbacks. The various phases always run after tasks have been frozen and +before they are unfrozen. Furthermore, the ``*_noirq phases`` run at a time +when IRQ handlers have been disabled (except for those marked with the +IRQF_NO_SUSPEND flag). + +All phases use PM domain, bus, type, class or driver callbacks (that is, methods +defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``, +``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the +PM core as mutually exclusive. Moreover, PM domain callbacks always take +precedence over all of the other callbacks and, for example, type callbacks take +precedence over bus, class and driver callbacks. To be precise, the following +rules are used to determine which callback to execute in the given phase: + + 1. If ``dev->pm_domain`` is present, the PM core will choose the callback + provided by ``dev->pm_domain->ops`` for execution. + + 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the + callback provided by ``dev->type->pm`` will be chosen for execution. + + 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present, + the callback provided by ``dev->class->pm`` will be chosen for + execution. + + 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the + callback provided by ``dev->bus->pm`` will be chosen for execution. + +This allows PM domains and device types to override callbacks provided by bus +types or device classes if necessary. + +The PM domain, type, class and bus callbacks may in turn invoke device- or +driver-specific methods stored in ``dev->driver->pm``, but they don't have to do +that. + +If the subsystem callback chosen for execution is not present, the PM core will +execute the corresponding method from the ``dev->driver->pm`` set instead if +there is one. + + +Entering System Suspend +----------------------- + +When the system goes into the freeze, standby or memory sleep state, +the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``. + + 1. The ``prepare`` phase is meant to prevent races by preventing new + devices from being registered; the PM core would never know that all the + children of a device had been suspended if new children could be + registered at will. [By contrast, from the PM core's perspective, + devices may be unregistered at any time.] Unlike the other + suspend-related phases, during the ``prepare`` phase the device + hierarchy is traversed top-down. + + After the ``->prepare`` callback method returns, no new children may be + registered below the device. The method may also prepare the device or + driver in some way for the upcoming system power transition, but it + should not put the device into a low-power state. + + For devices supporting runtime power management, the return value of the + prepare callback can be used to indicate to the PM core that it may + safely leave the device in runtime suspend (if runtime-suspended + already), provided that all of the device's descendants are also left in + runtime suspend. Namely, if the prepare callback returns a positive + number and that happens for all of the descendants of the device too, + and all of them (including the device itself) are runtime-suspended, the + PM core will skip the ``suspend``, ``suspend_late`` and + ``suspend_noirq`` phases as well as all of the corresponding phases of + the subsequent device resume for all of these devices. In that case, + the ``->complete`` callback will be invoked directly after the + ``->prepare`` callback and is entirely responsible for putting the + device into a consistent state as appropriate. + + Note that this direct-complete procedure applies even if the device is + disabled for runtime PM; only the runtime-PM status matters. It follows + that if a device has system-sleep callbacks but does not support runtime + PM, then its prepare callback must never return a positive value. This + is because all such devices are initially set to runtime-suspended with + runtime PM disabled. + + 2. The ``->suspend`` methods should quiesce the device to stop it from + performing I/O. They also may save the device registers and put it into + the appropriate low-power state, depending on the bus type the device is + on, and they may enable wakeup events. + + 3. For a number of devices it is convenient to split suspend into the + "quiesce device" and "save device state" phases, in which cases + ``suspend_late`` is meant to do the latter. It is always executed after + runtime power management has been disabled for the device in question. + + 4. The ``suspend_noirq`` phase occurs after IRQ handlers have been disabled, + which means that the driver's interrupt handler will not be called while + the callback method is running. The ``->suspend_noirq`` methods should + save the values of the device's registers that weren't saved previously + and finally put the device into the appropriate low-power state. + + The majority of subsystems and device drivers need not implement this + callback. However, bus types allowing devices to share interrupt + vectors, like PCI, generally need it; otherwise a driver might encounter + an error during the suspend phase by fielding a shared interrupt + generated by some other device after its own device had been set to low + power. + +At the end of these phases, drivers should have stopped all I/O transactions +(DMA, IRQs), saved enough state that they can re-initialize or restore previous +state (as needed by the hardware), and placed the device into a low-power state. +On many platforms they will gate off one or more clock sources; sometimes they +will also switch off power supplies or reduce voltages. [Drivers supporting +runtime PM may already have performed some or all of these steps.] + +If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be +prepared for generating hardware wakeup signals to trigger a system wakeup event +when the system is in the sleep state. For example, :c:func:`enable_irq_wake()` +might identify GPIO signals hooked up to a switch or other external hardware, +and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal. + +If any of these callbacks returns an error, the system won't enter the desired +low-power state. Instead, the PM core will unwind its actions by resuming all +the devices that were suspended. + + +Leaving System Suspend +---------------------- + +When resuming from freeze, standby or memory sleep, the phases are: +``resume_noirq``, ``resume_early``, ``resume``, ``complete``. + + 1. The ``->resume_noirq`` callback methods should perform any actions + needed before the driver's interrupt handlers are invoked. This + generally means undoing the actions of the ``suspend_noirq`` phase. If + the bus type permits devices to share interrupt vectors, like PCI, the + method should bring the device and its driver into a state in which the + driver can recognize if the device is the source of incoming interrupts, + if any, and handle them correctly. + + For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device + into the full-power state (D0 in the PCI terminology) and restores the + standard configuration registers of the device. Then it calls the + device driver's ``->pm.resume_noirq()`` method to perform device-specific + actions. + + 2. The ``->resume_early`` methods should prepare devices for the execution + of the resume methods. This generally involves undoing the actions of + the preceding ``suspend_late`` phase. + + 3. The ``->resume`` methods should bring the device back to its operating + state, so that it can perform normal I/O. This generally involves + undoing the actions of the ``suspend`` phase. + + 4. The ``complete`` phase should undo the actions of the ``prepare`` phase. + For this reason, unlike the other resume-related phases, during the + ``complete`` phase the device hierarchy is traversed bottom-up. + + Note, however, that new children may be registered below the device as + soon as the ``->resume`` callbacks occur; it's not necessary to wait + until the ``complete`` phase with that. + + Moreover, if the preceding ``->prepare`` callback returned a positive + number, the device may have been left in runtime suspend throughout the + whole system suspend and resume (the ``suspend``, ``suspend_late``, + ``suspend_noirq`` phases of system suspend and the ``resume_noirq``, + ``resume_early``, ``resume`` phases of system resume may have been + skipped for it). In that case, the ``->complete`` callback is entirely + responsible for putting the device into a consistent state after system + suspend if necessary. [For example, it may need to queue up a runtime + resume request for the device for this purpose.] To check if that is + the case, the ``->complete`` callback can consult the device's + ``power.direct_complete`` flag. Namely, if that flag is set when the + ``->complete`` callback is being run, it has been called directly after + the preceding ``->prepare`` and special actions may be required + to make the device work correctly afterward. + +At the end of these phases, drivers should be as functional as they were before +suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are +gated on. + +However, the details here may again be platform-specific. For example, +some systems support multiple "run" states, and the mode in effect at +the end of resume might not be the one which preceded suspension. +That means availability of certain clocks or power supplies changed, +which could easily affect how a driver works. + +Drivers need to be able to handle hardware which has been reset since all of the +suspend methods were called, for example by complete reinitialization. +This may be the hardest part, and the one most protected by NDA'd documents +and chip errata. It's simplest if the hardware state hasn't changed since +the suspend was carried out, but that can only be guaranteed if the target +system sleep entered was suspend-to-idle. For the other system sleep states +that may not be the case (and usually isn't for ACPI-defined system sleep +states, like S3). + +Drivers must also be prepared to notice that the device has been removed +while the system was powered down, whenever that's physically possible. +PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses +where common Linux platforms will see such removal. Details of how drivers +will notice and handle such removals are currently bus-specific, and often +involve a separate thread. + +These callbacks may return an error value, but the PM core will ignore such +errors since there's nothing it can do about them other than printing them in +the system log. + + +Entering Hibernation +-------------------- + +Hibernating the system is more complicated than putting it into sleep states, +because it involves creating and saving a system image. Therefore there are +more phases for hibernation, with a different set of callbacks. These phases +always run after tasks have been frozen and enough memory has been freed. + +The general procedure for hibernation is to quiesce all devices ("freeze"), +create an image of the system memory while everything is stable, reactivate all +devices ("thaw"), write the image to permanent storage, and finally shut down +the system ("power off"). The phases used to accomplish this are: ``prepare``, +``freeze``, ``freeze_late``, ``freeze_noirq``, ``thaw_noirq``, ``thaw_early``, +``thaw``, ``complete``, ``prepare``, ``poweroff``, ``poweroff_late``, +``poweroff_noirq``. + + 1. The ``prepare`` phase is discussed in the "Entering System Suspend" + section above. + + 2. The ``->freeze`` methods should quiesce the device so that it doesn't + generate IRQs or DMA, and they may need to save the values of device + registers. However the device does not have to be put in a low-power + state, and to save time it's best not to do so. Also, the device should + not be prepared to generate wakeup events. + + 3. The ``freeze_late`` phase is analogous to the ``suspend_late`` phase + described earlier, except that the device should not be put into a + low-power state and should not be allowed to generate wakeup events. + + 4. The ``freeze_noirq`` phase is analogous to the ``suspend_noirq`` phase + discussed earlier, except again that the device should not be put into + a low-power state and should not be allowed to generate wakeup events. + +At this point the system image is created. All devices should be inactive and +the contents of memory should remain undisturbed while this happens, so that the +image forms an atomic snapshot of the system state. + + 5. The ``thaw_noirq`` phase is analogous to the ``resume_noirq`` phase + discussed earlier. The main difference is that its methods can assume + the device is in the same state as at the end of the ``freeze_noirq`` + phase. + + 6. The ``thaw_early`` phase is analogous to the ``resume_early`` phase + described above. Its methods should undo the actions of the preceding + ``freeze_late``, if necessary. + + 7. The ``thaw`` phase is analogous to the ``resume`` phase discussed + earlier. Its methods should bring the device back to an operating + state, so that it can be used for saving the image if necessary. + + 8. The ``complete`` phase is discussed in the "Leaving System Suspend" + section above. + +At this point the system image is saved, and the devices then need to be +prepared for the upcoming system shutdown. This is much like suspending them +before putting the system into the suspend-to-idle, shallow or deep sleep state, +and the phases are similar. + + 9. The ``prepare`` phase is discussed above. + + 10. The ``poweroff`` phase is analogous to the ``suspend`` phase. + + 11. The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase. + + 12. The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase. + +The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks +should do essentially the same things as the ``->suspend``, ``->suspend_late`` +and ``->suspend_noirq`` callbacks, respectively. The only notable difference is +that they need not store the device register values, because the registers +should already have been stored during the ``freeze``, ``freeze_late`` or +``freeze_noirq`` phases. + + +Leaving Hibernation +------------------- + +Resuming from hibernation is, again, more complicated than resuming from a sleep +state in which the contents of main memory are preserved, because it requires +a system image to be loaded into memory and the pre-hibernation memory contents +to be restored before control can be passed back to the image kernel. + +Although in principle the image might be loaded into memory and the +pre-hibernation memory contents restored by the boot loader, in practice this +can't be done because boot loaders aren't smart enough and there is no +established protocol for passing the necessary information. So instead, the +boot loader loads a fresh instance of the kernel, called "the restore kernel", +into memory and passes control to it in the usual way. Then the restore kernel +reads the system image, restores the pre-hibernation memory contents, and passes +control to the image kernel. Thus two different kernel instances are involved +in resuming from hibernation. In fact, the restore kernel may be completely +different from the image kernel: a different configuration and even a different +version. This has important consequences for device drivers and their +subsystems. + +To be able to load the system image into memory, the restore kernel needs to +include at least a subset of device drivers allowing it to access the storage +medium containing the image, although it doesn't need to include all of the +drivers present in the image kernel. After the image has been loaded, the +devices managed by the boot kernel need to be prepared for passing control back +to the image kernel. This is very similar to the initial steps involved in +creating a system image, and it is accomplished in the same way, using +``prepare``, ``freeze``, and ``freeze_noirq`` phases. However, the devices +affected by these phases are only those having drivers in the restore kernel; +other devices will still be in whatever state the boot loader left them. + +Should the restoration of the pre-hibernation memory contents fail, the restore +kernel would go through the "thawing" procedure described above, using the +``thaw_noirq``, ``thaw_early``, ``thaw``, and ``complete`` phases, and then +continue running normally. This happens only rarely. Most often the +pre-hibernation memory contents are restored successfully and control is passed +to the image kernel, which then becomes responsible for bringing the system back +to the working state. + +To achieve this, the image kernel must restore the devices' pre-hibernation +functionality. The operation is much like waking up from a sleep state (with +the memory contents preserved), although it involves different phases: +``restore_noirq``, ``restore_early``, ``restore``, ``complete``. + + 1. The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase. + + 2. The ``restore_early`` phase is analogous to the ``resume_early`` phase. + + 3. The ``restore`` phase is analogous to the ``resume`` phase. + + 4. The ``complete`` phase is discussed above. + +The main difference from ``resume[_early|_noirq]`` is that +``restore[_early|_noirq]`` must assume the device has been accessed and +reconfigured by the boot loader or the restore kernel. Consequently, the state +of the device may be different from the state remembered from the ``freeze``, +``freeze_late`` and ``freeze_noirq`` phases. The device may even need to be +reset and completely re-initialized. In many cases this difference doesn't +matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]`` +method pointers can be set to the same routines. Nevertheless, different +callback pointers are used in case there is a situation where it actually does +matter. + + +Power Management Notifiers +========================== + +There are some operations that cannot be carried out by the power management +callbacks discussed above, because the callbacks occur too late or too early. +To handle these cases, subsystems and device drivers may register power +management notifiers that are called before tasks are frozen and after they have +been thawed. Generally speaking, the PM notifiers are suitable for performing +actions that either require user space to be available, or at least won't +interfere with user space. + +For details refer to :doc:`notifiers`. + + +Device Low-Power (suspend) States +================================= + +Device low-power states aren't standard. One device might only handle +"on" and "off", while another might support a dozen different versions of +"on" (how many engines are active?), plus a state that gets back to "on" +faster than from a full "off". + +Some buses define rules about what different suspend states mean. PCI +gives one example: after the suspend sequence completes, a non-legacy +PCI device may not perform DMA or issue IRQs, and any wakeup events it +issues would be issued through the PME# bus signal. Plus, there are +several PCI-standard device states, some of which are optional. + +In contrast, integrated system-on-chip processors often use IRQs as the +wakeup event sources (so drivers would call :c:func:`enable_irq_wake`) and +might be able to treat DMA completion as a wakeup event (sometimes DMA can stay +active too, it'd only be the CPU and some peripherals that sleep). + +Some details here may be platform-specific. Systems may have devices that +can be fully active in certain sleep states, such as an LCD display that's +refreshed using DMA while most of the system is sleeping lightly ... and +its frame buffer might even be updated by a DSP or other non-Linux CPU while +the Linux control processor stays idle. + +Moreover, the specific actions taken may depend on the target system state. +One target system state might allow a given device to be very operational; +another might require a hard shut down with re-initialization on resume. +And two different target systems might use the same device in different +ways; the aforementioned LCD might be active in one product's "standby", +but a different product using the same SOC might work differently. + + +Device Power Management Domains +=============================== + +Sometimes devices share reference clocks or other power resources. In those +cases it generally is not possible to put devices into low-power states +individually. Instead, a set of devices sharing a power resource can be put +into a low-power state together at the same time by turning off the shared +power resource. Of course, they also need to be put into the full-power state +together, by turning the shared power resource on. A set of devices with this +property is often referred to as a power domain. A power domain may also be +nested inside another power domain. The nested domain is referred to as the +sub-domain of the parent domain. + +Support for power domains is provided through the :c:member:`pm_domain` field of +|struct device|. This field is a pointer to an object of type +|struct dev_pm_domain|, defined in :file:`include/linux/pm.h``, providing a set +of power management callbacks analogous to the subsystem-level and device driver +callbacks that are executed for the given device during all power transitions, +instead of the respective subsystem-level callbacks. Specifically, if a +device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback +from the object pointed to by it will be executed instead of its subsystem's +(e.g. bus type's) ``->suspend()`` callback and analogously for all of the +remaining callbacks. In other words, power management domain callbacks, if +defined for the given device, always take precedence over the callbacks provided +by the device's subsystem (e.g. bus type). + +The support for device power management domains is only relevant to platforms +needing to use the same device driver power management callbacks in many +different power domain configurations and wanting to avoid incorporating the +support for power domains into subsystem-level callbacks, for example by +modifying the platform bus type. Other platforms need not implement it or take +it into account in any way. + +Devices may be defined as IRQ-safe which indicates to the PM core that their +runtime PM callbacks may be invoked with disabled interrupts (see +:file:`Documentation/power/runtime_pm.txt` for more information). If an +IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be +disallowed, unless the domain itself is defined as IRQ-safe. However, it +makes sense to define a PM domain as IRQ-safe only if all the devices in it +are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime +PM of the parent is only allowed if the parent itself is IRQ-safe too with the +additional restriction that all child domains of an IRQ-safe parent must also +be IRQ-safe. + + +Runtime Power Management +======================== + +Many devices are able to dynamically power down while the system is still +running. This feature is useful for devices that are not being used, and +can offer significant power savings on a running system. These devices +often support a range of runtime power states, which might use names such +as "off", "sleep", "idle", "active", and so on. Those states will in some +cases (like PCI) be partially constrained by the bus the device uses, and will +usually include hardware states that are also used in system sleep states. + +A system-wide power transition can be started while some devices are in low +power states due to runtime power management. The system sleep PM callbacks +should recognize such situations and react to them appropriately, but the +necessary actions are subsystem-specific. + +In some cases the decision may be made at the subsystem level while in other +cases the device driver may be left to decide. In some cases it may be +desirable to leave a suspended device in that state during a system-wide power +transition, but in other cases the device must be put back into the full-power +state temporarily, for example so that its system wakeup capability can be +disabled. This all depends on the hardware and the design of the subsystem and +device driver in question. + +During system-wide resume from a sleep state it's easiest to put devices into +the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`. +Refer to that document for more information regarding this particular issue as +well as for information on the device runtime power management framework in +general. diff --git a/Documentation/driver-api/pm/index.rst b/Documentation/driver-api/pm/index.rst new file mode 100644 index 000000000000..2f6d0e9cf6b7 --- /dev/null +++ b/Documentation/driver-api/pm/index.rst @@ -0,0 +1,16 @@ +======================= +Device Power Management +======================= + +.. toctree:: + + devices + notifiers + types + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/driver-api/pm/notifiers.rst b/Documentation/driver-api/pm/notifiers.rst new file mode 100644 index 000000000000..62f860026992 --- /dev/null +++ b/Documentation/driver-api/pm/notifiers.rst @@ -0,0 +1,70 @@ +============================= +Suspend/Hibernation Notifiers +============================= + +:: + + Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +There are some operations that subsystems or drivers may want to carry out +before hibernation/suspend or after restore/resume, but they require the system +to be fully functional, so the drivers' and subsystems' ``->suspend()`` and +``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not +suitable for this purpose. + +For example, device drivers may want to upload firmware to their devices after +resume/restore, but they cannot do it by calling :c:func:`request_firmware()` +from their ``->resume()`` or ``->complete()`` callback routines (user land +processes are frozen at these points). The solution may be to load the firmware +into memory before processes are frozen and upload it from there in the +``->resume()`` routine. A suspend/hibernation notifier may be used for that. + +Subsystems or drivers having such needs can register suspend notifiers that +will be called upon the following events by the PM core: + +``PM_HIBERNATION_PREPARE`` + The system is going to hibernate, tasks will be frozen immediately. This + is different from ``PM_SUSPEND_PREPARE`` below, because in this case + additional work is done between the notifiers and the invocation of PM + callbacks for the "freeze" transition. + +``PM_POST_HIBERNATION`` + The system memory state has been restored from a hibernation image or an + error occurred during hibernation. Device restore callbacks have been + executed and tasks have been thawed. + +``PM_RESTORE_PREPARE`` + The system is going to restore a hibernation image. If all goes well, + the restored image kernel will issue a ``PM_POST_HIBERNATION`` + notification. + +``PM_POST_RESTORE`` + An error occurred during restore from hibernation. Device restore + callbacks have been executed and tasks have been thawed. + +``PM_SUSPEND_PREPARE`` + The system is preparing for suspend. + +``PM_POST_SUSPEND`` + The system has just resumed or an error occurred during suspend. Device + resume callbacks have been executed and tasks have been thawed. + +It is generally assumed that whatever the notifiers do for +``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``. +Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be +reversed for ``PM_POST_SUSPEND``. + +Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or +``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that +event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``, +respectively. + +The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held. +They are defined in the usual way, but their last argument is meaningless (it is +always NULL). + +To register and/or unregister a suspend notifier use +:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`, +respectively (both defined in :file:`include/linux/suspend.h`). If you don't +need to unregister the notifier, you can also use the :c:func:`pm_notifier()` +macro defined in :file:`include/linux/suspend.h`. diff --git a/Documentation/driver-api/pm/types.rst b/Documentation/driver-api/pm/types.rst new file mode 100644 index 000000000000..3ebdecc54104 --- /dev/null +++ b/Documentation/driver-api/pm/types.rst @@ -0,0 +1,5 @@ +================================== +Device Power Management Data Types +================================== + +.. kernel-doc:: include/linux/pm.h diff --git a/Documentation/driver-api/regulator.rst b/Documentation/driver-api/regulator.rst new file mode 100644 index 000000000000..520da0a5251d --- /dev/null +++ b/Documentation/driver-api/regulator.rst @@ -0,0 +1,170 @@ +.. Copyright 2007-2008 Wolfson Microelectronics + +.. 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. + +================================= +Voltage and current regulator API +================================= + +:Author: Liam Girdwood +:Author: Mark Brown + +Introduction +============ + +This framework is designed to provide a standard kernel interface to +control voltage and current regulators. + +The intention is to allow systems to dynamically control regulator power +output in order to save power and prolong battery life. This applies to +both voltage regulators (where voltage output is controllable) and +current sinks (where current limit is controllable). + +Note that additional (and currently more complete) documentation is +available in the Linux kernel source under +``Documentation/power/regulator``. + +Glossary +-------- + +The regulator API uses a number of terms which may not be familiar: + +Regulator + + Electronic device that supplies power to other devices. Most regulators + can enable and disable their output and some can also control their + output voltage or current. + +Consumer + + Electronic device which consumes power provided by a regulator. These + may either be static, requiring only a fixed supply, or dynamic, + requiring active management of the regulator at runtime. + +Power Domain + + The electronic circuit supplied by a given regulator, including the + regulator and all consumer devices. The configuration of the regulator + is shared between all the components in the circuit. + +Power Management Integrated Circuit (PMIC) + + An IC which contains numerous regulators and often also other + subsystems. In an embedded system the primary PMIC is often equivalent + to a combination of the PSU and southbridge in a desktop system. + +Consumer driver interface +========================= + +This offers a similar API to the kernel clock framework. Consumer +drivers use `get <#API-regulator-get>`__ and +`put <#API-regulator-put>`__ operations to acquire and release +regulators. Functions are provided to `enable <#API-regulator-enable>`__ +and `disable <#API-regulator-disable>`__ the regulator and to get and +set the runtime parameters of the regulator. + +When requesting regulators consumers use symbolic names for their +supplies, such as "Vcc", which are mapped into actual regulator devices +by the machine interface. + +A stub version of this API is provided when the regulator framework is +not in use in order to minimise the need to use ifdefs. + +Enabling and disabling +---------------------- + +The regulator API provides reference counted enabling and disabling of +regulators. Consumer devices use the :c:func:`regulator_enable()` and +:c:func:`regulator_disable()` functions to enable and disable +regulators. Calls to the two functions must be balanced. + +Note that since multiple consumers may be using a regulator and machine +constraints may not allow the regulator to be disabled there is no +guarantee that calling :c:func:`regulator_disable()` will actually +cause the supply provided by the regulator to be disabled. Consumer +drivers should assume that the regulator may be enabled at all times. + +Configuration +------------- + +Some consumer devices may need to be able to dynamically configure their +supplies. For example, MMC drivers may need to select the correct +operating voltage for their cards. This may be done while the regulator +is enabled or disabled. + +The :c:func:`regulator_set_voltage()` and +:c:func:`regulator_set_current_limit()` functions provide the primary +interface for this. Both take ranges of voltages and currents, supporting +drivers that do not require a specific value (eg, CPU frequency scaling +normally permits the CPU to use a wider range of supply voltages at lower +frequencies but does not require that the supply voltage be lowered). Where +an exact value is required both minimum and maximum values should be +identical. + +Callbacks +--------- + +Callbacks may also be registered for events such as regulation failures. + +Regulator driver interface +========================== + +Drivers for regulator chips register the regulators with the regulator +core, providing operations structures to the core. A notifier interface +allows error conditions to be reported to the core. + +Registration should be triggered by explicit setup done by the platform, +supplying a struct :c:type:`regulator_init_data` for the regulator +containing constraint and supply information. + +Machine interface +================= + +This interface provides a way to define how regulators are connected to +consumers on a given system and what the valid operating parameters are +for the system. + +Supplies +-------- + +Regulator supplies are specified using struct +:c:type:`regulator_consumer_supply`. This is done at driver registration +time as part of the machine constraints. + +Constraints +----------- + +As well as defining the connections the machine interface also provides +constraints defining the operations that clients are allowed to perform +and the parameters that may be set. This is required since generally +regulator devices will offer more flexibility than it is safe to use on +a given system, for example supporting higher supply voltages than the +consumers are rated for. + +This is done at driver registration time` by providing a +struct :c:type:`regulation_constraints`. + +The constraints may also specify an initial configuration for the +regulator in the constraints, which is particularly useful for use with +static consumers. + +API reference +============= + +Due to limitations of the kernel documentation framework and the +existing layout of the source code the entire regulator API is +documented here. + +.. kernel-doc:: include/linux/regulator/consumer.h + :internal: + +.. kernel-doc:: include/linux/regulator/machine.h + :internal: + +.. kernel-doc:: include/linux/regulator/driver.h + :internal: + +.. kernel-doc:: drivers/regulator/core.c + :export: diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst new file mode 100644 index 000000000000..f73d660b2956 --- /dev/null +++ b/Documentation/driver-api/uio-howto.rst @@ -0,0 +1,705 @@ +======================= +The Userspace I/O HOWTO +======================= + +:Author: Hans-Jürgen Koch Linux developer, Linutronix +:Date: 2006-12-11 + +About this document +=================== + +Translations +------------ + +If you know of any translations for this document, or you are interested +in translating it, please email me hjk@hansjkoch.de. + +Preface +------- + +For many types of devices, creating a Linux kernel driver is overkill. +All that is really needed is some way to handle an interrupt and provide +access to the memory space of the device. The logic of controlling the +device does not necessarily have to be within the kernel, as the device +does not need to take advantage of any of other resources that the +kernel provides. One such common class of devices that are like this are +for industrial I/O cards. + +To address this situation, the userspace I/O system (UIO) was designed. +For typical industrial I/O cards, only a very small kernel module is +needed. The main part of the driver will run in user space. This +simplifies development and reduces the risk of serious bugs within a +kernel module. + +Please note that UIO is not an universal driver interface. Devices that +are already handled well by other kernel subsystems (like networking or +serial or USB) are no candidates for an UIO driver. Hardware that is +ideally suited for an UIO driver fulfills all of the following: + +- The device has memory that can be mapped. The device can be + controlled completely by writing to this memory. + +- The device usually generates interrupts. + +- The device does not fit into one of the standard kernel subsystems. + +Acknowledgments +--------------- + +I'd like to thank Thomas Gleixner and Benedikt Spranger of Linutronix, +who have not only written most of the UIO code, but also helped greatly +writing this HOWTO by giving me all kinds of background information. + +Feedback +-------- + +Find something wrong with this document? (Or perhaps something right?) I +would love to hear from you. Please email me at hjk@hansjkoch.de. + +About UIO +========= + +If you use UIO for your card's driver, here's what you get: + +- only one small kernel module to write and maintain. + +- develop the main part of your driver in user space, with all the + tools and libraries you're used to. + +- bugs in your driver won't crash the kernel. + +- updates of your driver can take place without recompiling the kernel. + +How UIO works +------------- + +Each UIO device is accessed through a device file and several sysfs +attribute files. The device file will be called ``/dev/uio0`` for the +first device, and ``/dev/uio1``, ``/dev/uio2`` and so on for subsequent +devices. + +``/dev/uioX`` is used to access the address space of the card. Just use +:c:func:`mmap()` to access registers or RAM locations of your card. + +Interrupts are handled by reading from ``/dev/uioX``. A blocking +:c:func:`read()` from ``/dev/uioX`` will return as soon as an +interrupt occurs. You can also use :c:func:`select()` on +``/dev/uioX`` to wait for an interrupt. The integer value read from +``/dev/uioX`` represents the total interrupt count. You can use this +number to figure out if you missed some interrupts. + +For some hardware that has more than one interrupt source internally, +but not separate IRQ mask and status registers, there might be +situations where userspace cannot determine what the interrupt source +was if the kernel handler disables them by writing to the chip's IRQ +register. In such a case, the kernel has to disable the IRQ completely +to leave the chip's register untouched. Now the userspace part can +determine the cause of the interrupt, but it cannot re-enable +interrupts. Another cornercase is chips where re-enabling interrupts is +a read-modify-write operation to a combined IRQ status/acknowledge +register. This would be racy if a new interrupt occurred simultaneously. + +To address these problems, UIO also implements a write() function. It is +normally not used and can be ignored for hardware that has only a single +interrupt source or has separate IRQ mask and status registers. If you +need it, however, a write to ``/dev/uioX`` will call the +:c:func:`irqcontrol()` function implemented by the driver. You have +to write a 32-bit value that is usually either 0 or 1 to disable or +enable interrupts. If a driver does not implement +:c:func:`irqcontrol()`, :c:func:`write()` will return with +``-ENOSYS``. + +To handle interrupts properly, your custom kernel module can provide its +own interrupt handler. It will automatically be called by the built-in +handler. + +For cards that don't generate interrupts but need to be polled, there is +the possibility to set up a timer that triggers the interrupt handler at +configurable time intervals. This interrupt simulation is done by +calling :c:func:`uio_event_notify()` from the timer's event +handler. + +Each driver provides attributes that are used to read or write +variables. These attributes are accessible through sysfs files. A custom +kernel driver module can add its own attributes to the device owned by +the uio driver, but not added to the UIO device itself at this time. +This might change in the future if it would be found to be useful. + +The following standard attributes are provided by the UIO framework: + +- ``name``: The name of your device. It is recommended to use the name + of your kernel module for this. + +- ``version``: A version string defined by your driver. This allows the + user space part of your driver to deal with different versions of the + kernel module. + +- ``event``: The total number of interrupts handled by the driver since + the last time the device node was read. + +These attributes appear under the ``/sys/class/uio/uioX`` directory. +Please note that this directory might be a symlink, and not a real +directory. Any userspace code that accesses it must be able to handle +this. + +Each UIO device can make one or more memory regions available for memory +mapping. This is necessary because some industrial I/O cards require +access to more than one PCI memory region in a driver. + +Each mapping has its own directory in sysfs, the first mapping appears +as ``/sys/class/uio/uioX/maps/map0/``. Subsequent mappings create +directories ``map1/``, ``map2/``, and so on. These directories will only +appear if the size of the mapping is not 0. + +Each ``mapX/`` directory contains four read-only files that show +attributes of the memory: + +- ``name``: A string identifier for this mapping. This is optional, the + string can be empty. Drivers can set this to make it easier for + userspace to find the correct mapping. + +- ``addr``: The address of memory that can be mapped. + +- ``size``: The size, in bytes, of the memory pointed to by addr. + +- ``offset``: The offset, in bytes, that has to be added to the pointer + returned by :c:func:`mmap()` to get to the actual device memory. + This is important if the device's memory is not page aligned. + Remember that pointers returned by :c:func:`mmap()` are always + page aligned, so it is good style to always add this offset. + +From userspace, the different mappings are distinguished by adjusting +the ``offset`` parameter of the :c:func:`mmap()` call. To map the +memory of mapping N, you have to use N times the page size as your +offset:: + + offset = N * getpagesize(); + +Sometimes there is hardware with memory-like regions that can not be +mapped with the technique described here, but there are still ways to +access them from userspace. The most common example are x86 ioports. On +x86 systems, userspace can access these ioports using +:c:func:`ioperm()`, :c:func:`iopl()`, :c:func:`inb()`, +:c:func:`outb()`, and similar functions. + +Since these ioport regions can not be mapped, they will not appear under +``/sys/class/uio/uioX/maps/`` like the normal memory described above. +Without information about the port regions a hardware has to offer, it +becomes difficult for the userspace part of the driver to find out which +ports belong to which UIO device. + +To address this situation, the new directory +``/sys/class/uio/uioX/portio/`` was added. It only exists if the driver +wants to pass information about one or more port regions to userspace. +If that is the case, subdirectories named ``port0``, ``port1``, and so +on, will appear underneath ``/sys/class/uio/uioX/portio/``. + +Each ``portX/`` directory contains four read-only files that show name, +start, size, and type of the port region: + +- ``name``: A string identifier for this port region. The string is + optional and can be empty. Drivers can set it to make it easier for + userspace to find a certain port region. + +- ``start``: The first port of this region. + +- ``size``: The number of ports in this region. + +- ``porttype``: A string describing the type of port. + +Writing your own kernel module +============================== + +Please have a look at ``uio_cif.c`` as an example. The following +paragraphs explain the different sections of this file. + +struct uio_info +--------------- + +This structure tells the framework the details of your driver, Some of +the members are required, others are optional. + +- ``const char *name``: Required. The name of your driver as it will + appear in sysfs. I recommend using the name of your module for this. + +- ``const char *version``: Required. This string appears in + ``/sys/class/uio/uioX/version``. + +- ``struct uio_mem mem[ MAX_UIO_MAPS ]``: Required if you have memory + that can be mapped with :c:func:`mmap()`. For each mapping you + need to fill one of the ``uio_mem`` structures. See the description + below for details. + +- ``struct uio_port port[ MAX_UIO_PORTS_REGIONS ]``: Required if you + want to pass information about ioports to userspace. For each port + region you need to fill one of the ``uio_port`` structures. See the + description below for details. + +- ``long irq``: Required. If your hardware generates an interrupt, it's + your modules task to determine the irq number during initialization. + If you don't have a hardware generated interrupt but want to trigger + the interrupt handler in some other way, set ``irq`` to + ``UIO_IRQ_CUSTOM``. If you had no interrupt at all, you could set + ``irq`` to ``UIO_IRQ_NONE``, though this rarely makes sense. + +- ``unsigned long irq_flags``: Required if you've set ``irq`` to a + hardware interrupt number. The flags given here will be used in the + call to :c:func:`request_irq()`. + +- ``int (*mmap)(struct uio_info *info, struct vm_area_struct *vma)``: + Optional. If you need a special :c:func:`mmap()` + function, you can set it here. If this pointer is not NULL, your + :c:func:`mmap()` will be called instead of the built-in one. + +- ``int (*open)(struct uio_info *info, struct inode *inode)``: + Optional. You might want to have your own :c:func:`open()`, + e.g. to enable interrupts only when your device is actually used. + +- ``int (*release)(struct uio_info *info, struct inode *inode)``: + Optional. If you define your own :c:func:`open()`, you will + probably also want a custom :c:func:`release()` function. + +- ``int (*irqcontrol)(struct uio_info *info, s32 irq_on)``: + Optional. If you need to be able to enable or disable interrupts + from userspace by writing to ``/dev/uioX``, you can implement this + function. The parameter ``irq_on`` will be 0 to disable interrupts + and 1 to enable them. + +Usually, your device will have one or more memory regions that can be +mapped to user space. For each region, you have to set up a +``struct uio_mem`` in the ``mem[]`` array. Here's a description of the +fields of ``struct uio_mem``: + +- ``const char *name``: Optional. Set this to help identify the memory + region, it will show up in the corresponding sysfs node. + +- ``int memtype``: Required if the mapping is used. Set this to + ``UIO_MEM_PHYS`` if you you have physical memory on your card to be + mapped. Use ``UIO_MEM_LOGICAL`` for logical memory (e.g. allocated + with :c:func:`kmalloc()`). There's also ``UIO_MEM_VIRTUAL`` for + virtual memory. + +- ``phys_addr_t addr``: Required if the mapping is used. Fill in the + address of your memory block. This address is the one that appears in + sysfs. + +- ``resource_size_t size``: Fill in the size of the memory block that + ``addr`` points to. If ``size`` is zero, the mapping is considered + unused. Note that you *must* initialize ``size`` with zero for all + unused mappings. + +- ``void *internal_addr``: If you have to access this memory region + from within your kernel module, you will want to map it internally by + using something like :c:func:`ioremap()`. Addresses returned by + this function cannot be mapped to user space, so you must not store + it in ``addr``. Use ``internal_addr`` instead to remember such an + address. + +Please do not touch the ``map`` element of ``struct uio_mem``! It is +used by the UIO framework to set up sysfs files for this mapping. Simply +leave it alone. + +Sometimes, your device can have one or more port regions which can not +be mapped to userspace. But if there are other possibilities for +userspace to access these ports, it makes sense to make information +about the ports available in sysfs. For each region, you have to set up +a ``struct uio_port`` in the ``port[]`` array. Here's a description of +the fields of ``struct uio_port``: + +- ``char *porttype``: Required. Set this to one of the predefined + constants. Use ``UIO_PORT_X86`` for the ioports found in x86 + architectures. + +- ``unsigned long start``: Required if the port region is used. Fill in + the number of the first port of this region. + +- ``unsigned long size``: Fill in the number of ports in this region. + If ``size`` is zero, the region is considered unused. Note that you + *must* initialize ``size`` with zero for all unused regions. + +Please do not touch the ``portio`` element of ``struct uio_port``! It is +used internally by the UIO framework to set up sysfs files for this +region. Simply leave it alone. + +Adding an interrupt handler +--------------------------- + +What you need to do in your interrupt handler depends on your hardware +and on how you want to handle it. You should try to keep the amount of +code in your kernel interrupt handler low. If your hardware requires no +action that you *have* to perform after each interrupt, then your +handler can be empty. + +If, on the other hand, your hardware *needs* some action to be performed +after each interrupt, then you *must* do it in your kernel module. Note +that you cannot rely on the userspace part of your driver. Your +userspace program can terminate at any time, possibly leaving your +hardware in a state where proper interrupt handling is still required. + +There might also be applications where you want to read data from your +hardware at each interrupt and buffer it in a piece of kernel memory +you've allocated for that purpose. With this technique you could avoid +loss of data if your userspace program misses an interrupt. + +A note on shared interrupts: Your driver should support interrupt +sharing whenever this is possible. It is possible if and only if your +driver can detect whether your hardware has triggered the interrupt or +not. This is usually done by looking at an interrupt status register. If +your driver sees that the IRQ bit is actually set, it will perform its +actions, and the handler returns IRQ_HANDLED. If the driver detects +that it was not your hardware that caused the interrupt, it will do +nothing and return IRQ_NONE, allowing the kernel to call the next +possible interrupt handler. + +If you decide not to support shared interrupts, your card won't work in +computers with no free interrupts. As this frequently happens on the PC +platform, you can save yourself a lot of trouble by supporting interrupt +sharing. + +Using uio_pdrv for platform devices +----------------------------------- + +In many cases, UIO drivers for platform devices can be handled in a +generic way. In the same place where you define your +``struct platform_device``, you simply also implement your interrupt +handler and fill your ``struct uio_info``. A pointer to this +``struct uio_info`` is then used as ``platform_data`` for your platform +device. + +You also need to set up an array of ``struct resource`` containing +addresses and sizes of your memory mappings. This information is passed +to the driver using the ``.resource`` and ``.num_resources`` elements of +``struct platform_device``. + +You now have to set the ``.name`` element of ``struct platform_device`` +to ``"uio_pdrv"`` to use the generic UIO platform device driver. This +driver will fill the ``mem[]`` array according to the resources given, +and register the device. + +The advantage of this approach is that you only have to edit a file you +need to edit anyway. You do not have to create an extra driver. + +Using uio_pdrv_genirq for platform devices +------------------------------------------ + +Especially in embedded devices, you frequently find chips where the irq +pin is tied to its own dedicated interrupt line. In such cases, where +you can be really sure the interrupt is not shared, we can take the +concept of ``uio_pdrv`` one step further and use a generic interrupt +handler. That's what ``uio_pdrv_genirq`` does. + +The setup for this driver is the same as described above for +``uio_pdrv``, except that you do not implement an interrupt handler. The +``.handler`` element of ``struct uio_info`` must remain ``NULL``. The +``.irq_flags`` element must not contain ``IRQF_SHARED``. + +You will set the ``.name`` element of ``struct platform_device`` to +``"uio_pdrv_genirq"`` to use this driver. + +The generic interrupt handler of ``uio_pdrv_genirq`` will simply disable +the interrupt line using :c:func:`disable_irq_nosync()`. After +doing its work, userspace can reenable the interrupt by writing +0x00000001 to the UIO device file. The driver already implements an +:c:func:`irq_control()` to make this possible, you must not +implement your own. + +Using ``uio_pdrv_genirq`` not only saves a few lines of interrupt +handler code. You also do not need to know anything about the chip's +internal registers to create the kernel part of the driver. All you need +to know is the irq number of the pin the chip is connected to. + +Using uio_dmem_genirq for platform devices +------------------------------------------ + +In addition to statically allocated memory ranges, they may also be a +desire to use dynamically allocated regions in a user space driver. In +particular, being able to access memory made available through the +dma-mapping API, may be particularly useful. The ``uio_dmem_genirq`` +driver provides a way to accomplish this. + +This driver is used in a similar manner to the ``"uio_pdrv_genirq"`` +driver with respect to interrupt configuration and handling. + +Set the ``.name`` element of ``struct platform_device`` to +``"uio_dmem_genirq"`` to use this driver. + +When using this driver, fill in the ``.platform_data`` element of +``struct platform_device``, which is of type +``struct uio_dmem_genirq_pdata`` and which contains the following +elements: + +- ``struct uio_info uioinfo``: The same structure used as the + ``uio_pdrv_genirq`` platform data + +- ``unsigned int *dynamic_region_sizes``: Pointer to list of sizes of + dynamic memory regions to be mapped into user space. + +- ``unsigned int num_dynamic_regions``: Number of elements in + ``dynamic_region_sizes`` array. + +The dynamic regions defined in the platform data will be appended to the +`` mem[] `` array after the platform device resources, which implies +that the total number of static and dynamic memory regions cannot exceed +``MAX_UIO_MAPS``. + +The dynamic memory regions will be allocated when the UIO device file, +``/dev/uioX`` is opened. Similar to static memory resources, the memory +region information for dynamic regions is then visible via sysfs at +``/sys/class/uio/uioX/maps/mapY/*``. The dynamic memory regions will be +freed when the UIO device file is closed. When no processes are holding +the device file open, the address returned to userspace is ~0. + +Writing a driver in userspace +============================= + +Once you have a working kernel module for your hardware, you can write +the userspace part of your driver. You don't need any special libraries, +your driver can be written in any reasonable language, you can use +floating point numbers and so on. In short, you can use all the tools +and libraries you'd normally use for writing a userspace application. + +Getting information about your UIO device +----------------------------------------- + +Information about all UIO devices is available in sysfs. The first thing +you should do in your driver is check ``name`` and ``version`` to make +sure your talking to the right device and that its kernel driver has the +version you expect. + +You should also make sure that the memory mapping you need exists and +has the size you expect. + +There is a tool called ``lsuio`` that lists UIO devices and their +attributes. It is available here: + +http://www.osadl.org/projects/downloads/UIO/user/ + +With ``lsuio`` you can quickly check if your kernel module is loaded and +which attributes it exports. Have a look at the manpage for details. + +The source code of ``lsuio`` can serve as an example for getting +information about an UIO device. The file ``uio_helper.c`` contains a +lot of functions you could use in your userspace driver code. + +mmap() device memory +-------------------- + +After you made sure you've got the right device with the memory mappings +you need, all you have to do is to call :c:func:`mmap()` to map the +device's memory to userspace. + +The parameter ``offset`` of the :c:func:`mmap()` call has a special +meaning for UIO devices: It is used to select which mapping of your +device you want to map. To map the memory of mapping N, you have to use +N times the page size as your offset:: + + offset = N * getpagesize(); + +N starts from zero, so if you've got only one memory range to map, set +``offset = 0``. A drawback of this technique is that memory is always +mapped beginning with its start address. + +Waiting for interrupts +---------------------- + +After you successfully mapped your devices memory, you can access it +like an ordinary array. Usually, you will perform some initialization. +After that, your hardware starts working and will generate an interrupt +as soon as it's finished, has some data available, or needs your +attention because an error occurred. + +``/dev/uioX`` is a read-only file. A :c:func:`read()` will always +block until an interrupt occurs. There is only one legal value for the +``count`` parameter of :c:func:`read()`, and that is the size of a +signed 32 bit integer (4). Any other value for ``count`` causes +:c:func:`read()` to fail. The signed 32 bit integer read is the +interrupt count of your device. If the value is one more than the value +you read the last time, everything is OK. If the difference is greater +than one, you missed interrupts. + +You can also use :c:func:`select()` on ``/dev/uioX``. + +Generic PCI UIO driver +====================== + +The generic driver is a kernel module named uio_pci_generic. It can +work with any device compliant to PCI 2.3 (circa 2002) and any compliant +PCI Express device. Using this, you only need to write the userspace +driver, removing the need to write a hardware-specific kernel module. + +Making the driver recognize the device +-------------------------------------- + +Since the driver does not declare any device ids, it will not get loaded +automatically and will not automatically bind to any devices, you must +load it and allocate id to the driver yourself. For example:: + + modprobe uio_pci_generic + echo "8086 10f5" > /sys/bus/pci/drivers/uio_pci_generic/new_id + +If there already is a hardware specific kernel driver for your device, +the generic driver still won't bind to it, in this case if you want to +use the generic driver (why would you?) you'll have to manually unbind +the hardware specific driver and bind the generic driver, like this:: + + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/e1000e/unbind + echo -n 0000:00:19.0 > /sys/bus/pci/drivers/uio_pci_generic/bind + +You can verify that the device has been bound to the driver by looking +for it in sysfs, for example like the following:: + + ls -l /sys/bus/pci/devices/0000:00:19.0/driver + +Which if successful should print:: + + .../0000:00:19.0/driver -> ../../../bus/pci/drivers/uio_pci_generic + +Note that the generic driver will not bind to old PCI 2.2 devices. If +binding the device failed, run the following command:: + + dmesg + +and look in the output for failure reasons. + +Things to know about uio_pci_generic +------------------------------------ + +Interrupts are handled using the Interrupt Disable bit in the PCI +command register and Interrupt Status bit in the PCI status register. +All devices compliant to PCI 2.3 (circa 2002) and all compliant PCI +Express devices should support these bits. uio_pci_generic detects +this support, and won't bind to devices which do not support the +Interrupt Disable Bit in the command register. + +On each interrupt, uio_pci_generic sets the Interrupt Disable bit. +This prevents the device from generating further interrupts until the +bit is cleared. The userspace driver should clear this bit before +blocking and waiting for more interrupts. + +Writing userspace driver using uio_pci_generic +------------------------------------------------ + +Userspace driver can use pci sysfs interface, or the libpci library that +wraps it, to talk to the device and to re-enable interrupts by writing +to the command register. + +Example code using uio_pci_generic +---------------------------------- + +Here is some sample userspace driver code using uio_pci_generic:: + + #include <stdlib.h> + #include <stdio.h> + #include <unistd.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <errno.h> + + int main() + { + int uiofd; + int configfd; + int err; + int i; + unsigned icount; + unsigned char command_high; + + uiofd = open("/dev/uio0", O_RDONLY); + if (uiofd < 0) { + perror("uio open:"); + return errno; + } + configfd = open("/sys/class/uio/uio0/device/config", O_RDWR); + if (configfd < 0) { + perror("config open:"); + return errno; + } + + /* Read and cache command value */ + err = pread(configfd, &command_high, 1, 5); + if (err != 1) { + perror("command config read:"); + return errno; + } + command_high &= ~0x4; + + for(i = 0;; ++i) { + /* Print out a message, for debugging. */ + if (i == 0) + fprintf(stderr, "Started uio test driver.\n"); + else + fprintf(stderr, "Interrupts: %d\n", icount); + + /****************************************/ + /* Here we got an interrupt from the + device. Do something to it. */ + /****************************************/ + + /* Re-enable interrupts. */ + err = pwrite(configfd, &command_high, 1, 5); + if (err != 1) { + perror("config write:"); + break; + } + + /* Wait for next interrupt. */ + err = read(uiofd, &icount, 4); + if (err != 4) { + perror("uio read:"); + break; + } + + } + return errno; + } + +Generic Hyper-V UIO driver +========================== + +The generic driver is a kernel module named uio_hv_generic. It +supports devices on the Hyper-V VMBus similar to uio_pci_generic on +PCI bus. + +Making the driver recognize the device +-------------------------------------- + +Since the driver does not declare any device GUID's, it will not get +loaded automatically and will not automatically bind to any devices, you +must load it and allocate id to the driver yourself. For example, to use +the network device GUID:: + + modprobe uio_hv_generic + echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id + +If there already is a hardware specific kernel driver for the device, +the generic driver still won't bind to it, in this case if you want to +use the generic driver (why would you?) you'll have to manually unbind +the hardware specific driver and bind the generic driver, like this:: + + echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind + echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind + +You can verify that the device has been bound to the driver by looking +for it in sysfs, for example like the following:: + + ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver + +Which if successful should print:: + + .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic + +Things to know about uio_hv_generic +----------------------------------- + +On each interrupt, uio_hv_generic sets the Interrupt Disable bit. This +prevents the device from generating further interrupts until the bit is +cleared. The userspace driver should clear this bit before blocking and +waiting for more interrupts. + +Further information +=================== + +- `OSADL homepage. <http://www.osadl.org>`_ + +- `Linutronix homepage. <http://www.linutronix.de>`_ diff --git a/Documentation/extcon/intel-int3496.txt b/Documentation/extcon/intel-int3496.txt new file mode 100644 index 000000000000..af0b366c25b7 --- /dev/null +++ b/Documentation/extcon/intel-int3496.txt @@ -0,0 +1,22 @@ +Intel INT3496 ACPI device extcon driver documentation +----------------------------------------------------- + +The Intel INT3496 ACPI device extcon driver is a driver for ACPI +devices with an acpi-id of INT3496, such as found for example on +Intel Baytrail and Cherrytrail tablets. + +This ACPI device describes how the OS can read the id-pin of the devices' +USB-otg port, as well as how it optionally can enable Vbus output on the +otg port and how it can optionally control the muxing of the data pins +between an USB host and an USB peripheral controller. + +The ACPI devices exposes this functionality by returning an array with up +to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call: + +Index 0: The input gpio for the id-pin, this is always present and valid +Index 1: The output gpio for enabling Vbus output from the device to the otg + port, write 1 to enable the Vbus output (this gpio descriptor may + be absent or invalid) +Index 2: The output gpio for muxing of the data pins between the USB host and + the USB peripheral controller, write 1 to mux to the peripheral + controller diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index ace63cd7af8c..fdcfdd79682a 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -58,7 +58,8 @@ prototypes: int (*permission) (struct inode *, int, unsigned int); int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *); + int (*getattr) (const struct path *, struct dentry *, struct kstat *, + u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); void (*update_time)(struct inode *, struct timespec *, int); diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt index ffef91c4e0d6..060da408923b 100644 --- a/Documentation/filesystems/afs.txt +++ b/Documentation/filesystems/afs.txt @@ -64,8 +64,7 @@ USAGE When inserting the driver modules the root cell must be specified along with a list of volume location server IP addresses: - modprobe af_rxrpc - modprobe rxkad + modprobe rxrpc modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 The first module is the AF_RXRPC network protocol driver. This provides the @@ -214,34 +213,3 @@ If a file is opened with a particular key and then the file descriptor is passed to a process that doesn't have that key (perhaps over an AF_UNIX socket), then the operations on the file will be made with key that was used to open the file. - - -======== -EXAMPLES -======== - -Here's what I use to test this. Some of the names and IP addresses are local -to my internal DNS. My "root.afs" partition has a mount point within it for -some public volumes volumes. - -insmod /tmp/rxrpc.o -insmod /tmp/rxkad.o -insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91 - -mount -t afs \%root.afs. /afs -mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ - -echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells -mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ -mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive -mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib -mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc -mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project -mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service -mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software -mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user - -umount /afs -rmmod kafs -rmmod rxkad -rmmod rxrpc diff --git a/Documentation/filesystems/autofs4-mount-control.txt b/Documentation/filesystems/autofs4-mount-control.txt index 50a3e01a36f8..e5177cb31a04 100644 --- a/Documentation/filesystems/autofs4-mount-control.txt +++ b/Documentation/filesystems/autofs4-mount-control.txt @@ -179,6 +179,7 @@ struct autofs_dev_ioctl { * including this struct */ __s32 ioctlfd; /* automount command fd */ + /* Command parameters */ union { struct args_protover protover; struct args_protosubver protosubver; diff --git a/Documentation/filesystems/autofs4.txt b/Documentation/filesystems/autofs4.txt index 8fac3fe7b8c9..f10dd590f69f 100644 --- a/Documentation/filesystems/autofs4.txt +++ b/Documentation/filesystems/autofs4.txt @@ -65,7 +65,7 @@ directory is a mount trap only if the filesystem is mounted *direct* and the root is empty. Directories created in the root directory are mount traps only if the -filesystem is mounted *indirect* and they are empty. +filesystem is mounted *indirect* and they are empty. Directories further down the tree depend on the *maxproto* mount option and particularly whether it is less than five or not. @@ -352,7 +352,7 @@ Communicating with autofs: root directory ioctls ------------------------------------------------ The root directory of an autofs filesystem will respond to a number of -ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN +ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN capability, or must be the automount daemon. The available ioctl commands are: @@ -425,8 +425,20 @@ Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: * including this struct */ __s32 ioctlfd; /* automount command fd */ - __u32 arg1; /* Command parameters */ - __u32 arg2; + /* Command parameters */ + 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]; }; @@ -446,25 +458,22 @@ Commands are: set version numbers. - **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: return an open file descriptor on the root of an autofs filesystem. The filesystem is identified - by name and device number, which is stored in `arg1`. Device - numbers for existing filesystems can be found in + by name and device number, which is stored in `openmount.devid`. + Device 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 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 + in `setpipefd.pipefd` to re-establish communication with a daemon. + The process group of the calling process is used to identify the daemon. - **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a name within the filesystem that has been auto-mounted on. - arg1 is the dev number of the underlying autofs. On successful - return, `arg1` and `arg2` will be the UID and GID of the process - which triggered that mount. - + On successful return, `requester.uid` and `requester.gid` will be + the UID and GID of the process which triggered that mount. - **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a mountpoint of a particular type - see separate documentation for details. - - **AUTOFS_DEV_IOCTL_PROTOVER_CMD**: - **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**: - **AUTOFS_DEV_IOCTL_READY_CMD**: @@ -474,7 +483,7 @@ Commands are: - **AUTOFS_DEV_IOCTL_EXPIRE_CMD**: - **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**: These all have the same function as the similarly named **AUTOFS_IOC** ioctls, except - that **FAIL** can be given an explicit error number in `arg1` + that **FAIL** can be given an explicit error number in `fail.status` instead of assuming `ENOENT`, and this **EXPIRE** command corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. @@ -512,7 +521,7 @@ always be mounted "shared". e.g. > `mount --make-shared /autofs/mount/point` -The automount daemon is only able to mange a single mount location for +The automount daemon is only able to manage a single mount location for an autofs filesystem and if mounts on that are not 'shared', other locations will not behave as expected. In particular access to those other locations will likely result in the `ELOOP` error diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt index f5306ee40ea9..0b302a11718a 100644 --- a/Documentation/filesystems/ceph.txt +++ b/Documentation/filesystems/ceph.txt @@ -98,11 +98,10 @@ Mount Options size. rsize=X - Specify the maximum read size in bytes. By default there is no - maximum. + Specify the maximum read size in bytes. Default: 64 MB. rasize=X - Specify the maximum readahead. + Specify the maximum readahead. Default: 8 MB. mount_timeout=X Specify the timeout value for mount (in seconds), in the case diff --git a/Documentation/filesystems/f2fs.txt b/Documentation/filesystems/f2fs.txt index 753dd4f96afe..4f6531a4701b 100644 --- a/Documentation/filesystems/f2fs.txt +++ b/Documentation/filesystems/f2fs.txt @@ -125,13 +125,14 @@ active_logs=%u Support configuring the number of active logs. In the disable_ext_identify Disable the extension list configured by mkfs, so f2fs does not aware of cold files such as media files. inline_xattr Enable the inline xattrs feature. +noinline_xattr Disable the inline xattrs feature. inline_data Enable the inline data feature: New created small(<~3.4k) files can be written into inode block. 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. +noinline_dentry Disable 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, @@ -157,6 +158,8 @@ data_flush Enable data flushing before checkpoint in order to mode=%s Control block allocation mode which supports "adaptive" and "lfs". In "lfs" mode, there should be no random writes towards main area. +io_bits=%u Set the bit size of write IO requests. It should be set + with "mode=lfs". ================================================================================ DEBUGFS ENTRIES @@ -174,7 +177,7 @@ f2fs. Each file shows the whole f2fs information. SYSFS ENTRIES ================================================================================ -Information about mounted f2f2 file systems can be found in +Information about mounted f2fs file systems can be found in /sys/fs/f2fs. Each mounted filesystem will have a directory in /sys/fs/f2fs based on its device name (i.e., /sys/fs/f2fs/sda). The files in each per-device directory are shown in table below. diff --git a/Documentation/filesystems/quota.txt b/Documentation/filesystems/quota.txt index 29fc01552646..32874b06ebe9 100644 --- a/Documentation/filesystems/quota.txt +++ b/Documentation/filesystems/quota.txt @@ -6,7 +6,7 @@ Quota subsystem allows system administrator to set limits on used space and number of used inodes (inode is a filesystem structure which is associated with each file or directory) for users and/or groups. For both used space and number of used inodes there are actually two limits. The first one is called softlimit -and the second one hardlimit. An user can never exceed a hardlimit for any +and the second one hardlimit. A user can never exceed a hardlimit for any resource (unless he has CAP_SYS_RESOURCE capability). User is allowed to exceed softlimit but only for limited period of time. This period is called "grace period" or "grace time". When grace time is over, user is not able to allocate diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index b968084eeac1..569211703721 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -382,7 +382,8 @@ struct inode_operations { int (*permission) (struct inode *, int); int (*get_acl)(struct inode *, int); int (*setattr) (struct dentry *, struct iattr *); - int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *); + int (*getattr) (const struct path *, struct dentry *, struct kstat *, + u32, unsigned int); ssize_t (*listxattr) (struct dentry *, char *, size_t); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, diff --git a/Documentation/firmware_class/README b/Documentation/firmware_class/README deleted file mode 100644 index cafdca8b3b15..000000000000 --- a/Documentation/firmware_class/README +++ /dev/null @@ -1,128 +0,0 @@ - - request_firmware() hotplug interface: - ------------------------------------ - Copyright (C) 2003 Manuel Estrada Sainz - - Why: - --- - - Today, the most extended way to use firmware in the Linux kernel is linking - it statically in a header file. Which has political and technical issues: - - 1) Some firmware is not legal to redistribute. - 2) The firmware occupies memory permanently, even though it often is just - used once. - 3) Some people, like the Debian crowd, don't consider some firmware free - enough and remove entire drivers (e.g.: keyspan). - - High level behavior (mixed): - ============================ - - 1), kernel(driver): - - calls request_firmware(&fw_entry, $FIRMWARE, device) - - kernel searches the firmware image with name $FIRMWARE directly - in the below search path of root filesystem: - User customized search path by module parameter 'path'[1] - "/lib/firmware/updates/" UTS_RELEASE, - "/lib/firmware/updates", - "/lib/firmware/" UTS_RELEASE, - "/lib/firmware" - - If found, goto 7), else goto 2) - - [1], the 'path' is a string parameter which length should be less - than 256, user should pass 'firmware_class.path=$CUSTOMIZED_PATH' - if firmware_class is built in kernel(the general situation) - - 2), userspace: - - /sys/class/firmware/xxx/{loading,data} appear. - - hotplug gets called with a firmware identifier in $FIRMWARE - and the usual hotplug environment. - - hotplug: echo 1 > /sys/class/firmware/xxx/loading - - 3), kernel: Discard any previous partial load. - - 4), userspace: - - hotplug: cat appropriate_firmware_image > \ - /sys/class/firmware/xxx/data - - 5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it - comes in. - - 6), userspace: - - hotplug: echo 0 > /sys/class/firmware/xxx/loading - - 7), kernel: request_firmware() returns and the driver has the firmware - image in fw_entry->{data,size}. If something went wrong - request_firmware() returns non-zero and fw_entry is set to - NULL. - - 8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing - the firmware image and any related resource. - - High level behavior (driver code): - ================================== - - if(request_firmware(&fw_entry, $FIRMWARE, device) == 0) - copy_fw_to_device(fw_entry->data, fw_entry->size); - release_firmware(fw_entry); - - Sample/simple hotplug script: - ============================ - - # Both $DEVPATH and $FIRMWARE are already provided in the environment. - - HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/ - - echo 1 > /sys/$DEVPATH/loading - cat $HOTPLUG_FW_DIR/$FIRMWARE > /sys/$DEVPATH/data - echo 0 > /sys/$DEVPATH/loading - - Random notes: - ============ - - - "echo -1 > /sys/class/firmware/xxx/loading" will cancel the load at - once and make request_firmware() return with error. - - - firmware_data_read() and firmware_loading_show() are just provided - for testing and completeness, they are not called in normal use. - - - There is also /sys/class/firmware/timeout which holds a timeout in - seconds for the whole load operation. - - - request_firmware_nowait() is also provided for convenience in - user contexts to request firmware asynchronously, but can't be called - in atomic contexts. - - - about in-kernel persistence: - --------------------------- - Under some circumstances, as explained below, it would be interesting to keep - firmware images in non-swappable kernel memory or even in the kernel image - (probably within initramfs). - - Note that this functionality has not been implemented. - - - Why OPTIONAL in-kernel persistence may be a good idea sometimes: - - - If the device that needs the firmware is needed to access the - filesystem. When upon some error the device has to be reset and the - firmware reloaded, it won't be possible to get it from userspace. - e.g.: - - A diskless client with a network card that needs firmware. - - The filesystem is stored in a disk behind an scsi device - that needs firmware. - - Replacing buggy DSDT/SSDT ACPI tables on boot. - Note: this would require the persistent objects to be included - within the kernel image, probably within initramfs. - - And the same device can be needed to access the filesystem or not depending - on the setup, so I think that the choice on what firmware to make - persistent should be left to userspace. - - about firmware cache: - -------------------- - After firmware cache mechanism is introduced during system sleep, - request_firmware can be called safely inside device's suspend and - resume callback, and callers needn't cache the firmware by - themselves any more for dealing with firmware loss during system - resume. diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt index 86ee5078fd03..78f197fadfd1 100644 --- a/Documentation/fpga/fpga-mgr.txt +++ b/Documentation/fpga/fpga-mgr.txt @@ -22,7 +22,16 @@ To program the FPGA from a file or from a buffer: struct fpga_image_info *info, const char *buf, size_t count); -Load the FPGA from an image which exists as a buffer in memory. +Load the FPGA from an image which exists as a contiguous buffer in +memory. Allocating contiguous kernel memory for the buffer should be avoided, +users are encouraged to use the _sg interface instead of this. + + int fpga_mgr_buf_load_sg(struct fpga_manager *mgr, + struct fpga_image_info *info, + struct sg_table *sgt); + +Load the FPGA from an image from non-contiguous in memory. Callers can +construct a sg_table using alloc_page backed memory. int fpga_mgr_firmware_load(struct fpga_manager *mgr, struct fpga_image_info *info, @@ -166,7 +175,7 @@ success or negative error codes otherwise. The programming sequence is: 1. .write_init - 2. .write (may be called once or multiple times) + 2. .write or .write_sg (may be called once or multiple times) 3. .write_complete The .write_init function will prepare the FPGA to receive the image data. The @@ -176,7 +185,11 @@ buffer up at least this much before starting. The .write function writes a buffer to the FPGA. The buffer may be contain the whole FPGA image or may be a smaller chunk of an FPGA image. In the latter -case, this function is called multiple times for successive chunks. +case, this function is called multiple times for successive chunks. This interface +is suitable for drivers which use PIO. + +The .write_sg version behaves the same as .write except the input is a sg_table +scatter list. This interface is suitable for drivers which use DMA. The .write_complete function is called after all the image has been written to put the FPGA into operating mode. diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index ad8f0c0cd13f..fc1d2f83564d 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -41,34 +41,71 @@ In the gpiolib framework each GPIO controller is packaged as a "struct gpio_chip" (see linux/gpio/driver.h for its complete definition) with members common to each controller of that type: - - methods to establish GPIO direction - - methods used to access GPIO values - - method to return the IRQ number associated to a given GPIO + - methods to establish GPIO line direction + - methods used to access GPIO line values + - method to set electrical configuration to a a given GPIO line + - method to return the IRQ number associated to a given GPIO line - flag saying whether calls to its methods may sleep + - optional line names array to identify lines - optional debugfs dump method (showing extra state like pullup config) - optional base number (will be automatically assigned if omitted) - - label for diagnostics and GPIOs mapping using platform data + - optional label for diagnostics and GPIO chip mapping using platform data The code implementing a gpio_chip should support multiple instances of the controller, possibly using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be rare; -use gpiochip_remove() when it is unavoidable. +gpio_chip and issue gpiochip_add[_data]() or devm_gpiochip_add_data(). +Removing a GPIO controller should be rare; use [devm_]gpiochip_remove() when +it is unavoidable. -Most often a gpio_chip is part of an instance-specific structure with state not +Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. -Chips such as codecs will have complex non-GPIO state. +Chips such as audio codecs will have complex non-GPIO states. Any debugfs dump method should normally ignore signals which haven't been requested as GPIOs. They can use gpiochip_is_requested(), which returns either NULL or the label associated with that GPIO when it was requested. -RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs +RT_FULL: the GPIO driver should not use spinlock_t or any sleepable APIs (like PM runtime) in its gpio_chip implementation (.get/.set and direction control callbacks) if it is expected to call GPIO APIs from atomic context on -RT (inside hard IRQ handlers and similar contexts). Normally this should not be required. +GPIO electrical configuration +----------------------------- + +GPIOs can be configured for several electrical modes of operation by using the +.set_config() callback. Currently this API supports setting debouncing and +single-ended modes (open drain/open source). These settings are described +below. + +The .set_config() callback uses the same enumerators and configuration +semantics as the generic pin control drivers. This is not a coincidence: it is +possible to assign the .set_config() to the function gpiochip_generic_config() +which will result in pinctrl_gpio_set_config() being called and eventually +ending up in the pin control back-end "behind" the GPIO controller, usually +closer to the actual pins. This way the pin controller can manage the below +listed GPIO configurations. + + +GPIOs with debounce support +--------------------------- + +Debouncing is a configuration set to a pin indicating that it is connected to +a mechanical switch or button, or similar that may bounce. Bouncing means the +line is pulled high/low quickly at very short intervals for mechanical +reasons. This can result in the value being unstable or irqs fireing repeatedly +unless the line is debounced. + +Debouncing in practice involves setting up a timer when something happens on +the line, wait a little while and then sample the line again, so see if it +still has the same value (low or high). This could also be repeated by a clever +state machine, waiting for a line to become stable. In either case, it sets +a certain number of milliseconds for debouncing, or just "on/off" if that time +is not configurable. + + GPIOs with open drain/source support ------------------------------------ diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 0c9abdc0ee31..4d4068855ec4 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -48,11 +48,17 @@ CRTC Abstraction ================ .. kernel-doc:: drivers/gpu/drm/drm_crtc.c - :export: + :doc: overview + +CRTC Functions Reference +-------------------------------- .. kernel-doc:: include/drm/drm_crtc.h :internal: +.. kernel-doc:: drivers/gpu/drm/drm_crtc.c + :export: + Frame Buffer Abstraction ======================== diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index cb5daffcd6be..f5760b140f13 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -34,25 +34,26 @@ TTM initialization ------------------ **Warning** - This section is outdated. -Drivers wishing to support TTM must fill out a drm_bo_driver -structure. The structure contains several fields with function pointers -for initializing the TTM, allocating and freeing memory, waiting for -command completion and fence synchronization, and memory migration. See -the radeon_ttm.c file for an example of usage. +Drivers wishing to support TTM must pass a filled :c:type:`ttm_bo_driver +<ttm_bo_driver>` structure to ttm_bo_device_init, together with an +initialized global reference to the memory manager. The ttm_bo_driver +structure contains several fields with function pointers for +initializing the TTM, allocating and freeing memory, waiting for command +completion and fence synchronization, and memory migration. -The ttm_global_reference structure is made up of several fields: +The :c:type:`struct drm_global_reference <drm_global_reference>` is made +up of several fields: .. code-block:: c - struct ttm_global_reference { + struct drm_global_reference { enum ttm_global_types global_type; size_t size; void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); + int (*init) (struct drm_global_reference *); + void (*release) (struct drm_global_reference *); }; @@ -76,6 +77,12 @@ ttm_bo_global_release(), respectively. Also, like the previous object, ttm_global_item_ref() is used to create an initial reference count for the TTM, which will call your initialization function. +See the radeon_ttm.c file for an example of usage. + +.. kernel-doc:: drivers/gpu/drm/drm_global.c + :export: + + The Graphics Execution Manager (GEM) ==================================== @@ -284,10 +291,17 @@ To use :c:func:`drm_gem_mmap()`, drivers must fill the struct :c:type:`struct drm_driver <drm_driver>` gem_vm_ops field with a pointer to VM operations. -struct vm_operations_struct \*gem_vm_ops struct -vm_operations_struct { void (\*open)(struct vm_area_struct \* area); -void (\*close)(struct vm_area_struct \* area); int (\*fault)(struct -vm_area_struct \*vma, struct vm_fault \*vmf); }; +The VM operations is a :c:type:`struct vm_operations_struct <vm_operations_struct>` +made up of several fields, the more interesting ones being: + +.. code-block:: c + + struct vm_operations_struct { + void (*open)(struct vm_area_struct * area); + void (*close)(struct vm_area_struct * area); + int (*fault)(struct vm_fault *vmf); + }; + The open and close operations must update the GEM object reference count. Drivers can use the :c:func:`drm_gem_vm_open()` and @@ -303,6 +317,17 @@ created. Drivers that want to map the GEM object upfront instead of handling page faults can implement their own mmap file operation handler. +For platforms without MMU the GEM core provides a helper method +:c:func:`drm_gem_cma_get_unmapped_area`. The mmap() routines will call +this to get a proposed address for the mapping. + +To use :c:func:`drm_gem_cma_get_unmapped_area`, drivers must fill the +struct :c:type:`struct file_operations <file_operations>` get_unmapped_area +field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`. + +More detailed information about get_unmapped_area can be found in +Documentation/nommu-mmap.txt + Memory Coherency ---------------- @@ -442,7 +467,7 @@ LRU Scan/Eviction Support ------------------------- .. kernel-doc:: drivers/gpu/drm/drm_mm.c - :doc: lru scan roaster + :doc: lru scan roster DRM MM Range Allocator Function References ------------------------------------------ @@ -452,3 +477,9 @@ DRM MM Range Allocator Function References .. kernel-doc:: include/drm/drm_mm.h :internal: + +DRM Cache Handling +================== + +.. kernel-doc:: drivers/gpu/drm/drm_cache.c + :export: diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index de3ac9f90f8f..fcc228ef5bc4 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -156,8 +156,12 @@ 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. + +Testing and validation +====================== + 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 @@ -193,6 +197,12 @@ 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. +Display CRC Support +------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c + :doc: CRC ABI + VBlank event handling ===================== @@ -209,16 +219,3 @@ DRM_IOCTL_MODESET_CTL mode setting, since on many devices the vertical blank counter is reset to 0 at some point during modeset. Modern drivers should not call this any more since with kernel mode setting it is a no-op. - -This second part of the GPU Driver Developer's Guide documents driver -code, implementation details and also all the driver-specific userspace -interfaces. Especially since all hardware-acceleration interfaces to -userspace are driver specific for efficiency and other reasons these -interfaces can be rather substantial. Hence every driver has its own -chapter. - -Testing and validation -====================== - -.. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c - :doc: CRC ABI diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst index 117d2ab7a5f7..b0d6709b8600 100644 --- a/Documentation/gpu/i915.rst +++ b/Documentation/gpu/i915.rst @@ -144,6 +144,15 @@ High Definition Audio .. kernel-doc:: include/drm/i915_component.h :internal: +Intel HDMI LPE Audio Support +---------------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c + :doc: LPE Audio integration for HDMI or DP playback + +.. kernel-doc:: drivers/gpu/drm/i915/intel_lpe_audio.c + :internal: + Panel Self Refresh PSR (PSR/SRD) -------------------------------- @@ -213,6 +222,18 @@ Video BIOS Table (VBT) .. kernel-doc:: drivers/gpu/drm/i915/intel_vbt_defs.h :internal: +Display PLLs +------------ + +.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c + :doc: Display PLLs + +.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.c + :internal: + +.. kernel-doc:: drivers/gpu/drm/i915/intel_dpll_mgr.h + :internal: + Memory Management and Command Submission ======================================== @@ -356,4 +377,95 @@ switch_mm .. kernel-doc:: drivers/gpu/drm/i915/i915_trace.h :doc: switch_mm tracepoint +Perf +==== + +Overview +-------- +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :doc: i915 Perf Overview + +Comparison with Core Perf +------------------------- +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :doc: i915 Perf History and Comparison with Core Perf + +i915 Driver Entry Points +------------------------ + +This section covers the entrypoints exported outside of i915_perf.c to +integrate with drm/i915 and to handle the `DRM_I915_PERF_OPEN` ioctl. + +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_init +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_fini +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_register +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_unregister +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_open_ioctl +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_release + +i915 Perf Stream +---------------- + +This section covers the stream-semantics-agnostic structures and functions +for representing an i915 perf stream FD and associated file operations. + +.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h + :functions: i915_perf_stream +.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h + :functions: i915_perf_stream_ops + +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: read_properties_unlocked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_open_ioctl_locked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_destroy_locked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_read +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_ioctl +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_enable_locked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_disable_locked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_poll +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_perf_poll_locked + +i915 Perf Observation Architecture Stream +----------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/i915/i915_drv.h + :functions: i915_oa_ops + +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_stream_init +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_read +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_stream_enable +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_stream_disable +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_wait_unlocked +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :functions: i915_oa_poll_wait + +All i915 Perf Internals +----------------------- + +This section simply includes all currently documented i915 perf internals, in +no particular order, but may include some more minor utilities or platform +specific details than found in the more high-level sections. + +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c + :internal: + .. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index 367d7c36b8e9..f81278a7c2cc 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -11,6 +11,7 @@ Linux GPU Driver Developer's Guide drm-kms-helpers drm-uapi i915 + tinydrm vga-switcheroo vgaarbiter diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index 1903595b5310..eb284eb748ba 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -23,13 +23,12 @@ For consistency this documentation uses American English. Abbreviations are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so on. To aid in reading, documentations make full use of the markup characters kerneldoc provides: @parameter for function parameters, -@member for structure members, &structure to reference structures and -function() for functions. These all get automatically hyperlinked if -kerneldoc for the referenced objects exists. When referencing entries in -function vtables please use ->vfunc(). Note that kerneldoc does not -support referencing struct members directly, so please add a reference -to the vtable struct somewhere in the same paragraph or at least -section. +@member for structure members (within the same structure), &struct structure to +reference structures and function() for functions. These all get automatically +hyperlinked if kerneldoc for the referenced objects exists. When referencing +entries in function vtables (and structure members in general) please use +&vtable_name.vfunc. Unfortunately this does not yet yield a direct link to the +member, only the structure. Except in special situations (to separate locked from unlocked variants) locking requirements for functions aren't documented in the kerneldoc. @@ -49,3 +48,5 @@ section name should be all upper-case or not, and whether it should end in a colon or not. Go with the file-local style. Other common section names are "Notes" with information for dangerous or tricky corner cases, and "FIXME" where the interface could be cleaned up. + +Also read the :ref:`guidelines for the kernel documentation at large <doc_guide>`. diff --git a/Documentation/gpu/tinydrm.rst b/Documentation/gpu/tinydrm.rst new file mode 100644 index 000000000000..a913644bfc19 --- /dev/null +++ b/Documentation/gpu/tinydrm.rst @@ -0,0 +1,42 @@ +========================== +drm/tinydrm Driver library +========================== + +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c + :doc: overview + +Core functionality +================== + +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c + :doc: core + +.. kernel-doc:: include/drm/tinydrm/tinydrm.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-core.c + :export: + +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-pipe.c + :export: + +Additional helpers +================== + +.. kernel-doc:: include/drm/tinydrm/tinydrm-helpers.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/tinydrm/core/tinydrm-helpers.c + :export: + +MIPI DBI Compatible Controllers +=============================== + +.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c + :doc: overview + +.. kernel-doc:: include/drm/tinydrm/mipi-dbi.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/tinydrm/mipi-dbi.c + :export: diff --git a/Documentation/hwmon/ds1621 b/Documentation/hwmon/ds1621 index f775e612f582..fa3407997795 100644 --- a/Documentation/hwmon/ds1621 +++ b/Documentation/hwmon/ds1621 @@ -117,10 +117,10 @@ support, which is achieved via the R0 and R1 config register bits, where: R0..R1 ------ - 0 0 => 9 bits, 0.5 degrees Celcius - 1 0 => 10 bits, 0.25 degrees Celcius - 0 1 => 11 bits, 0.125 degrees Celcius - 1 1 => 12 bits, 0.0625 degrees Celcius + 0 0 => 9 bits, 0.5 degrees Celsius + 1 0 => 10 bits, 0.25 degrees Celsius + 0 1 => 11 bits, 0.125 degrees Celsius + 1 1 => 12 bits, 0.0625 degrees Celsius Note: At initial device power-on, the default resolution is set to 12-bits. diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801 index 1bba38dd2637..820d9040de16 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801 @@ -33,6 +33,7 @@ Supported adapters: * Intel DNV (SOC) * Intel Broxton (SOC) * Intel Lewisburg (PCH) + * Intel Gemini Lake (SOC) Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio index d4d91a53fc39..7a8d7d261632 100644 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ b/Documentation/i2c/muxes/i2c-mux-gpio @@ -1,11 +1,11 @@ -Kernel driver i2c-gpio-mux +Kernel driver i2c-mux-gpio Author: Peter Korsgaard <peter.korsgaard@barco.com> Description ----------- -i2c-gpio-mux is an i2c mux driver providing access to I2C bus segments +i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments from a master I2C bus and a hardware MUX controlled through GPIO pins. E.G.: @@ -26,16 +26,16 @@ according to the settings of the GPIO pins 1..N. Usage ----- -i2c-gpio-mux uses the platform bus, so you need to provide a struct +i2c-mux-gpio uses the platform bus, so you need to provide a struct platform_device with the platform_data pointing to a struct -gpio_i2cmux_platform_data with the I2C adapter number of the master +i2c_mux_gpio_platform_data with the I2C adapter number of the master bus, the number of bus segments to create and the GPIO pins used -to control it. See include/linux/i2c-gpio-mux.h for details. +to control it. See include/linux/i2c-mux-gpio.h for details. E.G. something like this for a MUX providing 4 bus segments controlled through 3 GPIO pins: -#include <linux/i2c-gpio-mux.h> +#include <linux/i2c-mux-gpio.h> #include <linux/platform_device.h> static const unsigned myboard_gpiomux_gpios[] = { @@ -46,7 +46,7 @@ static const unsigned myboard_gpiomux_values[] = { 0, 1, 2, 3 }; -static struct gpio_i2cmux_platform_data myboard_i2cmux_data = { +static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .parent = 1, .base_nr = 2, /* optional */ .values = myboard_gpiomux_values, @@ -57,7 +57,7 @@ static struct gpio_i2cmux_platform_data myboard_i2cmux_data = { }; static struct platform_device myboard_i2cmux = { - .name = "i2c-gpio-mux", + .name = "i2c-mux-gpio", .id = 0, .dev = { .platform_data = &myboard_i2cmux_data, @@ -66,14 +66,14 @@ static struct platform_device myboard_i2cmux = { If you don't know the absolute GPIO pin numbers at registration time, you can instead provide a chip name (.chip_name) and relative GPIO pin -numbers, and the i2c-gpio-mux driver will do the work for you, +numbers, and the i2c-mux-gpio driver will do the work for you, including deferred probing if the GPIO chip isn't immediately available. Device Registration ------------------- -When registering your i2c-gpio-mux device, you should pass the number +When registering your i2c-mux-gpio device, you should pass the number of any GPIO pin it uses as the device ID. This guarantees that every instance has a different ID. diff --git a/Documentation/index.rst b/Documentation/index.rst index cb5d77699c60..f6e641a54bbc 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -47,7 +47,7 @@ These books get into the details of how specific kernel subsystems work from the point of view of a kernel developer. Much of the information here is taken directly from the kernel source, with supplemental material added as needed (or at least as we managed to add it — probably *not* all that is -needed). +needed). .. toctree:: :maxdepth: 2 @@ -68,6 +68,14 @@ Korean translations translations/ko_KR/index +Chinese translations +-------------------- + +.. toctree:: + :maxdepth: 1 + + translations/zh_CN/index + Indices and tables ================== diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt index 0acfddbe2028..7ebce100fe90 100644 --- a/Documentation/input/input.txt +++ b/Documentation/input/input.txt @@ -279,10 +279,10 @@ struct input_event { 'time' is the timestamp, it returns the time at which the event happened. Type is for example EV_REL for relative moment, EV_KEY for a keypress or -release. More types are defined in include/linux/input.h. +release. More types are defined in include/uapi/linux/input-event-codes.h. 'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete -list is in include/linux/input.h. +list is in include/uapi/linux/input-event-codes.h. 'value' is the value the event carries. Either a relative change for EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index 36138c632f7a..d02cfb48901c 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -24,7 +24,7 @@ Prerequisites ------------- First the prerequisites. Without these you have already failed, because you -will need to add a a 32-bit compat layer: +will need to add a 32-bit compat layer: * Only use fixed sized integers. To avoid conflicts with typedefs in userspace the kernel has special types like __u32, __s64. Use them. diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 81c7f2bb7daf..08244bea5048 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -321,6 +321,7 @@ Code Seq#(hex) Include File Comments 0xB1 00-1F PPPoX <mailto:mostrows@styx.uwaterloo.ca> 0xB3 00 linux/mmc/ioctl.h 0xB4 00-0F linux/gpio.h <mailto:linux-gpio@vger.kernel.org> +0xB5 00-0F uapi/linux/rpmsg.h <mailto:linux-remoteproc@vger.kernel.org> 0xC0 00-0F linux/usb/iowarrior.h 0xCA 00-0F uapi/misc/cxl.h 0xCA 80-8F uapi/scsi/cxlflash_ioctl.h diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt index e5c7254e73d7..5bd590335839 100644 --- a/Documentation/kselftest.txt +++ b/Documentation/kselftest.txt @@ -59,14 +59,14 @@ Install selftests ================= You can use kselftest_install.sh tool installs selftests in default -location which is tools/testing/selftests/kselftest or an user specified +location which is tools/testing/selftests/kselftest or a user specified location. To install selftests in default location: $ cd tools/testing/selftests $ ./kselftest_install.sh -To install selftests in an user specified location: +To install selftests in a user specified location: $ cd tools/testing/selftests $ ./kselftest_install.sh install_dir @@ -95,3 +95,15 @@ In general, the rules for selftests are * Don't cause the top-level "make run_tests" to fail if your feature is unconfigured. + +Contributing new tests(details) +=============================== + + * Use TEST_GEN_XXX if such binaries or files are generated during + compiling. + TEST_PROGS, TEST_GEN_PROGS mean it is the excutable tested by + default. + TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the + executable which is not tested by default. + TEST_FILES, TEST_GEN_FILES mean it is the file which is used by + test. diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index 7f04e13ec53d..9d2096c7160d 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -358,7 +358,7 @@ The current Livepatch implementation has several limitations: Each function has to handle TOC and save LR before it could call the ftrace handler. This operation has to be reverted on return. Fortunately, the generic ftrace code has the same problem and all - this is is handled on the ftrace level. + this is handled on the ftrace level. + Kretprobes using the ftrace framework conflict with the patched diff --git a/Documentation/md-cluster.txt b/Documentation/md/md-cluster.txt index 38883276d31c..38883276d31c 100644 --- a/Documentation/md-cluster.txt +++ b/Documentation/md/md-cluster.txt diff --git a/Documentation/md/raid5-cache.txt b/Documentation/md/raid5-cache.txt new file mode 100644 index 000000000000..2b210f295786 --- /dev/null +++ b/Documentation/md/raid5-cache.txt @@ -0,0 +1,109 @@ +RAID5 cache + +Raid 4/5/6 could include an extra disk for data cache besides normal RAID +disks. The role of RAID disks isn't changed with the cache disk. The cache disk +caches data to the RAID disks. The cache can be in write-through (supported +since 4.4) or write-back mode (supported since 4.10). mdadm (supported since +3.4) has a new option '--write-journal' to create array with cache. Please +refer to mdadm manual for details. By default (RAID array starts), the cache is +in write-through mode. A user can switch it to write-back mode by: + +echo "write-back" > /sys/block/md0/md/journal_mode + +And switch it back to write-through mode by: + +echo "write-through" > /sys/block/md0/md/journal_mode + +In both modes, all writes to the array will hit cache disk first. This means +the cache disk must be fast and sustainable. + +------------------------------------- +write-through mode: + +This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean +shutdown can cause data in some stripes to not be in consistent state, eg, data +and parity don't match. The reason is that a stripe write involves several RAID +disks and it's possible the writes don't hit all RAID disks yet before the +unclean shutdown. We call an array degraded if it has inconsistent data. MD +tries to resync the array to bring it back to normal state. But before the +resync completes, any system crash will expose the chance of real data +corruption in the RAID array. This problem is called 'write hole'. + +The write-through cache will cache all data on cache disk first. After the data +is safe on the cache disk, the data will be flushed onto RAID disks. The +two-step write will guarantee MD can recover correct data after unclean +shutdown even the array is degraded. Thus the cache can close the 'write hole'. + +In write-through mode, MD reports IO completion to upper layer (usually +filesystems) after the data is safe on RAID disks, so cache disk failure +doesn't cause data loss. Of course cache disk failure means the array is +exposed to 'write hole' again. + +In write-through mode, the cache disk isn't required to be big. Several +hundreds megabytes are enough. + +-------------------------------------- +write-back mode: + +write-back mode fixes the 'write hole' issue too, since all write data is +cached on cache disk. But the main goal of 'write-back' cache is to speed up +write. If a write crosses all RAID disks of a stripe, we call it full-stripe +write. For non-full-stripe writes, MD must read old data before the new parity +can be calculated. These synchronous reads hurt write throughput. Some writes +which are sequential but not dispatched in the same time will suffer from this +overhead too. Write-back cache will aggregate the data and flush the data to +RAID disks only after the data becomes a full stripe write. This will +completely avoid the overhead, so it's very helpful for some workloads. A +typical workload which does sequential write followed by fsync is an example. + +In write-back mode, MD reports IO completion to upper layer (usually +filesystems) right after the data hits cache disk. The data is flushed to raid +disks later after specific conditions met. So cache disk failure will cause +data loss. + +In write-back mode, MD also caches data in memory. The memory cache includes +the same data stored on cache disk, so a power loss doesn't cause data loss. +The memory cache size has performance impact for the array. It's recommended +the size is big. A user can configure the size by: + +echo "2048" > /sys/block/md0/md/stripe_cache_size + +Too small cache disk will make the write aggregation less efficient in this +mode depending on the workloads. It's recommended to use a cache disk with at +least several gigabytes size in write-back mode. + +-------------------------------------- +The implementation: + +The write-through and write-back cache use the same disk format. The cache disk +is organized as a simple write log. The log consists of 'meta data' and 'data' +pairs. The meta data describes the data. It also includes checksum and sequence +ID for recovery identification. Data can be IO data and parity data. Data is +checksumed too. The checksum is stored in the meta data ahead of the data. The +checksum is an optimization because MD can write meta and data freely without +worry about the order. MD superblock has a field pointed to the valid meta data +of log head. + +The log implementation is pretty straightforward. The difficult part is the +order in which MD writes data to cache disk and RAID disks. Specifically, in +write-through mode, MD calculates parity for IO data, writes both IO data and +parity to the log, writes the data and parity to RAID disks after the data and +parity is settled down in log and finally the IO is finished. Read just reads +from raid disks as usual. + +In write-back mode, MD writes IO data to the log and reports IO completion. The +data is also fully cached in memory at that time, which means read must query +memory cache. If some conditions are met, MD will flush the data to RAID disks. +MD will calculate parity for the data and write parity into the log. After this +is finished, MD will write both data and parity into RAID disks, then MD can +release the memory cache. The flush conditions could be stripe becomes a full +stripe write, free cache disk space is low or free in-kernel memory cache space +is low. + +After an unclean shutdown, MD does recovery. MD reads all meta data and data +from the log. The sequence ID and checksum will help us detect corrupted meta +data and data. If MD finds a stripe with data and valid parities (1 parity for +raid4/5 and 2 for raid6), MD will write the data and parities to RAID disks. If +parities are incompleted, they are discarded. If part of data is corrupted, +they are discarded too. MD then loads valid data and writes them to RAID disks +in normal way. diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile index 32663602ff25..9b3e70b2cab2 100644 --- a/Documentation/media/Makefile +++ b/Documentation/media/Makefile @@ -36,7 +36,7 @@ quiet_cmd_genpdf = GENPDF $2 cmd_genpdf = convert $2 $3 quiet_cmd_gendot = DOT $2 - cmd_gendot = dot -Tsvg $2 > $3 + cmd_gendot = dot -Tsvg $2 > $3 || { rm -f $3; exit 1; } %.pdf: %.svg @$(call cmd,genpdf,$<,$@) @@ -103,6 +103,7 @@ html: all epub: all xml: all latex: $(IMGPDF) all +linkcheck: clean: -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null diff --git a/Documentation/media/dvb-drivers/ci.rst b/Documentation/media/dvb-drivers/ci.rst index 8124bf5ce5ef..69b07e9d1816 100644 --- a/Documentation/media/dvb-drivers/ci.rst +++ b/Documentation/media/dvb-drivers/ci.rst @@ -20,7 +20,7 @@ existing low level CI API. ca_zap ~~~~~~ -An userspace application, like ``ca_zap`` is required to handle encrypted +A userspace application, like ``ca_zap`` is required to handle encrypted MPEG-TS streams. The ``ca_zap`` userland application is in charge of sending the diff --git a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst index bf31411fc9df..899fd5c3545e 100644 --- a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst +++ b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst @@ -9,7 +9,7 @@ frontend parameters The kind of parameters passed to the frontend device for tuning depend on the kind of hardware you are using. -The struct ``dvb_frontend_parameters`` uses an union with specific +The struct ``dvb_frontend_parameters`` uses a union with specific per-system parameters. However, as newer delivery systems required more data, the structure size weren't enough to fit, and just extending its size would break the existing applications. So, those parameters were @@ -23,7 +23,7 @@ So, newer applications should use instead, in order to be able to support the newer System Delivery like DVB-S2, DVB-T2, DVB-C2, ISDB, etc. -All kinds of parameters are combined as an union in the +All kinds of parameters are combined as a union in the FrontendParameters structure: diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index bc63b12efafd..195ccaac2816 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -312,7 +312,7 @@ information out of a register+stack dump printed by the kernel on protection faults (so-called "kernel oops"). If you run into some kind of deadlock, you can try to dump a call trace -for each process using sysrq-t (see Documentation/sysrq.txt). +for each process using sysrq-t (see Documentation/admin-guide/sysrq.rst). This way it is possible to figure where *exactly* some process in "D" state is stuck. diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 5de846d3ecc0..670f3ded0802 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -114,11 +114,11 @@ config options. Memory model -> Sparse Memory (CONFIG_SPARSEMEM) Allow for memory hot-add (CONFIG_MEMORY_HOTPLUG) -- To enable memory removal, the followings are also necessary +- To enable memory removal, the following are also necessary Allow for memory hot remove (CONFIG_MEMORY_HOTREMOVE) Page Migration (CONFIG_MIGRATION) -- For ACPI memory hotplug, the followings are also necessary +- For ACPI memory hotplug, the following are also necessary Memory hotplug (under ACPI Support menu) (CONFIG_ACPI_HOTPLUG_MEMORY) This option can be kernel module. diff --git a/Documentation/networking/cdc_mbim.txt b/Documentation/networking/cdc_mbim.txt index a15ea602aa52..b9482ca10254 100644 --- a/Documentation/networking/cdc_mbim.txt +++ b/Documentation/networking/cdc_mbim.txt @@ -38,7 +38,7 @@ Basic usage =========== MBIM functions are inactive when unmanaged. The cdc_mbim driver only -provides an userspace interface to the MBIM control channel, and will +provides a userspace interface to the MBIM control channel, and will not participate in the management of the function. This implies that a userspace MBIM management application always is required to enable a MBIM function. @@ -200,7 +200,7 @@ structure described in section 10.5.29 of [1]. The DSS VLAN subdevices are used as a practical interface between the shared MBIM data channel and a MBIM DSS aware userspace application. It is not intended to be presented as-is to an end user. The -assumption is that an userspace application initiating a DSS session +assumption is that a userspace application initiating a DSS session also takes care of the necessary framing of the DSS data, presenting the stream to the end user in an appropriate way for the stream type. diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index 63912ef34606..b8b40753133e 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -295,7 +295,6 @@ DSA currently leverages the following subsystems: - MDIO/PHY library: drivers/net/phy/phy.c, mdio_bus.c - Switchdev: net/switchdev/* - Device Tree for various of_* functions -- HWMON: drivers/hwmon/* MDIO/PHY library ---------------- @@ -349,12 +348,6 @@ Documentation/devicetree/bindings/net/dsa/dsa.txt. PHY/MDIO library helper functions such as of_get_phy_mode(), of_phy_connect() are also used to query per-port PHY specific details: interface connection, MDIO bus location etc.. -HWMON ------ - -Some switch drivers feature internal temperature sensors which are exposed as -regular HWMON devices in /sys/class/hwmon/. - Driver development ================== @@ -495,23 +488,6 @@ Power management BR_STATE_DISABLED and propagating changes to the hardware if this port is disabled while being a bridge member -Hardware monitoring -------------------- - -These callbacks are only available if CONFIG_NET_DSA_HWMON is enabled: - -- get_temp: this function queries the given switch for its temperature - -- get_temp_limit: this function returns the switch current maximum temperature - limit - -- set_temp_limit: this function configures the maximum temperature limit allowed - -- get_temp_alarm: this function returns the critical temperature threshold - returning an alarm notification - -See Documentation/hwmon/sysfs-interface for details. - Bridge layer ------------ diff --git a/Documentation/networking/gtp.txt b/Documentation/networking/gtp.txt new file mode 100644 index 000000000000..93e96750f103 --- /dev/null +++ b/Documentation/networking/gtp.txt @@ -0,0 +1,135 @@ +The Linux kernel GTP tunneling module +====================================================================== +Documentation by Harald Welte <laforge@gnumonks.org> + +In 'drivers/net/gtp.c' you are finding a kernel-level implementation +of a GTP tunnel endpoint. + +== What is GTP == + +GTP is the Generic Tunnel Protocol, which is a 3GPP protocol used for +tunneling User-IP payload between a mobile station (phone, modem) +and the interconnection between an external packet data network (such +as the internet). + +So when you start a 'data connection' from your mobile phone, the +phone will use the control plane to signal for the establishment of +such a tunnel between that external data network and the phone. The +tunnel endpoints thus reside on the phone and in the gateway. All +intermediate nodes just transport the encapsulated packet. + +The phone itself does not implement GTP but uses some other +technology-dependent protocol stack for transmitting the user IP +payload, such as LLC/SNDCP/RLC/MAC. + +At some network element inside the cellular operator infrastructure +(SGSN in case of GPRS/EGPRS or classic UMTS, hNodeB in case of a 3G +femtocell, eNodeB in case of 4G/LTE), the cellular protocol stacking +is translated into GTP *without breaking the end-to-end tunnel*. So +intermediate nodes just perform some specific relay function. + +At some point the GTP packet ends up on the so-called GGSN (GSM/UMTS) +or P-GW (LTE), which terminates the tunnel, decapsulates the packet +and forwards it onto an external packet data network. This can be +public internet, but can also be any private IP network (or even +theoretically some non-IP network like X.25). + +You can find the protocol specification in 3GPP TS 29.060, available +publicly via the 3GPP website at http://www.3gpp.org/DynaReport/29060.htm + +A direct PDF link to v13.6.0 is provided for convenience below: +http://www.etsi.org/deliver/etsi_ts/129000_129099/129060/13.06.00_60/ts_129060v130600p.pdf + +== The Linux GTP tunnelling module == + +The module implements the function of a tunnel endpoint, i.e. it is +able to decapsulate tunneled IP packets in the uplink originated by +the phone, and encapsulate raw IP packets received from the external +packet network in downlink towards the phone. + +It *only* implements the so-called 'user plane', carrying the User-IP +payload, called GTP-U. It does not implement the 'control plane', +which is a signaling protocol used for establishment and teardown of +GTP tunnels (GTP-C). + +So in order to have a working GGSN/P-GW setup, you will need a +userspace program that implements the GTP-C protocol and which then +uses the netlink interface provided by the GTP-U module in the kernel +to configure the kernel module. + +This split architecture follows the tunneling modules of other +protocols, e.g. PPPoE or L2TP, where you also run a userspace daemon +to handle the tunnel establishment, authentication etc. and only the +data plane is accelerated inside the kernel. + +Don't be confused by terminology: The GTP User Plane goes through +kernel accelerated path, while the GTP Control Plane goes to +Userspace :) + +The official homepge of the module is at +https://osmocom.org/projects/linux-kernel-gtp-u/wiki + +== Userspace Programs with Linux Kernel GTP-U support == + +At the time of this writing, there are at least two Free Software +implementations that implement GTP-C and can use the netlink interface +to make use of the Linux kernel GTP-U support: + +* OpenGGSN (classic 2G/3G GGSN in C): + https://osmocom.org/projects/openggsn/wiki/OpenGGSN + +* ergw (GGSN + P-GW in Erlang): + https://github.com/travelping/ergw + +== Userspace Library / Command Line Utilities == + +There is a userspace library called 'libgtpnl' which is based on +libmnl and which implements a C-language API towards the netlink +interface provided by the Kernel GTP module: + +http://git.osmocom.org/libgtpnl/ + +== Protocol Versions == + +There are two different versions of GTP-U: v0 and v1. Both are +implemented in the Kernel GTP module. Version 0 is a legacy version, +and deprecated from recent 3GPP specifications. + +There are three versions of GTP-C: v0, v1, and v2. As the kernel +doesn't implement GTP-C, we don't have to worry about this. It's the +responsibility of the control plane implementation in userspace to +implement that. + +== IPv6 == + +The 3GPP specifications indicate either IPv4 or IPv6 can be used both +on the inner (user) IP layer, or on the outer (transport) layer. + +Unfortunately, the Kernel module currently supports IPv6 neither for +the User IP payload, nor for the outer IP layer. Patches or other +Contributions to fix this are most welcome! + +== Mailing List == + +If yo have questions regarding how to use the Kernel GTP module from +your own software, or want to contribute to the code, please use the +osmocom-net-grps mailing list for related discussion. The list can be +reached at osmocom-net-gprs@lists.osmocom.org and the mailman +interface for managign your subscription is at +https://lists.osmocom.org/mailman/listinfo/osmocom-net-gprs + +== Issue Tracker == + +The Osmocom project maintains an issue tracker for the Kernel GTP-U +module at +https://osmocom.org/projects/linux-kernel-gtp-u/issues + +== History / Acknowledgements == + +The Module was originally created in 2012 by Harald Welte, but never +completed. Pablo came in to finish the mess Harald left behind. But +doe to a lack of user interest, it never got merged. + +In 2015, Andreas Schultz came to the rescue and fixed lots more bugs, +extended it with new features and finally pushed all of us to get it +mainline, where it was merged in 4.7.0. diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 7dd65c9cf707..ab0230461377 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -246,21 +246,12 @@ tcp_dsack - BOOLEAN Allows TCP to send "duplicate" SACKs. tcp_early_retrans - INTEGER - Enable Early Retransmit (ER), per RFC 5827. ER lowers the threshold - for triggering fast retransmit when the amount of outstanding data is - small and when no previously unsent data can be transmitted (such - that limited transmit could be used). Also controls the use of - Tail loss probe (TLP) that converts RTOs occurring due to tail - losses into fast recovery (draft-dukkipati-tcpm-tcp-loss-probe-01). + Tail loss probe (TLP) converts RTOs occurring due to tail + losses into fast recovery (draft-ietf-tcpm-rack). Note that + TLP requires RACK to function properly (see tcp_recovery below) Possible values: - 0 disables ER - 1 enables ER - 2 enables ER but delays fast recovery and fast retransmit - by a fourth of RTT. This mitigates connection falsely - recovers when network has a small degree of reordering - (less than 3 packets). - 3 enables delayed ER and TLP. - 4 enables TLP only. + 0 disables TLP + 3 or 4 enables TLP Default: 3 tcp_ecn - INTEGER @@ -712,18 +703,6 @@ tcp_thin_linear_timeouts - BOOLEAN Documentation/networking/tcp-thin.txt Default: 0 -tcp_thin_dupack - BOOLEAN - Enable dynamic triggering of retransmissions after one dupACK - for thin streams. If set, a check is performed upon reception - of a dupACK to determine if the stream is thin (less than 4 - packets in flight). As long as the stream is found to be thin, - data is retransmitted on the first received dupACK. This - improves retransmission latency for non-aggressive thin - streams, often found to be time-dependent. - For more information on thin streams, see - Documentation/networking/tcp-thin.txt - Default: 0 - tcp_limit_output_bytes - INTEGER Controls TCP Small Queue limit per tcp socket. TCP bulk sender tends to increase packets in flight until it @@ -742,6 +721,13 @@ tcp_challenge_ack_limit - INTEGER UDP variables: +udp_l3mdev_accept - BOOLEAN + Enabling this option allows a "global" bound socket to work + across L3 master domains (e.g., VRFs) with packets capable of + being received regardless of the L3 domain in which they + originated. Only valid when the kernel was compiled with + CONFIG_NET_L3_MASTER_DEV. + udp_mem - vector of 3 INTEGERs: min, pressure, max Number of pages allowed for queueing by all UDP sockets. @@ -843,6 +829,15 @@ ip_local_reserved_ports - list of comma separated ranges Default: Empty +ip_unprivileged_port_start - INTEGER + This is a per-namespace sysctl. It defines the first + unprivileged port in the network namespace. Privileged ports + require root or CAP_NET_BIND_SERVICE in order to bind to them. + To disable all privileged ports, set this to 0. It may not + overlap with the ip_local_reserved_ports range. + + Default: 1024 + ip_nonlocal_bind - BOOLEAN If set, allows processes to bind() to non-local IP addresses, which can be quite useful - but may break some applications. @@ -1011,7 +1006,8 @@ accept_redirects - BOOLEAN FALSE (router) forwarding - BOOLEAN - Enable IP forwarding on this interface. + Enable IP forwarding on this interface. This controls whether packets + received _on_ this interface can be forwarded. mc_forwarding - BOOLEAN Do multicast routing. The kernel needs to be compiled with CONFIG_MROUTE diff --git a/Documentation/networking/kcm.txt b/Documentation/networking/kcm.txt index 3476ede5bc2c..9a513295b07c 100644 --- a/Documentation/networking/kcm.txt +++ b/Documentation/networking/kcm.txt @@ -272,7 +272,7 @@ on the socket thus waking up the application thread. When the application sees the error (which may just be a disconnect) it should unattach the socket from KCM and then close it. It is assumed that once an error is posted on the TCP socket the data stream is unrecoverable (i.e. an error -may have occurred in in the middle of receiving a messssge). +may have occurred in the middle of receiving a messssge). TCP connection monitoring ------------------------- diff --git a/Documentation/networking/netfilter-sysctl.txt b/Documentation/networking/netfilter-sysctl.txt new file mode 100644 index 000000000000..55791e50e169 --- /dev/null +++ b/Documentation/networking/netfilter-sysctl.txt @@ -0,0 +1,10 @@ +/proc/sys/net/netfilter/* Variables: + +nf_log_all_netns - BOOLEAN + 0 - disabled (default) + not 0 - enabled + + By default, only init_net namespace can log packets into kernel log + with LOG target; this aims to prevent containers from flooding host + kernel log. If enabled, this target also works in other network + namespaces. This variable is only accessible from init_net. diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt index daa015af16a0..f3b9e507ab05 100644 --- a/Documentation/networking/packet_mmap.txt +++ b/Documentation/networking/packet_mmap.txt @@ -565,7 +565,7 @@ TPACKET_V1 --> TPACKET_V2: (void *)hdr + TPACKET_ALIGN(sizeof(struct tpacket_hdr)) TPACKET_V2 --> TPACKET_V3: - - Flexible buffer implementation: + - Flexible buffer implementation for RX_RING: 1. Blocks can be configured with non-static frame-size 2. Read/poll is at a block-level (as opposed to packet-level) 3. Added poll timeout to avoid indefinite user-space wait @@ -574,7 +574,12 @@ TPACKET_V2 --> TPACKET_V3: 4.1 block::timeout 4.2 tpkt_hdr::sk_rxhash - RX Hash data available in user space - - Currently only RX_RING available + - TX_RING semantics are conceptually similar to TPACKET_V2; + use tpacket3_hdr instead of tpacket2_hdr, and TPACKET3_HDRLEN + instead of TPACKET2_HDRLEN. In the current implementation, + the tp_next_offset field in the tpacket3_hdr MUST be set to + zero, indicating that the ring does not hold variable sized frames. + Packets with non-zero values of tp_next_offset will be dropped. ------------------------------------------------------------------------------- + AF_PACKET fanout mode diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt index 356f791af574..7818b5fe448b 100644 --- a/Documentation/networking/regulatory.txt +++ b/Documentation/networking/regulatory.txt @@ -156,12 +156,12 @@ struct ieee80211_regdomain mydriver_jp_regdom = { //.alpha2 = "99", /* If I have no alpha2 to map it to */ .reg_rules = { /* IEEE 802.11b/g, channels 1..14 */ - REG_RULE(2412-20, 2484+20, 40, 6, 20, 0), + REG_RULE(2412-10, 2484+10, 40, 6, 20, 0), /* IEEE 802.11a, channels 34..48 */ - REG_RULE(5170-20, 5240+20, 40, 6, 20, + REG_RULE(5170-10, 5240+10, 40, 6, 20, NL80211_RRF_NO_IR), /* IEEE 802.11a, channels 52..64 */ - REG_RULE(5260-20, 5320+20, 40, 6, 20, + REG_RULE(5260-10, 5320+10, 40, 6, 20, NL80211_RRF_NO_IR| NL80211_RRF_DFS), } @@ -205,7 +205,7 @@ the data in regdb.c as an alternative to using CRDA. The file net/wireless/db.txt should be kept up-to-date with the db.txt file available in the git repository here: - git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-regdb.git + git://git.kernel.org/pub/scm/linux/kernel/git/sforshee/wireless-regdb.git Again, most users in most situations should be using the CRDA package provided with their distribution, and in most other situations users diff --git a/Documentation/networking/vrf.txt b/Documentation/networking/vrf.txt index 755dab856392..3918dae964d4 100644 --- a/Documentation/networking/vrf.txt +++ b/Documentation/networking/vrf.txt @@ -98,10 +98,11 @@ VRF device: or to specify the output device using cmsg and IP_PKTINFO. -TCP services running in the default VRF context (ie., not bound to any VRF -device) can work across all VRF domains by enabling the tcp_l3mdev_accept -sysctl option: +TCP & UDP services running in the default VRF context (ie., not bound +to any VRF device) can work across all VRF domains by enabling the +tcp_l3mdev_accept and udp_l3mdev_accept sysctl options: sysctl -w net.ipv4.tcp_l3mdev_accept=1 + sysctl -w net.ipv4.udp_l3mdev_accept=1 netfilter rules on the VRF device can be used to limit access to services running in the default VRF context as well. diff --git a/Documentation/perf/qcom_l2_pmu.txt b/Documentation/perf/qcom_l2_pmu.txt new file mode 100644 index 000000000000..b25b97659ab9 --- /dev/null +++ b/Documentation/perf/qcom_l2_pmu.txt @@ -0,0 +1,38 @@ +Qualcomm Technologies Level-2 Cache Performance Monitoring Unit (PMU) +===================================================================== + +This driver supports the L2 cache clusters found in Qualcomm Technologies +Centriq SoCs. There are multiple physical L2 cache clusters, each with their +own PMU. Each cluster has one or more CPUs associated with it. + +There is one logical L2 PMU exposed, which aggregates the results from +the physical PMUs. + +The driver provides a description of its available events and configuration +options in sysfs, see /sys/devices/l2cache_0. + +The "format" directory describes the format of the events. + +Events can be envisioned as a 2-dimensional array. Each column represents +a group of events. There are 8 groups. Only one entry from each +group can be in use at a time. If multiple events from the same group +are specified, the conflicting events cannot be counted at the same time. + +Events are specified as 0xCCG, where CC is 2 hex digits specifying +the code (array row) and G specifies the group (column) 0-7. + +In addition there is a cycle counter event specified by the value 0xFE +which is outside the above scheme. + +The driver provides a "cpumask" sysfs attribute which contains a mask +consisting of one CPU per cluster which will be used to handle all the PMU +events on that cluster. + +Examples for use with perf: + + perf stat -e l2cache_0/config=0x001/,l2cache_0/config=0x042/ -a sleep 1 + + perf stat -e l2cache_0/config=0xfe/ -C 2 sleep 1 + +The driver does not support sampling, therefore "perf record" will +not work. Per-task perf sessions are not supported. diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX index 7cb6085839f3..7f3c2def2cac 100644 --- a/Documentation/power/00-INDEX +++ b/Documentation/power/00-INDEX @@ -14,8 +14,6 @@ freezing-of-tasks.txt - How processes and controlled during suspend interface.txt - Power management user interface in /sys/power -notifiers.txt - - Registering suspend notifiers in device drivers opp.txt - Operating Performance Point library pci.txt diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt deleted file mode 100644 index 73ddea39a9ce..000000000000 --- a/Documentation/power/devices.txt +++ /dev/null @@ -1,716 +0,0 @@ -Device Power Management - -Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. -Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> -Copyright (c) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> - - -Most of the code in Linux is device drivers, so most of the Linux power -management (PM) code is also driver-specific. Most drivers will do very -little; others, especially for platforms with small batteries (like cell -phones), will do a lot. - -This writeup gives an overview of how drivers interact with system-wide -power management goals, emphasizing the models and interfaces that are -shared by everything that hooks up to the driver model core. Read it as -background for the domain-specific work you'd do with any specific driver. - - -Two Models for Device Power Management -====================================== -Drivers will use one or both of these models to put devices into low-power -states: - - System Sleep model: - Drivers can enter low-power states as part of entering system-wide - low-power states like "suspend" (also known as "suspend-to-RAM"), or - (mostly for systems with disks) "hibernation" (also known as - "suspend-to-disk"). - - This is something that device, bus, and class drivers collaborate on - by implementing various role-specific suspend and resume methods to - cleanly power down hardware and software subsystems, then reactivate - them without loss of data. - - Some drivers can manage hardware wakeup events, which make the system - leave the low-power state. This feature may be enabled or disabled - using the relevant /sys/devices/.../power/wakeup file (for Ethernet - drivers the ioctl interface used by ethtool may also be used for this - purpose); enabling it may cost some power usage, but let the whole - system enter low-power states more often. - - Runtime Power Management model: - Devices may also be put into low-power states while the system is - running, independently of other power management activity in principle. - However, devices are not generally independent of each other (for - example, a parent device cannot be suspended unless all of its child - devices have been suspended). Moreover, depending on the bus type the - device is on, it may be necessary to carry out some bus-specific - operations on the device for this purpose. Devices put into low power - states at run time may require special handling during system-wide power - transitions (suspend or hibernation). - - For these reasons not only the device driver itself, but also the - appropriate subsystem (bus type, device type or device class) driver and - the PM core are involved in runtime power management. As in the system - sleep power management case, they need to collaborate by implementing - various role-specific suspend and resume methods, so that the hardware - is cleanly powered down and reactivated without data or service loss. - -There's not a lot to be said about those low-power states except that they are -very system-specific, and often device-specific. Also, that if enough devices -have been put into low-power states (at runtime), the effect may be very similar -to entering some system-wide low-power state (system sleep) ... and that -synergies exist, so that several drivers using runtime PM might put the system -into a state where even deeper power saving options are available. - -Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except -for wakeup events), no more data read or written, and requests from upstream -drivers are no longer accepted. A given bus or platform may have different -requirements though. - -Examples of hardware wakeup events include an alarm from a real time clock, -network wake-on-LAN packets, keyboard or mouse activity, and media insertion -or removal (for PCMCIA, MMC/SD, USB, and so on). - - -Interfaces for Entering System Sleep States -=========================================== -There are programming interfaces provided for subsystems (bus type, device type, -device class) and device drivers to allow them to participate in the power -management of devices they are concerned with. These interfaces cover both -system sleep and runtime power management. - - -Device Power Management Operations ----------------------------------- -Device power management operations, at the subsystem level as well as at the -device driver level, are implemented by defining and populating objects of type -struct dev_pm_ops: - -struct dev_pm_ops { - int (*prepare)(struct device *dev); - void (*complete)(struct device *dev); - int (*suspend)(struct device *dev); - int (*resume)(struct device *dev); - int (*freeze)(struct device *dev); - int (*thaw)(struct device *dev); - int (*poweroff)(struct device *dev); - int (*restore)(struct device *dev); - int (*suspend_late)(struct device *dev); - int (*resume_early)(struct device *dev); - int (*freeze_late)(struct device *dev); - int (*thaw_early)(struct device *dev); - int (*poweroff_late)(struct device *dev); - int (*restore_early)(struct device *dev); - int (*suspend_noirq)(struct device *dev); - int (*resume_noirq)(struct device *dev); - int (*freeze_noirq)(struct device *dev); - int (*thaw_noirq)(struct device *dev); - int (*poweroff_noirq)(struct device *dev); - int (*restore_noirq)(struct device *dev); - int (*runtime_suspend)(struct device *dev); - int (*runtime_resume)(struct device *dev); - int (*runtime_idle)(struct device *dev); -}; - -This structure is defined in include/linux/pm.h and the methods included in it -are also described in that file. Their roles will be explained in what follows. -For now, it should be sufficient to remember that the last three methods are -specific to runtime power management while the remaining ones are used during -system-wide power transitions. - -There also is a deprecated "old" or "legacy" interface for power management -operations available at least for some subsystems. This approach does not use -struct dev_pm_ops objects and it is suitable only for implementing system sleep -power management methods. Therefore it is not described in this document, so -please refer directly to the source code for more information about it. - - -Subsystem-Level Methods ------------------------ -The core methods to suspend and resume devices reside in struct dev_pm_ops -pointed to by the ops member of struct dev_pm_domain, or by the pm member of -struct bus_type, struct device_type and struct class. They are mostly of -interest to the people writing infrastructure for platforms and buses, like PCI -or USB, or device type and device class drivers. They also are relevant to the -writers of device drivers whose subsystems (PM domains, device types, device -classes and bus types) don't provide all power management methods. - -Bus drivers implement these methods as appropriate for the hardware and the -drivers using it; PCI works differently from USB, and so on. Not many people -write subsystem-level drivers; most driver code is a "device driver" that builds -on top of bus-specific framework code. - -For more information on these driver calls, see the description later; -they are called in phases for every device, respecting the parent-child -sequencing in the driver model tree. - - -/sys/devices/.../power/wakeup files ------------------------------------ -All device objects in the driver model contain fields that control the handling -of system wakeup events (hardware signals that can force the system out of a -sleep state). These fields are initialized by bus or device driver code using -device_set_wakeup_capable() and device_set_wakeup_enable(), defined in -include/linux/pm_wakeup.h. - -The "power.can_wakeup" flag just records whether the device (and its driver) can -physically support wakeup events. The device_set_wakeup_capable() routine -affects this flag. The "power.wakeup" field is a pointer to an object of type -struct wakeup_source used for controlling whether or not the device should use -its system wakeup mechanism and for notifying the PM core of system wakeup -events signaled by the device. This object is only present for wakeup-capable -devices (i.e. devices whose "can_wakeup" flags are set) and is created (or -removed) by device_set_wakeup_capable(). - -Whether or not a device is capable of issuing wakeup events is a hardware -matter, and the kernel is responsible for keeping track of it. By contrast, -whether or not a wakeup-capable device should issue wakeup events is a policy -decision, and it is managed by user space through a sysfs attribute: the -"power/wakeup" file. User space can write the strings "enabled" or "disabled" -to it to indicate whether or not, respectively, the device is supposed to signal -system wakeup. This file is only present if the "power.wakeup" object exists -for the given device and is created (or removed) along with that object, by -device_set_wakeup_capable(). Reads from the file will return the corresponding -string. - -The "power/wakeup" file is supposed to contain the "disabled" string initially -for the majority of devices; the major exceptions are power buttons, keyboards, -and Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with -ethtool. It should also default to "enabled" for devices that don't generate -wakeup requests on their own but merely forward wakeup requests from one bus to -another (like PCI Express ports). - -The device_may_wakeup() routine returns true only if the "power.wakeup" object -exists and the corresponding "power/wakeup" file contains the string "enabled". -This information is used by subsystems, like the PCI bus type code, to see -whether or not to enable the devices' wakeup mechanisms. If device wakeup -mechanisms are enabled or disabled directly by drivers, they also should use -device_may_wakeup() to decide what to do during a system sleep transition. -Device drivers, however, are not supposed to call device_set_wakeup_enable() -directly in any case. - -It ought to be noted that system wakeup is conceptually different from "remote -wakeup" used by runtime power management, although it may be supported by the -same physical mechanism. Remote wakeup is a feature allowing devices in -low-power states to trigger specific interrupts to signal conditions in which -they should be put into the full-power state. Those interrupts may or may not -be used to signal system wakeup events, depending on the hardware design. On -some systems it is impossible to trigger them from system sleep states. In any -case, remote wakeup should always be enabled for runtime power management for -all devices and drivers that support it. - -/sys/devices/.../power/control files ------------------------------------- -Each device in the driver model has a flag to control whether it is subject to -runtime power management. This flag, called runtime_auto, is initialized by the -bus type (or generally subsystem) code using pm_runtime_allow() or -pm_runtime_forbid(); the default is to allow runtime power management. - -The setting can be adjusted by user space by writing either "on" or "auto" to -the device's power/control sysfs file. Writing "auto" calls pm_runtime_allow(), -setting the flag and allowing the device to be runtime power-managed by its -driver. Writing "on" calls pm_runtime_forbid(), clearing the flag, returning -the device to full power if it was in a low-power state, and preventing the -device from being runtime power-managed. User space can check the current value -of the runtime_auto flag by reading the file. - -The device's runtime_auto flag has no effect on the handling of system-wide -power transitions. In particular, the device can (and in the majority of cases -should and will) be put into a low-power state during a system-wide transition -to a sleep state even though its runtime_auto flag is clear. - -For more information about the runtime power management framework, refer to -Documentation/power/runtime_pm.txt. - - -Calling Drivers to Enter and Leave System Sleep States -====================================================== -When the system goes into a sleep state, each device's driver is asked to -suspend the device by putting it into a state compatible with the target -system state. That's usually some version of "off", but the details are -system-specific. Also, wakeup-enabled devices will usually stay partly -functional in order to wake the system. - -When the system leaves that low-power state, the device's driver is asked to -resume it by returning it to full power. The suspend and resume operations -always go together, and both are multi-phase operations. - -For simple drivers, suspend might quiesce the device using class code -and then turn its hardware as "off" as possible during suspend_noirq. The -matching resume calls would then completely reinitialize the hardware -before reactivating its class I/O queues. - -More power-aware drivers might prepare the devices for triggering system wakeup -events. - - -Call Sequence Guarantees ------------------------- -To ensure that bridges and similar links needing to talk to a device are -available when the device is suspended or resumed, the device tree is -walked in a bottom-up order to suspend devices. A top-down order is -used to resume those devices. - -The ordering of the device tree is defined by the order in which devices -get registered: a child can never be registered, probed or resumed before -its parent; and can't be removed or suspended after that parent. - -The policy is that the device tree should match hardware bus topology. -(Or at least the control bus, for devices which use multiple busses.) -In particular, this means that a device registration may fail if the parent of -the device is suspending (i.e. has been chosen by the PM core as the next -device to suspend) or has already suspended, as well as after all of the other -devices have been suspended. Device drivers must be prepared to cope with such -situations. - - -System Power Management Phases ------------------------------- -Suspending or resuming the system is done in several phases. Different phases -are used for freeze, standby, and memory sleep states ("suspend-to-RAM") and the -hibernation state ("suspend-to-disk"). Each phase involves executing callbacks -for every device before the next phase begins. Not all busses or classes -support all these callbacks and not all drivers use all the callbacks. The -various phases always run after tasks have been frozen and before they are -unfrozen. Furthermore, the *_noirq phases run at a time when IRQ handlers have -been disabled (except for those marked with the IRQF_NO_SUSPEND flag). - -All phases use PM domain, bus, type, class or driver callbacks (that is, methods -defined in dev->pm_domain->ops, dev->bus->pm, dev->type->pm, dev->class->pm or -dev->driver->pm). These callbacks are regarded by the PM core as mutually -exclusive. Moreover, PM domain callbacks always take precedence over all of the -other callbacks and, for example, type callbacks take precedence over bus, class -and driver callbacks. To be precise, the following rules are used to determine -which callback to execute in the given phase: - - 1. If dev->pm_domain is present, the PM core will choose the callback - included in dev->pm_domain->ops for execution - - 2. Otherwise, if both dev->type and dev->type->pm are present, the callback - included in dev->type->pm will be chosen for execution. - - 3. Otherwise, if both dev->class and dev->class->pm are present, the - callback included in dev->class->pm will be chosen for execution. - - 4. Otherwise, if both dev->bus and dev->bus->pm are present, the callback - included in dev->bus->pm will be chosen for execution. - -This allows PM domains and device types to override callbacks provided by bus -types or device classes if necessary. - -The PM domain, type, class and bus callbacks may in turn invoke device- or -driver-specific methods stored in dev->driver->pm, but they don't have to do -that. - -If the subsystem callback chosen for execution is not present, the PM core will -execute the corresponding method from dev->driver->pm instead if there is one. - - -Entering System Suspend ------------------------ -When the system goes into the freeze, standby or memory sleep state, -the phases are: - - prepare, suspend, suspend_late, suspend_noirq. - - 1. The prepare phase is meant to prevent races by preventing new devices - from being registered; the PM core would never know that all the - children of a device had been suspended if new children could be - registered at will. (By contrast, devices may be unregistered at any - time.) Unlike the other suspend-related phases, during the prepare - phase the device tree is traversed top-down. - - After the prepare callback method returns, no new children may be - registered below the device. The method may also prepare the device or - driver in some way for the upcoming system power transition, but it - should not put the device into a low-power state. - - For devices supporting runtime power management, the return value of the - prepare callback can be used to indicate to the PM core that it may - safely leave the device in runtime suspend (if runtime-suspended - already), provided that all of the device's descendants are also left in - runtime suspend. Namely, if the prepare callback returns a positive - number and that happens for all of the descendants of the device too, - and all of them (including the device itself) are runtime-suspended, the - PM core will skip the suspend, suspend_late and suspend_noirq suspend - phases as well as the resume_noirq, resume_early and resume phases of - the following system resume for all of these devices. In that case, - the complete callback will be called directly after the prepare callback - and is entirely responsible for bringing the device back to the - functional state as appropriate. - - Note that this direct-complete procedure applies even if the device is - disabled for runtime PM; only the runtime-PM status matters. It follows - that if a device has system-sleep callbacks but does not support runtime - PM, then its prepare callback must never return a positive value. This - is because all devices are initially set to runtime-suspended with - runtime PM disabled. - - 2. The suspend methods should quiesce the device to stop it from performing - I/O. They also may save the device registers and put it into the - appropriate low-power state, depending on the bus type the device is on, - and they may enable wakeup events. - - 3 For a number of devices it is convenient to split suspend into the - "quiesce device" and "save device state" phases, in which cases - suspend_late is meant to do the latter. It is always executed after - runtime power management has been disabled for all devices. - - 4. The suspend_noirq phase occurs after IRQ handlers have been disabled, - which means that the driver's interrupt handler will not be called while - the callback method is running. The methods should save the values of - the device's registers that weren't saved previously and finally put the - device into the appropriate low-power state. - - The majority of subsystems and device drivers need not implement this - callback. However, bus types allowing devices to share interrupt - vectors, like PCI, generally need it; otherwise a driver might encounter - an error during the suspend phase by fielding a shared interrupt - generated by some other device after its own device had been set to low - power. - -At the end of these phases, drivers should have stopped all I/O transactions -(DMA, IRQs), saved enough state that they can re-initialize or restore previous -state (as needed by the hardware), and placed the device into a low-power state. -On many platforms they will gate off one or more clock sources; sometimes they -will also switch off power supplies or reduce voltages. (Drivers supporting -runtime PM may already have performed some or all of these steps.) - -If device_may_wakeup(dev) returns true, the device should be prepared for -generating hardware wakeup signals to trigger a system wakeup event when the -system is in the sleep state. For example, enable_irq_wake() might identify -GPIO signals hooked up to a switch or other external hardware, and -pci_enable_wake() does something similar for the PCI PME signal. - -If any of these callbacks returns an error, the system won't enter the desired -low-power state. Instead the PM core will unwind its actions by resuming all -the devices that were suspended. - - -Leaving System Suspend ----------------------- -When resuming from freeze, standby or memory sleep, the phases are: - - resume_noirq, resume_early, resume, complete. - - 1. The resume_noirq callback methods should perform any actions needed - before the driver's interrupt handlers are invoked. This generally - means undoing the actions of the suspend_noirq phase. If the bus type - permits devices to share interrupt vectors, like PCI, the method should - bring the device and its driver into a state in which the driver can - recognize if the device is the source of incoming interrupts, if any, - and handle them correctly. - - For example, the PCI bus type's ->pm.resume_noirq() puts the device into - the full-power state (D0 in the PCI terminology) and restores the - standard configuration registers of the device. Then it calls the - device driver's ->pm.resume_noirq() method to perform device-specific - actions. - - 2. The resume_early methods should prepare devices for the execution of - the resume methods. This generally involves undoing the actions of the - preceding suspend_late phase. - - 3 The resume methods should bring the device back to its operating - state, so that it can perform normal I/O. This generally involves - undoing the actions of the suspend phase. - - 4. The complete phase should undo the actions of the prepare phase. Note, - however, that new children may be registered below the device as soon as - the resume callbacks occur; it's not necessary to wait until the - complete phase. - - Moreover, if the preceding prepare callback returned a positive number, - the device may have been left in runtime suspend throughout the whole - system suspend and resume (the suspend, suspend_late, suspend_noirq - phases of system suspend and the resume_noirq, resume_early, resume - phases of system resume may have been skipped for it). In that case, - the complete callback is entirely responsible for bringing the device - back to the functional state after system suspend if necessary. [For - example, it may need to queue up a runtime resume request for the device - for this purpose.] To check if that is the case, the complete callback - can consult the device's power.direct_complete flag. Namely, if that - flag is set when the complete callback is being run, it has been called - directly after the preceding prepare and special action may be required - to make the device work correctly afterward. - -At the end of these phases, drivers should be as functional as they were before -suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are -gated on. - -However, the details here may again be platform-specific. For example, -some systems support multiple "run" states, and the mode in effect at -the end of resume might not be the one which preceded suspension. -That means availability of certain clocks or power supplies changed, -which could easily affect how a driver works. - -Drivers need to be able to handle hardware which has been reset since the -suspend methods were called, for example by complete reinitialization. -This may be the hardest part, and the one most protected by NDA'd documents -and chip errata. It's simplest if the hardware state hasn't changed since -the suspend was carried out, but that can't be guaranteed (in fact, it usually -is not the case). - -Drivers must also be prepared to notice that the device has been removed -while the system was powered down, whenever that's physically possible. -PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses -where common Linux platforms will see such removal. Details of how drivers -will notice and handle such removals are currently bus-specific, and often -involve a separate thread. - -These callbacks may return an error value, but the PM core will ignore such -errors since there's nothing it can do about them other than printing them in -the system log. - - -Entering Hibernation --------------------- -Hibernating the system is more complicated than putting it into the other -sleep states, because it involves creating and saving a system image. -Therefore there are more phases for hibernation, with a different set of -callbacks. These phases always run after tasks have been frozen and memory has -been freed. - -The general procedure for hibernation is to quiesce all devices (freeze), create -an image of the system memory while everything is stable, reactivate all -devices (thaw), write the image to permanent storage, and finally shut down the -system (poweroff). The phases used to accomplish this are: - - prepare, freeze, freeze_late, freeze_noirq, thaw_noirq, thaw_early, - thaw, complete, prepare, poweroff, poweroff_late, poweroff_noirq - - 1. The prepare phase is discussed in the "Entering System Suspend" section - above. - - 2. The freeze methods should quiesce the device so that it doesn't generate - IRQs or DMA, and they may need to save the values of device registers. - However the device does not have to be put in a low-power state, and to - save time it's best not to do so. Also, the device should not be - prepared to generate wakeup events. - - 3. The freeze_late phase is analogous to the suspend_late phase described - above, except that the device should not be put in a low-power state and - should not be allowed to generate wakeup events by it. - - 4. The freeze_noirq phase is analogous to the suspend_noirq phase discussed - above, except again that the device should not be put in a low-power - state and should not be allowed to generate wakeup events. - -At this point the system image is created. All devices should be inactive and -the contents of memory should remain undisturbed while this happens, so that the -image forms an atomic snapshot of the system state. - - 5. The thaw_noirq phase is analogous to the resume_noirq phase discussed - above. The main difference is that its methods can assume the device is - in the same state as at the end of the freeze_noirq phase. - - 6. The thaw_early phase is analogous to the resume_early phase described - above. Its methods should undo the actions of the preceding - freeze_late, if necessary. - - 7. The thaw phase is analogous to the resume phase discussed above. Its - methods should bring the device back to an operating state, so that it - can be used for saving the image if necessary. - - 8. The complete phase is discussed in the "Leaving System Suspend" section - above. - -At this point the system image is saved, and the devices then need to be -prepared for the upcoming system shutdown. This is much like suspending them -before putting the system into the freeze, standby or memory sleep state, -and the phases are similar. - - 9. The prepare phase is discussed above. - - 10. The poweroff phase is analogous to the suspend phase. - - 11. The poweroff_late phase is analogous to the suspend_late phase. - - 12. The poweroff_noirq phase is analogous to the suspend_noirq phase. - -The poweroff, poweroff_late and poweroff_noirq callbacks should do essentially -the same things as the suspend, suspend_late and suspend_noirq callbacks, -respectively. The only notable difference is that they need not store the -device register values, because the registers should already have been stored -during the freeze, freeze_late or freeze_noirq phases. - - -Leaving Hibernation -------------------- -Resuming from hibernation is, again, more complicated than resuming from a sleep -state in which the contents of main memory are preserved, because it requires -a system image to be loaded into memory and the pre-hibernation memory contents -to be restored before control can be passed back to the image kernel. - -Although in principle, the image might be loaded into memory and the -pre-hibernation memory contents restored by the boot loader, in practice this -can't be done because boot loaders aren't smart enough and there is no -established protocol for passing the necessary information. So instead, the -boot loader loads a fresh instance of the kernel, called the boot kernel, into -memory and passes control to it in the usual way. Then the boot kernel reads -the system image, restores the pre-hibernation memory contents, and passes -control to the image kernel. Thus two different kernels are involved in -resuming from hibernation. In fact, the boot kernel may be completely different -from the image kernel: a different configuration and even a different version. -This has important consequences for device drivers and their subsystems. - -To be able to load the system image into memory, the boot kernel needs to -include at least a subset of device drivers allowing it to access the storage -medium containing the image, although it doesn't need to include all of the -drivers present in the image kernel. After the image has been loaded, the -devices managed by the boot kernel need to be prepared for passing control back -to the image kernel. This is very similar to the initial steps involved in -creating a system image, and it is accomplished in the same way, using prepare, -freeze, and freeze_noirq phases. However the devices affected by these phases -are only those having drivers in the boot kernel; other devices will still be in -whatever state the boot loader left them. - -Should the restoration of the pre-hibernation memory contents fail, the boot -kernel would go through the "thawing" procedure described above, using the -thaw_noirq, thaw, and complete phases, and then continue running normally. This -happens only rarely. Most often the pre-hibernation memory contents are -restored successfully and control is passed to the image kernel, which then -becomes responsible for bringing the system back to the working state. - -To achieve this, the image kernel must restore the devices' pre-hibernation -functionality. The operation is much like waking up from the memory sleep -state, although it involves different phases: - - restore_noirq, restore_early, restore, complete - - 1. The restore_noirq phase is analogous to the resume_noirq phase. - - 2. The restore_early phase is analogous to the resume_early phase. - - 3. The restore phase is analogous to the resume phase. - - 4. The complete phase is discussed above. - -The main difference from resume[_early|_noirq] is that restore[_early|_noirq] -must assume the device has been accessed and reconfigured by the boot loader or -the boot kernel. Consequently the state of the device may be different from the -state remembered from the freeze, freeze_late and freeze_noirq phases. The -device may even need to be reset and completely re-initialized. In many cases -this difference doesn't matter, so the resume[_early|_noirq] and -restore[_early|_norq] method pointers can be set to the same routines. -Nevertheless, different callback pointers are used in case there is a situation -where it actually does matter. - - -Device Power Management Domains -------------------------------- -Sometimes devices share reference clocks or other power resources. In those -cases it generally is not possible to put devices into low-power states -individually. Instead, a set of devices sharing a power resource can be put -into a low-power state together at the same time by turning off the shared -power resource. Of course, they also need to be put into the full-power state -together, by turning the shared power resource on. A set of devices with this -property is often referred to as a power domain. A power domain may also be -nested inside another power domain. The nested domain is referred to as the -sub-domain of the parent domain. - -Support for power domains is provided through the pm_domain field of struct -device. This field is a pointer to an object of type struct dev_pm_domain, -defined in include/linux/pm.h, providing a set of power management callbacks -analogous to the subsystem-level and device driver callbacks that are executed -for the given device during all power transitions, instead of the respective -subsystem-level callbacks. Specifically, if a device's pm_domain pointer is -not NULL, the ->suspend() callback from the object pointed to by it will be -executed instead of its subsystem's (e.g. bus type's) ->suspend() callback and -analogously for all of the remaining callbacks. In other words, power -management domain callbacks, if defined for the given device, always take -precedence over the callbacks provided by the device's subsystem (e.g. bus -type). - -The support for device power management domains is only relevant to platforms -needing to use the same device driver power management callbacks in many -different power domain configurations and wanting to avoid incorporating the -support for power domains into subsystem-level callbacks, for example by -modifying the platform bus type. Other platforms need not implement it or take -it into account in any way. - -Devices may be defined as IRQ-safe which indicates to the PM core that their -runtime PM callbacks may be invoked with disabled interrupts (see -Documentation/power/runtime_pm.txt for more information). If an IRQ-safe -device belongs to a PM domain, the runtime PM of the domain will be -disallowed, unless the domain itself is defined as IRQ-safe. However, it -makes sense to define a PM domain as IRQ-safe only if all the devices in it -are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime -PM of the parent is only allowed if the parent itself is IRQ-safe too with the -additional restriction that all child domains of an IRQ-safe parent must also -be IRQ-safe. - -Device Low Power (suspend) States ---------------------------------- -Device low-power states aren't standard. One device might only handle -"on" and "off", while another might support a dozen different versions of -"on" (how many engines are active?), plus a state that gets back to "on" -faster than from a full "off". - -Some busses define rules about what different suspend states mean. PCI -gives one example: after the suspend sequence completes, a non-legacy -PCI device may not perform DMA or issue IRQs, and any wakeup events it -issues would be issued through the PME# bus signal. Plus, there are -several PCI-standard device states, some of which are optional. - -In contrast, integrated system-on-chip processors often use IRQs as the -wakeup event sources (so drivers would call enable_irq_wake) and might -be able to treat DMA completion as a wakeup event (sometimes DMA can stay -active too, it'd only be the CPU and some peripherals that sleep). - -Some details here may be platform-specific. Systems may have devices that -can be fully active in certain sleep states, such as an LCD display that's -refreshed using DMA while most of the system is sleeping lightly ... and -its frame buffer might even be updated by a DSP or other non-Linux CPU while -the Linux control processor stays idle. - -Moreover, the specific actions taken may depend on the target system state. -One target system state might allow a given device to be very operational; -another might require a hard shut down with re-initialization on resume. -And two different target systems might use the same device in different -ways; the aforementioned LCD might be active in one product's "standby", -but a different product using the same SOC might work differently. - - -Power Management Notifiers --------------------------- -There are some operations that cannot be carried out by the power management -callbacks discussed above, because the callbacks occur too late or too early. -To handle these cases, subsystems and device drivers may register power -management notifiers that are called before tasks are frozen and after they have -been thawed. Generally speaking, the PM notifiers are suitable for performing -actions that either require user space to be available, or at least won't -interfere with user space. - -For details refer to Documentation/power/notifiers.txt. - - -Runtime Power Management -======================== -Many devices are able to dynamically power down while the system is still -running. This feature is useful for devices that are not being used, and -can offer significant power savings on a running system. These devices -often support a range of runtime power states, which might use names such -as "off", "sleep", "idle", "active", and so on. Those states will in some -cases (like PCI) be partially constrained by the bus the device uses, and will -usually include hardware states that are also used in system sleep states. - -A system-wide power transition can be started while some devices are in low -power states due to runtime power management. The system sleep PM callbacks -should recognize such situations and react to them appropriately, but the -necessary actions are subsystem-specific. - -In some cases the decision may be made at the subsystem level while in other -cases the device driver may be left to decide. In some cases it may be -desirable to leave a suspended device in that state during a system-wide power -transition, but in other cases the device must be put back into the full-power -state temporarily, for example so that its system wakeup capability can be -disabled. This all depends on the hardware and the design of the subsystem and -device driver in question. - -During system-wide resume from a sleep state it's easiest to put devices into -the full-power state, as explained in Documentation/power/runtime_pm.txt. Refer -to that document for more information regarding this particular issue as well as -for information on the device runtime power management framework in general. diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.txt index 85894d83b352..af005770e767 100644 --- a/Documentation/power/freezing-of-tasks.txt +++ b/Documentation/power/freezing-of-tasks.txt @@ -197,7 +197,8 @@ tasks, since it generally exists anyway. A driver must have all firmwares it may need in RAM before suspend() is called. If keeping them is not practical, for example due to their size, they must be -requested early enough using the suspend notifier API described in notifiers.txt. +requested early enough using the suspend notifier API described in +Documentation/driver-api/pm/notifiers.rst. VI. Are there any precautions to be taken to prevent freezing failures? diff --git a/Documentation/power/notifiers.txt b/Documentation/power/notifiers.txt deleted file mode 100644 index a81fa254303d..000000000000 --- a/Documentation/power/notifiers.txt +++ /dev/null @@ -1,55 +0,0 @@ -Suspend notifiers - (C) 2007-2011 Rafael J. Wysocki <rjw@sisk.pl>, GPL - -There are some operations that subsystems or drivers may want to carry out -before hibernation/suspend or after restore/resume, but they require the system -to be fully functional, so the drivers' and subsystems' .suspend() and .resume() -or even .prepare() and .complete() callbacks are not suitable for this purpose. -For example, device drivers may want to upload firmware to their devices after -resume/restore, but they cannot do it by calling request_firmware() from their -.resume() or .complete() routines (user land processes are frozen at these -points). The solution may be to load the firmware into memory before processes -are frozen and upload it from there in the .resume() routine. -A suspend/hibernation notifier may be used for this purpose. - -The subsystems or drivers having such needs can register suspend notifiers that -will be called upon the following events by the PM core: - -PM_HIBERNATION_PREPARE The system is going to hibernate, tasks will be frozen - immediately. This is different from PM_SUSPEND_PREPARE - below because here we do additional work between notifiers - and drivers freezing. - -PM_POST_HIBERNATION The system memory state has been restored from a - hibernation image or an error occurred during - hibernation. Device drivers' restore callbacks have - been executed and tasks have been thawed. - -PM_RESTORE_PREPARE The system is going to restore a hibernation image. - If all goes well, the restored kernel will issue a - PM_POST_HIBERNATION notification. - -PM_POST_RESTORE An error occurred during restore from hibernation. - Device drivers' restore callbacks have been executed - and tasks have been thawed. - -PM_SUSPEND_PREPARE The system is preparing for suspend. - -PM_POST_SUSPEND The system has just resumed or an error occurred during - suspend. Device drivers' resume callbacks have been - executed and tasks have been thawed. - -It is generally assumed that whatever the notifiers do for -PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously, -operations performed for PM_SUSPEND_PREPARE should be reversed for -PM_POST_SUSPEND. Additionally, all of the notifiers are called for -PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and -all of the notifiers are called for PM_POST_SUSPEND if one of them fails for -PM_SUSPEND_PREPARE. - -The hibernation and suspend notifiers are called with pm_mutex held. They are -defined in the usual way, but their last argument is meaningless (it is always -NULL). To register and/or unregister a suspend notifier use the functions -register_pm_notifier() and unregister_pm_notifier(), respectively, defined in -include/linux/suspend.h . If you don't need to unregister the notifier, you can -also use the pm_notifier() macro defined in include/linux/suspend.h . diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index 85c746cbab2c..a1b7f7158930 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -713,7 +713,7 @@ In addition to that the prepare() callback may carry out some operations preparing the device to be suspended, although it should not allocate memory (if additional memory is required to suspend the device, it has to be preallocated earlier, for example in a suspend/hibernate notifier as described -in Documentation/power/notifiers.txt). +in Documentation/driver-api/pm/notifiers.rst). 3.1.2. suspend() diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.txt index 129f7c0e1483..21d2d48f87a2 100644 --- a/Documentation/power/pm_qos_interface.txt +++ b/Documentation/power/pm_qos_interface.txt @@ -163,8 +163,7 @@ of flags and remove sysfs attributes pm_qos_no_power_off and pm_qos_remote_wakeu under the device's power directory. Notification mechanisms: -The per-device PM QoS framework has 2 different and distinct notification trees: -a per-device notification tree and a global notification tree. +The per-device PM QoS framework has a per-device notification tree. int dev_pm_qos_add_notifier(device, notifier): Adds a notification callback function for the device. @@ -174,16 +173,6 @@ is changed (for resume latency device PM QoS only). int dev_pm_qos_remove_notifier(device, notifier): Removes the notification callback function for the device. -int dev_pm_qos_add_global_notifier(notifier): -Adds a notification callback function in the global notification tree of the -framework. -The callback is called when the aggregated value for any device is changed -(for resume latency device PM QoS only). - -int dev_pm_qos_remove_global_notifier(notifier): -Removes the notification callback function from the global notification tree -of the framework. - Active state latency tolerance diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 4870980e967e..64546eb9a16a 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -100,7 +100,7 @@ knows what to do to handle the device). * If the suspend callback returns an error code different from -EBUSY and -EAGAIN, the PM core regards this as a fatal error and will refuse to run the helper functions described in Section 4 for the device until its status - is directly set to either'active', or 'suspended' (the PM core provides + is directly set to either 'active', or 'suspended' (the PM core provides special helper functions for this purpose). In particular, if the driver requires remote wakeup capability (i.e. hardware @@ -217,7 +217,7 @@ defined in include/linux/pm.h: one to complete spinlock_t lock; - - lock used for synchronisation + - lock used for synchronization atomic_t usage_count; - the usage counter of the device @@ -565,7 +565,7 @@ appropriate to ensure that the device is not put back to sleep during the probe. This can happen with systems such as the network device layer. It may be desirable to suspend the device once ->probe() has finished. -Therefore the driver core uses the asyncronous pm_request_idle() to submit a +Therefore the driver core uses the asynchronous pm_request_idle() to submit a request to execute the subsystem-level idle callback for the device at that time. A driver that makes use of the runtime autosuspend feature, may want to update the last busy mark before returning from ->probe(). diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt index 50022b3c8ebf..1fdbd5447216 100644 --- a/Documentation/pps/pps.txt +++ b/Documentation/pps/pps.txt @@ -63,7 +63,7 @@ for instance) is a PPS source too, and if not they should provide the possibility to open another device as PPS source. In LinuxPPS the PPS sources are simply char devices usually mapped -into files /dev/pps0, /dev/pps1, etc.. +into files /dev/pps0, /dev/pps1, etc. PPS with USB to serial devices @@ -71,9 +71,12 @@ PPS with USB to serial devices It is possible to grab the PPS from an USB to serial device. However, you should take into account the latencies and jitter introduced by -the USB stack. Users has reported clock instability around +-1ms when -synchronized with PPS through USB. This isn't suited for time server -synchronization. +the USB stack. Users have reported clock instability around +-1ms when +synchronized with PPS through USB. With USB 2.0, jitter may decrease +down to the order of 125 microseconds. + +This may be suitable for time server synchronization with NTP because +of its undersampling and algorithms. If your device doesn't report PPS, you can check that the feature is supported by its driver. Most of the time, you only need to add a call @@ -166,7 +169,8 @@ Testing the PPS support In order to test the PPS support even without specific hardware you can use the ktimer driver (see the client subsection in the PPS configuration menu) -and the userland tools provided in the Documentation/pps/ directory. +and the userland tools available in your distribution's pps-tools package, +http://linuxpps.org , or https://github.com/ago/pps-tools . Once you have enabled the compilation of ktimer just modprobe it (if not statically compiled): @@ -183,8 +187,8 @@ and the run ppstest as follow: source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0 source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0 -Please, note that to compile userland programs you need the file timepps.h -(see Documentation/pps/). +Please, note that to compile userland programs you need the file timepps.h . +This is available in the pps-tools repository mentioned above. Generators diff --git a/Documentation/s390/Debugging390.txt b/Documentation/s390/Debugging390.txt index 3df8babcdc41..5ae7f868a007 100644 --- a/Documentation/s390/Debugging390.txt +++ b/Documentation/s390/Debugging390.txt @@ -2116,7 +2116,7 @@ The sysrq key reading is very picky ( I have to type the keys in an This is particularly useful for syncing disks unmounting & rebooting if the machine gets partially hung. -Read Documentation/sysrq.txt for more info +Read Documentation/admin-guide/sysrq.rst for more info References: =========== diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 00ffdf187f0b..234ddabb23ef 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -549,7 +549,7 @@ ii. Reduced by 1 max cmds sent to FW from Driver to make the reply_q_sz same 3 Older Version : 00.00.03.02 i. Send stop adapter to FW & Dump pending FW cmds before declaring adapter dead. - New varible added to set dbg level. + New variable added to set dbg level. ii. Disable interrupt made as fn pointer as they are different for 1068 / 1078 iii. Frame count optimization. Main frame can contain 2 SGE for 64 bit SGLs and 3 SGE for 32 bit SGL diff --git a/Documentation/security/keys.txt b/Documentation/security/keys.txt index 3849814bfe6d..0e03baf271bd 100644 --- a/Documentation/security/keys.txt +++ b/Documentation/security/keys.txt @@ -1151,8 +1151,21 @@ access the data: usage. This is called key->payload.rcu_data0. The following accessors wrap the RCU calls to this element: - rcu_assign_keypointer(struct key *key, void *data); - void *rcu_dereference_key(struct key *key); + (a) Set or change the first payload pointer: + + rcu_assign_keypointer(struct key *key, void *data); + + (b) Read the first payload pointer with the key semaphore held: + + [const] void *dereference_key_locked([const] struct key *key); + + Note that the return value will inherit its constness from the key + parameter. Static analysis will give an error if it things the lock + isn't held. + + (c) Read the first payload pointer with the RCU read lock held: + + const void *dereference_key_rcu(const struct key *key); =================== diff --git a/Documentation/security/self-protection.txt b/Documentation/security/self-protection.txt index 3010576c9fca..141acfebe6ef 100644 --- a/Documentation/security/self-protection.txt +++ b/Documentation/security/self-protection.txt @@ -51,11 +51,17 @@ kernel, they are implemented in a way where the memory is temporarily made writable during the update, and then returned to the original permissions.) -In support of this are (the poorly named) CONFIG_DEBUG_RODATA and -CONFIG_DEBUG_SET_MODULE_RONX, which seek to make sure that code is not +In support of this are CONFIG_STRICT_KERNEL_RWX and +CONFIG_STRICT_MODULE_RWX, which seek to make sure that code is not writable, data is not executable, and read-only data is neither writable nor executable. +Most architectures have these options on by default and not user selectable. +For some architectures like arm that wish to have these be selectable, +the architecture Kconfig can select ARCH_OPTIONAL_KERNEL_RWX to enable +a Kconfig prompt. CONFIG_ARCH_OPTIONAL_KERNEL_RWX_DEFAULT determines +the default setting when ARCH_OPTIONAL_KERNEL_RWX is enabled. + #### Function pointers and sensitive variables must not be writable Vast areas of kernel memory contain function pointers that are looked diff --git a/Documentation/siphash.txt b/Documentation/siphash.txt new file mode 100644 index 000000000000..908d348ff777 --- /dev/null +++ b/Documentation/siphash.txt @@ -0,0 +1,175 @@ + SipHash - a short input PRF +----------------------------------------------- +Written by Jason A. Donenfeld <jason@zx2c4.com> + +SipHash is a cryptographically secure PRF -- a keyed hash function -- that +performs very well for short inputs, hence the name. It was designed by +cryptographers Daniel J. Bernstein and Jean-Philippe Aumasson. It is intended +as a replacement for some uses of: `jhash`, `md5_transform`, `sha_transform`, +and so forth. + +SipHash takes a secret key filled with randomly generated numbers and either +an input buffer or several input integers. It spits out an integer that is +indistinguishable from random. You may then use that integer as part of secure +sequence numbers, secure cookies, or mask it off for use in a hash table. + +1. Generating a key + +Keys should always be generated from a cryptographically secure source of +random numbers, either using get_random_bytes or get_random_once: + +siphash_key_t key; +get_random_bytes(&key, sizeof(key)); + +If you're not deriving your key from here, you're doing it wrong. + +2. Using the functions + +There are two variants of the function, one that takes a list of integers, and +one that takes a buffer: + +u64 siphash(const void *data, size_t len, const siphash_key_t *key); + +And: + +u64 siphash_1u64(u64, const siphash_key_t *key); +u64 siphash_2u64(u64, u64, const siphash_key_t *key); +u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key); +u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key); +u64 siphash_1u32(u32, const siphash_key_t *key); +u64 siphash_2u32(u32, u32, const siphash_key_t *key); +u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key); +u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key); + +If you pass the generic siphash function something of a constant length, it +will constant fold at compile-time and automatically choose one of the +optimized functions. + +3. Hashtable key function usage: + +struct some_hashtable { + DECLARE_HASHTABLE(hashtable, 8); + siphash_key_t key; +}; + +void init_hashtable(struct some_hashtable *table) +{ + get_random_bytes(&table->key, sizeof(table->key)); +} + +static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) +{ + return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; +} + +You may then iterate like usual over the returned hash bucket. + +4. Security + +SipHash has a very high security margin, with its 128-bit key. So long as the +key is kept secret, it is impossible for an attacker to guess the outputs of +the function, even if being able to observe many outputs, since 2^128 outputs +is significant. + +Linux implements the "2-4" variant of SipHash. + +5. Struct-passing Pitfalls + +Often times the XuY functions will not be large enough, and instead you'll +want to pass a pre-filled struct to siphash. When doing this, it's important +to always ensure the struct has no padding holes. The easiest way to do this +is to simply arrange the members of the struct in descending order of size, +and to use offsetendof() instead of sizeof() for getting the size. For +performance reasons, if possible, it's probably a good thing to align the +struct to the right boundary. Here's an example: + +const struct { + struct in6_addr saddr; + u32 counter; + u16 dport; +} __aligned(SIPHASH_ALIGNMENT) combined = { + .saddr = *(struct in6_addr *)saddr, + .counter = counter, + .dport = dport +}; +u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret); + +6. Resources + +Read the SipHash paper if you're interested in learning more: +https://131002.net/siphash/siphash.pdf + + +~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~ + +HalfSipHash - SipHash's insecure younger cousin +----------------------------------------------- +Written by Jason A. Donenfeld <jason@zx2c4.com> + +On the off-chance that SipHash is not fast enough for your needs, you might be +able to justify using HalfSipHash, a terrifying but potentially useful +possibility. HalfSipHash cuts SipHash's rounds down from "2-4" to "1-3" and, +even scarier, uses an easily brute-forcable 64-bit key (with a 32-bit output) +instead of SipHash's 128-bit key. However, this may appeal to some +high-performance `jhash` users. + +Danger! + +Do not ever use HalfSipHash except for as a hashtable key function, and only +then when you can be absolutely certain that the outputs will never be +transmitted out of the kernel. This is only remotely useful over `jhash` as a +means of mitigating hashtable flooding denial of service attacks. + +1. Generating a key + +Keys should always be generated from a cryptographically secure source of +random numbers, either using get_random_bytes or get_random_once: + +hsiphash_key_t key; +get_random_bytes(&key, sizeof(key)); + +If you're not deriving your key from here, you're doing it wrong. + +2. Using the functions + +There are two variants of the function, one that takes a list of integers, and +one that takes a buffer: + +u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key); + +And: + +u32 hsiphash_1u32(u32, const hsiphash_key_t *key); +u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key); +u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key); +u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key); + +If you pass the generic hsiphash function something of a constant length, it +will constant fold at compile-time and automatically choose one of the +optimized functions. + +3. Hashtable key function usage: + +struct some_hashtable { + DECLARE_HASHTABLE(hashtable, 8); + hsiphash_key_t key; +}; + +void init_hashtable(struct some_hashtable *table) +{ + get_random_bytes(&table->key, sizeof(table->key)); +} + +static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input) +{ + return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)]; +} + +You may then iterate like usual over the returned hash bucket. + +4. Performance + +HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements, +this will not be a problem, as the hashtable lookup isn't the bottleneck. And +in general, this is probably a good sacrifice to make for the security and DoS +resistance of HalfSipHash. diff --git a/Documentation/sound/hd-audio/dp-mst.rst b/Documentation/sound/hd-audio/dp-mst.rst index 58b72437e6c3..1617459e332f 100644 --- a/Documentation/sound/hd-audio/dp-mst.rst +++ b/Documentation/sound/hd-audio/dp-mst.rst @@ -19,6 +19,23 @@ PCM === To be added +Pin Initialization +================== +Each pin may have several device entries (virtual pins). On Intel platform, +the device entries number is dynamically changed. If DP MST hub is connected, +it is in DP MST mode, and the device entries number is 3. Otherwise, the +device entries number is 1. + +To simplify the implementation, all the device entries will be initialized +when bootup no matter whether it is in DP MST mode or not. + +Connection list +=============== +DP MST reuses connection list code. The code can be reused because +device entries on the same pin have the same connection list. + +This means DP MST gets the device entry connection list without the +device entry setting. Jack ==== diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst index 168d0cfab1ce..9eeb9b468706 100644 --- a/Documentation/sound/hd-audio/notes.rst +++ b/Documentation/sound/hd-audio/notes.rst @@ -697,7 +697,7 @@ If it's a regression, at best, send alsa-info outputs of both working and non-working kernels. This is really helpful because we can compare the codec registers directly. -Send a bug report either the followings: +Send a bug report either the following: kernel-bugzilla https://bugzilla.kernel.org/ diff --git a/Documentation/sparc/console.txt b/Documentation/sparc/console.txt new file mode 100644 index 000000000000..5aa735a44e02 --- /dev/null +++ b/Documentation/sparc/console.txt @@ -0,0 +1,9 @@ +Steps for sending 'break' on sunhv console: +=========================================== + +On Baremetal: + 1. press Esc + 'B' + +On LDOM: + 1. press Ctrl + ']' + 2. telnet> send break diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt index ea8d7b4e53f0..32a25fad0c1b 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/static-keys.txt @@ -155,7 +155,9 @@ or: There are a few functions and macros that architectures must implement in order to take advantage of this optimization. If there is no architecture support, we -simply fall back to a traditional, load, test, and jump sequence. +simply fall back to a traditional, load, test, and jump sequence. Also, the +struct jump_entry table must be at least 4-byte aligned because the +static_key->entry field makes use of the two least significant bits. * select HAVE_ARCH_JUMP_LABEL, see: arch/x86/Kconfig diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index a32b4b748644..bac23c198360 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -85,7 +85,7 @@ show up in /proc/sys/kernel: - softlockup_all_cpu_backtrace - soft_watchdog - stop-a [ SPARC only ] -- sysrq ==> Documentation/sysrq.txt +- sysrq ==> Documentation/admin-guide/sysrq.rst - sysctl_writes_strict - tainted - threads-max diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index f0480f7ea740..2ebabc93014a 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -54,6 +54,18 @@ Values : 1 - enable JIT hardening for unprivileged users only 2 - enable JIT hardening for all users +bpf_jit_kallsyms +---------------- + +When Berkeley Packet Filter Just in Time compiler is enabled, then compiled +images are unknown addresses to the kernel, meaning they neither show up in +traces nor in /proc/kallsyms. This enables export of these addresses, which +can be used for debugging/tracing. If bpf_jit_harden is enabled, this feature +is disabled. +Values : + 0 - disable JIT kallsyms export (default value) + 1 - enable JIT kallsyms export for privileged users only + dev_weight -------------- @@ -61,6 +73,27 @@ The maximum number of packets that kernel can handle on a NAPI interrupt, it's a Per-CPU variable. Default: 64 +dev_weight_rx_bias +-------------- + +RPS (e.g. RFS, aRFS) processing is competing with the registered NAPI poll function +of the driver for the per softirq cycle netdev_budget. This parameter influences +the proportion of the configured netdev_budget that is spent on RPS based packet +processing during RX softirq cycles. It is further meant for making current +dev_weight adaptable for asymmetric CPU needs on RX/TX side of the network stack. +(see dev_weight_tx_bias) It is effective on a per CPU basis. Determination is based +on dev_weight and is calculated multiplicative (dev_weight * dev_weight_rx_bias). +Default: 1 + +dev_weight_tx_bias +-------------- + +Scales the maximum number of packets that can be processed during a TX softirq cycle. +Effective on a per CPU basis. Allows scaling of current dev_weight for asymmetric +net stack processing needs. Be careful to avoid making TX softirq processing a CPU hog. +Calculation is based on dev_weight (dev_weight * dev_weight_tx_bias). +Default: 1 + default_qdisc -------------- diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 95ccbe6d79ce..b4ad97f10b8e 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -376,8 +376,8 @@ max_map_count: This file contains the maximum number of memory map areas a process may have. Memory map areas are used as a side-effect of calling -malloc, directly by mmap and mprotect, and also when loading shared -libraries. +malloc, directly by mmap, mprotect, and madvise, and also when loading +shared libraries. While most applications need less than a thousand maps, certain programs, particularly malloc debuggers, may consume lots of them, diff --git a/Documentation/thermal/nouveau_thermal b/Documentation/thermal/nouveau_thermal index 60bc29357ac3..6e17a11efcb0 100644 --- a/Documentation/thermal/nouveau_thermal +++ b/Documentation/thermal/nouveau_thermal @@ -42,7 +42,7 @@ thresholds can be configured thanks to the following HWMON attributes: * Critical: temp1_crit and temp1_crit_hyst; * Shutdown: temp1_emergency and temp1_emergency_hyst. -NOTE: Remember that the values are stored as milli degrees Celcius. Don't forget +NOTE: Remember that the values are stored as milli degrees Celsius. Don't forget to multiply! Fan management diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index e4991fb1eedc..41ef9d8efe95 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -12,7 +12,7 @@ kprobes can probe (this means, all functions body except for __kprobes functions). Unlike the Tracepoint based event, this can be added and removed dynamically, on the fly. -To enable this feature, build your kernel with CONFIG_KPROBE_EVENT=y. +To enable this feature, build your kernel with CONFIG_KPROBE_EVENTS=y. Similar to the events tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via diff --git a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl index 8f961ef2b457..ba976805853a 100644 --- a/Documentation/trace/postprocess/trace-vmscan-postprocess.pl +++ b/Documentation/trace/postprocess/trace-vmscan-postprocess.pl @@ -112,8 +112,8 @@ my $regex_direct_end_default = 'nr_reclaimed=([0-9]*)'; my $regex_kswapd_wake_default = 'nid=([0-9]*) order=([0-9]*)'; my $regex_kswapd_sleep_default = 'nid=([0-9]*)'; my $regex_wakeup_kswapd_default = 'nid=([0-9]*) zid=([0-9]*) order=([0-9]*)'; -my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_taken=([0-9]*) file=([0-9]*)'; -my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) zid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; +my $regex_lru_isolate_default = 'isolate_mode=([0-9]*) classzone_idx=([0-9]*) order=([0-9]*) nr_requested=([0-9]*) nr_scanned=([0-9]*) nr_skipped=([0-9]*) nr_taken=([0-9]*) lru=([a-z_]*)'; +my $regex_lru_shrink_inactive_default = 'nid=([0-9]*) nr_scanned=([0-9]*) nr_reclaimed=([0-9]*) nr_dirty=([0-9]*) nr_writeback=([0-9]*) nr_congested=([0-9]*) nr_immediate=([0-9]*) nr_activate=([0-9]*) nr_ref_keep=([0-9]*) nr_unmap_fail=([0-9]*) priority=([0-9]*) flags=([A-Z_|]*)'; my $regex_lru_shrink_active_default = 'lru=([A-Z_]*) nr_scanned=([0-9]*) nr_rotated=([0-9]*) priority=([0-9]*)'; my $regex_writepage_default = 'page=([0-9a-f]*) pfn=([0-9]*) flags=([A-Z_|]*)'; @@ -205,15 +205,15 @@ $regex_wakeup_kswapd = generate_traceevent_regex( $regex_lru_isolate = generate_traceevent_regex( "vmscan/mm_vmscan_lru_isolate", $regex_lru_isolate_default, - "isolate_mode", "order", - "nr_requested", "nr_scanned", "nr_taken", - "file"); + "isolate_mode", "classzone_idx", "order", + "nr_requested", "nr_scanned", "nr_skipped", "nr_taken", + "lru"); $regex_lru_shrink_inactive = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_inactive", $regex_lru_shrink_inactive_default, - "nid", "zid", - "nr_scanned", "nr_reclaimed", "priority", - "flags"); + "nid", "nr_scanned", "nr_reclaimed", "nr_dirty", "nr_writeback", + "nr_congested", "nr_immediate", "nr_activate", "nr_ref_keep", + "nr_unmap_fail", "priority", "flags"); $regex_lru_shrink_active = generate_traceevent_regex( "vmscan/mm_vmscan_lru_shrink_active", $regex_lru_shrink_active_default, @@ -381,8 +381,8 @@ EVENT_PROCESS: next; } my $isolate_mode = $1; - my $nr_scanned = $4; - my $file = $6; + my $nr_scanned = $5; + my $file = $8; # To closer match vmstat scanning statistics, only count isolate_both # and isolate_inactive as scanning. isolate_active is rotation @@ -391,7 +391,7 @@ EVENT_PROCESS: # isolate_both == 3 if ($isolate_mode != 2) { $perprocesspid{$process_pid}->{HIGH_NR_SCANNED} += $nr_scanned; - if ($file == 1) { + if ($file =~ /_file/) { $perprocesspid{$process_pid}->{HIGH_NR_FILE_SCANNED} += $nr_scanned; } else { $perprocesspid{$process_pid}->{HIGH_NR_ANON_SCANNED} += $nr_scanned; @@ -406,8 +406,8 @@ EVENT_PROCESS: next; } - my $nr_reclaimed = $4; - my $flags = $6; + my $nr_reclaimed = $3; + my $flags = $12; my $file = 0; if ($flags =~ /RECLAIM_WB_FILE/) { $file = 1; diff --git a/Documentation/trace/uprobetracer.txt b/Documentation/trace/uprobetracer.txt index fa7b680ee8a0..bf526a7c5559 100644 --- a/Documentation/trace/uprobetracer.txt +++ b/Documentation/trace/uprobetracer.txt @@ -7,7 +7,7 @@ Overview -------- Uprobe based trace events are similar to kprobe based trace events. -To enable this feature, build your kernel with CONFIG_UPROBE_EVENT=y. +To enable this feature, build your kernel with CONFIG_UPROBE_EVENTS=y. Similar to the kprobe-event tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via diff --git a/Documentation/translations/ja_JP/HOWTO b/Documentation/translations/ja_JP/HOWTO index b03fc8047f03..4ebd20750ef1 100644 --- a/Documentation/translations/ja_JP/HOWTO +++ b/Documentation/translations/ja_JP/HOWTO @@ -111,7 +111,7 @@ Linux カーネルソースツリーは幅広い範囲のドキュメントを カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの 変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報 をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を -linux-api@ver.kernel.org に送ることを勧めます。 +linux-api@vger.kernel.org に送ることを勧めます。 以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で す- diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 3b0c15b277e0..2333697251dd 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -289,8 +289,8 @@ pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세 Andrew Morton의 글이 있다. *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 - 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 - 배포되는 것은 아니기 때문이다."* + 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 + 배포되는 것은 아니기 때문이다."* 4.x.y - 안정 커널 트리 ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index a3228a676cc1..ce0b48d69eaa 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -662,6 +662,10 @@ include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를 컨트롤 의존성 ------------- +현재의 컴파일러들은 컨트롤 의존성을 이해하고 있지 않기 때문에 컨트롤 의존성은 +약간 다루기 어려울 수 있습니다. 이 섹션의 목적은 여러분이 컴파일러의 무시로 +인해 여러분의 코드가 망가지는 걸 막을 수 있도록 돕는겁니다. + 로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가 없어서 읽기 메모리 배리어를 필요로 합니다. 아래의 코드를 봅시다: @@ -689,20 +693,21 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q) { - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); } 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. 그렇다곤 -하나, READ_ONCE() 는 반드시 사용해야 함을 부디 명심하세요! READ_ONCE() 가 -없다면, 컴파일러가 'a' 로부터의 로드를 'a' 로부터의 또다른 로드와, 'b' 로의 -스토어를 'b' 로의 또다른 스토어와 조합해 버려 매우 비직관적인 결과를 초래할 수 -있습니다. +하나, READ_ONCE() 도 WRITE_ONCE() 도 선택사항이 아니라 필수사항임을 부디 +명심하세요! READ_ONCE() 가 없다면, 컴파일러는 'a' 로부터의 로드를 'a' 로부터의 +또다른 로드와 조합할 수 있습니다. WRITE_ONCE() 가 없다면, 컴파일러는 'b' 로의 +스토어를 'b' 로의 또라느 스토어들과 조합할 수 있습니다. 두 경우 모두 순서에 +있어 상당히 비직관적인 결과를 초래할 수 있습니다. 이걸로 끝이 아닌게, 컴파일러가 변수 'a' 의 값이 항상 0이 아니라고 증명할 수 있다면, 앞의 예에서 "if" 문을 없애서 다음과 같이 최적화 할 수도 있습니다: q = a; - b = p; /* BUG: Compiler and CPU can both reorder!!! */ + b = 1; /* BUG: Compiler and CPU can both reorder!!! */ 그러니 READ_ONCE() 를 반드시 사용하세요. @@ -712,11 +717,11 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q) { barrier(); - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something(); } else { barrier(); - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something_else(); } @@ -725,12 +730,12 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); barrier(); - WRITE_ONCE(b, p); /* BUG: No ordering vs. load from a!!! */ + WRITE_ONCE(b, 1); /* BUG: No ordering vs. load from a!!! */ if (q) { - /* WRITE_ONCE(b, p); -- moved up, BUG!!! */ + /* WRITE_ONCE(b, 1); -- moved up, BUG!!! */ do_something(); } else { - /* WRITE_ONCE(b, p); -- moved up, BUG!!! */ + /* WRITE_ONCE(b, 1); -- moved up, BUG!!! */ do_something_else(); } @@ -742,10 +747,10 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q) { - smp_store_release(&b, p); + smp_store_release(&b, 1); do_something(); } else { - smp_store_release(&b, p); + smp_store_release(&b, 1); do_something_else(); } @@ -754,10 +759,10 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q) { - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something(); } else { - WRITE_ONCE(b, r); + WRITE_ONCE(b, 2); do_something_else(); } @@ -770,10 +775,10 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q % MAX) { - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something(); } else { - WRITE_ONCE(b, r); + WRITE_ONCE(b, 2); do_something_else(); } @@ -781,7 +786,7 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 위의 코드를 아래와 같이 바꿔버릴 수 있습니다: q = READ_ONCE(a); - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something_else(); 이렇게 되면, CPU 는 변수 'a' 로부터의 로드와 변수 'b' 로의 스토어 사이의 순서를 @@ -793,10 +798,10 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */ if (q % MAX) { - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); do_something(); } else { - WRITE_ONCE(b, r); + WRITE_ONCE(b, 2); do_something_else(); } @@ -828,35 +833,33 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 q = READ_ONCE(a); if (q) { - WRITE_ONCE(b, p); + WRITE_ONCE(b, 1); } else { - WRITE_ONCE(b, r); + WRITE_ONCE(b, 2); } - WRITE_ONCE(c, 1); /* BUG: No ordering against the read from "a". */ + WRITE_ONCE(c, 1); /* BUG: No ordering against the read from 'a'. */ -컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 "b" +컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 'b' 로의 쓰기를 재배치 할 수 없기 때문에 여기에 순서 규칙이 존재한다고 주장하고 싶을 겁니다. 불행히도 이 경우에, 컴파일러는 다음의 가상의 pseudo-assembly 언어 -코드처럼 "b" 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로 +코드처럼 'b' 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로 번역할 수 있습니다: ld r1,a - ld r2,p - ld r3,r cmp r1,$0 - cmov,ne r4,r2 - cmov,eq r4,r3 + cmov,ne r4,$1 + cmov,eq r4,$2 st r4,b st $1,c -완화된 순서 규칙의 CPU 는 "a" 로부터의 로드와 "c" 로의 스토어 사이에 어떤 +완화된 순서 규칙의 CPU 는 'a' 로부터의 로드와 'c' 로의 스토어 사이에 어떤 종류의 의존성도 갖지 않을 겁니다. 이 컨트롤 의존성은 두개의 cmov 인스트럭션과 거기에 의존하는 스토어 에게만 적용될 겁니다. 짧게 말하자면, 컨트롤 의존성은 주어진 if 문의 then 절과 else 절에게만 (그리고 이 두 절 내에서 호출되는 함수들에게까지) 적용되지, 이 if 문을 뒤따르는 코드에는 적용되지 않습니다. 마지막으로, 컨트롤 의존성은 이행성 (transitivity) 을 제공하지 -않습니다-. 이건 -x 와 y 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로 +'x' 와 'y' 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로 보이겠습니다: CPU 0 CPU 1 @@ -924,6 +927,9 @@ http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf 와 (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-. 이행성이 필요하다면, smp_mb() 를 사용하세요. + (*) 컴파일러는 컨트롤 의존성을 이해하고 있지 않습니다. 따라서 컴파일러가 + 여러분의 코드를 망가뜨리지 않도록 하는건 여러분이 해야 하는 일입니다. + SMP 배리어 짝맞추기 -------------------- diff --git a/Documentation/translations/zh_CN/CodingStyle b/Documentation/translations/zh_CN/CodingStyle deleted file mode 100644 index dc101f48e713..000000000000 --- a/Documentation/translations/zh_CN/CodingStyle +++ /dev/null @@ -1,813 +0,0 @@ -Chinese translated version of Documentation/process/coding-style.rst - -If you have any comment or update to the content, please post to LKML directly. -However, if you have problem communicating in English you can also ask the -Chinese maintainer for help. Contact the Chinese maintainer, if this -translation is outdated or there is problem with translation. - -Chinese maintainer: Zhang Le <r0bertz@gentoo.org> ---------------------------------------------------------------------- -Documentation/process/coding-style.rst的中文翻译 - -如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 -以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 - -中文版维护者： 张乐 Zhang Le <r0bertz@gentoo.org> -中文版翻译者： 张乐 Zhang Le <r0bertz@gentoo.org> -中文版校译者： 王聪 Wang Cong <xiyou.wangcong@gmail.com> - wheelz <kernel.zeng@gmail.com> - 管旭东 Xudong Guan <xudong.guan@gmail.com> - Li Zefan <lizf@cn.fujitsu.com> - Wang Chen <wangchen@cn.fujitsu.com> -以下为正文 ---------------------------------------------------------------------- - - Linux内核代码风格 - -这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我 -不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也 -希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。 - -首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义 -的动作。 - -不管怎样，现在我们开始： - - - 第一章：缩进 - -制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！） -个字符深，这几乎相当于尝试将圆周率的值定义为 3。 - -理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕 -连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 - -现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端屏幕上 -就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用何种方式你 -的代码已经有问题了，应该修正你的程序。 - -简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的 -时候可以给你警告。留心这个警告。 - -在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签 -对齐于同一列，而不要 “两次缩进” “case” 标签。比如： - - switch (suffix) { - case 'G': - case 'g': - mem <<= 30; - break; - case 'M': - case 'm': - mem <<= 20; - break; - case 'K': - case 'k': - mem <<= 10; - /* fall through */ - default: - break; - } - -不要把多个语句放在一行里，除非你有什么东西要隐藏： - - if (condition) do_this; - do_something_everytime; - -也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表 -达式。 - -除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为之。 - -选用一个好的编辑器，不要在行尾留空格。 - - - 第二章：把长的行和字符串打散 - -代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 - -每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 - -长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不会隐藏 -信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表的函数头。 -然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这将导致无法 grep 这些 -信息。 - - 第三章：大括号和空格的放置 - -C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策 -略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示给我们的， -是把起始大括号放在行尾，而把结束大括号放在行首，所以： - - if (x is true) { - we do y - } - -这适用于所有的非函数语句块（if、switch、for、while、do）。比如： - - switch (action) { - case KOBJ_ADD: - return "add"; - case KOBJ_REMOVE: - return "remove"; - case KOBJ_CHANGE: - return "change"; - default: - return NULL; - } - -不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以： - - int function(int x) - { - body of function - } - -全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道 -(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C -函数是不能嵌套的）。 - -注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的 -“while” 或者 if 语句中的 “else”，像这样： - - do { - body of do-loop - } while (condition); - -和 - - if (x == y) { - .. - } else if (x > y) { - ... - } else { - .... - } - -理由：K&R。 - -也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可 -读性。因此，由于你的屏幕上的新行是不可再生资源（想想 25 行的终端屏幕），你将会有更 -多的空行来放置注释。 - -当只有一个单独的语句的时候，不用加不必要的大括号。 - - if (condition) - action(); - -和 - - if (condition) - do_this(); - else - do_that(); - -这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号： - - if (condition) { - do_this(); - do_that(); - } else { - otherwise(); - } - - 3.1：空格 - -Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后 -要加一个空格。值得注意的例外是 sizeof、typeof、alignof 和 __attribute__，这些 -关键字某些程度上看起来更像函数（它们在 Linux 里也常常伴随小括号而使用，尽管在 C 里 -这样的小括号不是必需的，就像 “struct fileinfo info” 声明过后的 “sizeof info”）。 - -所以在这些关键字之后放一个空格： - - if, switch, case, for, do, while - -但是不要在 sizeof、typeof、alignof 或者 __attribute__ 这些关键字之后放空格。例如， - - s = sizeof(struct file); - -不要在小括号里的表达式两侧加空格。这是一个反例： - - s = sizeof( struct file ); - -当声明指针类型或者返回指针类型的函数时，“*” 的首选使用方式是使之靠近变量名或者函 -数名，而不是靠近类型名。例子： - - char *linux_banner; - unsigned long long memparse(char *ptr, char **retptr); - char *match_strdup(substring_t *s); - -在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符： - - = + - < > * / % | & ^ <= >= == != ? : - -但是一元操作符后不要加空格： - - & * + - ~ ! sizeof typeof alignof __attribute__ defined - -后缀自加和自减一元操作符前不加空格： - - ++ -- - -前缀自加和自减一元操作符后不加空格： - - ++ -- - -‘.’ 和 “->” 结构体成员操作符前后不加空格。 - -不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你 -就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不 -会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就这样产 -生了。 - -当git发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白；不过 -如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的上下文。 - - - 第四章：命名 - -C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，C 程序员 -不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量 -为 “tmp”，这样写起来会更容易，而且至少不会令其难于理解。 - -不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字 -。称一个全局函数为 “foo” 是一个难以饶恕的错误。 - -全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函 -数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()” -或者类似的名字，你不应该叫它 “cntuser()”。 - -在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而 -且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。 - -本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器 -，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。 -类似的，“tmp” 可以用来称呼任意类型的临时变量。 - -如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症 -。请看第六章（函数）。 - - - 第五章：Typedef - -不要使用类似 “vps_t” 之类的东西。 - -对结构体和指针使用 typedef 是一个错误。当你在代码里看到： - - vps_t a; - -这代表什么意思呢？ - -相反，如果是这样 - - struct virtual_container *a; - -你就知道 “a” 是什么了。 - -很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用： - - (a) 完全不透明的对象（这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么）。 - - 例如：“pte_t” 等不透明对象，你只能用合适的访问函数来访问它们。 - - 注意！不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是 - 完全没有任何共用的可访问信息。 - - (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。 - - u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。 - - 再次注意！要这样做，必须事出有因。如果某个变量是 “unsigned long“，那么没有必要 - - typedef unsigned long myflags_t; - - 不过如果有一个明确的原因，比如它在某种情况下可能会是一个 “unsigned int” 而在 - 其他情况下可能为 “unsigned long”，那么就不要犹豫，请务必使用 typedef。 - - (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。 - - (d) 和标准C99类型相同的类型，在某些例外的情况下。 - - 虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间，可是有些 - 人仍然拒绝使用它们。 - - 因此，Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被 - 允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 - - 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。 - - (e) 可以在用户空间安全使用的类型。 - - 在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的 “u32” - 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。 - -可能还有其他的情况，不过基本的规则是永远不要使用 typedef，除非你可以明确的应用上 -述某个规则中的一个。 - -总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不 -应该是一个 typedef。 - - - 第六章：函数 - -函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知 -道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。 - -一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上 -很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做 -很多很小的事情，这样的函数尽管很长，但也是可以的。 - -不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至 -搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之 -取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的 -效果往往会比你写一个复杂函数的效果要好。） - -函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有 -问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟 -踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你 -2 个星期前做过的事情。 - -在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴 -在它的结束大括号之下。比如： - - int system_is_up(void) - { - return system_state == SYSTEM_RUNNING; - } - EXPORT_SYMBOL(system_is_up); - -在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在 Linux 里这 -是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 - - - 第七章：集中的函数退出途径 - -虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是 -无条件跳转指令。 - -当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。 -如果并不需要清理操作，那么直接 return 即可。 - -理由是： - -- 无条件语句容易理解和跟踪 -- 嵌套程度减小 -- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误 -- 减轻了编译器的工作，无需删除冗余代码;) - - int fun(int a) - { - int result = 0; - char *buffer; - - buffer = kmalloc(SIZE, GFP_KERNEL); - if (!buffer) - return -ENOMEM; - - if (condition1) { - while (loop1) { - ... - } - result = 1; - goto out_buffer; - } - ... - out_buffer: - kfree(buffer); - return result; - } - -一个需要注意的常见错误是“一个 err 错误”，就像这样： - - err: - kfree(foo->bar); - kfree(foo); - return ret; - -这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个 -错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。 - - 第八章：注释 - -注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好 -的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 - -一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释 -放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到 -第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要 -加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这 -些事情的原因。 - -当注释内核API函数时，请使用 kernel-doc 格式。请看 -Documentation/doc-guide/和scripts/kernel-doc 以获得详细信息。 - -Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。 - -长（多行）的首选注释风格是： - - /* - * This is the preferred style for multi-line - * comments in the Linux kernel source code. - * Please use it consistently. - * - * Description: A column of asterisks on the left side, - * with beginning and ending almost-blank lines. - */ - -对于在 net/ 和 drivers/net/ 的文件，首选的长（多行）注释风格有些不同。 - - /* The preferred comment style for files in net/ and drivers/net - * looks like this. - * - * It is nearly the same as the generally preferred comment style, - * but there is no initial almost-blank line. - */ - -注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只 -声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段 -小注释来解释它们的用途了。 - - - 第九章：你已经把事情弄糟了 - -这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能 -自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们 -想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不 -会创造出一个好程序）（译注：请参考 Infinite Monkey Theorem） - -所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可 -以把下面这段粘贴到你的 .emacs 文件里。 - -(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"))))) - -这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。 - -不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用 -“indent”。 - -不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不 -过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是 -坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8” -（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式 -缩进源代码。 - -“indent” 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过 -记住：“indent” 不能修正坏的编程习惯。 - - - 第十章：Kconfig 配置文件 - -对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式与 C 代码相比有所不同。紧挨 -在 “config” 定义下面的行缩进一个制表符，帮助信息则再多缩进 2 个空格。比如： - -config AUDIT - bool "Auditing support" - depends on NET - help - Enable auditing infrastructure that can be used with another - kernel subsystem, such as SELinux (which requires this for - logging of avc messages output). Does not do system-call - auditing without CONFIG_AUDITSYSCALL. - -而那些危险的功能（比如某些文件系统的写支持）应该在它们的提示字符串里显著的声明这 -一点： - -config ADFS_FS_RW - bool "ADFS write support (DANGEROUS)" - depends on ADFS_FS - ... - -要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。 - - - 第十一章：数据结构 - -如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引用计 -数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这意味着你绝对需 -要记录你对这种数据结构的使用情况。 - -引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要担心 -这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或者做了一 -些其他事情而已。 - -注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一个内存管 -理技巧。通常二者都需要，不要把两个搞混了。 - -很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用 -户的数量，每当子类计数器减至零时，全局计数器减一。 - -这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users 和 mm_count） -和文件系统（“struct super_block”：s_count和s_active）中找到。 - -记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这 -里几乎肯定是一个 bug。 - - - 第十二章：宏，枚举和RTL - -用于定义常量的宏的名字及枚举里的标签需要大写。 - -#define CONSTANT 0x12345 - -在定义几个相关的常量时，最好用枚举。 - -宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 - -一般的，如果能写成内联函数就不要写成像函数的宏。 - -含有多个语句的宏应该被包含在一个 do-while 代码块里： - - #define macrofun(a, b, c) \ - do { \ - if (a == 5) \ - do_this(b, c); \ - } while (0) - -使用宏的时候应避免的事情： - -1) 影响控制流程的宏： - - #define FOO(x) \ - do { \ - if (blah(x) < 0) \ - return -EBUGGERED; \ - } while (0) - -非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里 -的语法分析器。 - -2) 依赖于一个固定名字的本地变量的宏： - - #define FOO(val) bar(index, val) - -可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来 -不相关的改动带来错误。 - -3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这种用 -法就会出错了。 - -4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的 -宏也要注意此类问题。 - - #define CONSTANT 0x4000 - #define CONSTEXP (CONSTANT | 3) - -5) 在宏里定义类似函数的本地变量时命名冲突： - - #define FOO(x) \ - ({ \ - typeof(x) ret; \ - ret = calc_ret(x); \ - (ret); \ - }) - -ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 - -cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL（译注：register -transfer language），内核里的汇编语言经常用到它。 - - - 第十三章：打印内核消息 - -内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。不要 -用不规范的单词比如 “dont”，而要用 “do not”或者 “don't”。保证这些信息简单、明了、 -无歧义。 - -内核信息不必以句号（译注：英文句号，即点）结束。 - -在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。 - -<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的 -设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err()，dev_warn()， -dev_info() 等等。对于那些不和某个特定设备相关连的信息，<linux/printk.h> 定义了 -pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。 - -写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提供极大 -的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() 函数能无条件地 -打印，pr_debug() 却不；默认情况下它不会被编译，除非定义了 DEBUG 或设定了 -CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一个已经开启了 -DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 - -许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 -情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如，如果 -已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 - - - 第十四章：分配内存 - -内核提供了下面的一般用途的内存分配函数： -kmalloc()，kzalloc()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。 -请参考 API 文档以获取有关它们的详细信息。 - -传递结构体大小的首选形式是这样的： - - p = kmalloc(sizeof(*p), ...); - -另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能会引 -入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof 的结果不变。 - -强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型 -的转换是没有问题的。 - -分配一个数组的首选形式是这样的： - - p = kmalloc_array(n, sizeof(...), ...); - -分配一个零长数组的首选形式是这样的： - - p = kcalloc(n, sizeof(...), ...); - -两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 - - - 第十五章：内联弊病 - -有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联 -函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是 -这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核 -会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导 -致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址， -将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。 - -一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例 -外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能 -优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就 -是一个很好的例子。 - -人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失，因为没 -有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 inline gcc -也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的争论会抵消 inline -自身的潜在价值，得不偿失。 - - - 第十六章：函数返回值及命名 - -函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 -的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（ -0＝失败，非0＝成功）。 - -混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变 -量，那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug，请 -遵循下面的惯例： - - 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整 - 数。如果是一个判断，那么函数应该返回一个“成功”布尔值。 - -比如，“add work” 是一个命令，所以 add_work() 函数在成功时返回 0，在失败时返回 -EBUSY。 -类似的，因为 “PCI device present” 是一个判断，所以 pci_dev_present() 函数在成功找到 -一个匹配的设备时应该返回 1，如果找不到时应该返回 0。 - -所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私 -有（static）函数不需要如此，但是我们也推荐这样做。 - -返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们 -通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用 -NULL 或者 ERR_PTR 机制来报告错误。 - - - 第十七章：不要重新发明内核宏 - -头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些它们的 -变种。比如，如果你需要计算一个数组的长度，使用这个宏 - - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) - -类似的，如果你要计算某结构体成员的大小，使用 - - #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) - -还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以自己看看 -那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里 -自己重新定义。 - - - 第十八章：编辑器模式行和其他需要罗嗦的事情 - -有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs -能够解释被标记成这样的行： - - -*- mode: c -*- - -或者这样的： - - /* - Local Variables: - compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" - End: - */ - -Vim 能够解释这样的标记： - - /* vim:set sw=8 noet */ - -不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应 -该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模 -式，或者使用其他可以产生正确的缩进的巧妙方法。 - - - 第十九章：内联汇编 - -在特定架构的代码中，你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要 -这么做时，不要犹豫。然而，当 C 可以完成工作时，不要无端地使用内联汇编。如果 -可能，你可以并且应该用 C 和硬件交互。 - -考虑去写通用一点的内联汇编作为简明的辅助函数，而不是重复写下它们的细节。记住 -内联汇编可以使用 C 参数。 - -大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编 -函数的 C 原型应该使用 “asmlinkage”。 - -你可能需要将你的汇编语句标记为 volatile，来阻止 GCC 在没发现任何副作用后就 -移除了它。你不必总是这样做，虽然，这样可以限制不必要的优化。 - -在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号字符串分离，并写在 -单独一行，在每个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下 -一条指令： - - asm ("magic %reg1, #42\n\t" - "more_magic %reg2, %reg3" - : /* outputs */ : /* inputs */ : /* clobbers */); - - - 第二十章：条件编译 - -只要可能，就不要在 .c 文件里面使用预处理条件；这样做让代码更难阅读并且逻辑难以 -跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的条件表达式，提供空 -操作的桩版本（译注：桩程序，是指用来替换一部分功能的程序段）在 #else 情况下， -再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码，产生一致 -的结果，但逻辑将更加清晰。 - -宁可编译整个函数，而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef， -解析部分或全部表达式到一个单独的辅助函数，并应用条件到该函数内。 - -如果你有一个在特定配置中可能是未使用的函数或变量，编译器将警告它定义了但未使用， -标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。（然而，如果 -一个函数或变量总是未使用的，就直接删除它。） - -在代码中，可能的情况下，使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 -表达式，并在正常的 C 条件中使用它： - - if (IS_ENABLED(CONFIG_SOMETHING)) { - ... - } - -编译器会无条件地做常数合并，就像使用 #ifdef 那样，包含或排除代码块，所以这不会 -带来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正确 -性（语法，类型，符号引用，等等）。因此，如果条件不满足，代码块内的引用符号将不存在， -你必须继续使用 #ifdef。 - -在任何有意义的 #if 或 #ifdef 块的末尾（超过几行），在 #endif 同一行的后面写下 -注释，指出该条件表达式被使用。例如： - - #ifdef CONFIG_SOMETHING - ... - #endif /* CONFIG_SOMETHING */ - - - 附录 I：参考 - -The C Programming Language, 第二版 -作者：Brian W. Kernighan 和 Denni M. Ritchie. -Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). - -The Practice of Programming -作者：Brian W. Kernighan 和 Rob Pike. -Addison-Wesley, Inc., 1999. -ISBN 0-201-61586-X. - -GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, -都可以从 http://www.gnu.org/manual/ 找到 - -WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ - -Kernel process/coding-style.rst，作者 greg@kroah.com 发表于OLS 2002： -http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_CN/coding-style.rst b/Documentation/translations/zh_CN/coding-style.rst new file mode 100644 index 000000000000..1466aa64b8b4 --- /dev/null +++ b/Documentation/translations/zh_CN/coding-style.rst @@ -0,0 +1,950 @@ +Chinese translated version of Documentation/process/coding-style.rst + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Zhang Le <r0bertz@gentoo.org> + +--------------------------------------------------------------------- + +Documentation/process/coding-style.rst 的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话， +也可以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版 +维护者:: + + 中文版维护者： 张乐 Zhang Le <r0bertz@gentoo.org> + 中文版翻译者： 张乐 Zhang Le <r0bertz@gentoo.org> + 中文版校译者： 王聪 Wang Cong <xiyou.wangcong@gmail.com> + wheelz <kernel.zeng@gmail.com> + 管旭东 Xudong Guan <xudong.guan@gmail.com> + Li Zefan <lizf@cn.fujitsu.com> + Wang Chen <wangchen@cn.fujitsu.com> + +以下为正文 + +--------------------------------------------------------------------- + +Linux 内核代码风格 +========================= + +这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的， +而且我不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则 +那样，我也希望在绝大多数事上保持这种的态度。请 (在写代码时) 至少考虑一下这里 +的代码风格。 + +首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征 +性意义的动作。 + +不管怎样，现在我们开始： + + +1) 缩进 +-------------- + +制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4 (甚至 +2！) 字符深，这几乎相当于尝试将圆周率的值定义为 3。 + +理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的 +屏幕连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。 + +现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端 +屏幕上就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用 +何种方式你的代码已经有问题了，应该修正你的程序。 + +简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太 +深的时候可以给你警告。留心这个警告。 + +在 switch 语句中消除多级缩进的首选的方式是让 ``switch`` 和从属于它的 ``case`` +标签对齐于同一列，而不要 ``两次缩进`` ``case`` 标签。比如： + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + +不要把多个语句放在一行里，除非你有什么东西要隐藏： + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读 +的表达式。 + +除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为 +之。 + +选用一个好的编辑器，不要在行尾留空格。 + + +2) 把长的行和字符串打散 +------------------------------ + +代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。 + +每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。 + +长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不 +会隐藏信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表 +的函数头。然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这样就 +很难对它们 grep。 + + +3) 大括号和空格的放置 +------------------------------ + +C 语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放 +置策略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示 +给我们的，是把起始大括号放在行尾，而把结束大括号放在行首，所以： + +.. code-block:: c + + if (x is true) { + we do y + } + +这适用于所有的非函数语句块 (if, switch, for, while, do)。比如： + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以： + +.. code-block:: c + + int function(int x) + { + body of function + } + +全世界的异端可能会抱怨这个不一致性是... 呃... 不一致的，不过所有思维健全的人 +都知道 (a) K&R 是 **正确的** 并且 (b) K&R 是正确的。此外，不管怎样函数都是特 +殊的 (C 函数是不能嵌套的)。 + +注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语 +句中的 "while" 或者 if 语句中的 "else"，像这样： + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +和 + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +理由：K&R。 + +也请注意这种大括号的放置方式也能使空 (或者差不多空的) 行的数量最小化，同时不 +失可读性。因此，由于你的屏幕上的新行是不可再生资源 (想想 25 行的终端屏幕)，你 +将会有更多的空行来放置注释。 + +当只有一个单独的语句的时候，不用加不必要的大括号。 + +.. code-block:: c + + if (condition) + action(); + +和 + +.. code-block:: c + + if (condition) + do_this(); + else + do_that(); + +这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号： + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +3.1) 空格 +******************** + +Linux 内核的空格使用方式 (主要) 取决于它是用于函数还是关键字。(大多数) 关键字 +后要加一个空格。值得注意的例外是 sizeof, typeof, alignof 和 __attribute__，这 +些关键字某些程度上看起来更像函数 (它们在 Linux 里也常常伴随小括号而使用，尽管 +在 C 里这样的小括号不是必需的，就像 ``struct fileinfo info;`` 声明过后的 +``sizeof info``)。 + +所以在这些关键字之后放一个空格:: + + if, switch, case, for, do, while + +但是不要在 sizeof, typeof, alignof 或者 __attribute__ 这些关键字之后放空格。 +例如， + +.. code-block:: c + + s = sizeof(struct file); + +不要在小括号里的表达式两侧加空格。这是一个 **反例** ： + +.. code-block:: c + + s = sizeof( struct file ); + +当声明指针类型或者返回指针类型的函数时， ``*`` 的首选使用方式是使之靠近变量名 +或者函数名，而不是靠近类型名。例子： + +.. code-block:: c + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符:: + + = + - < > * / % | & ^ <= >= == != ? : + +但是一元操作符后不要加空格:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +后缀自加和自减一元操作符前不加空格:: + + ++ -- + +前缀自加和自减一元操作符后不加空格:: + + ++ -- + +``.`` 和 ``->`` 结构体成员操作符前后不加空格。 + +不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后 +你就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器 +就不会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就 +这样产生了。 + +当 git 发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白； +不过如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的 +上下文。 + + +4) 命名 +------------------------------ + +C 是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同， +C 程序员不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会 +称那个变量为 ``tmp`` ，这样写起来会更容易，而且至少不会令其难于理解。 + +不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的 +名字。称一个全局函数为 ``foo`` 是一个难以饶恕的错误。 + +全局变量 (只有当你 **真正** 需要它们的时候再用它) 需要有一个具描述性的名字，就 +像全局函数。如果你有一个可以计算活动用户数量的函数，你应该叫它 +``count_active_users()`` 或者类似的名字，你不应该叫它 ``cntuser()`` 。 + +在函数名中包含函数类型 (所谓的匈牙利命名法) 是脑子出了问题——编译器知道那些类 +型而且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题 +的程序。 + +本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计 +数器，它应该被称为 ``i`` 。叫它 ``loop_counter`` 并无益处，如果它没有被误解的 +可能的话。类似的， ``tmp`` 可以用来称呼任意类型的临时变量。 + +如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综 +合症。请看第六章 (函数)。 + + +5) Typedef +----------- + +不要使用类似 ``vps_t`` 之类的东西。 + +对结构体和指针使用 typedef 是一个 **错误** 。当你在代码里看到： + +.. code-block:: c + + vps_t a; + +这代表什么意思呢？ + +相反，如果是这样 + +.. code-block:: c + + struct virtual_container *a; + +你就知道 ``a`` 是什么了。 + +很多人认为 typedef ``能提高可读性`` 。实际不是这样的。它们只在下列情况下有用： + + (a) 完全不透明的对象 (这种情况下要主动使用 typedef 来 **隐藏** 这个对象实际上 + 是什么)。 + + 例如： ``pte_t`` 等不透明对象，你只能用合适的访问函数来访问它们。 + + .. note:: + + 不透明性和 "访问函数" 本身是不好的。我们使用 pte_t 等类型的原因在于真 + 的是完全没有任何共用的可访问信息。 + + (b) 清楚的整数类型，如此，这层抽象就可以 **帮助** 消除到底是 ``int`` 还是 + ``long`` 的混淆。 + + u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。 + + .. note:: + + 要这样做，必须事出有因。如果某个变量是 ``unsigned long`` ，那么没有必要 + + typedef unsigned long myflags_t; + + 不过如果有一个明确的原因，比如它在某种情况下可能会是一个 ``unsigned int`` + 而在其他情况下可能为 ``unsigned long`` ，那么就不要犹豫，请务必使用 + typedef。 + + (c) 当你使用 sparse 按字面的创建一个 **新** 类型来做类型检查的时候。 + + (d) 和标准 C99 类型相同的类型，在某些例外的情况下。 + + 虽然让眼睛和脑筋来适应新的标准类型比如 ``uint32_t`` 不需要花很多时间，可 + 是有些人仍然拒绝使用它们。 + + 因此，Linux 特有的等同于标准类型的 ``u8/u16/u32/u64`` 类型和它们的有符号 + 类型是被允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。 + + 当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选 + 择。 + + (e) 可以在用户空间安全使用的类型。 + + 在某些用户空间可见的结构体里，我们不能要求 C99 类型而且不能用上面提到的 + ``u32`` 类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似 + 的类型。 + +可能还有其他的情况，不过基本的规则是 **永远不要** 使用 typedef，除非你可以明 +确的应用上述某个规则中的一个。 + +总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们 +就不应该是一个 typedef。 + + +6) 函数 +------------------------------ + +函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完 (我们 +都知道 ISO/ANSI 屏幕大小是 80x24)，只做一件事情，而且把它做好。 + +一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理 +论上很简单的只有一个很长 (但是简单) 的 case 语句的函数，而且你需要在每个 case +里做很多很小的事情，这样的函数尽管很长，但也是可以的。 + +不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能 +甚至搞不清楚这个函数的目的，你应该严格遵守前面提到的长度限制。使用辅助函数， +并为之取个具描述性的名字 (如果你觉得它们的性能很重要的话，可以让编译器内联它 +们，这样的效果往往会比你写一个复杂函数的效果要好。) + +函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数 +就有问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松 +的同时跟踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可 +能会记不清你 2 个星期前做过的事情。 + +在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 **EXPORT** 宏 +应该紧贴在它的结束大括号之下。比如： + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +在函数原型中，包含函数名和它们的数据类型。虽然 C 语言里没有这样的要求，在 +Linux 里这是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。 + + +7) 集中的函数退出途径 +------------------------------ + +虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体 +形式是无条件跳转指令。 + +当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方 +便了。如果并不需要清理操作，那么直接 return 即可。 + +选择一个能够说明 goto 行为或它为何存在的标签名。如果 goto 要释放 ``buffer``, +一个不错的名字可以是 ``out_free_buffer:`` 。别去使用像 ``err1:`` 和 ``err2:`` +这样的GW_BASIC 名称，因为一旦你添加或删除了 (函数的) 退出路径，你就必须对它们 +重新编号，这样会难以去检验正确性。 + +使用 goto 的理由是： + +- 无条件语句容易理解和跟踪 +- 嵌套程度减小 +- 可以避免由于修改时忘记更新个别的退出点而导致错误 +- 让编译器省去删除冗余代码的工作 ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_free_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +一个需要注意的常见错误是 ``一个 err 错误`` ，就像这样： + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +这段代码的错误是，在某些退出路径上 ``foo`` 是 NULL。通常情况下，通过把它分离 +成两个错误标签 ``err_free_bar:`` 和 ``err_free_foo:`` 来修复这个错误： + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +理想情况下，你应该模拟错误来测试所有退出路径。 + + +8) 注释 +------------------------------ + +注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的： +更好的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。 + +一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把 +注释放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能 +需要回到第六章看一看。你可以做一些小注释来注明或警告某些很聪明 (或者槽糕) 的 +做法，但不要加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么， +也可以加上它做这些事情的原因。 + +当注释内核 API 函数时，请使用 kernel-doc 格式。请看 +Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。 + +长 (多行) 注释的首选风格是： + +.. code-block:: c + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +对于在 net/ 和 drivers/net/ 的文件，首选的长 (多行) 注释风格有些不同。 + +.. code-block:: c + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + +注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行 +应只声明一个数据 (不要使用逗号来一次声明多个数据)。这样你就有空间来为每个数据 +写一段小注释来解释它们的用途了。 + + +9) 你已经把事情弄糟了 +------------------------------ + +这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 +``GNU emacs`` 能自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它 +所使用的默认值和我们想要的相去甚远 (实际上，甚至比随机打的还要差——无数个猴子 +在 GNU emacs 里打字永远不会创造出一个好程序) (译注：Infinite Monkey Theorem) + +所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案， +你可以把下面这段粘贴到你的 .emacs 文件里。 + +.. 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"))))) + +这会让 emacs 在 ``~/src/linux-trees`` 下的 C 源文件获得更好的内核代码风格。 + +不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可 +以用 ``indent`` 。 + +不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选 +项。不过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性 +(GNU 的人并不是坏人，他们只是在这个问题上被严重的误导了)，所以你只要给 indent +指定选项 ``-kr -i8`` (代表 ``K&R，8 字符缩进``)，或使用 ``scripts/Lindent`` +这样就可以以最时髦的方式缩进源代码。 + +``indent`` 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册。 +不过记住： ``indent`` 不能修正坏的编程习惯。 + + +10) Kconfig 配置文件 +------------------------------ + +对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式有所不同。紧挨着 +``config`` 定义的行，用一个制表符缩进，然而 help 信息的缩进则额外增加 2 个空 +格。举个例子:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +而那些危险的功能 (比如某些文件系统的写支持) 应该在它们的提示字符串里显著的声 +明这一点:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。 + + +11) 数据结构 +------------------------------ + +如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引 +用计数器。内核里没有垃圾收集 (并且内核之外的垃圾收集慢且效率低下)，这意味着你 +绝对需要记录你对这种数据结构的使用情况。 + +引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要 +担心这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或 +者做了一些其他事情而已。 + +注意上锁 **不能** 取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一 +个内存管理技巧。通常二者都需要，不要把两个搞混了。 + +很多数据结构实际上有 2 级引用计数，它们通常有不同 ``类`` 的用户。子类计数器统 +计子类用户的数量，每当子类计数器减至零时，全局计数器减一。 + +这种 ``多级引用计数`` 的例子可以在内存管理 (``struct mm_struct``: mm_users 和 +mm_count)，和文件系统 (``struct super_block``: s_count 和 s_active) 中找到。 + +记住：如果另一个执行线索可以找到你的数据结构，但这个数据结构没有引用计数器， +这里几乎肯定是一个 bug。 + + +12) 宏，枚举和RTL +------------------------------ + +用于定义常量的宏的名字及枚举里的标签需要大写。 + +.. code-block:: c + + #define CONSTANT 0x12345 + +在定义几个相关的常量时，最好用枚举。 + +宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。 + +一般的，如果能写成内联函数就不要写成像函数的宏。 + +含有多个语句的宏应该被包含在一个 do-while 代码块里： + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +使用宏的时候应避免的事情： + +1) 影响控制流程的宏： + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +**非常** 不好。它看起来像一个函数，不过却能导致 ``调用`` 它的函数退出；不要打 +乱读者大脑里的语法分析器。 + +2) 依赖于一个固定名字的本地变量的宏： + +.. code-block:: c + + #define FOO(val) bar(index, val) + +可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起 +来不相关的改动带来错误。 + +3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这 + 种用法就会出错了。 + +4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数 + 的宏也要注意此类问题。 + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) 在宏里定义类似函数的本地变量时命名冲突： + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret 是本地变量的通用名字 - __foo_ret 更不容易与一个已存在的变量冲突。 + +cpp 手册对宏的讲解很详细。gcc internals 手册也详细讲解了 RTL，内核里的汇编语 +言经常用到它。 + + +13) 打印内核消息 +------------------------------ + +内核开发者应该是受过良好教育的。请一定注意内核信息的拼写，以给人以好的印象。 +不要用不规范的单词比如 ``dont``，而要用 ``do not`` 或者 ``don't`` 。保证这些信 +息简单明了,无歧义。 + +内核信息不必以英文句号结束。 + +在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。 + +<linux/device.h> 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确 +的设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err(), dev_warn(), +dev_info() 等等。对于那些不和某个特定设备相关连的信息，<linux/printk.h> 定义 +了 pr_notice(), pr_info(), pr_warn(), pr_err() 和其他。 + +写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提 +供极大的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 pr_XXX() +函数能无条件地打印，pr_debug() 却不；默认情况下它不会被编译，除非定义了 DEBUG +或设定了 CONFIG_DYNAMIC_DEBUG。实际这同样是为了 dev_dbg()，一个相关约定是在一 +个已经开启了 DEBUG 时，使用 VERBOSE_DEBUG 来添加 dev_vdbg()。 + +许多子系统拥有 Kconfig 调试选项来开启 -DDEBUG 在对应的 Makefile 里面；在其他 +情况下，特殊文件使用 #define DEBUG。当一条调试信息需要被无条件打印时，例如， +如果已经包含一个调试相关的 #ifdef 条件，printk(KERN_DEBUG ...) 就可被使用。 + + +14) 分配内存 +------------------------------ + +内核提供了下面的一般用途的内存分配函数： +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc() 和 vzalloc()。 +请参考 API 文档以获取有关它们的详细信息。 + +传递结构体大小的首选形式是这样的： + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能 +会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof +的结果不变。 + +强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何 +指针类型的转换是没有问题的。 + +分配一个数组的首选形式是这样的： + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +分配一个零长数组的首选形式是这样的： + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。 + + +15) 内联弊病 +------------------------------ + +有一个常见的误解是 ``内联`` 是 gcc 提供的可以让代码运行更快的一个选项。虽然使 +用内联函数有时候是恰当的 (比如作为一种替代宏的方式，请看第十二章)，不过很多情 +况下不是这样。inline 的过度使用会使内核变大，从而使整个系统运行速度变慢。 +因为体积大内核会占用更多的指令高速缓存，而且会导致 pagecache 的可用内存减少。 +想象一下，一次 pagecache 未命中就会导致一次磁盘寻址，将耗时 5 毫秒。5 毫秒的 +时间内 CPU 能执行很多很多指令。 + +一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一 +个例外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在 +编译时能优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。 +kmalloc() 内联函数就是一个很好的例子。 + +人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失， +因为没有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 +inline gcc 也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的 +争论会抵消 inline 自身的潜在价值，得不偿失。 + + +16) 函数返回值及命名 +------------------------------ + +函数可以返回多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样 +的一个值可以表示为一个错误代码整数 (-Exxx＝失败，0＝成功) 或者一个 ``成功`` +布尔值 (0＝失败，非0＝成功)。 + +混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和 +布尔型变量，那么编译器就能够帮我们发现这些错误... 不过 C 语言不区分。为了避免 +产生这种 bug，请遵循下面的惯例:: + + 如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代 + 码整数。如果是一个判断，那么函数应该返回一个 "成功" 布尔值。 + +比如， ``add work`` 是一个命令，所以 add_work() 在成功时返回 0，在失败时返回 +-EBUSY。类似的，因为 ``PCI device present`` 是一个判断，所以 pci_dev_present() +在成功找到一个匹配的设备时应该返回 1，如果找不到时应该返回 0。 + +所有 EXPORTed 函数都必须遵守这个惯例，所有的公共函数也都应该如此。私有 +(static) 函数不需要如此，但是我们也推荐这样做。 + +返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的， +他们通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数， +他们使用 NULL 或者 ERR_PTR 机制来报告错误。 + + +17) 不要重新发明内核宏 +------------------------------ + +头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些 +它们的变种。比如，如果你需要计算一个数组的长度，使用这个宏 + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +类似的，如果你要计算某结构体成员的大小，使用 + +.. code-block:: c + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以 +自己看看那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应 +在你的代码里自己重新定义。 + + +18) 编辑器模式行和其他需要罗嗦的事情 +-------------------------------------------------- + +有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs +能够解释被标记成这样的行： + +.. code-block:: c + + -*- mode: c -*- + +或者这样的： + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim 能够解释这样的标记： + +.. code-block:: c + + /* vim:set sw=8 noet */ + +不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不 +应该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制 +的模式，或者使用其他可以产生正确的缩进的巧妙方法。 + + +19) 内联汇编 +------------------------------ + +在特定架构的代码中，你可能需要内联汇编与 CPU 和平台相关功能连接。需要这么做时 +就不要犹豫。然而，当 C 可以完成工作时，不要平白无故地使用内联汇编。在可能的情 +况下，你可以并且应该用 C 和硬件沟通。 + +请考虑去写捆绑通用位元 (wrap common bits) 的内联汇编的简单辅助函数，别去重复 +地写下只有细微差异内联汇编。记住内联汇编可以使用 C 参数。 + +大型，有一定复杂度的汇编函数应该放在 .S 文件内，用相应的 C 原型定义在 C 头文 +件中。汇编函数的 C 原型应该使用 ``asmlinkage`` 。 + +你可能需要把汇编语句标记为 volatile，用来阻止 GCC 在没发现任何副作用后就把它 +移除了。你不必总是这样做，尽管，这不必要的举动会限制优化。 + +在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号分割而且各占一行， +除了最后一条指令外，在每个指令结尾加上 \n\t，让汇编输出时可以正确地缩进下一条 +指令： + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) 条件编译 +------------------------------ + +只要可能，就不要在 .c 文件里面使用预处理条件 (#if, #ifdef)；这样做让代码更难 +阅读并且更难去跟踪逻辑。替代方案是，在头文件中用预处理条件提供给那些 .c 文件 +使用，再给 #else 提供一个空桩 (no-op stub) 版本，然后在 .c 文件内无条件地调用 +那些 (定义在头文件内的) 函数。这样做，编译器会避免为桩函数 (stub) 的调用生成 +任何代码，产生的结果是相同的，但逻辑将更加清晰。 + +最好倾向于编译整个函数，而不是函数的一部分或表达式的一部分。与其放一个 ifdef +在表达式内，不如分解出部分或全部表达式，放进一个单独的辅助函数，并应用预处理 +条件到这个辅助函数内。 + +如果你有一个在特定配置中，可能变成未使用的函数或变量，编译器会警告它定义了但 +未使用，把它标记为 __maybe_unused 而不是将它包含在一个预处理条件中。(然而，如 +果一个函数或变量总是未使用，就直接删除它。) + +在代码中，尽可能地使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔 +表达式，并在一般的 C 条件中使用它： + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +编译器会做常量折叠，然后就像使用 #ifdef 那样去包含或排除代码块，所以这不会带 +来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正 +确性 (语法，类型，符号引用，等等)。因此，如果条件不满足，代码块内的引用符号就 +不存在时，你还是必须去用 #ifdef。 + +在任何有意义的 #if 或 #ifdef 块的末尾 (超过几行的)，在 #endif 同一行的后面写下 +注解，注释这个条件表达式。例如： + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +附录 I) 参考 +------------------- + +The C Programming Language, 第二版 +作者：Brian W. Kernighan 和 Denni M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮). + +The Practice of Programming +作者：Brian W. Kernighan 和 Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, +都可以从 http://www.gnu.org/manual/ 找到 + +WG14 是 C 语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel process/coding-style.rst，作者 greg@kroah.com 发表于 OLS 2002： +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/zh_CN/index.rst b/Documentation/translations/zh_CN/index.rst new file mode 100644 index 000000000000..75956d669962 --- /dev/null +++ b/Documentation/translations/zh_CN/index.rst @@ -0,0 +1,12 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +Chinese translations +==================== + +.. toctree:: + :maxdepth: 1 + + coding-style diff --git a/Documentation/usb/gadget-testing.txt b/Documentation/usb/gadget-testing.txt index 581960574889..fb0cc4df1765 100644 --- a/Documentation/usb/gadget-testing.txt +++ b/Documentation/usb/gadget-testing.txt @@ -632,6 +632,8 @@ The uac2 function provides these attributes in its function directory: p_chmask - playback channel mask p_srate - playback sampling rate p_ssize - playback sample size (bytes) + req_number - the number of pre-allocated request for both capture + and playback The attributes have sane default values. diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 0a94ffe17ab6..00e706997130 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -543,7 +543,7 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm. When a USB 3.0 lpm-capable device is plugged in to a xHCI host which supports link PM, it will check if U1 and U2 exit latencies have been set in the BOS - descriptor; if the check is is passed and the host + descriptor; if the check is passed and the host supports USB3 hardware LPM, USB3 hardware LPM will be enabled for the device and these files will be created. The files hold a string value (enable or disable) diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 03145b7cafaa..3c248f772ae6 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -951,6 +951,10 @@ This ioctl allows the user to create or modify a guest physical memory slot. When changing an existing slot, it may be moved in the guest physical memory space, or its flags may be modified. It may not be resized. Slots may not overlap in guest physical address space. +Bits 0-15 of "slot" specifies the slot id and this value should be +less than the maximum number of user memory slots supported per VM. +The maximum allowed slots can be queried using KVM_CAP_NR_MEMSLOTS, +if this capability is supported by the architecture. If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 of "slot" specifies the address space which is being modified. They must be @@ -2061,6 +2065,8 @@ registers, find a list below: MIPS | KVM_REG_MIPS_LO | 64 MIPS | KVM_REG_MIPS_PC | 64 MIPS | KVM_REG_MIPS_CP0_INDEX | 32 + MIPS | KVM_REG_MIPS_CP0_ENTRYLO0 | 64 + MIPS | KVM_REG_MIPS_CP0_ENTRYLO1 | 64 MIPS | KVM_REG_MIPS_CP0_CONTEXT | 64 MIPS | KVM_REG_MIPS_CP0_USERLOCAL | 64 MIPS | KVM_REG_MIPS_CP0_PAGEMASK | 32 @@ -2071,9 +2077,11 @@ registers, find a list below: MIPS | KVM_REG_MIPS_CP0_ENTRYHI | 64 MIPS | KVM_REG_MIPS_CP0_COMPARE | 32 MIPS | KVM_REG_MIPS_CP0_STATUS | 32 + MIPS | KVM_REG_MIPS_CP0_INTCTL | 32 MIPS | KVM_REG_MIPS_CP0_CAUSE | 32 MIPS | KVM_REG_MIPS_CP0_EPC | 64 MIPS | KVM_REG_MIPS_CP0_PRID | 32 + MIPS | KVM_REG_MIPS_CP0_EBASE | 64 MIPS | KVM_REG_MIPS_CP0_CONFIG | 32 MIPS | KVM_REG_MIPS_CP0_CONFIG1 | 32 MIPS | KVM_REG_MIPS_CP0_CONFIG2 | 32 @@ -2148,6 +2156,12 @@ patterns depending on whether they're 32-bit or 64-bit registers: 0x7020 0000 0001 00 <reg:5> <sel:3> (32-bit) 0x7030 0000 0001 00 <reg:5> <sel:3> (64-bit) +Note: KVM_REG_MIPS_CP0_ENTRYLO0 and KVM_REG_MIPS_CP0_ENTRYLO1 are the MIPS64 +versions of the EntryLo registers regardless of the word size of the host +hardware, host kernel, guest, and whether XPA is present in the guest, i.e. +with the RI and XI bits (if they exist) in bits 63 and 62 respectively, and +the PFNX field starting at bit 30. + MIPS KVM control registers (see above) have the following id bit patterns: 0x7030 0000 0002 <reg:16> @@ -2443,18 +2457,20 @@ are, it will do nothing and return an EBUSY error. The parameter is a pointer to a 32-bit unsigned integer variable containing the order (log base 2) of the desired size of the hash table, which must be between 18 and 46. On successful return from the -ioctl, it will have been updated with the order of the hash table that -was allocated. +ioctl, the value will not be changed by the kernel. If no hash table has been allocated when any vcpu is asked to run (with the KVM_RUN ioctl), the host kernel will allocate a default-sized hash table (16 MB). If this ioctl is called when a hash table has already been allocated, -the kernel will clear out the existing hash table (zero all HPTEs) and -return the hash table order in the parameter. (If the guest is using -the virtualized real-mode area (VRMA) facility, the kernel will -re-create the VMRA HPTEs on the next KVM_RUN of any vcpu.) +with a different order from the existing hash table, the existing hash +table will be freed and a new one allocated. If this is ioctl is +called when a hash table has already been allocated of the same order +as specified, the kernel will clear out the existing hash table (zero +all HPTEs). In either case, if the guest is using the virtualized +real-mode area (VRMA) facility, the kernel will re-create the VMRA +HPTEs on the next KVM_RUN of any vcpu. 4.77 KVM_S390_INTERRUPT @@ -3177,7 +3193,7 @@ of IOMMU pages. The rest of functionality is identical to KVM_CREATE_SPAPR_TCE. -4.98 KVM_REINJECT_CONTROL +4.99 KVM_REINJECT_CONTROL Capability: KVM_CAP_REINJECT_CONTROL Architectures: x86 @@ -3201,6 +3217,166 @@ struct kvm_reinject_control { pit_reinject = 0 (!reinject mode) is recommended, unless running an old operating system that uses the PIT for timing (e.g. Linux 2.4.x). +4.100 KVM_PPC_CONFIGURE_V3_MMU + +Capability: KVM_CAP_PPC_RADIX_MMU or KVM_CAP_PPC_HASH_MMU_V3 +Architectures: ppc +Type: vm ioctl +Parameters: struct kvm_ppc_mmuv3_cfg (in) +Returns: 0 on success, + -EFAULT if struct kvm_ppc_mmuv3_cfg cannot be read, + -EINVAL if the configuration is invalid + +This ioctl controls whether the guest will use radix or HPT (hashed +page table) translation, and sets the pointer to the process table for +the guest. + +struct kvm_ppc_mmuv3_cfg { + __u64 flags; + __u64 process_table; +}; + +There are two bits that can be set in flags; KVM_PPC_MMUV3_RADIX and +KVM_PPC_MMUV3_GTSE. KVM_PPC_MMUV3_RADIX, if set, configures the guest +to use radix tree translation, and if clear, to use HPT translation. +KVM_PPC_MMUV3_GTSE, if set and if KVM permits it, configures the guest +to be able to use the global TLB and SLB invalidation instructions; +if clear, the guest may not use these instructions. + +The process_table field specifies the address and size of the guest +process table, which is in the guest's space. This field is formatted +as the second doubleword of the partition table entry, as defined in +the Power ISA V3.00, Book III section 5.7.6.1. + +4.101 KVM_PPC_GET_RMMU_INFO + +Capability: KVM_CAP_PPC_RADIX_MMU +Architectures: ppc +Type: vm ioctl +Parameters: struct kvm_ppc_rmmu_info (out) +Returns: 0 on success, + -EFAULT if struct kvm_ppc_rmmu_info cannot be written, + -EINVAL if no useful information can be returned + +This ioctl returns a structure containing two things: (a) a list +containing supported radix tree geometries, and (b) a list that maps +page sizes to put in the "AP" (actual page size) field for the tlbie +(TLB invalidate entry) instruction. + +struct kvm_ppc_rmmu_info { + struct kvm_ppc_radix_geom { + __u8 page_shift; + __u8 level_bits[4]; + __u8 pad[3]; + } geometries[8]; + __u32 ap_encodings[8]; +}; + +The geometries[] field gives up to 8 supported geometries for the +radix page table, in terms of the log base 2 of the smallest page +size, and the number of bits indexed at each level of the tree, from +the PTE level up to the PGD level in that order. Any unused entries +will have 0 in the page_shift field. + +The ap_encodings gives the supported page sizes and their AP field +encodings, encoded with the AP value in the top 3 bits and the log +base 2 of the page size in the bottom 6 bits. + +4.102 KVM_PPC_RESIZE_HPT_PREPARE + +Capability: KVM_CAP_SPAPR_RESIZE_HPT +Architectures: powerpc +Type: vm ioctl +Parameters: struct kvm_ppc_resize_hpt (in) +Returns: 0 on successful completion, + >0 if a new HPT is being prepared, the value is an estimated + number of milliseconds until preparation is complete + -EFAULT if struct kvm_reinject_control cannot be read, + -EINVAL if the supplied shift or flags are invalid + -ENOMEM if unable to allocate the new HPT + -ENOSPC if there was a hash collision when moving existing + HPT entries to the new HPT + -EIO on other error conditions + +Used to implement the PAPR extension for runtime resizing of a guest's +Hashed Page Table (HPT). Specifically this starts, stops or monitors +the preparation of a new potential HPT for the guest, essentially +implementing the H_RESIZE_HPT_PREPARE hypercall. + +If called with shift > 0 when there is no pending HPT for the guest, +this begins preparation of a new pending HPT of size 2^(shift) bytes. +It then returns a positive integer with the estimated number of +milliseconds until preparation is complete. + +If called when there is a pending HPT whose size does not match that +requested in the parameters, discards the existing pending HPT and +creates a new one as above. + +If called when there is a pending HPT of the size requested, will: + * If preparation of the pending HPT is already complete, return 0 + * If preparation of the pending HPT has failed, return an error + code, then discard the pending HPT. + * If preparation of the pending HPT is still in progress, return an + estimated number of milliseconds until preparation is complete. + +If called with shift == 0, discards any currently pending HPT and +returns 0 (i.e. cancels any in-progress preparation). + +flags is reserved for future expansion, currently setting any bits in +flags will result in an -EINVAL. + +Normally this will be called repeatedly with the same parameters until +it returns <= 0. The first call will initiate preparation, subsequent +ones will monitor preparation until it completes or fails. + +struct kvm_ppc_resize_hpt { + __u64 flags; + __u32 shift; + __u32 pad; +}; + +4.103 KVM_PPC_RESIZE_HPT_COMMIT + +Capability: KVM_CAP_SPAPR_RESIZE_HPT +Architectures: powerpc +Type: vm ioctl +Parameters: struct kvm_ppc_resize_hpt (in) +Returns: 0 on successful completion, + -EFAULT if struct kvm_reinject_control cannot be read, + -EINVAL if the supplied shift or flags are invalid + -ENXIO is there is no pending HPT, or the pending HPT doesn't + have the requested size + -EBUSY if the pending HPT is not fully prepared + -ENOSPC if there was a hash collision when moving existing + HPT entries to the new HPT + -EIO on other error conditions + +Used to implement the PAPR extension for runtime resizing of a guest's +Hashed Page Table (HPT). Specifically this requests that the guest be +transferred to working with the new HPT, essentially implementing the +H_RESIZE_HPT_COMMIT hypercall. + +This should only be called after KVM_PPC_RESIZE_HPT_PREPARE has +returned 0 with the same parameters. In other cases +KVM_PPC_RESIZE_HPT_COMMIT will return an error (usually -ENXIO or +-EBUSY, though others may be possible if the preparation was started, +but failed). + +This will have undefined effects on the guest if it has not already +placed itself in a quiescent state where no vcpu will make MMU enabled +memory accesses. + +On succsful completion, the pending HPT will become the guest's active +HPT and the previous HPT will be discarded. + +On failure, the guest will still be operating on its previous HPT. + +struct kvm_ppc_resize_hpt { + __u64 flags; + __u32 shift; + __u32 pad; +}; + 5. The kvm_run structure ------------------------ @@ -3217,7 +3393,18 @@ struct kvm_run { Request that KVM_RUN return when it becomes possible to inject external interrupts into the guest. Useful in conjunction with KVM_INTERRUPT. - __u8 padding1[7]; + __u8 immediate_exit; + +This field is polled once when KVM_RUN starts; if non-zero, KVM_RUN +exits immediately, returning -EINTR. In the common scenario where a +signal is used to "kick" a VCPU out of KVM_RUN, this field can be used +to avoid usage of KVM_SET_SIGNAL_MASK, which has worse scalability. +Rather than blocking the signal outside KVM_RUN, userspace can set up +a signal handler that sets run->immediate_exit to a non-zero value. + +This field is ignored if KVM_CAP_IMMEDIATE_EXIT is not available. + + __u8 padding1[6]; /* out */ __u32 exit_reason; @@ -3942,3 +4129,21 @@ In order to use SynIC, it has to be activated by setting this capability via KVM_ENABLE_CAP ioctl on the vcpu fd. Note that this will disable the use of APIC hardware virtualization even if supported by the CPU, as it's incompatible with SynIC auto-EOI behavior. + +8.3 KVM_CAP_PPC_RADIX_MMU + +Architectures: ppc + +This capability, if KVM_CHECK_EXTENSION indicates that it is +available, means that that the kernel can support guests using the +radix MMU defined in Power ISA V3.00 (as implemented in the POWER9 +processor). + +8.4 KVM_CAP_PPC_HASH_MMU_V3 + +Architectures: ppc + +This capability, if KVM_CHECK_EXTENSION indicates that it is +available, means that that the kernel can support guests using the +hashed page table MMU defined in Power ISA V3.00 (as implemented in +the POWER9 processor), including in-memory segment tables. diff --git a/Documentation/virtual/kvm/devices/arm-vgic-v3.txt b/Documentation/virtual/kvm/devices/arm-vgic-v3.txt index 9348b3caccd7..c1a24612c198 100644 --- a/Documentation/virtual/kvm/devices/arm-vgic-v3.txt +++ b/Documentation/virtual/kvm/devices/arm-vgic-v3.txt @@ -118,7 +118,7 @@ Groups: -EBUSY: One or more VCPUs are running - KVM_DEV_ARM_VGIC_CPU_SYSREGS + KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS Attributes: The attr field of kvm_device_attr encodes two values: bits: | 63 .... 32 | 31 .... 16 | 15 .... 0 | @@ -139,13 +139,15 @@ Groups: All system regs accessed through this API are (rw, 64-bit) and kvm_device_attr.addr points to a __u64 value. - KVM_DEV_ARM_VGIC_CPU_SYSREGS accesses the CPU interface registers for the + KVM_DEV_ARM_VGIC_GRP_CPU_SYSREGS accesses the CPU interface registers for the CPU specified by the mpidr field. + CPU interface registers access is not implemented for AArch32 mode. + Error -ENXIO is returned when accessed in AArch32 mode. Errors: -ENXIO: Getting or setting this register is not yet supported -EBUSY: VCPU is running - -EINVAL: Invalid mpidr supplied + -EINVAL: Invalid mpidr or register value supplied KVM_DEV_ARM_VGIC_GRP_NR_IRQS @@ -204,3 +206,6 @@ Groups: architecture defined MPIDR, and the field is encoded as follows: | 63 .... 56 | 55 .... 48 | 47 .... 40 | 39 .... 32 | | Aff3 | Aff2 | Aff1 | Aff0 | + Errors: + -EINVAL: vINTID is not multiple of 32 or + info field is not VGIC_LEVEL_INFO_LINE_LEVEL diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt index c8d040e27046..feaaa634f154 100644 --- a/Documentation/virtual/kvm/hypercalls.txt +++ b/Documentation/virtual/kvm/hypercalls.txt @@ -81,3 +81,38 @@ the vcpu to sleep until occurrence of an appropriate event. Another vcpu of the same guest can wakeup the sleeping vcpu by issuing KVM_HC_KICK_CPU hypercall, specifying APIC ID (a1) of the vcpu to be woken up. An additional argument (a0) is used in the hypercall for future use. + + +6. KVM_HC_CLOCK_PAIRING +------------------------ +Architecture: x86 +Status: active +Purpose: Hypercall used to synchronize host and guest clocks. +Usage: + +a0: guest physical address where host copies +"struct kvm_clock_offset" structure. + +a1: clock_type, ATM only KVM_CLOCK_PAIRING_WALLCLOCK (0) +is supported (corresponding to the host's CLOCK_REALTIME clock). + + struct kvm_clock_pairing { + __s64 sec; + __s64 nsec; + __u64 tsc; + __u32 flags; + __u32 pad[9]; + }; + + Where: + * sec: seconds from clock_type clock. + * nsec: nanoseconds from clock_type clock. + * tsc: guest TSC value used to calculate sec/nsec pair + * flags: flags, unused (0) at the moment. + +The hypercall lets a guest compute a precise timestamp across +host and guest. The guest can use the returned TSC value to +compute the CLOCK_REALTIME for its clock, at the same instant. + +Returns KVM_EOPNOTSUPP if the host does not use TSC clocksource, +or if clock type is different than KVM_CLOCK_PAIRING_WALLCLOCK. diff --git a/Documentation/virtual/kvm/locking.txt b/Documentation/virtual/kvm/locking.txt index fd013bf4115b..1bb8bcaf8497 100644 --- a/Documentation/virtual/kvm/locking.txt +++ b/Documentation/virtual/kvm/locking.txt @@ -26,9 +26,16 @@ sections. Fast page fault: Fast page fault is the fast path which fixes the guest page fault out of -the mmu-lock on x86. Currently, the page fault can be fast only if the -shadow page table is present and it is caused by write-protect, that means -we just need change the W bit of the spte. +the mmu-lock on x86. Currently, the page fault can be fast in one of the +following two cases: + +1. Access Tracking: The SPTE is not present, but it is marked for access +tracking i.e. the SPTE_SPECIAL_MASK is set. That means we need to +restore the saved R/X bits. This is described in more detail later below. + +2. Write-Protection: The SPTE is present and the fault is +caused by write-protect. That means we just need to change the W bit of the +spte. What we use to avoid all the race is the SPTE_HOST_WRITEABLE bit and SPTE_MMU_WRITEABLE bit on the spte: @@ -38,7 +45,8 @@ SPTE_MMU_WRITEABLE bit on the spte: page write-protection. On fast page fault path, we will use cmpxchg to atomically set the spte W -bit if spte.SPTE_HOST_WRITEABLE = 1 and spte.SPTE_WRITE_PROTECT = 1, this +bit if spte.SPTE_HOST_WRITEABLE = 1 and spte.SPTE_WRITE_PROTECT = 1, or +restore the saved R/X bits if VMX_EPT_TRACK_ACCESS mask is set, or both. This is safe because whenever changing these bits can be detected by cmpxchg. But we need carefully check these cases: @@ -142,6 +150,21 @@ Since the spte is "volatile" if it can be updated out of mmu-lock, we always atomically update the spte, the race caused by fast page fault can be avoided, See the comments in spte_has_volatile_bits() and mmu_spte_update(). +Lockless Access Tracking: + +This is used for Intel CPUs that are using EPT but do not support the EPT A/D +bits. In this case, when the KVM MMU notifier is called to track accesses to a +page (via kvm_mmu_notifier_clear_flush_young), it marks the PTE as not-present +by clearing the RWX bits in the PTE and storing the original R & X bits in +some unused/ignored bits. In addition, the SPTE_SPECIAL_MASK is also set on the +PTE (using the ignored bit 62). When the VM tries to access the page later on, +a fault is generated and the fast page fault mechanism described above is used +to atomically restore the PTE to a Present state. The W bit is not saved when +the PTE is marked for access tracking and during restoration to the Present +state, the W bit is set depending on whether or not it was a write access. If +it wasn't, then the W bit will remain clear until a write access happens, at +which time it will be set using the Dirty tracking mechanism described above. + 3. Reference ------------ diff --git a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt index f4099ca6b483..87b80f589e1c 100644 --- a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt +++ b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt @@ -2401,9 +2401,9 @@ This takes one argument, which is a single letter. It calls the generic kernel's SysRq driver, which does whatever is called for by - that argument. See the SysRq documentation in Documentation/sysrq.txt - in your favorite kernel tree to see what letters are valid and what - they do. + that argument. See the SysRq documentation in + Documentation/admin-guide/sysrq.rst in your favorite kernel tree to + see what letters are valid and what they do. diff --git a/Documentation/vm/ksm.txt b/Documentation/vm/ksm.txt index f34a8ee6f860..6b0ca7feb135 100644 --- a/Documentation/vm/ksm.txt +++ b/Documentation/vm/ksm.txt @@ -38,6 +38,10 @@ the range for whenever the KSM daemon is started; even if the range cannot contain any pages which KSM could actually merge; even if MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. +If a region of memory must be split into at least one new MADV_MERGEABLE +or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process +will exceed vm.max_map_count (see Documentation/sysctl/vm.txt). + Like other madvise calls, they are intended for use on mapped areas of the user address space: they will report ENOMEM if the specified range includes unmapped gaps (though working on the intervening mapped areas), @@ -80,6 +84,20 @@ run - set 0 to stop ksmd from running but keep merged pages, Default: 0 (must be changed to 1 to activate KSM, except if CONFIG_SYSFS is disabled) +use_zero_pages - specifies whether empty pages (i.e. allocated pages + that only contain zeroes) should be treated specially. + When set to 1, empty pages are merged with the kernel + zero page(s) instead of with each other as it would + happen normally. This can improve the performance on + architectures with coloured zero pages, depending on + the workload. Care should be taken when enabling this + setting, as it can potentially degrade the performance + of KSM for some workloads, for example if the checksums + of pages candidate for merging match the checksum of + an empty page. This setting can be changed at any time, + it is only effective for pages merged after the change. + Default: 0 (normal KSM behaviour as in earlier releases) + The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: pages_shared - how many shared pages are being used diff --git a/Documentation/vm/transhuge.txt b/Documentation/vm/transhuge.txt index c4171e4519c2..cd28d5ee5273 100644 --- a/Documentation/vm/transhuge.txt +++ b/Documentation/vm/transhuge.txt @@ -110,6 +110,7 @@ MADV_HUGEPAGE region. echo always >/sys/kernel/mm/transparent_hugepage/defrag echo defer >/sys/kernel/mm/transparent_hugepage/defrag +echo defer+madvise >/sys/kernel/mm/transparent_hugepage/defrag echo madvise >/sys/kernel/mm/transparent_hugepage/defrag echo never >/sys/kernel/mm/transparent_hugepage/defrag @@ -120,10 +121,15 @@ that benefit heavily from THP use and are willing to delay the VM start to utilise them. "defer" means that an application will wake kswapd in the background -to reclaim pages and wake kcompact to compact memory so that THP is +to reclaim pages and wake kcompactd to compact memory so that THP is available in the near future. It's the responsibility of khugepaged to then install the THP pages later. +"defer+madvise" will enter direct reclaim and compaction like "always", but +only for regions that have used madvise(MADV_HUGEPAGE); all other regions +will wake kswapd in the background to reclaim pages and wake kcompactd to +compact memory so that THP is available in the near future. + "madvise" will enter direct reclaim like "always" but only for regions that are have used madvise(MADV_HUGEPAGE). This is the default behaviour. @@ -296,7 +302,7 @@ thp_split_page is incremented every time a huge page is split into base reason is that a huge page is old and is being reclaimed. This action implies splitting all PMD the page mapped with. -thp_split_page_failed is is incremented if kernel fails to split huge +thp_split_page_failed is incremented if kernel fails to split huge page. This can happen if the page was pinned by somebody. thp_deferred_split_page is incremented when a huge page is put onto split diff --git a/Documentation/vm/userfaultfd.txt b/Documentation/vm/userfaultfd.txt index 70a3c94d1941..bb2f945f87ab 100644 --- a/Documentation/vm/userfaultfd.txt +++ b/Documentation/vm/userfaultfd.txt @@ -54,6 +54,26 @@ uffdio_api.features and uffdio_api.ioctls two 64bit bitmasks of respectively all the available features of the read(2) protocol and the generic ioctl available. +The uffdio_api.features bitmask returned by the UFFDIO_API ioctl +defines what memory types are supported by the userfaultfd and what +events, except page fault notifications, may be generated. + +If the kernel supports registering userfaultfd ranges on hugetlbfs +virtual memory areas, UFFD_FEATURE_MISSING_HUGETLBFS will be set in +uffdio_api.features. Similarly, UFFD_FEATURE_MISSING_SHMEM will be +set if the kernel supports registering userfaultfd ranges on shared +memory (covering all shmem APIs, i.e. tmpfs, IPCSHM, /dev/zero +MAP_SHARED, memfd_create, etc). + +The userland application that wants to use userfaultfd with hugetlbfs +or shared memory need to set the corresponding flag in +uffdio_api.features to enable those features. + +If the userland desires to receive notifications for events other than +page faults, it has to verify that uffdio_api.features has appropriate +UFFD_FEATURE_EVENT_* bits set. These events are described in more +detail below in "Non-cooperative userfaultfd" section. + Once the userfaultfd has been enabled the UFFDIO_REGISTER ioctl should be invoked (if present in the returned uffdio_api.ioctls bitmask) to register a memory range in the userfaultfd by setting the @@ -129,7 +149,7 @@ migration thread in the QEMU running in the destination node will receive the page that triggered the userfault and it'll map it as usual with the UFFDIO_COPY|ZEROPAGE (without actually knowing if it was spontaneously sent by the source or if it was an urgent page -requested through an userfault). +requested through a userfault). By the time the userfaults start, the QEMU in the destination node doesn't need to keep any per-page state bitmap relative to the live @@ -142,3 +162,68 @@ course the bitmap is updated accordingly. It's also useful to avoid sending the same page twice (in case the userfault is read by the postcopy thread just before UFFDIO_COPY|ZEROPAGE runs in the migration thread). + +== Non-cooperative userfaultfd == + +When the userfaultfd is monitored by an external manager, the manager +must be able to track changes in the process virtual memory +layout. Userfaultfd can notify the manager about such changes using +the same read(2) protocol as for the page fault notifications. The +manager has to explicitly enable these events by setting appropriate +bits in uffdio_api.features passed to UFFDIO_API ioctl: + +UFFD_FEATURE_EVENT_FORK - enable userfaultfd hooks for fork(). When +this feature is enabled, the userfaultfd context of the parent process +is duplicated into the newly created process. The manager receives +UFFD_EVENT_FORK with file descriptor of the new userfaultfd context in +the uffd_msg.fork. + +UFFD_FEATURE_EVENT_REMAP - enable notifications about mremap() +calls. When the non-cooperative process moves a virtual memory area to +a different location, the manager will receive UFFD_EVENT_REMAP. The +uffd_msg.remap will contain the old and new addresses of the area and +its original length. + +UFFD_FEATURE_EVENT_REMOVE - enable notifications about +madvise(MADV_REMOVE) and madvise(MADV_DONTNEED) calls. The event +UFFD_EVENT_REMOVE will be generated upon these calls to madvise. The +uffd_msg.remove will contain start and end addresses of the removed +area. + +UFFD_FEATURE_EVENT_UNMAP - enable notifications about memory +unmapping. The manager will get UFFD_EVENT_UNMAP with uffd_msg.remove +containing start and end addresses of the unmapped area. + +Although the UFFD_FEATURE_EVENT_REMOVE and UFFD_FEATURE_EVENT_UNMAP +are pretty similar, they quite differ in the action expected from the +userfaultfd manager. In the former case, the virtual memory is +removed, but the area is not, the area remains monitored by the +userfaultfd, and if a page fault occurs in that area it will be +delivered to the manager. The proper resolution for such page fault is +to zeromap the faulting address. However, in the latter case, when an +area is unmapped, either explicitly (with munmap() system call), or +implicitly (e.g. during mremap()), the area is removed and in turn the +userfaultfd context for such area disappears too and the manager will +not get further userland page faults from the removed area. Still, the +notification is required in order to prevent manager from using +UFFDIO_COPY on the unmapped area. + +Unlike userland page faults which have to be synchronous and require +explicit or implicit wakeup, all the events are delivered +asynchronously and the non-cooperative process resumes execution as +soon as manager executes read(). The userfaultfd manager should +carefully synchronize calls to UFFDIO_COPY with the events +processing. To aid the synchronization, the UFFDIO_COPY ioctl will +return -ENOSPC when the monitored process exits at the time of +UFFDIO_COPY, and -ENOENT, when the non-cooperative process has changed +its virtual memory layout simultaneously with outstanding UFFDIO_COPY +operation. + +The current asynchronous model of the event delivery is optimal for +single threaded non-cooperative userfaultfd manager implementations. A +synchronous event delivery model can be added later as a new +userfaultfd feature to facilitate multithreading enhancements of the +non cooperative manager, for example to allow UFFDIO_COPY ioctls to +run in parallel to the event reception. Single threaded +implementations should continue to use the current async event +delivery model instead. diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt index ea277478982f..9b93953f69cf 100644 --- a/Documentation/watchdog/watchdog-kernel-api.txt +++ b/Documentation/watchdog/watchdog-kernel-api.txt @@ -280,6 +280,12 @@ To disable the watchdog on reboot, the user must call the following helper: static inline void watchdog_stop_on_reboot(struct watchdog_device *wdd); +To disable the watchdog when unregistering the watchdog, the user must call +the following helper. Note that this will only stop the watchdog if the +nowayout flag is not set. + +static inline void watchdog_stop_on_unregister(struct watchdog_device *wdd); + To change the priority of the restart handler the following helper should be used: diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index e21850e270a0..4f7d86dd0a5d 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -209,6 +209,11 @@ timeout: Initial watchdog timeout in seconds (0<timeout<516, default=60) nowayout: Watchdog cannot be stopped once started (default=kernel config parameter) ------------------------------------------------- +nic7018_wdt: +timeout: Initial watchdog timeout in seconds (0<timeout<464, default=80) +nowayout: Watchdog cannot be stopped once started + (default=kernel config parameter) +------------------------------------------------- nuc900_wdt: heartbeat: Watchdog heartbeats in seconds. (default = 15) diff --git a/Documentation/x86/intel_rdt_ui.txt b/Documentation/x86/intel_rdt_ui.txt index d918d268cd72..51cf6fa5591f 100644 --- a/Documentation/x86/intel_rdt_ui.txt +++ b/Documentation/x86/intel_rdt_ui.txt @@ -212,3 +212,117 @@ Finally we move core 4-7 over to the new group and make sure that the kernel and the tasks running there get 50% of the cache. # echo C0 > p0/cpus + +4) Locking between applications + +Certain operations on the resctrl filesystem, composed of read/writes +to/from multiple files, must be atomic. + +As an example, the allocation of an exclusive reservation of L3 cache +involves: + + 1. Read the cbmmasks from each directory + 2. Find a contiguous set of bits in the global CBM bitmask that is clear + in any of the directory cbmmasks + 3. Create a new directory + 4. Set the bits found in step 2 to the new directory "schemata" file + +If two applications attempt to allocate space concurrently then they can +end up allocating the same bits so the reservations are shared instead of +exclusive. + +To coordinate atomic operations on the resctrlfs and to avoid the problem +above, the following locking procedure is recommended: + +Locking is based on flock, which is available in libc and also as a shell +script command + +Write lock: + + A) Take flock(LOCK_EX) on /sys/fs/resctrl + B) Read/write the directory structure. + C) funlock + +Read lock: + + A) Take flock(LOCK_SH) on /sys/fs/resctrl + B) If success read the directory structure. + C) funlock + +Example with bash: + +# Atomically read directory structure +$ flock -s /sys/fs/resctrl/ find /sys/fs/resctrl + +# Read directory contents and create new subdirectory + +$ cat create-dir.sh +find /sys/fs/resctrl/ > output.txt +mask = function-of(output.txt) +mkdir /sys/fs/resctrl/newres/ +echo mask > /sys/fs/resctrl/newres/schemata + +$ flock /sys/fs/resctrl/ ./create-dir.sh + +Example with C: + +/* + * Example code do take advisory locks + * before accessing resctrl filesystem + */ +#include <sys/file.h> +#include <stdlib.h> + +void resctrl_take_shared_lock(int fd) +{ + int ret; + + /* take shared lock on resctrl filesystem */ + ret = flock(fd, LOCK_SH); + if (ret) { + perror("flock"); + exit(-1); + } +} + +void resctrl_take_exclusive_lock(int fd) +{ + int ret; + + /* release lock on resctrl filesystem */ + ret = flock(fd, LOCK_EX); + if (ret) { + perror("flock"); + exit(-1); + } +} + +void resctrl_release_lock(int fd) +{ + int ret; + + /* take shared lock on resctrl filesystem */ + ret = flock(fd, LOCK_UN); + if (ret) { + perror("flock"); + exit(-1); + } +} + +void main(void) +{ + int fd, ret; + + fd = open("/sys/fs/resctrl", O_DIRECTORY); + if (fd == -1) { + perror("open"); + exit(-1); + } + resctrl_take_shared_lock(fd); + /* code to read directory contents */ + resctrl_release_lock(fd); + + resctrl_take_exclusive_lock(fd); + /* code to read and write directory contents */ + resctrl_release_lock(fd); +} |