diff options
Diffstat (limited to 'Documentation')
1608 files changed, 43608 insertions, 12452 deletions
diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus index 3fed8fdb873d..826689dcc2e6 100644 --- a/Documentation/ABI/stable/sysfs-bus-vmbus +++ b/Documentation/ABI/stable/sysfs-bus-vmbus @@ -146,3 +146,36 @@ KernelVersion: 4.16 Contact: Stephen Hemminger <sthemmin@microsoft.com> Description: Binary file created by uio_hv_generic for ring buffer Users: Userspace drivers + +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/intr_in_full +Date: February 2019 +KernelVersion: 5.0 +Contact: Michael Kelley <mikelley@microsoft.com> +Description: Number of guest to host interrupts caused by the inbound ring + buffer transitioning from full to not full while a packet is + waiting for buffer space to become available +Users: Debugging tools + +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/intr_out_empty +Date: February 2019 +KernelVersion: 5.0 +Contact: Michael Kelley <mikelley@microsoft.com> +Description: Number of guest to host interrupts caused by the outbound ring + buffer transitioning from empty to not empty +Users: Debugging tools + +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_full_first +Date: February 2019 +KernelVersion: 5.0 +Contact: Michael Kelley <mikelley@microsoft.com> +Description: Number of write operations that were the first to encounter an + outbound ring buffer full condition +Users: Debugging tools + +What: /sys/bus/vmbus/devices/<UUID>/channels/<N>/out_full_total +Date: February 2019 +KernelVersion: 5.0 +Contact: Michael Kelley <mikelley@microsoft.com> +Description: Total number of write operations that encountered an outbound + ring buffer full condition +Users: Debugging tools diff --git a/Documentation/ABI/stable/sysfs-driver-mlxreg-io b/Documentation/ABI/stable/sysfs-driver-mlxreg-io index d9d117d457e1..169fe08a649b 100644 --- a/Documentation/ABI/stable/sysfs-driver-mlxreg-io +++ b/Documentation/ABI/stable/sysfs-driver-mlxreg-io @@ -12,7 +12,6 @@ Description: This file shows ASIC health status. The possible values are: What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ cpld1_version cpld2_version - Date: June 2018 KernelVersion: 4.19 Contact: Vadim Pasternak <vadimpmellanox.com> @@ -21,6 +20,28 @@ Description: These files show with which CPLD versions have been burned The files are read only. +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ + cpld3_version + +Date: November 2018 +KernelVersion: 5.0 +Contact: Vadim Pasternak <vadimpmellanox.com> +Description: These files show with which CPLD versions have been burned + on LED board. + + The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ + jtag_enable + +Date: November 2018 +KernelVersion: 5.0 +Contact: Vadim Pasternak <vadimpmellanox.com> +Description: These files enable and disable the access to the JTAG domain. + By default access to the JTAG domain is disabled. + + The file is read/write. + What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/select_iio Date: June 2018 KernelVersion: 4.19 @@ -76,3 +97,21 @@ Description: These files show the system reset cause, as following: power reset cause. The files are read only. + +What: /sys/devices/platform/mlxplat/mlxreg-io/hwmon/hwmon*/ + reset_comex_pwr_fail + reset_from_comex + reset_system + reset_voltmon_upgrade_fail + +Date: November 2018 +KernelVersion: 5.0 +Contact: Vadim Pasternak <vadimpmellanox.com> +Description: These files show the system reset cause, as following: ComEx + power fail, reset from ComEx, system platform reset, reset + due to voltage monitor devices upgrade failure, + Value 1 in file means this is reset cause, 0 - otherwise. + Only one bit could be 1 at the same time, representing only + the last reset cause. + + The files are read only. diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc index e960cd027e1e..a9e123ba32cd 100644 --- a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc +++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc @@ -25,38 +25,3 @@ Description: 4.2.2. The files are read only. - - -What: /sys/bus/usb/drivers/usbtmc/*/TermChar -Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> -Description: - This file is the TermChar value to be sent to the USB TMC - device as described by the document, "Universal Serial Bus Test - and Measurement Class Specification - (USBTMC) Revision 1.0" as published by the USB-IF. - - Note that the TermCharEnabled file determines if this value is - sent to the device or not. - - -What: /sys/bus/usb/drivers/usbtmc/*/TermCharEnabled -Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> -Description: - This file determines if the TermChar is to be sent to the - device on every transaction or not. For more details about - this, please see the document, "Universal Serial Bus Test and - Measurement Class Specification (USBTMC) Revision 1.0" as - published by the USB-IF. - - -What: /sys/bus/usb/drivers/usbtmc/*/auto_abort -Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> -Description: - This file determines if the transaction of the USB TMC - device is to be automatically aborted if there is any error. - For more details about this, please see the document, - "Universal Serial Bus Test and Measurement Class Specification - (USBTMC) Revision 1.0" as published by the USB-IF. diff --git a/Documentation/ABI/testing/configfs-stp-policy-p_sys-t b/Documentation/ABI/testing/configfs-stp-policy-p_sys-t new file mode 100644 index 000000000000..b290d1c00dcf --- /dev/null +++ b/Documentation/ABI/testing/configfs-stp-policy-p_sys-t @@ -0,0 +1,41 @@ +What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/uuid +Date: June 2018 +KernelVersion: 4.19 +Description: + UUID source identifier string, RW. + Default value is randomly generated at the mkdir <node> time. + Data coming from trace sources that use this <node> will be + tagged with this UUID in the MIPI SyS-T packet stream, to + allow the decoder to discern between different sources + within the same master/channel range, and identify the + higher level decoders that may be needed for each source. + +What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/do_len +Date: June 2018 +KernelVersion: 4.19 +Description: + Include payload length in the MIPI SyS-T header, boolean. + If enabled, the SyS-T protocol encoder will include payload + length in each packet's metadata. This is normally redundant + if the underlying transport protocol supports marking message + boundaries (which STP does), so this is off by default. + +What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/ts_interval +Date: June 2018 +KernelVersion: 4.19 +Description: + Time interval in milliseconds. Include a timestamp in the + MIPI SyS-T packet metadata, if this many milliseconds have + passed since the previous packet from this source. Zero is + the default and stands for "never send the timestamp". + +What: /config/stp-policy/<device>:p_sys-t.<policy>/<node>/clocksync_interval +Date: June 2018 +KernelVersion: 4.19 +Description: + Time interval in milliseconds. Send a CLOCKSYNC packet if + this many milliseconds have passed since the previous + CLOCKSYNC packet from this source. Zero is the default and + stands for "never send the CLOCKSYNC". It makes sense to + use this option with sources that generate constant and/or + periodic data, like stm_heartbeat. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc index 9281e2aa38df..809765bd9573 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-uvc +++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc @@ -12,6 +12,10 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Control descriptors + All attributes read only: + bInterfaceNumber - USB interface number for this + streaming interface + What: /config/usb-gadget/gadget/functions/uvc.name/control/class Date: Dec 2014 KernelVersion: 4.0 @@ -109,6 +113,10 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Streaming descriptors + All attributes read only: + bInterfaceNumber - USB interface number for this + streaming interface + What: /config/usb-gadget/gadget/functions/uvc.name/streaming/class Date: Dec 2014 KernelVersion: 4.0 @@ -160,6 +168,10 @@ Description: Specific MJPEG format descriptors All attributes read only, except bmaControls and bDefaultFrameIndex: + bFormatIndex - unique id for this format descriptor; + only defined after parent header is + linked into the streaming class; + read-only bmaControls - this format's data for bmaControls in the streaming header bmInterfaceFlags - specifies interlace information, @@ -177,6 +189,10 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Specific MJPEG frame descriptors + bFrameIndex - unique id for this framedescriptor; + only defined after parent format is + linked into the streaming header; + read-only dwFrameInterval - indicates how frame interval can be programmed; a number of values separated by newline can be specified @@ -204,6 +220,10 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Specific uncompressed format descriptors + bFormatIndex - unique id for this format descriptor; + only defined after parent header is + linked into the streaming class; + read-only bmaControls - this format's data for bmaControls in the streaming header bmInterfaceFlags - specifies interlace information, @@ -224,6 +244,10 @@ Date: Dec 2014 KernelVersion: 4.0 Description: Specific uncompressed frame descriptors + bFrameIndex - unique id for this framedescriptor; + only defined after parent format is + linked into the streaming header; + read-only dwFrameInterval - indicates how frame interval can be programmed; a number of values separated by newline can be specified diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs new file mode 100644 index 000000000000..2f5b80be07a3 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-driver-habanalabs @@ -0,0 +1,126 @@ +What: /sys/kernel/debug/habanalabs/hl<n>/addr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets the device address to be used for read or write through + PCI bar. The acceptable value is a string that starts with "0x" + +What: /sys/kernel/debug/habanalabs/hl<n>/command_buffers +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays a list with information about the currently allocated + command buffers + +What: /sys/kernel/debug/habanalabs/hl<n>/command_submission +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays a list with information about the currently active + command submissions + +What: /sys/kernel/debug/habanalabs/hl<n>/command_submission_jobs +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays a list with detailed information about each JOB (CB) of + each active command submission + +What: /sys/kernel/debug/habanalabs/hl<n>/data32 +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the root user to read or write directly through the + device's PCI bar. Writing to this file generates a write + transaction while reading from the file generates a read + transcation. This custom interface is needed (instead of using + the generic Linux user-space PCI mapping) because the DDR bar + is very small compared to the DDR memory and only the driver can + move the bar before and after the transaction + +What: /sys/kernel/debug/habanalabs/hl<n>/device +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Enables the root user to set the device to specific state. + Valid values are "disable", "enable", "suspend", "resume". + User can read this property to see the valid values + +What: /sys/kernel/debug/habanalabs/hl<n>/i2c_addr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets I2C device address for I2C transaction that is generated + by the device's CPU + +What: /sys/kernel/debug/habanalabs/hl<n>/i2c_bus +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets I2C bus address for I2C transaction that is generated by + the device's CPU + +What: /sys/kernel/debug/habanalabs/hl<n>/i2c_data +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Triggers an I2C transaction that is generated by the device's + CPU. Writing to this file generates a write transaction while + reading from the file generates a read transcation + +What: /sys/kernel/debug/habanalabs/hl<n>/i2c_reg +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets I2C register id for I2C transaction that is generated by + the device's CPU + +What: /sys/kernel/debug/habanalabs/hl<n>/led0 +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets the state of the first S/W led on the device + +What: /sys/kernel/debug/habanalabs/hl<n>/led1 +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets the state of the second S/W led on the device + +What: /sys/kernel/debug/habanalabs/hl<n>/led2 +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets the state of the third S/W led on the device + +What: /sys/kernel/debug/habanalabs/hl<n>/mmu +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the hop values and physical address for a given ASID + and virtual address. The user should write the ASID and VA into + the file and then read the file to get the result. + e.g. to display info about VA 0x1000 for ASID 1 you need to do: + echo "1 0x1000" > /sys/kernel/debug/habanalabs/hl0/mmu + +What: /sys/kernel/debug/habanalabs/hl<n>/set_power_state +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Sets the PCI power state. Valid values are "1" for D0 and "2" + for D3Hot + +What: /sys/kernel/debug/habanalabs/hl<n>/userptr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays a list with information about the currently user + pointers (user virtual addresses) that are pinned and mapped + to DMA addresses + +What: /sys/kernel/debug/habanalabs/hl<n>/vm +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays a list with information about all the active virtual + address mappings per ASID diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index dea212db9df3..dfad7427817c 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -244,7 +244,7 @@ Description: What: /sys/block/<disk>/queue/zoned Date: September 2016 -Contact: Damien Le Moal <damien.lemoal@hgst.com> +Contact: Damien Le Moal <damien.lemoal@wdc.com> Description: zoned indicates if the device is a zoned block device and the zone model of the device if it is indeed zoned. @@ -259,6 +259,14 @@ Description: zone commands, they will be treated as regular block devices and zoned will report "none". +What: /sys/block/<disk>/queue/nr_zones +Date: November 2018 +Contact: Damien Le Moal <damien.lemoal@wdc.com> +Description: + nr_zones indicates the total number of zones of a zoned block + device ("host-aware" or "host-managed" zone model). For regular + block devices, the value is always 0. + What: /sys/block/<disk>/queue/chunk_sectors Date: September 2016 Contact: Hannes Reinecke <hare@suse.com> @@ -268,6 +276,15 @@ Description: indicates the size in 512B sectors of the RAID volume stripe segment. For a zoned block device, either host-aware or host-managed, chunk_sectors indicates the - size of 512B sectors of the zones of the device, with + size in 512B sectors of the zones of the device, with the eventual exception of the last zone of the device which may be smaller. + +What: /sys/block/<disk>/queue/io_timeout +Date: November 2018 +Contact: Weiping Zhang <zhangweiping@didiglobal.com> +Description: + io_timeout is the request timeout in milliseconds. If a request + does not complete in this time then the block driver timeout + handler is invoked. That timeout handler can decide to retry + the request, to fail it or to start a device recovery strategy. diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram index c1513c756af1..14b2bf2e5105 100644 --- a/Documentation/ABI/testing/sysfs-block-zram +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -98,3 +98,42 @@ Description: The backing_dev file is read-write and set up backing device for zram to write incompressible pages. For using, user should enable CONFIG_ZRAM_WRITEBACK. + +What: /sys/block/zram<id>/idle +Date: November 2018 +Contact: Minchan Kim <minchan@kernel.org> +Description: + idle file is write-only and mark zram slot as idle. + If system has mounted debugfs, user can see which slots + are idle via /sys/kernel/debug/zram/zram<id>/block_state + +What: /sys/block/zram<id>/writeback +Date: November 2018 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The writeback file is write-only and trigger idle and/or + huge page writeback to backing device. + +What: /sys/block/zram<id>/bd_stat +Date: November 2018 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The bd_stat file is read-only and represents backing device's + statistics (bd_count, bd_reads, bd_writes) in a format + similar to block layer statistics file format. + +What: /sys/block/zram<id>/writeback_limit_enable +Date: November 2018 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The writeback_limit_enable file is read-write and specifies + eanbe of writeback_limit feature. "1" means eable the feature. + No limit "0" is the initial state. + +What: /sys/block/zram<id>/writeback_limit +Date: November 2018 +Contact: Minchan Kim <minchan@kernel.org> +Description: + The writeback_limit file is read-write and specifies the maximum + amount of writeback ZRAM can do. The limit could be changed + in run time. diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c new file mode 100644 index 000000000000..2f332ec36f82 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i3c @@ -0,0 +1,146 @@ +What: /sys/bus/i3c/devices/i3c-<bus-id> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + An I3C bus. This directory will contain one sub-directory per + I3C device present on the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/current_master +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the master that owns the bus (<bus-id>-<master-pid>) at + the time this file is read. Note that bus ownership can change + overtime, so there's no guarantee that when the read() call + returns, the value returned is still valid. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/mode +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + I3C bus mode. Can be "pure", "mixed-fast" or "mixed-slow". See + the I3C specification for a detailed description of what each + of these modes implies. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/i3c_scl_frequency +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + The frequency (expressed in Hz) of the SCL signal when + operating in I3C SDR mode. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/i2c_scl_frequency +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + The frequency (expressed in Hz) of the SCL signal when + operating in I2C mode. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/dynamic_address +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Dynamic address assigned to the master controller. This + address may change if the bus is re-initialized. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/bcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + BCR stands for Bus Characteristics Register and express the + device capabilities in term of speed, maximum read/write + length, etc. See the I3C specification for more details. + This entry describes the BCR of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/dcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + DCR stands for Device Characteristics Register and express the + device capabilities in term of exposed features. See the I3C + specification for more details. + This entry describes the DCR of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/pid +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + PID stands for Provisional ID and is used to uniquely identify + a device on a bus. This PID contains information about the + vendor, the part and an instance ID so that several devices of + the same type can be connected on the same bus. + See the I3C specification for more details. + This entry describes the PID of the master controller driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/hdrcap +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the HDR (High Data Rate) capabilities of a device. + Returns a list of supported HDR mode, each element is separated + by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". + See the I3C specification for more details about these HDR + modes. + This entry describes the HDRCAP of the master controller + driving the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + An I3C device present on I3C bus identified by <bus-id>. Note + that all devices are represented including the master driving + the bus. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dynamic_address +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Dynamic address assigned to device <bus-id>-<device-pid>. This + address may change if the bus is re-initialized. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/bcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + BCR stands for Bus Characteristics Register and express the + device capabilities in term of speed, maximum read/write + length, etc. See the I3C specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/dcr +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + DCR stands for Device Characteristics Register and express the + device capabilities in term of exposed features. See the I3C + specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/pid +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + PID stands for Provisional ID and is used to uniquely identify + a device on a bus. This PID contains information about the + vendor, the part and an instance ID so that several devices of + the same type can be connected on the same bus. + See the I3C specification for more details. + +What: /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>/hdrcap +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + Expose the HDR (High Data Rate) capabilities of a device. + Returns a list of supported HDR mode, each element is separated + by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl". + See the I3C specification for more details about these HDR + modes. + +What: /sys/bus/i3c/devices/<bus-id>-<device-pid> +KernelVersion: 5.0 +Contact: linux-i3c@vger.kernel.org +Description: + These directories are just symbolic links to + /sys/bus/i3c/devices/i3c-<bus-id>/<bus-id>-<device-pid>. diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index a5b4f223641d..864f8efd12e5 100644 --- a/Documentation/ABI/testing/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -199,7 +199,7 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/in_positionrelative_x_raw What: /sys/bus/iio/devices/iio:deviceX/in_positionrelative_y_raw -KernelVersion: 4.18 +KernelVersion: 4.19 Contact: linux-iio@vger.kernel.org Description: Relative position in direction x or y on a pad (may be @@ -1554,6 +1554,10 @@ What: /sys/bus/iio/devices/iio:deviceX/in_concentration_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_co2_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_co2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_ethanol_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_ethanol_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentration_h2_raw +What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_h2_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentration_voc_raw What: /sys/bus/iio/devices/iio:deviceX/in_concentrationX_voc_raw KernelVersion: 4.3 @@ -1684,4 +1688,19 @@ KernelVersion: 4.18 Contact: linux-iio@vger.kernel.org Description: Raw (unscaled) phase difference reading from channel Y - that can be processed to radians.
\ No newline at end of file + that can be processed to radians. + +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm1_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm1_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm2p5_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm2p5_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm4_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm4_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentration_pm10_input +What: /sys/bus/iio/devices/iio:deviceX/in_massconcentrationY_pm10_input +KernelVersion: 4.22 +Contact: linux-iio@vger.kernel.org +Description: + Mass concentration reading of particulate matter in ug / m3. + pmX consists of particles with aerodynamic diameter less or + equal to X micrometers. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-sps30 b/Documentation/ABI/testing/sysfs-bus-iio-sps30 new file mode 100644 index 000000000000..143df8e89d08 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-sps30 @@ -0,0 +1,28 @@ +What: /sys/bus/iio/devices/iio:deviceX/start_cleaning +Date: December 2018 +KernelVersion: 4.22 +Contact: linux-iio@vger.kernel.org +Description: + Writing 1 starts sensor self cleaning. Internal fan accelerates + to its maximum speed and keeps spinning for about 10 seconds in + order to blow out accumulated dust. + +What: /sys/bus/iio/devices/iio:deviceX/cleaning_period +Date: January 2019 +KernelVersion: 5.1 +Contact: linux-iio@vger.kernel.org +Description: + Sensor is capable of triggering self cleaning periodically. + Period can be changed by writing a new value here. Upon reading + the current one is returned. Units are seconds. + + Writing 0 disables periodical self cleaning entirely. + +What: /sys/bus/iio/devices/iio:deviceX/cleaning_period_available +Date: January 2019 +KernelVersion: 5.1 +Contact: linux-iio@vger.kernel.org +Description: + The range of available values in seconds represented as the + minimum value, the step and the maximum value, all enclosed in + square brackets. diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices index 4d48a9451866..d1f667104944 100644 --- a/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-output-devices @@ -3,11 +3,13 @@ Date: June 2015 KernelVersion: 4.3 Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> Description: (RW) Writes of 1 or 0 enable or disable trace output to this - output device. Reads return current status. + output device. Reads return current status. Requires that the + correstponding output port driver be loaded. What: /sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/port Date: June 2015 KernelVersion: 4.3 Contact: Alexander Shishkin <alexander.shishkin@linux.intel.com> Description: (RO) Port number, corresponding to this output device on the - switch (GTH). + switch (GTH) or "unassigned" if the corresponding output + port driver is not loaded. diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt index 151584a1f950..b21fba14689b 100644 --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt @@ -21,6 +21,15 @@ Description: Holds a comma separated list of device unique_ids that If a device is authorized automatically during boot its boot attribute is set to 1. +What: /sys/bus/thunderbolt/devices/.../domainX/iommu_dma_protection +Date: Mar 2019 +KernelVersion: 4.21 +Contact: thunderbolt-software@lists.01.org +Description: This attribute tells whether the system uses IOMMU + for DMA protection. Value of 1 means IOMMU is used 0 means + it is not (DMA protection is solely based on Thunderbolt + security levels). + What: /sys/bus/thunderbolt/devices/.../domainX/security Date: Sep 2017 KernelVersion: 4.13 diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 08d456e07b53..614d216dff1d 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -186,9 +186,19 @@ Contact: Lan Tianyu <tianyu.lan@intel.com> Description: Some platforms provide usb port connect types through ACPI. This attribute is to expose these information to user space. - The file will read "hotplug", "wired" and "not used" if the + The file will read "hotplug", "hardwired" and "not used" if the information is available, and "unknown" otherwise. +What: /sys/bus/usb/devices/.../(hub interface)/portX/location +Date: October 2018 +Contact: Bjørn Mork <bjorn@mork.no> +Description: + Some platforms provide usb port physical location through + firmware. This is used by the kernel to pair up logical ports + mapping to the same physical connector. The attribute exposes the + raw location value as a hex integer. + + What: /sys/bus/usb/devices/.../(hub interface)/portX/quirks Date: May 2018 Contact: Nicolas Boichat <drinkcat@chromium.org> @@ -219,7 +229,14 @@ Description: ports and report them to the kernel. This attribute is to expose the number of over-current situation occurred on a specific port to user space. This file will contain an unsigned 32 bit value - which wraps to 0 after its maximum is reached. + which wraps to 0 after its maximum is reached. This file supports + poll() for monitoring changes to this value in user space. + + Any time this value changes the corresponding hub device will send a + udev event with the following attributes: + + OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX + OVER_CURRENT_COUNT=[current value of this sysfs attribute] What: /sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit Date: November 2015 diff --git a/Documentation/ABI/testing/sysfs-bus-vmbus b/Documentation/ABI/testing/sysfs-bus-vmbus new file mode 100644 index 000000000000..91e6c065973c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-vmbus @@ -0,0 +1,21 @@ +What: /sys/bus/vmbus/devices/.../driver_override +Date: August 2019 +Contact: Stephen Hemminger <sthemmin@microsoft.com> +Description: + This file allows the driver for a device to be specified which + will override standard static and dynamic ID matching. When + specified, only a driver with a name matching the value written + to driver_override will have an opportunity to bind to the + device. The override is specified by writing a string to the + driver_override file (echo uio_hv_generic > driver_override) and + may be cleared with an empty string (echo > driver_override). + This returns the device to standard matching rules binding. + Writing to driver_override does not automatically unbind the + device from its current driver or make any attempt to + automatically load the specified driver. If no driver with a + matching name is currently loaded in the kernel, the device + will not bind to any driver. This also allows devices to + opt-out of driver binding using a driver_override name such as + "none". Only a single driver may be specified in the override, + there is no support for parsing delimiters. + diff --git a/Documentation/ABI/testing/sysfs-class-chromeos b/Documentation/ABI/testing/sysfs-class-chromeos new file mode 100644 index 000000000000..5819699d66ec --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-chromeos @@ -0,0 +1,32 @@ +What: /sys/class/chromeos/<ec-device-name>/flashinfo +Date: August 2015 +KernelVersion: 4.2 +Description: + Show the EC flash information. + +What: /sys/class/chromeos/<ec-device-name>/kb_wake_angle +Date: March 2018 +KernelVersion: 4.17 +Description: + Control the keyboard wake lid angle. Values are between + 0 and 360. This file will also show the keyboard wake lid + angle by querying the hardware. + +What: /sys/class/chromeos/<ec-device-name>/reboot +Date: August 2015 +KernelVersion: 4.2 +Description: + Tell the EC to reboot in various ways. Options are: + "cancel": Cancel a pending reboot. + "ro": Jump to RO without rebooting. + "rw": Jump to RW without rebooting. + "cold": Cold reboot. + "disable-jump": Disable jump until next reboot. + "hibernate": Hibernate the EC. + "at-shutdown": Reboot after an AP shutdown. + +What: /sys/class/chromeos/<ec-device-name>/version +Date: August 2015 +KernelVersion: 4.2 +Description: + Show the information about the EC software and hardware. diff --git a/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar new file mode 100644 index 000000000000..57a037791403 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-lightbar @@ -0,0 +1,74 @@ +What: /sys/class/chromeos/<ec-device-name>/lightbar/brightness +Date: August 2015 +KernelVersion: 4.2 +Description: + Writing to this file adjusts the overall brightness of + the lightbar, separate from any color intensity. The + valid range is 0 (off) to 255 (maximum brightness). + +What: /sys/class/chromeos/<ec-device-name>/lightbar/interval_msec +Date: August 2015 +KernelVersion: 4.2 +Description: + The lightbar is controlled by an embedded controller (EC), + which also manages the keyboard, battery charging, fans, + and other system hardware. To prevent unprivileged users + from interfering with the other EC functions, the rate at + which the lightbar control files can be read or written is + limited. + + Reading this file will return the number of milliseconds + that must elapse between accessing any of the lightbar + functions through this interface. Going faster will simply + block until the necessary interval has lapsed. The interval + applies uniformly to all accesses of any kind by any user. + +What: /sys/class/chromeos/<ec-device-name>/lightbar/led_rgb +Date: August 2015 +KernelVersion: 4.2 +Description: + This allows you to control each LED segment. If the + lightbar is already running one of the automatic + sequences, you probably won’t see anything change because + your color setting will be almost immediately replaced. + To get useful results, you should stop the lightbar + sequence first. + + The values written to this file are sets of four integers, + indicating LED, RED, GREEN, BLUE. The LED number is 0 to 3 + to select a single segment, or 4 to set all four segments + to the same value at once. The RED, GREEN, and BLUE + numbers should be in the range 0 (off) to 255 (maximum). + You can update more than one segment at a time by writing + more than one set of four integers. + +What: /sys/class/chromeos/<ec-device-name>/lightbar/program +Date: August 2015 +KernelVersion: 4.2 +Description: + This allows you to upload and run custom lightbar sequences. + +What: /sys/class/chromeos/<ec-device-name>/lightbar/sequence +Date: August 2015 +KernelVersion: 4.2 +Description: + The Pixel lightbar has a number of built-in sequences + that it displays under various conditions, such as at + power on, shut down, or while running. Reading from this + file displays the current sequence that the lightbar is + displaying. Writing to this file allows you to change the + sequence. + +What: /sys/class/chromeos/<ec-device-name>/lightbar/userspace_control +Date: August 2015 +KernelVersion: 4.2 +Description: + This allows you to take the control of the lightbar. This + prevents the kernel from going through its normal + sequences. + +What: /sys/class/chromeos/<ec-device-name>/lightbar/version +Date: August 2015 +KernelVersion: 4.2 +Description: + Show the information about the lightbar version. diff --git a/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc new file mode 100644 index 000000000000..38c5aaaaa89a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-chromeos-driver-cros-ec-vbc @@ -0,0 +1,6 @@ +What: /sys/class/chromeos/<ec-device-name>/vbc/vboot_context +Date: October 2015 +KernelVersion: 4.4 +Description: + Read/write the verified boot context data included on a + small nvram space on some EC implementations. diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern index fb3d1e03b881..bd92ef9d6faa 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern @@ -7,55 +7,10 @@ Description: timer. It can do gradual dimming and step change of brightness. The pattern is given by a series of tuples, of brightness and - duration (ms). The LED is expected to traverse the series and - each brightness value for the specified duration. Duration of - 0 means brightness should immediately change to new value, and - writing malformed pattern deactivates any active one. + duration (ms). - 1. For gradual dimming, the dimming interval now is set as 50 - milliseconds. So the tuple with duration less than dimming - interval (50ms) is treated as a step change of brightness, - i.e. the subsequent brightness will be applied without adding - intervening dimming intervals. - - The gradual dimming format of the software pattern values should be: - "brightness_1 duration_1 brightness_2 duration_2 brightness_3 - duration_3 ...". For example: - - echo 0 1000 255 2000 > pattern - - It will make the LED go gradually from zero-intensity to max (255) - intensity in 1000 milliseconds, then back to zero intensity in 2000 - milliseconds: - - LED brightness - ^ - 255-| / \ / \ / - | / \ / \ / - | / \ / \ / - | / \ / \ / - 0-| / \/ \/ - +---0----1----2----3----4----5----6------------> time (s) - - 2. To make the LED go instantly from one brigntess value to another, - we should use use zero-time lengths (the brightness must be same as - the previous tuple's). So the format should be: - "brightness_1 duration_1 brightness_1 0 brightness_2 duration_2 - brightness_2 0 ...". For example: - - echo 0 1000 0 0 255 2000 255 0 > pattern - - It will make the LED stay off for one second, then stay at max brightness - for two seconds: - - LED brightness - ^ - 255-| +---------+ +---------+ - | | | | | - | | | | | - | | | | | - 0-| -----+ +----+ +---- - +---0----1----2----3----4----5----6------------> time (s) + The exact format is described in: + Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt What: /sys/class/leds/<led>/hw_pattern Date: September 2018 diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net index e2e0fe553ad8..664a8f6a634f 100644 --- a/Documentation/ABI/testing/sysfs-class-net +++ b/Documentation/ABI/testing/sysfs-class-net @@ -91,6 +91,24 @@ Description: stacked (e.g: VLAN interfaces) but still have the same MAC address as their parent device. +What: /sys/class/net/<iface>/dev_port +Date: February 2014 +KernelVersion: 3.15 +Contact: netdev@vger.kernel.org +Description: + Indicates the port number of this network device, formatted + as a decimal value. Some NICs have multiple independent ports + on the same PCI bus, device and function. This attribute allows + userspace to distinguish the respective interfaces. + + Note: some device drivers started to use 'dev_id' for this + purpose since long before 3.15 and have not adopted the new + attribute ever since. To query the port number, some tools look + exclusively at 'dev_port', while others only consult 'dev_id'. + If a network device has multiple client adapter ports as + described in the previous paragraph and does not set this + attribute to its port number, it's a kernel bug. + What: /sys/class/net/<iface>/dormant Date: March 2006 KernelVersion: 2.6.17 diff --git a/Documentation/ABI/testing/sysfs-class-net-dsa b/Documentation/ABI/testing/sysfs-class-net-dsa index f240221e071e..985d84c585c6 100644 --- a/Documentation/ABI/testing/sysfs-class-net-dsa +++ b/Documentation/ABI/testing/sysfs-class-net-dsa @@ -1,4 +1,4 @@ -What: /sys/class/net/<iface>/tagging +What: /sys/class/net/<iface>/dsa/tagging Date: August 2018 KernelVersion: 4.20 Contact: netdev@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-devices-software_node b/Documentation/ABI/testing/sysfs-devices-software_node new file mode 100644 index 000000000000..85df37de359f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-software_node @@ -0,0 +1,10 @@ +What: /sys/devices/.../software_node/ +Date: January 2019 +Contact: Heikki Krogerus <heikki.krogerus@linux.intel.com> +Description: + This directory contains the details about the device that are + assigned in kernel (i.e. software), as opposed to the + firmware_node directory which contains the details that are + assigned for the device in firmware. The main attributes in the + directory will show the properties the device has, and the + relationship it has to some of the other devices. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 73318225a368..9605dbd4b5b5 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -145,6 +145,8 @@ What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/name /sys/devices/system/cpu/cpuX/cpuidle/stateN/power /sys/devices/system/cpu/cpuX/cpuidle/stateN/time /sys/devices/system/cpu/cpuX/cpuidle/stateN/usage + /sys/devices/system/cpu/cpuX/cpuidle/stateN/above + /sys/devices/system/cpu/cpuX/cpuidle/stateN/below Date: September 2007 KernelVersion: v2.6.24 Contact: Linux power management list <linux-pm@vger.kernel.org> @@ -166,6 +168,11 @@ Description: usage: (RO) Number of times this state was entered (a count). + above: (RO) Number of times this state was entered, but the + observed CPU idle duration was too short for it (a count). + + below: (RO) Number of times this state was entered, but the + observed CPU idle duration was too long for it (a count). What: /sys/devices/system/cpu/cpuX/cpuidle/stateN/desc Date: February 2008 diff --git a/Documentation/ABI/testing/sysfs-driver-habanalabs b/Documentation/ABI/testing/sysfs-driver-habanalabs new file mode 100644 index 000000000000..78b2bcf316a3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-habanalabs @@ -0,0 +1,190 @@ +What: /sys/class/habanalabs/hl<n>/armcp_kernel_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the Linux kernel running on the device's CPU + +What: /sys/class/habanalabs/hl<n>/armcp_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the application running on the device's CPU + +What: /sys/class/habanalabs/hl<n>/cpld_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the Device's CPLD F/W + +What: /sys/class/habanalabs/hl<n>/device_type +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the code name of the device according to its type. + The supported values are: "GOYA" + +What: /sys/class/habanalabs/hl<n>/eeprom +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: A binary file attribute that contains the contents of the + on-board EEPROM + +What: /sys/class/habanalabs/hl<n>/fuse_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the device's version from the eFuse + +What: /sys/class/habanalabs/hl<n>/hard_reset +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Interface to trigger a hard-reset operation for the device. + Hard-reset will reset ALL internal components of the device + except for the PCI interface and the internal PLLs + +What: /sys/class/habanalabs/hl<n>/hard_reset_cnt +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays how many times the device have undergone a hard-reset + operation since the driver was loaded + +What: /sys/class/habanalabs/hl<n>/high_pll +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the user to set the maximum clock frequency for MME, TPC + and IC when the power management profile is set to "automatic". + +What: /sys/class/habanalabs/hl<n>/ic_clk +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the user to set the maximum clock frequency of the + Interconnect fabric. Writes to this parameter affect the device + only when the power management profile is set to "manual" mode. + The device IC clock might be set to lower value then the + maximum. The user should read the ic_clk_curr to see the actual + frequency value of the IC + +What: /sys/class/habanalabs/hl<n>/ic_clk_curr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the current clock frequency of the Interconnect fabric + +What: /sys/class/habanalabs/hl<n>/infineon_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the Device's power supply F/W code + +What: /sys/class/habanalabs/hl<n>/max_power +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the user to set the maximum power consumption of the + device in milliwatts. + +What: /sys/class/habanalabs/hl<n>/mme_clk +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the user to set the maximum clock frequency of the + MME compute engine. Writes to this parameter affect the device + only when the power management profile is set to "manual" mode. + The device MME clock might be set to lower value then the + maximum. The user should read the mme_clk_curr to see the actual + frequency value of the MME + +What: /sys/class/habanalabs/hl<n>/mme_clk_curr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the current clock frequency of the MME compute engine + +What: /sys/class/habanalabs/hl<n>/pci_addr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the PCI address of the device. This is needed so the + user would be able to open a device based on its PCI address + +What: /sys/class/habanalabs/hl<n>/pm_mng_profile +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Power management profile. Values are "auto", "manual". In "auto" + mode, the driver will set the maximum clock frequency to a high + value when a user-space process opens the device's file (unless + it was already opened by another process). The driver will set + the max clock frequency to a low value when there are no user + processes that are opened on the device's file. In "manual" + mode, the user sets the maximum clock frequency by writing to + ic_clk, mme_clk and tpc_clk + + +What: /sys/class/habanalabs/hl<n>/preboot_btl_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the device's preboot F/W code + +What: /sys/class/habanalabs/hl<n>/soft_reset +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Interface to trigger a soft-reset operation for the device. + Soft-reset will reset only the compute and DMA engines of the + device + +What: /sys/class/habanalabs/hl<n>/soft_reset_cnt +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays how many times the device have undergone a soft-reset + operation since the driver was loaded + +What: /sys/class/habanalabs/hl<n>/status +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Status of the card: "Operational", "Malfunction", "In reset". + +What: /sys/class/habanalabs/hl<n>/thermal_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the Device's thermal daemon + +What: /sys/class/habanalabs/hl<n>/tpc_clk +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Allows the user to set the maximum clock frequency of the + TPC compute engines. Writes to this parameter affect the device + only when the power management profile is set to "manual" mode. + The device TPC clock might be set to lower value then the + maximum. The user should read the tpc_clk_curr to see the actual + frequency value of the TPC + +What: /sys/class/habanalabs/hl<n>/tpc_clk_curr +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the current clock frequency of the TPC compute engines + +What: /sys/class/habanalabs/hl<n>/uboot_ver +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Version of the u-boot running on the device's CPU + +What: /sys/class/habanalabs/hl<n>/write_open_cnt +Date: Jan 2019 +KernelVersion: 5.1 +Contact: oded.gabbay@gmail.com +Description: Displays the total number of user processes that are currently + opened on the device's file diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 3ac41774ad3c..a7ce33199457 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -92,6 +92,15 @@ Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> Description: Controls the number of trials to find a victim segment. +What: /sys/fs/f2fs/<disk>/migration_granularity +Date: October 2018 +Contact: "Chao Yu" <yuchao0@huawei.com> +Description: + Controls migration granularity of garbage collection on large + section, it can let GC move partial segment{s} of one section + in one GC cycle, so that dispersing heavy overhead GC to + multiple lightweight one. + What: /sys/fs/f2fs/<disk>/dir_level Date: March 2014 Contact: "Jaegeuk Kim" <jaegeuk.kim@samsung.com> diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch index dac7e1e62a8b..85db352f68f9 100644 --- a/Documentation/ABI/testing/sysfs-kernel-livepatch +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch @@ -33,18 +33,6 @@ Description: An attribute which indicates whether the patch is currently in transition. -What: /sys/kernel/livepatch/<patch>/signal -Date: Nov 2017 -KernelVersion: 4.15.0 -Contact: live-patching@vger.kernel.org -Description: - A writable attribute that allows administrator to affect the - course of an existing transition. Writing 1 sends a fake - signal to all remaining blocking tasks. The fake signal - means that no proper signal is delivered (there is no data in - signal pending structures). Tasks are interrupted or woken up, - and forced to change their patched state. - What: /sys/kernel/livepatch/<patch>/force Date: Nov 2017 KernelVersion: 4.15.0 diff --git a/Documentation/ABI/testing/sysfs-platform-lg-laptop b/Documentation/ABI/testing/sysfs-platform-lg-laptop new file mode 100644 index 000000000000..cf47749b19df --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-lg-laptop @@ -0,0 +1,35 @@ +What: /sys/devices/platform/lg-laptop/reader_mode +Date: October 2018 +KernelVersion: 4.20 +Contact: "Matan Ziv-Av <matan@svgalib.org> +Description: + Control reader mode. 1 means on, 0 means off. + +What: /sys/devices/platform/lg-laptop/fn_lock +Date: October 2018 +KernelVersion: 4.20 +Contact: "Matan Ziv-Av <matan@svgalib.org> +Description: + Control FN lock mode. 1 means on, 0 means off. + +What: /sys/devices/platform/lg-laptop/battery_care_limit +Date: October 2018 +KernelVersion: 4.20 +Contact: "Matan Ziv-Av <matan@svgalib.org> +Description: + Maximal battery charge level. Accepted values are 80 or 100. + +What: /sys/devices/platform/lg-laptop/fan_mode +Date: October 2018 +KernelVersion: 4.20 +Contact: "Matan Ziv-Av <matan@svgalib.org> +Description: + Control fan mode. 1 for performance mode, 0 for silent mode. + +What: /sys/devices/platform/lg-laptop/usb_charge +Date: October 2018 +KernelVersion: 4.20 +Contact: "Matan Ziv-Av <matan@svgalib.org> +Description: + Control USB port charging when device is turned off. + 1 means on, 0 means off. diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index ac66ae2509a9..e133ccd60228 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -60,15 +60,6 @@ the returned memory, like GFP_DMA). :: - void * - dma_zalloc_coherent(struct device *dev, size_t size, - dma_addr_t *dma_handle, gfp_t flag) - -Wraps dma_alloc_coherent() and also zeroes the returned memory if the -allocation attempt succeeded. - -:: - void dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, dma_addr_t dma_handle) @@ -717,12 +708,15 @@ dma-api/num_errors The number in this file shows how many dma-api/min_free_entries This read-only file can be read to get the minimum number of free dma_debug_entries the allocator has ever seen. If this value goes - down to zero the code will disable itself - because it is not longer reliable. + down to zero the code will attempt to increase + nr_total_entries to compensate. dma-api/num_free_entries The current number of free dma_debug_entries in the allocator. +dma-api/nr_total_entries The total number of dma_debug_entries in the + allocator, both free and used. + dma-api/driver-filter You can write a name of a driver into this file to limit the debug output to requests from that particular driver. Write an empty string to @@ -742,10 +736,15 @@ driver filter at boot time. The debug code will only print errors for that driver afterwards. This filter can be disabled or changed later using debugfs. When the code disables itself at runtime this is most likely because it ran -out of dma_debug_entries. These entries are preallocated at boot. The number -of preallocated entries is defined per architecture. If it is too low for you -boot with 'dma_debug_entries=<your_desired_number>' to overwrite the -architectural default. +out of dma_debug_entries and was unable to allocate more on-demand. 65536 +entries are preallocated at boot - if this is too low for you boot with +'dma_debug_entries=<your_desired_number>' to overwrite the default. Note +that the code allocates entries in batches, so the exact number of +preallocated entries may be greater than the actual number requested. The +code will print to the kernel log each time it has dynamically allocated +as many entries as were initially preallocated. This is to indicate that a +larger preallocation size may be appropriate, or if it happens continually +that a driver may be leaking mappings. :: diff --git a/Documentation/EDID/1024x768.S b/Documentation/EDID/1024x768.S index 6f3e4b75e49e..4aed3f9ab88a 100644 --- a/Documentation/EDID/1024x768.S +++ b/Documentation/EDID/1024x768.S @@ -31,14 +31,13 @@ #define YBLANK 38 #define XOFFSET 8 #define XPULSE 144 -#define YOFFSET (63+3) -#define YPULSE (63+6) +#define YOFFSET 3 +#define YPULSE 6 #define DPI 72 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux XGA" #define ESTABLISHED_TIMING2_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */ #define HSYNC_POL 0 #define VSYNC_POL 0 -#define CRC 0x55 #include "edid.S" diff --git a/Documentation/EDID/1280x1024.S b/Documentation/EDID/1280x1024.S index bd9bef2a65af..b26dd424cad7 100644 --- a/Documentation/EDID/1280x1024.S +++ b/Documentation/EDID/1280x1024.S @@ -31,14 +31,13 @@ #define YBLANK 42 #define XOFFSET 48 #define XPULSE 112 -#define YOFFSET (63+1) -#define YPULSE (63+3) +#define YOFFSET 1 +#define YPULSE 3 #define DPI 72 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux SXGA" /* No ESTABLISHED_TIMINGx_BITS */ #define HSYNC_POL 1 #define VSYNC_POL 1 -#define CRC 0xa0 #include "edid.S" diff --git a/Documentation/EDID/1600x1200.S b/Documentation/EDID/1600x1200.S index a45101c6160c..0d091b282768 100644 --- a/Documentation/EDID/1600x1200.S +++ b/Documentation/EDID/1600x1200.S @@ -31,14 +31,13 @@ #define YBLANK 50 #define XOFFSET 64 #define XPULSE 192 -#define YOFFSET (63+1) -#define YPULSE (63+3) +#define YOFFSET 1 +#define YPULSE 3 #define DPI 72 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux UXGA" /* No ESTABLISHED_TIMINGx_BITS */ #define HSYNC_POL 1 #define VSYNC_POL 1 -#define CRC 0x9d #include "edid.S" diff --git a/Documentation/EDID/1680x1050.S b/Documentation/EDID/1680x1050.S index b0d7c69282b4..7dfed9a33eab 100644 --- a/Documentation/EDID/1680x1050.S +++ b/Documentation/EDID/1680x1050.S @@ -31,14 +31,13 @@ #define YBLANK 39 #define XOFFSET 104 #define XPULSE 176 -#define YOFFSET (63+3) -#define YPULSE (63+6) +#define YOFFSET 3 +#define YPULSE 6 #define DPI 96 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux WSXGA" /* No ESTABLISHED_TIMINGx_BITS */ #define HSYNC_POL 1 #define VSYNC_POL 1 -#define CRC 0x26 #include "edid.S" diff --git a/Documentation/EDID/1920x1080.S b/Documentation/EDID/1920x1080.S index 3084355e81e7..d6ffbba28e95 100644 --- a/Documentation/EDID/1920x1080.S +++ b/Documentation/EDID/1920x1080.S @@ -31,14 +31,13 @@ #define YBLANK 45 #define XOFFSET 88 #define XPULSE 44 -#define YOFFSET (63+4) -#define YPULSE (63+5) +#define YOFFSET 4 +#define YPULSE 5 #define DPI 96 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux FHD" /* No ESTABLISHED_TIMINGx_BITS */ #define HSYNC_POL 1 #define VSYNC_POL 1 -#define CRC 0x05 #include "edid.S" diff --git a/Documentation/EDID/800x600.S b/Documentation/EDID/800x600.S index 6644e26d5801..a5616588de08 100644 --- a/Documentation/EDID/800x600.S +++ b/Documentation/EDID/800x600.S @@ -28,14 +28,13 @@ #define YBLANK 28 #define XOFFSET 40 #define XPULSE 128 -#define YOFFSET (63+1) -#define YPULSE (63+4) +#define YOFFSET 1 +#define YPULSE 4 #define DPI 72 #define VFREQ 60 /* Hz */ #define TIMING_NAME "Linux SVGA" #define ESTABLISHED_TIMING1_BITS 0x01 /* Bit 0: 800x600 @ 60Hz */ #define HSYNC_POL 1 #define VSYNC_POL 1 -#define CRC 0xc2 #include "edid.S" diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/HOWTO.txt index 835db332289b..539871c3b785 100644 --- a/Documentation/EDID/HOWTO.txt +++ b/Documentation/EDID/HOWTO.txt @@ -45,14 +45,5 @@ EDID: #define YPIX vdisp #define YBLANK vtotal-vdisp -#define YOFFSET (63+(vsyncstart-vdisp)) -#define YPULSE (63+(vsyncend-vsyncstart)) - -The CRC value in the last line - #define CRC 0x55 -also is a bit tricky. After a first version of the binary data set is -created, it must be checked with the "edid-decode" utility which will -most probably complain about a wrong CRC. Fortunately, the utility also -displays the correct CRC which must then be inserted into the source -file. After the make procedure is repeated, the EDID data set is ready -to be used. +#define YOFFSET vsyncstart-vdisp +#define YPULSE vsyncend-vsyncstart diff --git a/Documentation/EDID/Makefile b/Documentation/EDID/Makefile index 17763ca3f12b..85a927dfab02 100644 --- a/Documentation/EDID/Makefile +++ b/Documentation/EDID/Makefile @@ -15,10 +15,21 @@ clean: %.o: %.S @cc -c $^ -%.bin: %.o +%.bin.nocrc: %.o @objcopy -Obinary $^ $@ -%.bin.ihex: %.o +%.crc: %.bin.nocrc + @list=$$(for i in `seq 1 127`; do head -c$$i $^ | tail -c1 \ + | hexdump -v -e '/1 "%02X+"'; done); \ + echo "ibase=16;100-($${list%?})%100" | bc >$@ + +%.p: %.crc %.S + @cc -c -DCRC="$$(cat $*.crc)" -o $@ $*.S + +%.bin: %.p + @objcopy -Obinary $^ $@ + +%.bin.ihex: %.p @objcopy -Oihex $^ $@ @dos2unix $@ 2>/dev/null diff --git a/Documentation/EDID/edid.S b/Documentation/EDID/edid.S index ef082dcc6084..c3d13815526d 100644 --- a/Documentation/EDID/edid.S +++ b/Documentation/EDID/edid.S @@ -47,9 +47,11 @@ #define mfgname2id(v1,v2,v3) \ ((((v1-'@')&0x1f)<<10)+(((v2-'@')&0x1f)<<5)+((v3-'@')&0x1f)) #define swap16(v1) ((v1>>8)+((v1&0xff)<<8)) +#define lsbs2(v1,v2) (((v1&0x0f)<<4)+(v2&0x0f)) #define msbs2(v1,v2) ((((v1>>8)&0x0f)<<4)+((v2>>8)&0x0f)) #define msbs4(v1,v2,v3,v4) \ - (((v1&0x03)>>2)+((v2&0x03)>>4)+((v3&0x03)>>6)+((v4&0x03)>>8)) + ((((v1>>8)&0x03)<<6)+(((v2>>8)&0x03)<<4)+\ + (((v3>>4)&0x03)<<2)+((v4>>4)&0x03)) #define pixdpi2mm(pix,dpi) ((pix*25)/dpi) #define xsize pixdpi2mm(XPIX,DPI) #define ysize pixdpi2mm(YPIX,DPI) @@ -200,9 +202,9 @@ y_msbs: .byte msbs2(YPIX,YBLANK) x_snc_off_lsb: .byte XOFFSET&0xff /* Horizontal sync pulse width pixels 8 lsbits (0-1023) */ x_snc_pls_lsb: .byte XPULSE&0xff -/* Bits 7-4 Vertical sync offset lines 4 lsbits -63) - Bits 3-0 Vertical sync pulse width lines 4 lsbits -63) */ -y_snc_lsb: .byte ((YOFFSET-63)<<4)+(YPULSE-63) +/* Bits 7-4 Vertical sync offset lines 4 lsbits (0-63) + Bits 3-0 Vertical sync pulse width lines 4 lsbits (0-63) */ +y_snc_lsb: .byte lsbs2(YOFFSET, YPULSE) /* Bits 7-6 Horizontal sync offset pixels 2 msbits Bits 5-4 Horizontal sync pulse width pixels 2 msbits Bits 3-2 Vertical sync offset lines 2 msbits diff --git a/Documentation/Makefile b/Documentation/Makefile index 2ca77ad0f238..9786957c6a35 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,7 +2,7 @@ # Makefile for Sphinx documentation # -subdir-y := +subdir-y := devicetree/bindings/ # You can set these variables from the command line. SPHINXBUILD = sphinx-build diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg deleted file mode 100644 index 9bbb1944f962..000000000000 --- a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBH.svg +++ /dev/null @@ -1,499 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> - -<!-- CreationDate: Wed Dec 9 17:26:09 2015 --> - -<!-- Magnification: 2.000 --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="5.7in" - height="6.6in" - viewBox="-44 -44 6838 7888" - id="svg2" - version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="BigTreeClassicRCUBH.fig"> - <metadata - id="metadata110"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <defs - id="defs108"> - <marker - inkscape:stockid="Arrow1Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mend" - style="overflow:visible;"> - <path - id="path3868" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Mend" - style="overflow:visible;"> - <path - id="path3886" - style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(0.6) rotate(180) translate(0,0)" /> - </marker> - </defs> - <sodipodi:namedview - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1" - objecttolerance="10" - gridtolerance="10" - guidetolerance="10" - inkscape:pageopacity="0" - inkscape:pageshadow="2" - inkscape:window-width="878" - inkscape:window-height="1148" - id="namedview106" - showgrid="false" - inkscape:zoom="1.3547758" - inkscape:cx="256.5" - inkscape:cy="297" - inkscape:window-x="45" - inkscape:window-y="24" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> - <g - style="stroke-width:.025in; fill:none" - id="g4"> - <!-- Line: box --> - <rect - x="450" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> - <!-- Line: box --> - <rect - x="4950" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect8" /> - <!-- Line: box --> - <rect - x="750" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect10" /> - <!-- Line: box --> - <rect - x="0" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect12" /> - <!-- Line: box --> - <rect - x="300" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect14" /> - <!-- Circle --> - <circle - cx="2850" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle16" /> - <!-- Circle --> - <circle - cx="3150" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle18" /> - <!-- Circle --> - <circle - cx="3450" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle20" /> - <!-- Circle --> - <circle - cx="1350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle22" /> - <!-- Circle --> - <circle - cx="1650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle24" /> - <!-- Circle --> - <circle - cx="1950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle26" /> - <!-- Circle --> - <circle - cx="4350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle28" /> - <!-- Circle --> - <circle - cx="4650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle30" /> - <!-- Circle --> - <circle - cx="4950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle32" /> - <!-- Line --> - <polyline - points="1350,3450 2350,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline34" /> - <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> - <!-- Line --> - <polyline - points="4950,3450 3948,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline38" /> - <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> - <!-- Line: box --> - <rect - x="750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect42" /> - <!-- Line --> - <polyline - points="2250,5400 2250,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline44" /> - <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> - <!-- Line: box --> - <rect - x="1500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect48" /> - <!-- Line: box --> - <rect - x="300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect50" /> - <!-- Line: box --> - <rect - x="3750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect52" /> - <!-- Line: box --> - <rect - x="4500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect54" /> - <!-- Line: box --> - <rect - x="3300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect56" /> - <!-- Line: box --> - <rect - x="2250" - y="1650" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect58" /> - <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text60">rcu_bh</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="1950" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text62">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2250" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text64">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text66">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text68">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text70">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text72">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text74">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text76">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text78">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text80">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text82">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text84">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text86">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text88">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="450" - y="1350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="start" - id="text90">struct rcu_state</text> - <!-- Text --> - <text - xml:space="preserve" - x="6000" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text92">rcu_sched</text> - <!-- Line --> - <polyline - points="5250,5400 5250,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline94" /> - <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> - <!-- Line --> - <polyline - points="4050,6600 4050,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline98" /> - <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> - <!-- Line --> - <polyline - points="1050,6600 1050,4414 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline102" /> - <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> - </g> -</svg> diff --git a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg b/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg deleted file mode 100644 index 21ba7823479d..000000000000 --- a/Documentation/RCU/Design/Data-Structures/BigTreeClassicRCUBHdyntick.svg +++ /dev/null @@ -1,695 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> - -<!-- CreationDate: Wed Dec 9 17:20:02 2015 --> - -<!-- Magnification: 2.000 --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="5.7in" - height="8.6in" - viewBox="-44 -44 6838 10288" - id="svg2" - version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="BigTreeClassicRCUBHdyntick.fig"> - <metadata - id="metadata166"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <defs - id="defs164"> - <marker - inkscape:stockid="Arrow1Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mend" - style="overflow:visible;"> - <path - id="path3924" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> - </marker> - <marker - inkscape:stockid="Arrow2Lend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow2Lend" - style="overflow:visible;"> - <path - id="path3936" - style="fill-rule:evenodd;stroke-width:0.62500000;stroke-linejoin:round;" - d="M 8.7185878,4.0337352 L -2.2072895,0.016013256 L 8.7185884,-4.0017078 C 6.9730900,-1.6296469 6.9831476,1.6157441 8.7185878,4.0337352 z " - transform="scale(1.1) rotate(180) translate(1,0)" /> - </marker> - </defs> - <sodipodi:namedview - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1" - objecttolerance="10" - gridtolerance="10" - guidetolerance="10" - inkscape:pageopacity="0" - inkscape:pageshadow="2" - inkscape:window-width="845" - inkscape:window-height="988" - id="namedview162" - showgrid="false" - inkscape:zoom="1.0452196" - inkscape:cx="256.5" - inkscape:cy="387.00003" - inkscape:window-x="356" - inkscape:window-y="61" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> - <g - style="stroke-width:.025in; fill:none" - id="g4"> - <!-- Line: box --> - <rect - x="450" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> - <!-- Line: box --> - <rect - x="4950" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect8" /> - <!-- Line: box --> - <rect - x="750" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect10" /> - <!-- Line --> - <polyline - points="5250,8100 5688,5912 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline12" /> - <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790--> - <polyline - points="5714 6068 5704 5822 5598 6044 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline14" /> - <!-- Line --> - <polyline - points="4050,9300 4486,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline16" /> - <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140--> - <polyline - points="4514 7418 4506 7172 4396 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline18" /> - <!-- Line --> - <polyline - points="1040,9300 1476,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline20" /> - <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140--> - <polyline - points="1504 7418 1496 7172 1386 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline22" /> - <!-- Line --> - <polyline - points="2240,8100 2676,6062 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline24" /> - <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940--> - <polyline - points="2704 6218 2696 5972 2586 6194 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline26" /> - <!-- Line: box --> - <rect - x="0" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect28" /> - <!-- Line: box --> - <rect - x="300" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect30" /> - <!-- Line --> - <polyline - points="1350,3450 2350,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline32" /> - <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> - <!-- Line --> - <polyline - points="4950,3450 3948,2590 " - style="stroke:#00d1d1;stroke-width:30.0045575;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline36" /> - <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> - <!-- Line --> - <polyline - points="4050,6600 4050,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline40" /> - <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> - <!-- Line --> - <polyline - points="1050,6600 1050,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline44" /> - <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> - <!-- Line --> - <polyline - points="2250,5400 2250,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline48" /> - <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> - <!-- Line --> - <polyline - points="2250,8100 2250,6364 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline52" /> - <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240--> - <!-- Line --> - <polyline - points="1050,9300 1050,7564 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline56" /> - <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440--> - <!-- Line --> - <polyline - points="4050,9300 4050,7564 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline60" /> - <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440--> - <!-- Line --> - <polyline - points="5250,8100 5250,6364 " - style="stroke:#00ff00;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline64" /> - <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240--> - <!-- Circle --> - <circle - cx="2850" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle68" /> - <!-- Circle --> - <circle - cx="3150" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle70" /> - <!-- Circle --> - <circle - cx="3450" - cy="3900" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle72" /> - <!-- Circle --> - <circle - cx="1350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle74" /> - <!-- Circle --> - <circle - cx="1650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle76" /> - <!-- Circle --> - <circle - cx="1950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle78" /> - <!-- Circle --> - <circle - cx="4350" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle80" /> - <!-- Circle --> - <circle - cx="4650" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle82" /> - <!-- Circle --> - <circle - cx="4950" - cy="5100" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle84" /> - <!-- Line: box --> - <rect - x="750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect86" /> - <!-- Line: box --> - <rect - x="300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect88" /> - <!-- Line: box --> - <rect - x="3750" - y="3450" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect90" /> - <!-- Line: box --> - <rect - x="4500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect92" /> - <!-- Line: box --> - <rect - x="3300" - y="6600" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect94" /> - <!-- Line: box --> - <rect - x="2250" - y="1650" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect96" /> - <!-- Line: box --> - <rect - x="0" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect98" /> - <!-- Line: box --> - <rect - x="1350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect100" /> - <!-- Line: box --> - <rect - x="3000" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect102" /> - <!-- Line: box --> - <rect - x="4350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect104" /> - <!-- Line: box --> - <rect - x="1500" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect106" /> - <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text108">rcu_bh</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="1950" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text110">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2250" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text112">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text114">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text116">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text118">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="3750" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text120">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text122">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text124">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text126">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text128">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="5700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text130">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6000" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text132">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="6900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text134">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text136">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="450" - y="1350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="start" - id="text138">struct rcu_state</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text140">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text142">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text144">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text146">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text148">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text150">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text152">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text154">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="6000" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text156">rcu_sched</text> - <!-- Line --> - <polyline - points="5250,5400 5250,4414 " - style="stroke:#00d1d1;stroke-width:30.00455750000000066;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline158" /> - <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> - </g> -</svg> diff --git a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg deleted file mode 100644 index 15adcac036c7..000000000000 --- a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntick.svg +++ /dev/null @@ -1,741 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Creator: fig2dev Version 3.2 Patchlevel 5e --> - -<!-- CreationDate: Wed Dec 9 17:32:59 2015 --> - -<!-- Magnification: 2.000 --> - -<svg - xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://creativecommons.org/ns#" - xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" - xmlns:svg="http://www.w3.org/2000/svg" - xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="6.1in" - height="8.9in" - viewBox="-44 -44 7288 10738" - id="svg2" - version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="BigTreePreemptRCUBHdyntick.fig"> - <metadata - id="metadata182"> - <rdf:RDF> - <cc:Work - rdf:about=""> - <dc:format>image/svg+xml</dc:format> - <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> - <dc:title></dc:title> - </cc:Work> - </rdf:RDF> - </metadata> - <defs - id="defs180"> - <marker - inkscape:stockid="Arrow1Mend" - orient="auto" - refY="0.0" - refX="0.0" - id="Arrow1Mend" - style="overflow:visible;"> - <path - id="path3940" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> - </marker> - </defs> - <sodipodi:namedview - pagecolor="#ffffff" - bordercolor="#666666" - borderopacity="1" - objecttolerance="10" - gridtolerance="10" - guidetolerance="10" - inkscape:pageopacity="0" - inkscape:pageshadow="2" - inkscape:window-width="874" - inkscape:window-height="1148" - id="namedview178" - showgrid="false" - inkscape:zoom="1.2097379" - inkscape:cx="274.5" - inkscape:cy="400.49997" - inkscape:window-x="946" - inkscape:window-y="24" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> - <g - style="stroke-width:.025in; fill:none" - id="g4"> - <!-- Line: box --> - <rect - x="900" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> - <!-- Line: box --> - <rect - x="1200" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect8" /> - <!-- Line: box --> - <rect - x="5400" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect10" /> - <!-- Line: box --> - <rect - x="450" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect12" /> - <!-- Line: box --> - <rect - x="750" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect14" /> - <!-- Line: box --> - <rect - x="4950" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect16" /> - <!-- Line --> - <polyline - points="5250,8550 5688,6362 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline18" /> - <!-- Arrowhead on XXXpoint 5250 8550 - 5710 6240--> - <polyline - points="5714 6518 5704 6272 5598 6494 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline20" /> - <!-- Line --> - <polyline - points="4050,9750 4486,7712 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline22" /> - <!-- Arrowhead on XXXpoint 4050 9750 - 4512 7590--> - <polyline - points="4514 7868 4506 7622 4396 7844 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline24" /> - <!-- Line --> - <polyline - points="1040,9750 1476,7712 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline26" /> - <!-- Arrowhead on XXXpoint 1040 9750 - 1502 7590--> - <polyline - points="1504 7868 1496 7622 1386 7844 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline28" /> - <!-- Line --> - <polyline - points="2240,8550 2676,6512 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline30" /> - <!-- Arrowhead on XXXpoint 2240 8550 - 2702 6390--> - <polyline - points="2704 6668 2696 6422 2586 6644 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline32" /> - <!-- Line --> - <polyline - points="4050,9750 5682,6360 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline34" /> - <!-- Arrowhead on XXXpoint 4050 9750 - 5736 6246--> - <polyline - points="5672 6518 5722 6276 5562 6466 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline36" /> - <!-- Line --> - <polyline - points="1010,9750 2642,6360 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline38" /> - <!-- Arrowhead on XXXpoint 1010 9750 - 2696 6246--> - <polyline - points="2632 6518 2682 6276 2522 6466 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline40" /> - <!-- Line: box --> - <rect - x="0" - y="900" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect42" /> - <!-- Line: box --> - <rect - x="300" - y="1500" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect44" /> - <!-- Line --> - <polyline - points="1350,3900 2350,3040 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline46" /> - <!-- Arrowhead on XXXpoint 1350 3900 - 2444 2960--> - <!-- Line --> - <polyline - points="4950,3900 3948,3040 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline50" /> - <!-- Arrowhead on XXXpoint 4950 3900 - 3854 2960--> - <!-- Line --> - <polyline - points="4050,7050 4050,4864 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline54" /> - <!-- Arrowhead on XXXpoint 4050 7050 - 4050 4740--> - <!-- Line --> - <polyline - points="1050,7050 1050,4864 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline58" /> - <!-- Arrowhead on XXXpoint 1050 7050 - 1050 4740--> - <!-- Line --> - <polyline - points="2250,5850 2250,4864 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline62" /> - <!-- Arrowhead on XXXpoint 2250 5850 - 2250 4740--> - <!-- Line --> - <polyline - points="2250,8550 2250,6814 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline66" /> - <!-- Arrowhead on XXXpoint 2250 8550 - 2250 6690--> - <!-- Line --> - <polyline - points="1050,9750 1050,8014 " - style="stroke:#00ff00;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline70" /> - <!-- Arrowhead on XXXpoint 1050 9750 - 1050 7890--> - <!-- Line --> - <polyline - points="4050,9750 4050,8014 " - style="stroke:#00ff00;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline74" /> - <!-- Arrowhead on XXXpoint 4050 9750 - 4050 7890--> - <!-- Line --> - <polyline - points="5250,8550 5250,6814 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline78" /> - <!-- Arrowhead on XXXpoint 5250 8550 - 5250 6690--> - <!-- Circle --> - <circle - cx="2850" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle82" /> - <!-- Circle --> - <circle - cx="3150" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle84" /> - <!-- Circle --> - <circle - cx="3450" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle86" /> - <!-- Circle --> - <circle - cx="1350" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle88" /> - <!-- Circle --> - <circle - cx="1650" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle90" /> - <!-- Circle --> - <circle - cx="1950" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle92" /> - <!-- Circle --> - <circle - cx="4350" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle94" /> - <!-- Circle --> - <circle - cx="4650" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle96" /> - <!-- Circle --> - <circle - cx="4950" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle98" /> - <!-- Line: box --> - <rect - x="750" - y="3900" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect100" /> - <!-- Line: box --> - <rect - x="300" - y="7050" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect102" /> - <!-- Line: box --> - <rect - x="3750" - y="3900" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect104" /> - <!-- Line: box --> - <rect - x="4500" - y="5850" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect106" /> - <!-- Line: box --> - <rect - x="3300" - y="7050" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect108" /> - <!-- Line: box --> - <rect - x="2250" - y="2100" - width="1800" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " - id="rect110" /> - <!-- Line: box --> - <rect - x="0" - y="9750" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect112" /> - <!-- Line: box --> - <rect - x="1350" - y="8550" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect114" /> - <!-- Line: box --> - <rect - x="3000" - y="9750" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect116" /> - <!-- Line: box --> - <rect - x="4350" - y="8550" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect118" /> - <!-- Line: box --> - <rect - x="1500" - y="5850" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect120" /> - <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text122">rcu_bh</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text124">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="3150" - y="2700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text126">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text128">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1650" - y="4500" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text130">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4500" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text132">rcu_node</text> - <!-- Text --> - <text - xml:space="preserve" - x="4650" - y="4200" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text134">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text136">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2250" - y="6450" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text138">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text140">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="7650" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text142">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text144">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5250" - y="6450" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text146">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text148">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="7650" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text150">rcu_data</text> - <!-- Text --> - <text - xml:space="preserve" - x="450" - y="1800" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="start" - id="text152">struct rcu_state</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="10050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text154">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="10350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text156">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="10050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text158">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="10350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text160">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8850" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text162">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="9150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text164">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8850" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text166">struct</text> - <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="9150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text168">rcu_dynticks</text> - <!-- Text --> - <text - xml:space="preserve" - x="6900" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text170">rcu_preempt</text> - <!-- Text --> - <text - xml:space="preserve" - x="6000" - y="1200" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text172">rcu_sched</text> - <!-- Line --> - <polyline - points="5250,5850 5250,4864 " - style="stroke:#00d1d1;stroke-width:30.00205472;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline174" /> - <!-- Arrowhead on XXXpoint 5250 5850 - 5250 4740--> - </g> -</svg> diff --git a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg index bbc3801470d0..3a1a4f85dc3a 100644 --- a/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg +++ b/Documentation/RCU/Design/Data-Structures/BigTreePreemptRCUBHdyntickCB.svg @@ -13,12 +13,12 @@ xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - width="7.4in" - height="9.9in" - viewBox="-44 -44 8938 11938" + width="7.4000001in" + height="7.9000001in" + viewBox="-44 -44 8938 9526.283" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.2pre0 (973e216, 2017-07-25)" sodipodi:docname="BigTreePreemptRCUBHdyntickCB.svg"> <metadata id="metadata212"> @@ -37,15 +37,46 @@ <marker inkscape:stockid="Arrow1Mend" orient="auto" - refY="0.0" - refX="0.0" + refY="0" + refX="0" + id="marker1177" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path897" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0" + refX="0" + id="Arrow1Lend" + style="overflow:visible" + inkscape:isstock="true"> + <path + id="path891" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> + </marker> + <marker + inkscape:stockid="Arrow1Mend" + orient="auto" + refY="0" + refX="0" id="Arrow1Mend" - style="overflow:visible;"> + style="overflow:visible"> <path id="path3970" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> </marker> </defs> <sodipodi:namedview @@ -57,802 +88,575 @@ guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" - inkscape:window-width="881" - inkscape:window-height="1128" + inkscape:window-width="1920" + inkscape:window-height="1019" id="namedview208" showgrid="false" inkscape:zoom="1.0195195" - inkscape:cx="333" - inkscape:cy="445.49997" - inkscape:window-x="936" - inkscape:window-y="24" - inkscape:window-maximized="0" + inkscape:cx="166.25478" + inkscape:cy="362.18693" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" inkscape:current-layer="g4" /> <g - style="stroke-width:.025in; fill:none" - id="g4"> + style="fill:none;stroke-width:0.025in" + id="g4" + transform="translate(0,-2415.6743)"> <!-- Line: box --> - <rect - x="900" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> <!-- Line: box --> - <rect - x="1200" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect8" /> <!-- Line: box --> - <rect - x="5400" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect10" /> <!-- Line: box --> - <rect - x="450" - y="450" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect12" /> <!-- Line: box --> - <rect - x="750" - y="1050" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect14" /> <!-- Line: box --> - <rect - x="4950" - y="5400" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect16" /> <!-- Line --> - <polyline - points="5250,8550 5688,6362 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline18" /> <!-- Arrowhead on XXXpoint 5250 8550 - 5710 6240--> <polyline points="5714 6518 5704 6272 5598 6494 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline20" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline20" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line --> - <polyline - points="4050,9750 4486,7712 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline22" /> <!-- Arrowhead on XXXpoint 4050 9750 - 4512 7590--> <polyline points="4514 7868 4506 7622 4396 7844 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline24" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline24" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line --> - <polyline - points="1040,9750 1476,7712 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline26" /> <!-- Arrowhead on XXXpoint 1040 9750 - 1502 7590--> <polyline points="1504 7868 1496 7622 1386 7844 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline28" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline28" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line --> - <polyline - points="2240,8550 2676,6512 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline30" /> <!-- Arrowhead on XXXpoint 2240 8550 - 2702 6390--> <polyline points="2704 6668 2696 6422 2586 6644 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline32" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline32" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line --> - <polyline - points="4050,9600 5692,6062 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline34" /> <!-- Arrowhead on XXXpoint 4050 9600 - 5744 5948--> <polyline points="5682 6220 5730 5978 5574 6170 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline36" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline36" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line --> - <polyline - points="1086,9600 2728,6062 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline38" /> <!-- Arrowhead on XXXpoint 1086 9600 - 2780 5948--> <polyline points="2718 6220 2766 5978 2610 6170 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline40" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline40" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Line: box --> <rect - x="0" - y="900" + x="12.340758" + y="2442.5947" width="6300" - height="7350" + height="7045.3135" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + style="fill:#ffffff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect42" /> <!-- Line: box --> <rect - x="300" - y="1500" + x="312.34076" + y="3017.7224" width="5700" - height="3750" + height="3594.5476" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + style="fill:#ffff00;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect44" /> <!-- Line --> <polyline points="1350,3900 2350,3040 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline46" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline46" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 1350 3900 - 2444 2960--> <!-- Line --> <polyline points="4950,3900 3948,3040 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline50" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline50" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 4950 3900 - 3854 2960--> <!-- Line --> <polyline points="4050,7050 4050,4864 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline54" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline54" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 4050 7050 - 4050 4740--> <!-- Line --> <polyline points="1050,7050 1050,4864 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline58" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline58" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 1050 7050 - 1050 4740--> <!-- Line --> <polyline points="2250,5850 2250,4864 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline62" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline62" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 2250 5850 - 2250 4740--> <!-- Line --> - <polyline - points="2250,8550 2250,6814 " - style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline66" /> <!-- Arrowhead on XXXpoint 2250 8550 - 2250 6690--> <!-- Line --> - <polyline - points="1050,9750 1050,8014 " - style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline70" /> <!-- Arrowhead on XXXpoint 1050 9750 - 1050 7890--> <!-- Line --> - <polyline - points="4050,9750 4050,8014 " - style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline74" /> <!-- Arrowhead on XXXpoint 4050 9750 - 4050 7890--> <!-- Line --> - <polyline - points="5250,8550 5250,6814 " - style="stroke:#00ff00;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline78" /> <!-- Arrowhead on XXXpoint 5250 8550 - 5250 6690--> <!-- Line --> - <polyline - points="6000,6300 8048,7910 " - style="stroke:#87cfff;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline82" /> <!-- Arrowhead on XXXpoint 6000 6300 - 8146 7986--> <!-- Circle --> - <circle - cx="2850" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle86" /> + <ellipse + cx="2862.3408" + cy="5749.5786" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle86" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="3150" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle88" /> + <ellipse + cx="3162.3408" + cy="5749.5786" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle88" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="3450" - cy="4350" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle90" /> + <ellipse + cx="3462.3408" + cy="5749.5786" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle90" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="1350" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle92" /> + <ellipse + cx="1362.3407" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle92" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="1650" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle94" /> + <ellipse + cx="1662.3407" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle94" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="1950" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle96" /> + <ellipse + cx="1962.3407" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle96" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="4350" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle98" /> + <ellipse + cx="4362.3408" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle98" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="4650" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle100" /> + <ellipse + cx="4662.3408" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle100" + rx="76" + ry="72.849495" /> <!-- Circle --> - <circle - cx="4950" - cy="5550" - r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" - id="circle102" /> + <ellipse + cx="4962.3408" + cy="6899.834" + style="fill:#000000;stroke:#000000;stroke-width:13.70675087" + id="circle102" + rx="76" + ry="72.849495" /> <!-- Line: box --> <rect - x="7350" - y="7950" + x="6745.3027" + y="8146.0654" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect104" /> <!-- Line: box --> <rect - x="7350" - y="9450" + x="6745.3027" + y="9583.8857" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect106" /> <!-- Line --> <polyline points="8100,8850 8100,9384 " - style="stroke:#000000;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline108" /> + style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend)" + id="polyline108" + transform="matrix(1,0,0,0.95854605,-604.69715,525.62477)" /> <!-- Arrowhead on XXXpoint 8100 8850 - 8100 9510--> <!-- Line: box --> <rect - x="7350" - y="10950" + x="6745.3027" + y="11021.704" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect112" /> <!-- Line --> <polyline points="8100,10350 8100,10884 " - style="stroke:#000000;stroke-width:30;stroke-linejoin:miter;stroke-linecap:butt;marker-end:url(#Arrow1Mend)" - id="polyline114" /> + style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter;marker-end:url(#Arrow1Mend)" + id="polyline114" + transform="matrix(1,0,0,0.95854605,-604.69715,525.62477)" /> <!-- Arrowhead on XXXpoint 8100 10350 - 8100 11010--> <!-- Line: box --> <rect - x="750" - y="3900" + x="762.34076" + y="5318.2324" width="1800" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect118" /> <!-- Line: box --> <rect - x="300" - y="7050" + x="312.34076" + y="8337.6533" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect120" /> <!-- Line: box --> <rect - x="3750" - y="3900" + x="3762.3408" + y="5318.2324" width="1800" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect122" /> <!-- Line: box --> <rect - x="4500" - y="5850" + x="4512.3408" + y="7187.3975" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect124" /> <!-- Line: box --> <rect - x="3300" - y="7050" + x="3312.3408" + y="8337.6533" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect126" /> <!-- Line: box --> <rect - x="2250" - y="2100" + x="2262.3408" + y="3592.8503" width="1800" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect128" /> <!-- Line: box --> - <rect - x="0" - y="9750" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect130" /> <!-- Line: box --> - <rect - x="1350" - y="8550" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect132" /> <!-- Line: box --> - <rect - x="3000" - y="9750" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect134" /> <!-- Line: box --> - <rect - x="4350" - y="8550" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect136" /> <!-- Line: box --> <rect - x="1500" - y="5850" + x="1512.3407" + y="7187.3975" width="1500" - height="900" + height="862.69141" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:29.37160873;stroke-linecap:butt;stroke-linejoin:miter" id="rect138" /> <!-- Text --> <text xml:space="preserve" - x="8100" - y="8250" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="8614.0625" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text140">struct</text> + id="text140" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="8100" - y="8550" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="8907.7783" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text142">rcu_head</text> + id="text142" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_head</text> <!-- Text --> <text xml:space="preserve" - x="8100" - y="9750" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="10082.644" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text144">struct</text> + id="text144" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="8100" - y="10050" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="10376.36" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text146">rcu_head</text> + id="text146" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_head</text> <!-- Text --> <text xml:space="preserve" - x="8100" - y="11250" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="11551.224" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text148">struct</text> + id="text148" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="8100" - y="11550" - fill="#000000" - font-family="Courier" + x="7338.3037" + y="11844.94" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text150">rcu_head</text> + id="text150" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_head</text> <!-- Text --> <text xml:space="preserve" - x="6000" - y="1200" - fill="#000000" - font-family="Helvetica" + x="5886.4043" + y="2788.5688" font-style="normal" font-weight="normal" font-size="192" - text-anchor="end" - id="text152">rcu_sched</text> + id="text152" + style="font-style:normal;font-weight:normal;font-size:187.978302px;font-family:Helvetica;text-anchor:end;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_state</text> <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="750" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text154">rcu_bh</text> <!-- Text --> <text xml:space="preserve" - x="3150" - y="2400" - fill="#000000" - font-family="Courier" + x="3096.1016" + y="3963.4336" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text156">struct</text> + id="text156" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="3150" - y="2700" - fill="#000000" - font-family="Courier" + x="3096.1016" + y="4257.1494" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text158">rcu_node</text> + id="text158" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="1650" - y="4200" - fill="#000000" - font-family="Courier" + x="1627.5209" + y="5725.7305" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text160">struct</text> + id="text160" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="1650" - y="4500" - fill="#000000" - font-family="Courier" + x="1627.5209" + y="6019.4463" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text162">rcu_node</text> + id="text162" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="4650" - y="4500" - fill="#000000" - font-family="Courier" + x="4564.6821" + y="6019.4463" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text164">rcu_node</text> + id="text164" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="4650" - y="4200" - fill="#000000" - font-family="Courier" + x="4564.6821" + y="5725.7305" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text166">struct</text> + id="text166" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="2250" - y="6150" - fill="#000000" - font-family="Courier" + x="2214.9531" + y="7634.8848" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text168">struct</text> + id="text168" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="2250" - y="6450" - fill="#000000" - font-family="Courier" + x="2214.9531" + y="7928.6011" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text170">rcu_data</text> + id="text170" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="1050" - y="7350" - fill="#000000" - font-family="Courier" + x="1040.0886" + y="8809.749" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text172">struct</text> + id="text172" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="1050" - y="7650" - fill="#000000" - font-family="Courier" + x="1040.0886" + y="9103.4648" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text174">rcu_data</text> + id="text174" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="5250" - y="6150" - fill="#000000" - font-family="Courier" + x="5152.1138" + y="7634.8848" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text176">struct</text> + id="text176" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="5250" - y="6450" - fill="#000000" - font-family="Courier" + x="5152.1138" + y="7928.6011" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text178">rcu_data</text> + id="text178" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="4050" - y="7350" - fill="#000000" - font-family="Courier" + x="3977.2495" + y="8809.749" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text180">struct</text> + id="text180" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct</text> <!-- Text --> <text xml:space="preserve" - x="4050" - y="7650" - fill="#000000" - font-family="Courier" + x="3977.2495" + y="9103.4648" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text182">rcu_data</text> + id="text182" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:middle;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="450" - y="1800" - fill="#000000" - font-family="Courier" + x="452.6564" + y="3376.0012" font-style="normal" font-weight="bold" font-size="192" - text-anchor="start" - id="text184">struct rcu_state</text> + id="text184" + style="font-style:normal;font-weight:bold;font-size:187.978302px;font-family:Courier;text-anchor:start;fill:#000000;stroke-width:0.02447634in" + transform="scale(1.0213945,0.97905363)">struct rcu_state</text> <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="10050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text186">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="10350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text188">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="10050" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text190">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="10350" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text192">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8850" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text194">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="9150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text196">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8850" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text198">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="9150" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text200">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="6900" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text202">rcu_preempt</text> <!-- Line --> <polyline points="5250,5850 5250,4864 " - style="stroke:#00d1d1;stroke-width:29.99463964;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline204" /> + style="stroke:#00d1d1;stroke-width:29.99464035;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline204" + transform="matrix(1,0,0,0.95854605,12.340758,1579.9033)" /> <!-- Arrowhead on XXXpoint 5250 5850 - 5250 4740--> + <path + style="fill:none;stroke:#000000;stroke-width:34.24744034;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker1177)" + d="m 6000.1472,7564.2558 c 1498.5508,0 1498.5508,0 1498.5508,0 v 520.0252" + id="path886" + inkscape:connector-curvature="0" /> </g> </svg> diff --git a/Documentation/RCU/Design/Data-Structures/Data-Structures.html b/Documentation/RCU/Design/Data-Structures/Data-Structures.html index 1d2051c0c3fc..18f179807563 100644 --- a/Documentation/RCU/Design/Data-Structures/Data-Structures.html +++ b/Documentation/RCU/Design/Data-Structures/Data-Structures.html @@ -23,8 +23,6 @@ to each other. The <tt>rcu_segcblist</tt> Structure</a> <li> <a href="#The rcu_data Structure"> The <tt>rcu_data</tt> Structure</a> -<li> <a href="#The rcu_dynticks Structure"> - The <tt>rcu_dynticks</tt> Structure</a> <li> <a href="#The rcu_head Structure"> The <tt>rcu_head</tt> Structure</a> <li> <a href="#RCU-Specific Fields in the task_struct Structure"> @@ -127,9 +125,11 @@ CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows: </p><p>RCU currently permits up to a four-level tree, which on a 64-bit system accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for 32-bit systems. -On the other hand, you can set <tt>CONFIG_RCU_FANOUT</tt> to be -as small as 2 if you wish, which would permit only 16 CPUs, which -is useful for testing. +On the other hand, you can set both <tt>CONFIG_RCU_FANOUT</tt> and +<tt>CONFIG_RCU_FANOUT_LEAF</tt> to be as small as 2, which would result +in a 16-CPU test using a 4-level tree. +This can be useful for testing large-system capabilities on small test +machines. </p><p>This multi-level combining tree allows us to get most of the performance and scalability @@ -154,44 +154,9 @@ on that root <tt>rcu_node</tt> structure remains acceptably low. keeping lock contention under control at all tree levels regardless of the level of loading on the system. -</p><p>The Linux kernel actually supports multiple flavors of RCU -running concurrently, so RCU builds separate data structures for each -flavor. -For example, for <tt>CONFIG_TREE_RCU=y</tt> kernels, RCU provides -rcu_sched and rcu_bh, as shown below: - -</p><p><img src="BigTreeClassicRCUBH.svg" alt="BigTreeClassicRCUBH.svg" width="33%"> - -</p><p>Energy efficiency is increasingly important, and for that -reason the Linux kernel provides <tt>CONFIG_NO_HZ_IDLE</tt>, which -turns off the scheduling-clock interrupts on idle CPUs, which in -turn allows those CPUs to attain deeper sleep states and to consume -less energy. -CPUs whose scheduling-clock interrupts have been turned off are -said to be in <i>dyntick-idle mode</i>. -RCU must handle dyntick-idle CPUs specially -because RCU would otherwise wake up each CPU on every grace period, -which would defeat the whole purpose of <tt>CONFIG_NO_HZ_IDLE</tt>. -RCU uses the <tt>rcu_dynticks</tt> structure to track -which CPUs are in dyntick idle mode, as shown below: - -</p><p><img src="BigTreeClassicRCUBHdyntick.svg" alt="BigTreeClassicRCUBHdyntick.svg" width="33%"> - -</p><p>However, if a CPU is in dyntick-idle mode, it is in that mode -for all flavors of RCU. -Therefore, a single <tt>rcu_dynticks</tt> structure is allocated per -CPU, and all of a given CPU's <tt>rcu_data</tt> structures share -that <tt>rcu_dynticks</tt>, as shown in the figure. - -</p><p>Kernels built with <tt>CONFIG_PREEMPT_RCU</tt> support -rcu_preempt in addition to rcu_sched and rcu_bh, as shown below: - -</p><p><img src="BigTreePreemptRCUBHdyntick.svg" alt="BigTreePreemptRCUBHdyntick.svg" width="35%"> - </p><p>RCU updaters wait for normal grace periods by registering RCU callbacks, either directly via <tt>call_rcu()</tt> and friends (namely <tt>call_rcu_bh()</tt> and <tt>call_rcu_sched()</tt>), -there being a separate interface per flavor of RCU) or indirectly via <tt>synchronize_rcu()</tt> and friends. RCU callbacks are represented by <tt>rcu_head</tt> structures, which are queued on <tt>rcu_data</tt> structures while they are @@ -214,9 +179,6 @@ its own synchronization: <li> Each <tt>rcu_node</tt> structure has a spinlock. <li> The fields in <tt>rcu_data</tt> are private to the corresponding CPU, although a few can be read and written by other CPUs. -<li> Similarly, the fields in <tt>rcu_dynticks</tt> are private - to the corresponding CPU, although a few can be read by - other CPUs. </ol> <p>It is important to note that different data structures can have @@ -272,11 +234,6 @@ follows: access to this information from the corresponding CPU. Finally, this structure records past dyntick-idle state for the corresponding CPU and also tracks statistics. -<li> <tt>rcu_dynticks</tt>: - This per-CPU structure tracks the current dyntick-idle - state for the corresponding CPU. - Unlike the other three structures, the <tt>rcu_dynticks</tt> - structure is not replicated per RCU flavor. <li> <tt>rcu_head</tt>: This structure represents RCU callbacks, and is the only structure allocated and managed by RCU users. @@ -287,14 +244,14 @@ follows: <p>If all you wanted from this article was a general notion of how RCU's data structures are related, you are done. Otherwise, each of the following sections give more details on -the <tt>rcu_state</tt>, <tt>rcu_node</tt>, <tt>rcu_data</tt>, -and <tt>rcu_dynticks</tt> data structures. +the <tt>rcu_state</tt>, <tt>rcu_node</tt> and <tt>rcu_data</tt> data +structures. <h3><a name="The rcu_state Structure"> The <tt>rcu_state</tt> Structure</a></h3> <p>The <tt>rcu_state</tt> structure is the base structure that -represents a flavor of RCU. +represents the state of RCU in the system. This structure forms the interconnection between the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures, tracks grace periods, contains the lock used to @@ -389,7 +346,7 @@ sequence number. The bottom two bits are the state of the current grace period, which can be zero for not yet started or one for in progress. In other words, if the bottom two bits of <tt>->gp_seq</tt> are -zero, the corresponding flavor of RCU is idle. +zero, then RCU is idle. Any other value in the bottom two bits indicates that something is broken. This field is protected by the root <tt>rcu_node</tt> structure's <tt>->lock</tt> field. @@ -419,10 +376,10 @@ as follows: grace period in jiffies. It is protected by the root <tt>rcu_node</tt>'s <tt>->lock</tt>. -<p>The <tt>->name</tt> field points to the name of the RCU flavor -(for example, “rcu_sched”), and is constant. -The <tt>->abbr</tt> field contains a one-character abbreviation, -for example, “s” for RCU-sched. +<p>The <tt>->name</tt> and <tt>->abbr</tt> fields distinguish +between preemptible RCU (“rcu_preempt” and “p”) +and non-preemptible RCU (“rcu_sched” and “s”). +These fields are used for diagnostic and tracing purposes. <h3><a name="The rcu_node Structure"> The <tt>rcu_node</tt> Structure</a></h3> @@ -971,25 +928,31 @@ this <tt>rcu_segcblist</tt> structure, <i>not</i> the <tt>->head</tt> pointer. The reason for this is that all the ready-to-invoke callbacks (that is, those in the <tt>RCU_DONE_TAIL</tt> segment) are extracted -all at once at callback-invocation time. +all at once at callback-invocation time (<tt>rcu_do_batch</tt>), due +to which <tt>->head</tt> may be set to NULL if there are no not-done +callbacks remaining in the <tt>rcu_segcblist</tt>. If callback invocation must be postponed, for example, because a high-priority process just woke up on this CPU, then the remaining -callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment. -Either way, the <tt>->len</tt> and <tt>->len_lazy</tt> counts -are adjusted after the corresponding callbacks have been invoked, and so -again it is the <tt>->len</tt> count that accurately reflects whether -or not there are callbacks associated with this <tt>rcu_segcblist</tt> -structure. +callbacks are placed back on the <tt>RCU_DONE_TAIL</tt> segment and +<tt>->head</tt> once again points to the start of the segment. +In short, the head field can briefly be <tt>NULL</tt> even though the +CPU has callbacks present the entire time. +Therefore, it is not appropriate to test the <tt>->head</tt> pointer +for <tt>NULL</tt>. + +<p>In contrast, the <tt>->len</tt> and <tt>->len_lazy</tt> counts +are adjusted only after the corresponding callbacks have been invoked. +This means that the <tt>->len</tt> count is zero only if +the <tt>rcu_segcblist</tt> structure really is devoid of callbacks. Of course, off-CPU sampling of the <tt>->len</tt> count requires -the use of appropriate synchronization, for example, memory barriers. +careful use of appropriate synchronization, for example, memory barriers. This synchronization can be a bit subtle, particularly in the case of <tt>rcu_barrier()</tt>. <h3><a name="The rcu_data Structure"> The <tt>rcu_data</tt> Structure</a></h3> -<p>The <tt>rcu_data</tt> maintains the per-CPU state for the -corresponding flavor of RCU. +<p>The <tt>rcu_data</tt> maintains the per-CPU state for the RCU subsystem. The fields in this structure may be accessed only from the corresponding CPU (and from tracing) unless otherwise stated. This structure is the @@ -1015,30 +978,19 @@ as follows: <pre> 1 int cpu; - 2 struct rcu_state *rsp; - 3 struct rcu_node *mynode; - 4 struct rcu_dynticks *dynticks; - 5 unsigned long grpmask; - 6 bool beenonline; + 2 struct rcu_node *mynode; + 3 unsigned long grpmask; + 4 bool beenonline; </pre> <p>The <tt>->cpu</tt> field contains the number of the -corresponding CPU, the <tt>->rsp</tt> pointer references -the corresponding <tt>rcu_state</tt> structure (and is most frequently -used to locate the name of the corresponding flavor of RCU for tracing), -and the <tt>->mynode</tt> field references the corresponding -<tt>rcu_node</tt> structure. +corresponding CPU and the <tt>->mynode</tt> field references the +corresponding <tt>rcu_node</tt> structure. The <tt>->mynode</tt> is used to propagate quiescent states up the combining tree. -<p>The <tt>->dynticks</tt> pointer references the -<tt>rcu_dynticks</tt> structure corresponding to this -CPU. -Recall that a single per-CPU instance of the <tt>rcu_dynticks</tt> -structure is shared among all flavors of RCU. -These first four fields are constant and therefore require not -synchronization. +These two fields are constant and therefore do not require synchronization. -</p><p>The <tt>->grpmask</tt> field indicates the bit in +<p>The <tt>->grpmask</tt> field indicates the bit in the <tt>->mynode->qsmask</tt> corresponding to this <tt>rcu_data</tt> structure, and is also used when propagating quiescent states. @@ -1057,12 +1009,12 @@ as follows: 3 bool cpu_no_qs; 4 bool core_needs_qs; 5 bool gpwrap; - 6 unsigned long rcu_qs_ctr_snap; </pre> -<p>The <tt>->gp_seq</tt> and <tt>->gp_seq_needed</tt> -fields are the counterparts of the fields of the same name -in the <tt>rcu_state</tt> and <tt>rcu_node</tt> structures. +<p>The <tt>->gp_seq</tt> field is the counterpart of the field of the same +name in the <tt>rcu_state</tt> and <tt>rcu_node</tt> structures. The +<tt>->gp_seq_needed</tt> field is the counterpart of the field of the same +name in the rcu_node</tt> structure. They may each lag up to one behind their <tt>rcu_node</tt> counterparts, but in <tt>CONFIG_NO_HZ_IDLE</tt> and <tt>CONFIG_NO_HZ_FULL</tt> kernels can lag @@ -1103,10 +1055,6 @@ CPU has remained idle for so long that the <tt>gp_seq</tt> counter is in danger of overflow, which will cause the CPU to disregard the values of its counters on its next exit from idle. -Finally, the <tt>rcu_qs_ctr_snap</tt> field is used to detect -cases where a given operation has resulted in a quiescent state -for all flavors of RCU, for example, <tt>cond_resched()</tt> -when RCU has indicated a need for quiescent states. <h5>RCU Callback Handling</h5> @@ -1179,26 +1127,22 @@ Finally, the <tt>->dynticks_fqs</tt> field is used to count the number of times this CPU is determined to be in dyntick-idle state, and is used for tracing and debugging purposes. -<h3><a name="The rcu_dynticks Structure"> -The <tt>rcu_dynticks</tt> Structure</a></h3> - -<p>The <tt>rcu_dynticks</tt> maintains the per-CPU dyntick-idle state -for the corresponding CPU. -Unlike the other structures, <tt>rcu_dynticks</tt> is not -replicated over the different flavors of RCU. -The fields in this structure may be accessed only from the corresponding -CPU (and from tracing) unless otherwise stated. -Its fields are as follows: +<p> +This portion of the rcu_data structure is declared as follows: <pre> 1 long dynticks_nesting; 2 long dynticks_nmi_nesting; 3 atomic_t dynticks; 4 bool rcu_need_heavy_qs; - 5 unsigned long rcu_qs_ctr; - 6 bool rcu_urgent_qs; + 5 bool rcu_urgent_qs; </pre> +<p>These fields in the rcu_data structure maintain the per-CPU dyntick-idle +state for the corresponding CPU. +The fields may be accessed only from the corresponding CPU (and from tracing) +unless otherwise stated. + <p>The <tt>->dynticks_nesting</tt> field counts the nesting depth of process execution, so that in normal circumstances this counter has value zero or one. @@ -1240,19 +1184,12 @@ it is willing to call for heavy-weight dyntick-counter operations. This flag is checked by RCU's context-switch and <tt>cond_resched()</tt> code, which provide a momentary idle sojourn in response. -</p><p>The <tt>->rcu_qs_ctr</tt> field is used to record -quiescent states from <tt>cond_resched()</tt>. -Because <tt>cond_resched()</tt> can execute quite frequently, this -must be quite lightweight, as in a non-atomic increment of this -per-CPU field. - </p><p>Finally, the <tt>->rcu_urgent_qs</tt> field is used to record -the fact that the RCU core code would really like to see a quiescent -state from the corresponding CPU, with the various other fields indicating -just how badly RCU wants this quiescent state. -This flag is checked by RCU's context-switch and <tt>cond_resched()</tt> -code, which, if nothing else, non-atomically increment <tt>->rcu_qs_ctr</tt> -in response. +the fact that the RCU core code would really like to see a quiescent state from +the corresponding CPU, with the various other fields indicating just how badly +RCU wants this quiescent state. +This flag is checked by RCU's context-switch path +(<tt>rcu_note_context_switch</tt>) and the cond_resched code. <table> <tr><th> </th></tr> @@ -1425,11 +1362,11 @@ the last part of the array, thus traversing only the leaf <h3><a name="Summary"> Summary</a></h3> -So each flavor of RCU is represented by an <tt>rcu_state</tt> structure, +So the state of RCU is represented by an <tt>rcu_state</tt> structure, which contains a combining tree of <tt>rcu_node</tt> and <tt>rcu_data</tt> structures. Finally, in <tt>CONFIG_NO_HZ_IDLE</tt> kernels, each CPU's dyntick-idle -state is tracked by an <tt>rcu_dynticks</tt> structure. +state is tracked by dynticks-related fields in the <tt>rcu_data</tt> structure. If you made it this far, you are well prepared to read the code walkthroughs in the other articles in this series. diff --git a/Documentation/RCU/Design/Data-Structures/blkd_task.svg b/Documentation/RCU/Design/Data-Structures/blkd_task.svg index 00e810bb8419..bed13e9ecab8 100644 --- a/Documentation/RCU/Design/Data-Structures/blkd_task.svg +++ b/Documentation/RCU/Design/Data-Structures/blkd_task.svg @@ -14,12 +14,12 @@ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="10.1in" - height="8.6in" - viewBox="-44 -44 12088 10288" + height="6.5999999in" + viewBox="-44 -44 12088 7895.4414" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" - sodipodi:docname="blkd_task.fig"> + inkscape:version="0.92.2pre0 (973e216, 2017-07-25)" + sodipodi:docname="blkd_task.svg"> <metadata id="metadata212"> <rdf:RDF> @@ -37,15 +37,16 @@ <marker inkscape:stockid="Arrow1Mend" orient="auto" - refY="0.0" - refX="0.0" + refY="0" + refX="0" id="Arrow1Mend" - style="overflow:visible;"> + style="overflow:visible"> <path id="path3970" - d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " - style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;" - transform="scale(0.4) rotate(180) translate(10,0)" /> + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt" + transform="matrix(-0.4,0,0,-0.4,-4,0)" + inkscape:connector-curvature="0" /> </marker> </defs> <sodipodi:namedview @@ -57,787 +58,574 @@ guidetolerance="10" inkscape:pageopacity="0" inkscape:pageshadow="2" - inkscape:window-width="1087" - inkscape:window-height="1144" + inkscape:window-width="1920" + inkscape:window-height="1019" id="namedview208" showgrid="false" inkscape:zoom="1.0495049" - inkscape:cx="454.50003" - inkscape:cy="387.00003" - inkscape:window-x="833" - inkscape:window-y="28" - inkscape:window-maximized="0" - inkscape:current-layer="g4" /> + inkscape:cx="456.40569" + inkscape:cy="348.88682" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:window-maximized="1" + inkscape:current-layer="g4" + showguides="false" /> <g - style="stroke-width:.025in; fill:none" - id="g4"> + style="fill:none;stroke-width:0.025in" + id="g4" + transform="translate(0,-2393.6637)"> <!-- Line: box --> - <rect - x="450" - y="0" - width="6300" - height="7350" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " - id="rect6" /> <!-- Line: box --> - <rect - x="4950" - y="4950" - width="1500" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " - id="rect8" /> <!-- Line: box --> - <rect - x="750" - y="600" - width="5700" - height="3750" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " - id="rect10" /> <!-- Line --> - <polyline - points="5250,8100 5688,5912 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline12" /> <!-- Arrowhead on XXXpoint 5250 8100 - 5710 5790--> <polyline points="5714 6068 5704 5822 5598 6044 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline14" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline14" + transform="translate(23.757862,2185.7233)" /> <!-- Line --> - <polyline - points="4050,9300 4486,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline16" /> <!-- Arrowhead on XXXpoint 4050 9300 - 4512 7140--> <polyline points="4514 7418 4506 7172 4396 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline18" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline18" + transform="translate(23.757862,2185.7233)" /> <!-- Line --> - <polyline - points="1040,9300 1476,7262 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline20" /> <!-- Arrowhead on XXXpoint 1040 9300 - 1502 7140--> <polyline points="1504 7418 1496 7172 1386 7394 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline22" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline22" + transform="translate(23.757862,2185.7233)" /> <!-- Line --> - <polyline - points="2240,8100 2676,6062 " - style="stroke:#00ff00;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " - id="polyline24" /> <!-- Arrowhead on XXXpoint 2240 8100 - 2702 5940--> <polyline points="2704 6218 2696 5972 2586 6194 " - style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8; " - id="polyline26" /> + style="stroke:#00ff00;stroke-width:14;stroke-miterlimit:8" + id="polyline26" + transform="translate(23.757862,2185.7233)" /> <!-- Line: box --> <rect - x="0" - y="450" + x="23.757858" + y="2635.7231" width="6300" height="7350" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffffff; " + style="fill:#ffffff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect28" /> <!-- Line: box --> <rect - x="300" - y="1050" + x="323.75787" + y="3235.7231" width="5700" height="3750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffff00; " + style="fill:#ffff00;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect30" /> <!-- Line --> <polyline points="1350,3450 2350,2590 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline32" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline32" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 1350 3450 - 2444 2510--> <!-- Line --> <polyline points="4950,3450 3948,2590 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline36" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline36" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 4950 3450 - 3854 2510--> <!-- Line --> <polyline points="4050,6600 4050,4414 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline40" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline40" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 4050 6600 - 4050 4290--> <!-- Line --> <polyline points="1050,6600 1050,4414 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline44" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline44" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 1050 6600 - 1050 4290--> <!-- Line --> <polyline points="2250,5400 2250,4414 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline48" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline48" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 2250 5400 - 2250 4290--> <!-- Line --> - <polyline - points="2250,8100 2250,6364 " - style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline52" /> <!-- Arrowhead on XXXpoint 2250 8100 - 2250 6240--> <!-- Line --> - <polyline - points="1050,9300 1050,7564 " - style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline56" /> <!-- Arrowhead on XXXpoint 1050 9300 - 1050 7440--> <!-- Line --> - <polyline - points="4050,9300 4050,7564 " - style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline60" /> <!-- Arrowhead on XXXpoint 4050 9300 - 4050 7440--> <!-- Line --> - <polyline - points="5250,8100 5250,6364 " - style="stroke:#00ff00;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline64" /> <!-- Arrowhead on XXXpoint 5250 8100 - 5250 6240--> <!-- Circle --> <circle - cx="2850" - cy="3900" + cx="2873.7581" + cy="6085.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle68" /> <!-- Circle --> <circle - cx="3150" - cy="3900" + cx="3173.7581" + cy="6085.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle70" /> <!-- Circle --> <circle - cx="3450" - cy="3900" + cx="3473.7581" + cy="6085.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle72" /> <!-- Circle --> <circle - cx="1350" - cy="5100" + cx="1373.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle74" /> <!-- Circle --> <circle - cx="1650" - cy="5100" + cx="1673.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle76" /> <!-- Circle --> <circle - cx="1950" - cy="5100" + cx="1973.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle78" /> <!-- Circle --> <circle - cx="4350" - cy="5100" + cx="4373.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle80" /> <!-- Circle --> <circle - cx="4650" - cy="5100" + cx="4673.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle82" /> <!-- Circle --> <circle - cx="4950" - cy="5100" + cx="4973.7578" + cy="7285.7236" r="76" - style="fill:#000000;stroke:#000000;stroke-width:14;" + style="fill:#000000;stroke:#000000;stroke-width:14" id="circle84" /> <!-- Line: box --> <rect - x="750" - y="3450" + x="773.75781" + y="5635.7236" width="1800" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect86" /> <!-- Line: box --> <rect - x="300" - y="6600" + x="323.75787" + y="8785.7227" width="1500" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect88" /> <!-- Line: box --> <rect - x="4500" - y="5400" + x="4523.7578" + y="7585.7236" width="1500" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect90" /> <!-- Line: box --> <rect - x="3300" - y="6600" + x="3323.7581" + y="8785.7227" width="1500" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect92" /> <!-- Line: box --> <rect - x="2250" - y="1650" + x="2273.7581" + y="3835.7231" width="1800" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect94" /> <!-- Line: box --> - <rect - x="0" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect96" /> <!-- Line: box --> - <rect - x="1350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect98" /> <!-- Line: box --> - <rect - x="3000" - y="9300" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect100" /> <!-- Line: box --> - <rect - x="4350" - y="8100" - width="2100" - height="900" - rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#00ff00; " - id="rect102" /> <!-- Line: box --> <rect - x="1500" - y="5400" + x="1523.7578" + y="7585.7236" width="1500" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#87cfff; " + style="fill:#87cfff;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect104" /> <!-- Line --> <polygon - points="5550,3450 7350,2850 7350,5100 5550,4350 5550,3450 " - style="stroke:#000000;stroke-width:14; stroke-linejoin:miter; stroke-linecap:butt; stroke-dasharray:120 120;fill:#ffbfbf; " - id="polygon106" /> + points="7350,2850 7350,5100 5550,4350 5550,3450 " + style="fill:#ffbfbf;stroke:#000000;stroke-width:14;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:120, 120" + id="polygon106" + transform="translate(23.757862,2185.7233)" /> <!-- Line --> <polyline points="9300,3150 10734,3150 " - style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline108" /> + style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline108" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 9300 3150 - 10860 3150--> <!-- Line: box --> <rect - x="10800" - y="2850" + x="10823.758" + y="5035.7236" width="1200" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect112" /> <!-- Line --> <polyline points="11400,3600 11400,4284 " - style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline114" /> + style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline114" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 11400 3600 - 11400 4410--> <!-- Line: box --> <rect - x="10800" - y="4350" + x="10823.758" + y="6535.7236" width="1200" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect118" /> <!-- Line --> <polyline points="11400,5100 11400,5784 " - style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline120" /> + style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline120" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 11400 5100 - 11400 5910--> <!-- Line: box --> <rect - x="10800" - y="5850" + x="10823.758" + y="8035.7236" width="1200" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; " + style="stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect124" /> <!-- Line --> <polyline points="9300,3900 9900,3900 9900,4650 10734,4650 " - style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline126" /> + style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline126" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 9900 4650 - 10860 4650--> <!-- Line --> <polyline points="9300,4650 9600,4650 9600,6150 10734,6150 " - style="stroke:#000000;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline130" /> + style="stroke:#000000;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline130" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 9600 6150 - 10860 6150--> <!-- Text --> - <text - xml:space="preserve" - x="6450" - y="300" - fill="#000000" - font-family="Helvetica" - font-style="normal" - font-weight="normal" - font-size="192" - text-anchor="end" - id="text134">rcu_bh</text> <!-- Text --> <text xml:space="preserve" - x="3150" - y="1950" - fill="#000000" - font-family="Courier" + x="3173.7581" + y="4135.7231" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text136">struct</text> + id="text136" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="3150" - y="2250" - fill="#000000" - font-family="Courier" + x="3173.7581" + y="4435.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text138">rcu_node</text> + id="text138" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="1650" - y="3750" - fill="#000000" - font-family="Courier" + x="1673.7578" + y="5935.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text140">struct</text> + id="text140" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="1650" - y="4050" - fill="#000000" - font-family="Courier" + x="1673.7578" + y="6235.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text142">rcu_node</text> + id="text142" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="2250" - y="5700" - fill="#000000" - font-family="Courier" + x="2273.7581" + y="7885.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text144">struct</text> + id="text144" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="2250" - y="6000" - fill="#000000" - font-family="Courier" + x="2273.7581" + y="8185.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text146">rcu_data</text> + id="text146" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="1050" - y="6900" - fill="#000000" - font-family="Courier" + x="1073.7578" + y="9085.7227" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text148">struct</text> + id="text148" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="1050" - y="7200" - fill="#000000" - font-family="Courier" + x="1073.7578" + y="9385.7227" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text150">rcu_data</text> + id="text150" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="5250" - y="5700" - fill="#000000" - font-family="Courier" + x="5273.7578" + y="7885.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text152">struct</text> + id="text152" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="5250" - y="6000" - fill="#000000" - font-family="Courier" + x="5273.7578" + y="8185.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text154">rcu_data</text> + id="text154" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="4050" - y="6900" - fill="#000000" - font-family="Courier" + x="4073.7578" + y="9085.7227" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text156">struct</text> + id="text156" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="4050" - y="7200" - fill="#000000" - font-family="Courier" + x="4073.7578" + y="9385.7227" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text158">rcu_data</text> + id="text158" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_data</text> <!-- Text --> <text xml:space="preserve" - x="450" - y="1350" - fill="#000000" - font-family="Courier" + x="473.75784" + y="3535.7231" font-style="normal" font-weight="bold" font-size="192" - text-anchor="start" - id="text160">struct rcu_state</text> + id="text160" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">struct rcu_state</text> <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text162">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="1050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text164">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9600" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text166">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="4050" - y="9900" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text168">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text170">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="2400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text172">rcu_dynticks</text> <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8400" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text174">struct</text> <!-- Text --> - <text - xml:space="preserve" - x="5400" - y="8700" - fill="#000000" - font-family="Courier" - font-style="normal" - font-weight="bold" - font-size="192" - text-anchor="middle" - id="text176">rcu_dynticks</text> <!-- Text --> <text xml:space="preserve" - x="6000" - y="750" - fill="#000000" - font-family="Helvetica" + x="6023.7578" + y="2935.7231" font-style="normal" font-weight="normal" font-size="192" - text-anchor="end" - id="text178">rcu_sched</text> + id="text178" + style="font-style:normal;font-weight:normal;font-size:192px;font-family:Helvetica;text-anchor:end;fill:#000000">rcu_state</text> <!-- Text --> <text xml:space="preserve" - x="11400" - y="3300" - fill="#000000" - font-family="Helvetica" + x="11423.758" + y="5485.7236" font-style="normal" font-weight="normal" font-size="216" - text-anchor="middle" - id="text180">T3</text> + id="text180" + style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T3</text> <!-- Text --> <text xml:space="preserve" - x="11400" - y="4800" - fill="#000000" - font-family="Helvetica" + x="11423.758" + y="6985.7236" font-style="normal" font-weight="normal" font-size="216" - text-anchor="middle" - id="text182">T2</text> + id="text182" + style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T2</text> <!-- Text --> <text xml:space="preserve" - x="11400" - y="6300" - fill="#000000" - font-family="Helvetica" + x="11423.758" + y="8485.7227" font-style="normal" font-weight="normal" font-size="216" - text-anchor="middle" - id="text184">T1</text> + id="text184" + style="font-style:normal;font-weight:normal;font-size:216px;font-family:Helvetica;text-anchor:middle;fill:#000000">T1</text> <!-- Line --> <polyline points="5250,5400 5250,4414 " - style="stroke:#00d1d1;stroke-width:30.00057884;stroke-linejoin:miter;stroke-linecap:butt;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" - id="polyline186" /> + style="stroke:#00d1d1;stroke-width:30.00057793;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Mend)" + id="polyline186" + transform="translate(23.757862,2185.7233)" /> <!-- Arrowhead on XXXpoint 5250 5400 - 5250 4290--> <!-- Line: box --> <rect - x="3750" - y="3450" + x="3773.7581" + y="5635.7236" width="1800" height="900" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect190" /> <!-- Line: box --> <rect - x="7350" - y="2850" + x="7373.7578" + y="5035.7236" width="1950" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect192" /> <!-- Line: box --> <rect - x="7350" - y="3600" + x="7373.7578" + y="5785.7236" width="1950" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect194" /> <!-- Line: box --> <rect - x="7350" - y="4350" + x="7373.7578" + y="6535.7236" width="1950" height="750" rx="0" - style="stroke:#000000;stroke-width:30; stroke-linejoin:miter; stroke-linecap:butt; fill:#ffbfbf; " + style="fill:#ffbfbf;stroke:#000000;stroke-width:30;stroke-linecap:butt;stroke-linejoin:miter" id="rect196" /> <!-- Text --> <text xml:space="preserve" - x="4650" - y="4050" - fill="#000000" - font-family="Courier" + x="4673.7578" + y="6235.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text198">rcu_node</text> + id="text198" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">rcu_node</text> <!-- Text --> <text xml:space="preserve" - x="4650" - y="3750" - fill="#000000" - font-family="Courier" + x="4673.7578" + y="5935.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="middle" - id="text200">struct</text> + id="text200" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:middle;fill:#000000">struct</text> <!-- Text --> <text xml:space="preserve" - x="7500" - y="3300" - fill="#000000" - font-family="Courier" + x="7523.7578" + y="5485.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="start" - id="text202">blkd_tasks</text> + id="text202" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">blkd_tasks</text> <!-- Text --> <text xml:space="preserve" - x="7500" - y="4050" - fill="#000000" - font-family="Courier" + x="7523.7578" + y="6235.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="start" - id="text204">gp_tasks</text> + id="text204" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">gp_tasks</text> <!-- Text --> <text xml:space="preserve" - x="7500" - y="4800" - fill="#000000" - font-family="Courier" + x="7523.7578" + y="6985.7236" font-style="normal" font-weight="bold" font-size="192" - text-anchor="start" - id="text206">exp_tasks</text> + id="text206" + style="font-style:normal;font-weight:bold;font-size:192px;font-family:Courier;text-anchor:start;fill:#000000">exp_tasks</text> </g> </svg> diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg index e4233ac93c2b..6189ffcc6aff 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/ExpSchedFlow.svg @@ -328,13 +328,13 @@ inkscape:window-height="1148" id="namedview90" showgrid="true" - inkscape:zoom="0.80021373" - inkscape:cx="462.49289" - inkscape:cy="473.6718" + inkscape:zoom="0.69092787" + inkscape:cx="476.34085" + inkscape:cy="712.80957" inkscape:window-x="770" inkscape:window-y="24" inkscape:window-maximized="0" - inkscape:current-layer="g4114-9-3-9" + inkscape:current-layer="g4" inkscape:snap-grids="false" fit-margin-top="5" fit-margin-right="5" @@ -813,14 +813,18 @@ <text sodipodi:linespacing="125%" id="text4110-5-7-6-2-4-0" - y="841.88086" + y="670.74316" x="1460.1007" style="font-size:267.24359131px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan - y="841.88086" + y="670.74316" + x="1460.1007" + sodipodi:role="line" + id="tspan4925-1-2-4-5">Request</tspan><tspan + y="1004.7976" x="1460.1007" sodipodi:role="line" - id="tspan4925-1-2-4-5">reched_cpu()</tspan></text> + id="tspan3100">context switch</tspan></text> </g> </g> </svg> diff --git a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html index e62c7c34a369..19e7a5fb6b73 100644 --- a/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html +++ b/Documentation/RCU/Design/Expedited-Grace-Periods/Expedited-Grace-Periods.html @@ -72,10 +72,10 @@ will ignore it because idle and offline CPUs are already residing in quiescent states. Otherwise, the expedited grace period will use <tt>smp_call_function_single()</tt> to send the CPU an IPI, which -is handled by <tt>sync_rcu_exp_handler()</tt>. +is handled by <tt>rcu_exp_handler()</tt>. <p> -However, because this is preemptible RCU, <tt>sync_rcu_exp_handler()</tt> +However, because this is preemptible RCU, <tt>rcu_exp_handler()</tt> can check to see if the CPU is currently running in an RCU read-side critical section. If not, the handler can immediately report a quiescent state. @@ -145,24 +145,23 @@ expedited grace period is shown in the following diagram: <p><img src="ExpSchedFlow.svg" alt="ExpSchedFlow.svg" width="55%"> <p> -As with RCU-preempt's <tt>synchronize_rcu_expedited()</tt>, +As with RCU-preempt, RCU-sched's <tt>synchronize_sched_expedited()</tt> ignores offline and idle CPUs, again because they are in remotely detectable quiescent states. -However, the <tt>synchronize_rcu_expedited()</tt> handler -is <tt>sync_sched_exp_handler()</tt>, and because the +However, because the <tt>rcu_read_lock_sched()</tt> and <tt>rcu_read_unlock_sched()</tt> leave no trace of their invocation, in general it is not possible to tell whether or not the current CPU is in an RCU read-side critical section. -The best that <tt>sync_sched_exp_handler()</tt> can do is to check +The best that RCU-sched's <tt>rcu_exp_handler()</tt> can do is to check for idle, on the off-chance that the CPU went idle while the IPI was in flight. -If the CPU is idle, then <tt>sync_sched_exp_handler()</tt> reports +If the CPU is idle, then <tt>rcu_exp_handler()</tt> reports the quiescent state. -<p> -Otherwise, the handler invokes <tt>resched_cpu()</tt>, which forces -a future context switch. +<p> Otherwise, the handler forces a future context switch by setting the +NEED_RESCHED flag of the current task's thread flag and the CPU preempt +counter. At the time of the context switch, the CPU reports the quiescent state. Should the CPU go offline first, it will report the quiescent state at that time. @@ -298,19 +297,18 @@ Instead, the task pushing the grace period forward will include the idle CPUs in the mask passed to <tt>rcu_report_exp_cpu_mult()</tt>. <p> -For RCU-sched, there is an additional check for idle in the IPI -handler, <tt>sync_sched_exp_handler()</tt>. +For RCU-sched, there is an additional check: If the IPI has interrupted the idle loop, then -<tt>sync_sched_exp_handler()</tt> invokes <tt>rcu_report_exp_rdp()</tt> +<tt>rcu_exp_handler()</tt> invokes <tt>rcu_report_exp_rdp()</tt> to report the corresponding quiescent state. <p> For RCU-preempt, there is no specific check for idle in the -IPI handler (<tt>sync_rcu_exp_handler()</tt>), but because +IPI handler (<tt>rcu_exp_handler()</tt>), but because RCU read-side critical sections are not permitted within the -idle loop, if <tt>sync_rcu_exp_handler()</tt> sees that the CPU is within +idle loop, if <tt>rcu_exp_handler()</tt> sees that the CPU is within RCU read-side critical section, the CPU cannot possibly be idle. -Otherwise, <tt>sync_rcu_exp_handler()</tt> invokes +Otherwise, <tt>rcu_exp_handler()</tt> invokes <tt>rcu_report_exp_rdp()</tt> to report the corresponding quiescent state, regardless of whether or not that quiescent state was due to the CPU being idle. @@ -625,6 +623,8 @@ checks, but only during the mid-boot dead zone. <p> With this refinement, synchronous grace periods can now be used from task context pretty much any time during the life of the kernel. +That is, aside from some points in the suspend, hibernate, or shutdown +code path. <h3><a name="Summary"> Summary</a></h3> diff --git a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html index a346ce0116eb..8d21af02b1f0 100644 --- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html +++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.html @@ -77,7 +77,7 @@ The key point is that the lock-acquisition functions, including <tt>smp_mb__after_unlock_lock()</tt> immediately after successful acquisition of the lock. -<p>Therefore, for any given <tt>rcu_node</tt> struction, any access +<p>Therefore, for any given <tt>rcu_node</tt> structure, any access happening before one of the above lock-release functions will be seen by all CPUs as happening before any access happening after a later one of the above lock-acquisition functions. @@ -485,13 +485,13 @@ section that the grace period must wait on. noted by <tt>rcu_node_context_switch()</tt> on the left. On the other hand, if the CPU takes a scheduler-clock interrupt while executing in usermode, a quiescent state will be noted by -<tt>rcu_check_callbacks()</tt> on the right. +<tt>rcu_sched_clock_irq()</tt> on the right. Either way, the passage through a quiescent state will be noted in a per-CPU variable. <p>The next time an <tt>RCU_SOFTIRQ</tt> handler executes on this CPU (for example, after the next scheduler-clock -interrupt), <tt>__rcu_process_callbacks()</tt> will invoke +interrupt), <tt>rcu_core()</tt> will invoke <tt>rcu_check_quiescent_state()</tt>, which will notice the recorded quiescent state, and invoke <tt>rcu_report_qs_rdp()</tt>. @@ -651,7 +651,7 @@ to end. These callbacks are identified by <tt>rcu_advance_cbs()</tt>, which is usually invoked by <tt>__note_gp_changes()</tt>. As shown in the diagram below, this invocation can be triggered by -the scheduling-clock interrupt (<tt>rcu_check_callbacks()</tt> on +the scheduling-clock interrupt (<tt>rcu_sched_clock_irq()</tt> on the left) or by idle entry (<tt>rcu_cleanup_after_idle()</tt> on the right, but only for kernels build with <tt>CONFIG_RCU_FAST_NO_HZ=y</tt>). diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg index 832408313d93..3fcf0c17cef2 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-callback-invocation.svg @@ -349,7 +349,7 @@ font-weight="bold" font-size="192" id="text202-7-5" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_check_callbacks()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_sched_clock_irq()</text> <rect x="7069.6187" y="5087.4678" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg index acd73c7ad0f4..2bcd742d6e49 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-gp.svg @@ -3902,7 +3902,7 @@ font-style="normal" y="-4418.6582" x="3745.7725" - xml:space="preserve">rcu_check_callbacks()</text> + xml:space="preserve">rcu_sched_clock_irq()</text> </g> <g transform="translate(-850.30204,55463.106)" @@ -3924,7 +3924,7 @@ font-style="normal" y="-4418.6582" x="3745.7725" - xml:space="preserve">rcu_process_callbacks()</text> + xml:space="preserve">rcu_core()</text> <text style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier" id="text202-7-5-3-27-0" @@ -3933,7 +3933,7 @@ font-style="normal" y="-4165.7954" x="3745.7725" - xml:space="preserve">rcu_check_quiescent_state())</text> + xml:space="preserve">rcu_check_quiescent_state()</text> <text style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier" id="text202-7-5-3-27-0-9" @@ -4968,7 +4968,7 @@ font-weight="bold" font-size="192" id="text202-7-5-19" - style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_check_callbacks()</text> + style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier">rcu_sched_clock_irq()</text> <rect x="5314.2671" y="82817.688" diff --git a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg index 149bec2a4493..779c9ac31a52 100644 --- a/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg +++ b/Documentation/RCU/Design/Memory-Ordering/TreeRCU-qs.svg @@ -775,7 +775,7 @@ font-style="normal" y="-4418.6582" x="3745.7725" - xml:space="preserve">rcu_check_callbacks()</text> + xml:space="preserve">rcu_sched_clock_irq()</text> </g> <g transform="translate(399.7744,828.86448)" @@ -797,7 +797,7 @@ font-style="normal" y="-4418.6582" x="3745.7725" - xml:space="preserve">rcu_process_callbacks()</text> + xml:space="preserve">rcu_core()</text> <text style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier" id="text202-7-5-3-27-0" @@ -806,7 +806,7 @@ font-style="normal" y="-4165.7954" x="3745.7725" - xml:space="preserve">rcu_check_quiescent_state())</text> + xml:space="preserve">rcu_check_quiescent_state()</text> <text style="font-size:192px;font-style:normal;font-weight:bold;text-anchor:start;fill:#000000;stroke-width:0.025in;font-family:Courier" id="text202-7-5-3-27-0-9" diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html index 43c4e2f05f40..5a9238a2883c 100644 --- a/Documentation/RCU/Design/Requirements/Requirements.html +++ b/Documentation/RCU/Design/Requirements/Requirements.html @@ -900,8 +900,6 @@ Except where otherwise noted, these non-guarantees were premeditated. Grace Periods Don't Partition Read-Side Critical Sections</a> <li> <a href="#Read-Side Critical Sections Don't Partition Grace Periods"> Read-Side Critical Sections Don't Partition Grace Periods</a> -<li> <a href="#Disabling Preemption Does Not Block Grace Periods"> - Disabling Preemption Does Not Block Grace Periods</a> </ol> <h3><a name="Readers Impose Minimal Ordering">Readers Impose Minimal Ordering</a></h3> @@ -1259,54 +1257,6 @@ of RCU grace periods. <tr><td> </td></tr> </table> -<h3><a name="Disabling Preemption Does Not Block Grace Periods"> -Disabling Preemption Does Not Block Grace Periods</a></h3> - -<p> -There was a time when disabling preemption on any given CPU would block -subsequent grace periods. -However, this was an accident of implementation and is not a requirement. -And in the current Linux-kernel implementation, disabling preemption -on a given CPU in fact does not block grace periods, as Oleg Nesterov -<a href="https://lkml.kernel.org/g/20150614193825.GA19582@redhat.com">demonstrated</a>. - -<p> -If you need a preempt-disable region to block grace periods, you need to add -<tt>rcu_read_lock()</tt> and <tt>rcu_read_unlock()</tt>, for example -as follows: - -<blockquote> -<pre> - 1 preempt_disable(); - 2 rcu_read_lock(); - 3 do_something(); - 4 rcu_read_unlock(); - 5 preempt_enable(); - 6 - 7 /* Spinlocks implicitly disable preemption. */ - 8 spin_lock(&mylock); - 9 rcu_read_lock(); -10 do_something(); -11 rcu_read_unlock(); -12 spin_unlock(&mylock); -</pre> -</blockquote> - -<p> -In theory, you could enter the RCU read-side critical section first, -but it is more efficient to keep the entire RCU read-side critical -section contained in the preempt-disable region as shown above. -Of course, RCU read-side critical sections that extend outside of -preempt-disable regions will work correctly, but such critical sections -can be preempted, which forces <tt>rcu_read_unlock()</tt> to do -more work. -And no, this is <i>not</i> an invitation to enclose all of your RCU -read-side critical sections within preempt-disable regions, because -doing so would degrade real-time response. - -<p> -This non-requirement appeared with preemptible RCU. - <h2><a name="Parallelism Facts of Life">Parallelism Facts of Life</a></h2> <p> @@ -1381,6 +1331,7 @@ Classes of quality-of-implementation requirements are as follows: <ol> <li> <a href="#Specialization">Specialization</a> <li> <a href="#Performance and Scalability">Performance and Scalability</a> +<li> <a href="#Forward Progress">Forward Progress</a> <li> <a href="#Composability">Composability</a> <li> <a href="#Corner Cases">Corner Cases</a> </ol> @@ -1645,7 +1596,7 @@ used in place of <tt>synchronize_rcu()</tt> as follows: 16 struct foo *p; 17 18 spin_lock(&gp_lock); -19 p = rcu_dereference(gp); +19 p = rcu_access_pointer(gp); 20 if (!p) { 21 spin_unlock(&gp_lock); 22 return false; @@ -1822,6 +1773,106 @@ so it is too early to tell whether they will stand the test of time. RCU thus provides a range of tools to allow updaters to strike the required tradeoff between latency, flexibility and CPU overhead. +<h3><a name="Forward Progress">Forward Progress</a></h3> + +<p> +In theory, delaying grace-period completion and callback invocation +is harmless. +In practice, not only are memory sizes finite but also callbacks sometimes +do wakeups, and sufficiently deferred wakeups can be difficult +to distinguish from system hangs. +Therefore, RCU must provide a number of mechanisms to promote forward +progress. + +<p> +These mechanisms are not foolproof, nor can they be. +For one simple example, an infinite loop in an RCU read-side critical +section must by definition prevent later grace periods from ever completing. +For a more involved example, consider a 64-CPU system built with +<tt>CONFIG_RCU_NOCB_CPU=y</tt> and booted with <tt>rcu_nocbs=1-63</tt>, +where CPUs 1 through 63 spin in tight loops that invoke +<tt>call_rcu()</tt>. +Even if these tight loops also contain calls to <tt>cond_resched()</tt> +(thus allowing grace periods to complete), CPU 0 simply will +not be able to invoke callbacks as fast as the other 63 CPUs can +register them, at least not until the system runs out of memory. +In both of these examples, the Spiderman principle applies: With great +power comes great responsibility. +However, short of this level of abuse, RCU is required to +ensure timely completion of grace periods and timely invocation of +callbacks. + +<p> +RCU takes the following steps to encourage timely completion of +grace periods: + +<ol> +<li> If a grace period fails to complete within 100 milliseconds, + RCU causes future invocations of <tt>cond_resched()</tt> on + the holdout CPUs to provide an RCU quiescent state. + RCU also causes those CPUs' <tt>need_resched()</tt> invocations + to return <tt>true</tt>, but only after the corresponding CPU's + next scheduling-clock. +<li> CPUs mentioned in the <tt>nohz_full</tt> kernel boot parameter + can run indefinitely in the kernel without scheduling-clock + interrupts, which defeats the above <tt>need_resched()</tt> + strategem. + RCU will therefore invoke <tt>resched_cpu()</tt> on any + <tt>nohz_full</tt> CPUs still holding out after + 109 milliseconds. +<li> In kernels built with <tt>CONFIG_RCU_BOOST=y</tt>, if a given + task that has been preempted within an RCU read-side critical + section is holding out for more than 500 milliseconds, + RCU will resort to priority boosting. +<li> If a CPU is still holding out 10 seconds into the grace + period, RCU will invoke <tt>resched_cpu()</tt> on it regardless + of its <tt>nohz_full</tt> state. +</ol> + +<p> +The above values are defaults for systems running with <tt>HZ=1000</tt>. +They will vary as the value of <tt>HZ</tt> varies, and can also be +changed using the relevant Kconfig options and kernel boot parameters. +RCU currently does not do much sanity checking of these +parameters, so please use caution when changing them. +Note that these forward-progress measures are provided only for RCU, +not for +<a href="#Sleepable RCU">SRCU</a> or +<a href="#Tasks RCU">Tasks RCU</a>. + +<p> +RCU takes the following steps in <tt>call_rcu()</tt> to encourage timely +invocation of callbacks when any given non-<tt>rcu_nocbs</tt> CPU has +10,000 callbacks, or has 10,000 more callbacks than it had the last time +encouragement was provided: + +<ol> +<li> Starts a grace period, if one is not already in progress. +<li> Forces immediate checking for quiescent states, rather than + waiting for three milliseconds to have elapsed since the + beginning of the grace period. +<li> Immediately tags the CPU's callbacks with their grace period + completion numbers, rather than waiting for the <tt>RCU_SOFTIRQ</tt> + handler to get around to it. +<li> Lifts callback-execution batch limits, which speeds up callback + invocation at the expense of degrading realtime response. +</ol> + +<p> +Again, these are default values when running at <tt>HZ=1000</tt>, +and can be overridden. +Again, these forward-progress measures are provided only for RCU, +not for +<a href="#Sleepable RCU">SRCU</a> or +<a href="#Tasks RCU">Tasks RCU</a>. +Even for RCU, callback-invocation forward progress for <tt>rcu_nocbs</tt> +CPUs is much less well-developed, in part because workloads benefiting +from <tt>rcu_nocbs</tt> CPUs tend to invoke <tt>call_rcu()</tt> +relatively infrequently. +If workloads emerge that need both <tt>rcu_nocbs</tt> CPUs and high +<tt>call_rcu()</tt> invocation rates, then additional forward-progress +work will be required. + <h3><a name="Composability">Composability</a></h3> <p> @@ -2272,7 +2323,7 @@ that meets this requirement. Furthermore, NMI handlers can be interrupted by what appear to RCU to be normal interrupts. One way that this can happen is for code that directly invokes -<tt>rcu_irq_enter()</tt> and </tt>rcu_irq_exit()</tt> to be called +<tt>rcu_irq_enter()</tt> and <tt>rcu_irq_exit()</tt> to be called from an NMI handler. This astonishing fact of life prompted the current code structure, which has <tt>rcu_irq_enter()</tt> invoking <tt>rcu_nmi_enter()</tt> @@ -2294,7 +2345,7 @@ via <tt>del_timer_sync()</tt> or similar. <p> Unfortunately, there is no way to cancel an RCU callback; once you invoke <tt>call_rcu()</tt>, the callback function is -going to eventually be invoked, unless the system goes down first. +eventually going to be invoked, unless the system goes down first. Because it is normally considered socially irresponsible to crash the system in response to a module unload request, we need some other way to deal with in-flight RCU callbacks. @@ -2424,23 +2475,37 @@ for context-switch-heavy <tt>CONFIG_NO_HZ_FULL=y</tt> workloads, but there is room for further improvement. <p> -In the past, it was forbidden to disable interrupts across an -<tt>rcu_read_unlock()</tt> unless that interrupt-disabled region -of code also included the matching <tt>rcu_read_lock()</tt>. -Violating this restriction could result in deadlocks involving the -scheduler's runqueue and priority-inheritance spinlocks. -This restriction was lifted when interrupt-disabled calls to -<tt>rcu_read_unlock()</tt> started deferring the reporting of -the resulting RCU-preempt quiescent state until the end of that +It is forbidden to hold any of scheduler's runqueue or priority-inheritance +spinlocks across an <tt>rcu_read_unlock()</tt> unless interrupts have been +disabled across the entire RCU read-side critical section, that is, +up to and including the matching <tt>rcu_read_lock()</tt>. +Violating this restriction can result in deadlocks involving these +scheduler spinlocks. +There was hope that this restriction might be lifted when interrupt-disabled +calls to <tt>rcu_read_unlock()</tt> started deferring the reporting of +the resulting RCU-preempt quiescent state until the end of the corresponding interrupts-disabled region. -This deferred reporting means that the scheduler's runqueue and -priority-inheritance locks cannot be held while reporting an RCU-preempt -quiescent state, which lifts the earlier restriction, at least from -a deadlock perspective. -Unfortunately, real-time systems using RCU priority boosting may +Unfortunately, timely reporting of the corresponding quiescent state +to expedited grace periods requires a call to <tt>raise_softirq()</tt>, +which can acquire these scheduler spinlocks. +In addition, real-time systems using RCU priority boosting need this restriction to remain in effect because deferred -quiescent-state reporting also defers deboosting, which in turn -degrades real-time latencies. +quiescent-state reporting would also defer deboosting, which in turn +would degrade real-time latencies. + +<p> +In theory, if a given RCU read-side critical section could be +guaranteed to be less than one second in duration, holding a scheduler +spinlock across that critical section's <tt>rcu_read_unlock()</tt> +would require only that preemption be disabled across the entire +RCU read-side critical section, not interrupts. +Unfortunately, given the possibility of vCPU preemption, long-running +interrupts, and so on, it is not possible in practice to guarantee +that a given RCU read-side critical section will complete in less than +one second. +Therefore, as noted above, if scheduler spinlocks are held across +a given call to <tt>rcu_read_unlock()</tt>, interrupts must be +disabled across the entire RCU read-side critical section. <h3><a name="Tracing and RCU">Tracing and RCU</a></h3> @@ -3034,7 +3099,7 @@ If you block forever in one of a given domain's SRCU read-side critical sections, then that domain's grace periods will also be blocked forever. Of course, one good way to block forever is to deadlock, which can happen if any operation in a given domain's SRCU read-side critical -section can block waiting, either directly or indirectly, for that domain's +section can wait, either directly or indirectly, for that domain's grace period to elapse. For example, this results in a self-deadlock: @@ -3074,12 +3139,18 @@ API, which, in combination with <tt>srcu_read_unlock()</tt>, guarantees a full memory barrier. <p> -Also unlike other RCU flavors, SRCU's callbacks-wait function -<tt>srcu_barrier()</tt> may be invoked from CPU-hotplug notifiers, -though this is not necessarily a good idea. -The reason that this is possible is that SRCU is insensitive -to whether or not a CPU is online, which means that <tt>srcu_barrier()</tt> -need not exclude CPU-hotplug operations. +Also unlike other RCU flavors, <tt>synchronize_srcu()</tt> may <b>not</b> +be invoked from CPU-hotplug notifiers, due to the fact that SRCU grace +periods make use of timers and the possibility of timers being temporarily +“stranded” on the outgoing CPU. +This stranding of timers means that timers posted to the outgoing CPU +will not fire until late in the CPU-hotplug process. +The problem is that if a notifier is waiting on an SRCU grace period, +that grace period is waiting on a timer, and that timer is stranded on the +outgoing CPU, then the notifier will never be awakened, in other words, +deadlock has occurred. +This same situation of course also prohibits <tt>srcu_barrier()</tt> +from being invoked from CPU-hotplug notifiers. <p> SRCU also differs from other RCU flavors in that SRCU's expedited and @@ -3233,6 +3304,11 @@ For example, RCU callback overhead might be charged back to the originating <tt>call_rcu()</tt> instance, though probably not in production kernels. +<p> +Additional work may be required to provide reasonable forward-progress +guarantees under heavy load for grace periods and for callback +invocation. + <h2><a name="Summary">Summary</a></h2> <p> diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index 49747717d905..6f469864d9f5 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.txt @@ -63,7 +63,7 @@ over a rather long period of time, but improvements are always welcome! pointer must be covered by rcu_read_lock(), rcu_read_lock_bh(), rcu_read_lock_sched(), or by the appropriate update-side lock. Disabling of preemption can serve as rcu_read_lock_sched(), but - is less readable. + is less readable and prevents lockdep from detecting locking issues. Letting RCU-protected pointers "leak" out of an RCU read-side critical section is every bid as bad as letting them leak out @@ -285,11 +285,7 @@ over a rather long period of time, but improvements are always welcome! here is that superuser already has lots of ways to crash the machine. - d. Use call_rcu_bh() rather than call_rcu(), in order to take - advantage of call_rcu_bh()'s faster grace periods. (This - is only a partial solution, though.) - - e. Periodically invoke synchronize_rcu(), permitting a limited + d. Periodically invoke synchronize_rcu(), permitting a limited number of updates per grace period. The same cautions apply to call_rcu_bh(), call_rcu_sched(), @@ -324,37 +320,14 @@ over a rather long period of time, but improvements are always welcome! will break Alpha, cause aggressive compilers to generate bad code, and confuse people trying to read your code. -11. Note that synchronize_rcu() -only- guarantees to wait until - all currently executing rcu_read_lock()-protected RCU read-side - critical sections complete. It does -not- necessarily guarantee - that all currently running interrupts, NMIs, preempt_disable() - code, or idle loops will complete. Therefore, if your - read-side critical sections are protected by something other - than rcu_read_lock(), do -not- use synchronize_rcu(). - - Similarly, disabling preemption is not an acceptable substitute - for rcu_read_lock(). Code that attempts to use preemption - disabling where it should be using rcu_read_lock() will break - in CONFIG_PREEMPT=y kernel builds. - - If you want to wait for interrupt handlers, NMI handlers, and - code under the influence of preempt_disable(), you instead - need to use synchronize_irq() or synchronize_sched(). - - This same limitation also applies to synchronize_rcu_bh() - and synchronize_srcu(), as well as to the asynchronous and - expedited forms of the three primitives, namely call_rcu(), - call_rcu_bh(), call_srcu(), synchronize_rcu_expedited(), - synchronize_rcu_bh_expedited(), and synchronize_srcu_expedited(). - -12. Any lock acquired by an RCU callback must be acquired elsewhere +11. Any lock acquired by an RCU callback must be acquired elsewhere with softirq disabled, e.g., via spin_lock_irqsave(), spin_lock_bh(), etc. Failing to disable irq on a given acquisition of that lock will result in deadlock as soon as the RCU softirq handler happens to run your RCU callback while interrupting that acquisition's critical section. -13. RCU callbacks can be and are executed in parallel. In many cases, +12. RCU callbacks can be and are executed in parallel. In many cases, the callback code simply wrappers around kfree(), so that this is not an issue (or, more accurately, to the extent that it is an issue, the memory-allocator locking handles it). However, @@ -370,7 +343,7 @@ over a rather long period of time, but improvements are always welcome! not the case, a self-spawning RCU callback would prevent the victim CPU from ever going offline.) -14. Unlike other forms of RCU, it -is- permissible to block in an +13. Unlike other forms of RCU, it -is- permissible to block in an SRCU read-side critical section (demarked by srcu_read_lock() and srcu_read_unlock()), hence the "SRCU": "sleepable RCU". Please note that if you don't need to sleep in read-side critical @@ -414,7 +387,7 @@ over a rather long period of time, but improvements are always welcome! Note that rcu_dereference() and rcu_assign_pointer() relate to SRCU just as they do to other forms of RCU. -15. The whole point of call_rcu(), synchronize_rcu(), and friends +14. The whole point of call_rcu(), synchronize_rcu(), and friends is to wait until all pre-existing readers have finished before carrying out some otherwise-destructive operation. It is therefore critically important to -first- remove any path @@ -426,13 +399,13 @@ over a rather long period of time, but improvements are always welcome! is the caller's responsibility to guarantee that any subsequent readers will execute safely. -16. The various RCU read-side primitives do -not- necessarily contain +15. The various RCU read-side primitives do -not- necessarily contain memory barriers. You should therefore plan for the CPU and the compiler to freely reorder code into and out of RCU read-side critical sections. It is the responsibility of the RCU update-side primitives to deal with this. -17. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the +16. Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the __rcu sparse checks to validate your RCU code. These can help find problems as follows: @@ -455,7 +428,7 @@ over a rather long period of time, but improvements are always welcome! These debugging aids can help you find problems that are otherwise extremely difficult to spot. -18. If you register a callback using call_rcu(), call_rcu_bh(), +17. If you register a callback using call_rcu(), call_rcu_bh(), call_rcu_sched(), or call_srcu(), and pass in a function defined within a loadable module, then it in necessary to wait for all pending callbacks to be invoked after the last invocation @@ -469,8 +442,8 @@ over a rather long period of time, but improvements are always welcome! You instead need to use one of the barrier functions: o call_rcu() -> rcu_barrier() - o call_rcu_bh() -> rcu_barrier_bh() - o call_rcu_sched() -> rcu_barrier_sched() + o call_rcu_bh() -> rcu_barrier() + o call_rcu_sched() -> rcu_barrier() o call_srcu() -> srcu_barrier() However, these barrier functions are absolutely -not- guaranteed diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 491043fd976f..1ab70c37921f 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -176,9 +176,8 @@ causing stalls, and that the stall was affecting RCU-sched. This message will normally be followed by stack dumps for each CPU. Please note that PREEMPT_RCU builds can be stalled by tasks as well as by CPUs, and that the tasks will be indicated by PID, for example, "P3421". It is even -possible for a rcu_preempt_state stall to be caused by both CPUs -and- -tasks, in which case the offending CPUs and tasks will all be called -out in the list. +possible for an rcu_state stall to be caused by both CPUs -and- tasks, +in which case the offending CPUs and tasks will all be called out in the list. CPU 2's "(3 GPs behind)" indicates that this CPU has not interacted with the RCU core for the past three grace periods. In contrast, CPU 16's "(0 @@ -206,7 +205,7 @@ handlers are no longer able to execute on this CPU. This can happen if the stalled CPU is spinning with interrupts are disabled, or, in -rt kernels, if a high-priority process is starving RCU's softirq handler. -The "fps=" shows the number of force-quiescent-state idle/offline +The "fqs=" shows the number of force-quiescent-state idle/offline detection passes that the grace-period kthread has made across this CPU since the last time that this CPU noted the beginning of a grace period. @@ -220,17 +219,18 @@ an estimate of the total number of RCU callbacks queued across all CPUs In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed for each CPU: - 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 nonlazy_posted: 25 .D + 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 Nonlazy posted: ..D The "last_accelerate:" prints the low-order 16 bits (in hex) of the jiffies counter when this CPU last invoked rcu_try_advance_all_cbs() from rcu_needs_cpu() or last invoked rcu_accelerate_cbs() from -rcu_prepare_for_idle(). The "nonlazy_posted:" prints the number -of non-lazy callbacks posted since the last call to rcu_needs_cpu(). -Finally, an "L" indicates that there are currently no non-lazy callbacks -("." is printed otherwise, as shown above) and "D" indicates that -dyntick-idle processing is enabled ("." is printed otherwise, for example, -if disabled via the "nohz=" kernel boot parameter). +rcu_prepare_for_idle(). The "Nonlazy posted:" indicates lazy-callback +status, so that an "l" indicates that all callbacks were lazy at the start +of the last idle period and an "L" indicates that there are currently +no non-lazy callbacks (in both cases, "." is printed otherwise, as +shown above) and "D" indicates that dyntick-idle processing is enabled +("." is printed otherwise, for example, if disabled via the "nohz=" +kernel boot parameter). If the grace period ends just as the stall warning starts printing, there will be a spurious stall-warning message, which will include diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt index 55918b54808b..a41a0384d20c 100644 --- a/Documentation/RCU/torture.txt +++ b/Documentation/RCU/torture.txt @@ -10,173 +10,8 @@ status messages via printk(), which can be examined via the dmesg command (perhaps grepping for "torture"). The test is started when the module is loaded, and stops when the module is unloaded. - -MODULE PARAMETERS - -This module has the following parameters: - -fqs_duration Duration (in microseconds) of artificially induced bursts - of force_quiescent_state() invocations. In RCU - implementations having force_quiescent_state(), these - bursts help force races between forcing a given grace - period and that grace period ending on its own. - -fqs_holdoff Holdoff time (in microseconds) between consecutive calls - to force_quiescent_state() within a burst. - -fqs_stutter Wait time (in seconds) between consecutive bursts - of calls to force_quiescent_state(). - -gp_normal Make the fake writers use normal synchronous grace-period - primitives. - -gp_exp Make the fake writers use expedited synchronous grace-period - primitives. If both gp_normal and gp_exp are set, or - if neither gp_normal nor gp_exp are set, then randomly - choose the primitive so that about 50% are normal and - 50% expedited. By default, neither are set, which - gives best overall test coverage. - -irqreader Says to invoke RCU readers from irq level. This is currently - done via timers. Defaults to "1" for variants of RCU that - permit this. (Or, more accurately, variants of RCU that do - -not- permit this know to ignore this variable.) - -n_barrier_cbs If this is nonzero, RCU barrier testing will be conducted, - in which case n_barrier_cbs specifies the number of - RCU callbacks (and corresponding kthreads) to use for - this testing. The value cannot be negative. If you - specify this to be non-zero when torture_type indicates a - synchronous RCU implementation (one for which a member of - the synchronize_rcu() rather than the call_rcu() family is - used -- see the documentation for torture_type below), an - error will be reported and no testing will be carried out. - -nfakewriters This is the number of RCU fake writer threads to run. Fake - writer threads repeatedly use the synchronous "wait for - current readers" function of the interface selected by - torture_type, with a delay between calls to allow for various - different numbers of writers running in parallel. - nfakewriters defaults to 4, which provides enough parallelism - to trigger special cases caused by multiple writers, such as - the synchronize_srcu() early return optimization. - -nreaders This is the number of RCU reading threads supported. - The default is twice the number of CPUs. Why twice? - To properly exercise RCU implementations with preemptible - read-side critical sections. - -onoff_interval - The number of seconds between each attempt to execute a - randomly selected CPU-hotplug operation. Defaults to - zero, which disables CPU hotplugging. In HOTPLUG_CPU=n - kernels, rcutorture will silently refuse to do any - CPU-hotplug operations regardless of what value is - specified for onoff_interval. - -onoff_holdoff The number of seconds to wait until starting CPU-hotplug - operations. This would normally only be used when - rcutorture was built into the kernel and started - automatically at boot time, in which case it is useful - in order to avoid confusing boot-time code with CPUs - coming and going. - -shuffle_interval - The number of seconds to keep the test threads affinitied - to a particular subset of the CPUs, defaults to 3 seconds. - Used in conjunction with test_no_idle_hz. - -shutdown_secs The number of seconds to run the test before terminating - the test and powering off the system. The default is - zero, which disables test termination and system shutdown. - This capability is useful for automated testing. - -stall_cpu The number of seconds that a CPU should be stalled while - within both an rcu_read_lock() and a preempt_disable(). - This stall happens only once per rcutorture run. - If you need multiple stalls, use modprobe and rmmod to - repeatedly run rcutorture. The default for stall_cpu - is zero, which prevents rcutorture from stalling a CPU. - - Note that attempts to rmmod rcutorture while the stall - is ongoing will hang, so be careful what value you - choose for this module parameter! In addition, too-large - values for stall_cpu might well induce failures and - warnings in other parts of the kernel. You have been - warned! - -stall_cpu_holdoff - The number of seconds to wait after rcutorture starts - before stalling a CPU. Defaults to 10 seconds. - -stat_interval The number of seconds between output of torture - statistics (via printk()). Regardless of the interval, - statistics are printed when the module is unloaded. - Setting the interval to zero causes the statistics to - be printed -only- when the module is unloaded, and this - is the default. - -stutter The length of time to run the test before pausing for this - same period of time. Defaults to "stutter=5", so as - to run and pause for (roughly) five-second intervals. - Specifying "stutter=0" causes the test to run continuously - without pausing, which is the old default behavior. - -test_boost Whether or not to test the ability of RCU to do priority - boosting. Defaults to "test_boost=1", which performs - RCU priority-inversion testing only if the selected - RCU implementation supports priority boosting. Specifying - "test_boost=0" never performs RCU priority-inversion - testing. Specifying "test_boost=2" performs RCU - priority-inversion testing even if the selected RCU - implementation does not support RCU priority boosting, - which can be used to test rcutorture's ability to - carry out RCU priority-inversion testing. - -test_boost_interval - The number of seconds in an RCU priority-inversion test - cycle. Defaults to "test_boost_interval=7". It is - usually wise for this value to be relatively prime to - the value selected for "stutter". - -test_boost_duration - The number of seconds to do RCU priority-inversion testing - within any given "test_boost_interval". Defaults to - "test_boost_duration=4". - -test_no_idle_hz Whether or not to test the ability of RCU to operate in - a kernel that disables the scheduling-clock interrupt to - idle CPUs. Boolean parameter, "1" to test, "0" otherwise. - Defaults to omitting this test. - -torture_type The type of RCU to test, with string values as follows: - - "rcu": rcu_read_lock(), rcu_read_unlock() and call_rcu(), - along with expedited, synchronous, and polling - variants. - - "rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and - call_rcu_bh(), along with expedited and synchronous - variants. - - "rcu_busted": This tests an intentionally incorrect version - of RCU in order to help test rcutorture itself. - - "srcu": srcu_read_lock(), srcu_read_unlock() and - call_srcu(), along with expedited and - synchronous variants. - - "sched": preempt_disable(), preempt_enable(), and - call_rcu_sched(), along with expedited, - synchronous, and polling variants. - - "tasks": voluntary context switch and call_rcu_tasks(), - along with expedited and synchronous variants. - - Defaults to "rcu". - -verbose Enable debug printk()s. Default is disabled. - +Module parameters are prefixed by "rcutorture." in +Documentation/admin-guide/kernel-parameters.txt. OUTPUT diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index 86d82f7f3500..1ace20815bb1 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -266,7 +266,7 @@ rcu_dereference() unnecessary overhead on Alpha CPUs. Note that the value returned by rcu_dereference() is valid - only within the enclosing RCU read-side critical section. + only within the enclosing RCU read-side critical section [1]. For example, the following is -not- legal: rcu_read_lock(); @@ -292,6 +292,19 @@ rcu_dereference() typically used indirectly, via the _rcu list-manipulation primitives, such as list_for_each_entry_rcu(). + [1] The variant rcu_dereference_protected() can be used outside + of an RCU read-side critical section as long as the usage is + protected by locks acquired by the update-side code. This variant + avoids the lockdep warning that would happen when using (for + example) rcu_dereference() without rcu_read_lock() protection. + Using rcu_dereference_protected() also has the advantage + of permitting compiler optimizations that rcu_dereference() + must prohibit. The rcu_dereference_protected() variant takes + a lockdep expression to indicate which locks must be acquired + by the caller. If the indicated protection is not provided, + a lockdep splat is emitted. See RCU/Design/Requirements/Requirements.html + and the API's code comments for more details and example usage. + The following diagram shows how each API communicates among the reader, updater, and reclaimer. @@ -322,28 +335,27 @@ to their callers and (2) call_rcu() callbacks may be invoked. Efficient implementations of the RCU infrastructure make heavy use of batching in order to amortize their overhead over many uses of the corresponding APIs. -There are no fewer than three RCU mechanisms in the Linux kernel; the -diagram above shows the first one, which is by far the most commonly used. -The rcu_dereference() and rcu_assign_pointer() primitives are used for -all three mechanisms, but different defer and protect primitives are -used as follows: - - Defer Protect +There are at least three flavors of RCU usage in the Linux kernel. The diagram +above shows the most common one. On the updater side, the rcu_assign_pointer(), +sychronize_rcu() and call_rcu() primitives used are the same for all three +flavors. However for protection (on the reader side), the primitives used vary +depending on the flavor: -a. synchronize_rcu() rcu_read_lock() / rcu_read_unlock() - call_rcu() rcu_dereference() +a. rcu_read_lock() / rcu_read_unlock() + rcu_dereference() -b. synchronize_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh() - call_rcu_bh() rcu_dereference_bh() +b. rcu_read_lock_bh() / rcu_read_unlock_bh() + local_bh_disable() / local_bh_enable() + rcu_dereference_bh() -c. synchronize_sched() rcu_read_lock_sched() / rcu_read_unlock_sched() - call_rcu_sched() preempt_disable() / preempt_enable() - local_irq_save() / local_irq_restore() - hardirq enter / hardirq exit - NMI enter / NMI exit - rcu_dereference_sched() +c. rcu_read_lock_sched() / rcu_read_unlock_sched() + preempt_disable() / preempt_enable() + local_irq_save() / local_irq_restore() + hardirq enter / hardirq exit + NMI enter / NMI exit + rcu_dereference_sched() -These three mechanisms are used as follows: +These three flavors are used as follows: a. RCU applied to normal data structures. @@ -548,7 +560,7 @@ presents two such "toy" implementations of RCU, one that is implemented in terms of familiar locking primitives, and another that more closely resembles "classic" RCU. Both are way too simple for real-world use, lacking both functionality and performance. However, they are useful -in getting a feel for how RCU works. See kernel/rcupdate.c for a +in getting a feel for how RCU works. See kernel/rcu/update.c for a production-quality implementation, and see: http://www.rdrop.com/users/paulmck/RCU @@ -867,18 +879,20 @@ RCU: Critical sections Grace period Barrier bh: Critical sections Grace period Barrier - rcu_read_lock_bh call_rcu_bh rcu_barrier_bh - rcu_read_unlock_bh synchronize_rcu_bh - rcu_dereference_bh synchronize_rcu_bh_expedited + rcu_read_lock_bh call_rcu rcu_barrier + rcu_read_unlock_bh synchronize_rcu + [local_bh_disable] synchronize_rcu_expedited + [and friends] + rcu_dereference_bh rcu_dereference_bh_check rcu_dereference_bh_protected rcu_read_lock_bh_held sched: Critical sections Grace period Barrier - rcu_read_lock_sched synchronize_sched rcu_barrier_sched - rcu_read_unlock_sched call_rcu_sched - [preempt_disable] synchronize_sched_expedited + rcu_read_lock_sched call_rcu rcu_barrier + rcu_read_unlock_sched synchronize_rcu + [preempt_disable] synchronize_rcu_expedited [and friends] rcu_read_lock_sched_notrace rcu_read_unlock_sched_notrace @@ -890,8 +904,8 @@ sched: Critical sections Grace period Barrier SRCU: Critical sections Grace period Barrier - srcu_read_lock synchronize_srcu srcu_barrier - srcu_read_unlock call_srcu + srcu_read_lock call_srcu srcu_barrier + srcu_read_unlock synchronize_srcu srcu_dereference synchronize_srcu_expedited srcu_dereference_check srcu_read_lock_held @@ -1034,7 +1048,7 @@ Answer: Just as PREEMPT_RT permits preemption of spinlock spinlocks blocking while in RCU read-side critical sections. - Why the apparent inconsistency? Because it is it + Why the apparent inconsistency? Because it is possible to use priority boosting to keep the RCU grace periods short if need be (for example, if running short of memory). In contrast, if blocking waiting diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.txt new file mode 100644 index 000000000000..b8ca28b60215 --- /dev/null +++ b/Documentation/accounting/psi.txt @@ -0,0 +1,73 @@ +================================ +PSI - Pressure Stall Information +================================ + +:Date: April, 2018 +:Author: Johannes Weiner <hannes@cmpxchg.org> + +When CPU, memory or IO devices are contended, workloads experience +latency spikes, throughput losses, and run the risk of OOM kills. + +Without an accurate measure of such contention, users are forced to +either play it safe and under-utilize their hardware resources, or +roll the dice and frequently suffer the disruptions resulting from +excessive overcommit. + +The psi feature identifies and quantifies the disruptions caused by +such resource crunches and the time impact it has on complex workloads +or even entire systems. + +Having an accurate measure of productivity losses caused by resource +scarcity aids users in sizing workloads to hardware--or provisioning +hardware according to workload demand. + +As psi aggregates this information in realtime, systems can be managed +dynamically using techniques such as load shedding, migrating jobs to +other systems or data centers, or strategically pausing or killing low +priority or restartable batch jobs. + +This allows maximizing hardware utilization without sacrificing +workload health or risking major disruptions such as OOM kills. + +Pressure interface +================== + +Pressure information for each resource is exported through the +respective file in /proc/pressure/ -- cpu, memory, and io. + +The format for CPU is as such: + +some avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +and for memory and IO: + +some avg10=0.00 avg60=0.00 avg300=0.00 total=0 +full avg10=0.00 avg60=0.00 avg300=0.00 total=0 + +The "some" line indicates the share of time in which at least some +tasks are stalled on a given resource. + +The "full" line indicates the share of time in which all non-idle +tasks are stalled on a given resource simultaneously. In this state +actual CPU cycles are going to waste, and a workload that spends +extended time in this state is considered to be thrashing. This has +severe impact on performance, and it's useful to distinguish this +situation from a state where some tasks are stalled but the CPU is +still doing productive work. As such, time spent in this subset of the +stall state is tracked separately and exported in the "full" averages. + +The ratios are tracked as recent trends over ten, sixty, and three +hundred second windows, which gives insight into short term events as +well as medium and long term trends. The total absolute stall time is +tracked and exported as well, to allow detection of latency spikes +which wouldn't necessarily make a dent in the time averages, or to +average trends over custom time frames. + +Cgroup2 interface +================= + +In a system with a CONFIG_CGROUP=y kernel and the cgroup2 filesystem +mounted, pressure stall information is also tracked for tasks grouped +into cgroups. Each subdirectory in the cgroupfs mountpoint contains +cpu.pressure, memory.pressure, and io.pressure files; the format is +the same as the /proc/pressure/ files. diff --git a/Documentation/acpi/initrd_table_override.txt b/Documentation/acpi/initrd_table_override.txt index eb651a6aa285..30437a6db373 100644 --- a/Documentation/acpi/initrd_table_override.txt +++ b/Documentation/acpi/initrd_table_override.txt @@ -14,6 +14,10 @@ upgrade the ACPI execution environment that is defined by the ACPI tables via upgrading the ACPI tables provided by the BIOS with an instrumented, modified, more recent version one, or installing brand new ACPI tables. +When building initrd with kernel in a single image, option +ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this +feature to work. + For a full list of ACPI tables that can be upgraded/installed, take a look at the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in drivers/acpi/tables.c. diff --git a/Documentation/admin-guide/LSM/SELinux.rst b/Documentation/admin-guide/LSM/SELinux.rst index f722c9b4173a..520a1c2c6fd2 100644 --- a/Documentation/admin-guide/LSM/SELinux.rst +++ b/Documentation/admin-guide/LSM/SELinux.rst @@ -6,7 +6,7 @@ If you want to use SELinux, chances are you will want to use the distro-provided policies, or install the latest reference policy release from - http://oss.tresys.com/projects/refpolicy + https://github.com/SELinuxProject/refpolicy However, if you want to install a dummy policy for testing, you can do using ``mdp`` provided under diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst new file mode 100644 index 000000000000..212434ef65ad --- /dev/null +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -0,0 +1,107 @@ +========= +SafeSetID +========= +SafeSetID is an LSM module that gates the setid family of syscalls to restrict +UID/GID transitions from a given UID/GID to only those approved by a +system-wide whitelist. These restrictions also prohibit the given UIDs/GIDs +from obtaining auxiliary privileges associated with CAP_SET{U/G}ID, such as +allowing a user to set up user namespace UID mappings. + + +Background +========== +In absence of file capabilities, processes spawned on a Linux system that need +to switch to a different user must be spawned with CAP_SETUID privileges. +CAP_SETUID is granted to programs running as root or those running as a non-root +user that have been explicitly given the CAP_SETUID runtime capability. It is +often preferable to use Linux runtime capabilities rather than file +capabilities, since using file capabilities to run a program with elevated +privileges opens up possible security holes since any user with access to the +file can exec() that program to gain the elevated privileges. + +While it is possible to implement a tree of processes by giving full +CAP_SET{U/G}ID capabilities, this is often at odds with the goals of running a +tree of processes under non-root user(s) in the first place. Specifically, +since CAP_SETUID allows changing to any user on the system, including the root +user, it is an overpowered capability for what is needed in this scenario, +especially since programs often only call setuid() to drop privileges to a +lesser-privileged user -- not elevate privileges. Unfortunately, there is no +generally feasible way in Linux to restrict the potential UIDs that a user can +switch to through setuid() beyond allowing a switch to any user on the system. +This SafeSetID LSM seeks to provide a solution for restricting setid +capabilities in such a way. + +The main use case for this LSM is to allow a non-root program to transition to +other untrusted uids without full blown CAP_SETUID capabilities. The non-root +program would still need CAP_SETUID to do any kind of transition, but the +additional restrictions imposed by this LSM would mean it is a "safer" version +of CAP_SETUID since the non-root program cannot take advantage of CAP_SETUID to +do any unapproved actions (e.g. setuid to uid 0 or create/enter new user +namespace). The higher level goal is to allow for uid-based sandboxing of system +services without having to give out CAP_SETUID all over the place just so that +non-root programs can drop to even-lesser-privileged uids. This is especially +relevant when one non-root daemon on the system should be allowed to spawn other +processes as different uids, but its undesirable to give the daemon a +basically-root-equivalent CAP_SETUID. + + +Other Approaches Considered +=========================== + +Solve this problem in userspace +------------------------------- +For candidate applications that would like to have restricted setid capabilities +as implemented in this LSM, an alternative option would be to simply take away +setid capabilities from the application completely and refactor the process +spawning semantics in the application (e.g. by using a privileged helper program +to do process spawning and UID/GID transitions). Unfortunately, there are a +number of semantics around process spawning that would be affected by this, such +as fork() calls where the program doesn???t immediately call exec() after the +fork(), parent processes specifying custom environment variables or command line +args for spawned child processes, or inheritance of file handles across a +fork()/exec(). Because of this, as solution that uses a privileged helper in +userspace would likely be less appealing to incorporate into existing projects +that rely on certain process-spawning semantics in Linux. + +Use user namespaces +------------------- +Another possible approach would be to run a given process tree in its own user +namespace and give programs in the tree setid capabilities. In this way, +programs in the tree could change to any desired UID/GID in the context of their +own user namespace, and only approved UIDs/GIDs could be mapped back to the +initial system user namespace, affectively preventing privilege escalation. +Unfortunately, it is not generally feasible to use user namespaces in isolation, +without pairing them with other namespace types, which is not always an option. +Linux checks for capabilities based off of the user namespace that ???owns??? some +entity. For example, Linux has the notion that network namespaces are owned by +the user namespace in which they were created. A consequence of this is that +capability checks for access to a given network namespace are done by checking +whether a task has the given capability in the context of the user namespace +that owns the network namespace -- not necessarily the user namespace under +which the given task runs. Therefore spawning a process in a new user namespace +effectively prevents it from accessing the network namespace owned by the +initial namespace. This is a deal-breaker for any application that expects to +retain the CAP_NET_ADMIN capability for the purpose of adjusting network +configurations. Using user namespaces in isolation causes problems regarding +other system interactions, including use of pid namespaces and device creation. + +Use an existing LSM +------------------- +None of the other in-tree LSMs have the capability to gate setid transitions, or +even employ the security_task_fix_setuid hook at all. SELinux says of that hook: +"Since setuid only affects the current process, and since the SELinux controls +are not based on the Linux identity attributes, SELinux does not need to control +this operation." + + +Directions for use +================== +This LSM hooks the setid syscalls to make sure transitions are allowed if an +applicable restriction policy is in place. Policies are configured through +securityfs by writing to the safesetid/add_whitelist_policy and +safesetid/flush_whitelist_policies files at the location where securityfs is +mounted. The format for adding a policy is '<UID>:<UID>', using literal +numbers, such as '123:456'. To flush the policies, any write to the file is +sufficient. Again, configuring a policy for a UID will prevent that UID from +obtaining auxiliary setid privileges, such as allowing a user to set up user +namespace UID mappings. diff --git a/Documentation/admin-guide/LSM/Smack.rst b/Documentation/admin-guide/LSM/Smack.rst index 6a5826a13aea..6d44f4fdbf59 100644 --- a/Documentation/admin-guide/LSM/Smack.rst +++ b/Documentation/admin-guide/LSM/Smack.rst @@ -818,6 +818,10 @@ Smack supports some mount options: specifies a label to which all labels set on the filesystem must have read access. Not yet enforced. + smackfstransmute=label: + behaves exactly like smackfsroot except that it also + sets the transmute flag on the root of the mount + These mount options apply to all file system types. Smack auditing diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst index c980dfe9abf1..a6ba95fbaa9f 100644 --- a/Documentation/admin-guide/LSM/index.rst +++ b/Documentation/admin-guide/LSM/index.rst @@ -17,9 +17,8 @@ MAC extensions, other extensions can be built using the LSM to provide specific changes to system operation when these tweaks are not available in the core functionality of Linux itself. -Without a specific LSM built into the kernel, the default LSM will be the -Linux capabilities system. Most LSMs choose to extend the capabilities -system, building their checks on top of the defined capability hooks. +The Linux capabilities modules will always be included. This may be +followed by any number of "minor" modules and at most one "major" module. For more details on capabilities, see ``capabilities(7)`` in the Linux man-pages project. @@ -30,6 +29,14 @@ order in which checks are made. The capability module will always be first, followed by any "minor" modules (e.g. Yama) and then the one "major" module (e.g. SELinux) if there is one configured. +Process attributes associated with "major" security modules should +be accessed and maintained using the special files in ``/proc/.../attr``. +A security module may maintain a module specific subdirectory there, +named after the module. ``/proc/.../attr/smack`` is provided by the Smack +security module and contains all its special files. The files directly +in ``/proc/.../attr`` remain as legacy interfaces for modules that provide +subdirectories. + .. toctree:: :maxdepth: 1 @@ -39,3 +46,4 @@ the one "major" module (e.g. SELinux) if there is one configured. Smack tomoyo Yama + SafeSetID diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 0797eec76be1..47e577264198 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -1,9 +1,9 @@ .. _readme: -Linux kernel release 4.x <http://kernel.org/> +Linux kernel release 5.x <http://kernel.org/> ============================================= -These are the release notes for Linux version 4. Read them carefully, +These are the release notes for Linux version 5. Read them carefully, as they tell you what this is all about, explain how to install the kernel, and what to do if something goes wrong. @@ -63,7 +63,7 @@ Installing the kernel source directory where you have permissions (e.g. your home directory) and unpack it:: - xz -cd linux-4.X.tar.xz | tar xvf - + xz -cd linux-5.x.tar.xz | tar xvf - Replace "X" with the version number of the latest kernel. @@ -72,26 +72,26 @@ Installing the kernel source files. They should match the library, and not get messed up by whatever the kernel-du-jour happens to be. - - You can also upgrade between 4.x releases by patching. Patches are + - You can also upgrade between 5.x releases by patching. Patches are distributed in the xz format. To install by patching, get all the newer patch files, enter the top level directory of the kernel source - (linux-4.X) and execute:: + (linux-5.x) and execute:: - xz -cd ../patch-4.x.xz | patch -p1 + xz -cd ../patch-5.x.xz | patch -p1 - Replace "x" for all versions bigger than the version "X" of your current + Replace "x" for all versions bigger than the version "x" of your current source tree, **in_order**, and you should be ok. You may want to remove the backup files (some-file-name~ or some-file-name.orig), and make sure that there are no failed patches (some-file-name# or some-file-name.rej). If there are, either you or I have made a mistake. - Unlike patches for the 4.x kernels, patches for the 4.x.y kernels + Unlike patches for the 5.x kernels, patches for the 5.x.y kernels (also known as the -stable kernels) are not incremental but instead apply - directly to the base 4.x kernel. For example, if your base kernel is 4.0 - and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 - and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and - want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, - patch -R) **before** applying the 4.0.3 patch. You can read more on this in + directly to the base 5.x kernel. For example, if your base kernel is 5.0 + and you want to apply the 5.0.3 patch, you must not first apply the 5.0.1 + and 5.0.2 patches. Similarly, if you are running kernel version 5.0.2 and + want to jump to 5.0.3, you must first reverse the 5.0.2 patch (that is, + patch -R) **before** applying the 5.0.3 patch. You can read more on this in :ref:`Documentation/process/applying-patches.rst <applying_patches>`. Alternatively, the script patch-kernel can be used to automate this @@ -114,7 +114,7 @@ Installing the kernel source Software requirements --------------------- - Compiling and running the 4.x kernels requires up-to-date + Compiling and running the 5.x kernels requires up-to-date versions of various software packages. Consult :ref:`Documentation/process/changes.rst <changes>` for the minimum version numbers required and how to get updates for these packages. Beware that using @@ -132,12 +132,12 @@ Build directory for the kernel place for the output files (including .config). Example:: - kernel source code: /usr/src/linux-4.X + kernel source code: /usr/src/linux-5.x build directory: /home/name/build/kernel To configure and build the kernel, use:: - cd /usr/src/linux-4.X + cd /usr/src/linux-5.x make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index caf36105a1c7..20f92c16ffbf 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -56,11 +56,13 @@ v1 is available under Documentation/cgroup-v1/. 5-3-3-2. IO Latency Interface Files 5-4. PID 5-4-1. PID Interface Files - 5-5. Device - 5-6. RDMA - 5-6-1. RDMA Interface Files - 5-7. Misc - 5-7-1. perf_event + 5-5. Cpuset + 5.5-1. Cpuset Interface Files + 5-6. Device + 5-7. RDMA + 5-7-1. RDMA Interface Files + 5-8. Misc + 5-8-1. perf_event 5-N. Non-normative information 5-N-1. CPU controller root cgroup process behaviour 5-N-2. IO controller root cgroup process behaviour @@ -966,6 +968,12 @@ All time durations are in microseconds. $PERIOD duration. "max" for $MAX indicates no limit. If only one number is written, $MAX is updated. + cpu.pressure + A read-only nested-key file which exists on non-root cgroups. + + Shows pressure stall information for CPU. See + Documentation/accounting/psi.txt for details. + Memory ------ @@ -1127,6 +1135,10 @@ PAGE_SIZE multiple when read back. disk readahead. For now OOM in memory cgroup kills tasks iff shortage has happened inside page fault. + This event is not raised if the OOM killer is not + considered as an option, e.g. for failed high-order + allocations. + oom_kill The number of processes belonging to this cgroup killed by any kind of OOM killer. @@ -1177,6 +1189,10 @@ PAGE_SIZE multiple when read back. Amount of cached filesystem data that was modified and is currently being written back to disk + anon_thp + Amount of memory used in anonymous mappings backed by + transparent hugepages + inactive_anon, active_anon, inactive_file, active_file, unevictable Amount of memory, swap-backed and filesystem-backed, on the internal memory management lists used by the @@ -1236,6 +1252,18 @@ PAGE_SIZE multiple when read back. Amount of reclaimed lazyfree pages + thp_fault_alloc + + Number of transparent hugepages which were allocated to satisfy + a page fault, including COW faults. This counter is not present + when CONFIG_TRANSPARENT_HUGEPAGE is not set. + + thp_collapse_alloc + + Number of transparent hugepages which were allocated to allow + collapsing an existing range of pages. This counter is not + present when CONFIG_TRANSPARENT_HUGEPAGE is not set. + memory.swap.current A read-only single value file which exists on non-root cgroups. @@ -1271,6 +1299,12 @@ PAGE_SIZE multiple when read back. higher than the limit for an extended period of time. This reduces the impact on the workload and memory management. + memory.pressure + A read-only nested-key file which exists on non-root cgroups. + + Shows pressure stall information for memory. See + Documentation/accounting/psi.txt for details. + Usage Guidelines ~~~~~~~~~~~~~~~~ @@ -1408,6 +1442,12 @@ IO Interface Files 8:16 rbps=2097152 wbps=max riops=max wiops=max + io.pressure + A read-only nested-key file which exists on non-root cgroups. + + Shows pressure stall information for IO. See + Documentation/accounting/psi.txt for details. + Writeback ~~~~~~~~~ @@ -1479,7 +1519,7 @@ protected workload. The limits are only applied at the peer level in the hierarchy. This means that in the diagram below, only groups A, B, and C will influence each other, and -groups D and F will influence each other. Group G will influence nobody. +groups D and F will influence each other. Group G will influence nobody:: [root] / | \ @@ -1588,6 +1628,176 @@ through fork() or clone(). These will return -EAGAIN if the creation of a new process would cause a cgroup policy to be violated. +Cpuset +------ + +The "cpuset" controller provides a mechanism for constraining +the CPU and memory node placement of tasks to only the resources +specified in the cpuset interface files in a task's current cgroup. +This is especially valuable on large NUMA systems where placing jobs +on properly sized subsets of the systems with careful processor and +memory placement to reduce cross-node memory access and contention +can improve overall system performance. + +The "cpuset" controller is hierarchical. That means the controller +cannot use CPUs or memory nodes not allowed in its parent. + + +Cpuset Interface Files +~~~~~~~~~~~~~~~~~~~~~~ + + cpuset.cpus + A read-write multiple values file which exists on non-root + cpuset-enabled cgroups. + + It lists the requested CPUs to be used by tasks within this + cgroup. The actual list of CPUs to be granted, however, is + subjected to constraints imposed by its parent and can differ + from the requested CPUs. + + The CPU numbers are comma-separated numbers or ranges. + For example: + + # cat cpuset.cpus + 0-4,6,8-10 + + An empty value indicates that the cgroup is using the same + setting as the nearest cgroup ancestor with a non-empty + "cpuset.cpus" or all the available CPUs if none is found. + + The value of "cpuset.cpus" stays constant until the next update + and won't be affected by any CPU hotplug events. + + cpuset.cpus.effective + A read-only multiple values file which exists on all + cpuset-enabled cgroups. + + It lists the onlined CPUs that are actually granted to this + cgroup by its parent. These CPUs are allowed to be used by + tasks within the current cgroup. + + If "cpuset.cpus" is empty, the "cpuset.cpus.effective" file shows + all the CPUs from the parent cgroup that can be available to + be used by this cgroup. Otherwise, it should be a subset of + "cpuset.cpus" unless none of the CPUs listed in "cpuset.cpus" + can be granted. In this case, it will be treated just like an + empty "cpuset.cpus". + + Its value will be affected by CPU hotplug events. + + cpuset.mems + A read-write multiple values file which exists on non-root + cpuset-enabled cgroups. + + It lists the requested memory nodes to be used by tasks within + this cgroup. The actual list of memory nodes granted, however, + is subjected to constraints imposed by its parent and can differ + from the requested memory nodes. + + The memory node numbers are comma-separated numbers or ranges. + For example: + + # cat cpuset.mems + 0-1,3 + + An empty value indicates that the cgroup is using the same + setting as the nearest cgroup ancestor with a non-empty + "cpuset.mems" or all the available memory nodes if none + is found. + + The value of "cpuset.mems" stays constant until the next update + and won't be affected by any memory nodes hotplug events. + + cpuset.mems.effective + A read-only multiple values file which exists on all + cpuset-enabled cgroups. + + It lists the onlined memory nodes that are actually granted to + this cgroup by its parent. These memory nodes are allowed to + be used by tasks within the current cgroup. + + If "cpuset.mems" is empty, it shows all the memory nodes from the + parent cgroup that will be available to be used by this cgroup. + Otherwise, it should be a subset of "cpuset.mems" unless none of + the memory nodes listed in "cpuset.mems" can be granted. In this + case, it will be treated just like an empty "cpuset.mems". + + Its value will be affected by memory nodes hotplug events. + + cpuset.cpus.partition + A read-write single value file which exists on non-root + cpuset-enabled cgroups. This flag is owned by the parent cgroup + and is not delegatable. + + It accepts only the following input values when written to. + + "root" - a paritition root + "member" - a non-root member of a partition + + When set to be a partition root, the current cgroup is the + root of a new partition or scheduling domain that comprises + itself and all its descendants except those that are separate + partition roots themselves and their descendants. The root + cgroup is always a partition root. + + There are constraints on where a partition root can be set. + It can only be set in a cgroup if all the following conditions + are true. + + 1) The "cpuset.cpus" is not empty and the list of CPUs are + exclusive, i.e. they are not shared by any of its siblings. + 2) The parent cgroup is a partition root. + 3) The "cpuset.cpus" is also a proper subset of the parent's + "cpuset.cpus.effective". + 4) There is no child cgroups with cpuset enabled. This is for + eliminating corner cases that have to be handled if such a + condition is allowed. + + Setting it to partition root will take the CPUs away from the + effective CPUs of the parent cgroup. Once it is set, this + file cannot be reverted back to "member" if there are any child + cgroups with cpuset enabled. + + A parent partition cannot distribute all its CPUs to its + child partitions. There must be at least one cpu left in the + parent partition. + + Once becoming a partition root, changes to "cpuset.cpus" is + generally allowed as long as the first condition above is true, + the change will not take away all the CPUs from the parent + partition and the new "cpuset.cpus" value is a superset of its + children's "cpuset.cpus" values. + + Sometimes, external factors like changes to ancestors' + "cpuset.cpus" or cpu hotplug can cause the state of the partition + root to change. On read, the "cpuset.sched.partition" file + can show the following values. + + "member" Non-root member of a partition + "root" Partition root + "root invalid" Invalid partition root + + It is a partition root if the first 2 partition root conditions + above are true and at least one CPU from "cpuset.cpus" is + granted by the parent cgroup. + + A partition root can become invalid if none of CPUs requested + in "cpuset.cpus" can be granted by the parent cgroup or the + parent cgroup is no longer a partition root itself. In this + case, it is not a real partition even though the restriction + of the first partition root condition above will still apply. + The cpu affinity of all the tasks in the cgroup will then be + associated with CPUs in the nearest ancestor partition. + + An invalid partition root can be transitioned back to a + real partition root if at least one of the requested CPUs + can now be granted by its parent. In this case, the cpu + affinity of all the tasks in the formerly invalid partition + will be associated to the CPUs of the newly formed partition. + Changing the partition state of an invalid partition root to + "member" is always allowed even if child cpusets are present. + + Device controller ----------------- @@ -1879,7 +2089,7 @@ the configuration, the bio may be executed at a lower priority and if the writeback session is holding shared resources, e.g. a journal entry, may lead to priority inversion. There is no one easy solution for the problem. Filesystems can try to work around specific problem -cases by skipping wbc_init_bio() or using bio_associate_create_blkg() +cases by skipping wbc_init_bio() and using bio_associate_blkg() directly. diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index 7fadc05330dd..d41671aeaef0 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -1,3 +1,4 @@ +.. _admin_devices: Linux allocated devices (4.x+ version) ====================================== diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst index fdf72429f801..252e5ef324e5 100644 --- a/Documentation/admin-guide/dynamic-debug-howto.rst +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -110,8 +110,8 @@ If your query set is big, you can batch them too:: ~# cat query-batch-file > <debugfs>/dynamic_debug/control -A another way is to use wildcard. The match rule support ``*`` (matches -zero or more characters) and ``?`` (matches exactly one character).For +Another way is to use wildcards. The match rule supports ``*`` (matches +zero or more characters) and ``?`` (matches exactly one character). For example, you can match all usb drivers:: ~# echo "file drivers/usb/* +p" > <debugfs>/dynamic_debug/control @@ -258,7 +258,7 @@ this boot parameter for debugging purposes. If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at boot time, without effect, but will be reprocessed when module is -loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at +loaded later. ``ddebug_query=`` and bare ``dyndbg=`` are only processed at boot. @@ -301,7 +301,7 @@ The ``dyndbg`` option is a "fake" module parameter, which means: For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or enabled by ``-DDEBUG`` flag during compilation) can be disabled later via -the sysfs interface if the debug messages are no longer needed:: +the debugfs interface if the debug messages are no longer needed:: echo "module module_name -p" > <debugfs>/dynamic_debug/control diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 965745d5fb9a..0a491676685e 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -76,6 +76,7 @@ configure specific aspects of kernel behavior to your liking. thunderbolt LSM/index mm/index + perf-security .. only:: subproject and html diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index e129cd8a6dcc..42379633801f 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -331,7 +331,7 @@ APC and your system crashes randomly. apic= [APIC,X86] Advanced Programmable Interrupt Controller - Change the output verbosity whilst booting + Change the output verbosity while booting Format: { quiet (default) | verbose | debug } Change the amount of debugging information output when initialising the APIC and IO-APIC components. @@ -461,6 +461,11 @@ possible to determine what the correct size should be. This option provides an override for these situations. + carrier_timeout= + [NET] Specifies amount of time (in seconds) that + the kernel should wait for a network carrier. By default + it waits 120 seconds. + ca_keys= [KEYS] This parameter identifies a specific key(s) on the system trusted keyring to be used for certificate trust validation. @@ -486,10 +491,14 @@ cut the overhead, others just disable the usage. So only cgroup_disable=memory is actually worthy} - cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 - Format: { controller[,controller...] | "all" } + cgroup_no_v1= [KNL] Disable cgroup controllers and named hierarchies in v1 + Format: { { controller | "all" | "named" } + [,{ controller | "all" | "named" }...] } Like cgroup_disable, but only applies to cgroup v1; the blacklisted controllers remain available in cgroup2. + "all" blacklists all controllers and "named" disables + named mounts. Specifying both "all" and "named" disables + all v1 hierarchies. cgroup.memory= [KNL] Pass options to the cgroup memory controller. Format: <string> @@ -674,6 +683,9 @@ cpuidle.off=1 [CPU_IDLE] disable the cpuidle sub-system + cpuidle.governor= + [CPU_IDLE] Name of the cpuidle governor to use. + cpufreq.off=1 [CPU_FREQ] disable the cpufreq sub-system @@ -856,7 +868,8 @@ causing system reset or hang due to sending INIT from AP to BSP. - disable_counter_freezing [HW] + perf_v4_pmi= [X86,INTEL] + Format: <bool> Disable Intel PMU counter freezing feature. The feature only exists starting from Arch Perfmon v4 (Skylake and newer). @@ -902,6 +915,10 @@ The filter can be disabled or changed to another driver later using sysfs. + driver_async_probe= [KNL] + List of driver names to be probed asynchronously. + Format: <driver_name1>,<driver_name2>... + drm.edid_firmware=[<connector>:]<file>[,[<connector>:]<file>] Broken monitors, graphic adapters, KVMs and EDIDless panels may send no or incorrect EDID data sets. @@ -1020,6 +1037,12 @@ specified address. The serial port must already be setup and configured. Options are not yet supported. + rda,<addr> + Start an early, polled-mode console on a serial port + of an RDA Micro SoC, such as RDA8810PL, at the + specified address. The serial port must already be + setup and configured. Options are not yet supported. + smh Use ARM semihosting calls for early console. s3c2410,<addr> @@ -1059,16 +1082,22 @@ specified address. The serial port must already be setup and configured. Options are not yet supported. + efifb,[options] + Start an early, unaccelerated console on the EFI + memory mapped framebuffer (if available). On cache + coherent non-x86 systems that use system memory for + the framebuffer, pass the 'ram' option so that it is + mapped with the correct attributes. + earlyprintk= [X86,SH,ARM,M68k,S390] earlyprintk=vga - earlyprintk=efi earlyprintk=sclp earlyprintk=xen earlyprintk=serial[,ttySn[,baudrate]] earlyprintk=serial[,0x...[,baudrate]] earlyprintk=ttySn[,baudrate] earlyprintk=dbgp[debugController#] - earlyprintk=pciserial,bus:device.function[,baudrate] + earlyprintk=pciserial[,force],bus:device.function[,baudrate] earlyprintk=xdbc[xhciController#] earlyprintk is useful when the kernel crashes before @@ -1100,6 +1129,10 @@ The sclp output can only be used on s390. + The optional "force" to "pciserial" enables use of a + PCI device even when its classcode is not of the + UART class. + 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 @@ -1678,12 +1711,11 @@ By default, super page will be supported if Intel IOMMU has the capability. With this option, super page will not be supported. - ecs_off [Default Off] - By default, extended context tables will be supported if - the hardware advertises that it has support both for the - extended tables themselves, and also PASID support. With - this option set, extended tables will not be used even - on hardware which claims to support them. + sm_on [Default Off] + By default, scalable mode will be disabled even if the + hardware advertises that it has support for the scalable + mode translation. With this option set, scalable mode + will be used on hardware which claims to support it. tboot_noforce [Default Off] Do not force the Intel IOMMU enabled under tboot. By default, tboot will force Intel IOMMU on, which @@ -1759,6 +1791,18 @@ nobypass [PPC/POWERNV] Disable IOMMU bypass, using IOMMU for PCI devices. + iommu.strict= [ARM64] Configure TLB invalidation behaviour + Format: { "0" | "1" } + 0 - Lazy mode. + Request that DMA unmap operations use deferred + invalidation of hardware TLBs, for increased + throughput at the cost of reduced device isolation. + Will fall back to strict mode if not supported by + the relevant IOMMU driver. + 1 - Strict mode (default). + DMA unmap operations invalidate IOMMU hardware TLBs + synchronously. + iommu.passthrough= [ARM64] Configure DMA to bypass the IOMMU by default. Format: { "0" | "1" } @@ -2079,6 +2123,9 @@ off Disables hypervisor mitigations and doesn't emit any warnings. + It also drops the swap size and available + RAM limit restriction on both hypervisor and + bare metal. Default is 'flush'. @@ -2286,6 +2333,10 @@ lsm.debug [SECURITY] Enable LSM initialization debugging output. + lsm=lsm1,...,lsmN + [SECURITY] Choose order of LSM initialization. This + overrides CONFIG_LSM, and the "security=" parameter. + machvec= [IA-64] Force the use of a particular machine-vector (machvec) in a generic kernel. Example: machvec=hpzx1_swiotlb @@ -2416,7 +2467,7 @@ seconds. Use this parameter to check at some other rate. 0 disables periodic checking. - memtest= [KNL,X86,ARM] Enable memtest + memtest= [KNL,X86,ARM,PPC] Enable memtest Format: <integer> default : 0 <disable> Specifies the number of memtest passes to be @@ -2810,7 +2861,7 @@ check bypass). With this option data leaks are possible in the system. - nospectre_v2 [X86] Disable all mitigations for the Spectre variant 2 + nospectre_v2 [X86,PPC_FSL_BOOK3E] Disable all mitigations for the Spectre variant 2 (indirect branch prediction) vulnerability. System may allow data leaks with this option, which is equivalent to spectre_v2=off. @@ -3065,6 +3116,14 @@ timeout < 0: reboot immediately Format: <timeout> + panic_print= Bitmask for printing system info when panic happens. + User can chose combination of the following bits: + bit 0: print all tasks info + bit 1: print system memory info + bit 2: print timer info + bit 3: print locks info if CONFIG_LOCKDEP is on + bit 4: print ftrace buffer + panic_on_warn panic() instead of WARN(). Useful to cause kdump on a WARN(). @@ -3488,6 +3547,10 @@ before loading. See Documentation/blockdev/ramdisk.txt. + psi= [KNL] Enable or disable pressure stall information + tracking. + Format: <bool> + psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to probe for; one of (bare|imps|exps|lifebook|any). psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports @@ -3609,19 +3672,6 @@ latencies, which will choose a value aligned with the appropriate hardware boundaries. - rcutree.jiffies_till_sched_qs= [KNL] - Set required age in jiffies for a - given grace period before RCU starts - soliciting quiescent-state help from - rcu_note_context_switch(). If not specified, the - kernel will calculate a value based on the most - recent settings of rcutree.jiffies_till_first_fqs - and rcutree.jiffies_till_next_fqs. - This calculated value may be viewed in - rcutree.jiffies_to_sched_qs. Any attempt to - set rcutree.jiffies_to_sched_qs will be - cheerfully overwritten. - rcutree.jiffies_till_first_fqs= [KNL] Set delay from grace-period initialization to first attempt to force quiescent states. @@ -3633,6 +3683,20 @@ quiescent states. Units are jiffies, minimum value is one, and maximum value is HZ. + rcutree.jiffies_till_sched_qs= [KNL] + Set required age in jiffies for a + given grace period before RCU starts + soliciting quiescent-state help from + rcu_note_context_switch() and cond_resched(). + If not specified, the kernel will calculate + a value based on the most recent settings + of rcutree.jiffies_till_first_fqs + and rcutree.jiffies_till_next_fqs. + This calculated value may be viewed in + rcutree.jiffies_to_sched_qs. Any attempt to set + rcutree.jiffies_to_sched_qs will be cheerfully + overwritten. + rcutree.kthread_prio= [KNL,BOOT] Set the SCHED_FIFO priority of the RCU per-CPU kthreads (rcuc/N). This value is also used for @@ -3676,6 +3740,11 @@ This wake_up() will be accompanied by a WARN_ONCE() splat and an ftrace_dump(). + rcutree.sysrq_rcu= [KNL] + Commandeer a sysrq key to dump out Tree RCU's + rcu_node tree with an eye towards determining + why a new grace period has not yet started. + rcuperf.gp_async= [KNL] Measure performance of asynchronous grace-period primitives such as call_rcu(). @@ -3727,24 +3796,6 @@ in microseconds. The default of zero says no holdoff. - rcutorture.cbflood_inter_holdoff= [KNL] - Set holdoff time (jiffies) between successive - callback-flood tests. - - rcutorture.cbflood_intra_holdoff= [KNL] - Set holdoff time (jiffies) between successive - bursts of callbacks within a given callback-flood - test. - - rcutorture.cbflood_n_burst= [KNL] - Set the number of bursts making up a given - callback-flood test. Set this to zero to - disable callback-flood testing. - - rcutorture.cbflood_n_per_burst= [KNL] - Set the number of callbacks to be registered - in a given burst of a callback-flood test. - rcutorture.fqs_duration= [KNL] Set duration of force_quiescent_state bursts in microseconds. @@ -3757,6 +3808,23 @@ Set wait time between force_quiescent_state bursts in seconds. + rcutorture.fwd_progress= [KNL] + Enable RCU grace-period forward-progress testing + for the types of RCU supporting this notion. + + rcutorture.fwd_progress_div= [KNL] + Specify the fraction of a CPU-stall-warning + period to do tight-loop forward-progress testing. + + rcutorture.fwd_progress_holdoff= [KNL] + Number of seconds to wait between successive + forward-progress tests. + + rcutorture.fwd_progress_need_resched= [KNL] + Enclose cond_resched() calls within checks for + need_resched() during tight-loop forward-progress + testing. + rcutorture.gp_cond= [KNL] Use conditional/asynchronous update-side primitives, if available. @@ -4046,11 +4114,9 @@ Note: increases power consumption, thus should only be enabled if running jitter sensitive (HPC/RT) workloads. - security= [SECURITY] Choose a security module to enable at boot. - If this boot parameter is not specified, only the first - security module asking for security registration will be - loaded. An invalid security module name will be treated - as if no module has been chosen. + security= [SECURITY] Choose a legacy "major" security module to + enable at boot. This has been deprecated by the + "lsm=" parameter. selinux= [SELINUX] Disable or enable SELinux at boot time. Format: { "0" | "1" } @@ -4178,9 +4244,13 @@ spectre_v2= [X86] Control mitigation of Spectre variant 2 (indirect branch speculation) vulnerability. + The default operation protects the kernel from + user space attacks. - on - unconditionally enable - off - unconditionally disable + on - unconditionally enable, implies + spectre_v2_user=on + off - unconditionally disable, implies + spectre_v2_user=off auto - kernel detects whether your CPU model is vulnerable @@ -4190,6 +4260,12 @@ CONFIG_RETPOLINE configuration option, and the compiler with which the kernel was built. + Selecting 'on' will also enable the mitigation + against user space to user space task attacks. + + Selecting 'off' will disable both the kernel and + the user space protections. + Specific mitigations can also be selected manually: retpoline - replace indirect branches @@ -4199,6 +4275,48 @@ Not specifying this option is equivalent to spectre_v2=auto. + spectre_v2_user= + [X86] Control mitigation of Spectre variant 2 + (indirect branch speculation) vulnerability between + user space tasks + + on - Unconditionally enable mitigations. Is + enforced by spectre_v2=on + + off - Unconditionally disable mitigations. Is + enforced by spectre_v2=off + + prctl - Indirect branch speculation is enabled, + but mitigation can be enabled via prctl + per thread. The mitigation control state + is inherited on fork. + + prctl,ibpb + - Like "prctl" above, but only STIBP is + controlled per thread. IBPB is issued + always when switching between different user + space processes. + + seccomp + - Same as "prctl" above, but all seccomp + threads will enable the mitigation unless + they explicitly opt out. + + seccomp,ibpb + - Like "seccomp" above, but only STIBP is + controlled per thread. IBPB is issued + always when switching between different + user space processes. + + auto - Kernel selects the mitigation depending on + the available CPU features and vulnerability. + + Default mitigation: + If CONFIG_SECCOMP=y then "seccomp", otherwise "prctl" + + Not specifying this option is equivalent to + spectre_v2_user=auto. + spec_store_bypass_disable= [HW] Control Speculative Store Bypass (SSB) Disable mitigation (Speculative Store Bypass vulnerability) @@ -4602,7 +4720,8 @@ usbcore.authorized_default= [USB] Default USB device authorization: (default -1 = authorized except for wireless USB, - 0 = not authorized, 1 = authorized) + 0 = not authorized, 1 = authorized, 2 = authorized + if device connected to internal port) usbcore.autosuspend= [USB] The autosuspend time delay (in seconds) used @@ -4623,7 +4742,8 @@ usbcore.old_scheme_first= [USB] Start with the old device initialization - scheme (default 0 = off). + scheme, applies only to low and full-speed devices + (default 0 = off). usbcore.usbfs_memory_mb= [USB] Memory limit (in MB) for buffers allocated by @@ -4696,6 +4816,8 @@ prevent spurious wakeup); n = USB_QUIRK_DELAY_CTRL_MSG (Device needs a pause after every control message); + o = USB_QUIRK_HUB_SLOW_RESET (Hub needs extra + delay after resetting its port); Example: quirks=0781:5580:bk,0a5c:5834:gij usbhid.mousepoll= @@ -4838,6 +4960,18 @@ This is actually a boot loader parameter; the value is passed to the kernel using a special protocol. + vm_debug[=options] [KNL] Available with CONFIG_DEBUG_VM=y. + May slow down system boot speed, especially when + enabled on systems with a large amount of memory. + All options are enabled by default, and this + interface is meant to allow for selectively + enabling or disabling specific virtual memory + debugging features. + + Available options are: + P Enable page structure init time poisoning + - Disable all of the above options + vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact size of <nn>. This can be used to increase the minimum size (128MB on x86). It can also be used to diff --git a/Documentation/admin-guide/l1tf.rst b/Documentation/admin-guide/l1tf.rst index b85dd80510b0..9af977384168 100644 --- a/Documentation/admin-guide/l1tf.rst +++ b/Documentation/admin-guide/l1tf.rst @@ -405,6 +405,9 @@ time with the option "l1tf=". The valid arguments for this option are: off Disables hypervisor mitigations and doesn't emit any warnings. + It also drops the swap size and available RAM limit restrictions + on both hypervisor and bare metal. + ============ ============================================================= The default is 'flush'. For details about L1D flushing see :ref:`l1d_flush`. @@ -576,7 +579,8 @@ Default mitigations The kernel default mitigations for vulnerable processors are: - PTE inversion to protect against malicious user space. This is done - unconditionally and cannot be controlled. + unconditionally and cannot be controlled. The swap storage is limited + to ~16TB. - L1D conditional flushing on VMENTER when EPT is enabled for a guest. diff --git a/Documentation/admin-guide/mm/concepts.rst b/Documentation/admin-guide/mm/concepts.rst index 291699c810d4..c2531b14bf46 100644 --- a/Documentation/admin-guide/mm/concepts.rst +++ b/Documentation/admin-guide/mm/concepts.rst @@ -4,13 +4,13 @@ Concepts overview ================= -The memory management in Linux is complex system that evolved over the -years and included more and more functionality to support variety of +The memory management in Linux is a complex system that evolved over the +years and included more and more functionality to support a variety of systems from MMU-less microcontrollers to supercomputers. The memory -management for systems without MMU is called ``nommu`` and it +management for systems without an MMU is called ``nommu`` and it definitely deserves a dedicated document, which hopefully will be eventually written. Yet, although some of the concepts are the same, -here we assume that MMU is available and CPU can translate a virtual +here we assume that an MMU is available and a CPU can translate a virtual address to a physical address. .. contents:: :local: @@ -21,10 +21,10 @@ Virtual Memory Primer The physical memory in a computer system is a limited resource and even for systems that support memory hotplug there is a hard limit on the amount of memory that can be installed. The physical memory is not -necessary contiguous, it might be accessible as a set of distinct +necessarily contiguous; it might be accessible as a set of distinct address ranges. Besides, different CPU architectures, and even -different implementations of the same architecture have different view -how these address ranges defined. +different implementations of the same architecture have different views +of how these address ranges are defined. All this makes dealing directly with physical memory quite complex and to avoid this complexity a concept of virtual memory was developed. @@ -48,8 +48,8 @@ appropriate kernel configuration option. Each physical memory page can be mapped as one or more virtual pages. These mappings are described by page tables that allow -translation from virtual address used by programs to real address in -the physical memory. The page tables organized hierarchically. +translation from a virtual address used by programs to the physical +memory address. The page tables are organized hierarchically. The tables at the lowest level of the hierarchy contain physical addresses of actual pages used by the software. The tables at higher @@ -121,8 +121,8 @@ Nodes Many multi-processor machines are NUMA - Non-Uniform Memory Access - systems. In such systems the memory is arranged into banks that have different access latency depending on the "distance" from the -processor. Each bank is referred as `node` and for each node Linux -constructs an independent memory management subsystem. A node has it's +processor. Each bank is referred to as a `node` and for each node Linux +constructs an independent memory management subsystem. A node has its own set of zones, lists of free and used pages and various statistics counters. You can find more details about NUMA in :ref:`Documentation/vm/numa.rst <numa>` and in @@ -149,9 +149,9 @@ for program's stack and heap or by explicit calls to mmap(2) system call. Usually, the anonymous mappings only define virtual memory areas that the program is allowed to access. The read accesses will result in creation of a page table entry that references a special physical -page filled with zeroes. When the program performs a write, regular +page filled with zeroes. When the program performs a write, a regular physical page will be allocated to hold the written data. The page -will be marked dirty and if the kernel will decide to repurpose it, +will be marked dirty and if the kernel decides to repurpose it, the dirty page will be swapped out. Reclaim @@ -181,8 +181,8 @@ pressure. The process of freeing the reclaimable physical memory pages and repurposing them is called (surprise!) `reclaim`. Linux can reclaim pages either asynchronously or synchronously, depending on the state -of the system. When system is not loaded, most of the memory is free -and allocation request will be satisfied immediately from the free +of the system. When the system is not loaded, most of the memory is free +and allocation requests will be satisfied immediately from the free pages supply. As the load increases, the amount of the free pages goes down and when it reaches a certain threshold (high watermark), an allocation request will awaken the ``kswapd`` daemon. It will @@ -190,7 +190,7 @@ asynchronously scan memory pages and either just free them if the data they contain is available elsewhere, or evict to the backing storage device (remember those dirty pages?). As memory usage increases even more and reaches another threshold - min watermark - an allocation -will trigger the `direct reclaim`. In this case allocation is stalled +will trigger `direct reclaim`. In this case allocation is stalled until enough memory pages are reclaimed to satisfy the request. Compaction @@ -200,7 +200,7 @@ As the system runs, tasks allocate and free the memory and it becomes fragmented. Although with virtual memory it is possible to present scattered physical pages as virtually contiguous range, sometimes it is necessary to allocate large physically contiguous memory areas. Such -need may arise, for instance, when a device driver requires large +need may arise, for instance, when a device driver requires a large buffer for DMA, or when THP allocates a huge page. Memory `compaction` addresses the fragmentation issue. This mechanism moves occupied pages from the lower part of a memory zone to free pages in the upper part @@ -208,15 +208,16 @@ of the zone. When a compaction scan is finished free pages are grouped together at the beginning of the zone and allocations of large physically contiguous areas become possible. -Like reclaim, the compaction may happen asynchronously in ``kcompactd`` -daemon or synchronously as a result of memory allocation request. +Like reclaim, the compaction may happen asynchronously in the ``kcompactd`` +daemon or synchronously as a result of a memory allocation request. OOM killer ========== -It may happen, that on a loaded machine memory will be exhausted. When -the kernel detects that the system runs out of memory (OOM) it invokes -`OOM killer`. Its mission is simple: all it has to do is to select a -task to sacrifice for the sake of the overall system health. The -selected task is killed in a hope that after it exits enough memory -will be freed to continue normal operation. +It is possible that on a loaded machine memory will be exhausted and the +kernel will be unable to reclaim enough memory to continue to operate. In +order to save the rest of the system, it invokes the `OOM killer`. + +The `OOM killer` selects a task to sacrifice for the sake of the overall +system health. The selected task is killed in a hope that after it exits +enough memory will be freed to continue normal operation. diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index 25157aec5b31..5c4432c96c4b 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -5,7 +5,7 @@ Memory Hotplug ============== :Created: Jul 28 2007 -:Updated: Add description of notifier of memory hotplug: Oct 11 2007 +:Updated: Add some details about locking internals: Aug 20 2018 This document is about memory hotplug including how-to-use and current status. Because Memory Hotplug is still under development, contents of this text will @@ -392,6 +392,46 @@ Need more implementation yet.... - Notification completion of remove works by OS to firmware. - Guard from remove if not yet. + +Locking Internals +================= + +When adding/removing memory that uses memory block devices (i.e. ordinary RAM), +the device_hotplug_lock should be held to: + +- synchronize against online/offline requests (e.g. via sysfs). This way, memory + block devices can only be accessed (.online/.state attributes) by user + space once memory has been fully added. And when removing memory, we + know nobody is in critical sections. +- synchronize against CPU hotplug and similar (e.g. relevant for ACPI and PPC) + +Especially, there is a possible lock inversion that is avoided using +device_hotplug_lock when adding memory and user space tries to online that +memory faster than expected: + +- device_online() will first take the device_lock(), followed by + mem_hotplug_lock +- add_memory_resource() will first take the mem_hotplug_lock, followed by + the device_lock() (while creating the devices, during bus_add_device()). + +As the device is visible to user space before taking the device_lock(), this +can result in a lock inversion. + +onlining/offlining of memory should be done via device_online()/ +device_offline() - to make sure it is properly synchronized to actions +via sysfs. Holding device_hotplug_lock is advised (to e.g. protect online_type) + +When adding/removing/onlining/offlining memory or adding/removing +heterogeneous/device memory, we should always hold the mem_hotplug_lock in +write mode to serialise memory hotplug (e.g. access to global/zone +variables). + +In addition, mem_hotplug_lock (in contrast to device_hotplug_lock) in read +mode allows for a quite efficient get_online_mems/put_online_mems +implementation, so code accessing memory can protect from that memory +vanishing. + + Future Work =========== diff --git a/Documentation/admin-guide/mm/pagemap.rst b/Documentation/admin-guide/mm/pagemap.rst index 3f7bade2c231..340a5aee9b80 100644 --- a/Documentation/admin-guide/mm/pagemap.rst +++ b/Documentation/admin-guide/mm/pagemap.rst @@ -75,9 +75,10 @@ number of times a page is mapped. 20. NOPAGE 21. KSM 22. THP - 23. BALLOON + 23. OFFLINE 24. ZERO_PAGE 25. IDLE + 26. PGTABLE * ``/proc/kpagecgroup``. This file contains a 64-bit inode number of the memory cgroup each page is charged to, indexed by PFN. Only available when @@ -118,8 +119,8 @@ Short descriptions to the page flags identical memory pages dynamically shared between one or more processes 22 - THP contiguous pages which construct transparent hugepages -23 - BALLOON - balloon compaction page +23 - OFFLINE + page is logically offline 24 - ZERO_PAGE zero page for pfn_zero or huge_zero page 25 - IDLE @@ -128,6 +129,8 @@ Short descriptions to the page flags Note that this flag may be stale in case the page was accessed via a PTE. To make sure the flag is up-to-date one has to read ``/sys/kernel/mm/page_idle/bitmap`` first. +26 - PGTABLE + page is in use as a page table IO related page flags --------------------- diff --git a/Documentation/admin-guide/perf-security.rst b/Documentation/admin-guide/perf-security.rst new file mode 100644 index 000000000000..f73ebfe9bfe2 --- /dev/null +++ b/Documentation/admin-guide/perf-security.rst @@ -0,0 +1,97 @@ +.. _perf_security: + +Perf Events and tool security +============================= + +Overview +-------- + +Usage of Performance Counters for Linux (perf_events) [1]_ , [2]_ , [3]_ can +impose a considerable risk of leaking sensitive data accessed by monitored +processes. The data leakage is possible both in scenarios of direct usage of +perf_events system call API [2]_ and over data files generated by Perf tool user +mode utility (Perf) [3]_ , [4]_ . The risk depends on the nature of data that +perf_events performance monitoring units (PMU) [2]_ collect and expose for +performance analysis. Having that said perf_events/Perf performance monitoring +is the subject for security access control management [5]_ . + +perf_events/Perf access control +------------------------------- + +To perform security checks, the Linux implementation splits processes into two +categories [6]_ : a) privileged processes (whose effective user ID is 0, referred +to as superuser or root), and b) unprivileged processes (whose effective UID is +nonzero). Privileged processes bypass all kernel security permission checks so +perf_events performance monitoring is fully available to privileged processes +without access, scope and resource restrictions. + +Unprivileged processes are subject to a full security permission check based on +the process's credentials [5]_ (usually: effective UID, effective GID, and +supplementary group list). + +Linux divides the privileges traditionally associated with superuser into +distinct units, known as capabilities [6]_ , which can be independently enabled +and disabled on per-thread basis for processes and files of unprivileged users. + +Unprivileged processes with enabled CAP_SYS_ADMIN capability are treated as +privileged processes with respect to perf_events performance monitoring and +bypass *scope* permissions checks in the kernel. + +Unprivileged processes using perf_events system call API is also subject for +PTRACE_MODE_READ_REALCREDS ptrace access mode check [7]_ , whose outcome +determines whether monitoring is permitted. So unprivileged processes provided +with CAP_SYS_PTRACE capability are effectively permitted to pass the check. + +Other capabilities being granted to unprivileged processes can effectively +enable capturing of additional data required for later performance analysis of +monitored processes or a system. For example, CAP_SYSLOG capability permits +reading kernel space memory addresses from /proc/kallsyms file. + +perf_events/Perf unprivileged users +----------------------------------- + +perf_events/Perf *scope* and *access* control for unprivileged processes is +governed by perf_event_paranoid [2]_ setting: + +-1: + Impose no *scope* and *access* restrictions on using perf_events performance + monitoring. Per-user per-cpu perf_event_mlock_kb [2]_ locking limit is + ignored when allocating memory buffers for storing performance data. + This is the least secure mode since allowed monitored *scope* is + maximized and no perf_events specific limits are imposed on *resources* + allocated for performance monitoring. + +>=0: + *scope* includes per-process and system wide performance monitoring + but excludes raw tracepoints and ftrace function tracepoints monitoring. + CPU and system events happened when executing either in user or + in kernel space can be monitored and captured for later analysis. + Per-user per-cpu perf_event_mlock_kb locking limit is imposed but + ignored for unprivileged processes with CAP_IPC_LOCK [6]_ capability. + +>=1: + *scope* includes per-process performance monitoring only and excludes + system wide performance monitoring. CPU and system events happened when + executing either in user or in kernel space can be monitored and + captured for later analysis. Per-user per-cpu perf_event_mlock_kb + locking limit is imposed but ignored for unprivileged processes with + CAP_IPC_LOCK capability. + +>=2: + *scope* includes per-process performance monitoring only. CPU and system + events happened when executing in user space only can be monitored and + captured for later analysis. Per-user per-cpu perf_event_mlock_kb + locking limit is imposed but ignored for unprivileged processes with + CAP_IPC_LOCK capability. + +Bibliography +------------ + +.. [1] `<https://lwn.net/Articles/337493/>`_ +.. [2] `<http://man7.org/linux/man-pages/man2/perf_event_open.2.html>`_ +.. [3] `<http://web.eece.maine.edu/~vweaver/projects/perf_events/>`_ +.. [4] `<https://perf.wiki.kernel.org/index.php/Main_Page>`_ +.. [5] `<https://www.kernel.org/doc/html/latest/security/credentials.html>`_ +.. [6] `<http://man7.org/linux/man-pages/man7/capabilities.7.html>`_ +.. [7] `<http://man7.org/linux/man-pages/man2/ptrace.2.html>`_ + diff --git a/Documentation/admin-guide/pm/cpufreq.rst b/Documentation/admin-guide/pm/cpufreq.rst index 47153e64dfb5..7eca9026a9ed 100644 --- a/Documentation/admin-guide/pm/cpufreq.rst +++ b/Documentation/admin-guide/pm/cpufreq.rst @@ -150,7 +150,7 @@ data structures necessary to handle the given policy and, possibly, to add a governor ``sysfs`` interface to it. Next, the governor is started by invoking its ``->start()`` callback. -That callback it expected to register per-CPU utilization update callbacks for +That callback is expected to register per-CPU utilization update callbacks for all of the online CPUs belonging to the given policy with the CPU scheduler. The utilization update callbacks will be invoked by the CPU scheduler on important events, like task enqueue and dequeue, on every iteration of the diff --git a/Documentation/admin-guide/pm/cpuidle.rst b/Documentation/admin-guide/pm/cpuidle.rst new file mode 100644 index 000000000000..9c58b35a81cb --- /dev/null +++ b/Documentation/admin-guide/pm/cpuidle.rst @@ -0,0 +1,719 @@ +.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` +.. |cpufreq| replace:: :doc:`CPU Performance Scaling <cpufreq>` + +======================== +CPU Idle Time Management +======================== + +:: + + Copyright (c) 2018 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +Concepts +======== + +Modern processors are generally able to enter states in which the execution of +a program is suspended and instructions belonging to it are not fetched from +memory or executed. Those states are the *idle* states of the processor. + +Since part of the processor hardware is not used in idle states, entering them +generally allows power drawn by the processor to be reduced and, in consequence, +it is an opportunity to save energy. + +CPU idle time management is an energy-efficiency feature concerned about using +the idle states of processors for this purpose. + +Logical CPUs +------------ + +CPU idle time management operates on CPUs as seen by the *CPU scheduler* (that +is the part of the kernel responsible for the distribution of computational +work in the system). In its view, CPUs are *logical* units. That is, they need +not be separate physical entities and may just be interfaces appearing to +software as individual single-core processors. In other words, a CPU is an +entity which appears to be fetching instructions that belong to one sequence +(program) from memory and executing them, but it need not work this way +physically. Generally, three different cases can be consider here. + +First, if the whole processor can only follow one sequence of instructions (one +program) at a time, it is a CPU. In that case, if the hardware is asked to +enter an idle state, that applies to the processor as a whole. + +Second, if the processor is multi-core, each core in it is able to follow at +least one program at a time. The cores need not be entirely independent of each +other (for example, they may share caches), but still most of the time they +work physically in parallel with each other, so if each of them executes only +one program, those programs run mostly independently of each other at the same +time. The entire cores are CPUs in that case and if the hardware is asked to +enter an idle state, that applies to the core that asked for it in the first +place, but it also may apply to a larger unit (say a "package" or a "cluster") +that the core belongs to (in fact, it may apply to an entire hierarchy of larger +units containing the core). Namely, if all of the cores in the larger unit +except for one have been put into idle states at the "core level" and the +remaining core asks the processor to enter an idle state, that may trigger it +to put the whole larger unit into an idle state which also will affect the +other cores in that unit. + +Finally, each core in a multi-core processor may be able to follow more than one +program in the same time frame (that is, each core may be able to fetch +instructions from multiple locations in memory and execute them in the same time +frame, but not necessarily entirely in parallel with each other). In that case +the cores present themselves to software as "bundles" each consisting of +multiple individual single-core "processors", referred to as *hardware threads* +(or hyper-threads specifically on Intel hardware), that each can follow one +sequence of instructions. Then, the hardware threads are CPUs from the CPU idle +time management perspective and if the processor is asked to enter an idle state +by one of them, the hardware thread (or CPU) that asked for it is stopped, but +nothing more happens, unless all of the other hardware threads within the same +core also have asked the processor to enter an idle state. In that situation, +the core may be put into an idle state individually or a larger unit containing +it may be put into an idle state as a whole (if the other cores within the +larger unit are in idle states already). + +Idle CPUs +--------- + +Logical CPUs, simply referred to as "CPUs" in what follows, are regarded as +*idle* by the Linux kernel when there are no tasks to run on them except for the +special "idle" task. + +Tasks are the CPU scheduler's representation of work. Each task consists of a +sequence of instructions to execute, or code, data to be manipulated while +running that code, and some context information that needs to be loaded into the +processor every time the task's code is run by a CPU. The CPU scheduler +distributes work by assigning tasks to run to the CPUs present in the system. + +Tasks can be in various states. In particular, they are *runnable* if there are +no specific conditions preventing their code from being run by a CPU as long as +there is a CPU available for that (for example, they are not waiting for any +events to occur or similar). When a task becomes runnable, the CPU scheduler +assigns it to one of the available CPUs to run and if there are no more runnable +tasks assigned to it, the CPU will load the given task's context and run its +code (from the instruction following the last one executed so far, possibly by +another CPU). [If there are multiple runnable tasks assigned to one CPU +simultaneously, they will be subject to prioritization and time sharing in order +to allow them to make some progress over time.] + +The special "idle" task becomes runnable if there are no other runnable tasks +assigned to the given CPU and the CPU is then regarded as idle. In other words, +in Linux idle CPUs run the code of the "idle" task called *the idle loop*. That +code may cause the processor to be put into one of its idle states, if they are +supported, in order to save energy, but if the processor does not support any +idle states, or there is not enough time to spend in an idle state before the +next wakeup event, or there are strict latency constraints preventing any of the +available idle states from being used, the CPU will simply execute more or less +useless instructions in a loop until it is assigned a new task to run. + + +.. _idle-loop: + +The Idle Loop +============= + +The idle loop code takes two major steps in every iteration of it. First, it +calls into a code module referred to as the *governor* that belongs to the CPU +idle time management subsystem called ``CPUIdle`` to select an idle state for +the CPU to ask the hardware to enter. Second, it invokes another code module +from the ``CPUIdle`` subsystem, called the *driver*, to actually ask the +processor hardware to enter the idle state selected by the governor. + +The role of the governor is to find an idle state most suitable for the +conditions at hand. For this purpose, idle states that the hardware can be +asked to enter by logical CPUs are represented in an abstract way independent of +the platform or the processor architecture and organized in a one-dimensional +(linear) array. That array has to be prepared and supplied by the ``CPUIdle`` +driver matching the platform the kernel is running on at the initialization +time. This allows ``CPUIdle`` governors to be independent of the underlying +hardware and to work with any platforms that the Linux kernel can run on. + +Each idle state present in that array is characterized by two parameters to be +taken into account by the governor, the *target residency* and the (worst-case) +*exit latency*. The target residency is the minimum time the hardware must +spend in the given state, including the time needed to enter it (which may be +substantial), in order to save more energy than it would save by entering one of +the shallower idle states instead. [The "depth" of an idle state roughly +corresponds to the power drawn by the processor in that state.] The exit +latency, in turn, is the maximum time it will take a CPU asking the processor +hardware to enter an idle state to start executing the first instruction after a +wakeup from that state. Note that in general the exit latency also must cover +the time needed to enter the given state in case the wakeup occurs when the +hardware is entering it and it must be entered completely to be exited in an +ordered manner. + +There are two types of information that can influence the governor's decisions. +First of all, the governor knows the time until the closest timer event. That +time is known exactly, because the kernel programs timers and it knows exactly +when they will trigger, and it is the maximum time the hardware that the given +CPU depends on can spend in an idle state, including the time necessary to enter +and exit it. However, the CPU may be woken up by a non-timer event at any time +(in particular, before the closest timer triggers) and it generally is not known +when that may happen. The governor can only see how much time the CPU actually +was idle after it has been woken up (that time will be referred to as the *idle +duration* from now on) and it can use that information somehow along with the +time until the closest timer to estimate the idle duration in future. How the +governor uses that information depends on what algorithm is implemented by it +and that is the primary reason for having more than one governor in the +``CPUIdle`` subsystem. + +There are three ``CPUIdle`` governors available, ``menu``, `TEO <teo-gov_>`_ +and ``ladder``. Which of them is used by default depends on the configuration +of the kernel and in particular on whether or not the scheduler tick can be +`stopped by the idle loop <idle-cpus-and-tick_>`_. It is possible to change the +governor at run time if the ``cpuidle_sysfs_switch`` command line parameter has +been passed to the kernel, but that is not safe in general, so it should not be +done on production systems (that may change in the future, though). The name of +the ``CPUIdle`` governor currently used by the kernel can be read from the +:file:`current_governor_ro` (or :file:`current_governor` if +``cpuidle_sysfs_switch`` is present in the kernel command line) file under +:file:`/sys/devices/system/cpu/cpuidle/` in ``sysfs``. + +Which ``CPUIdle`` driver is used, on the other hand, usually depends on the +platform the kernel is running on, but there are platforms with more than one +matching driver. For example, there are two drivers that can work with the +majority of Intel platforms, ``intel_idle`` and ``acpi_idle``, one with +hardcoded idle states information and the other able to read that information +from the system's ACPI tables, respectively. Still, even in those cases, the +driver chosen at the system initialization time cannot be replaced later, so the +decision on which one of them to use has to be made early (on Intel platforms +the ``acpi_idle`` driver will be used if ``intel_idle`` is disabled for some +reason or if it does not recognize the processor). The name of the ``CPUIdle`` +driver currently used by the kernel can be read from the :file:`current_driver` +file under :file:`/sys/devices/system/cpu/cpuidle/` in ``sysfs``. + + +.. _idle-cpus-and-tick: + +Idle CPUs and The Scheduler Tick +================================ + +The scheduler tick is a timer that triggers periodically in order to implement +the time sharing strategy of the CPU scheduler. Of course, if there are +multiple runnable tasks assigned to one CPU at the same time, the only way to +allow them to make reasonable progress in a given time frame is to make them +share the available CPU time. Namely, in rough approximation, each task is +given a slice of the CPU time to run its code, subject to the scheduling class, +prioritization and so on and when that time slice is used up, the CPU should be +switched over to running (the code of) another task. The currently running task +may not want to give the CPU away voluntarily, however, and the scheduler tick +is there to make the switch happen regardless. That is not the only role of the +tick, but it is the primary reason for using it. + +The scheduler tick is problematic from the CPU idle time management perspective, +because it triggers periodically and relatively often (depending on the kernel +configuration, the length of the tick period is between 1 ms and 10 ms). +Thus, if the tick is allowed to trigger on idle CPUs, it will not make sense +for them to ask the hardware to enter idle states with target residencies above +the tick period length. Moreover, in that case the idle duration of any CPU +will never exceed the tick period length and the energy used for entering and +exiting idle states due to the tick wakeups on idle CPUs will be wasted. + +Fortunately, it is not really necessary to allow the tick to trigger on idle +CPUs, because (by definition) they have no tasks to run except for the special +"idle" one. In other words, from the CPU scheduler perspective, the only user +of the CPU time on them is the idle loop. Since the time of an idle CPU need +not be shared between multiple runnable tasks, the primary reason for using the +tick goes away if the given CPU is idle. Consequently, it is possible to stop +the scheduler tick entirely on idle CPUs in principle, even though that may not +always be worth the effort. + +Whether or not it makes sense to stop the scheduler tick in the idle loop +depends on what is expected by the governor. First, if there is another +(non-tick) timer due to trigger within the tick range, stopping the tick clearly +would be a waste of time, even though the timer hardware may not need to be +reprogrammed in that case. Second, if the governor is expecting a non-timer +wakeup within the tick range, stopping the tick is not necessary and it may even +be harmful. Namely, in that case the governor will select an idle state with +the target residency within the time until the expected wakeup, so that state is +going to be relatively shallow. The governor really cannot select a deep idle +state then, as that would contradict its own expectation of a wakeup in short +order. Now, if the wakeup really occurs shortly, stopping the tick would be a +waste of time and in this case the timer hardware would need to be reprogrammed, +which is expensive. On the other hand, if the tick is stopped and the wakeup +does not occur any time soon, the hardware may spend indefinite amount of time +in the shallow idle state selected by the governor, which will be a waste of +energy. Hence, if the governor is expecting a wakeup of any kind within the +tick range, it is better to allow the tick trigger. Otherwise, however, the +governor will select a relatively deep idle state, so the tick should be stopped +so that it does not wake up the CPU too early. + +In any case, the governor knows what it is expecting and the decision on whether +or not to stop the scheduler tick belongs to it. Still, if the tick has been +stopped already (in one of the previous iterations of the loop), it is better +to leave it as is and the governor needs to take that into account. + +The kernel can be configured to disable stopping the scheduler tick in the idle +loop altogether. That can be done through the build-time configuration of it +(by unsetting the ``CONFIG_NO_HZ_IDLE`` configuration option) or by passing +``nohz=off`` to it in the command line. In both cases, as the stopping of the +scheduler tick is disabled, the governor's decisions regarding it are simply +ignored by the idle loop code and the tick is never stopped. + +The systems that run kernels configured to allow the scheduler tick to be +stopped on idle CPUs are referred to as *tickless* systems and they are +generally regarded as more energy-efficient than the systems running kernels in +which the tick cannot be stopped. If the given system is tickless, it will use +the ``menu`` governor by default and if it is not tickless, the default +``CPUIdle`` governor on it will be ``ladder``. + + +.. _menu-gov: + +The ``menu`` Governor +===================== + +The ``menu`` governor is the default ``CPUIdle`` governor for tickless systems. +It is quite complex, but the basic principle of its design is straightforward. +Namely, when invoked to select an idle state for a CPU (i.e. an idle state that +the CPU will ask the processor hardware to enter), it attempts to predict the +idle duration and uses the predicted value for idle state selection. + +It first obtains the time until the closest timer event with the assumption +that the scheduler tick will be stopped. That time, referred to as the *sleep +length* in what follows, is the upper bound on the time before the next CPU +wakeup. It is used to determine the sleep length range, which in turn is needed +to get the sleep length correction factor. + +The ``menu`` governor maintains two arrays of sleep length correction factors. +One of them is used when tasks previously running on the given CPU are waiting +for some I/O operations to complete and the other one is used when that is not +the case. Each array contains several correction factor values that correspond +to different sleep length ranges organized so that each range represented in the +array is approximately 10 times wider than the previous one. + +The correction factor for the given sleep length range (determined before +selecting the idle state for the CPU) is updated after the CPU has been woken +up and the closer the sleep length is to the observed idle duration, the closer +to 1 the correction factor becomes (it must fall between 0 and 1 inclusive). +The sleep length is multiplied by the correction factor for the range that it +falls into to obtain the first approximation of the predicted idle duration. + +Next, the governor uses a simple pattern recognition algorithm to refine its +idle duration prediction. Namely, it saves the last 8 observed idle duration +values and, when predicting the idle duration next time, it computes the average +and variance of them. If the variance is small (smaller than 400 square +milliseconds) or it is small relative to the average (the average is greater +that 6 times the standard deviation), the average is regarded as the "typical +interval" value. Otherwise, the longest of the saved observed idle duration +values is discarded and the computation is repeated for the remaining ones. +Again, if the variance of them is small (in the above sense), the average is +taken as the "typical interval" value and so on, until either the "typical +interval" is determined or too many data points are disregarded, in which case +the "typical interval" is assumed to equal "infinity" (the maximum unsigned +integer value). The "typical interval" computed this way is compared with the +sleep length multiplied by the correction factor and the minimum of the two is +taken as the predicted idle duration. + +Then, the governor computes an extra latency limit to help "interactive" +workloads. It uses the observation that if the exit latency of the selected +idle state is comparable with the predicted idle duration, the total time spent +in that state probably will be very short and the amount of energy to save by +entering it will be relatively small, so likely it is better to avoid the +overhead related to entering that state and exiting it. Thus selecting a +shallower state is likely to be a better option then. The first approximation +of the extra latency limit is the predicted idle duration itself which +additionally is divided by a value depending on the number of tasks that +previously ran on the given CPU and now they are waiting for I/O operations to +complete. The result of that division is compared with the latency limit coming +from the power management quality of service, or `PM QoS <cpu-pm-qos_>`_, +framework and the minimum of the two is taken as the limit for the idle states' +exit latency. + +Now, the governor is ready to walk the list of idle states and choose one of +them. For this purpose, it compares the target residency of each state with +the predicted idle duration and the exit latency of it with the computed latency +limit. It selects the state with the target residency closest to the predicted +idle duration, but still below it, and exit latency that does not exceed the +limit. + +In the final step the governor may still need to refine the idle state selection +if it has not decided to `stop the scheduler tick <idle-cpus-and-tick_>`_. That +happens if the idle duration predicted by it is less than the tick period and +the tick has not been stopped already (in a previous iteration of the idle +loop). Then, the sleep length used in the previous computations may not reflect +the real time until the closest timer event and if it really is greater than +that time, the governor may need to select a shallower state with a suitable +target residency. + + +.. _teo-gov: + +The Timer Events Oriented (TEO) Governor +======================================== + +The timer events oriented (TEO) governor is an alternative ``CPUIdle`` governor +for tickless systems. It follows the same basic strategy as the ``menu`` `one +<menu-gov_>`_: it always tries to find the deepest idle state suitable for the +given conditions. However, it applies a different approach to that problem. + +First, it does not use sleep length correction factors, but instead it attempts +to correlate the observed idle duration values with the available idle states +and use that information to pick up the idle state that is most likely to +"match" the upcoming CPU idle interval. Second, it does not take the tasks +that were running on the given CPU in the past and are waiting on some I/O +operations to complete now at all (there is no guarantee that they will run on +the same CPU when they become runnable again) and the pattern detection code in +it avoids taking timer wakeups into account. It also only uses idle duration +values less than the current time till the closest timer (with the scheduler +tick excluded) for that purpose. + +Like in the ``menu`` governor `case <menu-gov_>`_, the first step is to obtain +the *sleep length*, which is the time until the closest timer event with the +assumption that the scheduler tick will be stopped (that also is the upper bound +on the time until the next CPU wakeup). That value is then used to preselect an +idle state on the basis of three metrics maintained for each idle state provided +by the ``CPUIdle`` driver: ``hits``, ``misses`` and ``early_hits``. + +The ``hits`` and ``misses`` metrics measure the likelihood that a given idle +state will "match" the observed (post-wakeup) idle duration if it "matches" the +sleep length. They both are subject to decay (after a CPU wakeup) every time +the target residency of the idle state corresponding to them is less than or +equal to the sleep length and the target residency of the next idle state is +greater than the sleep length (that is, when the idle state corresponding to +them "matches" the sleep length). The ``hits`` metric is increased if the +former condition is satisfied and the target residency of the given idle state +is less than or equal to the observed idle duration and the target residency of +the next idle state is greater than the observed idle duration at the same time +(that is, it is increased when the given idle state "matches" both the sleep +length and the observed idle duration). In turn, the ``misses`` metric is +increased when the given idle state "matches" the sleep length only and the +observed idle duration is too short for its target residency. + +The ``early_hits`` metric measures the likelihood that a given idle state will +"match" the observed (post-wakeup) idle duration if it does not "match" the +sleep length. It is subject to decay on every CPU wakeup and it is increased +when the idle state corresponding to it "matches" the observed (post-wakeup) +idle duration and the target residency of the next idle state is less than or +equal to the sleep length (i.e. the idle state "matching" the sleep length is +deeper than the given one). + +The governor walks the list of idle states provided by the ``CPUIdle`` driver +and finds the last (deepest) one with the target residency less than or equal +to the sleep length. Then, the ``hits`` and ``misses`` metrics of that idle +state are compared with each other and it is preselected if the ``hits`` one is +greater (which means that that idle state is likely to "match" the observed idle +duration after CPU wakeup). If the ``misses`` one is greater, the governor +preselects the shallower idle state with the maximum ``early_hits`` metric +(or if there are multiple shallower idle states with equal ``early_hits`` +metric which also is the maximum, the shallowest of them will be preselected). +[If there is a wakeup latency constraint coming from the `PM QoS framework +<cpu-pm-qos_>`_ which is hit before reaching the deepest idle state with the +target residency within the sleep length, the deepest idle state with the exit +latency within the constraint is preselected without consulting the ``hits``, +``misses`` and ``early_hits`` metrics.] + +Next, the governor takes several idle duration values observed most recently +into consideration and if at least a half of them are greater than or equal to +the target residency of the preselected idle state, that idle state becomes the +final candidate to ask for. Otherwise, the average of the most recent idle +duration values below the target residency of the preselected idle state is +computed and the governor walks the idle states shallower than the preselected +one and finds the deepest of them with the target residency within that average. +That idle state is then taken as the final candidate to ask for. + +Still, at this point the governor may need to refine the idle state selection if +it has not decided to `stop the scheduler tick <idle-cpus-and-tick_>`_. That +generally happens if the target residency of the idle state selected so far is +less than the tick period and the tick has not been stopped already (in a +previous iteration of the idle loop). Then, like in the ``menu`` governor +`case <menu-gov_>`_, the sleep length used in the previous computations may not +reflect the real time until the closest timer event and if it really is greater +than that time, a shallower state with a suitable target residency may need to +be selected. + + +.. _idle-states-representation: + +Representation of Idle States +============================= + +For the CPU idle time management purposes all of the physical idle states +supported by the processor have to be represented as a one-dimensional array of +|struct cpuidle_state| objects each allowing an individual (logical) CPU to ask +the processor hardware to enter an idle state of certain properties. If there +is a hierarchy of units in the processor, one |struct cpuidle_state| object can +cover a combination of idle states supported by the units at different levels of +the hierarchy. In that case, the `target residency and exit latency parameters +of it <idle-loop_>`_, must reflect the properties of the idle state at the +deepest level (i.e. the idle state of the unit containing all of the other +units). + +For example, take a processor with two cores in a larger unit referred to as +a "module" and suppose that asking the hardware to enter a specific idle state +(say "X") at the "core" level by one core will trigger the module to try to +enter a specific idle state of its own (say "MX") if the other core is in idle +state "X" already. In other words, asking for idle state "X" at the "core" +level gives the hardware a license to go as deep as to idle state "MX" at the +"module" level, but there is no guarantee that this is going to happen (the core +asking for idle state "X" may just end up in that state by itself instead). +Then, the target residency of the |struct cpuidle_state| object representing +idle state "X" must reflect the minimum time to spend in idle state "MX" of +the module (including the time needed to enter it), because that is the minimum +time the CPU needs to be idle to save any energy in case the hardware enters +that state. Analogously, the exit latency parameter of that object must cover +the exit time of idle state "MX" of the module (and usually its entry time too), +because that is the maximum delay between a wakeup signal and the time the CPU +will start to execute the first new instruction (assuming that both cores in the +module will always be ready to execute instructions as soon as the module +becomes operational as a whole). + +There are processors without direct coordination between different levels of the +hierarchy of units inside them, however. In those cases asking for an idle +state at the "core" level does not automatically affect the "module" level, for +example, in any way and the ``CPUIdle`` driver is responsible for the entire +handling of the hierarchy. Then, the definition of the idle state objects is +entirely up to the driver, but still the physical properties of the idle state +that the processor hardware finally goes into must always follow the parameters +used by the governor for idle state selection (for instance, the actual exit +latency of that idle state must not exceed the exit latency parameter of the +idle state object selected by the governor). + +In addition to the target residency and exit latency idle state parameters +discussed above, the objects representing idle states each contain a few other +parameters describing the idle state and a pointer to the function to run in +order to ask the hardware to enter that state. Also, for each +|struct cpuidle_state| object, there is a corresponding +:c:type:`struct cpuidle_state_usage <cpuidle_state_usage>` one containing usage +statistics of the given idle state. That information is exposed by the kernel +via ``sysfs``. + +For each CPU in the system, there is a :file:`/sys/devices/system/cpu<N>/cpuidle/` +directory in ``sysfs``, where the number ``<N>`` is assigned to the given +CPU at the initialization time. That directory contains a set of subdirectories +called :file:`state0`, :file:`state1` and so on, up to the number of idle state +objects defined for the given CPU minus one. Each of these directories +corresponds to one idle state object and the larger the number in its name, the +deeper the (effective) idle state represented by it. Each of them contains +a number of files (attributes) representing the properties of the idle state +object corresponding to it, as follows: + +``above`` + Total number of times this idle state had been asked for, but the + observed idle duration was certainly too short to match its target + residency. + +``below`` + Total number of times this idle state had been asked for, but cerainly + a deeper idle state would have been a better match for the observed idle + duration. + +``desc`` + Description of the idle state. + +``disable`` + Whether or not this idle state is disabled. + +``latency`` + Exit latency of the idle state in microseconds. + +``name`` + Name of the idle state. + +``power`` + Power drawn by hardware in this idle state in milliwatts (if specified, + 0 otherwise). + +``residency`` + Target residency of the idle state in microseconds. + +``time`` + Total time spent in this idle state by the given CPU (as measured by the + kernel) in microseconds. + +``usage`` + Total number of times the hardware has been asked by the given CPU to + enter this idle state. + +The :file:`desc` and :file:`name` files both contain strings. The difference +between them is that the name is expected to be more concise, while the +description may be longer and it may contain white space or special characters. +The other files listed above contain integer numbers. + +The :file:`disable` attribute is the only writeable one. If it contains 1, the +given idle state is disabled for this particular CPU, which means that the +governor will never select it for this particular CPU and the ``CPUIdle`` +driver will never ask the hardware to enter it for that CPU as a result. +However, disabling an idle state for one CPU does not prevent it from being +asked for by the other CPUs, so it must be disabled for all of them in order to +never be asked for by any of them. [Note that, due to the way the ``ladder`` +governor is implemented, disabling an idle state prevents that governor from +selecting any idle states deeper than the disabled one too.] + +If the :file:`disable` attribute contains 0, the given idle state is enabled for +this particular CPU, but it still may be disabled for some or all of the other +CPUs in the system at the same time. Writing 1 to it causes the idle state to +be disabled for this particular CPU and writing 0 to it allows the governor to +take it into consideration for the given CPU and the driver to ask for it, +unless that state was disabled globally in the driver (in which case it cannot +be used at all). + +The :file:`power` attribute is not defined very well, especially for idle state +objects representing combinations of idle states at different levels of the +hierarchy of units in the processor, and it generally is hard to obtain idle +state power numbers for complex hardware, so :file:`power` often contains 0 (not +available) and if it contains a nonzero number, that number may not be very +accurate and it should not be relied on for anything meaningful. + +The number in the :file:`time` file generally may be greater than the total time +really spent by the given CPU in the given idle state, because it is measured by +the kernel and it may not cover the cases in which the hardware refused to enter +this idle state and entered a shallower one instead of it (or even it did not +enter any idle state at all). The kernel can only measure the time span between +asking the hardware to enter an idle state and the subsequent wakeup of the CPU +and it cannot say what really happened in the meantime at the hardware level. +Moreover, if the idle state object in question represents a combination of idle +states at different levels of the hierarchy of units in the processor, +the kernel can never say how deep the hardware went down the hierarchy in any +particular case. For these reasons, the only reliable way to find out how +much time has been spent by the hardware in different idle states supported by +it is to use idle state residency counters in the hardware, if available. + + +.. _cpu-pm-qos: + +Power Management Quality of Service for CPUs +============================================ + +The power management quality of service (PM QoS) framework in the Linux kernel +allows kernel code and user space processes to set constraints on various +energy-efficiency features of the kernel to prevent performance from dropping +below a required level. The PM QoS constraints can be set globally, in +predefined categories referred to as PM QoS classes, or against individual +devices. + +CPU idle time management can be affected by PM QoS in two ways, through the +global constraint in the ``PM_QOS_CPU_DMA_LATENCY`` class and through the +resume latency constraints for individual CPUs. Kernel code (e.g. device +drivers) can set both of them with the help of special internal interfaces +provided by the PM QoS framework. User space can modify the former by opening +the :file:`cpu_dma_latency` special device file under :file:`/dev/` and writing +a binary value (interpreted as a signed 32-bit integer) to it. In turn, the +resume latency constraint for a CPU can be modified by user space by writing a +string (representing a signed 32-bit integer) to the +:file:`power/pm_qos_resume_latency_us` file under +:file:`/sys/devices/system/cpu/cpu<N>/` in ``sysfs``, where the CPU number +``<N>`` is allocated at the system initialization time. Negative values +will be rejected in both cases and, also in both cases, the written integer +number will be interpreted as a requested PM QoS constraint in microseconds. + +The requested value is not automatically applied as a new constraint, however, +as it may be less restrictive (greater in this particular case) than another +constraint previously requested by someone else. For this reason, the PM QoS +framework maintains a list of requests that have been made so far in each +global class and for each device, aggregates them and applies the effective +(minimum in this particular case) value as the new constraint. + +In fact, opening the :file:`cpu_dma_latency` special device file causes a new +PM QoS request to be created and added to the priority list of requests in the +``PM_QOS_CPU_DMA_LATENCY`` class and the file descriptor coming from the +"open" operation represents that request. If that file descriptor is then +used for writing, the number written to it will be associated with the PM QoS +request represented by it as a new requested constraint value. Next, the +priority list mechanism will be used to determine the new effective value of +the entire list of requests and that effective value will be set as a new +constraint. Thus setting a new requested constraint value will only change the +real constraint if the effective "list" value is affected by it. In particular, +for the ``PM_QOS_CPU_DMA_LATENCY`` class it only affects the real constraint if +it is the minimum of the requested constraints in the list. The process holding +a file descriptor obtained by opening the :file:`cpu_dma_latency` special device +file controls the PM QoS request associated with that file descriptor, but it +controls this particular PM QoS request only. + +Closing the :file:`cpu_dma_latency` special device file or, more precisely, the +file descriptor obtained while opening it, causes the PM QoS request associated +with that file descriptor to be removed from the ``PM_QOS_CPU_DMA_LATENCY`` +class priority list and destroyed. If that happens, the priority list mechanism +will be used, again, to determine the new effective value for the whole list +and that value will become the new real constraint. + +In turn, for each CPU there is only one resume latency PM QoS request +associated with the :file:`power/pm_qos_resume_latency_us` file under +:file:`/sys/devices/system/cpu/cpu<N>/` in ``sysfs`` and writing to it causes +this single PM QoS request to be updated regardless of which user space +process does that. In other words, this PM QoS request is shared by the entire +user space, so access to the file associated with it needs to be arbitrated +to avoid confusion. [Arguably, the only legitimate use of this mechanism in +practice is to pin a process to the CPU in question and let it use the +``sysfs`` interface to control the resume latency constraint for it.] It +still only is a request, however. It is a member of a priority list used to +determine the effective value to be set as the resume latency constraint for the +CPU in question every time the list of requests is updated this way or another +(there may be other requests coming from kernel code in that list). + +CPU idle time governors are expected to regard the minimum of the global +effective ``PM_QOS_CPU_DMA_LATENCY`` class constraint and the effective +resume latency constraint for the given CPU as the upper limit for the exit +latency of the idle states they can select for that CPU. They should never +select any idle states with exit latency beyond that limit. + + +Idle States Control Via Kernel Command Line +=========================================== + +In addition to the ``sysfs`` interface allowing individual idle states to be +`disabled for individual CPUs <idle-states-representation_>`_, there are kernel +command line parameters affecting CPU idle time management. + +The ``cpuidle.off=1`` kernel command line option can be used to disable the +CPU idle time management entirely. It does not prevent the idle loop from +running on idle CPUs, but it prevents the CPU idle time governors and drivers +from being invoked. If it is added to the kernel command line, the idle loop +will ask the hardware to enter idle states on idle CPUs via the CPU architecture +support code that is expected to provide a default mechanism for this purpose. +That default mechanism usually is the least common denominator for all of the +processors implementing the architecture (i.e. CPU instruction set) in question, +however, so it is rather crude and not very energy-efficient. For this reason, +it is not recommended for production use. + +The ``cpuidle.governor=`` kernel command line switch allows the ``CPUIdle`` +governor to use to be specified. It has to be appended with a string matching +the name of an available governor (e.g. ``cpuidle.governor=menu``) and that +governor will be used instead of the default one. It is possible to force +the ``menu`` governor to be used on the systems that use the ``ladder`` governor +by default this way, for example. + +The other kernel command line parameters controlling CPU idle time management +described below are only relevant for the *x86* architecture and some of +them affect Intel processors only. + +The *x86* architecture support code recognizes three kernel command line +options related to CPU idle time management: ``idle=poll``, ``idle=halt``, +and ``idle=nomwait``. The first two of them disable the ``acpi_idle`` and +``intel_idle`` drivers altogether, which effectively causes the entire +``CPUIdle`` subsystem to be disabled and makes the idle loop invoke the +architecture support code to deal with idle CPUs. How it does that depends on +which of the two parameters is added to the kernel command line. In the +``idle=halt`` case, the architecture support code will use the ``HLT`` +instruction of the CPUs (which, as a rule, suspends the execution of the program +and causes the hardware to attempt to enter the shallowest available idle state) +for this purpose, and if ``idle=poll`` is used, idle CPUs will execute a +more or less ``lightweight'' sequence of instructions in a tight loop. [Note +that using ``idle=poll`` is somewhat drastic in many cases, as preventing idle +CPUs from saving almost any energy at all may not be the only effect of it. +For example, on Intel hardware it effectively prevents CPUs from using +P-states (see |cpufreq|) that require any number of CPUs in a package to be +idle, so it very well may hurt single-thread computations performance as well as +energy-efficiency. Thus using it for performance reasons may not be a good idea +at all.] + +The ``idle=nomwait`` option disables the ``intel_idle`` driver and causes +``acpi_idle`` to be used (as long as all of the information needed by it is +there in the system's ACPI tables), but it is not allowed to use the +``MWAIT`` instruction of the CPUs to ask the hardware to enter idle states. + +In addition to the architecture-level kernel command line options affecting CPU +idle time management, there are parameters affecting individual ``CPUIdle`` +drivers that can be passed to them via the kernel command line. Specifically, +the ``intel_idle.max_cstate=<n>`` and ``processor.max_cstate=<n>`` parameters, +where ``<n>`` is an idle state index also used in the name of the given +state's directory in ``sysfs`` (see +`Representation of Idle States <idle-states-representation_>`_), causes the +``intel_idle`` and ``acpi_idle`` drivers, respectively, to discard all of the +idle states deeper than idle state ``<n>``. In that case, they will never ask +for any of those idle states or expose them to the governor. [The behavior of +the two drivers is different for ``<n>`` equal to ``0``. Adding +``intel_idle.max_cstate=0`` to the kernel command line disables the +``intel_idle`` driver and allows ``acpi_idle`` to be used, whereas +``processor.max_cstate=0`` is equivalent to ``processor.max_cstate=1``. +Also, the ``acpi_idle`` driver is part of the ``processor`` kernel module that +can be loaded separately and ``max_cstate=<n>`` can be passed to it as a module +parameter when it is loaded.] diff --git a/Documentation/admin-guide/pm/intel_pstate.rst b/Documentation/admin-guide/pm/intel_pstate.rst index ac6f5c597a56..ec0f7c111f65 100644 --- a/Documentation/admin-guide/pm/intel_pstate.rst +++ b/Documentation/admin-guide/pm/intel_pstate.rst @@ -495,7 +495,15 @@ on the following rules, regardless of the current operation mode of the driver: 2. Each individual CPU is affected by its own per-policy limits (that is, it cannot be requested to run faster than its own per-policy maximum and it - cannot be requested to run slower than its own per-policy minimum). + cannot be requested to run slower than its own per-policy minimum). The + effective performance depends on whether the platform supports per core + P-states, hyper-threading is enabled and on current performance requests + from other CPUs. When platform doesn't support per core P-states, the + effective performance can be more than the policy limits set on a CPU, if + other CPUs are requesting higher performance at that moment. Even with per + core P-states support, when hyper-threading is enabled, if the sibling CPU + is requesting higher performance, the other siblings will get higher + performance than their policy limits. 3. The global and per-policy limits can be set independently. diff --git a/Documentation/admin-guide/pm/working-state.rst b/Documentation/admin-guide/pm/working-state.rst index fa01bf083dfe..b6cef9b5e961 100644 --- a/Documentation/admin-guide/pm/working-state.rst +++ b/Documentation/admin-guide/pm/working-state.rst @@ -5,5 +5,6 @@ Working-State Power Management .. toctree:: :maxdepth: 2 + cpuidle cpufreq intel_pstate diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst index 197896718f81..c7495e42e6f4 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/ras.rst @@ -54,7 +54,7 @@ those errors are correctable. Types of errors --------------- -Most mechanisms used on modern systems use use technologies like Hamming +Most mechanisms used on modern systems use technologies like Hamming Codes that allow error correction when the number of errors on a bit packet is below a threshold. If the number of errors is above, those mechanisms can indicate with a high degree of confidence that an error happened, but diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 4650edb8840a..49ac8dc3594d 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -67,7 +67,7 @@ If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more information on the linux-kernel mailing list see -http://www.tux.org/lkml/). +http://vger.kernel.org/lkml/). Tips for reporting bugs diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index 30491d91e93d..dcd6c93c7aac 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -26,23 +26,35 @@ information is helpful. Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. -Disclosure ----------- - -The goal of the Linux kernel security team is to work with the bug -submitter to understand and fix the bug. We prefer to publish the fix as -soon as possible, but try to avoid public discussion of the bug itself -and leave that to others. - -Publishing the fix may be delayed when the bug or the fix is not yet -fully understood, the solution is not well-tested or for vendor -coordination. However, we expect these delays to be short, measurable in -days, not weeks or months. A release date is negotiated by the security -team working with the bug submitter as well as vendors. However, the -kernel security team holds the final say when setting a timeframe. The -timeframe varies from immediate (esp. if it's already publicly known bug) -to a few weeks. As a basic default policy, we expect report date to -release date to be on the order of 7 days. +Disclosure and embargoed information +------------------------------------ + +The security list is not a disclosure channel. For that, see Coordination +below. + +Once a robust fix has been developed, the release process starts. Fixes +for publicly known bugs are released immediately. + +Although our preference is to release fixes for publicly undisclosed bugs +as soon as they become available, this may be postponed at the request of +the reporter or an affected party for up to 7 calendar days from the start +of the release process, with an exceptional extension to 14 calendar days +if it is agreed that the criticality of the bug requires more time. The +only valid reason for deferring the publication of a fix is to accommodate +the logistics of QA and large scale rollouts which require release +coordination. + +While embargoed information may be shared with trusted individuals in +order to develop a fix, such information will not be published alongside +the fix or on any other disclosure channel without the permission of the +reporter. This includes but is not limited to the original bug report +and followup discussions (if any), exploits, CVE information or the +identity of the reporter. + +In other words our only interest is in getting bugs fixed. All other +information submitted to the security list and any followup discussions +of the report are treated confidentially even after the embargo has been +lifted, in perpetuity. Coordination ------------ @@ -68,7 +80,7 @@ may delay the bug handling. If a reporter wishes to have a CVE identifier assigned ahead of public disclosure, they will need to contact the private linux-distros list, described above. When such a CVE identifier is known before a patch is provided, it is desirable to mention it in the commit -message, though. +message if the reporter agrees. Non-disclosure agreements ------------------------- diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 35fccba6a9a6..898ad78f3cc7 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -133,6 +133,26 @@ If the user still wants to connect the device they can either approve the device without a key or write a new key and write 1 to the ``authorized`` file to get the new key stored on the device NVM. +DMA protection utilizing IOMMU +------------------------------ +Recent systems from 2018 and forward with Thunderbolt ports may natively +support IOMMU. This means that Thunderbolt security is handled by an IOMMU +so connected devices cannot access memory regions outside of what is +allocated for them by drivers. When Linux is running on such system it +automatically enables IOMMU if not enabled by the user already. These +systems can be identified by reading ``1`` from +``/sys/bus/thunderbolt/devices/domainX/iommu_dma_protection`` attribute. + +The driver does not do anything special in this case but because DMA +protection is handled by the IOMMU, security levels (if set) are +redundant. For this reason some systems ship with security level set to +``none``. Other systems have security level set to ``user`` in order to +support downgrade to older OS, so users who want to automatically +authorize devices when IOMMU DMA protection is enabled can use the +following ``udev`` rule:: + + ACTION=="add", SUBSYSTEM=="thunderbolt", ATTRS{iommu_dma_protection}=="1", ATTR{authorized}=="0", ATTR{authorized}="1" + Upgrading NVM on Thunderbolt device or host ------------------------------------------- Since most of the functionality is handled in firmware running on a diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting index 259f00af3ab3..f1f965ce93d6 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/Booting @@ -126,7 +126,7 @@ tagged list. The boot loader must pass at a minimum the size and location of the system memory, and the root filesystem location. The dtb must be placed in a region of memory where the kernel decompressor will not -overwrite it, whilst remaining within the region which will be covered +overwrite it, while remaining within the region which will be covered by the kernel's low-memory mapping. A safe location is just above the 128MiB boundary from start of RAM. diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/Samsung-S3C24XX/GPIO.txt index 0ebd7e2244d0..e8f918b96123 100644 --- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt +++ b/Documentation/arm/Samsung-S3C24XX/GPIO.txt @@ -55,7 +55,7 @@ out s3c2410 API, then here are some notes on the process. as they have the same arguments, and can either take the pin specific values, or the more generic special-function-number arguments. -3) s3c2410_gpio_pullup() changes have the problem that whilst the +3) s3c2410_gpio_pullup() changes have the problem that while the s3c2410_gpio_pullup(x, 1) can be easily translated to the s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0) are not so easy. diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/Samsung-S3C24XX/Overview.txt index 359587b2367b..00d3c3141e21 100644 --- a/Documentation/arm/Samsung-S3C24XX/Overview.txt +++ b/Documentation/arm/Samsung-S3C24XX/Overview.txt @@ -17,7 +17,7 @@ Introduction versions. The S3C2416 and S3C2450 devices are very similar and S3C2450 support is - included under the arch/arm/mach-s3c2416 directory. Note, whilst core + included under the arch/arm/mach-s3c2416 directory. Note, while core support for these SoCs is in, work on some of the extra peripherals and extra interrupts is still ongoing. diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/Samsung-S3C24XX/Suspend.txt index 1ca63b3e5635..cb4f0c0cdf9d 100644 --- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt +++ b/Documentation/arm/Samsung-S3C24XX/Suspend.txt @@ -87,7 +87,7 @@ Debugging suspending, which means that use of printascii() or similar direct access to the UARTs will cause the debug to stop. - 2) Whilst the pm code itself will attempt to re-enable the UART clocks, + 2) While the pm code itself will attempt to re-enable the UART clocks, care should be taken that any external clock sources that the UARTs rely on are still enabled at that point. diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/Samsung/Bootloader-interface.txt index ed494ac0beb2..d17ed518a7ea 100644 --- a/Documentation/arm/Samsung/Bootloader-interface.txt +++ b/Documentation/arm/Samsung/Bootloader-interface.txt @@ -26,6 +26,7 @@ Offset Value Purpose 0x20 0xfcba0d10 (Magic cookie) AFTR 0x24 exynos_cpu_resume_ns AFTR 0x28 + 4*cpu 0x8 (Magic cookie, Exynos3250) AFTR +0x28 0x0 or last value during resume (Exynos542x) System suspend 2. Secure mode diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.txt index 8d0df62c3fe0..8df9f4658d6f 100644 --- a/Documentation/arm64/booting.txt +++ b/Documentation/arm64/booting.txt @@ -205,6 +205,14 @@ Before jumping into the kernel, the following conditions must be met: ICC_SRE_EL2.SRE (bit 0) must be initialised to 0b0. - The DT or ACPI tables must describe a GICv2 interrupt controller. + For CPUs with pointer authentication functionality: + - If EL3 is present: + SCR_EL3.APK (bit 16) must be initialised to 0b1 + SCR_EL3.API (bit 17) must be initialised to 0b1 + - If the kernel is entered at EL1: + HCR_EL2.APK (bit 40) must be initialised to 0b1 + HCR_EL2.API (bit 41) must be initialised to 0b1 + The requirements described above for CPU mode, caches, MMUs, architected timers, coherency and system registers apply to all CPUs. All CPUs must enter the kernel in the same exception level. diff --git a/Documentation/arm64/cpu-feature-registers.txt b/Documentation/arm64/cpu-feature-registers.txt index 7964f03846b1..d4b4dd1fe786 100644 --- a/Documentation/arm64/cpu-feature-registers.txt +++ b/Documentation/arm64/cpu-feature-registers.txt @@ -184,12 +184,20 @@ infrastructure: x--------------------------------------------------x | Name | bits | visible | |--------------------------------------------------| + | GPI | [31-28] | y | + |--------------------------------------------------| + | GPA | [27-24] | y | + |--------------------------------------------------| | LRCPC | [23-20] | y | |--------------------------------------------------| | FCMA | [19-16] | y | |--------------------------------------------------| | JSCVT | [15-12] | y | |--------------------------------------------------| + | API | [11-8] | y | + |--------------------------------------------------| + | APA | [7-4] | y | + |--------------------------------------------------| | DPB | [3-0] | y | x--------------------------------------------------x diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt index ea819ae024dd..13d6691b37be 100644 --- a/Documentation/arm64/elf_hwcaps.txt +++ b/Documentation/arm64/elf_hwcaps.txt @@ -182,3 +182,15 @@ HWCAP_FLAGM HWCAP_SSBS Functionality implied by ID_AA64PFR1_EL1.SSBS == 0b0010. + +HWCAP_PACA + + Functionality implied by ID_AA64ISAR1_EL1.APA == 0b0001 or + ID_AA64ISAR1_EL1.API == 0b0001, as described by + Documentation/arm64/pointer-authentication.txt. + +HWCAP_PACG + + Functionality implied by ID_AA64ISAR1_EL1.GPA == 0b0001 or + ID_AA64ISAR1_EL1.GPI == 0b0001, as described by + Documentation/arm64/pointer-authentication.txt. diff --git a/Documentation/arm64/pointer-authentication.txt b/Documentation/arm64/pointer-authentication.txt new file mode 100644 index 000000000000..a25cd21290e9 --- /dev/null +++ b/Documentation/arm64/pointer-authentication.txt @@ -0,0 +1,88 @@ +Pointer authentication in AArch64 Linux +======================================= + +Author: Mark Rutland <mark.rutland@arm.com> +Date: 2017-07-19 + +This document briefly describes the provision of pointer authentication +functionality in AArch64 Linux. + + +Architecture overview +--------------------- + +The ARMv8.3 Pointer Authentication extension adds primitives that can be +used to mitigate certain classes of attack where an attacker can corrupt +the contents of some memory (e.g. the stack). + +The extension uses a Pointer Authentication Code (PAC) to determine +whether pointers have been modified unexpectedly. A PAC is derived from +a pointer, another value (such as the stack pointer), and a secret key +held in system registers. + +The extension adds instructions to insert a valid PAC into a pointer, +and to verify/remove the PAC from a pointer. The PAC occupies a number +of high-order bits of the pointer, which varies dependent on the +configured virtual address size and whether pointer tagging is in use. + +A subset of these instructions have been allocated from the HINT +encoding space. In the absence of the extension (or when disabled), +these instructions behave as NOPs. Applications and libraries using +these instructions operate correctly regardless of the presence of the +extension. + +The extension provides five separate keys to generate PACs - two for +instruction addresses (APIAKey, APIBKey), two for data addresses +(APDAKey, APDBKey), and one for generic authentication (APGAKey). + + +Basic support +------------- + +When CONFIG_ARM64_PTR_AUTH is selected, and relevant HW support is +present, the kernel will assign random key values to each process at +exec*() time. The keys are shared by all threads within the process, and +are preserved across fork(). + +Presence of address authentication functionality is advertised via +HWCAP_PACA, and generic authentication functionality via HWCAP_PACG. + +The number of bits that the PAC occupies in a pointer is 55 minus the +virtual address size configured by the kernel. For example, with a +virtual address size of 48, the PAC is 7 bits wide. + +Recent versions of GCC can compile code with APIAKey-based return +address protection when passed the -msign-return-address option. This +uses instructions in the HINT space (unless -march=armv8.3-a or higher +is also passed), and such code can run on systems without the pointer +authentication extension. + +In addition to exec(), keys can also be reinitialized to random values +using the PR_PAC_RESET_KEYS prctl. A bitmask of PR_PAC_APIAKEY, +PR_PAC_APIBKEY, PR_PAC_APDAKEY, PR_PAC_APDBKEY and PR_PAC_APGAKEY +specifies which keys are to be reinitialized; specifying 0 means "all +keys". + + +Debugging +--------- + +When CONFIG_ARM64_PTR_AUTH is selected, and HW support for address +authentication is present, the kernel will expose the position of TTBR0 +PAC bits in the NT_ARM_PAC_MASK regset (struct user_pac_mask), which +userspace can acquire via PTRACE_GETREGSET. + +The regset is exposed only when HWCAP_PACA is set. Separate masks are +exposed for data pointers and instruction pointers, as the set of PAC +bits can vary between the two. Note that the masks apply to TTBR0 +addresses, and are not valid to apply to TTBR1 addresses (e.g. kernel +pointers). + + +Virtualization +-------------- + +Pointer authentication is not currently supported in KVM guests. KVM +will mask the feature bits from ID_AA64ISAR1_EL1, and attempted use of +the feature will result in an UNDEFINED exception being injected into +the guest. diff --git a/Documentation/arm64/silicon-errata.txt b/Documentation/arm64/silicon-errata.txt index 76ccded8b74c..ddb8ce5333ba 100644 --- a/Documentation/arm64/silicon-errata.txt +++ b/Documentation/arm64/silicon-errata.txt @@ -44,6 +44,8 @@ stable kernels. | Implementor | Component | Erratum ID | Kconfig | +----------------+-----------------+-----------------+-----------------------------+ +| Allwinner | A64/R18 | UNKNOWN1 | SUN50I_ERRATUM_UNKNOWN1 | +| | | | | | ARM | Cortex-A53 | #826319 | ARM64_ERRATUM_826319 | | ARM | Cortex-A53 | #827319 | ARM64_ERRATUM_827319 | | ARM | Cortex-A53 | #824069 | ARM64_ERRATUM_824069 | @@ -57,6 +59,8 @@ stable kernels. | ARM | Cortex-A73 | #858921 | ARM64_ERRATUM_858921 | | ARM | Cortex-A55 | #1024718 | ARM64_ERRATUM_1024718 | | ARM | Cortex-A76 | #1188873 | ARM64_ERRATUM_1188873 | +| ARM | Cortex-A76 | #1165522 | ARM64_ERRATUM_1165522 | +| ARM | Cortex-A76 | #1286807 | ARM64_ERRATUM_1286807 | | ARM | MMU-500 | #841119,#826419 | N/A | | | | | | | Cavium | ThunderX ITS | #22375, #24313 | CAVIUM_ERRATUM_22375 | diff --git a/Documentation/block/bfq-iosched.txt b/Documentation/block/bfq-iosched.txt index 8d8d8f06cab2..98a8dd5ee385 100644 --- a/Documentation/block/bfq-iosched.txt +++ b/Documentation/block/bfq-iosched.txt @@ -357,6 +357,13 @@ video playing/streaming, a very low drop rate may be more important than maximum throughput. In these cases, consider setting the strict_guarantees parameter. +slice_idle_us +------------- + +Controls the same tuning parameter as slice_idle, but in microseconds. +Either tunable can be used to set idling behavior. Afterwards, the +other tunable will reflect the newly set value in sysfs. + strict_guarantees ----------------- diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt index 207eca58efaa..ac18b488cb5e 100644 --- a/Documentation/block/biodoc.txt +++ b/Documentation/block/biodoc.txt @@ -65,7 +65,6 @@ Description of Contents: 3.2.3 I/O completion 3.2.4 Implications for drivers that do not interpret bios (don't handle multiple segments) - 3.2.5 Request command tagging 3.3 I/O submission 4. The I/O scheduler 5. Scalability related changes @@ -708,93 +707,6 @@ is crossed on completion of a transfer. (The end*request* functions should be used if only if the request has come down from block/bio path, not for direct access requests which only specify rq->buffer without a valid rq->bio) -3.2.5 Generic request command tagging - -3.2.5.1 Tag helpers - -Block now offers some simple generic functionality to help support command -queueing (typically known as tagged command queueing), ie manage more than -one outstanding command on a queue at any given time. - - blk_queue_init_tags(struct request_queue *q, int depth) - - Initialize internal command tagging structures for a maximum - depth of 'depth'. - - blk_queue_free_tags((struct request_queue *q) - - Teardown tag info associated with the queue. This will be done - automatically by block if blk_queue_cleanup() is called on a queue - that is using tagging. - -The above are initialization and exit management, the main helpers during -normal operations are: - - blk_queue_start_tag(struct request_queue *q, struct request *rq) - - Start tagged operation for this request. A free tag number between - 0 and 'depth' is assigned to the request (rq->tag holds this number), - and 'rq' is added to the internal tag management. If the maximum depth - for this queue is already achieved (or if the tag wasn't started for - some other reason), 1 is returned. Otherwise 0 is returned. - - blk_queue_end_tag(struct request_queue *q, struct request *rq) - - End tagged operation on this request. 'rq' is removed from the internal - book keeping structures. - -To minimize struct request and queue overhead, the tag helpers utilize some -of the same request members that are used for normal request queue management. -This means that a request cannot both be an active tag and be on the queue -list at the same time. blk_queue_start_tag() will remove the request, but -the driver must remember to call blk_queue_end_tag() before signalling -completion of the request to the block layer. This means ending tag -operations before calling end_that_request_last()! For an example of a user -of these helpers, see the IDE tagged command queueing support. - -3.2.5.2 Tag info - -Some block functions exist to query current tag status or to go from a -tag number to the associated request. These are, in no particular order: - - blk_queue_tagged(q) - - Returns 1 if the queue 'q' is using tagging, 0 if not. - - blk_queue_tag_request(q, tag) - - Returns a pointer to the request associated with tag 'tag'. - - blk_queue_tag_depth(q) - - Return current queue depth. - - blk_queue_tag_queue(q) - - Returns 1 if the queue can accept a new queued command, 0 if we are - at the maximum depth already. - - blk_queue_rq_tagged(rq) - - Returns 1 if the request 'rq' is tagged. - -3.2.5.2 Internal structure - -Internally, block manages tags in the blk_queue_tag structure: - - struct blk_queue_tag { - struct request **tag_index; /* array or pointers to rq */ - unsigned long *tag_map; /* bitmap of free tags */ - struct list_head busy_list; /* fifo list of busy tags */ - int busy; /* queue depth */ - int max_depth; /* max queue depth */ - }; - -Most of the above is simple and straight forward, however busy_list may need -a bit of explaining. Normally we don't care too much about request ordering, -but in the event of any barrier requests in the tag queue we need to ensure -that requests are restarted in the order they were queue. - 3.3 I/O Submission The routine submit_bio() is used to submit a single io. Higher level i/o diff --git a/Documentation/block/biovecs.txt b/Documentation/block/biovecs.txt index 25689584e6e0..ce6eccaf5df7 100644 --- a/Documentation/block/biovecs.txt +++ b/Documentation/block/biovecs.txt @@ -117,3 +117,28 @@ Other implications: size limitations and the limitations of the underlying devices. Thus there's no need to define ->merge_bvec_fn() callbacks for individual block drivers. + +Usage of helpers: +================= + +* The following helpers whose names have the suffix of "_all" can only be used +on non-BIO_CLONED bio. They are usually used by filesystem code. Drivers +shouldn't use them because the bio may have been split before it reached the +driver. + + bio_for_each_segment_all() + bio_first_bvec_all() + bio_first_page_all() + bio_last_bvec_all() + +* The following helpers iterate over single-page segment. The passed 'struct +bio_vec' will contain a single-page IO vector during the iteration + + bio_for_each_segment() + bio_for_each_segment_all() + +* The following helpers iterate over multi-page bvec. The passed 'struct +bio_vec' will contain a multi-page IO vector during the iteration + + bio_for_each_bvec() + rq_for_each_bvec() diff --git a/Documentation/block/cfq-iosched.txt b/Documentation/block/cfq-iosched.txt deleted file mode 100644 index 895bd3813115..000000000000 --- a/Documentation/block/cfq-iosched.txt +++ /dev/null @@ -1,291 +0,0 @@ -CFQ (Complete Fairness Queueing) -=============================== - -The main aim of CFQ scheduler is to provide a fair allocation of the disk -I/O bandwidth for all the processes which requests an I/O operation. - -CFQ maintains the per process queue for the processes which request I/O -operation(synchronous requests). In case of asynchronous requests, all the -requests from all the processes are batched together according to their -process's I/O priority. - -CFQ ioscheduler tunables -======================== - -slice_idle ----------- -This specifies how long CFQ should idle for next request on certain cfq queues -(for sequential workloads) and service trees (for random workloads) before -queue is expired and CFQ selects next queue to dispatch from. - -By default slice_idle is a non-zero value. That means by default we idle on -queues/service trees. This can be very helpful on highly seeky media like -single spindle SATA/SAS disks where we can cut down on overall number of -seeks and see improved throughput. - -Setting slice_idle to 0 will remove all the idling on queues/service tree -level and one should see an overall improved throughput on faster storage -devices like multiple SATA/SAS disks in hardware RAID configuration. The down -side is that isolation provided from WRITES also goes down and notion of -IO priority becomes weaker. - -So depending on storage and workload, it might be useful to set slice_idle=0. -In general I think for SATA/SAS disks and software RAID of SATA/SAS disks -keeping slice_idle enabled should be useful. For any configurations where -there are multiple spindles behind single LUN (Host based hardware RAID -controller or for storage arrays), setting slice_idle=0 might end up in better -throughput and acceptable latencies. - -back_seek_max -------------- -This specifies, given in Kbytes, the maximum "distance" for backward seeking. -The distance is the amount of space from the current head location to the -sectors that are backward in terms of distance. - -This parameter allows the scheduler to anticipate requests in the "backward" -direction and consider them as being the "next" if they are within this -distance from the current head location. - -back_seek_penalty ------------------ -This parameter is used to compute the cost of backward seeking. If the -backward distance of request is just 1/back_seek_penalty from a "front" -request, then the seeking cost of two requests is considered equivalent. - -So scheduler will not bias toward one or the other request (otherwise scheduler -will bias toward front request). Default value of back_seek_penalty is 2. - -fifo_expire_async ------------------ -This parameter is used to set the timeout of asynchronous requests. Default -value of this is 248ms. - -fifo_expire_sync ----------------- -This parameter is used to set the timeout of synchronous requests. Default -value of this is 124ms. In case to favor synchronous requests over asynchronous -one, this value should be decreased relative to fifo_expire_async. - -group_idle ------------ -This parameter forces idling at the CFQ group level instead of CFQ -queue level. This was introduced after a bottleneck was observed -in higher end storage due to idle on sequential queue and allow dispatch -from a single queue. The idea with this parameter is that it can be run with -slice_idle=0 and group_idle=8, so that idling does not happen on individual -queues in the group but happens overall on the group and thus still keeps the -IO controller working. -Not idling on individual queues in the group will dispatch requests from -multiple queues in the group at the same time and achieve higher throughput -on higher end storage. - -Default value for this parameter is 8ms. - -low_latency ------------ -This parameter is used to enable/disable the low latency mode of the CFQ -scheduler. If enabled, CFQ tries to recompute the slice time for each process -based on the target_latency set for the system. This favors fairness over -throughput. Disabling low latency (setting it to 0) ignores target latency, -allowing each process in the system to get a full time slice. - -By default low latency mode is enabled. - -target_latency --------------- -This parameter is used to calculate the time slice for a process if cfq's -latency mode is enabled. It will ensure that sync requests have an estimated -latency. But if sequential workload is higher(e.g. sequential read), -then to meet the latency constraints, throughput may decrease because of less -time for each process to issue I/O request before the cfq queue is switched. - -Though this can be overcome by disabling the latency_mode, it may increase -the read latency for some applications. This parameter allows for changing -target_latency through the sysfs interface which can provide the balanced -throughput and read latency. - -Default value for target_latency is 300ms. - -slice_async ------------ -This parameter is same as of slice_sync but for asynchronous queue. The -default value is 40ms. - -slice_async_rq --------------- -This parameter is used to limit the dispatching of asynchronous request to -device request queue in queue's slice time. The maximum number of request that -are allowed to be dispatched also depends upon the io priority. Default value -for this is 2. - -slice_sync ----------- -When a queue is selected for execution, the queues IO requests are only -executed for a certain amount of time(time_slice) before switching to another -queue. This parameter is used to calculate the time slice of synchronous -queue. - -time_slice is computed using the below equation:- -time_slice = slice_sync + (slice_sync/5 * (4 - prio)). To increase the -time_slice of synchronous queue, increase the value of slice_sync. Default -value is 100ms. - -quantum -------- -This specifies the number of request dispatched to the device queue. In a -queue's time slice, a request will not be dispatched if the number of request -in the device exceeds this parameter. This parameter is used for synchronous -request. - -In case of storage with several disk, this setting can limit the parallel -processing of request. Therefore, increasing the value can improve the -performance although this can cause the latency of some I/O to increase due -to more number of requests. - -CFQ Group scheduling -==================== - -CFQ supports blkio cgroup and has "blkio." prefixed files in each -blkio cgroup directory. It is weight-based and there are four knobs -for configuration - weight[_device] and leaf_weight[_device]. -Internal cgroup nodes (the ones with children) can also have tasks in -them, so the former two configure how much proportion the cgroup as a -whole is entitled to at its parent's level while the latter two -configure how much proportion the tasks in the cgroup have compared to -its direct children. - -Another way to think about it is assuming that each internal node has -an implicit leaf child node which hosts all the tasks whose weight is -configured by leaf_weight[_device]. Let's assume a blkio hierarchy -composed of five cgroups - root, A, B, AA and AB - with the following -weights where the names represent the hierarchy. - - weight leaf_weight - root : 125 125 - A : 500 750 - B : 250 500 - AA : 500 500 - AB : 1000 500 - -root never has a parent making its weight is meaningless. For backward -compatibility, weight is always kept in sync with leaf_weight. B, AA -and AB have no child and thus its tasks have no children cgroup to -compete with. They always get 100% of what the cgroup won at the -parent level. Considering only the weights which matter, the hierarchy -looks like the following. - - root - / | \ - A B leaf - 500 250 125 - / | \ - AA AB leaf - 500 1000 750 - -If all cgroups have active IOs and competing with each other, disk -time will be distributed like the following. - -Distribution below root. The total active weight at this level is -A:500 + B:250 + C:125 = 875. - - root-leaf : 125 / 875 =~ 14% - A : 500 / 875 =~ 57% - B(-leaf) : 250 / 875 =~ 28% - -A has children and further distributes its 57% among the children and -the implicit leaf node. The total active weight at this level is -AA:500 + AB:1000 + A-leaf:750 = 2250. - - A-leaf : ( 750 / 2250) * A =~ 19% - AA(-leaf) : ( 500 / 2250) * A =~ 12% - AB(-leaf) : (1000 / 2250) * A =~ 25% - -CFQ IOPS Mode for group scheduling -=================================== -Basic CFQ design is to provide priority based time slices. Higher priority -process gets bigger time slice and lower priority process gets smaller time -slice. Measuring time becomes harder if storage is fast and supports NCQ and -it would be better to dispatch multiple requests from multiple cfq queues in -request queue at a time. In such scenario, it is not possible to measure time -consumed by single queue accurately. - -What is possible though is to measure number of requests dispatched from a -single queue and also allow dispatch from multiple cfq queue at the same time. -This effectively becomes the fairness in terms of IOPS (IO operations per -second). - -If one sets slice_idle=0 and if storage supports NCQ, CFQ internally switches -to IOPS mode and starts providing fairness in terms of number of requests -dispatched. Note that this mode switching takes effect only for group -scheduling. For non-cgroup users nothing should change. - -CFQ IO scheduler Idling Theory -=============================== -Idling on a queue is primarily about waiting for the next request to come -on same queue after completion of a request. In this process CFQ will not -dispatch requests from other cfq queues even if requests are pending there. - -The rationale behind idling is that it can cut down on number of seeks -on rotational media. For example, if a process is doing dependent -sequential reads (next read will come on only after completion of previous -one), then not dispatching request from other queue should help as we -did not move the disk head and kept on dispatching sequential IO from -one queue. - -CFQ has following service trees and various queues are put on these trees. - - sync-idle sync-noidle async - -All cfq queues doing synchronous sequential IO go on to sync-idle tree. -On this tree we idle on each queue individually. - -All synchronous non-sequential queues go on sync-noidle tree. Also any -synchronous write request which is not marked with REQ_IDLE goes on this -service tree. On this tree we do not idle on individual queues instead idle -on the whole group of queues or the tree. So if there are 4 queues waiting -for IO to dispatch we will idle only once last queue has dispatched the IO -and there is no more IO on this service tree. - -All async writes go on async service tree. There is no idling on async -queues. - -CFQ has some optimizations for SSDs and if it detects a non-rotational -media which can support higher queue depth (multiple requests at in -flight at a time), then it cuts down on idling of individual queues and -all the queues move to sync-noidle tree and only tree idle remains. This -tree idling provides isolation with buffered write queues on async tree. - -FAQ -=== -Q1. Why to idle at all on queues not marked with REQ_IDLE. - -A1. We only do tree idle (all queues on sync-noidle tree) on queues not marked - with REQ_IDLE. This helps in providing isolation with all the sync-idle - queues. Otherwise in presence of many sequential readers, other - synchronous IO might not get fair share of disk. - - For example, if there are 10 sequential readers doing IO and they get - 100ms each. If a !REQ_IDLE request comes in, it will be scheduled - roughly after 1 second. If after completion of !REQ_IDLE request we - do not idle, and after a couple of milli seconds a another !REQ_IDLE - request comes in, again it will be scheduled after 1second. Repeat it - and notice how a workload can lose its disk share and suffer due to - multiple sequential readers. - - fsync can generate dependent IO where bunch of data is written in the - context of fsync, and later some journaling data is written. Journaling - data comes in only after fsync has finished its IO (atleast for ext4 - that seemed to be the case). Now if one decides not to idle on fsync - thread due to !REQ_IDLE, then next journaling write will not get - scheduled for another second. A process doing small fsync, will suffer - badly in presence of multiple sequential readers. - - Hence doing tree idling on threads using !REQ_IDLE flag on requests - provides isolation from multiple sequential readers and at the same - time we do not idle on individual threads. - -Q2. When to specify REQ_IDLE -A2. I would think whenever one is doing synchronous write and expecting - more writes to be dispatched from same context soon, should be able - to specify REQ_IDLE on writes and that probably should work well for - most of the cases. diff --git a/Documentation/block/null_blk.txt b/Documentation/block/null_blk.txt index ea2dafe49ae8..4cad1024fff7 100644 --- a/Documentation/block/null_blk.txt +++ b/Documentation/block/null_blk.txt @@ -88,7 +88,8 @@ shared_tags=[0/1]: Default: 0 zoned=[0/1]: Default: 0 0: Block device is exposed as a random-access block device. - 1: Block device is exposed as a host-managed zoned block device. + 1: Block device is exposed as a host-managed zoned block device. Requires + CONFIG_BLK_DEV_ZONED. zone_size=[MB]: Default: 256 Per zone size when exposed as a zoned block device. Must be a power of two. diff --git a/Documentation/block/queue-sysfs.txt b/Documentation/block/queue-sysfs.txt index 2c1e67058fd3..83b457e24bba 100644 --- a/Documentation/block/queue-sysfs.txt +++ b/Documentation/block/queue-sysfs.txt @@ -64,9 +64,16 @@ guess, the kernel will put the process issuing IO to sleep for an amount of time, before entering a classic poll loop. This mode might be a little slower than pure classic polling, but it will be more efficient. If set to a value larger than 0, the kernel will put the process issuing -IO to sleep for this amont of microseconds before entering classic +IO to sleep for this amount of microseconds before entering classic polling. +io_timeout (RW) +--------------- +io_timeout is the request timeout in milliseconds. If a request does not +complete in this time then the block driver timeout handler is invoked. +That timeout handler can decide to retry the request, to fail it or to start +a device recovery strategy. + iostats (RW) ------------- This file is used to control (on/off) the iostats accounting of the @@ -194,4 +201,31 @@ blk-throttle makes decision based on the samplings. Lower time means cgroups have more smooth throughput, but higher CPU overhead. This exists only when CONFIG_BLK_DEV_THROTTLING_LOW is enabled. +zoned (RO) +---------- +This indicates if the device is a zoned block device and the zone model of the +device if it is indeed zoned. The possible values indicated by zoned are +"none" for regular block devices and "host-aware" or "host-managed" for zoned +block devices. The characteristics of host-aware and host-managed zoned block +devices are described in the ZBC (Zoned Block Commands) and ZAC +(Zoned Device ATA Command Set) standards. These standards also define the +"drive-managed" zone model. However, since drive-managed zoned block devices +do not support zone commands, they will be treated as regular block devices +and zoned will report "none". + +nr_zones (RO) +------------- +For zoned block devices (zoned attribute indicating "host-managed" or +"host-aware"), this indicates the total number of zones of the device. +This is always 0 for regular block devices. + +chunk_sectors (RO) +------------------ +This has different meaning depending on the type of the block device. +For a RAID device (dm-raid), chunk_sectors indicates the size in 512B sectors +of the RAID volume stripe segment. For a zoned block device, either host-aware +or host-managed, chunk_sectors indicates the size in 512B sectors of the zones +of the device, with the eventual exception of the last zone of the device which +may be smaller. + Jens Axboe <jens.axboe@oracle.com>, February 2009 diff --git a/Documentation/blockdev/zram.txt b/Documentation/blockdev/zram.txt index 3c1b5ab54bc0..4df0ce271085 100644 --- a/Documentation/blockdev/zram.txt +++ b/Documentation/blockdev/zram.txt @@ -156,19 +156,23 @@ Per-device statistics are exported as various nodes under /sys/block/zram<id>/ A brief description of exported device attributes. For more details please read Documentation/ABI/testing/sysfs-block-zram. -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 -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 -compact WO trigger memory compaction -debug_stat RO this file is used for zram debugging purposes -backing_dev RW set up backend storage for zram to write out +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 +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 +writeback_limit WO specifies the maximum amount of write IO zram can + write out to backing device as 4KB unit +writeback_limit_enable RW show and set writeback_limit feature +max_comp_streams RW the number of possible concurrent compress operations +comp_algorithm RW show and change the compression algorithm +compact WO trigger memory compaction +debug_stat RO this file is used for zram debugging purposes +backing_dev RW set up backend storage for zram to write out +idle WO mark allocated slot as idle User space is advised to use the following files to read the device statistics. @@ -220,6 +224,17 @@ line of text and contains the following stats separated by whitespace: pages_compacted the number of pages freed during compaction huge_pages the number of incompressible pages +File /sys/block/zram<id>/bd_stat + +The stat file represents device's backing device statistics. It consists of +a single line of text and contains the following stats separated by whitespace: + bd_count size of data written in backing device. + Unit: 4K bytes + bd_reads the number of reads from backing device + Unit: 4K bytes + bd_writes the number of writes to backing device + Unit: 4K bytes + 9) Deactivate: swapoff /dev/zram0 umount /dev/zram1 @@ -237,11 +252,79 @@ line of text and contains the following stats separated by whitespace: = writeback -With incompressible pages, there is no memory saving with zram. -Instead, with CONFIG_ZRAM_WRITEBACK, zram can write incompressible page +With CONFIG_ZRAM_WRITEBACK, zram can write idle/incompressible page to backing storage rather than keeping it in memory. -User should set up backing device via /sys/block/zramX/backing_dev -before disksize setting. +To use the feature, admin should set up backing device via + + "echo /dev/sda5 > /sys/block/zramX/backing_dev" + +before disksize setting. It supports only partition at this moment. +If admin want to use incompressible page writeback, they could do via + + "echo huge > /sys/block/zramX/write" + +To use idle page writeback, first, user need to declare zram pages +as idle. + + "echo all > /sys/block/zramX/idle" + +From now on, any pages on zram are idle pages. The idle mark +will be removed until someone request access of the block. +IOW, unless there is access request, those pages are still idle pages. + +Admin can request writeback of those idle pages at right timing via + + "echo idle > /sys/block/zramX/writeback" + +With the command, zram writeback idle pages from memory to the storage. + +If there are lots of write IO with flash device, potentially, it has +flash wearout problem so that admin needs to design write limitation +to guarantee storage health for entire product life. + +To overcome the concern, zram supports "writeback_limit" feature. +The "writeback_limit_enable"'s default value is 0 so that it doesn't limit +any writeback. IOW, if admin want to apply writeback budget, he should +enable writeback_limit_enable via + + $ echo 1 > /sys/block/zramX/writeback_limit_enable + +Once writeback_limit_enable is set, zram doesn't allow any writeback +until admin set the budget via /sys/block/zramX/writeback_limit. + +(If admin doesn't enable writeback_limit_enable, writeback_limit's value +assigned via /sys/block/zramX/writeback_limit is meaninless.) + +If admin want to limit writeback as per-day 400M, he could do it +like below. + + $ MB_SHIFT=20 + $ 4K_SHIFT=12 + $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ + /sys/block/zram0/writeback_limit. + $ echo 1 > /sys/block/zram0/writeback_limit_enable + +If admin want to allow further write again once the bugdet is exausted, +he could do it like below + + $ echo $((400<<MB_SHIFT>>4K_SHIFT)) > \ + /sys/block/zram0/writeback_limit + +If admin want to see remaining writeback budget since he set, + + $ cat /sys/block/zramX/writeback_limit + +If admin want to disable writeback limit, he could do + + $ echo 0 > /sys/block/zramX/writeback_limit_enable + +The writeback_limit count will reset whenever you reset zram(e.g., +system reboot, echo 1 > /sys/block/zramX/reset) so keeping how many of +writeback happened until you reset the zram to allocate extra writeback +budget in next setting is user's job. + +If admin want to measure writeback count in a certain period, he could +know it via /sys/block/zram0/bd_stat's 3rd column. = memory tracking @@ -251,16 +334,17 @@ pages of the process with*pagemap. If you enable the feature, you could see block state via /sys/kernel/debug/zram/zram0/block_state". The output is as follows, - 300 75.033841 .wh - 301 63.806904 s.. - 302 63.806919 ..h + 300 75.033841 .wh. + 301 63.806904 s... + 302 63.806919 ..hi First column is zram's block index. Second column is access time since the system was booted Third column is state of the block. (s: same page w: written page to backing store -h: huge page) +h: huge page +i: idle page) First line of above example says 300th block is accessed at 75.033841sec and the block's state is huge so it is written back to the backing diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst index 6780a6d81745..10453c627135 100644 --- a/Documentation/bpf/bpf_design_QA.rst +++ b/Documentation/bpf/bpf_design_QA.rst @@ -36,27 +36,27 @@ consideration important quirks of other architectures) and defines calling convention that is compatible with C calling convention of the linux kernel on those architectures. -Q: can multiple return values be supported in the future? +Q: Can multiple return values be supported in the future? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A: NO. BPF allows only register R0 to be used as return value. -Q: can more than 5 function arguments be supported in the future? +Q: Can more than 5 function arguments be supported in the future? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A: NO. BPF calling convention only allows registers R1-R5 to be used as arguments. BPF is not a standalone instruction set. (unlike x64 ISA that allows msft, cdecl and other conventions) -Q: can BPF programs access instruction pointer or return address? +Q: Can BPF programs access instruction pointer or return address? ----------------------------------------------------------------- A: NO. -Q: can BPF programs access stack pointer ? +Q: Can BPF programs access stack pointer ? ------------------------------------------ A: NO. Only frame pointer (register R10) is accessible. From compiler point of view it's necessary to have stack pointer. -For example LLVM defines register R11 as stack pointer in its +For example, LLVM defines register R11 as stack pointer in its BPF backend, but it makes sure that generated code never uses it. Q: Does C-calling convention diminishes possible use cases? @@ -66,8 +66,8 @@ A: YES. BPF design forces addition of major functionality in the form of kernel helper functions and kernel objects like BPF maps with seamless interoperability between them. It lets kernel call into -BPF programs and programs call kernel helpers with zero overhead. -As all of them were native C code. That is particularly the case +BPF programs and programs call kernel helpers with zero overhead, +as all of them were native C code. That is particularly the case for JITed BPF programs that are indistinguishable from native kernel C code. @@ -75,9 +75,9 @@ Q: Does it mean that 'innovative' extensions to BPF code are disallowed? ------------------------------------------------------------------------ A: Soft yes. -At least for now until BPF core has support for +At least for now, until BPF core has support for bpf-to-bpf calls, indirect calls, loops, global variables, -jump tables, read only sections and all other normal constructs +jump tables, read-only sections, and all other normal constructs that C code can produce. Q: Can loops be supported in a safe way? @@ -109,16 +109,16 @@ For example why BPF_JNE and other compare and jumps are not cpu-like? A: This was necessary to avoid introducing flags into ISA which are impossible to make generic and efficient across CPU architectures. -Q: why BPF_DIV instruction doesn't map to x64 div? +Q: Why BPF_DIV instruction doesn't map to x64 div? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A: Because if we picked one-to-one relationship to x64 it would have made it more complicated to support on arm64 and other archs. Also it needs div-by-zero runtime check. -Q: why there is no BPF_SDIV for signed divide operation? +Q: Why there is no BPF_SDIV for signed divide operation? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A: Because it would be rarely used. llvm errors in such case and -prints a suggestion to use unsigned divide instead +prints a suggestion to use unsigned divide instead. Q: Why BPF has implicit prologue and epilogue? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -157,12 +157,11 @@ Q: Does BPF have a stable ABI? ------------------------------ A: YES. BPF instructions, arguments to BPF programs, set of helper functions and their arguments, recognized return codes are all part -of ABI. However when tracing programs are using bpf_probe_read() helper -to walk kernel internal datastructures and compile with kernel -internal headers these accesses can and will break with newer -kernels. The union bpf_attr -> kern_version is checked at load time -to prevent accidentally loading kprobe-based bpf programs written -for a different kernel. Networking programs don't do kern_version check. +of ABI. However there is one specific exception to tracing programs +which are using helpers like bpf_probe_read() to walk kernel internal +data structures and compile with kernel internal headers. Both of these +kernel internals are subject to change and can break with newer kernels +such that the program needs to be adapted accordingly. Q: How much stack space a BPF program uses? ------------------------------------------- diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst new file mode 100644 index 000000000000..9a60a5d60e38 --- /dev/null +++ b/Documentation/bpf/btf.rst @@ -0,0 +1,848 @@ +===================== +BPF Type Format (BTF) +===================== + +1. Introduction +*************** + +BTF (BPF Type Format) is the metadata format which encodes the debug info +related to BPF program/map. The name BTF was used initially to describe data +types. The BTF was later extended to include function info for defined +subroutines, and line info for source/line information. + +The debug info is used for map pretty print, function signature, etc. The +function signature enables better bpf program/function kernel symbol. The line +info helps generate source annotated translated byte code, jited code and +verifier log. + +The BTF specification contains two parts, + * BTF kernel API + * BTF ELF file format + +The kernel API is the contract between user space and kernel. The kernel +verifies the BTF info before using it. The ELF file format is a user space +contract between ELF file and libbpf loader. + +The type and string sections are part of the BTF kernel API, describing the +debug info (mostly types related) referenced by the bpf program. These two +sections are discussed in details in :ref:`BTF_Type_String`. + +.. _BTF_Type_String: + +2. BTF Type and String Encoding +******************************* + +The file ``include/uapi/linux/btf.h`` provides high-level definition of how +types/strings are encoded. + +The beginning of data blob must be:: + + struct btf_header { + __u16 magic; + __u8 version; + __u8 flags; + __u32 hdr_len; + + /* All offsets are in bytes relative to the end of this header */ + __u32 type_off; /* offset of type section */ + __u32 type_len; /* length of type section */ + __u32 str_off; /* offset of string section */ + __u32 str_len; /* length of string section */ + }; + +The magic is ``0xeB9F``, which has different encoding for big and little +endian systems, and can be used to test whether BTF is generated for big- or +little-endian target. The ``btf_header`` is designed to be extensible with +``hdr_len`` equal to ``sizeof(struct btf_header)`` when a data blob is +generated. + +2.1 String Encoding +=================== + +The first string in the string section must be a null string. The rest of +string table is a concatenation of other null-terminated strings. + +2.2 Type Encoding +================= + +The type id ``0`` is reserved for ``void`` type. The type section is parsed +sequentially and type id is assigned to each recognized type starting from id +``1``. Currently, the following types are supported:: + + #define BTF_KIND_INT 1 /* Integer */ + #define BTF_KIND_PTR 2 /* Pointer */ + #define BTF_KIND_ARRAY 3 /* Array */ + #define BTF_KIND_STRUCT 4 /* Struct */ + #define BTF_KIND_UNION 5 /* Union */ + #define BTF_KIND_ENUM 6 /* Enumeration */ + #define BTF_KIND_FWD 7 /* Forward */ + #define BTF_KIND_TYPEDEF 8 /* Typedef */ + #define BTF_KIND_VOLATILE 9 /* Volatile */ + #define BTF_KIND_CONST 10 /* Const */ + #define BTF_KIND_RESTRICT 11 /* Restrict */ + #define BTF_KIND_FUNC 12 /* Function */ + #define BTF_KIND_FUNC_PROTO 13 /* Function Proto */ + +Note that the type section encodes debug info, not just pure types. +``BTF_KIND_FUNC`` is not a type, and it represents a defined subprogram. + +Each type contains the following common data:: + + struct btf_type { + __u32 name_off; + /* "info" bits arrangement + * bits 0-15: vlen (e.g. # of struct's members) + * bits 16-23: unused + * bits 24-27: kind (e.g. int, ptr, array...etc) + * bits 28-30: unused + * bit 31: kind_flag, currently used by + * struct, union and fwd + */ + __u32 info; + /* "size" is used by INT, ENUM, STRUCT and UNION. + * "size" tells the size of the type it is describing. + * + * "type" is used by PTR, TYPEDEF, VOLATILE, CONST, RESTRICT, + * FUNC and FUNC_PROTO. + * "type" is a type_id referring to another type. + */ + union { + __u32 size; + __u32 type; + }; + }; + +For certain kinds, the common data are followed by kind-specific data. The +``name_off`` in ``struct btf_type`` specifies the offset in the string table. +The following sections detail encoding of each kind. + +2.2.1 BTF_KIND_INT +~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: any valid offset + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_INT + * ``info.vlen``: 0 + * ``size``: the size of the int type in bytes. + +``btf_type`` is followed by a ``u32`` with the following bits arrangement:: + + #define BTF_INT_ENCODING(VAL) (((VAL) & 0x0f000000) >> 24) + #define BTF_INT_OFFSET(VAL) (((VAL & 0x00ff0000)) >> 16) + #define BTF_INT_BITS(VAL) ((VAL) & 0x000000ff) + +The ``BTF_INT_ENCODING`` has the following attributes:: + + #define BTF_INT_SIGNED (1 << 0) + #define BTF_INT_CHAR (1 << 1) + #define BTF_INT_BOOL (1 << 2) + +The ``BTF_INT_ENCODING()`` provides extra information: signedness, char, or +bool, for the int type. The char and bool encoding are mostly useful for +pretty print. At most one encoding can be specified for the int type. + +The ``BTF_INT_BITS()`` specifies the number of actual bits held by this int +type. For example, a 4-bit bitfield encodes ``BTF_INT_BITS()`` equals to 4. +The ``btf_type.size * 8`` must be equal to or greater than ``BTF_INT_BITS()`` +for the type. The maximum value of ``BTF_INT_BITS()`` is 128. + +The ``BTF_INT_OFFSET()`` specifies the starting bit offset to calculate values +for this int. For example, a bitfield struct member has: * btf member bit +offset 100 from the start of the structure, * btf member pointing to an int +type, * the int type has ``BTF_INT_OFFSET() = 2`` and ``BTF_INT_BITS() = 4`` + +Then in the struct memory layout, this member will occupy ``4`` bits starting +from bits ``100 + 2 = 102``. + +Alternatively, the bitfield struct member can be the following to access the +same bits as the above: + + * btf member bit offset 102, + * btf member pointing to an int type, + * the int type has ``BTF_INT_OFFSET() = 0`` and ``BTF_INT_BITS() = 4`` + +The original intention of ``BTF_INT_OFFSET()`` is to provide flexibility of +bitfield encoding. Currently, both llvm and pahole generate +``BTF_INT_OFFSET() = 0`` for all int types. + +2.2.2 BTF_KIND_PTR +~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_PTR + * ``info.vlen``: 0 + * ``type``: the pointee type of the pointer + +No additional type data follow ``btf_type``. + +2.2.3 BTF_KIND_ARRAY +~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_ARRAY + * ``info.vlen``: 0 + * ``size/type``: 0, not used + +``btf_type`` is followed by one ``struct btf_array``:: + + struct btf_array { + __u32 type; + __u32 index_type; + __u32 nelems; + }; + +The ``struct btf_array`` encoding: + * ``type``: the element type + * ``index_type``: the index type + * ``nelems``: the number of elements for this array (``0`` is also allowed). + +The ``index_type`` can be any regular int type (``u8``, ``u16``, ``u32``, +``u64``, ``unsigned __int128``). The original design of including +``index_type`` follows DWARF, which has an ``index_type`` for its array type. +Currently in BTF, beyond type verification, the ``index_type`` is not used. + +The ``struct btf_array`` allows chaining through element type to represent +multidimensional arrays. For example, for ``int a[5][6]``, the following type +information illustrates the chaining: + + * [1]: int + * [2]: array, ``btf_array.type = [1]``, ``btf_array.nelems = 6`` + * [3]: array, ``btf_array.type = [2]``, ``btf_array.nelems = 5`` + +Currently, both pahole and llvm collapse multidimensional array into +one-dimensional array, e.g., for ``a[5][6]``, the ``btf_array.nelems`` is +equal to ``30``. This is because the original use case is map pretty print +where the whole array is dumped out so one-dimensional array is enough. As +more BTF usage is explored, pahole and llvm can be changed to generate proper +chained representation for multidimensional arrays. + +2.2.4 BTF_KIND_STRUCT +~~~~~~~~~~~~~~~~~~~~~ +2.2.5 BTF_KIND_UNION +~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 or offset to a valid C identifier + * ``info.kind_flag``: 0 or 1 + * ``info.kind``: BTF_KIND_STRUCT or BTF_KIND_UNION + * ``info.vlen``: the number of struct/union members + * ``info.size``: the size of the struct/union in bytes + +``btf_type`` is followed by ``info.vlen`` number of ``struct btf_member``.:: + + struct btf_member { + __u32 name_off; + __u32 type; + __u32 offset; + }; + +``struct btf_member`` encoding: + * ``name_off``: offset to a valid C identifier + * ``type``: the member type + * ``offset``: <see below> + +If the type info ``kind_flag`` is not set, the offset contains only bit offset +of the member. Note that the base type of the bitfield can only be int or enum +type. If the bitfield size is 32, the base type can be either int or enum +type. If the bitfield size is not 32, the base type must be int, and int type +``BTF_INT_BITS()`` encodes the bitfield size. + +If the ``kind_flag`` is set, the ``btf_member.offset`` contains both member +bitfield size and bit offset. The bitfield size and bit offset are calculated +as below.:: + + #define BTF_MEMBER_BITFIELD_SIZE(val) ((val) >> 24) + #define BTF_MEMBER_BIT_OFFSET(val) ((val) & 0xffffff) + +In this case, if the base type is an int type, it must be a regular int type: + + * ``BTF_INT_OFFSET()`` must be 0. + * ``BTF_INT_BITS()`` must be equal to ``{1,2,4,8,16} * 8``. + +The following kernel patch introduced ``kind_flag`` and explained why both +modes exist: + + https://github.com/torvalds/linux/commit/9d5f9f701b1891466fb3dbb1806ad97716f95cc3#diff-fa650a64fdd3968396883d2fe8215ff3 + +2.2.6 BTF_KIND_ENUM +~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 or offset to a valid C identifier + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_ENUM + * ``info.vlen``: number of enum values + * ``size``: 4 + +``btf_type`` is followed by ``info.vlen`` number of ``struct btf_enum``.:: + + struct btf_enum { + __u32 name_off; + __s32 val; + }; + +The ``btf_enum`` encoding: + * ``name_off``: offset to a valid C identifier + * ``val``: any value + +2.2.7 BTF_KIND_FWD +~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a valid C identifier + * ``info.kind_flag``: 0 for struct, 1 for union + * ``info.kind``: BTF_KIND_FWD + * ``info.vlen``: 0 + * ``type``: 0 + +No additional type data follow ``btf_type``. + +2.2.8 BTF_KIND_TYPEDEF +~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a valid C identifier + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_TYPEDEF + * ``info.vlen``: 0 + * ``type``: the type which can be referred by name at ``name_off`` + +No additional type data follow ``btf_type``. + +2.2.9 BTF_KIND_VOLATILE +~~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_VOLATILE + * ``info.vlen``: 0 + * ``type``: the type with ``volatile`` qualifier + +No additional type data follow ``btf_type``. + +2.2.10 BTF_KIND_CONST +~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_CONST + * ``info.vlen``: 0 + * ``type``: the type with ``const`` qualifier + +No additional type data follow ``btf_type``. + +2.2.11 BTF_KIND_RESTRICT +~~~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_RESTRICT + * ``info.vlen``: 0 + * ``type``: the type with ``restrict`` qualifier + +No additional type data follow ``btf_type``. + +2.2.12 BTF_KIND_FUNC +~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: offset to a valid C identifier + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_FUNC + * ``info.vlen``: 0 + * ``type``: a BTF_KIND_FUNC_PROTO type + +No additional type data follow ``btf_type``. + +A BTF_KIND_FUNC defines not a type, but a subprogram (function) whose +signature is defined by ``type``. The subprogram is thus an instance of that +type. The BTF_KIND_FUNC may in turn be referenced by a func_info in the +:ref:`BTF_Ext_Section` (ELF) or in the arguments to :ref:`BPF_Prog_Load` +(ABI). + +2.2.13 BTF_KIND_FUNC_PROTO +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``struct btf_type`` encoding requirement: + * ``name_off``: 0 + * ``info.kind_flag``: 0 + * ``info.kind``: BTF_KIND_FUNC_PROTO + * ``info.vlen``: # of parameters + * ``type``: the return type + +``btf_type`` is followed by ``info.vlen`` number of ``struct btf_param``.:: + + struct btf_param { + __u32 name_off; + __u32 type; + }; + +If a BTF_KIND_FUNC_PROTO type is referred by a BTF_KIND_FUNC type, then +``btf_param.name_off`` must point to a valid C identifier except for the +possible last argument representing the variable argument. The btf_param.type +refers to parameter type. + +If the function has variable arguments, the last parameter is encoded with +``name_off = 0`` and ``type = 0``. + +3. BTF Kernel API +***************** + +The following bpf syscall command involves BTF: + * BPF_BTF_LOAD: load a blob of BTF data into kernel + * BPF_MAP_CREATE: map creation with btf key and value type info. + * BPF_PROG_LOAD: prog load with btf function and line info. + * BPF_BTF_GET_FD_BY_ID: get a btf fd + * BPF_OBJ_GET_INFO_BY_FD: btf, func_info, line_info + and other btf related info are returned. + +The workflow typically looks like: +:: + + Application: + BPF_BTF_LOAD + | + v + BPF_MAP_CREATE and BPF_PROG_LOAD + | + V + ...... + + Introspection tool: + ...... + BPF_{PROG,MAP}_GET_NEXT_ID (get prog/map id's) + | + V + BPF_{PROG,MAP}_GET_FD_BY_ID (get a prog/map fd) + | + V + BPF_OBJ_GET_INFO_BY_FD (get bpf_prog_info/bpf_map_info with btf_id) + | | + V | + BPF_BTF_GET_FD_BY_ID (get btf_fd) | + | | + V | + BPF_OBJ_GET_INFO_BY_FD (get btf) | + | | + V V + pretty print types, dump func signatures and line info, etc. + + +3.1 BPF_BTF_LOAD +================ + +Load a blob of BTF data into kernel. A blob of data, described in +:ref:`BTF_Type_String`, can be directly loaded into the kernel. A ``btf_fd`` +is returned to a userspace. + +3.2 BPF_MAP_CREATE +================== + +A map can be created with ``btf_fd`` and specified key/value type id.:: + + __u32 btf_fd; /* fd pointing to a BTF type data */ + __u32 btf_key_type_id; /* BTF type_id of the key */ + __u32 btf_value_type_id; /* BTF type_id of the value */ + +In libbpf, the map can be defined with extra annotation like below: +:: + + struct bpf_map_def SEC("maps") btf_map = { + .type = BPF_MAP_TYPE_ARRAY, + .key_size = sizeof(int), + .value_size = sizeof(struct ipv_counts), + .max_entries = 4, + }; + BPF_ANNOTATE_KV_PAIR(btf_map, int, struct ipv_counts); + +Here, the parameters for macro BPF_ANNOTATE_KV_PAIR are map name, key and +value types for the map. During ELF parsing, libbpf is able to extract +key/value type_id's and assign them to BPF_MAP_CREATE attributes +automatically. + +.. _BPF_Prog_Load: + +3.3 BPF_PROG_LOAD +================= + +During prog_load, func_info and line_info can be passed to kernel with proper +values for the following attributes: +:: + + __u32 insn_cnt; + __aligned_u64 insns; + ...... + __u32 prog_btf_fd; /* fd pointing to BTF type data */ + __u32 func_info_rec_size; /* userspace bpf_func_info size */ + __aligned_u64 func_info; /* func info */ + __u32 func_info_cnt; /* number of bpf_func_info records */ + __u32 line_info_rec_size; /* userspace bpf_line_info size */ + __aligned_u64 line_info; /* line info */ + __u32 line_info_cnt; /* number of bpf_line_info records */ + +The func_info and line_info are an array of below, respectively.:: + + struct bpf_func_info { + __u32 insn_off; /* [0, insn_cnt - 1] */ + __u32 type_id; /* pointing to a BTF_KIND_FUNC type */ + }; + struct bpf_line_info { + __u32 insn_off; /* [0, insn_cnt - 1] */ + __u32 file_name_off; /* offset to string table for the filename */ + __u32 line_off; /* offset to string table for the source line */ + __u32 line_col; /* line number and column number */ + }; + +func_info_rec_size is the size of each func_info record, and +line_info_rec_size is the size of each line_info record. Passing the record +size to kernel make it possible to extend the record itself in the future. + +Below are requirements for func_info: + * func_info[0].insn_off must be 0. + * the func_info insn_off is in strictly increasing order and matches + bpf func boundaries. + +Below are requirements for line_info: + * the first insn in each func must have a line_info record pointing to it. + * the line_info insn_off is in strictly increasing order. + +For line_info, the line number and column number are defined as below: +:: + + #define BPF_LINE_INFO_LINE_NUM(line_col) ((line_col) >> 10) + #define BPF_LINE_INFO_LINE_COL(line_col) ((line_col) & 0x3ff) + +3.4 BPF_{PROG,MAP}_GET_NEXT_ID + +In kernel, every loaded program, map or btf has a unique id. The id won't +change during the lifetime of a program, map, or btf. + +The bpf syscall command BPF_{PROG,MAP}_GET_NEXT_ID returns all id's, one for +each command, to user space, for bpf program or maps, respectively, so an +inspection tool can inspect all programs and maps. + +3.5 BPF_{PROG,MAP}_GET_FD_BY_ID + +An introspection tool cannot use id to get details about program or maps. +A file descriptor needs to be obtained first for reference-counting purpose. + +3.6 BPF_OBJ_GET_INFO_BY_FD +========================== + +Once a program/map fd is acquired, an introspection tool can get the detailed +information from kernel about this fd, some of which are BTF-related. For +example, ``bpf_map_info`` returns ``btf_id`` and key/value type ids. +``bpf_prog_info`` returns ``btf_id``, func_info, and line info for translated +bpf byte codes, and jited_line_info. + +3.7 BPF_BTF_GET_FD_BY_ID +======================== + +With ``btf_id`` obtained in ``bpf_map_info`` and ``bpf_prog_info``, bpf +syscall command BPF_BTF_GET_FD_BY_ID can retrieve a btf fd. Then, with +command BPF_OBJ_GET_INFO_BY_FD, the btf blob, originally loaded into the +kernel with BPF_BTF_LOAD, can be retrieved. + +With the btf blob, ``bpf_map_info``, and ``bpf_prog_info``, an introspection +tool has full btf knowledge and is able to pretty print map key/values, dump +func signatures and line info, along with byte/jit codes. + +4. ELF File Format Interface +**************************** + +4.1 .BTF section +================ + +The .BTF section contains type and string data. The format of this section is +same as the one describe in :ref:`BTF_Type_String`. + +.. _BTF_Ext_Section: + +4.2 .BTF.ext section +==================== + +The .BTF.ext section encodes func_info and line_info which needs loader +manipulation before loading into the kernel. + +The specification for .BTF.ext section is defined at ``tools/lib/bpf/btf.h`` +and ``tools/lib/bpf/btf.c``. + +The current header of .BTF.ext section:: + + struct btf_ext_header { + __u16 magic; + __u8 version; + __u8 flags; + __u32 hdr_len; + + /* All offsets are in bytes relative to the end of this header */ + __u32 func_info_off; + __u32 func_info_len; + __u32 line_info_off; + __u32 line_info_len; + }; + +It is very similar to .BTF section. Instead of type/string section, it +contains func_info and line_info section. See :ref:`BPF_Prog_Load` for details +about func_info and line_info record format. + +The func_info is organized as below.:: + + func_info_rec_size + btf_ext_info_sec for section #1 /* func_info for section #1 */ + btf_ext_info_sec for section #2 /* func_info for section #2 */ + ... + +``func_info_rec_size`` specifies the size of ``bpf_func_info`` structure when +.BTF.ext is generated. ``btf_ext_info_sec``, defined below, is a collection of +func_info for each specific ELF section.:: + + struct btf_ext_info_sec { + __u32 sec_name_off; /* offset to section name */ + __u32 num_info; + /* Followed by num_info * record_size number of bytes */ + __u8 data[0]; + }; + +Here, num_info must be greater than 0. + +The line_info is organized as below.:: + + line_info_rec_size + btf_ext_info_sec for section #1 /* line_info for section #1 */ + btf_ext_info_sec for section #2 /* line_info for section #2 */ + ... + +``line_info_rec_size`` specifies the size of ``bpf_line_info`` structure when +.BTF.ext is generated. + +The interpretation of ``bpf_func_info->insn_off`` and +``bpf_line_info->insn_off`` is different between kernel API and ELF API. For +kernel API, the ``insn_off`` is the instruction offset in the unit of ``struct +bpf_insn``. For ELF API, the ``insn_off`` is the byte offset from the +beginning of section (``btf_ext_info_sec->sec_name_off``). + +5. Using BTF +************ + +5.1 bpftool map pretty print +============================ + +With BTF, the map key/value can be printed based on fields rather than simply +raw bytes. This is especially valuable for large structure or if your data +structure has bitfields. For example, for the following map,:: + + enum A { A1, A2, A3, A4, A5 }; + typedef enum A ___A; + struct tmp_t { + char a1:4; + int a2:4; + int :4; + __u32 a3:4; + int b; + ___A b1:4; + enum A b2:4; + }; + struct bpf_map_def SEC("maps") tmpmap = { + .type = BPF_MAP_TYPE_ARRAY, + .key_size = sizeof(__u32), + .value_size = sizeof(struct tmp_t), + .max_entries = 1, + }; + BPF_ANNOTATE_KV_PAIR(tmpmap, int, struct tmp_t); + +bpftool is able to pretty print like below: +:: + + [{ + "key": 0, + "value": { + "a1": 0x2, + "a2": 0x4, + "a3": 0x6, + "b": 7, + "b1": 0x8, + "b2": 0xa + } + } + ] + +5.2 bpftool prog dump +===================== + +The following is an example showing how func_info and line_info can help prog +dump with better kernel symbol names, function prototypes and line +information.:: + + $ bpftool prog dump jited pinned /sys/fs/bpf/test_btf_haskv + [...] + int test_long_fname_2(struct dummy_tracepoint_args * arg): + bpf_prog_44a040bf25481309_test_long_fname_2: + ; static int test_long_fname_2(struct dummy_tracepoint_args *arg) + 0: push %rbp + 1: mov %rsp,%rbp + 4: sub $0x30,%rsp + b: sub $0x28,%rbp + f: mov %rbx,0x0(%rbp) + 13: mov %r13,0x8(%rbp) + 17: mov %r14,0x10(%rbp) + 1b: mov %r15,0x18(%rbp) + 1f: xor %eax,%eax + 21: mov %rax,0x20(%rbp) + 25: xor %esi,%esi + ; int key = 0; + 27: mov %esi,-0x4(%rbp) + ; if (!arg->sock) + 2a: mov 0x8(%rdi),%rdi + ; if (!arg->sock) + 2e: cmp $0x0,%rdi + 32: je 0x0000000000000070 + 34: mov %rbp,%rsi + ; counts = bpf_map_lookup_elem(&btf_map, &key); + [...] + +5.3 Verifier Log +================ + +The following is an example of how line_info can help debugging verification +failure.:: + + /* The code at tools/testing/selftests/bpf/test_xdp_noinline.c + * is modified as below. + */ + data = (void *)(long)xdp->data; + data_end = (void *)(long)xdp->data_end; + /* + if (data + 4 > data_end) + return XDP_DROP; + */ + *(u32 *)data = dst->dst; + + $ bpftool prog load ./test_xdp_noinline.o /sys/fs/bpf/test_xdp_noinline type xdp + ; data = (void *)(long)xdp->data; + 224: (79) r2 = *(u64 *)(r10 -112) + 225: (61) r2 = *(u32 *)(r2 +0) + ; *(u32 *)data = dst->dst; + 226: (63) *(u32 *)(r2 +0) = r1 + invalid access to packet, off=0 size=4, R2(id=0,off=0,r=0) + R2 offset is outside of the packet + +6. BTF Generation +***************** + +You need latest pahole + + https://git.kernel.org/pub/scm/devel/pahole/pahole.git/ + +or llvm (8.0 or later). The pahole acts as a dwarf2btf converter. It doesn't +support .BTF.ext and btf BTF_KIND_FUNC type yet. For example,:: + + -bash-4.4$ cat t.c + struct t { + int a:2; + int b:3; + int c:2; + } g; + -bash-4.4$ gcc -c -O2 -g t.c + -bash-4.4$ pahole -JV t.o + File t.o: + [1] STRUCT t kind_flag=1 size=4 vlen=3 + a type_id=2 bitfield_size=2 bits_offset=0 + b type_id=2 bitfield_size=3 bits_offset=2 + c type_id=2 bitfield_size=2 bits_offset=5 + [2] INT int size=4 bit_offset=0 nr_bits=32 encoding=SIGNED + +The llvm is able to generate .BTF and .BTF.ext directly with -g for bpf target +only. The assembly code (-S) is able to show the BTF encoding in assembly +format.:: + + -bash-4.4$ cat t2.c + typedef int __int32; + struct t2 { + int a2; + int (*f2)(char q1, __int32 q2, ...); + int (*f3)(); + } g2; + int main() { return 0; } + int test() { return 0; } + -bash-4.4$ clang -c -g -O2 -target bpf t2.c + -bash-4.4$ readelf -S t2.o + ...... + [ 8] .BTF PROGBITS 0000000000000000 00000247 + 000000000000016e 0000000000000000 0 0 1 + [ 9] .BTF.ext PROGBITS 0000000000000000 000003b5 + 0000000000000060 0000000000000000 0 0 1 + [10] .rel.BTF.ext REL 0000000000000000 000007e0 + 0000000000000040 0000000000000010 16 9 8 + ...... + -bash-4.4$ clang -S -g -O2 -target bpf t2.c + -bash-4.4$ cat t2.s + ...... + .section .BTF,"",@progbits + .short 60319 # 0xeb9f + .byte 1 + .byte 0 + .long 24 + .long 0 + .long 220 + .long 220 + .long 122 + .long 0 # BTF_KIND_FUNC_PROTO(id = 1) + .long 218103808 # 0xd000000 + .long 2 + .long 83 # BTF_KIND_INT(id = 2) + .long 16777216 # 0x1000000 + .long 4 + .long 16777248 # 0x1000020 + ...... + .byte 0 # string offset=0 + .ascii ".text" # string offset=1 + .byte 0 + .ascii "/home/yhs/tmp-pahole/t2.c" # string offset=7 + .byte 0 + .ascii "int main() { return 0; }" # string offset=33 + .byte 0 + .ascii "int test() { return 0; }" # string offset=58 + .byte 0 + .ascii "int" # string offset=83 + ...... + .section .BTF.ext,"",@progbits + .short 60319 # 0xeb9f + .byte 1 + .byte 0 + .long 24 + .long 0 + .long 28 + .long 28 + .long 44 + .long 8 # FuncInfo + .long 1 # FuncInfo section string offset=1 + .long 2 + .long .Lfunc_begin0 + .long 3 + .long .Lfunc_begin1 + .long 5 + .long 16 # LineInfo + .long 1 # LineInfo section string offset=1 + .long 2 + .long .Ltmp0 + .long 7 + .long 33 + .long 7182 # Line 7 Col 14 + .long .Ltmp3 + .long 7 + .long 58 + .long 8206 # Line 8 Col 14 + +7. Testing +********** + +Kernel bpf selftest `test_btf.c` provides extensive set of BTF-related tests. diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst index 00a8450a602f..4e77932959cc 100644 --- a/Documentation/bpf/index.rst +++ b/Documentation/bpf/index.rst @@ -15,6 +15,13 @@ that goes into great technical depth about the BPF Architecture. The primary info for the bpf syscall is available in the `man-pages`_ for `bpf(2)`_. +BPF Type Format (BTF) +===================== + +.. toctree:: + :maxdepth: 1 + + btf Frequently asked questions (FAQ) diff --git a/Documentation/cgroup-v1/memcg_test.txt b/Documentation/cgroup-v1/memcg_test.txt index 5c7f310f32bb..621e29ffb358 100644 --- a/Documentation/cgroup-v1/memcg_test.txt +++ b/Documentation/cgroup-v1/memcg_test.txt @@ -107,9 +107,9 @@ Under below explanation, we assume CONFIG_MEM_RES_CTRL_SWAP=y. 8. LRU Each memcg has its own private LRU. Now, its handling is under global - VM's control (means that it's handled under global zone_lru_lock). + VM's control (means that it's handled under global pgdat->lru_lock). Almost all routines around memcg's LRU is called by global LRU's - list management functions under zone_lru_lock(). + list management functions under pgdat->lru_lock. A special function is mem_cgroup_isolate_pages(). This scans memcg's private LRU and call __isolate_lru_page() to extract a page diff --git a/Documentation/cgroup-v1/memory.txt b/Documentation/cgroup-v1/memory.txt index 3682e99234c2..a347fc9293e5 100644 --- a/Documentation/cgroup-v1/memory.txt +++ b/Documentation/cgroup-v1/memory.txt @@ -267,11 +267,11 @@ When oom event notifier is registered, event will be delivered. Other lock order is following: PG_locked. mm->page_table_lock - zone_lru_lock + pgdat->lru_lock lock_page_cgroup. In many cases, just lock_page_cgroup() is called. per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by - zone_lru_lock, it has no lock of its own. + pgdat->lru_lock, it has no lock of its own. 2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM) diff --git a/Documentation/cgroup-v1/pids.txt b/Documentation/cgroup-v1/pids.txt index 1a078b5d281a..e105d708ccde 100644 --- a/Documentation/cgroup-v1/pids.txt +++ b/Documentation/cgroup-v1/pids.txt @@ -33,6 +33,9 @@ limit in the hierarchy is followed). pids.current tracks all child cgroup hierarchies, so parent/pids.current is a superset of parent/child/pids.current. +The pids.events file contains event counters: + - max: Number of times fork failed because limit was hit. + Example ------- diff --git a/Documentation/cgroup-v1/rdma.txt b/Documentation/cgroup-v1/rdma.txt index af618171e0eb..9bdb7fd03f83 100644 --- a/Documentation/cgroup-v1/rdma.txt +++ b/Documentation/cgroup-v1/rdma.txt @@ -27,7 +27,7 @@ cgroup. 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. +rdma resources. This can lead to service unavailability. Therefore RDMA controller is needed through which resource consumption of processes can be limited. Through this controller different rdma diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-api/assoc_array.rst index 8231b915c939..792bbf9939e1 100644 --- a/Documentation/core-api/assoc_array.rst +++ b/Documentation/core-api/assoc_array.rst @@ -34,7 +34,7 @@ properties: 8. The array can iterated over. The objects will not necessarily come out in key order. -9. The array can be iterated over whilst it is being modified, provided the +9. The array can be iterated over while it is being modified, provided the RCU readlock is being held by the iterator. Note, however, under these circumstances, some objects may be seen more than once. If this is a problem, the iterator should lock against modification. Objects will not @@ -42,7 +42,7 @@ properties: 10. Objects in the array can be looked up by means of their index key. -11. Objects can be looked up whilst the array is being modified, provided the +11. Objects can be looked up while the array is being modified, provided the RCU readlock is being held by the thread doing the look up. The implementation uses a tree of 16-pointer nodes internally that are indexed @@ -273,7 +273,7 @@ The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't enough memory. It is possible for other threads to iterate over or search the array under -the RCU read lock whilst this function is in progress. The caller should +the RCU read lock while this function is in progress. The caller should lock exclusively against other modifiers of the array. diff --git a/Documentation/core-api/boot-time-mm.rst b/Documentation/core-api/boot-time-mm.rst index 6e12e89a03e0..e5ec9f1a563d 100644 --- a/Documentation/core-api/boot-time-mm.rst +++ b/Documentation/core-api/boot-time-mm.rst @@ -5,54 +5,23 @@ Boot time memory management Early system initialization cannot use "normal" memory management simply because it is not set up yet. But there is still need to allocate memory for various data structures, for instance for the -physical page allocator. To address this, a specialized allocator -called the :ref:`Boot Memory Allocator <bootmem>`, or bootmem, was -introduced. Several years later PowerPC developers added a "Logical -Memory Blocks" allocator, which was later adopted by other -architectures and renamed to :ref:`memblock <memblock>`. There is also -a compatibility layer called `nobootmem` that translates bootmem -allocation interfaces to memblock calls. +physical page allocator. -The selection of the early allocator is done using -``CONFIG_NO_BOOTMEM`` and ``CONFIG_HAVE_MEMBLOCK`` kernel -configuration options. These options are enabled or disabled -statically by the architectures' Kconfig files. - -* Architectures that rely only on bootmem select - ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=n``. -* The users of memblock with the nobootmem compatibility layer set - ``CONFIG_NO_BOOTMEM=y && CONFIG_HAVE_MEMBLOCK=y``. -* And for those that use both memblock and bootmem the configuration - includes ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=y``. - -Whichever allocator is used, it is the responsibility of the -architecture specific initialization to set it up in -:c:func:`setup_arch` and tear it down in :c:func:`mem_init` functions. +A specialized allocator called ``memblock`` performs the +boot time memory management. The architecture specific initialization +must set it up in :c:func:`setup_arch` and tear it down in +:c:func:`mem_init` functions. Once the early memory management is available it offers a variety of functions and macros for memory allocations. The allocation request may be directed to the first (and probably the only) node or to a particular node in a NUMA system. There are API variants that panic -when an allocation fails and those that don't. And more recent and -advanced memblock even allows controlling its own behaviour. - -.. _bootmem: - -Bootmem -======= +when an allocation fails and those that don't. -(mostly stolen from Mel Gorman's "Understanding the Linux Virtual -Memory Manager" `book`_) +Memblock also offers a variety of APIs that control its own behaviour. -.. _book: https://www.kernel.org/doc/gorman/ - -.. kernel-doc:: mm/bootmem.c - :doc: bootmem overview - -.. _memblock: - -Memblock -======== +Memblock Overview +================= .. kernel-doc:: mm/memblock.c :doc: memblock overview @@ -61,26 +30,6 @@ Memblock Functions and structures ======================== -Common API ----------- - -The functions that are described in this section are available -regardless of what early memory manager is enabled. - -.. kernel-doc:: mm/nobootmem.c - -Bootmem specific API --------------------- - -These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n`` - -.. kernel-doc:: include/linux/bootmem.h -.. kernel-doc:: mm/bootmem.c - :functions: - -Memblock specific API ---------------------- - Here is the description of memblock data structures, functions and macros. Some of them are actually internal, but since they are documented it would be silly to omit them. Besides, reading the diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index 29c790f571a5..3adee82be311 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -21,6 +21,7 @@ Core utilities local_ops workqueue genericirq + xarray flexible-arrays librs genalloc diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst index 3431337ee4e6..cdd24943fbcc 100644 --- a/Documentation/core-api/kernel-api.rst +++ b/Documentation/core-api/kernel-api.rst @@ -291,12 +291,6 @@ Block Devices .. kernel-doc:: block/blk-lib.c :export: -.. kernel-doc:: block/blk-tag.c - :export: - -.. kernel-doc:: block/blk-tag.c - :internal: - .. kernel-doc:: block/blk-integrity.c :export: diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst index f8bb9aa120c4..8954a88ff5b7 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -1,3 +1,5 @@ +.. _memory-allocation: + ======================= Memory Allocation Guide ======================= diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 5ce1ec1dd066..aa8e54b85221 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -46,11 +46,20 @@ The Slab Cache .. kernel-doc:: mm/slab.c :export: +.. kernel-doc:: mm/slab_common.c + :export: + .. kernel-doc:: mm/util.c :functions: kfree_const kvmalloc_node kvfree -More Memory Management Functions -================================ +Virtually Contiguous Mappings +============================= + +.. kernel-doc:: mm/vmalloc.c + :export: + +File Mapping and Page Cache +=========================== .. kernel-doc:: mm/readahead.c :export: @@ -58,23 +67,28 @@ More Memory Management Functions .. kernel-doc:: mm/filemap.c :export: -.. kernel-doc:: mm/memory.c +.. kernel-doc:: mm/page-writeback.c :export: -.. kernel-doc:: mm/vmalloc.c +.. kernel-doc:: mm/truncate.c :export: -.. kernel-doc:: mm/page_alloc.c - :internal: +Memory pools +============ .. kernel-doc:: mm/mempool.c :export: +DMA pools +========= + .. kernel-doc:: mm/dmapool.c :export: -.. kernel-doc:: mm/page-writeback.c - :export: +More Memory Management Functions +================================ -.. kernel-doc:: mm/truncate.c +.. kernel-doc:: mm/memory.c :export: + +.. kernel-doc:: mm/page_alloc.c diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index cd1b0e804b74..c37ec7cd9c06 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -420,6 +420,24 @@ Examples:: Passed by reference. +Time and date (struct rtc_time) +------------------------------- + +:: + + %ptR YYYY-mm-ddTHH:MM:SS + %ptRd YYYY-mm-dd + %ptRt HH:MM:SS + %ptR[dt][r] + +For printing date and time as represented by struct rtc_time structure in +human readable format. + +By default year will be incremented by 1900 and month by 1. Use %ptRr (raw) +to suppress this behaviour. + +Passed by reference. + struct clk ---------- diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst index 322851bada16..976e85adffe8 100644 --- a/Documentation/core-api/refcount-vs-atomic.rst +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -54,6 +54,13 @@ must propagate to all other CPUs before the release operation (A-cumulative property). This is implemented using :c:func:`smp_store_release`. +An ACQUIRE memory ordering guarantees that all post loads and +stores (all po-later instructions) on the same CPU are +completed after the acquire operation. It also guarantees that all +po-later stores on the same CPU must propagate to all other CPUs +after the acquire operation executes. This is implemented using +:c:func:`smp_acquire__after_ctrl_dep`. + A control dependency (on success) for refcounters guarantees that if a reference for an object was successfully obtained (reference counter increment or addition happened, function returned true), @@ -119,13 +126,24 @@ Memory ordering guarantees changes: result of obtaining pointer to the object! -case 5) - decrement-based RMW ops that return a value ------------------------------------------------------ +case 5) - generic dec/sub decrement-based RMW ops that return a value +--------------------------------------------------------------------- Function changes: * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + +Memory ordering guarantees changes: + + * fully ordered --> RELEASE ordering + ACQUIRE ordering on success + + +case 6) other decrement-based RMW ops that return a value +--------------------------------------------------------- + +Function changes: + * no atomic counterpart --> :c:func:`refcount_dec_if_one` * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` @@ -136,7 +154,7 @@ Memory ordering guarantees changes: .. note:: :c:func:`atomic_add_unless` only provides full order on success. -case 6) - lock-based RMW +case 7) - lock-based RMW ------------------------ Function changes: diff --git a/Documentation/core-api/xarray.rst b/Documentation/core-api/xarray.rst new file mode 100644 index 000000000000..5d54b27c6eba --- /dev/null +++ b/Documentation/core-api/xarray.rst @@ -0,0 +1,471 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +====== +XArray +====== + +:Author: Matthew Wilcox + +Overview +======== + +The XArray is an abstract data type which behaves like a very large array +of pointers. It meets many of the same needs as a hash or a conventional +resizable array. Unlike a hash, it allows you to sensibly go to the +next or previous entry in a cache-efficient manner. In contrast to a +resizable array, there is no need to copy data or change MMU mappings in +order to grow the array. It is more memory-efficient, parallelisable +and cache friendly than a doubly-linked list. It takes advantage of +RCU to perform lookups without locking. + +The XArray implementation is efficient when the indices used are densely +clustered; hashing the object and using the hash as the index will not +perform well. The XArray is optimised for small indices, but still has +good performance with large indices. If your index can be larger than +``ULONG_MAX`` then the XArray is not the data type for you. The most +important user of the XArray is the page cache. + +Each non-``NULL`` entry in the array has three bits associated with +it called marks. Each mark may be set or cleared independently of +the others. You can iterate over entries which are marked. + +Normal pointers may be stored in the XArray directly. They must be 4-byte +aligned, which is true for any pointer returned from :c:func:`kmalloc` and +:c:func:`alloc_page`. It isn't true for arbitrary user-space pointers, +nor for function pointers. You can store pointers to statically allocated +objects, as long as those objects have an alignment of at least 4. + +You can also store integers between 0 and ``LONG_MAX`` in the XArray. +You must first convert it into an entry using :c:func:`xa_mk_value`. +When you retrieve an entry from the XArray, you can check whether it is +a value entry by calling :c:func:`xa_is_value`, and convert it back to +an integer by calling :c:func:`xa_to_value`. + +Some users want to store tagged pointers instead of using the marks +described above. They can call :c:func:`xa_tag_pointer` to create an +entry with a tag, :c:func:`xa_untag_pointer` to turn a tagged entry +back into an untagged pointer and :c:func:`xa_pointer_tag` to retrieve +the tag of an entry. Tagged pointers use the same bits that are used +to distinguish value entries from normal pointers, so each user must +decide whether they want to store value entries or tagged pointers in +any particular XArray. + +The XArray does not support storing :c:func:`IS_ERR` pointers as some +conflict with value entries or internal entries. + +An unusual feature of the XArray is the ability to create entries which +occupy a range of indices. Once stored to, looking up any index in +the range will return the same entry as looking up any other index in +the range. Setting a mark on one index will set it on all of them. +Storing to any index will store to all of them. Multi-index entries can +be explicitly split into smaller entries, or storing ``NULL`` into any +entry will cause the XArray to forget about the range. + +Normal API +========== + +Start by initialising an XArray, either with :c:func:`DEFINE_XARRAY` +for statically allocated XArrays or :c:func:`xa_init` for dynamically +allocated ones. A freshly-initialised XArray contains a ``NULL`` +pointer at every index. + +You can then set entries using :c:func:`xa_store` and get entries +using :c:func:`xa_load`. xa_store will overwrite any entry with the +new entry and return the previous entry stored at that index. You can +use :c:func:`xa_erase` instead of calling :c:func:`xa_store` with a +``NULL`` entry. There is no difference between an entry that has never +been stored to, one that has been erased and one that has most recently +had ``NULL`` stored to it. + +You can conditionally replace an entry at an index by using +:c:func:`xa_cmpxchg`. Like :c:func:`cmpxchg`, it will only succeed if +the entry at that index has the 'old' value. It also returns the entry +which was at that index; if it returns the same entry which was passed as +'old', then :c:func:`xa_cmpxchg` succeeded. + +If you want to only store a new entry to an index if the current entry +at that index is ``NULL``, you can use :c:func:`xa_insert` which +returns ``-EEXIST`` if the entry is not empty. + +You can enquire whether a mark is set on an entry by using +:c:func:`xa_get_mark`. If the entry is not ``NULL``, you can set a mark +on it by using :c:func:`xa_set_mark` and remove the mark from an entry by +calling :c:func:`xa_clear_mark`. You can ask whether any entry in the +XArray has a particular mark set by calling :c:func:`xa_marked`. + +You can copy entries out of the XArray into a plain array by calling +:c:func:`xa_extract`. Or you can iterate over the present entries in +the XArray by calling :c:func:`xa_for_each`. You may prefer to use +:c:func:`xa_find` or :c:func:`xa_find_after` to move to the next present +entry in the XArray. + +Calling :c:func:`xa_store_range` stores the same entry in a range +of indices. If you do this, some of the other operations will behave +in a slightly odd way. For example, marking the entry at one index +may result in the entry being marked at some, but not all of the other +indices. Storing into one index may result in the entry retrieved by +some, but not all of the other indices changing. + +Sometimes you need to ensure that a subsequent call to :c:func:`xa_store` +will not need to allocate memory. The :c:func:`xa_reserve` function +will store a reserved entry at the indicated index. Users of the +normal API will see this entry as containing ``NULL``. If you do +not need to use the reserved entry, you can call :c:func:`xa_release` +to remove the unused entry. If another user has stored to the entry +in the meantime, :c:func:`xa_release` will do nothing; if instead you +want the entry to become ``NULL``, you should use :c:func:`xa_erase`. +Using :c:func:`xa_insert` on a reserved entry will fail. + +If all entries in the array are ``NULL``, the :c:func:`xa_empty` function +will return ``true``. + +Finally, you can remove all entries from an XArray by calling +:c:func:`xa_destroy`. If the XArray entries are pointers, you may wish +to free the entries first. You can do this by iterating over all present +entries in the XArray using the :c:func:`xa_for_each` iterator. + +Allocating XArrays +------------------ + +If you use :c:func:`DEFINE_XARRAY_ALLOC` to define the XArray, or +initialise it by passing ``XA_FLAGS_ALLOC`` to :c:func:`xa_init_flags`, +the XArray changes to track whether entries are in use or not. + +You can call :c:func:`xa_alloc` to store the entry at any unused index +in the XArray. If you need to modify the array from interrupt context, +you can use :c:func:`xa_alloc_bh` or :c:func:`xa_alloc_irq` to disable +interrupts while allocating the ID. + +Using :c:func:`xa_store`, :c:func:`xa_cmpxchg` or :c:func:`xa_insert` +will mark the entry as being allocated. Unlike a normal XArray, storing +``NULL`` will mark the entry as being in use, like :c:func:`xa_reserve`. +To free an entry, use :c:func:`xa_erase` (or :c:func:`xa_release` if +you only want to free the entry if it's ``NULL``). + +You cannot use ``XA_MARK_0`` with an allocating XArray as this mark +is used to track whether an entry is free or not. The other marks are +available for your use. + +Memory allocation +----------------- + +The :c:func:`xa_store`, :c:func:`xa_cmpxchg`, :c:func:`xa_alloc`, +:c:func:`xa_reserve` and :c:func:`xa_insert` functions take a gfp_t +parameter in case the XArray needs to allocate memory to store this entry. +If the entry is being deleted, no memory allocation needs to be performed, +and the GFP flags specified will be ignored. + +It is possible for no memory to be allocatable, particularly if you pass +a restrictive set of GFP flags. In that case, the functions return a +special value which can be turned into an errno using :c:func:`xa_err`. +If you don't need to know exactly which error occurred, using +:c:func:`xa_is_err` is slightly more efficient. + +Locking +------- + +When using the Normal API, you do not have to worry about locking. +The XArray uses RCU and an internal spinlock to synchronise access: + +No lock needed: + * :c:func:`xa_empty` + * :c:func:`xa_marked` + +Takes RCU read lock: + * :c:func:`xa_load` + * :c:func:`xa_for_each` + * :c:func:`xa_find` + * :c:func:`xa_find_after` + * :c:func:`xa_extract` + * :c:func:`xa_get_mark` + +Takes xa_lock internally: + * :c:func:`xa_store` + * :c:func:`xa_store_bh` + * :c:func:`xa_store_irq` + * :c:func:`xa_insert` + * :c:func:`xa_insert_bh` + * :c:func:`xa_insert_irq` + * :c:func:`xa_erase` + * :c:func:`xa_erase_bh` + * :c:func:`xa_erase_irq` + * :c:func:`xa_cmpxchg` + * :c:func:`xa_cmpxchg_bh` + * :c:func:`xa_cmpxchg_irq` + * :c:func:`xa_store_range` + * :c:func:`xa_alloc` + * :c:func:`xa_alloc_bh` + * :c:func:`xa_alloc_irq` + * :c:func:`xa_reserve` + * :c:func:`xa_reserve_bh` + * :c:func:`xa_reserve_irq` + * :c:func:`xa_destroy` + * :c:func:`xa_set_mark` + * :c:func:`xa_clear_mark` + +Assumes xa_lock held on entry: + * :c:func:`__xa_store` + * :c:func:`__xa_insert` + * :c:func:`__xa_erase` + * :c:func:`__xa_cmpxchg` + * :c:func:`__xa_alloc` + * :c:func:`__xa_reserve` + * :c:func:`__xa_set_mark` + * :c:func:`__xa_clear_mark` + +If you want to take advantage of the lock to protect the data structures +that you are storing in the XArray, you can call :c:func:`xa_lock` +before calling :c:func:`xa_load`, then take a reference count on the +object you have found before calling :c:func:`xa_unlock`. This will +prevent stores from removing the object from the array between looking +up the object and incrementing the refcount. You can also use RCU to +avoid dereferencing freed memory, but an explanation of that is beyond +the scope of this document. + +The XArray does not disable interrupts or softirqs while modifying +the array. It is safe to read the XArray from interrupt or softirq +context as the RCU lock provides enough protection. + +If, for example, you want to store entries in the XArray in process +context and then erase them in softirq context, you can do that this way:: + + void foo_init(struct foo *foo) + { + xa_init_flags(&foo->array, XA_FLAGS_LOCK_BH); + } + + int foo_store(struct foo *foo, unsigned long index, void *entry) + { + int err; + + xa_lock_bh(&foo->array); + err = xa_err(__xa_store(&foo->array, index, entry, GFP_KERNEL)); + if (!err) + foo->count++; + xa_unlock_bh(&foo->array); + return err; + } + + /* foo_erase() is only called from softirq context */ + void foo_erase(struct foo *foo, unsigned long index) + { + xa_lock(&foo->array); + __xa_erase(&foo->array, index); + foo->count--; + xa_unlock(&foo->array); + } + +If you are going to modify the XArray from interrupt or softirq context, +you need to initialise the array using :c:func:`xa_init_flags`, passing +``XA_FLAGS_LOCK_IRQ`` or ``XA_FLAGS_LOCK_BH``. + +The above example also shows a common pattern of wanting to extend the +coverage of the xa_lock on the store side to protect some statistics +associated with the array. + +Sharing the XArray with interrupt context is also possible, either +using :c:func:`xa_lock_irqsave` in both the interrupt handler and process +context, or :c:func:`xa_lock_irq` in process context and :c:func:`xa_lock` +in the interrupt handler. Some of the more common patterns have helper +functions such as :c:func:`xa_store_bh`, :c:func:`xa_store_irq`, +:c:func:`xa_erase_bh`, :c:func:`xa_erase_irq`, :c:func:`xa_cmpxchg_bh` +and :c:func:`xa_cmpxchg_irq`. + +Sometimes you need to protect access to the XArray with a mutex because +that lock sits above another mutex in the locking hierarchy. That does +not entitle you to use functions like :c:func:`__xa_erase` without taking +the xa_lock; the xa_lock is used for lockdep validation and will be used +for other purposes in the future. + +The :c:func:`__xa_set_mark` and :c:func:`__xa_clear_mark` functions are also +available for situations where you look up an entry and want to atomically +set or clear a mark. It may be more efficient to use the advanced API +in this case, as it will save you from walking the tree twice. + +Advanced API +============ + +The advanced API offers more flexibility and better performance at the +cost of an interface which can be harder to use and has fewer safeguards. +No locking is done for you by the advanced API, and you are required +to use the xa_lock while modifying the array. You can choose whether +to use the xa_lock or the RCU lock while doing read-only operations on +the array. You can mix advanced and normal operations on the same array; +indeed the normal API is implemented in terms of the advanced API. The +advanced API is only available to modules with a GPL-compatible license. + +The advanced API is based around the xa_state. This is an opaque data +structure which you declare on the stack using the :c:func:`XA_STATE` +macro. This macro initialises the xa_state ready to start walking +around the XArray. It is used as a cursor to maintain the position +in the XArray and let you compose various operations together without +having to restart from the top every time. + +The xa_state is also used to store errors. You can call +:c:func:`xas_error` to retrieve the error. All operations check whether +the xa_state is in an error state before proceeding, so there's no need +for you to check for an error after each call; you can make multiple +calls in succession and only check at a convenient point. The only +errors currently generated by the XArray code itself are ``ENOMEM`` and +``EINVAL``, but it supports arbitrary errors in case you want to call +:c:func:`xas_set_err` yourself. + +If the xa_state is holding an ``ENOMEM`` error, calling :c:func:`xas_nomem` +will attempt to allocate more memory using the specified gfp flags and +cache it in the xa_state for the next attempt. The idea is that you take +the xa_lock, attempt the operation and drop the lock. The operation +attempts to allocate memory while holding the lock, but it is more +likely to fail. Once you have dropped the lock, :c:func:`xas_nomem` +can try harder to allocate more memory. It will return ``true`` if it +is worth retrying the operation (i.e. that there was a memory error *and* +more memory was allocated). If it has previously allocated memory, and +that memory wasn't used, and there is no error (or some error that isn't +``ENOMEM``), then it will free the memory previously allocated. + +Internal Entries +---------------- + +The XArray reserves some entries for its own purposes. These are never +exposed through the normal API, but when using the advanced API, it's +possible to see them. Usually the best way to handle them is to pass them +to :c:func:`xas_retry`, and retry the operation if it returns ``true``. + +.. flat-table:: + :widths: 1 1 6 + + * - Name + - Test + - Usage + + * - Node + - :c:func:`xa_is_node` + - An XArray node. May be visible when using a multi-index xa_state. + + * - Sibling + - :c:func:`xa_is_sibling` + - A non-canonical entry for a multi-index entry. The value indicates + which slot in this node has the canonical entry. + + * - Retry + - :c:func:`xa_is_retry` + - This entry is currently being modified by a thread which has the + xa_lock. The node containing this entry may be freed at the end + of this RCU period. You should restart the lookup from the head + of the array. + + * - Zero + - :c:func:`xa_is_zero` + - Zero entries appear as ``NULL`` through the Normal API, but occupy + an entry in the XArray which can be used to reserve the index for + future use. This is used by allocating XArrays for allocated entries + which are ``NULL``. + +Other internal entries may be added in the future. As far as possible, they +will be handled by :c:func:`xas_retry`. + +Additional functionality +------------------------ + +The :c:func:`xas_create_range` function allocates all the necessary memory +to store every entry in a range. It will set ENOMEM in the xa_state if +it cannot allocate memory. + +You can use :c:func:`xas_init_marks` to reset the marks on an entry +to their default state. This is usually all marks clear, unless the +XArray is marked with ``XA_FLAGS_TRACK_FREE``, in which case mark 0 is set +and all other marks are clear. Replacing one entry with another using +:c:func:`xas_store` will not reset the marks on that entry; if you want +the marks reset, you should do that explicitly. + +The :c:func:`xas_load` will walk the xa_state as close to the entry +as it can. If you know the xa_state has already been walked to the +entry and need to check that the entry hasn't changed, you can use +:c:func:`xas_reload` to save a function call. + +If you need to move to a different index in the XArray, call +:c:func:`xas_set`. This resets the cursor to the top of the tree, which +will generally make the next operation walk the cursor to the desired +spot in the tree. If you want to move to the next or previous index, +call :c:func:`xas_next` or :c:func:`xas_prev`. Setting the index does +not walk the cursor around the array so does not require a lock to be +held, while moving to the next or previous index does. + +You can search for the next present entry using :c:func:`xas_find`. This +is the equivalent of both :c:func:`xa_find` and :c:func:`xa_find_after`; +if the cursor has been walked to an entry, then it will find the next +entry after the one currently referenced. If not, it will return the +entry at the index of the xa_state. Using :c:func:`xas_next_entry` to +move to the next present entry instead of :c:func:`xas_find` will save +a function call in the majority of cases at the expense of emitting more +inline code. + +The :c:func:`xas_find_marked` function is similar. If the xa_state has +not been walked, it will return the entry at the index of the xa_state, +if it is marked. Otherwise, it will return the first marked entry after +the entry referenced by the xa_state. The :c:func:`xas_next_marked` +function is the equivalent of :c:func:`xas_next_entry`. + +When iterating over a range of the XArray using :c:func:`xas_for_each` +or :c:func:`xas_for_each_marked`, it may be necessary to temporarily stop +the iteration. The :c:func:`xas_pause` function exists for this purpose. +After you have done the necessary work and wish to resume, the xa_state +is in an appropriate state to continue the iteration after the entry +you last processed. If you have interrupts disabled while iterating, +then it is good manners to pause the iteration and reenable interrupts +every ``XA_CHECK_SCHED`` entries. + +The :c:func:`xas_get_mark`, :c:func:`xas_set_mark` and +:c:func:`xas_clear_mark` functions require the xa_state cursor to have +been moved to the appropriate location in the xarray; they will do +nothing if you have called :c:func:`xas_pause` or :c:func:`xas_set` +immediately before. + +You can call :c:func:`xas_set_update` to have a callback function +called each time the XArray updates a node. This is used by the page +cache workingset code to maintain its list of nodes which contain only +shadow entries. + +Multi-Index Entries +------------------- + +The XArray has the ability to tie multiple indices together so that +operations on one index affect all indices. For example, storing into +any index will change the value of the entry retrieved from any index. +Setting or clearing a mark on any index will set or clear the mark +on every index that is tied together. The current implementation +only allows tying ranges which are aligned powers of two together; +eg indices 64-127 may be tied together, but 2-6 may not be. This may +save substantial quantities of memory; for example tying 512 entries +together will save over 4kB. + +You can create a multi-index entry by using :c:func:`XA_STATE_ORDER` +or :c:func:`xas_set_order` followed by a call to :c:func:`xas_store`. +Calling :c:func:`xas_load` with a multi-index xa_state will walk the +xa_state to the right location in the tree, but the return value is not +meaningful, potentially being an internal entry or ``NULL`` even when there +is an entry stored within the range. Calling :c:func:`xas_find_conflict` +will return the first entry within the range or ``NULL`` if there are no +entries in the range. The :c:func:`xas_for_each_conflict` iterator will +iterate over every entry which overlaps the specified range. + +If :c:func:`xas_load` encounters a multi-index entry, the xa_index +in the xa_state will not be changed. When iterating over an XArray +or calling :c:func:`xas_find`, if the initial index is in the middle +of a multi-index entry, it will not be altered. Subsequent calls +or iterations will move the index to the first index in the range. +Each entry will only be returned once, no matter how many indices it +occupies. + +Using :c:func:`xas_next` or :c:func:`xas_prev` with a multi-index xa_state +is not supported. Using either of these functions on a multi-index entry +will reveal sibling entries; these should be skipped over by the caller. + +Storing ``NULL`` into any index of a multi-index entry will set the entry +at every index to ``NULL`` and dissolve the tie. Splitting a multi-index +entry into entries occupying smaller ranges is not yet supported. + +Functions and structures +======================== + +.. kernel-doc:: include/linux/xarray.h +.. kernel-doc:: lib/xarray.c diff --git a/Documentation/cpu-freq/cpufreq-stats.txt b/Documentation/cpu-freq/cpufreq-stats.txt index a873855c811d..14378cecb172 100644 --- a/Documentation/cpu-freq/cpufreq-stats.txt +++ b/Documentation/cpu-freq/cpufreq-stats.txt @@ -86,9 +86,11 @@ transitions. This will give a fine grained information about all the CPU frequency transitions. The cat output here is a two dimensional matrix, where an entry <i,j> (row i, column j) represents the count of number of transitions from -Freq_i to Freq_j. Freq_i is in descending order with increasing rows and -Freq_j is in descending order with increasing columns. The output here also -contains the actual freq values for each row and column for better readability. +Freq_i to Freq_j. Freq_i rows and Freq_j columns follow the sorting order in +which the driver has provided the frequency table initially to the cpufreq core +and so can be sorted (ascending or descending) or unsorted. The output here +also contains the actual freq values for each row and column for better +readability. If the transition table is bigger than PAGE_SIZE, reading this will return an -EFBIG error. diff --git a/Documentation/cpuidle/core.txt b/Documentation/cpuidle/core.txt deleted file mode 100644 index 63ecc5dc9d8a..000000000000 --- a/Documentation/cpuidle/core.txt +++ /dev/null @@ -1,23 +0,0 @@ - - Supporting multiple CPU idle levels in kernel - - cpuidle - -General Information: - -Various CPUs today support multiple idle levels that are differentiated -by varying exit latencies and power consumption during idle. -cpuidle is a generic in-kernel infrastructure that separates -idle policy (governor) from idle mechanism (driver) and provides a -standardized infrastructure to support independent development of -governors and drivers. - -cpuidle resides under drivers/cpuidle. - -Boot options: -"cpuidle_sysfs_switch" -enables current_governor interface in /sys/devices/system/cpu/cpuidle/, -which can be used to switch governors at run time. This boot option -is meant for developer testing only. In normal usage, kernel picks the -best governor based on governor ratings. -SEE ALSO: sysfs.txt in this directory. diff --git a/Documentation/cpuidle/driver.txt b/Documentation/cpuidle/driver.txt deleted file mode 100644 index 1b0d81d92583..000000000000 --- a/Documentation/cpuidle/driver.txt +++ /dev/null @@ -1,37 +0,0 @@ - - - Supporting multiple CPU idle levels in kernel - - cpuidle drivers - - - - -cpuidle driver hooks into the cpuidle infrastructure and handles the -architecture/platform dependent part of CPU idle states. Driver -provides the platform idle state detection capability and also -has mechanisms in place to support actual entry-exit into CPU idle states. - -cpuidle driver initializes the cpuidle_device structure for each CPU device -and registers with cpuidle using cpuidle_register_device. - -If all the idle states are the same, the wrapper function cpuidle_register -could be used instead. - -It can also support the dynamic changes (like battery <-> AC), by using -cpuidle_pause_and_lock, cpuidle_disable_device and cpuidle_enable_device, -cpuidle_resume_and_unlock. - -Interfaces: -extern int cpuidle_register(struct cpuidle_driver *drv, - const struct cpumask *const coupled_cpus); -extern int cpuidle_unregister(struct cpuidle_driver *drv); -extern int cpuidle_register_driver(struct cpuidle_driver *drv); -extern void cpuidle_unregister_driver(struct cpuidle_driver *drv); -extern int cpuidle_register_device(struct cpuidle_device *dev); -extern void cpuidle_unregister_device(struct cpuidle_device *dev); - -extern void cpuidle_pause_and_lock(void); -extern void cpuidle_resume_and_unlock(void); -extern int cpuidle_enable_device(struct cpuidle_device *dev); -extern void cpuidle_disable_device(struct cpuidle_device *dev); diff --git a/Documentation/cpuidle/governor.txt b/Documentation/cpuidle/governor.txt deleted file mode 100644 index d9020f5e847b..000000000000 --- a/Documentation/cpuidle/governor.txt +++ /dev/null @@ -1,28 +0,0 @@ - - - - Supporting multiple CPU idle levels in kernel - - cpuidle governors - - - - -cpuidle governor is policy routine that decides what idle state to enter at -any given time. cpuidle core uses different callbacks to the governor. - -* enable() to enable governor for a particular device -* disable() to disable governor for a particular device -* select() to select an idle state to enter -* reflect() called after returning from the idle state, which can be used - by the governor for some record keeping. - -More than one governor can be registered at the same time and -users can switch between drivers using /sysfs interface (when enabled). -More than one governor part is supported for developers to easily experiment -with different governors. By default, most optimal governor based on your -kernel configuration and platform will be selected by cpuidle. - -Interfaces: -extern int cpuidle_register_governor(struct cpuidle_governor *gov); -struct cpuidle_governor diff --git a/Documentation/cpuidle/sysfs.txt b/Documentation/cpuidle/sysfs.txt deleted file mode 100644 index d1587f434e7b..000000000000 --- a/Documentation/cpuidle/sysfs.txt +++ /dev/null @@ -1,98 +0,0 @@ - - - Supporting multiple CPU idle levels in kernel - - cpuidle sysfs - -System global cpuidle related information and tunables are under -/sys/devices/system/cpu/cpuidle - -The current interfaces in this directory has self-explanatory names: -* current_driver -* current_governor_ro - -With cpuidle_sysfs_switch boot option (meant for developer testing) -following objects are visible instead. -* current_driver -* available_governors -* current_governor -In this case users can switch the governor at run time by writing -to current_governor. - - -Per logical CPU specific cpuidle information are under -/sys/devices/system/cpu/cpuX/cpuidle -for each online cpu X - --------------------------------------------------------------------------------- -# ls -lR /sys/devices/system/cpu/cpu0/cpuidle/ -/sys/devices/system/cpu/cpu0/cpuidle/: -total 0 -drwxr-xr-x 2 root root 0 Feb 8 10:42 state0 -drwxr-xr-x 2 root root 0 Feb 8 10:42 state1 -drwxr-xr-x 2 root root 0 Feb 8 10:42 state2 -drwxr-xr-x 2 root root 0 Feb 8 10:42 state3 - -/sys/devices/system/cpu/cpu0/cpuidle/state0: -total 0 --r--r--r-- 1 root root 4096 Feb 8 10:42 desc --rw-r--r-- 1 root root 4096 Feb 8 10:42 disable --r--r--r-- 1 root root 4096 Feb 8 10:42 latency --r--r--r-- 1 root root 4096 Feb 8 10:42 name --r--r--r-- 1 root root 4096 Feb 8 10:42 power --r--r--r-- 1 root root 4096 Feb 8 10:42 residency --r--r--r-- 1 root root 4096 Feb 8 10:42 time --r--r--r-- 1 root root 4096 Feb 8 10:42 usage - -/sys/devices/system/cpu/cpu0/cpuidle/state1: -total 0 --r--r--r-- 1 root root 4096 Feb 8 10:42 desc --rw-r--r-- 1 root root 4096 Feb 8 10:42 disable --r--r--r-- 1 root root 4096 Feb 8 10:42 latency --r--r--r-- 1 root root 4096 Feb 8 10:42 name --r--r--r-- 1 root root 4096 Feb 8 10:42 power --r--r--r-- 1 root root 4096 Feb 8 10:42 residency --r--r--r-- 1 root root 4096 Feb 8 10:42 time --r--r--r-- 1 root root 4096 Feb 8 10:42 usage - -/sys/devices/system/cpu/cpu0/cpuidle/state2: -total 0 --r--r--r-- 1 root root 4096 Feb 8 10:42 desc --rw-r--r-- 1 root root 4096 Feb 8 10:42 disable --r--r--r-- 1 root root 4096 Feb 8 10:42 latency --r--r--r-- 1 root root 4096 Feb 8 10:42 name --r--r--r-- 1 root root 4096 Feb 8 10:42 power --r--r--r-- 1 root root 4096 Feb 8 10:42 residency --r--r--r-- 1 root root 4096 Feb 8 10:42 time --r--r--r-- 1 root root 4096 Feb 8 10:42 usage - -/sys/devices/system/cpu/cpu0/cpuidle/state3: -total 0 --r--r--r-- 1 root root 4096 Feb 8 10:42 desc --rw-r--r-- 1 root root 4096 Feb 8 10:42 disable --r--r--r-- 1 root root 4096 Feb 8 10:42 latency --r--r--r-- 1 root root 4096 Feb 8 10:42 name --r--r--r-- 1 root root 4096 Feb 8 10:42 power --r--r--r-- 1 root root 4096 Feb 8 10:42 residency --r--r--r-- 1 root root 4096 Feb 8 10:42 time --r--r--r-- 1 root root 4096 Feb 8 10:42 usage --------------------------------------------------------------------------------- - - -* desc : Small description about the idle state (string) -* disable : Option to disable this idle state (bool) -> see note below -* latency : Latency to exit out of this idle state (in microseconds) -* residency : Time after which a state becomes more effecient than any - shallower state (in microseconds) -* name : Name of the idle state (string) -* power : Power consumed while in this idle state (in milliwatts) -* time : Total time spent in this idle state (in microseconds) -* usage : Number of times this state was entered (count) - -Note: -The behavior and the effect of the disable variable depends on the -implementation of a particular governor. In the ladder governor, for -example, it is not coherent, i.e. if one is disabling a light state, -then all deeper states are disabled as well, but the disable variable -does not reflect it. Likewise, if one enables a deep state but a lighter -state still is disabled, then this has no effect. diff --git a/Documentation/crypto/api.rst b/Documentation/crypto/api.rst index 2e519193ab4a..b91b31736df8 100644 --- a/Documentation/crypto/api.rst +++ b/Documentation/crypto/api.rst @@ -1,15 +1,6 @@ Programming Interface ===================== -Please note that the kernel crypto API contains the AEAD givcrypt API -(crypto_aead_giv\* and aead_givcrypt\* function calls in -include/crypto/aead.h). This API is obsolete and will be removed in the -future. To obtain the functionality of an AEAD cipher with internal IV -generation, use the IV generator as a regular cipher. For example, -rfc4106(gcm(aes)) is the AEAD cipher with external IV generation and -seqniv(rfc4106(gcm(aes))) implies that the kernel crypto API generates -the IV. Different IV generators are available. - .. class:: toc-title Table of contents diff --git a/Documentation/crypto/architecture.rst b/Documentation/crypto/architecture.rst index ca2d09b991f5..ee8ff0762d7f 100644 --- a/Documentation/crypto/architecture.rst +++ b/Documentation/crypto/architecture.rst @@ -157,10 +157,6 @@ applicable to a cipher, it is not displayed: - rng for random number generator - - givcipher for cipher with associated IV generator (see the geniv - entry below for the specification of the IV generator type used by - the cipher implementation) - - kpp for a Key-agreement Protocol Primitive (KPP) cipher such as an ECDH or DH implementation @@ -174,16 +170,7 @@ applicable to a cipher, it is not displayed: - digestsize: output size of the message digest -- geniv: IV generation type: - - - eseqiv for encrypted sequence number based IV generation - - - seqiv for sequence number based IV generation - - - chainiv for chain iv generation - - - <builtin> is a marker that the cipher implements IV generation and - handling as it is specific to the given cipher +- geniv: IV generator (obsolete) Key Sizes --------- @@ -218,10 +205,6 @@ the aforementioned cipher types: - CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher -- CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block cipher packed - together with an IV generator (see geniv field in the /proc/crypto - listing for the known IV generators) - - CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as an ECDH or DH implementation @@ -338,18 +321,14 @@ uses the API applicable to the cipher type specified for the block. The following call sequence is applicable when the IPSEC layer triggers an encryption operation with the esp_output function. During -configuration, the administrator set up the use of rfc4106(gcm(aes)) as -the cipher for ESP. The following call sequence is now depicted in the -ASCII art above: +configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes))) +as the cipher for ESP. The following call sequence is now depicted in +the ASCII art above: 1. esp_output() invokes crypto_aead_encrypt() to trigger an encryption operation of the AEAD cipher with IV generator. - In case of GCM, the SEQIV implementation is registered as GIVCIPHER - in crypto_rfc4106_alloc(). - - The SEQIV performs its operation to generate an IV where the core - function is seqiv_geniv(). + The SEQIV generates the IV. 2. Now, SEQIV uses the AEAD API function calls to invoke the associated AEAD cipher. In our case, during the instantiation of SEQIV, the diff --git a/Documentation/crypto/asymmetric-keys.txt b/Documentation/crypto/asymmetric-keys.txt index 5969bf42562a..8763866b11cf 100644 --- a/Documentation/crypto/asymmetric-keys.txt +++ b/Documentation/crypto/asymmetric-keys.txt @@ -183,6 +183,10 @@ and looks like the following: void (*describe)(const struct key *key, struct seq_file *m); void (*destroy)(void *payload); + int (*query)(const struct kernel_pkey_params *params, + struct kernel_pkey_query *info); + int (*eds_op)(struct kernel_pkey_params *params, + const void *in, void *out); int (*verify_signature)(const struct key *key, const struct public_key_signature *sig); }; @@ -207,12 +211,22 @@ There are a number of operations defined by the subtype: asymmetric key will look after freeing the fingerprint and releasing the reference on the subtype module. - (3) verify_signature(). + (3) query(). - Optional. These are the entry points for the key usage operations. - Currently there is only the one defined. If not set, the caller will be - given -ENOTSUPP. The subtype may do anything it likes to implement an - operation, including offloading to hardware. + Mandatory. This is a function for querying the capabilities of a key. + + (4) eds_op(). + + Optional. This is the entry point for the encryption, decryption and + signature creation operations (which are distinguished by the operation ID + in the parameter struct). The subtype may do anything it likes to + implement an operation, including offloading to hardware. + + (5) verify_signature(). + + Optional. This is the entry point for signature verification. The + subtype may do anything it likes to implement an operation, including + offloading to hardware. ========================== @@ -234,6 +248,8 @@ Examples of blob formats for which parsers could be implemented include: - X.509 ASN.1 stream. - Pointer to TPM key. - Pointer to UEFI key. + - PKCS#8 private key [RFC 5208]. + - PKCS#5 encrypted private key [RFC 2898]. During key instantiation each parser in the list is tried until one doesn't return -EBADMSG. diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst index aa14f05cabb1..00a3409b0c28 100644 --- a/Documentation/dev-tools/coccinelle.rst +++ b/Documentation/dev-tools/coccinelle.rst @@ -4,6 +4,8 @@ .. highlight:: none +.. _devtools_coccinelle: + Coccinelle ========== diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst index e313925fb0fa..b0522a4dd107 100644 --- a/Documentation/dev-tools/index.rst +++ b/Documentation/dev-tools/index.rst @@ -3,8 +3,8 @@ Development tools for the kernel ================================ This document is a collection of documents about development tools that can -be used to work on the kernel. For now, the documents have been pulled -together without any significant effot to integrate them into a coherent +be used to work on the kernel. For now, the documents have been pulled +together without any significant effort to integrate them into a coherent whole; patches welcome! .. class:: toc-title diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index aabc8738b3d8..b72d07d70239 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -4,15 +4,25 @@ The Kernel Address Sanitizer (KASAN) Overview -------- -KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides -a fast and comprehensive solution for finding use-after-free and out-of-bounds -bugs. +KernelAddressSANitizer (KASAN) is a dynamic memory error detector designed to +find out-of-bound and use-after-free bugs. KASAN has two modes: generic KASAN +(similar to userspace ASan) and software tag-based KASAN (similar to userspace +HWASan). -KASAN uses compile-time instrumentation for checking every memory access, -therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is -required for detection of out-of-bounds accesses to stack or global variables. +KASAN uses compile-time instrumentation to insert validity checks before every +memory access, and therefore requires a compiler version that supports that. -Currently KASAN is supported only for the x86_64 and arm64 architectures. +Generic KASAN is supported in both GCC and Clang. With GCC it requires version +4.9.2 or later for basic support and version 5.0 or later for detection of +out-of-bounds accesses for stack and global variables and for inline +instrumentation mode (see the Usage section). With Clang it requires version +7.0.0 or later and it doesn't support detection of out-of-bounds accesses for +global variables yet. + +Tag-based KASAN is only supported in Clang and requires version 7.0.0 or later. + +Currently generic KASAN is supported for the x86_64, arm64, xtensa and s390 +architectures, and tag-based KASAN is supported only for arm64. Usage ----- @@ -21,12 +31,14 @@ To enable KASAN configure kernel with:: CONFIG_KASAN = y -and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and -inline are compiler instrumentation types. The former produces smaller binary -the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC -version 5.0 or later. +and choose between CONFIG_KASAN_GENERIC (to enable generic KASAN) and +CONFIG_KASAN_SW_TAGS (to enable software tag-based KASAN). + +You also need to choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. +Outline and inline are compiler instrumentation types. The former produces +smaller binary while the latter is 1.1 - 2 times faster. -KASAN works with both SLUB and SLAB memory allocators. +Both KASAN modes work with both SLUB and SLAB memory allocators. For better bug detection and nicer reporting, enable CONFIG_STACKTRACE. To disable instrumentation for specific files or directories, add a line @@ -43,85 +55,85 @@ similar to the following to the respective kernel Makefile: Error reports ~~~~~~~~~~~~~ -A typical out of bounds access report looks like this:: +A typical out-of-bounds access generic KASAN report looks like this:: ================================================================== - BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3 - Write of size 1 by task modprobe/1689 - ============================================================================= - BUG kmalloc-128 (Not tainted): kasan error - ----------------------------------------------------------------------------- - - Disabling lock debugging due to kernel taint - INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689 - __slab_alloc+0x4b4/0x4f0 - kmem_cache_alloc_trace+0x10b/0x190 - kmalloc_oob_right+0x3d/0x75 [test_kasan] - init_module+0x9/0x47 [test_kasan] - do_one_initcall+0x99/0x200 - load_module+0x2cb3/0x3b20 - SyS_finit_module+0x76/0x80 - system_call_fastpath+0x12/0x17 - INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080 - INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720 - - Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a ........ZZZZZZZZ - Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b kkkkkkkkkkkkkkkk - Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5 kkkkkkkkkkkkkkk. - Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc ........ - Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a ZZZZZZZZ - CPU: 0 PID: 1689 Comm: modprobe Tainted: G B 3.18.0-rc1-mm1+ #98 - Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014 - ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78 - ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8 - ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558 + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 + + CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 + Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.10.2-1 04/01/2014 Call Trace: - [<ffffffff81cc68ae>] dump_stack+0x46/0x58 - [<ffffffff811fd848>] print_trailer+0xf8/0x160 - [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [<ffffffff811ff0f5>] object_err+0x35/0x40 - [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0 - [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 - [<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40 - [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40 - [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan] - [<ffffffff8120a995>] __asan_store1+0x75/0xb0 - [<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan] - [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan] - [<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan] - [<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan] - [<ffffffff810002d9>] do_one_initcall+0x99/0x200 - [<ffffffff811e4e5c>] ? __vunmap+0xec/0x160 - [<ffffffff81114f63>] load_module+0x2cb3/0x3b20 - [<ffffffff8110fd70>] ? m_show+0x240/0x240 - [<ffffffff81115f06>] SyS_finit_module+0x76/0x80 - [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17 + dump_stack+0x94/0xd8 + print_address_description+0x73/0x280 + kasan_report+0x144/0x187 + __asan_report_store1_noabort+0x17/0x20 + kmalloc_oob_right+0xa8/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + RIP: 0033:0x7f96443109da + RSP: 002b:00007ffcf0b51b08 EFLAGS: 00000202 ORIG_RAX: 00000000000000af + RAX: ffffffffffffffda RBX: 000055dc3ee521a0 RCX: 00007f96443109da + RDX: 00007f96445cff88 RSI: 0000000000057a50 RDI: 00007f9644992000 + RBP: 000055dc3ee510b0 R08: 0000000000000003 R09: 0000000000000000 + R10: 00007f964430cd0a R11: 0000000000000202 R12: 00007f96445cff88 + R13: 000055dc3ee51090 R14: 0000000000000000 R15: 0000000000000000 + + Allocated by task 2760: + save_stack+0x43/0xd0 + kasan_kmalloc+0xa7/0xd0 + kmem_cache_alloc_trace+0xe1/0x1b0 + kmalloc_oob_right+0x56/0xbc [test_kasan] + kmalloc_tests_init+0x16/0x700 [test_kasan] + do_one_initcall+0xa5/0x3ae + do_init_module+0x1b6/0x547 + load_module+0x75df/0x8070 + __do_sys_init_module+0x1c6/0x200 + __x64_sys_init_module+0x6e/0xb0 + do_syscall_64+0x9f/0x2c0 + entry_SYSCALL_64_after_hwframe+0x44/0xa9 + + Freed by task 815: + save_stack+0x43/0xd0 + __kasan_slab_free+0x135/0x190 + kasan_slab_free+0xe/0x10 + kfree+0x93/0x1a0 + umh_complete+0x6a/0xa0 + call_usermodehelper_exec_async+0x4c3/0x640 + ret_from_fork+0x35/0x40 + + The buggy address belongs to the object at ffff8801f44ec300 + which belongs to the cache kmalloc-128 of size 128 + The buggy address is located 123 bytes inside of + 128-byte region [ffff8801f44ec300, ffff8801f44ec380) + The buggy address belongs to the page: + page:ffffea0007d13b00 count:1 mapcount:0 mapping:ffff8801f7001640 index:0x0 + flags: 0x200000000000100(slab) + raw: 0200000000000100 ffffea0007d11dc0 0000001a0000001a ffff8801f7001640 + raw: 0000000000000000 0000000080150015 00000001ffffffff 0000000000000000 + page dumped because: kasan: bad access detected + Memory state around the buggy address: - ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc - ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00 - >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc - ^ - ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc - ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb - ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb + ffff8801f44ec200: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec280: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc + >ffff8801f44ec300: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 03 + ^ + ffff8801f44ec380: fc fc fc fc fc fc fc fc fb fb fb fb fb fb fb fb + ffff8801f44ec400: fb fb fb fb fb fb fb fb fc fc fc fc fc fc fc fc ================================================================== -The header of the report discribe what kind of bug happened and what kind of -access caused it. It's followed by the description of the accessed slub object -(see 'SLUB Debug output' section in Documentation/vm/slub.rst for details) and -the description of the accessed memory page. +The header of the report provides a short summary of what kind of bug happened +and what kind of access caused it. It's followed by a stack trace of the bad +access, a stack trace of where the accessed memory was allocated (in case bad +access happens on a slab object), and a stack trace of where the object was +freed (in case of a use-after-free bug report). Next comes a description of +the accessed slab object and information about the accessed memory page. In the last section the report shows memory state around the accessed address. Reading this part requires some understanding of how KASAN works. @@ -138,18 +150,24 @@ inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h). In the report above the arrows point to the shadow byte 03, which means that the accessed address is partially accessible. +For tag-based KASAN this last report section shows the memory tags around the +accessed address (see Implementation details section). + Implementation details ---------------------- +Generic KASAN +~~~~~~~~~~~~~ + From a high level, our approach to memory error detection is similar to that of kmemcheck: use shadow memory to record whether each byte of memory is safe -to access, and use compile-time instrumentation to check shadow memory on each -memory access. +to access, and use compile-time instrumentation to insert checks of shadow +memory on each memory access. -AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory -(e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and -offset to translate a memory address to its corresponding shadow address. +Generic KASAN dedicates 1/8th of kernel memory to its shadow memory (e.g. 16TB +to cover 128TB on x86_64) and uses direct mapping with a scale and offset to +translate a memory address to its corresponding shadow address. Here is the function which translates an address to its corresponding shadow address:: @@ -162,12 +180,38 @@ address:: where ``KASAN_SHADOW_SCALE_SHIFT = 3``. -Compile-time instrumentation used for checking memory accesses. Compiler inserts -function calls (__asan_load*(addr), __asan_store*(addr)) before each memory -access of size 1, 2, 4, 8 or 16. These functions check whether memory access is -valid or not by checking corresponding shadow memory. +Compile-time instrumentation is used to insert memory access checks. Compiler +inserts function calls (__asan_load*(addr), __asan_store*(addr)) before each +memory access of size 1, 2, 4, 8 or 16. These functions check whether memory +access is valid or not by checking corresponding shadow memory. GCC 5.0 has possibility to perform inline instrumentation. Instead of making function calls GCC directly inserts the code to check the shadow memory. This option significantly enlarges kernel but it gives x1.1-x2 performance boost over outline instrumented kernel. + +Software tag-based KASAN +~~~~~~~~~~~~~~~~~~~~~~~~ + +Tag-based KASAN uses the Top Byte Ignore (TBI) feature of modern arm64 CPUs to +store a pointer tag in the top byte of kernel pointers. Like generic KASAN it +uses shadow memory to store memory tags associated with each 16-byte memory +cell (therefore it dedicates 1/16th of the kernel memory for shadow memory). + +On each memory allocation tag-based KASAN generates a random tag, tags the +allocated memory with this tag, and embeds this tag into the returned pointer. +Software tag-based KASAN uses compile-time instrumentation to insert checks +before each memory access. These checks make sure that tag of the memory that +is being accessed is equal to tag of the pointer that is used to access this +memory. In case of a tag mismatch tag-based KASAN prints a bug report. + +Software tag-based KASAN also has two instrumentation modes (outline, that +emits callbacks to check memory accesses; and inline, that performs the shadow +memory checks inline). With outline instrumentation mode, a bug report is +simply printed from the function that performs the access check. With inline +instrumentation a brk instruction is emitted by the compiler, and a dedicated +brk handler is used to print bug reports. + +A potential expansion of this mode is a hardware tag-based mode, which would +use hardware memory tagging support instead of compiler instrumentation and +manual shadow memory manipulation. diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index dad1bb8711e2..7756f7a7c23b 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -9,7 +9,7 @@ and booting a kernel. On some systems, hot-plug tests could hang forever waiting for cpu and memory to be ready to be offlined. A special hot-plug target is created -to run full range of hot-plug tests. In default mode, hot-plug tests run +to run the full range of hot-plug tests. In default mode, hot-plug tests run in safe mode with a limited scope. In limited mode, cpu-hotplug test is run on a single cpu as opposed to all hotplug capable cpus, and memory hotplug test is run on 2% of hotplug capable memory instead of 10%. @@ -89,9 +89,9 @@ Note that some tests will require root privileges. Install selftests ================= -You can use kselftest_install.sh tool installs selftests in default -location which is tools/testing/selftests/kselftest or a user specified -location. +You can use the kselftest_install.sh tool to install selftests in the +default location, which is tools/testing/selftests/kselftest, or in a +user specified location. To install selftests in default location:: @@ -109,7 +109,7 @@ Running installed selftests Kselftest install as well as the Kselftest tarball provide a script named "run_kselftest.sh" to run the tests. -You can simply do the following to run the installed Kselftests. Please +You can simply do the following to run the installed Kselftests. Please note some tests will require root privileges:: $ cd kselftest @@ -139,7 +139,7 @@ Contributing new tests (details) default. TEST_CUSTOM_PROGS should be used by tests that require custom build - rule and prevent common build rule use. + rules and prevent common build rule use. TEST_PROGS are for test shell scripts. Please ensure shell script has its exec bit set. Otherwise, lib.mk run_tests will generate a warning. diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index 52a719b49afd..2355bef14653 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -146,7 +146,7 @@ The target is named "raid" and it accepts the following parameters: [data_offset <sectors>] This option value defines the offset into each data device where the data starts. This is used to provide out-of-place - reshaping space to avoid writing over data whilst + reshaping space to avoid writing over data while changing the layout of stripes, hence an interruption/crash may happen at any time without the risk of losing data. E.g. when adding devices to an existing raid set during diff --git a/Documentation/devicetree/bindings/.gitignore b/Documentation/devicetree/bindings/.gitignore new file mode 100644 index 000000000000..ef82fcfcccab --- /dev/null +++ b/Documentation/devicetree/bindings/.gitignore @@ -0,0 +1,2 @@ +*.example.dts +processed-schema.yaml diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile new file mode 100644 index 000000000000..50daa0b3b032 --- /dev/null +++ b/Documentation/devicetree/bindings/Makefile @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: GPL-2.0 +DT_DOC_CHECKER ?= dt-doc-validate +DT_EXTRACT_EX ?= dt-extract-example +DT_MK_SCHEMA ?= dt-mk-schema +DT_MK_SCHEMA_FLAGS := $(if $(DT_SCHEMA_FILES), -u) + +quiet_cmd_chk_binding = CHKDT $(patsubst $(srctree)/%,%,$<) + cmd_chk_binding = $(DT_DOC_CHECKER) $< ; \ + $(DT_EXTRACT_EX) $< > $@ + +$(obj)/%.example.dts: $(src)/%.yaml FORCE + $(call if_changed,chk_binding) + +DT_TMP_SCHEMA := processed-schema.yaml +extra-y += $(DT_TMP_SCHEMA) + +quiet_cmd_mk_schema = SCHEMA $@ + cmd_mk_schema = $(DT_MK_SCHEMA) $(DT_MK_SCHEMA_FLAGS) -o $@ $(filter-out FORCE, $^) + +DT_DOCS = $(shell \ + cd $(srctree)/$(src) && \ + find * \( -name '*.yaml' ! -name $(DT_TMP_SCHEMA) \) \ + ) + +DT_SCHEMA_FILES ?= $(addprefix $(src)/,$(DT_DOCS)) + +extra-y += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES)) +extra-y += $(patsubst $(src)/%.yaml,%.example.dtb, $(DT_SCHEMA_FILES)) + +$(obj)/$(DT_TMP_SCHEMA): $(DT_SCHEMA_FILES) FORCE + $(call if_changed,mk_schema) diff --git a/Documentation/devicetree/bindings/arm/al,alpine.txt b/Documentation/devicetree/bindings/arm/al,alpine.txt index f404a4f9b165..d00debe2e86f 100644 --- a/Documentation/devicetree/bindings/arm/al,alpine.txt +++ b/Documentation/devicetree/bindings/arm/al,alpine.txt @@ -14,75 +14,3 @@ compatible: must contain "al,alpine" ... } - -* CPU node: - -The Alpine platform includes cortex-a15 cores. -enable-method: must be "al,alpine-smp" to allow smp [1] - -Example: - -cpus { - #address-cells = <1>; - #size-cells = <0>; - enable-method = "al,alpine-smp"; - - cpu@0 { - compatible = "arm,cortex-a15"; - device_type = "cpu"; - reg = <0>; - }; - - cpu@1 { - compatible = "arm,cortex-a15"; - device_type = "cpu"; - reg = <1>; - }; - - cpu@2 { - compatible = "arm,cortex-a15"; - device_type = "cpu"; - reg = <2>; - }; - - cpu@3 { - compatible = "arm,cortex-a15"; - device_type = "cpu"; - reg = <3>; - }; -}; - - -* Alpine CPU resume registers - -The CPU resume register are used to define required resume address after -reset. - -Properties: -- compatible : Should contain "al,alpine-cpu-resume". -- reg : Offset and length of the register set for the device - -Example: - -cpu_resume { - compatible = "al,alpine-cpu-resume"; - reg = <0xfbff5ed0 0x30>; -}; - -* Alpine System-Fabric Service Registers - -The System-Fabric Service Registers allow various operation on CPU and -system fabric, like powering CPUs off. - -Properties: -- compatible : Should contain "al,alpine-sysfabric-service" and "syscon". -- reg : Offset and length of the register set for the device - -Example: - -nb_service { - compatible = "al,alpine-sysfabric-service", "syscon"; - reg = <0xfb070000 0x10000>; -}; - -[1] arm/cpu-enable-method/al,alpine-smp diff --git a/Documentation/devicetree/bindings/arm/altera.txt b/Documentation/devicetree/bindings/arm/altera.txt deleted file mode 100644 index 558735aacca8..000000000000 --- a/Documentation/devicetree/bindings/arm/altera.txt +++ /dev/null @@ -1,14 +0,0 @@ -Altera's SoCFPGA platform device tree bindings ---------------------------------------------- - -Boards with Cyclone 5 SoC: -Required root node properties: -compatible = "altr,socfpga-cyclone5", "altr,socfpga"; - -Boards with Arria 5 SoC: -Required root node properties: -compatible = "altr,socfpga-arria5", "altr,socfpga"; - -Boards with Arria 10 SoC: -Required root node properties: -compatible = "altr,socfpga-arria10", "altr,socfpga"; diff --git a/Documentation/devicetree/bindings/arm/altera.yaml b/Documentation/devicetree/bindings/arm/altera.yaml new file mode 100644 index 000000000000..49e0362ddc11 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/altera.yaml @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/altera.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Altera's SoCFPGA platform device tree bindings + +maintainers: + - Dinh Nguyen <dinguyen@kernel.org> + +properties: + compatible: + items: + - enum: + - altr,socfpga-cyclone5 + - altr,socfpga-arria5 + - altr,socfpga-arria10 + - const: altr,socfpga +... diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.txt b/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.txt deleted file mode 100644 index 2c28f1d12f45..000000000000 --- a/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.txt +++ /dev/null @@ -1,11 +0,0 @@ -Altera SOCFPGA Clock Manager - -Required properties: -- compatible : "altr,clk-mgr" -- reg : Should contain base address and length for Clock Manager - -Example: - clkmgr@ffd04000 { - compatible = "altr,clk-mgr"; - reg = <0xffd04000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.yaml b/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.yaml new file mode 100644 index 000000000000..e4131fa42b26 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.yaml @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/altera/socfpga-clk-manager.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Altera SOCFPGA Clock Manager + +maintainers: + - Dinh Nguyen <dinguyen@kernel.org> + +description: test + +properties: + compatible: + items: + - const: altr,clk-mgr + reg: + maxItems: 1 + +required: + - compatible + +examples: + - | + clkmgr@ffd04000 { + compatible = "altr,clk-mgr"; + reg = <0xffd04000 0x1000>; + }; + +... diff --git a/Documentation/devicetree/bindings/arm/amlogic,scpi.txt b/Documentation/devicetree/bindings/arm/amlogic,scpi.txt index 7b9a861e9306..5ab59da052df 100644 --- a/Documentation/devicetree/bindings/arm/amlogic,scpi.txt +++ b/Documentation/devicetree/bindings/arm/amlogic,scpi.txt @@ -17,4 +17,11 @@ Required sub-node properties: - compatible : should be "amlogic,meson-gxbb-scp-shmem" for SRAM based shared memory on Amlogic GXBB SoC. +Sensor bindings for the sensors based on SCPI Message Protocol +-------------------------------------------------------------- +SCPI provides an API to access the various sensors on the SoC. + +Required properties: +- compatible : should be "amlogic,meson-gxbb-scpi-sensors". + [0] Documentation/devicetree/bindings/arm/arm,scpi.txt diff --git a/Documentation/devicetree/bindings/arm/amlogic.txt b/Documentation/devicetree/bindings/arm/amlogic.txt index b5c2b5c35766..7f40cb5f490b 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.txt +++ b/Documentation/devicetree/bindings/arm/amlogic.txt @@ -57,12 +57,17 @@ Boards with the Amlogic Meson AXG A113D SoC shall have the following properties: Required root node property: compatible: "amlogic,a113d", "amlogic,meson-axg"; +Boards with the Amlogic Meson G12A S905D2 SoC shall have the following properties: + Required root node property: + compatible: "amlogic,g12a"; + Board compatible values (alphabetically, grouped by SoC): - "geniatech,atv1200" (Meson6) - "minix,neo-x8" (Meson8) + - "endless,ec100" (Meson8b) - "hardkernel,odroid-c1" (Meson8b) - "tronfy,mxq" (Meson8b) @@ -86,8 +91,10 @@ Board compatible values (alphabetically, grouped by SoC): - "amlogic,p230" (Meson gxl s905d) - "amlogic,p231" (Meson gxl s905d) + - "phicomm,n1" (Meson gxl s905d) - "amlogic,p241" (Meson gxl s805x) + - "libretech,aml-s805x-ac" (Meson gxl s805x) - "amlogic,p281" (Meson gxl s905w) - "oranth,tx3-mini" (Meson gxl s905w) @@ -101,6 +108,9 @@ Board compatible values (alphabetically, grouped by SoC): - "amlogic,s400" (Meson axg a113d) + - "amlogic,u200" (Meson g12a s905d2) + - "amediatech,x96-max" (Meson g12a s905x2) + Amlogic Meson Firmware registers Interface ------------------------------------------ diff --git a/Documentation/devicetree/bindings/arm/armadeus.txt b/Documentation/devicetree/bindings/arm/armadeus.txt deleted file mode 100644 index 9821283ff516..000000000000 --- a/Documentation/devicetree/bindings/arm/armadeus.txt +++ /dev/null @@ -1,6 +0,0 @@ -Armadeus i.MX Platforms Device Tree Bindings ------------------------------------------------ - -APF51: i.MX51 based module. -Required root node properties: - - compatible = "armadeus,imx51-apf51", "fsl,imx51"; diff --git a/Documentation/devicetree/bindings/arm/atmel-at91.txt b/Documentation/devicetree/bindings/arm/atmel-at91.txt index 31220b54d85d..4bf1b4da7659 100644 --- a/Documentation/devicetree/bindings/arm/atmel-at91.txt +++ b/Documentation/devicetree/bindings/arm/atmel-at91.txt @@ -70,173 +70,3 @@ compatible: must be one of: - "atmel,samv71q19" - "atmel,samv71q20" - "atmel,samv71q21" - -Chipid required properties: -- compatible: Should be "atmel,sama5d2-chipid" -- reg : Should contain registers location and length - -PIT Timer required properties: -- compatible: Should be "atmel,at91sam9260-pit" -- reg: Should contain registers location and length -- interrupts: Should contain interrupt for the PIT which is the IRQ line - shared across all System Controller members. - -System Timer (ST) required properties: -- compatible: Should be "atmel,at91rm9200-st", "syscon", "simple-mfd" -- reg: Should contain registers location and length -- interrupts: Should contain interrupt for the ST which is the IRQ line - shared across all System Controller members. -- clocks: phandle to input clock. -Its subnodes can be: -- watchdog: compatible should be "atmel,at91rm9200-wdt" - -RSTC Reset Controller required properties: -- compatible: Should be "atmel,<chip>-rstc". - <chip> can be "at91sam9260" or "at91sam9g45" or "sama5d3" -- reg: Should contain registers location and length -- clocks: phandle to input clock. - -Example: - - rstc@fffffd00 { - compatible = "atmel,at91sam9260-rstc"; - reg = <0xfffffd00 0x10>; - clocks = <&clk32k>; - }; - -RAMC SDRAM/DDR Controller required properties: -- compatible: Should be "atmel,at91rm9200-sdramc", "syscon" - "atmel,at91sam9260-sdramc", - "atmel,at91sam9g45-ddramc", - "atmel,sama5d3-ddramc", -- reg: Should contain registers location and length - -Examples: - - ramc0: ramc@ffffe800 { - compatible = "atmel,at91sam9g45-ddramc"; - reg = <0xffffe800 0x200>; - }; - -SHDWC Shutdown Controller - -required properties: -- compatible: Should be "atmel,<chip>-shdwc". - <chip> can be "at91sam9260", "at91sam9rl" or "at91sam9x5". -- reg: Should contain registers location and length -- clocks: phandle to input clock. - -optional properties: -- atmel,wakeup-mode: String, operation mode of the wakeup mode. - Supported values are: "none", "high", "low", "any". -- atmel,wakeup-counter: Counter on Wake-up 0 (between 0x0 and 0xf). - -optional at91sam9260 properties: -- atmel,wakeup-rtt-timer: boolean to enable Real-time Timer Wake-up. - -optional at91sam9rl properties: -- atmel,wakeup-rtc-timer: boolean to enable Real-time Clock Wake-up. -- atmel,wakeup-rtt-timer: boolean to enable Real-time Timer Wake-up. - -optional at91sam9x5 properties: -- atmel,wakeup-rtc-timer: boolean to enable Real-time Clock Wake-up. - -Example: - - shdwc@fffffd10 { - compatible = "atmel,at91sam9260-shdwc"; - reg = <0xfffffd10 0x10>; - clocks = <&clk32k>; - }; - -SHDWC SAMA5D2-Compatible Shutdown Controller - -1) shdwc node - -required properties: -- compatible: should be "atmel,sama5d2-shdwc". -- reg: should contain registers location and length -- clocks: phandle to input clock. -- #address-cells: should be one. The cell is the wake-up input index. -- #size-cells: should be zero. - -optional properties: - -- debounce-delay-us: minimum wake-up inputs debouncer period in - microseconds. It's usually a board-related property. -- atmel,wakeup-rtc-timer: boolean to enable Real-Time Clock wake-up. - -The node contains child nodes for each wake-up input that the platform uses. - -2) input nodes - -Wake-up input nodes are usually described in the "board" part of the Device -Tree. Note also that input 0 is linked to the wake-up pin and is frequently -used. - -Required properties: -- reg: should contain the wake-up input index [0 - 15]. - -Optional properties: -- atmel,wakeup-active-high: boolean, the corresponding wake-up input described - by the child, forces the wake-up of the core power supply on a high level. - The default is to be active low. - -Example: - -On the SoC side: - shdwc@f8048010 { - compatible = "atmel,sama5d2-shdwc"; - reg = <0xf8048010 0x10>; - clocks = <&clk32k>; - #address-cells = <1>; - #size-cells = <0>; - atmel,wakeup-rtc-timer; - }; - -On the board side: - shdwc@f8048010 { - debounce-delay-us = <976>; - - input@0 { - reg = <0>; - }; - - input@1 { - reg = <1>; - atmel,wakeup-active-high; - }; - }; - -Special Function Registers (SFR) - -Special Function Registers (SFR) manage specific aspects of the integrated -memory, bridge implementations, processor and other functionality not controlled -elsewhere. - -required properties: -- compatible: Should be "atmel,<chip>-sfr", "syscon" or - "atmel,<chip>-sfrbu", "syscon" - <chip> can be "sama5d3", "sama5d4" or "sama5d2". -- reg: Should contain registers location and length - - sfr@f0038000 { - compatible = "atmel,sama5d3-sfr", "syscon"; - reg = <0xf0038000 0x60>; - }; - -Security Module (SECUMOD) - -The Security Module macrocell provides all necessary secure functions to avoid -voltage, temperature, frequency and mechanical attacks on the chip. It also -embeds secure memories that can be scrambled - -required properties: -- compatible: Should be "atmel,<chip>-secumod", "syscon". - <chip> can be "sama5d2". -- reg: Should contain registers location and length - - secumod@fc040000 { - compatible = "atmel,sama5d2-secumod", "syscon"; - reg = <0xfc040000 0x100>; - }; diff --git a/Documentation/devicetree/bindings/arm/atmel-sysregs.txt b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt new file mode 100644 index 000000000000..e61d00e25b95 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/atmel-sysregs.txt @@ -0,0 +1,183 @@ +Atmel system registers + +Chipid required properties: +- compatible: Should be "atmel,sama5d2-chipid" +- reg : Should contain registers location and length + +PIT Timer required properties: +- compatible: Should be "atmel,at91sam9260-pit" +- reg: Should contain registers location and length +- interrupts: Should contain interrupt for the PIT which is the IRQ line + shared across all System Controller members. + +System Timer (ST) required properties: +- compatible: Should be "atmel,at91rm9200-st", "syscon", "simple-mfd" +- reg: Should contain registers location and length +- interrupts: Should contain interrupt for the ST which is the IRQ line + shared across all System Controller members. +- clocks: phandle to input clock. +Its subnodes can be: +- watchdog: compatible should be "atmel,at91rm9200-wdt" + +RSTC Reset Controller required properties: +- compatible: Should be "atmel,<chip>-rstc". + <chip> can be "at91sam9260", "at91sam9g45", "sama5d3" or "samx7" + it also can be "microchip,sam9x60-rstc" +- reg: Should contain registers location and length +- clocks: phandle to input clock. + +Example: + + rstc@fffffd00 { + compatible = "atmel,at91sam9260-rstc"; + reg = <0xfffffd00 0x10>; + clocks = <&clk32k>; + }; + +RAMC SDRAM/DDR Controller required properties: +- compatible: Should be "atmel,at91rm9200-sdramc", "syscon" + "atmel,at91sam9260-sdramc", + "atmel,at91sam9g45-ddramc", + "atmel,sama5d3-ddramc", +- reg: Should contain registers location and length + +Examples: + + ramc0: ramc@ffffe800 { + compatible = "atmel,at91sam9g45-ddramc"; + reg = <0xffffe800 0x200>; + }; + +SHDWC Shutdown Controller + +required properties: +- compatible: Should be "atmel,<chip>-shdwc". + <chip> can be "at91sam9260", "at91sam9rl" or "at91sam9x5". +- reg: Should contain registers location and length +- clocks: phandle to input clock. + +optional properties: +- atmel,wakeup-mode: String, operation mode of the wakeup mode. + Supported values are: "none", "high", "low", "any". +- atmel,wakeup-counter: Counter on Wake-up 0 (between 0x0 and 0xf). + +optional at91sam9260 properties: +- atmel,wakeup-rtt-timer: boolean to enable Real-time Timer Wake-up. + +optional at91sam9rl properties: +- atmel,wakeup-rtc-timer: boolean to enable Real-time Clock Wake-up. +- atmel,wakeup-rtt-timer: boolean to enable Real-time Timer Wake-up. + +optional at91sam9x5 properties: +- atmel,wakeup-rtc-timer: boolean to enable Real-time Clock Wake-up. + +Example: + + shdwc@fffffd10 { + compatible = "atmel,at91sam9260-shdwc"; + reg = <0xfffffd10 0x10>; + clocks = <&clk32k>; + }; + +SHDWC SAMA5D2-Compatible Shutdown Controller + +1) shdwc node + +required properties: +- compatible: should be "atmel,sama5d2-shdwc". +- reg: should contain registers location and length +- clocks: phandle to input clock. +- #address-cells: should be one. The cell is the wake-up input index. +- #size-cells: should be zero. + +optional properties: + +- debounce-delay-us: minimum wake-up inputs debouncer period in + microseconds. It's usually a board-related property. +- atmel,wakeup-rtc-timer: boolean to enable Real-Time Clock wake-up. + +The node contains child nodes for each wake-up input that the platform uses. + +2) input nodes + +Wake-up input nodes are usually described in the "board" part of the Device +Tree. Note also that input 0 is linked to the wake-up pin and is frequently +used. + +Required properties: +- reg: should contain the wake-up input index [0 - 15]. + +Optional properties: +- atmel,wakeup-active-high: boolean, the corresponding wake-up input described + by the child, forces the wake-up of the core power supply on a high level. + The default is to be active low. + +Example: + +On the SoC side: + shdwc@f8048010 { + compatible = "atmel,sama5d2-shdwc"; + reg = <0xf8048010 0x10>; + clocks = <&clk32k>; + #address-cells = <1>; + #size-cells = <0>; + atmel,wakeup-rtc-timer; + }; + +On the board side: + shdwc@f8048010 { + debounce-delay-us = <976>; + + input@0 { + reg = <0>; + }; + + input@1 { + reg = <1>; + atmel,wakeup-active-high; + }; + }; + +Special Function Registers (SFR) + +Special Function Registers (SFR) manage specific aspects of the integrated +memory, bridge implementations, processor and other functionality not controlled +elsewhere. + +required properties: +- compatible: Should be "atmel,<chip>-sfr", "syscon" or + "atmel,<chip>-sfrbu", "syscon" + <chip> can be "sama5d3", "sama5d4" or "sama5d2". + It also can be "microchip,sam9x60-sfr", "syscon". +- reg: Should contain registers location and length + + sfr@f0038000 { + compatible = "atmel,sama5d3-sfr", "syscon"; + reg = <0xf0038000 0x60>; + }; + +Security Module (SECUMOD) + +The Security Module macrocell provides all necessary secure functions to avoid +voltage, temperature, frequency and mechanical attacks on the chip. It also +embeds secure memories that can be scrambled. + +The Security Module also offers the PIOBU pins which can be used as GPIO pins. +Note that they maintain their voltage during Backup/Self-refresh. + +required properties: +- compatible: Should be "atmel,<chip>-secumod", "syscon". + <chip> can be "sama5d2". +- reg: Should contain registers location and length +- gpio-controller: Marks the port as GPIO controller. +- #gpio-cells: There are 2. The pin number is the + first, the second represents additional + parameters such as GPIO_ACTIVE_HIGH/LOW. + + + secumod@fc040000 { + compatible = "atmel,sama5d2-secumod", "syscon"; + reg = <0xfc040000 0x100>; + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt index 1e3e29a545e2..245328f36580 100644 --- a/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt +++ b/Documentation/devicetree/bindings/arm/bcm/brcm,bcm2835.txt @@ -30,6 +30,10 @@ Raspberry Pi 2 Model B Required root node properties: compatible = "raspberrypi,2-model-b", "brcm,bcm2836"; +Raspberry Pi 3 Model A+ +Required root node properties: +compatible = "raspberrypi,3-model-a-plus", "brcm,bcm2837"; + Raspberry Pi 3 Model B Required root node properties: compatible = "raspberrypi,3-model-b", "brcm,bcm2837"; @@ -42,6 +46,14 @@ Raspberry Pi Compute Module Required root node properties: compatible = "raspberrypi,compute-module", "brcm,bcm2835"; +Raspberry Pi Compute Module 3 +Required root node properties: +compatible = "raspberrypi,3-compute-module", "brcm,bcm2837"; + +Raspberry Pi Compute Module 3 Lite +Required root node properties: +compatible = "raspberrypi,3-compute-module-lite", "brcm,bcm2837"; + Raspberry Pi Zero Required root node properties: compatible = "raspberrypi,model-zero", "brcm,bcm2835"; diff --git a/Documentation/devicetree/bindings/arm/bhf.txt b/Documentation/devicetree/bindings/arm/bhf.txt deleted file mode 100644 index 886b503caf9c..000000000000 --- a/Documentation/devicetree/bindings/arm/bhf.txt +++ /dev/null @@ -1,6 +0,0 @@ -Beckhoff Automation Platforms Device Tree Bindings --------------------------------------------------- - -CX9020 Embedded PC -Required root node properties: - - compatible = "bhf,cx9020", "fsl,imx53"; diff --git a/Documentation/devicetree/bindings/arm/bitmain.yaml b/Documentation/devicetree/bindings/arm/bitmain.yaml new file mode 100644 index 000000000000..0efdb4ac028e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bitmain.yaml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/bitmain.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bitmain platform device tree bindings + +maintainers: + - Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org> + +properties: + compatible: + items: + - enum: + - bitmain,sophon-edge + - const: bitmain,bm1880 +... diff --git a/Documentation/devicetree/bindings/arm/calxeda.txt b/Documentation/devicetree/bindings/arm/calxeda.txt deleted file mode 100644 index 25fcf96795ca..000000000000 --- a/Documentation/devicetree/bindings/arm/calxeda.txt +++ /dev/null @@ -1,15 +0,0 @@ -Calxeda Platforms Device Tree Bindings ------------------------------------------------ - -Boards with Calxeda Cortex-A9 based ECX-1000 (Highbank) SOC shall have the -following properties. - -Required root node properties: - - compatible = "calxeda,highbank"; - - -Boards with Calxeda Cortex-A15 based ECX-2000 SOC shall have the following -properties. - -Required root node properties: - - compatible = "calxeda,ecx-2000"; diff --git a/Documentation/devicetree/bindings/arm/calxeda.yaml b/Documentation/devicetree/bindings/arm/calxeda.yaml new file mode 100644 index 000000000000..aa5571d23c39 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/calxeda.yaml @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/calxeda.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Calxeda Platforms Device Tree Bindings + +maintainers: + - Rob Herring <robh@kernel.org> +description: |+ + Bindings for boards with Calxeda Cortex-A9 based ECX-1000 (Highbank) SOC + or Cortex-A15 based ECX-2000 SOCs + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - calxeda,highbank + - calxeda,ecx-2000 diff --git a/Documentation/devicetree/bindings/arm/compulab-boards.txt b/Documentation/devicetree/bindings/arm/compulab-boards.txt deleted file mode 100644 index 42a10285af9c..000000000000 --- a/Documentation/devicetree/bindings/arm/compulab-boards.txt +++ /dev/null @@ -1,25 +0,0 @@ -CompuLab SB-SOM is a multi-module baseboard capable of carrying: - - CM-T43 - - CM-T54 - - CM-QS600 - - CL-SOM-AM57x - - CL-SOM-iMX7 -modules with minor modifications to the SB-SOM assembly. - -Required root node properties: - - compatible = should be "compulab,sb-som" - -Compulab CL-SOM-iMX7 is a miniature System-on-Module (SoM) based on -Freescale i.MX7 ARM Cortex-A7 System-on-Chip. - -Required root node properties: - - compatible = "compulab,cl-som-imx7", "fsl,imx7d"; - -Compulab SBC-iMX7 is a single board computer based on the -Freescale i.MX7 system-on-chip. SBC-iMX7 is implemented with -the CL-SOM-iMX7 System-on-Module providing most of the functions, -and SB-SOM-iMX7 carrier board providing additional peripheral -functions and connectors. - -Required root node properties: - - compatible = "compulab,sbc-imx7", "compulab,cl-som-imx7", "fsl,imx7d"; diff --git a/Documentation/devicetree/bindings/arm/coresight.txt b/Documentation/devicetree/bindings/arm/coresight.txt index 5d1ad09bafb4..f8aff65ab921 100644 --- a/Documentation/devicetree/bindings/arm/coresight.txt +++ b/Documentation/devicetree/bindings/arm/coresight.txt @@ -54,9 +54,7 @@ its hardware characteristcs. clocks the core of that coresight component. The latter clock is optional. - * port or ports: The representation of the component's port - layout using the generic DT graph presentation found in - "bindings/graph.txt". + * port or ports: see "Graph bindings for Coresight" below. * Additional required properties for System Trace Macrocells (STM): * reg: along with the physical base address and length of the register @@ -73,7 +71,7 @@ its hardware characteristcs. AMBA markee): - "arm,coresight-replicator" - * port or ports: same as above. + * port or ports: see "Graph bindings for Coresight" below. * Optional properties for ETM/PTMs: @@ -96,6 +94,20 @@ its hardware characteristcs. * interrupts : Exactly one SPI may be listed for reporting the address error +Graph bindings for Coresight +------------------------------- + +Coresight components are interconnected to create a data path for the flow of +trace data generated from the "sources" to their collection points "sink". +Each coresight component must describe the "input" and "output" connections. +The connections must be described via generic DT graph bindings as described +by the "bindings/graph.txt", where each "port" along with an "endpoint" +component represents a hardware port and the connection. + + * All output ports must be listed inside a child node named "out-ports" + * All input ports must be listed inside a child node named "in-ports". + * Port address must match the hardware port number. + Example: 1. Sinks @@ -105,10 +117,11 @@ Example: clocks = <&oscclk6a>; clock-names = "apb_pclk"; - port { - etb_in_port: endpoint@0 { - slave-mode; - remote-endpoint = <&replicator_out_port0>; + in-ports { + port { + etb_in_port: endpoint@0 { + remote-endpoint = <&replicator_out_port0>; + }; }; }; }; @@ -119,10 +132,11 @@ Example: clocks = <&oscclk6a>; clock-names = "apb_pclk"; - port { - tpiu_in_port: endpoint@0 { - slave-mode; - remote-endpoint = <&replicator_out_port1>; + in-ports { + port { + tpiu_in_port: endpoint@0 { + remote-endpoint = <&replicator_out_port1>; + }; }; }; }; @@ -133,22 +147,16 @@ Example: clocks = <&oscclk6a>; clock-names = "apb_pclk"; - ports { - #address-cells = <1>; - #size-cells = <0>; - - /* input port */ - port@0 { - reg = <0>; + in-ports { + port { etr_in_port: endpoint { - slave-mode; remote-endpoint = <&replicator2_out_port0>; }; }; + }; - /* CATU link represented by output port */ - port@1 { - reg = <1>; + out-ports { + port { etr_out_port: endpoint { remote-endpoint = <&catu_in_port>; }; @@ -163,7 +171,7 @@ Example: */ compatible = "arm,coresight-replicator"; - ports { + out-ports { #address-cells = <1>; #size-cells = <0>; @@ -181,12 +189,11 @@ Example: remote-endpoint = <&tpiu_in_port>; }; }; + }; - /* replicator input port */ - port@2 { - reg = <0>; + in-ports { + port { replicator_in_port0: endpoint { - slave-mode; remote-endpoint = <&funnel_out_port0>; }; }; @@ -199,40 +206,36 @@ Example: clocks = <&oscclk6a>; clock-names = "apb_pclk"; - ports { - #address-cells = <1>; - #size-cells = <0>; - - /* funnel output port */ - port@0 { - reg = <0>; + out-ports { + port { funnel_out_port0: endpoint { remote-endpoint = <&replicator_in_port0>; }; }; + }; - /* funnel input ports */ - port@1 { + in-ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { reg = <0>; funnel_in_port0: endpoint { - slave-mode; remote-endpoint = <&ptm0_out_port>; }; }; - port@2 { + port@1 { reg = <1>; funnel_in_port1: endpoint { - slave-mode; remote-endpoint = <&ptm1_out_port>; }; }; - port@3 { + port@2 { reg = <2>; funnel_in_port2: endpoint { - slave-mode; remote-endpoint = <&etm0_out_port>; }; }; @@ -248,9 +251,11 @@ Example: cpu = <&cpu0>; clocks = <&oscclk6a>; clock-names = "apb_pclk"; - port { - ptm0_out_port: endpoint { - remote-endpoint = <&funnel_in_port0>; + out-ports { + port { + ptm0_out_port: endpoint { + remote-endpoint = <&funnel_in_port0>; + }; }; }; }; @@ -262,9 +267,11 @@ Example: cpu = <&cpu1>; clocks = <&oscclk6a>; clock-names = "apb_pclk"; - port { - ptm1_out_port: endpoint { - remote-endpoint = <&funnel_in_port1>; + out-ports { + port { + ptm1_out_port: endpoint { + remote-endpoint = <&funnel_in_port1>; + }; }; }; }; @@ -278,9 +285,11 @@ Example: clocks = <&soc_smc50mhz>; clock-names = "apb_pclk"; - port { - stm_out_port: endpoint { - remote-endpoint = <&main_funnel_in_port2>; + out-ports { + port { + stm_out_port: endpoint { + remote-endpoint = <&main_funnel_in_port2>; + }; }; }; }; @@ -295,10 +304,11 @@ Example: clock-names = "apb_pclk"; interrupts = <GIC_SPI 4 IRQ_TYPE_LEVEL_HIGH>; - port { - catu_in_port: endpoint { - slave-mode; - remote-endpoint = <&etr_out_port>; + in-ports { + port { + catu_in_port: endpoint { + remote-endpoint = <&etr_out_port>; + }; }; }; }; diff --git a/Documentation/devicetree/bindings/arm/cpu-capacity.txt b/Documentation/devicetree/bindings/arm/cpu-capacity.txt index 9b5685a1d15d..96fa46cb133c 100644 --- a/Documentation/devicetree/bindings/arm/cpu-capacity.txt +++ b/Documentation/devicetree/bindings/arm/cpu-capacity.txt @@ -59,9 +59,11 @@ mhz values (normalized w.r.t. the highest value found while parsing the DT). =========================================== Example 1 (ARM 64-bit, 6-cpu system, two clusters): -capacities-dmips-mhz are scaled w.r.t. 1024 (cpu@0 and cpu@1) -supposing cluster0@max-freq=1100 and custer1@max-freq=850, -final capacities are 1024 for cluster0 and 446 for cluster1 +The capacities-dmips-mhz or DMIPS/MHz values (scaled to 1024) +are 1024 and 578 for cluster0 and cluster1. Further normalization +is done by the operating system based on cluster0@max-freq=1100 and +custer1@max-freq=850, final capacities are 1024 for cluster0 and +446 for cluster1 (576*850/1100). cpus { #address-cells = <2>; @@ -233,4 +235,4 @@ cpus { =========================================== [1] ARM Linux Kernel documentation - CPUs bindings - Documentation/devicetree/bindings/arm/cpus.txt + Documentation/devicetree/bindings/arm/cpus.yaml diff --git a/Documentation/devicetree/bindings/arm/cpu-enable-method/al,alpine-smp b/Documentation/devicetree/bindings/arm/cpu-enable-method/al,alpine-smp index c2e0cc5e4cfd..35e5afb6d9ad 100644 --- a/Documentation/devicetree/bindings/arm/cpu-enable-method/al,alpine-smp +++ b/Documentation/devicetree/bindings/arm/cpu-enable-method/al,alpine-smp @@ -14,7 +14,28 @@ Related properties: (none) Note: This enable method requires valid nodes compatible with -"al,alpine-cpu-resume" and "al,alpine-nb-service"[1]. +"al,alpine-cpu-resume" and "al,alpine-nb-service". + + +* Alpine CPU resume registers + +The CPU resume register are used to define required resume address after +reset. + +Properties: +- compatible : Should contain "al,alpine-cpu-resume". +- reg : Offset and length of the register set for the device + + +* Alpine System-Fabric Service Registers + +The System-Fabric Service Registers allow various operation on CPU and +system fabric, like powering CPUs off. + +Properties: +- compatible : Should contain "al,alpine-sysfabric-service" and "syscon". +- reg : Offset and length of the register set for the device + Example: @@ -48,5 +69,12 @@ cpus { }; }; --- -[1] arm/al,alpine.txt +cpu_resume { + compatible = "al,alpine-cpu-resume"; + reg = <0xfbff5ed0 0x30>; +}; + +nb_service { + compatible = "al,alpine-sysfabric-service", "syscon"; + reg = <0xfb070000 0x10000>; +}; diff --git a/Documentation/devicetree/bindings/arm/cpus.txt b/Documentation/devicetree/bindings/arm/cpus.txt deleted file mode 100644 index 96dfccc0faa8..000000000000 --- a/Documentation/devicetree/bindings/arm/cpus.txt +++ /dev/null @@ -1,490 +0,0 @@ -================= -ARM CPUs bindings -================= - -The device tree allows to describe the layout of CPUs in a system through -the "cpus" node, which in turn contains a number of subnodes (ie "cpu") -defining properties for every cpu. - -Bindings for CPU nodes follow the Devicetree Specification, available from: - -https://www.devicetree.org/specifications/ - -with updates for 32-bit and 64-bit ARM systems provided in this document. - -================================ -Convention used in this document -================================ - -This document follows the conventions described in the Devicetree -Specification, with the addition: - -- square brackets define bitfields, eg reg[7:0] value of the bitfield in - the reg property contained in bits 7 down to 0 - -===================================== -cpus and cpu node bindings definition -===================================== - -The ARM architecture, in accordance with the Devicetree Specification, -requires the cpus and cpu nodes to be present and contain the properties -described below. - -- cpus node - - Description: Container of cpu nodes - - The node name must be "cpus". - - A cpus node must define the following properties: - - - #address-cells - Usage: required - Value type: <u32> - - Definition depends on ARM architecture version and - configuration: - - # On uniprocessor ARM architectures previous to v7 - value must be 1, to enable a simple enumeration - scheme for processors that do not have a HW CPU - identification register. - # On 32-bit ARM 11 MPcore, ARM v7 or later systems - value must be 1, that corresponds to CPUID/MPIDR - registers sizes. - # On ARM v8 64-bit systems value should be set to 2, - that corresponds to the MPIDR_EL1 register size. - If MPIDR_EL1[63:32] value is equal to 0 on all CPUs - in the system, #address-cells can be set to 1, since - MPIDR_EL1[63:32] bits are not used for CPUs - identification. - - #size-cells - Usage: required - Value type: <u32> - Definition: must be set to 0 - -- cpu node - - Description: Describes a CPU in an ARM based system - - PROPERTIES - - - device_type - Usage: required - Value type: <string> - Definition: must be "cpu" - - reg - Usage and definition depend on ARM architecture version and - configuration: - - # On uniprocessor ARM architectures previous to v7 - this property is required and must be set to 0. - - # On ARM 11 MPcore based systems this property is - required and matches the CPUID[11:0] register bits. - - Bits [11:0] in the reg cell must be set to - bits [11:0] in CPU ID register. - - All other bits in the reg cell must be set to 0. - - # On 32-bit ARM v7 or later systems this property is - required and matches the CPU MPIDR[23:0] register - bits. - - Bits [23:0] in the reg cell must be set to - bits [23:0] in MPIDR. - - All other bits in the reg cell must be set to 0. - - # On ARM v8 64-bit systems this property is required - and matches the MPIDR_EL1 register affinity bits. - - * If cpus node's #address-cells property is set to 2 - - The first reg cell bits [7:0] must be set to - bits [39:32] of MPIDR_EL1. - - The second reg cell bits [23:0] must be set to - bits [23:0] of MPIDR_EL1. - - * If cpus node's #address-cells property is set to 1 - - The reg cell bits [23:0] must be set to bits [23:0] - of MPIDR_EL1. - - All other bits in the reg cells must be set to 0. - - - compatible: - Usage: required - Value type: <string> - Definition: should be one of: - "arm,arm710t" - "arm,arm720t" - "arm,arm740t" - "arm,arm7ej-s" - "arm,arm7tdmi" - "arm,arm7tdmi-s" - "arm,arm9es" - "arm,arm9ej-s" - "arm,arm920t" - "arm,arm922t" - "arm,arm925" - "arm,arm926e-s" - "arm,arm926ej-s" - "arm,arm940t" - "arm,arm946e-s" - "arm,arm966e-s" - "arm,arm968e-s" - "arm,arm9tdmi" - "arm,arm1020e" - "arm,arm1020t" - "arm,arm1022e" - "arm,arm1026ej-s" - "arm,arm1136j-s" - "arm,arm1136jf-s" - "arm,arm1156t2-s" - "arm,arm1156t2f-s" - "arm,arm1176jzf" - "arm,arm1176jz-s" - "arm,arm1176jzf-s" - "arm,arm11mpcore" - "arm,cortex-a5" - "arm,cortex-a7" - "arm,cortex-a8" - "arm,cortex-a9" - "arm,cortex-a12" - "arm,cortex-a15" - "arm,cortex-a17" - "arm,cortex-a53" - "arm,cortex-a57" - "arm,cortex-a72" - "arm,cortex-a73" - "arm,cortex-m0" - "arm,cortex-m0+" - "arm,cortex-m1" - "arm,cortex-m3" - "arm,cortex-m4" - "arm,cortex-r4" - "arm,cortex-r5" - "arm,cortex-r7" - "brcm,brahma-b15" - "brcm,brahma-b53" - "brcm,vulcan" - "cavium,thunder" - "cavium,thunder2" - "faraday,fa526" - "intel,sa110" - "intel,sa1100" - "marvell,feroceon" - "marvell,mohawk" - "marvell,pj4a" - "marvell,pj4b" - "marvell,sheeva-v5" - "nvidia,tegra132-denver" - "nvidia,tegra186-denver" - "nvidia,tegra194-carmel" - "qcom,krait" - "qcom,kryo" - "qcom,kryo385" - "qcom,scorpion" - - enable-method - Value type: <stringlist> - Usage and definition depend on ARM architecture version. - # On ARM v8 64-bit this property is required and must - be one of: - "psci" - "spin-table" - # On ARM 32-bit systems this property is optional and - can be one of: - "actions,s500-smp" - "allwinner,sun6i-a31" - "allwinner,sun8i-a23" - "allwinner,sun9i-a80-smp" - "amlogic,meson8-smp" - "amlogic,meson8b-smp" - "arm,realview-smp" - "brcm,bcm11351-cpu-method" - "brcm,bcm23550" - "brcm,bcm2836-smp" - "brcm,bcm-nsp-smp" - "brcm,brahma-b15" - "marvell,armada-375-smp" - "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" - "qcom,kpss-acc-v1" - "qcom,kpss-acc-v2" - "renesas,apmu" - "renesas,r9a06g032-smp" - "rockchip,rk3036-smp" - "rockchip,rk3066-smp" - "ste,dbx500-smp" - - - cpu-release-addr - Usage: required for systems that have an "enable-method" - property value of "spin-table". - Value type: <prop-encoded-array> - Definition: - # On ARM v8 64-bit systems must be a two cell - property identifying a 64-bit zero-initialised - memory location. - - - qcom,saw - Usage: required for systems that have an "enable-method" - property value of "qcom,kpss-acc-v1" or - "qcom,kpss-acc-v2" - Value type: <phandle> - Definition: Specifies the SAW[1] node associated with this CPU. - - - qcom,acc - Usage: required for systems that have an "enable-method" - property value of "qcom,kpss-acc-v1" or - "qcom,kpss-acc-v2" - Value type: <phandle> - Definition: Specifies the ACC[2] node associated with this CPU. - - - cpu-idle-states - Usage: Optional - Value type: <prop-encoded-array> - Definition: - # List of phandles to idle state nodes supported - by this cpu [3]. - - - capacity-dmips-mhz - Usage: Optional - Value type: <u32> - Definition: - # u32 value representing CPU capacity [4] in - DMIPS/MHz, relative to highest capacity-dmips-mhz - in the system. - - - rockchip,pmu - Usage: optional for systems that have an "enable-method" - property value of "rockchip,rk3066-smp" - While optional, it is the preferred way to get access to - the cpu-core power-domains. - Value type: <phandle> - Definition: Specifies the syscon node controlling the cpu core - power domains. - - - dynamic-power-coefficient - Usage: optional - Value type: <prop-encoded-array> - Definition: A u32 value that represents the running time dynamic - power coefficient in units of mW/MHz/uV^2. The - coefficient can either be calculated from power - measurements or derived by analysis. - - The dynamic power consumption of the CPU is - proportional to the square of the Voltage (V) and - the clock frequency (f). The coefficient is used to - calculate the dynamic power as below - - - Pdyn = dynamic-power-coefficient * V^2 * f - - where voltage is in uV, frequency is in MHz. - -Example 1 (dual-cluster big.LITTLE system 32-bit): - - cpus { - #size-cells = <0>; - #address-cells = <1>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x0>; - }; - - cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a15"; - reg = <0x1>; - }; - - cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x100>; - }; - - cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a7"; - reg = <0x101>; - }; - }; - -Example 2 (Cortex-A8 uniprocessor 32-bit system): - - cpus { - #size-cells = <0>; - #address-cells = <1>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a8"; - reg = <0x0>; - }; - }; - -Example 3 (ARM 926EJ-S uniprocessor 32-bit system): - - cpus { - #size-cells = <0>; - #address-cells = <1>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,arm926ej-s"; - reg = <0x0>; - }; - }; - -Example 4 (ARM Cortex-A57 64-bit system): - -cpus { - #size-cells = <0>; - #address-cells = <2>; - - cpu@0 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x0>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@1 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x1>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x100>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x101>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@10000 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10000>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@10001 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10001>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@10100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10100>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@10101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x0 0x10101>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100000000 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x0>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100000001 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x1>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100000100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x100>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100000101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x101>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100010000 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x10000>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100010001 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x10001>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100010100 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x10100>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; - - cpu@100010101 { - device_type = "cpu"; - compatible = "arm,cortex-a57"; - reg = <0x1 0x10101>; - enable-method = "spin-table"; - cpu-release-addr = <0 0x20000000>; - }; -}; - --- -[1] arm/msm/qcom,saw2.txt -[2] arm/msm/qcom,kpss-acc.txt -[3] ARM Linux kernel documentation - idle states bindings - Documentation/devicetree/bindings/arm/idle-states.txt -[4] ARM Linux kernel documentation - cpu capacity bindings - Documentation/devicetree/bindings/arm/cpu-capacity.txt diff --git a/Documentation/devicetree/bindings/arm/cpus.yaml b/Documentation/devicetree/bindings/arm/cpus.yaml new file mode 100644 index 000000000000..365dcf384d73 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/cpus.yaml @@ -0,0 +1,508 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/cpus.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM CPUs bindings + +maintainers: + - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com> + +description: |+ + The device tree allows to describe the layout of CPUs in a system through + the "cpus" node, which in turn contains a number of subnodes (ie "cpu") + defining properties for every cpu. + + Bindings for CPU nodes follow the Devicetree Specification, available from: + + https://www.devicetree.org/specifications/ + + with updates for 32-bit and 64-bit ARM systems provided in this document. + + ================================ + Convention used in this document + ================================ + + This document follows the conventions described in the Devicetree + Specification, with the addition: + + - square brackets define bitfields, eg reg[7:0] value of the bitfield in + the reg property contained in bits 7 down to 0 + + ===================================== + cpus and cpu node bindings definition + ===================================== + + The ARM architecture, in accordance with the Devicetree Specification, + requires the cpus and cpu nodes to be present and contain the properties + described below. + +properties: + $nodename: + const: cpus + description: Container of cpu nodes + + '#address-cells': + enum: [1, 2] + description: | + Definition depends on ARM architecture version and configuration: + + On uniprocessor ARM architectures previous to v7 + value must be 1, to enable a simple enumeration + scheme for processors that do not have a HW CPU + identification register. + On 32-bit ARM 11 MPcore, ARM v7 or later systems + value must be 1, that corresponds to CPUID/MPIDR + registers sizes. + On ARM v8 64-bit systems value should be set to 2, + that corresponds to the MPIDR_EL1 register size. + If MPIDR_EL1[63:32] value is equal to 0 on all CPUs + in the system, #address-cells can be set to 1, since + MPIDR_EL1[63:32] bits are not used for CPUs + identification. + + '#size-cells': + const: 0 + +patternProperties: + '^cpu@[0-9a-f]+$': + properties: + device_type: + const: cpu + + reg: + maxItems: 1 + description: | + Usage and definition depend on ARM architecture version and + configuration: + + On uniprocessor ARM architectures previous to v7 + this property is required and must be set to 0. + + On ARM 11 MPcore based systems this property is + required and matches the CPUID[11:0] register bits. + + Bits [11:0] in the reg cell must be set to + bits [11:0] in CPU ID register. + + All other bits in the reg cell must be set to 0. + + On 32-bit ARM v7 or later systems this property is + required and matches the CPU MPIDR[23:0] register + bits. + + Bits [23:0] in the reg cell must be set to + bits [23:0] in MPIDR. + + All other bits in the reg cell must be set to 0. + + On ARM v8 64-bit systems this property is required + and matches the MPIDR_EL1 register affinity bits. + + * If cpus node's #address-cells property is set to 2 + + The first reg cell bits [7:0] must be set to + bits [39:32] of MPIDR_EL1. + + The second reg cell bits [23:0] must be set to + bits [23:0] of MPIDR_EL1. + + * If cpus node's #address-cells property is set to 1 + + The reg cell bits [23:0] must be set to bits [23:0] + of MPIDR_EL1. + + All other bits in the reg cells must be set to 0. + + compatible: + items: + - enum: + - arm,arm710t + - arm,arm720t + - arm,arm740t + - arm,arm7ej-s + - arm,arm7tdmi + - arm,arm7tdmi-s + - arm,arm9es + - arm,arm9ej-s + - arm,arm920t + - arm,arm922t + - arm,arm925 + - arm,arm926e-s + - arm,arm926ej-s + - arm,arm940t + - arm,arm946e-s + - arm,arm966e-s + - arm,arm968e-s + - arm,arm9tdmi + - arm,arm1020e + - arm,arm1020t + - arm,arm1022e + - arm,arm1026ej-s + - arm,arm1136j-s + - arm,arm1136jf-s + - arm,arm1156t2-s + - arm,arm1156t2f-s + - arm,arm1176jzf + - arm,arm1176jz-s + - arm,arm1176jzf-s + - arm,arm11mpcore + - arm,armv8 # Only for s/w models + - arm,cortex-a5 + - arm,cortex-a7 + - arm,cortex-a8 + - arm,cortex-a9 + - arm,cortex-a12 + - arm,cortex-a15 + - arm,cortex-a17 + - arm,cortex-a53 + - arm,cortex-a57 + - arm,cortex-a72 + - arm,cortex-a73 + - arm,cortex-m0 + - arm,cortex-m0+ + - arm,cortex-m1 + - arm,cortex-m3 + - arm,cortex-m4 + - arm,cortex-r4 + - arm,cortex-r5 + - arm,cortex-r7 + - brcm,brahma-b15 + - brcm,brahma-b53 + - brcm,vulcan + - cavium,thunder + - cavium,thunder2 + - faraday,fa526 + - intel,sa110 + - intel,sa1100 + - marvell,feroceon + - marvell,mohawk + - marvell,pj4a + - marvell,pj4b + - marvell,sheeva-v5 + - marvell,sheeva-v7 + - nvidia,tegra132-denver + - nvidia,tegra186-denver + - nvidia,tegra194-carmel + - qcom,krait + - qcom,kryo + - qcom,kryo385 + - qcom,scorpion + + enable-method: + allOf: + - $ref: '/schemas/types.yaml#/definitions/string' + - oneOf: + # On ARM v8 64-bit this property is required + - enum: + - psci + - spin-table + # On ARM 32-bit systems this property is optional + - enum: + - actions,s500-smp + - allwinner,sun6i-a31 + - allwinner,sun8i-a23 + - allwinner,sun9i-a80-smp + - allwinner,sun8i-a83t-smp + - amlogic,meson8-smp + - amlogic,meson8b-smp + - arm,realview-smp + - brcm,bcm11351-cpu-method + - brcm,bcm23550 + - brcm,bcm2836-smp + - brcm,bcm63138 + - brcm,bcm-nsp-smp + - brcm,brahma-b15 + - marvell,armada-375-smp + - 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 + - qcom,kpss-acc-v1 + - qcom,kpss-acc-v2 + - renesas,apmu + - renesas,r9a06g032-smp + - rockchip,rk3036-smp + - rockchip,rk3066-smp + - socionext,milbeaut-m10v-smp + - ste,dbx500-smp + + cpu-release-addr: + $ref: '/schemas/types.yaml#/definitions/uint64' + + description: + Required for systems that have an "enable-method" + property value of "spin-table". + On ARM v8 64-bit systems must be a two cell + property identifying a 64-bit zero-initialised + memory location. + + cpu-idle-states: + $ref: '/schemas/types.yaml#/definitions/phandle-array' + description: | + List of phandles to idle state nodes supported + by this cpu (see ./idle-states.txt). + + capacity-dmips-mhz: + $ref: '/schemas/types.yaml#/definitions/uint32' + description: + u32 value representing CPU capacity (see ./cpu-capacity.txt) in + DMIPS/MHz, relative to highest capacity-dmips-mhz + in the system. + + dynamic-power-coefficient: + $ref: '/schemas/types.yaml#/definitions/uint32' + description: + A u32 value that represents the running time dynamic + power coefficient in units of uW/MHz/V^2. The + coefficient can either be calculated from power + measurements or derived by analysis. + + The dynamic power consumption of the CPU is + proportional to the square of the Voltage (V) and + the clock frequency (f). The coefficient is used to + calculate the dynamic power as below - + + Pdyn = dynamic-power-coefficient * V^2 * f + + where voltage is in V, frequency is in MHz. + + qcom,saw: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Specifies the SAW* node associated with this CPU. + + Required for systems that have an "enable-method" property + value of "qcom,kpss-acc-v1" or "qcom,kpss-acc-v2" + + * arm/msm/qcom,saw2.txt + + qcom,acc: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Specifies the ACC* node associated with this CPU. + + Required for systems that have an "enable-method" property + value of "qcom,kpss-acc-v1" or "qcom,kpss-acc-v2" + + * arm/msm/qcom,kpss-acc.txt + + rockchip,pmu: + $ref: '/schemas/types.yaml#/definitions/phandle' + description: | + Specifies the syscon node controlling the cpu core power domains. + + Optional for systems that have an "enable-method" + property value of "rockchip,rk3066-smp" + While optional, it is the preferred way to get access to + the cpu-core power-domains. + + required: + - device_type + - reg + - compatible + + dependencies: + cpu-release-addr: [enable-method] + rockchip,pmu: [enable-method] + +required: + - '#address-cells' + - '#size-cells' + +examples: + - | + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x0>; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a15"; + reg = <0x1>; + }; + + cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x100>; + }; + + cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a7"; + reg = <0x101>; + }; + }; + + - | + // Example 2 (Cortex-A8 uniprocessor 32-bit system): + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a8"; + reg = <0x0>; + }; + }; + + - | + // Example 3 (ARM 926EJ-S uniprocessor 32-bit system): + cpus { + #size-cells = <0>; + #address-cells = <1>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,arm926ej-s"; + reg = <0x0>; + }; + }; + + - | + // Example 4 (ARM Cortex-A57 64-bit system): + cpus { + #size-cells = <0>; + #address-cells = <2>; + + cpu@0 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x0>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@1 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x1>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x100>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x101>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@10000 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10000>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@10001 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10001>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@10100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10100>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@10101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x0 0x10101>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100000000 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x0>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100000001 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x1>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100000100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x100>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100000101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x101>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100010000 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x10000>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100010001 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x10001>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100010100 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x10100>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + + cpu@100010101 { + device_type = "cpu"; + compatible = "arm,cortex-a57"; + reg = <0x1 0x10101>; + enable-method = "spin-table"; + cpu-release-addr = <0 0x20000000>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/arm/davinci.txt b/Documentation/devicetree/bindings/arm/davinci.txt deleted file mode 100644 index 715622c36260..000000000000 --- a/Documentation/devicetree/bindings/arm/davinci.txt +++ /dev/null @@ -1,25 +0,0 @@ -Texas Instruments DaVinci Platforms Device Tree Bindings --------------------------------------------------------- - -DA850/OMAP-L138/AM18x Evaluation Module (EVM) board -Required root node properties: - - compatible = "ti,da850-evm", "ti,da850"; - -DA850/OMAP-L138/AM18x L138/C6748 Development Kit (LCDK) board -Required root node properties: - - compatible = "ti,da850-lcdk", "ti,da850"; - -EnBW AM1808 based CMC board -Required root node properties: - - compatible = "enbw,cmc", "ti,da850; - -LEGO MINDSTORMS EV3 (AM1808 based) -Required root node properties: - - compatible = "lego,ev3", "ti,da850"; - -Generic DaVinci Boards ----------------------- - -DA850/OMAP-L138/AM18x generic board -Required root node properties: - - compatible = "ti,da850"; diff --git a/Documentation/devicetree/bindings/arm/emtrion.txt b/Documentation/devicetree/bindings/arm/emtrion.txt new file mode 100644 index 000000000000..83329aefc483 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/emtrion.txt @@ -0,0 +1,12 @@ +Emtrion Devicetree Bindings +=========================== + +emCON Series: +------------- + +Required root node properties + - compatible: + - "emtrion,emcon-mx6", "fsl,imx6q"; : emCON-MX6D or emCON-MX6Q SoM + - "emtrion,emcon-mx6-avari", "fsl,imx6q"; : emCON-MX6D or emCON-MX6Q SoM on Avari Base + - "emtrion,emcon-mx6", "fsl,imx6dl"; : emCON-MX6S or emCON-MX6DL SoM + - "emtrion,emcon-mx6-avari", "fsl,imx6dl"; : emCON-MX6S or emCON-MX6DL SoM on Avari Base diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-pm.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-pm.txt new file mode 100644 index 000000000000..75195bee116f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-pm.txt @@ -0,0 +1,23 @@ +Freescale i.MX7ULP Power Management Components +---------------------------------------------- + +The Multi-System Mode Controller (MSMC) is responsible for sequencing +the MCU into and out of all stop and run power modes. Specifically, it +monitors events to trigger transitions between power modes while +controlling the power, clocks, and memories of the MCU to achieve the +power consumption and functionality of that mode. + +The WFI or WFE instruction is used to invoke a Sleep, Deep Sleep or +Standby modes for either Cortex family. Run, Wait, and Stop are the +common terms used for the primary operating modes of Kinetis +microcontrollers. + +Required properties: +- compatible: Should be "fsl,imx7ulp-smc1". +- reg: Specifies base physical address and size of the register sets. + +Example: +smc1: smc1@40410000 { + compatible = "fsl,imx7ulp-smc1"; + reg = <0x40410000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-sim.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-sim.txt new file mode 100644 index 000000000000..7d0c7f002401 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,imx7ulp-sim.txt @@ -0,0 +1,16 @@ +Freescale i.MX7ULP System Integration Module +---------------------------------------------- +The system integration module (SIM) provides system control and chip configuration +registers. In this module, chip revision information is located in JTAG ID register, +and a set of registers have been made available in DGO domain for SW use, with the +objective to maintain its value between system resets. + +Required properties: +- compatible: Should be "fsl,imx7ulp-sim". +- reg: Specifies base physical address and size of the register sets. + +Example: +sim: sim@410a3000 { + compatible = "fsl,imx7ulp-sim", "syscon"; + reg = <0x410a3000 0x1000>; +}; diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt new file mode 100644 index 000000000000..b5cb374dc47d --- /dev/null +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-dcfg.txt @@ -0,0 +1,19 @@ +Freescale DCFG + +DCFG is the device configuration unit, that provides general purpose +configuration and status for the device. Such as setting the secondary +core start address and release the secondary core from holdoff and startup. + +Required properties: + - 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: + ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. + + - reg : should contain base address and length of DCFG memory-mapped registers + +Example: + dcfg: dcfg@1ee0000 { + compatible = "fsl,ls1021a-dcfg"; + reg = <0x0 0x1ee0000 0x0 0x10000>; + }; diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-scfg.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-scfg.txt new file mode 100644 index 000000000000..0ab67b0b216d --- /dev/null +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,layerscape-scfg.txt @@ -0,0 +1,19 @@ +Freescale SCFG + +SCFG is the supplemental configuration unit, that provides SoC specific +configuration and status registers for the chip. Such as getting PEX port +status. + +Required properties: + - 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: + ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. + + - reg: should contain base address and length of SCFG memory-mapped registers + +Example: + scfg: scfg@1570000 { + compatible = "fsl,ls1021a-scfg"; + reg = <0x0 0x1570000 0x0 0x10000>; + }; diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt new file mode 100644 index 000000000000..72d481c8dd48 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt @@ -0,0 +1,182 @@ +NXP i.MX System Controller Firmware (SCFW) +-------------------------------------------------------------------- + +The System Controller Firmware (SCFW) is a low-level system function +which runs on a dedicated Cortex-M core to provide power, clock, and +resource management. It exists on some i.MX8 processors. e.g. i.MX8QM +(QM, QP), and i.MX8QX (QXP, DX). + +The AP communicates with the SC using a multi-ported MU module found +in the LSIO subsystem. The current definition of this MU module provides +5 remote AP connections to the SC to support up to 5 execution environments +(TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces +with the LSIO DSC IP bus. The SC firmware will communicate with this MU +using the MSI bus. + +System Controller Device Node: +============================================================ + +The scu node with the following properties shall be under the /firmware/ node. + +Required properties: +------------------- +- compatible: should be "fsl,imx-scu". +- mbox-names: should include "tx0", "tx1", "tx2", "tx3", + "rx0", "rx1", "rx2", "rx3". +- mboxes: List of phandle of 4 MU channels for tx and 4 MU channels + for rx. All 8 MU channels must be in the same MU instance. + Cross instances are not allowed. The MU instance can only + be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users need + to make sure use the one which is not conflict with other + execution environments. e.g. ATF. + Note: + Channel 0 must be "tx0" or "rx0". + Channel 1 must be "tx1" or "rx1". + Channel 2 must be "tx2" or "rx2". + Channel 3 must be "tx3" or "rx3". + e.g. + mboxes = <&lsio_mu1 0 0 + &lsio_mu1 0 1 + &lsio_mu1 0 2 + &lsio_mu1 0 3 + &lsio_mu1 1 0 + &lsio_mu1 1 1 + &lsio_mu1 1 2 + &lsio_mu1 1 3>; + See Documentation/devicetree/bindings/mailbox/fsl,mu.txt + for detailed mailbox binding. + +i.MX SCU Client Device Node: +============================================================ + +Client nodes are maintained as children of the relevant IMX-SCU device node. + +Power domain bindings based on SCU Message Protocol +------------------------------------------------------------ + +This binding for the SCU power domain providers uses the generic power +domain binding[2]. + +Required properties: +- compatible: Should be one of: + "fsl,imx8qm-scu-pd", + "fsl,imx8qxp-scu-pd" + followed by "fsl,scu-pd" + +- #power-domain-cells: Must be 1. Contains the Resource ID used by + SCU commands. + See detailed Resource ID list from: + include/dt-bindings/firmware/imx/rsrc.h + +Clock bindings based on SCU Message Protocol +------------------------------------------------------------ + +This binding uses the common clock binding[1]. + +Required properties: +- compatible: Should be one of: + "fsl,imx8qm-clock" + "fsl,imx8qxp-clock" + followed by "fsl,scu-clk" +- #clock-cells: Should be 1. Contains the Clock ID value. +- clocks: List of clock specifiers, must contain an entry for + each required entry in clock-names +- clock-names: Should include entries "xtal_32KHz", "xtal_24MHz" + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. + +See the full list of clock IDs from: +include/dt-bindings/clock/imx8qxp-clock.h + +Pinctrl bindings based on SCU Message Protocol +------------------------------------------------------------ + +This binding uses the i.MX common pinctrl binding[3]. + +Required properties: +- compatible: Should be one of: + "fsl,imx8qm-iomuxc", + "fsl,imx8qxp-iomuxc". + +Required properties for Pinctrl sub nodes: +- fsl,pins: Each entry consists of 3 integers which represents + the mux and config setting for one pin. The first 2 + integers <pin_id mux_mode> are specified using a + PIN_FUNC_ID macro, which can be found in + <dt-bindings/pinctrl/pads-imx8qm.h>, + <dt-bindings/pinctrl/pads-imx8qxp.h>. + The last integer CONFIG is the pad setting value like + pull-up on this pin. + + Please refer to i.MX8QXP Reference Manual for detailed + CONFIG settings. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt +[2] Documentation/devicetree/bindings/power/power_domain.txt +[3] Documentation/devicetree/bindings/pinctrl/fsl,imx-pinctrl.txt + +RTC bindings based on SCU Message Protocol +------------------------------------------------------------ + +Required properties: +- compatible: should be "fsl,imx8qxp-sc-rtc"; + +Example (imx8qxp): +------------- +lsio_mu1: mailbox@5d1c0000 { + ... + #mbox-cells = <2>; +}; + +firmware { + scu { + compatible = "fsl,imx-scu"; + mbox-names = "tx0", "tx1", "tx2", "tx3", + "rx0", "rx1", "rx2", "rx3"; + mboxes = <&lsio_mu1 0 0 + &lsio_mu1 0 1 + &lsio_mu1 0 2 + &lsio_mu1 0 3 + &lsio_mu1 1 0 + &lsio_mu1 1 1 + &lsio_mu1 1 2 + &lsio_mu1 1 3>; + + clk: clk { + compatible = "fsl,imx8qxp-clk", "fsl,scu-clk"; + #clock-cells = <1>; + }; + + iomuxc { + compatible = "fsl,imx8qxp-iomuxc"; + + pinctrl_lpuart0: lpuart0grp { + fsl,pins = < + SC_P_UART0_RX_ADMA_UART0_RX 0x06000020 + SC_P_UART0_TX_ADMA_UART0_TX 0x06000020 + >; + }; + ... + }; + + pd: imx8qx-pd { + compatible = "fsl,imx8qxp-scu-pd", "fsl,scu-pd"; + #power-domain-cells = <1>; + }; + + rtc: rtc { + compatible = "fsl,imx8qxp-sc-rtc"; + }; + }; +}; + +serial@5a060000 { + ... + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lpuart0>; + clocks = <&clk IMX8QXP_UART0_CLK>, + <&clk IMX8QXP_UART0_IPG_CLK>; + clock-names = "per", "ipg"; + power-domains = <&pd IMX_SC_R_UART_0>; +}; diff --git a/Documentation/devicetree/bindings/arm/fsl.txt b/Documentation/devicetree/bindings/arm/fsl.txt deleted file mode 100644 index 8a1baa2b9723..000000000000 --- a/Documentation/devicetree/bindings/arm/fsl.txt +++ /dev/null @@ -1,224 +0,0 @@ -Freescale i.MX Platforms Device Tree Bindings ------------------------------------------------ - -i.MX23 Evaluation Kit -Required root node properties: - - compatible = "fsl,imx23-evk", "fsl,imx23"; - -i.MX25 Product Development Kit -Required root node properties: - - compatible = "fsl,imx25-pdk", "fsl,imx25"; - -i.MX27 Product Development Kit -Required root node properties: - - compatible = "fsl,imx27-pdk", "fsl,imx27"; - -i.MX28 Evaluation Kit -Required root node properties: - - compatible = "fsl,imx28-evk", "fsl,imx28"; - -i.MX51 Babbage Board -Required root node properties: - - compatible = "fsl,imx51-babbage", "fsl,imx51"; - -i.MX53 Automotive Reference Design Board -Required root node properties: - - compatible = "fsl,imx53-ard", "fsl,imx53"; - -i.MX53 Evaluation Kit -Required root node properties: - - compatible = "fsl,imx53-evk", "fsl,imx53"; - -i.MX53 Quick Start Board -Required root node properties: - - compatible = "fsl,imx53-qsb", "fsl,imx53"; - -i.MX53 Smart Mobile Reference Design Board -Required root node properties: - - compatible = "fsl,imx53-smd", "fsl,imx53"; - -i.MX6 Quad Armadillo2 Board -Required root node properties: - - compatible = "fsl,imx6q-arm2", "fsl,imx6q"; - -i.MX6 Quad SABRE Lite Board -Required root node properties: - - compatible = "fsl,imx6q-sabrelite", "fsl,imx6q"; - -i.MX6 Quad SABRE Smart Device Board -Required root node properties: - - compatible = "fsl,imx6q-sabresd", "fsl,imx6q"; - -i.MX6 Quad SABRE Automotive Board -Required root node properties: - - compatible = "fsl,imx6q-sabreauto", "fsl,imx6q"; - -i.MX6SLL EVK board -Required root node properties: - - compatible = "fsl,imx6sll-evk", "fsl,imx6sll"; - -Generic i.MX boards -------------------- - -No iomux setup is done for these boards, so this must have been configured -by the bootloader for boards to work with the generic bindings. - -i.MX27 generic board -Required root node properties: - - compatible = "fsl,imx27"; - -i.MX51 generic board -Required root node properties: - - compatible = "fsl,imx51"; - -i.MX53 generic board -Required root node properties: - - compatible = "fsl,imx53"; - -i.MX6q generic board -Required root node properties: - - compatible = "fsl,imx6q"; - -Freescale Vybrid Platform Device Tree Bindings ----------------------------------------------- - -For the Vybrid SoC familiy all variants with DDR controller are supported, -which is the VF5xx and VF6xx series. Out of historical reasons, in most -places the kernel uses vf610 to refer to the whole familiy. -The compatible string "fsl,vf610m4" is used for the secondary Cortex-M4 -core support. - -Required root node compatible property (one of them): - - compatible = "fsl,vf500"; - - compatible = "fsl,vf510"; - - compatible = "fsl,vf600"; - - compatible = "fsl,vf610"; - - compatible = "fsl,vf610m4"; - -Freescale LS1021A Platform Device Tree Bindings ------------------------------------------------- - -Required root node compatible properties: - - compatible = "fsl,ls1021a"; - -Freescale SoC-specific Device Tree Bindings -------------------------------------------- - -Freescale SCFG - SCFG is the supplemental configuration unit, that provides SoC specific -configuration and status registers for the chip. Such as getting PEX port -status. - Required properties: - - 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: - ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. - - - reg: should contain base address and length of SCFG memory-mapped registers - -Example: - scfg: scfg@1570000 { - compatible = "fsl,ls1021a-scfg"; - reg = <0x0 0x1570000 0x0 0x10000>; - }; - -Freescale DCFG - DCFG is the device configuration unit, that provides general purpose -configuration and status for the device. Such as setting the secondary -core start address and release the secondary core from holdoff and startup. - Required properties: - - 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: - ls1012a, ls1021a, ls1043a, ls1046a, ls2080a. - - - reg : should contain base address and length of DCFG memory-mapped registers - -Example: - dcfg: dcfg@1ee0000 { - compatible = "fsl,ls1021a-dcfg"; - reg = <0x0 0x1ee0000 0x0 0x10000>; - }; - -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"; - -LS1043A ARMv8 based RDB Board -Required root node properties: - - compatible = "fsl,ls1043a-rdb", "fsl,ls1043a"; - -LS1043A ARMv8 based QDS Board -Required root node properties: - - compatible = "fsl,ls1043a-qds", "fsl,ls1043a"; - -LS1046A SoC -Required root node properties: - - compatible = "fsl,ls1046a"; - -LS1046A ARMv8 based QDS Board -Required root node properties: - - compatible = "fsl,ls1046a-qds", "fsl,ls1046a"; - -LS1046A ARMv8 based RDB Board -Required root node properties: - - compatible = "fsl,ls1046a-rdb", "fsl,ls1046a"; - -LS1088A SoC -Required root node properties: - - compatible = "fsl,ls1088a"; - -LS1088A ARMv8 based QDS Board -Required root node properties: - - compatible = "fsl,ls1088a-qds", "fsl,ls1088a"; - -LS1088A ARMv8 based RDB Board -Required root node properties: - - compatible = "fsl,ls1088a-rdb", "fsl,ls1088a"; - -LS2080A SoC -Required root node properties: - - compatible = "fsl,ls2080a"; - -LS2080A ARMv8 based Simulator model -Required root node properties: - - compatible = "fsl,ls2080a-simu", "fsl,ls2080a"; - -LS2080A ARMv8 based QDS Board -Required root node properties: - - compatible = "fsl,ls2080a-qds", "fsl,ls2080a"; - -LS2080A ARMv8 based RDB Board -Required root node properties: - - compatible = "fsl,ls2080a-rdb", "fsl,ls2080a"; - -LS2088A SoC -Required root node properties: - - compatible = "fsl,ls2088a"; - -LS2088A ARMv8 based QDS Board -Required root node properties: - - compatible = "fsl,ls2088a-qds", "fsl,ls2088a"; - -LS2088A ARMv8 based RDB Board -Required root node properties: - - compatible = "fsl,ls2088a-rdb", "fsl,ls2088a"; diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml new file mode 100644 index 000000000000..7e2cd6ad26bd --- /dev/null +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -0,0 +1,232 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/arm/fsl.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX Platforms Device Tree Bindings + +maintainers: + - Shawn Guo <shawnguo@kernel.org> + - Li Yang <leoyang.li@nxp.com> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: i.MX23 based Boards + items: + - enum: + - fsl,imx23-evk + - olimex,imx23-olinuxino + - const: fsl,imx23 + + - description: i.MX25 Product Development Kit + items: + - enum: + - fsl,imx25-pdk + - const: fsl,imx25 + + - description: i.MX27 Product Development Kit + items: + - enum: + - fsl,imx27-pdk + - const: fsl,imx27 + + - description: i.MX28 based Boards + items: + - enum: + - fsl,imx28-evk + - i2se,duckbill + - i2se,duckbill-2 + - technologic,imx28-ts4600 + - const: fsl,imx28 + - description: i.MX28 Duckbill 2 based Boards + items: + - enum: + - i2se,duckbill-2-485 + - i2se,duckbill-2-enocean + - i2se,duckbill-2-spi + - const: i2se,duckbill-2 + - const: fsl,imx28 + + - description: i.MX51 Babbage Board + items: + - enum: + - armadeus,imx51-apf51 + - fsl,imx51-babbage + - technologic,imx51-ts4800 + - const: fsl,imx51 + + - description: i.MX53 based Boards + items: + - enum: + - bhf,cx9020 + - fsl,imx53-ard + - fsl,imx53-evk + - fsl,imx53-qsb + - fsl,imx53-smd + - const: fsl,imx53 + + - description: i.MX6Q based Boards + items: + - enum: + - fsl,imx6q-arm2 + - fsl,imx6q-sabreauto + - fsl,imx6q-sabrelite + - fsl,imx6q-sabresd + - technologic,imx6q-ts4900 + - technologic,imx6q-ts7970 + - const: fsl,imx6q + + - description: i.MX6QP based Boards + items: + - enum: + - fsl,imx6qp-sabreauto # i.MX6 Quad Plus SABRE Automotive Board + - fsl,imx6qp-sabresd # i.MX6 Quad Plus SABRE Smart Device Board + - const: fsl,imx6qp + + - description: i.MX6DL based Boards + items: + - enum: + - fsl,imx6dl-sabreauto # i.MX6 DualLite/Solo SABRE Automotive Board + - fsl,imx6dl-sabresd # i.MX6 DualLite SABRE Smart Device Board + - technologic,imx6dl-ts4900 + - technologic,imx6dl-ts7970 + - ysoft,imx6dl-yapp4-draco # i.MX6 DualLite Y Soft IOTA Draco board + - ysoft,imx6dl-yapp4-hydra # i.MX6 DualLite Y Soft IOTA Hydra board + - ysoft,imx6dl-yapp4-ursa # i.MX6 Solo Y Soft IOTA Ursa board + - const: fsl,imx6dl + + - description: i.MX6SL based Boards + items: + - enum: + - fsl,imx6sl-evk # i.MX6 SoloLite EVK Board + - const: fsl,imx6sl + + - description: i.MX6SLL based Boards + items: + - enum: + - fsl,imx6sll-evk + - const: fsl,imx6sll + + - description: i.MX6SX based Boards + items: + - enum: + - fsl,imx6sx-sabreauto # i.MX6 SoloX Sabre Auto Board + - fsl,imx6sx-sdb # i.MX6 SoloX SDB Board + - const: fsl,imx6sx + + - description: i.MX6UL based Boards + items: + - enum: + - fsl,imx6ul-14x14-evk # i.MX6 UltraLite 14x14 EVK Board + - const: fsl,imx6ul + + - description: i.MX6ULL based Boards + items: + - enum: + - fsl,imx6ull-14x14-evk # i.MX6 UltraLiteLite 14x14 EVK Board + - const: fsl,imx6ull + + - description: i.MX6ULZ based Boards + items: + - enum: + - fsl,imx6ulz-14x14-evk # i.MX6 ULZ 14x14 EVK Board + - const: fsl,imx6ull # This seems odd. Should be last? + - const: fsl,imx6ulz + + - description: i.MX7D based Boards + items: + - enum: + - fsl,imx7d-sdb # i.MX7 SabreSD Board + - const: fsl,imx7d + + - description: + Compulab SBC-iMX7 is a single board computer based on the + Freescale i.MX7 system-on-chip. SBC-iMX7 is implemented with + the CL-SOM-iMX7 System-on-Module providing most of the functions, + and SB-SOM-iMX7 carrier board providing additional peripheral + functions and connectors. + items: + - const: compulab,sbc-imx7 + - const: compulab,cl-som-imx7 + - const: fsl,imx7d + + - description: i.MX8QXP based Boards + items: + - enum: + - fsl,imx8qxp-mek # i.MX8QXP MEK Board + - const: fsl,imx8qxp + + - description: + Freescale Vybrid Platform Device Tree Bindings + + For the Vybrid SoC familiy all variants with DDR controller are supported, + which is the VF5xx and VF6xx series. Out of historical reasons, in most + places the kernel uses vf610 to refer to the whole familiy. + The compatible string "fsl,vf610m4" is used for the secondary Cortex-M4 + core support. + items: + - enum: + - fsl,vf500 + - fsl,vf510 + - fsl,vf600 + - fsl,vf610 + - fsl,vf610m4 + + - description: LS1012A based Boards + items: + - enum: + - ebs-systart,oxalis + - fsl,ls1012a-rdb + - fsl,ls1012a-frdm + - fsl,ls1012a-qds + - const: fsl,ls1012a + + - description: LS1021A based Boards + items: + - enum: + - fsl,ls1021a-moxa-uc-8410a + - fsl,ls1021a-qds + - fsl,ls1021a-twr + - const: fsl,ls1021a + + - description: LS1043A based Boards + items: + - enum: + - fsl,ls1043a-rdb + - fsl,ls1043a-qds + - const: fsl,ls1043a + + - description: LS1046A based Boards + items: + - enum: + - fsl,ls1046a-qds + - fsl,ls1046a-rdb + - const: fsl,ls1046a + + - description: LS1088A based Boards + items: + - enum: + - fsl,ls1088a-qds + - fsl,ls1088a-rdb + - const: fsl,ls1088a + + - description: LS2080A based Boards + items: + - enum: + - fsl,ls2080a-simu + - fsl,ls2080a-qds + - fsl,ls2080a-rdb + - const: fsl,ls2080a + + - description: LS2088A based Boards + items: + - enum: + - fsl,ls2088a-qds + - fsl,ls2088a-rdb + - const: fsl,ls2088a + +... diff --git a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt index 199cd36fe1ba..a97f643e7d1c 100644 --- a/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt +++ b/Documentation/devicetree/bindings/arm/hisilicon/hisilicon.txt @@ -8,6 +8,14 @@ HiKey960 Board Required root node properties: - compatible = "hisilicon,hi3660-hikey960", "hisilicon,hi3660"; +Hi3670 SoC +Required root node properties: + - compatible = "hisilicon,hi3670"; + +HiKey970 Board +Required root node properties: + - compatible = "hisilicon,hi3670-hikey970", "hisilicon,hi3670"; + Hi3798cv200 SoC Required root node properties: - compatible = "hisilicon,hi3798cv200"; diff --git a/Documentation/devicetree/bindings/arm/i2se.txt b/Documentation/devicetree/bindings/arm/i2se.txt deleted file mode 100644 index dbd54a3aa07d..000000000000 --- a/Documentation/devicetree/bindings/arm/i2se.txt +++ /dev/null @@ -1,22 +0,0 @@ -I2SE Device Tree Bindings -------------------------- - -Duckbill Board -Required root node properties: - - compatible = "i2se,duckbill", "fsl,imx28"; - -Duckbill 2 Board -Required root node properties: - - compatible = "i2se,duckbill-2", "fsl,imx28"; - -Duckbill 2 485 Board -Required root node properties: - - compatible = "i2se,duckbill-2-485", "i2se,duckbill-2", "fsl,imx28"; - -Duckbill 2 EnOcean Board -Required root node properties: - - compatible = "i2se,duckbill-2-enocean", "i2se,duckbill-2", "fsl,imx28"; - -Duckbill 2 SPI Board -Required root node properties: - - compatible = "i2se,duckbill-2-spi", "i2se,duckbill-2", "fsl,imx28"; diff --git a/Documentation/devicetree/bindings/arm/idle-states.txt b/Documentation/devicetree/bindings/arm/idle-states.txt index 2c73847499ab..45730ba60af5 100644 --- a/Documentation/devicetree/bindings/arm/idle-states.txt +++ b/Documentation/devicetree/bindings/arm/idle-states.txt @@ -142,7 +142,7 @@ characterised by the following graph: The graph is split in two parts delimited by time 1ms on the X-axis. The graph curve with X-axis values = { x | 0 < x < 1ms } has a steep slope -and denotes the energy costs incurred whilst entering and leaving the idle +and denotes the energy costs incurred while entering and leaving the idle state. The graph curve in the area delimited by X-axis values = {x | x > 1ms } has shallower slope and essentially represents the energy consumption of the idle @@ -684,7 +684,7 @@ cpus { =========================================== [1] ARM Linux Kernel documentation - CPUs bindings - Documentation/devicetree/bindings/arm/cpus.txt + Documentation/devicetree/bindings/arm/cpus.yaml [2] ARM Linux Kernel documentation - PSCI bindings Documentation/devicetree/bindings/arm/psci.txt diff --git a/Documentation/devicetree/bindings/arm/keystone/ti,sci.txt b/Documentation/devicetree/bindings/arm/keystone/ti,sci.txt index 31f5f9a104cc..b56a02c10ae6 100644 --- a/Documentation/devicetree/bindings/arm/keystone/ti,sci.txt +++ b/Documentation/devicetree/bindings/arm/keystone/ti,sci.txt @@ -45,11 +45,15 @@ Optional Properties: debug_messages - Map the Debug message region - reg: register space corresponding to the debug_messages - ti,system-reboot-controller: If system reboot can be triggered by SoC reboot +- ti,host-id: Integer value corresponding to the host ID assigned by Firmware + for identification of host processing entities such as virtual + machines Example (K2G): ------------- pmmc: pmmc { compatible = "ti,k2g-sci"; + ti,host-id = <2>; mbox-names = "rx", "tx"; mboxes= <&msgmgr &msgmgr_proxy_pmmc_rx>, <&msgmgr &msgmgr_proxy_pmmc_tx>; diff --git a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt index 3fd21bb7cb37..7b8b8eb0191f 100644 --- a/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt @@ -114,12 +114,17 @@ Documentation/devicetree/bindings/thermal/thermal.txt The thermal IP can probe the temperature all around the processor. It may feature several channels, each of them wired to one sensor. +It is possible to setup an overheat interrupt by giving at least one +critical point to any subnode of the thermal-zone node. + Required properties: - compatible: must be one of: * marvell,armada-ap806-thermal - reg: register range associated with the thermal functions. Optional properties: +- interrupts: overheat interrupt handle. Should point to line 18 of the + SEI irqchip. See interrupt-controller/interrupts.txt - #thermal-sensor-cells: shall be <1> when thermal-zones subnodes refer to this IP and represents the channel ID. There is one sensor per channel. O refers to the thermal IP internal channel, while positive @@ -133,6 +138,8 @@ ap_syscon1: system-controller@6f8000 { ap_thermal: thermal-sensor@80 { compatible = "marvell,armada-ap806-thermal"; reg = <0x80 0x10>; + interrupt-parent = <&sei>; + interrupts = <18>; #thermal-sensor-cells = <1>; }; }; diff --git a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt index 81ce742d2760..4db4119a6d19 100644 --- a/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt +++ b/Documentation/devicetree/bindings/arm/marvell/cp110-system-controller.txt @@ -199,6 +199,9 @@ Thermal: The thermal IP can probe the temperature all around the processor. It may feature several channels, each of them wired to one sensor. +It is possible to setup an overheat interrupt by giving at least one +critical point to any subnode of the thermal-zone node. + For common binding part and usage, refer to Documentation/devicetree/bindings/thermal/thermal.txt @@ -208,6 +211,11 @@ Required properties: - reg: register range associated with the thermal functions. Optional properties: +- interrupts-extended: overheat interrupt handle. Should point to + a line of the ICU-SEI irqchip (116 is what is usually used by the + firmware). The ICU-SEI will redirect towards interrupt line #37 of the + AP SEI which is shared across all CPs. + See interrupt-controller/interrupts.txt - #thermal-sensor-cells: shall be <1> when thermal-zones subnodes refer to this IP and represents the channel ID. There is one sensor per channel. O refers to the thermal IP internal channel. @@ -220,6 +228,7 @@ CP110_LABEL(syscon1): system-controller@6f8000 { CP110_LABEL(thermal): thermal-sensor@70 { compatible = "marvell,armada-cp110-thermal"; reg = <0x70 0x10>; + interrupts-extended = <&CP110_LABEL(icu_sei) 116 IRQ_TYPE_LEVEL_HIGH>; #thermal-sensor-cells = <1>; }; }; diff --git a/Documentation/devicetree/bindings/arm/mediatek.txt b/Documentation/devicetree/bindings/arm/mediatek.txt index 8f260e5cfd16..56ac7896d6d8 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.txt +++ b/Documentation/devicetree/bindings/arm/mediatek.txt @@ -15,11 +15,12 @@ compatible: Must contain one of "mediatek,mt6795" "mediatek,mt6797" "mediatek,mt7622" - "mediatek,mt7623" which is referred to MT7623N SoC - "mediatek,mt7623a" + "mediatek,mt7623" + "mediatek,mt7629" "mediatek,mt8127" "mediatek,mt8135" "mediatek,mt8173" + "mediatek,mt8183" Supported boards: @@ -57,6 +58,9 @@ Supported boards: - Reference board variant 1 for MT7622: Required root node properties: - compatible = "mediatek,mt7622-rfb1", "mediatek,mt7622"; +- Bananapi BPI-R64 for MT7622: + Required root node properties: + - compatible = "bananapi,bpi-r64", "mediatek,mt7622"; - Reference board for MT7623a with eMMC: Required root node properties: - compatible = "mediatek,mt7623a-rfb-emmc", "mediatek,mt7623"; @@ -68,6 +72,9 @@ Supported boards: - compatible = "mediatek,mt7623n-rfb-emmc", "mediatek,mt7623"; - Bananapi BPI-R2 board: - compatible = "bananapi,bpi-r2", "mediatek,mt7623"; +- Reference board for MT7629: + Required root node properties: + - compatible = "mediatek,mt7629-rfb", "mediatek,mt7629"; - MTK mt8127 tablet moose EVB: Required root node properties: - compatible = "mediatek,mt8127-moose", "mediatek,mt8127"; @@ -77,3 +84,6 @@ Supported boards: - MTK mt8173 tablet EVB: Required root node properties: - compatible = "mediatek,mt8173-evb", "mediatek,mt8173"; +- Evaluation board for MT8183: + Required root node properties: + - compatible = "mediatek,mt8183-evb", "mediatek,mt8183"; diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt index b404d592ce58..de4075413d91 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,apmixedsys.txt @@ -10,6 +10,8 @@ Required Properties: - "mediatek,mt2712-apmixedsys", "syscon" - "mediatek,mt6797-apmixedsys" - "mediatek,mt7622-apmixedsys" + - "mediatek,mt7623-apmixedsys", "mediatek,mt2701-apmixedsys" + - "mediatek,mt7629-apmixedsys" - "mediatek,mt8135-apmixedsys" - "mediatek,mt8173-apmixedsys" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt index 34a69ba67f13..d1606b2c3e63 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,audsys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be one of: - "mediatek,mt2701-audsys", "syscon" - "mediatek,mt7622-audsys", "syscon" + - "mediatek,mt7623-audsys", "mediatek,mt2701-audsys", "syscon" - #clock-cells: Must be 1 The AUDSYS controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt index 4010e37c53a0..149567a38215 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,bdpsys.txt @@ -8,6 +8,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt2701-bdpsys", "syscon" - "mediatek,mt2712-bdpsys", "syscon" + - "mediatek,mt7623-bdpsys", "mediatek,mt2701-bdpsys", "syscon" - #clock-cells: Must be 1 The bdpsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt index 8f5335b480ac..6b7e8067e7aa 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ethsys.txt @@ -8,6 +8,8 @@ Required Properties: - compatible: Should be: - "mediatek,mt2701-ethsys", "syscon" - "mediatek,mt7622-ethsys", "syscon" + - "mediatek,mt7623-ethsys", "mediatek,mt2701-ethsys", "syscon" + - "mediatek,mt7629-ethsys", "syscon" - #clock-cells: Must be 1 - #reset-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt index f5629d64cef2..323905af82c3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,hifsys.txt @@ -9,6 +9,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt2701-hifsys", "syscon" - "mediatek,mt7622-hifsys", "syscon" + - "mediatek,mt7623-hifsys", "mediatek,mt2701-hifsys", "syscon" - #clock-cells: Must be 1 The hifsys controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt index 868bd51a98be..3f99672163e3 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,imgsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2701-imgsys", "syscon" - "mediatek,mt2712-imgsys", "syscon" - "mediatek,mt6797-imgsys", "syscon" + - "mediatek,mt7623-imgsys", "mediatek,mt2701-imgsys", "syscon" - "mediatek,mt8173-imgsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt index 566f153f9f83..417bd83d1378 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,infracfg.txt @@ -11,6 +11,8 @@ Required Properties: - "mediatek,mt2712-infracfg", "syscon" - "mediatek,mt6797-infracfg", "syscon" - "mediatek,mt7622-infracfg", "syscon" + - "mediatek,mt7623-infracfg", "mediatek,mt2701-infracfg", "syscon" + - "mediatek,mt7629-infracfg", "syscon" - "mediatek,mt8135-infracfg", "syscon" - "mediatek,mt8173-infracfg", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt index 4eb8bbe15c01..15d977afad31 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,mmsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2701-mmsys", "syscon" - "mediatek,mt2712-mmsys", "syscon" - "mediatek,mt6797-mmsys", "syscon" + - "mediatek,mt7623-mmsys", "mediatek,mt2701-mmsys", "syscon" - "mediatek,mt8173-mmsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt index 7fe5dc6097a6..d179a61536f4 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pciesys.txt @@ -7,6 +7,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-pciesys", "syscon" + - "mediatek,mt7629-pciesys", "syscon" - #clock-cells: Must be 1 - #reset-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt index fb58ca8c2770..4c7e478117a0 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,pericfg.txt @@ -10,6 +10,8 @@ Required Properties: - "mediatek,mt2701-pericfg", "syscon" - "mediatek,mt2712-pericfg", "syscon" - "mediatek,mt7622-pericfg", "syscon" + - "mediatek,mt7623-pericfg", "mediatek,mt2701-pericfg", "syscon" + - "mediatek,mt7629-pericfg", "syscon" - "mediatek,mt8135-pericfg", "syscon" - "mediatek,mt8173-pericfg", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt index d113b8e741f3..30cb645c0e54 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,sgmiisys.txt @@ -7,6 +7,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-sgmiisys", "syscon" + - "mediatek,mt7629-sgmiisys", "syscon" - #clock-cells: Must be 1 The SGMIISYS controller uses the common clk binding from diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt index b8184da2508c..7cb02c930613 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,ssusbsys.txt @@ -7,6 +7,7 @@ Required Properties: - compatible: Should be: - "mediatek,mt7622-ssusbsys", "syscon" + - "mediatek,mt7629-ssusbsys", "syscon" - #clock-cells: Must be 1 - #reset-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt index 24014a7e2332..d160c2b4b6fe 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,topckgen.txt @@ -10,6 +10,8 @@ Required Properties: - "mediatek,mt2712-topckgen", "syscon" - "mediatek,mt6797-topckgen" - "mediatek,mt7622-topckgen" + - "mediatek,mt7623-topckgen", "mediatek,mt2701-topckgen" + - "mediatek,mt7629-topckgen" - "mediatek,mt8135-topckgen" - "mediatek,mt8173-topckgen" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt index ea40d05089f8..3212afc753c8 100644 --- a/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt +++ b/Documentation/devicetree/bindings/arm/mediatek/mediatek,vdecsys.txt @@ -9,6 +9,7 @@ Required Properties: - "mediatek,mt2701-vdecsys", "syscon" - "mediatek,mt2712-vdecsys", "syscon" - "mediatek,mt6797-vdecsys", "syscon" + - "mediatek,mt7623-vdecsys", "mediatek,mt2701-vdecsys", "syscon" - "mediatek,mt8173-vdecsys", "syscon" - #clock-cells: Must be 1 diff --git a/Documentation/devicetree/bindings/arm/mrvl/mrvl.txt b/Documentation/devicetree/bindings/arm/mrvl/mrvl.txt index 117d741a2e4f..951687528efb 100644 --- a/Documentation/devicetree/bindings/arm/mrvl/mrvl.txt +++ b/Documentation/devicetree/bindings/arm/mrvl/mrvl.txt @@ -11,4 +11,4 @@ Required root node properties: MMP2 Brownstone Board Required root node properties: - - compatible = "mrvl,mmp2-brownstone"; + - compatible = "mrvl,mmp2-brownstone", "mrvl,mmp2"; diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,kpss-acc.txt b/Documentation/devicetree/bindings/arm/msm/qcom,kpss-acc.txt index 1333db9acfee..7f696362a4a1 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,kpss-acc.txt +++ b/Documentation/devicetree/bindings/arm/msm/qcom,kpss-acc.txt @@ -21,10 +21,29 @@ PROPERTIES the register region. An optional second element specifies the base address and size of the alias register region. +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the pll parents. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "pll8_vote", "pxo". + +- clock-output-names: + Usage: optional + Value type: <string> + Definition: Name of the output clock. Typically acpuX_aux where X is a + CPU number starting at 0. + Example: clock-controller@2088000 { compatible = "qcom,kpss-acc-v2"; reg = <0x02088000 0x1000>, <0x02008000 0x1000>; + clocks = <&gcc PLL8_VOTE>, <&gcc PXO_SRC>; + clock-names = "pll8_vote", "pxo"; + clock-output-names = "acpu0_aux"; }; diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,kpss-gcc.txt b/Documentation/devicetree/bindings/arm/msm/qcom,kpss-gcc.txt new file mode 100644 index 000000000000..e628758950e1 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/msm/qcom,kpss-gcc.txt @@ -0,0 +1,44 @@ +Krait Processor Sub-system (KPSS) Global Clock Controller (GCC) + +PROPERTIES + +- compatible: + Usage: required + Value type: <string> + Definition: should be one of the following. The generic compatible + "qcom,kpss-gcc" should also be included. + "qcom,kpss-gcc-ipq8064", "qcom,kpss-gcc" + "qcom,kpss-gcc-apq8064", "qcom,kpss-gcc" + "qcom,kpss-gcc-msm8974", "qcom,kpss-gcc" + "qcom,kpss-gcc-msm8960", "qcom,kpss-gcc" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: base address and size of the register region + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the pll parents. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "pll8_vote", "pxo". + +- clock-output-names: + Usage: required + Value type: <string> + Definition: Name of the output clock. Typically acpu_l2_aux indicating + an L2 cache auxiliary clock. + +Example: + + l2cc: clock-controller@2011000 { + compatible = "qcom,kpss-gcc-ipq8064", "qcom,kpss-gcc"; + reg = <0x2011000 0x1000>; + clocks = <&gcc PLL8_VOTE>, <&gcc PXO_SRC>; + clock-names = "pll8_vote", "pxo"; + clock-output-names = "acpu_l2_aux"; + }; diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.txt b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.txt index 5e85749262ae..eaee06b2d8f2 100644 --- a/Documentation/devicetree/bindings/arm/msm/qcom,llcc.txt +++ b/Documentation/devicetree/bindings/arm/msm/qcom,llcc.txt @@ -16,11 +16,26 @@ Properties: - reg: Usage: required Value Type: <prop-encoded-array> - Definition: Start address and the the size of the register region. + Definition: The first element specifies the llcc base start address and + the size of the register region. The second element specifies + the llcc broadcast base address and size of the register region. + +- reg-names: + Usage: required + Value Type: <stringlist> + Definition: Register region names. Must be "llcc_base", "llcc_broadcast_base". + +- interrupts: + Usage: required + Definition: The interrupt is associated with the llcc edac device. + It's used for llcc cache single and double bit error detection + and reporting. Example: cache-controller@1100000 { compatible = "qcom,sdm845-llcc"; - reg = <0x1100000 0x250000>; + reg = <0x1100000 0x200000>, <0x1300000 0x50000> ; + reg-names = "llcc_base", "llcc_broadcast_base"; + interrupts = <GIC_SPI 582 IRQ_TYPE_LEVEL_HIGH>; }; diff --git a/Documentation/devicetree/bindings/arm/nspire.txt b/Documentation/devicetree/bindings/arm/nspire.txt deleted file mode 100644 index 4d08518bd176..000000000000 --- a/Documentation/devicetree/bindings/arm/nspire.txt +++ /dev/null @@ -1,14 +0,0 @@ -TI-NSPIRE calculators - -Required properties: -- compatible: Compatible property value should contain "ti,nspire". - CX models should have "ti,nspire-cx" - Touchpad models should have "ti,nspire-tp" - Clickpad models should have "ti,nspire-clp" - -Example: - -/ { - model = "TI-NSPIRE CX"; - compatible = "ti,nspire-cx"; - ... diff --git a/Documentation/devicetree/bindings/arm/olimex.txt b/Documentation/devicetree/bindings/arm/olimex.txt deleted file mode 100644 index d726aeca56be..000000000000 --- a/Documentation/devicetree/bindings/arm/olimex.txt +++ /dev/null @@ -1,10 +0,0 @@ -Olimex Device Tree Bindings ---------------------------- - -SAM9-L9260 Board -Required root node properties: - - compatible = "olimex,sam9-l9260", "atmel,at91sam9260"; - -i.MX23 Olinuxino Low Cost Board -Required root node properties: - - compatible = "olimex,imx23-olinuxino", "fsl,imx23"; diff --git a/Documentation/devicetree/bindings/arm/primecell.txt b/Documentation/devicetree/bindings/arm/primecell.txt deleted file mode 100644 index 0df6acacfaea..000000000000 --- a/Documentation/devicetree/bindings/arm/primecell.txt +++ /dev/null @@ -1,46 +0,0 @@ -* ARM Primecell Peripherals - -ARM, Ltd. Primecell peripherals have a standard id register that can be used to -identify the peripheral type, vendor, and revision. This value can be used for -driver matching. - -Required properties: - -- compatible : should be a specific name for the peripheral and - "arm,primecell". The specific name will match the ARM - engineering name for the logic block in the form: "arm,pl???" - -Optional properties: - -- arm,primecell-periphid : Value to override the h/w value with -- clocks : From common clock binding. First clock is phandle to clock for apb - pclk. Additional clocks are optional and specific to those peripherals. -- clock-names : From common clock binding. Shall be "apb_pclk" for first clock. -- dmas : From common DMA binding. If present, refers to one or more dma channels. -- dma-names : From common DMA binding, needs to match the 'dmas' property. - Devices with exactly one receive and transmit channel shall name - these "rx" and "tx", respectively. -- pinctrl-<n> : Pinctrl states as described in bindings/pinctrl/pinctrl-bindings.txt -- pinctrl-names : Names corresponding to the numbered pinctrl states -- interrupts : one or more interrupt specifiers -- interrupt-names : names corresponding to the interrupts properties - -Example: - -serial@fff36000 { - compatible = "arm,pl011", "arm,primecell"; - arm,primecell-periphid = <0x00341011>; - - clocks = <&pclk>; - clock-names = "apb_pclk"; - - dmas = <&dma-controller 4>, <&dma-controller 5>; - dma-names = "rx", "tx"; - - pinctrl-0 = <&uart0_default_mux>, <&uart0_default_mode>; - pinctrl-1 = <&uart0_sleep_mode>; - pinctrl-names = "default","sleep"; - - interrupts = <0 11 0x4>; -}; - diff --git a/Documentation/devicetree/bindings/arm/primecell.yaml b/Documentation/devicetree/bindings/arm/primecell.yaml new file mode 100644 index 000000000000..5aae37f1c563 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/primecell.yaml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/primecell.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM Primecell Peripherals + +maintainers: + - Rob Herring <robh@kernel.org> + +description: |+ + ARM, Ltd. Primecell peripherals have a standard id register that can be used to + identify the peripheral type, vendor, and revision. This value can be used for + driver matching. + +properties: + compatible: + contains: + const: arm,primecell + description: + Should be a specific name for the peripheral followed by "arm,primecell". + The specific name will match the ARM engineering name for the logic block + in the form "arm,pl???" + + arm,primecell-periphid: + $ref: /schemas/types.yaml#/definitions/uint32 + description: Value to override the h/w ID value + clocks: + minItems: 1 + maxItems: 32 + clock-names: + contains: + const: apb_pclk + additionalItems: true +... diff --git a/Documentation/devicetree/bindings/arm/qcom.txt b/Documentation/devicetree/bindings/arm/qcom.txt deleted file mode 100644 index ee532e705d6c..000000000000 --- a/Documentation/devicetree/bindings/arm/qcom.txt +++ /dev/null @@ -1,57 +0,0 @@ -QCOM device tree bindings -------------------------- - -Some qcom based bootloaders identify the dtb blob based on a set of -device properties like SoC and platform and revisions of those components. -To support this scheme, we encode this information into the board compatible -string. - -Each board must specify a top-level board compatible string with the following -format: - - compatible = "qcom,<SoC>[-<soc_version>][-<foundry_id>]-<board>[/<subtype>][-<board_version>]" - -The 'SoC' and 'board' elements are required. All other elements are optional. - -The 'SoC' element must be one of the following strings: - - apq8016 - apq8074 - apq8084 - apq8096 - msm8916 - msm8974 - msm8992 - msm8994 - msm8996 - mdm9615 - ipq8074 - sdm845 - -The 'board' element must be one of the following strings: - - cdp - liquid - dragonboard - mtp - sbc - hk01 - -The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor> -where the minor number may be omitted when it's zero, i.e. v1.0 is the same -as v1. If all versions of the 'board_version' elements match, then a -wildcard '*' should be used, e.g. 'v*'. - -The 'foundry_id' and 'subtype' elements are one or more digits from 0 to 9. - -Examples: - - "qcom,msm8916-v1-cdp-pm8916-v2.1" - -A CDP board with an msm8916 SoC, version 1 paired with a pm8916 PMIC of version -2.1. - - "qcom,apq8074-v2.0-2-dragonboard/1-v0.1" - -A dragonboard board v0.1 of subtype 1 with an apq8074 SoC version 2, made in -foundry 2. diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml new file mode 100644 index 000000000000..f6316ab66385 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -0,0 +1,125 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/bindings/arm/qcom.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: QCOM device tree bindings + +maintainers: + - Stephen Boyd <sboyd@codeaurora.org> + +description: | + Some qcom based bootloaders identify the dtb blob based on a set of + device properties like SoC and platform and revisions of those components. + To support this scheme, we encode this information into the board compatible + string. + + Each board must specify a top-level board compatible string with the following + format: + + compatible = "qcom,<SoC>[-<soc_version>][-<foundry_id>]-<board>[/<subtype>][-<board_version>]" + + The 'SoC' and 'board' elements are required. All other elements are optional. + + The 'SoC' element must be one of the following strings: + + apq8016 + apq8074 + apq8084 + apq8096 + msm8916 + msm8974 + msm8992 + msm8994 + msm8996 + mdm9615 + ipq8074 + sdm845 + + The 'board' element must be one of the following strings: + + cdp + liquid + dragonboard + mtp + sbc + hk01 + + The 'soc_version' and 'board_version' elements take the form of v<Major>.<Minor> + where the minor number may be omitted when it's zero, i.e. v1.0 is the same + as v1. If all versions of the 'board_version' elements match, then a + wildcard '*' should be used, e.g. 'v*'. + + The 'foundry_id' and 'subtype' elements are one or more digits from 0 to 9. + + Examples: + + "qcom,msm8916-v1-cdp-pm8916-v2.1" + + A CDP board with an msm8916 SoC, version 1 paired with a pm8916 PMIC of version + 2.1. + + "qcom,apq8074-v2.0-2-dragonboard/1-v0.1" + + A dragonboard board v0.1 of subtype 1 with an apq8074 SoC version 2, made in + foundry 2. + +properties: + compatible: + oneOf: + - items: + - enum: + - qcom,apq8016-sbc + - const: qcom,apq8016 + + - items: + - enum: + - qcom,apq8064-cm-qs600 + - qcom,apq8064-ifc6410 + - const: qcom,apq8064 + + - items: + - enum: + - qcom,apq8074-dragonboard + - const: qcom,apq8074 + + - items: + - enum: + - qcom,apq8060-dragonboard + - qcom,msm8660-surf + - const: qcom,msm8660 + + - items: + - enum: + - qcom,apq8084-mtp + - qcom,apq8084-sbc + - const: qcom,apq8084 + + - items: + - enum: + - qcom,msm8960-cdp + - const: qcom,msm8960 + + - items: + - const: qcom,msm8916-mtp/1 + - const: qcom,msm8916-mtp + - const: qcom,msm8916 + + - items: + - const: qcom,msm8996-mtp + + - items: + - const: qcom,ipq4019 + + - items: + - enum: + - qcom,ipq8064-ap148 + - const: qcom,ipq8064 + + - items: + - enum: + - qcom,ipq8074-hk01 + - const: qcom,ipq8074 + +... diff --git a/Documentation/devicetree/bindings/arm/rda.txt b/Documentation/devicetree/bindings/arm/rda.txt new file mode 100644 index 000000000000..43c80762c428 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/rda.txt @@ -0,0 +1,17 @@ +RDA Micro platforms device tree bindings +---------------------------------------- + +RDA8810PL SoC +============= + +Required root node properties: + + - compatible : must contain "rda,8810pl" + + +Boards: + +Root node property compatible must contain, depending on board: + + - Orange Pi 2G-IoT: "xunlong,orangepi-2g-iot" + - Orange Pi i96: "xunlong,orangepi-i96" diff --git a/Documentation/devicetree/bindings/arm/renesas,prr.txt b/Documentation/devicetree/bindings/arm/renesas,prr.txt new file mode 100644 index 000000000000..08e482e953ca --- /dev/null +++ b/Documentation/devicetree/bindings/arm/renesas,prr.txt @@ -0,0 +1,20 @@ +Renesas Product Register + +Most Renesas ARM SoCs have a Product Register or Boundary Scan ID Register that +allows to retrieve SoC product and revision information. If present, a device +node for this register should be added. + +Required properties: + - compatible: Must be one of: + "renesas,prr" + "renesas,bsid" + - reg: Base address and length of the register block. + + +Examples +-------- + + prr: chipid@ff000044 { + compatible = "renesas,prr"; + reg = <0 0xff000044 0 4>; + }; diff --git a/Documentation/devicetree/bindings/arm/renesas.yaml b/Documentation/devicetree/bindings/arm/renesas.yaml new file mode 100644 index 000000000000..19f379863d50 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/renesas.yaml @@ -0,0 +1,238 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/shmobile.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas SH-Mobile, R-Mobile, and R-Car Platform Device Tree Bindings + +maintainers: + - Geert Uytterhoeven <geert+renesas@glider.be> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - description: Emma Mobile EV2 + items: + - enum: + - renesas,kzm9d # Kyoto Microcomputer Co. KZM-A9-Dual + - const: renesas,emev2 + + - description: RZ/A1H (R7S72100) + items: + - enum: + - renesas,genmai # Genmai (RTK772100BC00000BR) + - renesas,gr-peach # GR-Peach (X28A-M01-E/F) + - renesas,rskrza1 # RSKRZA1 (YR0K77210C000BE) + - const: renesas,r7s72100 + + - description: RZ/A2 (R7S9210) + items: + - enum: + - renesas,rza2mevb # RZ/A2M Eval Board (RTK7921053S00000BE) + - const: renesas,r7s9210 + + - description: SH-Mobile AG5 (R8A73A00/SH73A0) + items: + - enum: + - renesas,kzm9g # Kyoto Microcomputer Co. KZM-A9-GT + - const: renesas,sh73a0 + + - description: R-Mobile APE6 (R8A73A40) + items: + - enum: + - renesas,ape6evm + - const: renesas,r8a73a4 + + - description: R-Mobile A1 (R8A77400) + items: + - enum: + - renesas,armadillo800eva # Atmark Techno Armadillo-800 EVA + - const: renesas,r8a7740 + + - description: RZ/G1H (R8A77420) + items: + - const: renesas,r8a7742 + + - description: RZ/G1M (R8A77430) + items: + - enum: + # iWave Systems RZ/G1M Qseven Development Platform (iW-RainboW-G20D-Qseven) + - iwave,g20d + - const: iwave,g20m + - const: renesas,r8a7743 + + - items: + - enum: + # iWave Systems RZ/G1M Qseven System On Module (iW-RainboW-G20M-Qseven) + - iwave,g20m + - renesas,sk-rzg1m # SK-RZG1M (YR8A77430S000BE) + - const: renesas,r8a7743 + + - description: RZ/G1N (R8A77440) + items: + - enum: + # iWave Systems RZ/G1N Qseven Development Platform (iW-RainboW-G20D-Qseven) + - iwave,g20d + - const: iwave,g20m + - const: renesas,r8a7744 + + - items: + - enum: + # iWave Systems RZ/G1N Qseven System On Module (iW-RainboW-G20M-Qseven) + - iwave,g20m + - const: renesas,r8a7744 + + - description: RZ/G1E (R8A77450) + items: + - enum: + - iwave,g22m # iWave Systems RZ/G1E SODIMM System On Module (iW-RainboW-G22M-SM) + - renesas,sk-rzg1e # SK-RZG1E (YR8A77450S000BE) + - const: renesas,r8a7745 + + - description: iWave Systems RZ/G1E SODIMM SOM Development Platform (iW-RainboW-G22D) + items: + - const: iwave,g22d + - const: iwave,g22m + - const: renesas,r8a7745 + + - description: RZ/G1C (R8A77470) + items: + - enum: + - iwave,g23s #iWave Systems RZ/G1C Single Board Computer (iW-RainboW-G23S) + - const: renesas,r8a77470 + + - description: RZ/G2M (R8A774A1) + items: + - const: renesas,r8a774a1 + + - description: RZ/G2E (R8A774C0) + items: + - enum: + - si-linux,cat874 # Silicon Linux RZ/G2E 96board platform (CAT874) + - const: renesas,r8a774c0 + + - items: + - enum: + - si-linux,cat875 # Silicon Linux sub board for CAT874 (CAT875) + - const: si-linux,cat874 + - const: renesas,r8a774c0 + + - description: R-Car M1A (R8A77781) + items: + - enum: + - renesas,bockw + - const: renesas,r8a7778 + + - description: R-Car H1 (R8A77790) + items: + - enum: + - renesas,marzen # Marzen (R0P7779A00010S) + - const: renesas,r8a7779 + + - description: R-Car H2 (R8A77900) + items: + - enum: + - renesas,lager # Lager (RTP0RC7790SEB00010S) + - renesas,stout # Stout (ADAS Starterkit, Y-R-CAR-ADAS-SKH2-BOARD) + - const: renesas,r8a7790 + + - description: R-Car M2-W (R8A77910) + items: + - enum: + - renesas,henninger + - renesas,koelsch # Koelsch (RTP0RC7791SEB00010S) + - renesas,porter # Porter (M2-LCDP) + - const: renesas,r8a7791 + + - description: R-Car V2H (R8A77920) + items: + - enum: + - renesas,blanche # Blanche (RTP0RC7792SEB00010S) + - renesas,wheat # Wheat (RTP0RC7792ASKB0000JE) + - const: renesas,r8a7792 + + - description: R-Car M2-N (R8A77930) + items: + - enum: + - renesas,gose # Gose (RTP0RC7793SEB00010S) + - const: renesas,r8a7793 + + - description: R-Car E2 (R8A77940) + items: + - enum: + - renesas,alt # Alt (RTP0RC7794SEB00010S) + - renesas,silk # SILK (RTP0RC7794LCB00011S) + - const: renesas,r8a7794 + + - description: R-Car H3 (R8A77950) + items: + - enum: + # H3ULCB (R-Car Starter Kit Premier, RTP0RC7795SKBX0010SA00 (H3 ES1.1)) + # H3ULCB (R-Car Starter Kit Premier, RTP0RC77951SKBX010SA00 (H3 ES2.0)) + - renesas,h3ulcb + - renesas,salvator-x # Salvator-X (RTP0RC7795SIPB0010S) + - renesas,salvator-xs # Salvator-XS (Salvator-X 2nd version, RTP0RC7795SIPB0012S) + - const: renesas,r8a7795 + + - description: R-Car M3-W (R8A77960) + items: + - enum: + - renesas,m3ulcb # M3ULCB (R-Car Starter Kit Pro, RTP0RC7796SKBX0010SA09 (M3 ES1.0)) + - renesas,salvator-x # Salvator-X (RTP0RC7796SIPB0011S) + - renesas,salvator-xs # Salvator-XS (Salvator-X 2nd version, RTP0RC7796SIPB0012S) + - const: renesas,r8a7796 + + - description: Kingfisher (SBEV-RCAR-KF-M03) + items: + - const: shimafuji,kingfisher + - enum: + - renesas,h3ulcb + - renesas,m3ulcb + - enum: + - renesas,r8a7795 + - renesas,r8a7796 + + - description: R-Car M3-N (R8A77965) + items: + - enum: + - renesas,m3nulcb # M3NULCB (R-Car Starter Kit Pro, RTP0RC77965SKBX010SA00 (M3-N ES1.1)) + - renesas,salvator-x # Salvator-X (RTP0RC7796SIPB0011S (M3-N)) + - renesas,salvator-xs # Salvator-XS (Salvator-X 2nd version, RTP0RC77965SIPB012S) + - const: renesas,r8a77965 + + - description: R-Car V3M (R8A77970) + items: + - enum: + - renesas,eagle # Eagle (RTP0RC77970SEB0010S) + - renesas,v3msk # V3MSK (Y-ASK-RCAR-V3M-WS10) + - const: renesas,r8a77970 + + - description: R-Car V3H (R8A77980) + items: + - enum: + - renesas,condor # Condor (RTP0RC77980SEB0010SS/RTP0RC77980SEB0010SA01) + - renesas,v3hsk # V3HSK (Y-ASK-RCAR-V3H-WS10) + - const: renesas,r8a77980 + + - description: R-Car E3 (R8A77990) + items: + - enum: + - renesas,ebisu # Ebisu (RTP0RC77990SEB0010S) + - const: renesas,r8a77990 + + - description: R-Car D3 (R8A77995) + items: + - enum: + - renesas,draak # Draak (RTP0RC77995SEB0010S) + - const: renesas,r8a77995 + + - description: RZ/N1D (R9A06G032) + items: + - enum: + - renesas,rzn1d400-db # RZN1D-DB (RZ/N1D Demo Board for the RZ/N1D 400 pins package) + - const: renesas,r9a06g032 + +... diff --git a/Documentation/devicetree/bindings/arm/rockchip.txt b/Documentation/devicetree/bindings/arm/rockchip.txt deleted file mode 100644 index acfd3c773dd0..000000000000 --- a/Documentation/devicetree/bindings/arm/rockchip.txt +++ /dev/null @@ -1,220 +0,0 @@ -Rockchip platforms device tree bindings ---------------------------------------- - -- 96boards RK3399 Ficus (ROCK960 Enterprise Edition) - Required root node properties: - - compatible = "vamrs,ficus", "rockchip,rk3399"; - -- Amarula Vyasa RK3288 board - Required root node properties: - - compatible = "amarula,vyasa-rk3288", "rockchip,rk3288"; - -- Asus Tinker board - Required root node properties: - - compatible = "asus,rk3288-tinker", "rockchip,rk3288"; - -- Kylin RK3036 board: - Required root node properties: - - compatible = "rockchip,kylin-rk3036", "rockchip,rk3036"; - -- MarsBoard RK3066 board: - Required root node properties: - - compatible = "haoyu,marsboard-rk3066", "rockchip,rk3066a"; - -- bq Curie 2 tablet: - Required root node properties: - - compatible = "mundoreader,bq-curie2", "rockchip,rk3066a"; - -- ChipSPARK Rayeager PX2 board: - Required root node properties: - - compatible = "chipspark,rayeager-px2", "rockchip,rk3066a"; - -- Radxa Rock board: - Required root node properties: - - compatible = "radxa,rock", "rockchip,rk3188"; - -- Radxa Rock2 Square board: - Required root node properties: - - compatible = "radxa,rock2-square", "rockchip,rk3288"; - -- Rikomagic MK808 v1 board: - Required root node properties: - - compatible = "rikomagic,mk808", "rockchip,rk3066a"; - -- Firefly Firefly-RK3288 board: - Required root node properties: - - compatible = "firefly,firefly-rk3288", "rockchip,rk3288"; - or - - compatible = "firefly,firefly-rk3288-beta", "rockchip,rk3288"; - -- Firefly Firefly-RK3288 Reload board: - Required root node properties: - - compatible = "firefly,firefly-rk3288-reload", "rockchip,rk3288"; - -- Firefly Firefly-RK3399 board: - Required root node properties: - - compatible = "firefly,firefly-rk3399", "rockchip,rk3399"; - -- Firefly roc-rk3328-cc board: - Required root node properties: - - compatible = "firefly,roc-rk3328-cc", "rockchip,rk3328"; - -- ChipSPARK PopMetal-RK3288 board: - Required root node properties: - - compatible = "chipspark,popmetal-rk3288", "rockchip,rk3288"; - -- Netxeon R89 board: - Required root node properties: - - compatible = "netxeon,r89", "rockchip,rk3288"; - -- GeekBuying GeekBox: - Required root node properties: - - compatible = "geekbuying,geekbox", "rockchip,rk3368"; - -- Google Bob (Asus Chromebook Flip C101PA): - Required root node properties: - compatible = "google,bob-rev13", "google,bob-rev12", - "google,bob-rev11", "google,bob-rev10", - "google,bob-rev9", "google,bob-rev8", - "google,bob-rev7", "google,bob-rev6", - "google,bob-rev5", "google,bob-rev4", - "google,bob", "google,gru", "rockchip,rk3399"; - -- Google Brain (dev-board): - Required root node properties: - - compatible = "google,veyron-brain-rev0", "google,veyron-brain", - "google,veyron", "rockchip,rk3288"; - -- Google Gru (dev-board): - Required root node properties: - - compatible = "google,gru-rev15", "google,gru-rev14", - "google,gru-rev13", "google,gru-rev12", - "google,gru-rev11", "google,gru-rev10", - "google,gru-rev9", "google,gru-rev8", - "google,gru-rev7", "google,gru-rev6", - "google,gru-rev5", "google,gru-rev4", - "google,gru-rev3", "google,gru-rev2", - "google,gru", "rockchip,rk3399"; - -- Google Jaq (Haier Chromebook 11 and more): - Required root node properties: - - compatible = "google,veyron-jaq-rev5", "google,veyron-jaq-rev4", - "google,veyron-jaq-rev3", "google,veyron-jaq-rev2", - "google,veyron-jaq-rev1", "google,veyron-jaq", - "google,veyron", "rockchip,rk3288"; - -- Google Jerry (Hisense Chromebook C11 and more): - Required root node properties: - - compatible = "google,veyron-jerry-rev7", "google,veyron-jerry-rev6", - "google,veyron-jerry-rev5", "google,veyron-jerry-rev4", - "google,veyron-jerry-rev3", "google,veyron-jerry", - "google,veyron", "rockchip,rk3288"; - -- Google Kevin (Samsung Chromebook Plus): - Required root node properties: - - compatible = "google,kevin-rev15", "google,kevin-rev14", - "google,kevin-rev13", "google,kevin-rev12", - "google,kevin-rev11", "google,kevin-rev10", - "google,kevin-rev9", "google,kevin-rev8", - "google,kevin-rev7", "google,kevin-rev6", - "google,kevin", "google,gru", "rockchip,rk3399"; - -- Google Mickey (Asus Chromebit CS10): - Required root node properties: - - compatible = "google,veyron-mickey-rev8", "google,veyron-mickey-rev7", - "google,veyron-mickey-rev6", "google,veyron-mickey-rev5", - "google,veyron-mickey-rev4", "google,veyron-mickey-rev3", - "google,veyron-mickey-rev2", "google,veyron-mickey-rev1", - "google,veyron-mickey-rev0", "google,veyron-mickey", - "google,veyron", "rockchip,rk3288"; - -- Google Minnie (Asus Chromebook Flip C100P): - Required root node properties: - - compatible = "google,veyron-minnie-rev4", "google,veyron-minnie-rev3", - "google,veyron-minnie-rev2", "google,veyron-minnie-rev1", - "google,veyron-minnie-rev0", "google,veyron-minnie", - "google,veyron", "rockchip,rk3288"; - -- Google Pinky (dev-board): - Required root node properties: - - compatible = "google,veyron-pinky-rev2", "google,veyron-pinky", - "google,veyron", "rockchip,rk3288"; - -- Google Speedy (Asus C201 Chromebook): - Required root node properties: - - compatible = "google,veyron-speedy-rev9", "google,veyron-speedy-rev8", - "google,veyron-speedy-rev7", "google,veyron-speedy-rev6", - "google,veyron-speedy-rev5", "google,veyron-speedy-rev4", - "google,veyron-speedy-rev3", "google,veyron-speedy-rev2", - "google,veyron-speedy", "google,veyron", "rockchip,rk3288"; - -- mqmaker MiQi: - Required root node properties: - - compatible = "mqmaker,miqi", "rockchip,rk3288"; - -- Phytec phyCORE-RK3288: Rapid Development Kit - Required root node properties: - - compatible = "phytec,rk3288-pcm-947", "phytec,rk3288-phycore-som", "rockchip,rk3288"; - -- Pine64 Rock64 board: - Required root node properties: - - compatible = "pine64,rock64", "rockchip,rk3328"; - -- Rockchip PX3 Evaluation board: - Required root node properties: - - compatible = "rockchip,px3-evb", "rockchip,px3", "rockchip,rk3188"; - -- Rockchip PX5 Evaluation board: - Required root node properties: - - compatible = "rockchip,px5-evb", "rockchip,px5", "rockchip,rk3368"; - -- Rockchip RV1108 Evaluation board - Required root node properties: - - compatible = "rockchip,rv1108-evb", "rockchip,rv1108"; - -- Rockchip RK3368 evb: - Required root node properties: - - compatible = "rockchip,rk3368-evb-act8846", "rockchip,rk3368"; - -- Rockchip R88 board: - Required root node properties: - - compatible = "rockchip,r88", "rockchip,rk3368"; - -- Rockchip RK3228 Evaluation board: - Required root node properties: - - compatible = "rockchip,rk3228-evb", "rockchip,rk3228"; - -- Rockchip RK3229 Evaluation board: - - compatible = "rockchip,rk3229-evb", "rockchip,rk3229"; - -- Rockchip RK3288 Fennec board: - Required root node properties: - - compatible = "rockchip,rk3288-fennec", "rockchip,rk3288"; - -- Rockchip RK3328 evb: - Required root node properties: - - compatible = "rockchip,rk3328-evb", "rockchip,rk3328"; - -- Rockchip RK3399 evb: - Required root node properties: - - compatible = "rockchip,rk3399-evb", "rockchip,rk3399"; - -- Rockchip RK3399 Sapphire board standalone: - Required root node properties: - - compatible = "rockchip,rk3399-sapphire", "rockchip,rk3399"; - -- Rockchip RK3399 Sapphire Excavator board: - Required root node properties: - - compatible = "rockchip,rk3399-sapphire-excavator", "rockchip,rk3399"; - -- Theobroma Systems RK3368-uQ7 Haikou Baseboard: - Required root node properties: - - compatible = "tsd,rk3368-uq7-haikou", "rockchip,rk3368"; - -- Theobroma Systems RK3399-Q7 Haikou Baseboard: - Required root node properties: - - compatible = "tsd,rk3399-q7-haikou", "rockchip,rk3399"; - -- Tronsmart Orion R68 Meta - Required root node properties: - - compatible = "tronsmart,orion-r68-meta", "rockchip,rk3368"; diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml new file mode 100644 index 000000000000..061a03edf9c8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -0,0 +1,440 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/rockchip.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip platforms device tree bindings + +maintainers: + - Heiko Stuebner <heiko@sntech.de> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + + - description: 96boards RK3399 Ficus (ROCK960 Enterprise Edition) + items: + - const: vamrs,ficus + - const: rockchip,rk3399 + + - description: 96boards RK3399 Rock960 (ROCK960 Consumer Edition) + items: + - const: vamrs,rock960 + - const: rockchip,rk3399 + + - description: Amarula Vyasa RK3288 + items: + - const: amarula,vyasa-rk3288 + - const: rockchip,rk3288 + + - description: Asus Tinker board + items: + - const: asus,rk3288-tinker + - const: rockchip,rk3288 + + - description: Asus Tinker board S + items: + - const: asus,rk3288-tinker-s + - const: rockchip,rk3288 + + - description: bq Curie 2 tablet + items: + - const: mundoreader,bq-curie2 + - const: rockchip,rk3066a + + - description: bq Edison 2 Quad-Core tablet + items: + - const: mundoreader,bq-edison2qc + - const: rockchip,rk3188 + + - description: ChipSPARK PopMetal-RK3288 + items: + - const: chipspark,popmetal-rk3288 + - const: rockchip,rk3288 + + - description: ChipSPARK Rayeager PX2 + items: + - const: chipspark,rayeager-px2 + - const: rockchip,rk3066a + + - description: Elgin RV1108 R1 + items: + - const: elgin,rv1108-r1 + - const: rockchip,rv1108 + + - description: Firefly Firefly-RK3288 + items: + - enum: + - firefly,firefly-rk3288 + - firefly,firefly-rk3288-beta + - const: rockchip,rk3288 + + - description: Firefly Firefly-RK3288 Reload + items: + - const: firefly,firefly-rk3288-reload + - const: rockchip,rk3288 + + - description: Firefly Firefly-RK3399 + items: + - const: firefly,firefly-rk3399 + - const: rockchip,rk3399 + + - description: Firefly roc-rk3328-cc + items: + - const: firefly,roc-rk3328-cc + - const: rockchip,rk3328 + + - description: Firefly ROC-RK3399-PC + items: + - const: firefly,roc-rk3399-pc + - const: rockchip,rk3399 + + - description: FriendlyElec NanoPi4 series boards + items: + - enum: + - friendlyarm,nanopc-t4 + - friendlyarm,nanopi-m4 + - const: rockchip,rk3399 + + - description: GeekBuying GeekBox + items: + - const: geekbuying,geekbox + - const: rockchip,rk3368 + + - description: Google Bob (Asus Chromebook Flip C101PA) + items: + - const: google,bob-rev13 + - const: google,bob-rev12 + - const: google,bob-rev11 + - const: google,bob-rev10 + - const: google,bob-rev9 + - const: google,bob-rev8 + - const: google,bob-rev7 + - const: google,bob-rev6 + - const: google,bob-rev5 + - const: google,bob-rev4 + - const: google,bob + - const: google,gru + - const: rockchip,rk3399 + + - description: Google Brain (dev-board) + items: + - const: google,veyron-brain-rev0 + - const: google,veyron-brain + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Gru (dev-board) + items: + - const: google,gru-rev15 + - const: google,gru-rev14 + - const: google,gru-rev13 + - const: google,gru-rev12 + - const: google,gru-rev11 + - const: google,gru-rev10 + - const: google,gru-rev9 + - const: google,gru-rev8 + - const: google,gru-rev7 + - const: google,gru-rev6 + - const: google,gru-rev5 + - const: google,gru-rev4 + - const: google,gru-rev3 + - const: google,gru-rev2 + - const: google,gru + - const: rockchip,rk3399 + + - description: Google Jaq (Haier Chromebook 11 and more) + items: + - const: google,veyron-jaq-rev5 + - const: google,veyron-jaq-rev4 + - const: google,veyron-jaq-rev3 + - const: google,veyron-jaq-rev2 + - const: google,veyron-jaq-rev1 + - const: google,veyron-jaq + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Jerry (Hisense Chromebook C11 and more) + items: + - const: google,veyron-jerry-rev7 + - const: google,veyron-jerry-rev6 + - const: google,veyron-jerry-rev5 + - const: google,veyron-jerry-rev4 + - const: google,veyron-jerry-rev3 + - const: google,veyron-jerry + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Kevin (Samsung Chromebook Plus) + items: + - const: google,kevin-rev15 + - const: google,kevin-rev14 + - const: google,kevin-rev13 + - const: google,kevin-rev12 + - const: google,kevin-rev11 + - const: google,kevin-rev10 + - const: google,kevin-rev9 + - const: google,kevin-rev8 + - const: google,kevin-rev7 + - const: google,kevin-rev6 + - const: google,kevin + - const: google,gru + - const: rockchip,rk3399 + + - description: Google Mickey (Asus Chromebit CS10) + items: + - const: google,veyron-mickey-rev8 + - const: google,veyron-mickey-rev7 + - const: google,veyron-mickey-rev6 + - const: google,veyron-mickey-rev5 + - const: google,veyron-mickey-rev4 + - const: google,veyron-mickey-rev3 + - const: google,veyron-mickey-rev2 + - const: google,veyron-mickey-rev1 + - const: google,veyron-mickey-rev0 + - const: google,veyron-mickey + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Minnie (Asus Chromebook Flip C100P) + items: + - const: google,veyron-minnie-rev4 + - const: google,veyron-minnie-rev3 + - const: google,veyron-minnie-rev2 + - const: google,veyron-minnie-rev1 + - const: google,veyron-minnie-rev0 + - const: google,veyron-minnie + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Pinky (dev-board) + items: + - const: google,veyron-pinky-rev2 + - const: google,veyron-pinky + - const: google,veyron + - const: rockchip,rk3288 + + - description: Google Scarlet - Kingdisplay (Acer Chromebook Tab 10) + items: + - const: google,scarlet-rev15-sku7 + - const: google,scarlet-rev15 + - const: google,scarlet-rev14-sku7 + - const: google,scarlet-rev14 + - const: google,scarlet-rev13-sku7 + - const: google,scarlet-rev13 + - const: google,scarlet-rev12-sku7 + - const: google,scarlet-rev12 + - const: google,scarlet-rev11-sku7 + - const: google,scarlet-rev11 + - const: google,scarlet-rev10-sku7 + - const: google,scarlet-rev10 + - const: google,scarlet-rev9-sku7 + - const: google,scarlet-rev9 + - const: google,scarlet-rev8-sku7 + - const: google,scarlet-rev8 + - const: google,scarlet-rev7-sku7 + - const: google,scarlet-rev7 + - const: google,scarlet-rev6-sku7 + - const: google,scarlet-rev6 + - const: google,scarlet-rev5-sku7 + - const: google,scarlet-rev5 + - const: google,scarlet-rev4-sku7 + - const: google,scarlet-rev4 + - const: google,scarlet-rev3-sku7 + - const: google,scarlet-rev3 + - const: google,scarlet + - const: google,gru + - const: rockchip,rk3399 + + - description: Google Scarlet - Innolux display (Acer Chromebook Tab 10) + items: + - const: google,scarlet-rev15-sku6 + - const: google,scarlet-rev15 + - const: google,scarlet-rev14-sku6 + - const: google,scarlet-rev14 + - const: google,scarlet-rev13-sku6 + - const: google,scarlet-rev13 + - const: google,scarlet-rev12-sku6 + - const: google,scarlet-rev12 + - const: google,scarlet-rev11-sku6 + - const: google,scarlet-rev11 + - const: google,scarlet-rev10-sku6 + - const: google,scarlet-rev10 + - const: google,scarlet-rev9-sku6 + - const: google,scarlet-rev9 + - const: google,scarlet-rev8-sku6 + - const: google,scarlet-rev8 + - const: google,scarlet-rev7-sku6 + - const: google,scarlet-rev7 + - const: google,scarlet-rev6-sku6 + - const: google,scarlet-rev6 + - const: google,scarlet-rev5-sku6 + - const: google,scarlet-rev5 + - const: google,scarlet-rev4-sku6 + - const: google,scarlet-rev4 + - const: google,scarlet + - const: google,gru + - const: rockchip,rk3399 + + - description: Google Speedy (Asus C201 Chromebook) + items: + - const: google,veyron-speedy-rev9 + - const: google,veyron-speedy-rev8 + - const: google,veyron-speedy-rev7 + - const: google,veyron-speedy-rev6 + - const: google,veyron-speedy-rev5 + - const: google,veyron-speedy-rev4 + - const: google,veyron-speedy-rev3 + - const: google,veyron-speedy-rev2 + - const: google,veyron-speedy + - const: google,veyron + - const: rockchip,rk3288 + + - description: Haoyu MarsBoard RK3066 + items: + - const: haoyu,marsboard-rk3066 + - const: rockchip,rk3066a + + - description: mqmaker MiQi + items: + - const: mqmaker,miqi + - const: rockchip,rk3288 + + - description: Netxeon R89 board + items: + - const: netxeon,r89 + - const: rockchip,rk3288 + + - description: Phytec phyCORE-RK3288 Rapid Development Kit + items: + - const: phytec,rk3288-pcm-947 + - const: phytec,rk3288-phycore-som + - const: rockchip,rk3288 + + - description: Pine64 Rock64 + items: + - const: pine64,rock64 + - const: rockchip,rk3328 + + - description: Pine64 RockPro64 + items: + - const: pine64,rockpro64 + - const: rockchip,rk3399 + + - description: Radxa Rock + items: + - const: radxa,rock + - const: rockchip,rk3188 + + - description: Radxa ROCK Pi 4 + items: + - const: radxa,rockpi4 + - const: rockchip,rk3399 + + - description: Radxa Rock2 Square + items: + - const: radxa,rock2-square + - const: rockchip,rk3288 + + - description: Rikomagic MK808 v1 + items: + - const: rikomagic,mk808 + - const: rockchip,rk3066a + + - description: Rockchip Kylin + items: + - const: rockchip,kylin-rk3036 + - const: rockchip,rk3036 + + - description: Rockchip PX3 Evaluation board + items: + - const: rockchip,px3-evb + - const: rockchip,px3 + - const: rockchip,rk3188 + + - description: Rockchip PX30 Evaluation board + items: + - const: rockchip,px30-evb + - const: rockchip,px30 + + - description: Rockchip PX5 Evaluation board + items: + - const: rockchip,px5-evb + - const: rockchip,px5 + - const: rockchip,rk3368 + + - description: Rockchip R88 + items: + - const: rockchip,r88 + - const: rockchip,rk3368 + + - description: Rockchip RK3228 Evaluation board + items: + - const: rockchip,rk3228-evb + - const: rockchip,rk3228 + + - description: Rockchip RK3229 Evaluation board + items: + - const: rockchip,rk3229-evb + - const: rockchip,rk3229 + + - description: Rockchip RK3288 Evaluation board + items: + - enum: + - rockchip,rk3288-evb-act8846 + - rockchip,rk3288-evb-rk808 + - const: rockchip,rk3288 + + - description: Rockchip RK3288 Fennec + items: + - const: rockchip,rk3288-fennec + - const: rockchip,rk3288 + + - description: Rockchip RK3328 Evaluation board + items: + - const: rockchip,rk3328-evb + - const: rockchip,rk3328 + + - description: Rockchip RK3368 Evaluation board (act8846 pmic) + items: + - const: rockchip,rk3368-evb-act8846 + - const: rockchip,rk3368 + + - description: Rockchip RK3399 Evaluation board + items: + - const: rockchip,rk3399-evb + - const: rockchip,rk3399 + + - description: Rockchip RK3399 Sapphire standalone + items: + - const: rockchip,rk3399-sapphire + - const: rockchip,rk3399 + + - description: Rockchip RK3399 Sapphire with Excavator Baseboard + items: + - const: rockchip,rk3399-sapphire-excavator + - const: rockchip,rk3399 + + - description: Rockchip RV1108 Evaluation board + items: + - const: rockchip,rv1108-evb + - const: rockchip,rv1108 + + - description: Theobroma Systems RK3368-uQ7 with Haikou baseboard + items: + - const: tsd,rk3368-uq7-haikou + - const: rockchip,rk3368 + + - description: Theobroma Systems RK3399-Q7 with Haikou baseboard + items: + - const: tsd,rk3399-q7-haikou + - const: rockchip,rk3399 + + - description: Tronsmart Orion R68 Meta + items: + - const: tronsmart,orion-r68-meta + - const: rockchip,rk3368 +... diff --git a/Documentation/devicetree/bindings/arm/scu.txt b/Documentation/devicetree/bindings/arm/scu.txt index 08a587875996..74d0a780ce51 100644 --- a/Documentation/devicetree/bindings/arm/scu.txt +++ b/Documentation/devicetree/bindings/arm/scu.txt @@ -22,7 +22,7 @@ References: Example: -scu@a04100000 { +scu@a0410000 { compatible = "arm,cortex-a9-scu"; reg = <0xa0410000 0x100>; }; diff --git a/Documentation/devicetree/bindings/arm/secure.txt b/Documentation/devicetree/bindings/arm/secure.txt index e31303fb233a..f27bbff2c780 100644 --- a/Documentation/devicetree/bindings/arm/secure.txt +++ b/Documentation/devicetree/bindings/arm/secure.txt @@ -32,7 +32,8 @@ describe the view of Secure world using the standard bindings. These secure- bindings only need to be used where both the Secure and Normal world views need to be described in a single device tree. -Valid Secure world properties: +Valid Secure world properties +----------------------------- - secure-status : specifies whether the device is present and usable in the secure world. The combination of this with "status" allows @@ -51,3 +52,19 @@ Valid Secure world properties: status = "disabled"; secure-status = "okay"; /* S-only */ status = "disabled"; /* disabled in both */ status = "disabled"; secure-status = "disabled"; /* disabled in both */ + +The secure-chosen node +---------------------- + +Similar to the /chosen node which serves as a place for passing data +between firmware and the operating system, the /secure-chosen node may +be used to pass data to the Secure OS. Only the properties defined +below may appear in the /secure-chosen node. + +- stdout-path : specifies the device to be used by the Secure OS for + its console output. The syntax is the same as for /chosen/stdout-path. + If the /secure-chosen node exists but the stdout-path property is not + present, the Secure OS should not perform any console output. If + /secure-chosen does not exist, the Secure OS should use the value of + /chosen/stdout-path instead (that is, use the same device as the + Normal world OS). diff --git a/Documentation/devicetree/bindings/arm/shmobile.txt b/Documentation/devicetree/bindings/arm/shmobile.txt deleted file mode 100644 index 89b4a389fbc7..000000000000 --- a/Documentation/devicetree/bindings/arm/shmobile.txt +++ /dev/null @@ -1,161 +0,0 @@ -Renesas SH-Mobile, R-Mobile, and R-Car Platform Device Tree Bindings --------------------------------------------------------------------- - -SoCs: - - - Emma Mobile EV2 - compatible = "renesas,emev2" - - RZ/A1H (R7S72100) - compatible = "renesas,r7s72100" - - SH-Mobile AG5 (R8A73A00/SH73A0) - compatible = "renesas,sh73a0" - - R-Mobile APE6 (R8A73A40) - compatible = "renesas,r8a73a4" - - R-Mobile A1 (R8A77400) - compatible = "renesas,r8a7740" - - RZ/G1H (R8A77420) - compatible = "renesas,r8a7742" - - RZ/G1M (R8A77430) - compatible = "renesas,r8a7743" - - RZ/G1N (R8A77440) - compatible = "renesas,r8a7744" - - RZ/G1E (R8A77450) - compatible = "renesas,r8a7745" - - RZ/G1C (R8A77470) - compatible = "renesas,r8a77470" - - R-Car M1A (R8A77781) - compatible = "renesas,r8a7778" - - R-Car H1 (R8A77790) - compatible = "renesas,r8a7779" - - R-Car H2 (R8A77900) - compatible = "renesas,r8a7790" - - R-Car M2-W (R8A77910) - compatible = "renesas,r8a7791" - - R-Car V2H (R8A77920) - compatible = "renesas,r8a7792" - - R-Car M2-N (R8A77930) - compatible = "renesas,r8a7793" - - R-Car E2 (R8A77940) - compatible = "renesas,r8a7794" - - R-Car H3 (R8A77950) - compatible = "renesas,r8a7795" - - R-Car M3-W (R8A77960) - compatible = "renesas,r8a7796" - - R-Car M3-N (R8A77965) - compatible = "renesas,r8a77965" - - R-Car V3M (R8A77970) - compatible = "renesas,r8a77970" - - R-Car V3H (R8A77980) - compatible = "renesas,r8a77980" - - R-Car E3 (R8A77990) - compatible = "renesas,r8a77990" - - R-Car D3 (R8A77995) - compatible = "renesas,r8a77995" - - RZ/N1D (R9A06G032) - compatible = "renesas,r9a06g032" - -Boards: - - - Alt (RTP0RC7794SEB00010S) - compatible = "renesas,alt", "renesas,r8a7794" - - APE6-EVM - compatible = "renesas,ape6evm", "renesas,r8a73a4" - - Atmark Techno Armadillo-800 EVA - compatible = "renesas,armadillo800eva", "renesas,r8a7740" - - Blanche (RTP0RC7792SEB00010S) - compatible = "renesas,blanche", "renesas,r8a7792" - - BOCK-W - compatible = "renesas,bockw", "renesas,r8a7778" - - Condor (RTP0RC77980SEB0010SS/RTP0RC77980SEB0010SA01) - compatible = "renesas,condor", "renesas,r8a77980" - - Draak (RTP0RC77995SEB0010S) - compatible = "renesas,draak", "renesas,r8a77995" - - Eagle (RTP0RC77970SEB0010S) - compatible = "renesas,eagle", "renesas,r8a77970" - - Ebisu (RTP0RC77990SEB0010S) - compatible = "renesas,ebisu", "renesas,r8a77990" - - Genmai (RTK772100BC00000BR) - compatible = "renesas,genmai", "renesas,r7s72100" - - GR-Peach (X28A-M01-E/F) - compatible = "renesas,gr-peach", "renesas,r7s72100" - - Gose (RTP0RC7793SEB00010S) - compatible = "renesas,gose", "renesas,r8a7793" - - H3ULCB (R-Car Starter Kit Premier, RTP0RC7795SKBX0010SA00 (H3 ES1.1)) - H3ULCB (R-Car Starter Kit Premier, RTP0RC77951SKBX010SA00 (H3 ES2.0)) - compatible = "renesas,h3ulcb", "renesas,r8a7795" - - Henninger - compatible = "renesas,henninger", "renesas,r8a7791" - - iWave Systems RZ/G1C Single Board Computer (iW-RainboW-G23S) - compatible = "iwave,g23s", "renesas,r8a77470" - - iWave Systems RZ/G1E SODIMM SOM Development Platform (iW-RainboW-G22D) - compatible = "iwave,g22d", "iwave,g22m", "renesas,r8a7745" - - iWave Systems RZ/G1E SODIMM System On Module (iW-RainboW-G22M-SM) - compatible = "iwave,g22m", "renesas,r8a7745" - - iWave Systems RZ/G1M Qseven Development Platform (iW-RainboW-G20D-Qseven) - compatible = "iwave,g20d", "iwave,g20m", "renesas,r8a7743" - - iWave Systems RZ/G1M Qseven System On Module (iW-RainboW-G20M-Qseven) - compatible = "iwave,g20m", "renesas,r8a7743" - - Kingfisher (SBEV-RCAR-KF-M03) - compatible = "shimafuji,kingfisher" - - Koelsch (RTP0RC7791SEB00010S) - compatible = "renesas,koelsch", "renesas,r8a7791" - - Kyoto Microcomputer Co. KZM-A9-Dual - compatible = "renesas,kzm9d", "renesas,emev2" - - Kyoto Microcomputer Co. KZM-A9-GT - compatible = "renesas,kzm9g", "renesas,sh73a0" - - Lager (RTP0RC7790SEB00010S) - compatible = "renesas,lager", "renesas,r8a7790" - - M3ULCB (R-Car Starter Kit Pro, RTP0RC7796SKBX0010SA09 (M3 ES1.0)) - compatible = "renesas,m3ulcb", "renesas,r8a7796" - - Marzen (R0P7779A00010S) - compatible = "renesas,marzen", "renesas,r8a7779" - - Porter (M2-LCDP) - compatible = "renesas,porter", "renesas,r8a7791" - - RSKRZA1 (YR0K77210C000BE) - compatible = "renesas,rskrza1", "renesas,r7s72100" - - RZN1D-DB (RZ/N1D Demo Board for the RZ/N1D 400 pins package) - compatible = "renesas,rzn1d400-db", "renesas,r9a06g032" - - Salvator-X (RTP0RC7795SIPB0010S) - compatible = "renesas,salvator-x", "renesas,r8a7795" - - Salvator-X (RTP0RC7796SIPB0011S) - compatible = "renesas,salvator-x", "renesas,r8a7796" - - Salvator-X (RTP0RC7796SIPB0011S (M3-N)) - compatible = "renesas,salvator-x", "renesas,r8a77965" - - Salvator-XS (Salvator-X 2nd version, RTP0RC7795SIPB0012S) - compatible = "renesas,salvator-xs", "renesas,r8a7795" - - Salvator-XS (Salvator-X 2nd version, RTP0RC7796SIPB0012S) - compatible = "renesas,salvator-xs", "renesas,r8a7796" - - Salvator-XS (Salvator-X 2nd version, RTP0RC77965SIPB012S) - compatible = "renesas,salvator-xs", "renesas,r8a77965" - - SILK (RTP0RC7794LCB00011S) - compatible = "renesas,silk", "renesas,r8a7794" - - SK-RZG1E (YR8A77450S000BE) - compatible = "renesas,sk-rzg1e", "renesas,r8a7745" - - SK-RZG1M (YR8A77430S000BE) - compatible = "renesas,sk-rzg1m", "renesas,r8a7743" - - Stout (ADAS Starterkit, Y-R-CAR-ADAS-SKH2-BOARD) - compatible = "renesas,stout", "renesas,r8a7790" - - V3HSK (Y-ASK-RCAR-V3H-WS10) - compatible = "renesas,v3hsk", "renesas,r8a77980" - - V3MSK (Y-ASK-RCAR-V3M-WS10) - compatible = "renesas,v3msk", "renesas,r8a77970" - - Wheat (RTP0RC7792ASKB0000JE) - compatible = "renesas,wheat", "renesas,r8a7792" - - -Most Renesas ARM SoCs have a Product Register that allows to retrieve SoC -product and revision information. If present, a device node for this register -should be added. - -Required properties: - - compatible: Must be "renesas,prr". - - reg: Base address and length of the register block. - - -Examples --------- - - prr: chipid@ff000044 { - compatible = "renesas,prr"; - reg = <0 0xff000044 0 4>; - }; diff --git a/Documentation/devicetree/bindings/arm/sirf.txt b/Documentation/devicetree/bindings/arm/sirf.txt deleted file mode 100644 index 7b28ee6fee91..000000000000 --- a/Documentation/devicetree/bindings/arm/sirf.txt +++ /dev/null @@ -1,11 +0,0 @@ -CSR SiRFprimaII and SiRFmarco device tree bindings. -======================================== - -Required root node properties: - - compatible: - - "sirf,atlas6-cb" : atlas6 "cb" evaluation board - - "sirf,atlas6" : atlas6 device based board - - "sirf,atlas7-cb" : atlas7 "cb" evaluation board - - "sirf,atlas7" : atlas7 device based board - - "sirf,prima2-cb" : prima2 "cb" evaluation board - - "sirf,prima2" : prima2 device based board diff --git a/Documentation/devicetree/bindings/arm/sirf.yaml b/Documentation/devicetree/bindings/arm/sirf.yaml new file mode 100644 index 000000000000..0b597032c923 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sirf.yaml @@ -0,0 +1,27 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/sirf.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: CSR SiRFprimaII and SiRFmarco device tree bindings. + +maintainers: + - Binghua Duan <binghua.duan@csr.com> + - Barry Song <Baohua.Song@csr.com> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - const: sirf,atlas6-cb + - const: sirf,atlas6 + - items: + - const: sirf,atlas7-cb + - const: sirf,atlas7 + - items: + - const: sirf,prima2-cb + - const: sirf,prima2 +... diff --git a/Documentation/devicetree/bindings/arm/uniphier/cache-uniphier.txt b/Documentation/devicetree/bindings/arm/socionext/cache-uniphier.txt index d27a646f48a9..d27a646f48a9 100644 --- a/Documentation/devicetree/bindings/arm/uniphier/cache-uniphier.txt +++ b/Documentation/devicetree/bindings/arm/socionext/cache-uniphier.txt diff --git a/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml b/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml new file mode 100644 index 000000000000..aae53fc3cb1e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/socionext/milbeaut.yaml @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/milbeaut.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Milbeaut platforms device tree bindings + +maintainers: + - Taichi Sugaya <sugaya.taichi@socionext.com> + - Takao Orito <orito.takao@socionext.com> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - socionext,milbeaut-m10v-evb + - const: socionext,sc2000a +... diff --git a/Documentation/devicetree/bindings/arm/socionext/uniphier.txt b/Documentation/devicetree/bindings/arm/socionext/uniphier.txt new file mode 100644 index 000000000000..b3ed1033740e --- /dev/null +++ b/Documentation/devicetree/bindings/arm/socionext/uniphier.txt @@ -0,0 +1,47 @@ +Socionext UniPhier SoC family +----------------------------- + +Required properties in the root node: + - compatible: should contain board and SoC compatible strings + +SoC and board compatible strings: + (sorted chronologically) + + - LD4 SoC: "socionext,uniphier-ld4" + - Reference Board: "socionext,uniphier-ld4-ref" + + - Pro4 SoC: "socionext,uniphier-pro4" + - Reference Board: "socionext,uniphier-pro4-ref" + - Ace Board: "socionext,uniphier-pro4-ace" + - Sanji Board: "socionext,uniphier-pro4-sanji" + + - sLD8 SoC: "socionext,uniphier-sld8" + - Reference Board: "socionext,uniphier-sld8-ref" + + - PXs2 SoC: "socionext,uniphier-pxs2" + - Gentil Board: "socionext,uniphier-pxs2-gentil" + - Vodka Board: "socionext,uniphier-pxs2-vodka" + + - LD6b SoC: "socionext,uniphier-ld6b" + - Reference Board: "socionext,uniphier-ld6b-ref" + + - LD11 SoC: "socionext,uniphier-ld11" + - Reference Board: "socionext,uniphier-ld11-ref" + - Global Board: "socionext,uniphier-ld11-global" + + - LD20 SoC: "socionext,uniphier-ld20" + - Reference Board: "socionext,uniphier-ld20-ref" + - Global Board: "socionext,uniphier-ld20-global" + + - PXs3 SoC: "socionext,uniphier-pxs3" + - Reference Board: "socionext,uniphier-pxs3-ref" + +Example: + +/dts-v1/; + +/ { + compatible = "socionext,uniphier-ld20-ref", "socionext,uniphier-ld20"; + + ... +}; diff --git a/Documentation/devicetree/bindings/arm/sp810.txt b/Documentation/devicetree/bindings/arm/sp810.txt index 1b2ab1ff5587..46652bf65147 100644 --- a/Documentation/devicetree/bindings/arm/sp810.txt +++ b/Documentation/devicetree/bindings/arm/sp810.txt @@ -4,7 +4,7 @@ SP810 System Controller Required properties: - compatible: standard compatible string for a Primecell peripheral, - see Documentation/devicetree/bindings/arm/primecell.txt + see Documentation/devicetree/bindings/arm/primecell.yaml for more details should be: "arm,sp810", "arm,primecell" diff --git a/Documentation/devicetree/bindings/arm/spear.txt b/Documentation/devicetree/bindings/arm/spear.txt deleted file mode 100644 index 0d42949df6c2..000000000000 --- a/Documentation/devicetree/bindings/arm/spear.txt +++ /dev/null @@ -1,26 +0,0 @@ -ST SPEAr Platforms Device Tree Bindings ---------------------------------------- - -Boards with the ST SPEAr600 SoC shall have the following properties: -Required root node property: -compatible = "st,spear600"; - -Boards with the ST SPEAr300 SoC shall have the following properties: -Required root node property: -compatible = "st,spear300"; - -Boards with the ST SPEAr310 SoC shall have the following properties: -Required root node property: -compatible = "st,spear310"; - -Boards with the ST SPEAr320 SoC shall have the following properties: -Required root node property: -compatible = "st,spear320"; - -Boards with the ST SPEAr1310 SoC shall have the following properties: -Required root node property: -compatible = "st,spear1310"; - -Boards with the ST SPEAr1340 SoC shall have the following properties: -Required root node property: -compatible = "st,spear1340"; diff --git a/Documentation/devicetree/bindings/arm/spear.yaml b/Documentation/devicetree/bindings/arm/spear.yaml new file mode 100644 index 000000000000..f6ec731c9531 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/spear.yaml @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/spear.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ST SPEAr Platforms Device Tree Bindings + +maintainers: + - Viresh Kumar <vireshk@kernel.org> + - Stefan Roese <sr@denx.de> + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - st,spear600 + - st,spear300 + - st,spear310 + - st,spear320 + - st,spear1310 + - st,spear1340 +... diff --git a/Documentation/devicetree/bindings/arm/sti.txt b/Documentation/devicetree/bindings/arm/sti.txt deleted file mode 100644 index 8d27f6b084c7..000000000000 --- a/Documentation/devicetree/bindings/arm/sti.txt +++ /dev/null @@ -1,23 +0,0 @@ -ST STi Platforms Device Tree Bindings ---------------------------------------- - -Boards with the ST STiH415 SoC shall have the following properties: -Required root node property: -compatible = "st,stih415"; - -Boards with the ST STiH416 SoC shall have the following properties: -Required root node property: -compatible = "st,stih416"; - -Boards with the ST STiH407 SoC shall have the following properties: -Required root node property: -compatible = "st,stih407"; - -Boards with the ST STiH410 SoC shall have the following properties: -Required root node property: -compatible = "st,stih410"; - -Boards with the ST STiH418 SoC shall have the following properties: -Required root node property: -compatible = "st,stih418"; - diff --git a/Documentation/devicetree/bindings/arm/sti.yaml b/Documentation/devicetree/bindings/arm/sti.yaml new file mode 100644 index 000000000000..47f9b8eebaa0 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/sti.yaml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/sti.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ST STi Platforms Device Tree Bindings + +maintainers: + - Patrice Chotard <patrice.chotard@st.com> + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - st,stih415 + - st,stih416 + - st,stih407 + - st,stih410 + - st,stih418 +... diff --git a/Documentation/devicetree/bindings/arm/sunxi.txt b/Documentation/devicetree/bindings/arm/sunxi.txt index e4beec3d9ad3..9254cbe7d516 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.txt +++ b/Documentation/devicetree/bindings/arm/sunxi.txt @@ -14,8 +14,10 @@ using one of the following compatible strings: allwinner,sun8i-a83t allwinner,sun8i-h2-plus allwinner,sun8i-h3 - allwinner-sun8i-r40 + allwinner,sun8i-r40 + allwinner,sun8i-t3 allwinner,sun8i-v3s allwinner,sun9i-a80 allwinner,sun50i-a64 + allwinner,suniv-f1c100s nextthing,gr8 diff --git a/Documentation/devicetree/bindings/arm/marvell/marvell,berlin.txt b/Documentation/devicetree/bindings/arm/syna.txt index 3bab18409b7a..2face46a5f64 100644 --- a/Documentation/devicetree/bindings/arm/marvell/marvell,berlin.txt +++ b/Documentation/devicetree/bindings/arm/syna.txt @@ -1,4 +1,9 @@ -Marvell Berlin SoC Family Device Tree Bindings +Synaptics SoC Device Tree Bindings + +According to https://www.synaptics.com/company/news/conexant-marvell +Synaptics has acquired the Multimedia Solutions Business of Marvell, so +berlin SoCs are now Synaptics' SoCs now. + --------------------------------------------------------------- Work in progress statement: @@ -13,6 +18,10 @@ stable binding/ABI. --------------------------------------------------------------- +Boards with the Synaptics AS370 SoC shall have the following properties: + Required root node property: + compatible: "syna,as370" + Boards with a SoC of the Marvell Berlin family, e.g. Armada 1500 shall have the following properties: diff --git a/Documentation/devicetree/bindings/arm/technologic.txt b/Documentation/devicetree/bindings/arm/technologic.txt deleted file mode 100644 index f1cedc00dcab..000000000000 --- a/Documentation/devicetree/bindings/arm/technologic.txt +++ /dev/null @@ -1,23 +0,0 @@ -Technologic Systems Platforms Device Tree Bindings --------------------------------------------------- - -TS-4600 is a System-on-Module based on the Freescale i.MX28 System-on-Chip. -It can be mounted on a carrier board providing additional peripheral connectors. -Required root node properties: - - compatible = "technologic,imx28-ts4600", "fsl,imx28" - -TS-4800 board -Required root node properties: - - compatible = "technologic,imx51-ts4800", "fsl,imx51"; - -TS-4900 is a System-on-Module based on the Freescale i.MX6 System-on-Chip. -It can be mounted on a carrier board providing additional peripheral connectors. -Required root node properties: - - compatible = "technologic,imx6dl-ts4900", "fsl,imx6dl" - - compatible = "technologic,imx6q-ts4900", "fsl,imx6q" - -TS-7970 is a System-on-Module based on the Freescale i.MX6 System-on-Chip. -It can be mounted on a carrier board providing additional peripheral connectors. -Required root node properties: - - compatible = "technologic,imx6dl-ts7970", "fsl,imx6dl" - - compatible = "technologic,imx6q-ts7970", "fsl,imx6q" diff --git a/Documentation/devicetree/bindings/arm/tegra.txt b/Documentation/devicetree/bindings/arm/tegra.txt deleted file mode 100644 index 32f62bb7006d..000000000000 --- a/Documentation/devicetree/bindings/arm/tegra.txt +++ /dev/null @@ -1,60 +0,0 @@ -NVIDIA Tegra device tree bindings -------------------------------------------- - -SoCs -------------------------------------------- - -Each device tree must specify which Tegra SoC it uses, using one of the -following compatible values: - - nvidia,tegra20 - nvidia,tegra30 - nvidia,tegra114 - nvidia,tegra124 - nvidia,tegra132 - nvidia,tegra210 - nvidia,tegra186 - nvidia,tegra194 - -Boards -------------------------------------------- - -Each device tree must specify which one or more of the following -board-specific compatible values: - - ad,medcom-wide - ad,plutux - ad,tamonten - ad,tec - compal,paz00 - compulab,trimslice - nvidia,beaver - nvidia,cardhu - nvidia,cardhu-a02 - nvidia,cardhu-a04 - nvidia,dalmore - nvidia,harmony - nvidia,jetson-tk1 - nvidia,norrin - nvidia,p2371-0000 - nvidia,p2371-2180 - nvidia,p2571 - nvidia,p2771-0000 - nvidia,p2972-0000 - nvidia,roth - nvidia,seaboard - nvidia,tn7 - nvidia,ventana - toradex,apalis_t30 - toradex,apalis_t30-eval - toradex,apalis-tk1 - toradex,apalis-tk1-eval - toradex,colibri_t20-512 - toradex,colibri_t30 - toradex,colibri_t30-eval-v3 - toradex,iris - -Trusted Foundations -------------------------------------------- -Tegra supports the Trusted Foundation secure monitor. See the -"tlm,trusted-foundations" binding's documentation for more details. diff --git a/Documentation/devicetree/bindings/arm/tegra.yaml b/Documentation/devicetree/bindings/arm/tegra.yaml new file mode 100644 index 000000000000..60b38eb5c61a --- /dev/null +++ b/Documentation/devicetree/bindings/arm/tegra.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/tegra.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: NVIDIA Tegra device tree bindings + +maintainers: + - Thierry Reding <thierry.reding@gmail.com> + - Jonathan Hunter <jonathanh@nvidia.com> + +properties: + compatible: + oneOf: + - items: + - enum: + - compal,paz00 + - compulab,trimslice + - nvidia,harmony + - nvidia,seaboard + - nvidia,ventana + - const: nvidia,tegra20 + - items: + - enum: + - ad,medcom-wide + - ad,plutux + - ad,tec + - const: ad,tamonten + - const: nvidia,tegra20 + - items: + - enum: + - toradex,colibri_t20-eval-v3 + - toradex,colibri_t20-iris + - const: toradex,colibri_t20 + - const: nvidia,tegra20 + - items: + - enum: + - nvidia,beaver + - const: nvidia,tegra30 + - items: + - enum: + - nvidia,cardhu-a02 + - nvidia,cardhu-a04 + - const: nvidia,cardhu + - const: nvidia,tegra30 + - items: + - const: toradex,apalis_t30-eval + - const: toradex,apalis_t30 + - const: nvidia,tegra30 + - items: + - const: toradex,apalis_t30-eval-v1.1 + - const: toradex,apalis_t30-eval + - const: toradex,apalis_t30-v1.1 + - const: toradex,apalis_t30 + - const: nvidia,tegra30 + - items: + - enum: + - toradex,colibri_t30-eval-v3 + - const: toradex,colibri_t30 + - const: nvidia,tegra30 + - items: + - enum: + - nvidia,dalmore + - nvidia,roth + - nvidia,tn7 + - const: nvidia,tegra114 + - items: + - enum: + - nvidia,jetson-tk1 + - nvidia,venice2 + - const: nvidia,tegra124 + - items: + - const: toradex,apalis-tk1-eval + - const: toradex,apalis-tk1 + - const: nvidia,tegra124 + - items: + - const: toradex,apalis-tk1-v1.2-eval + - const: toradex,apalis-tk1-eval + - const: toradex,apalis-tk1-v1.2 + - const: toradex,apalis-tk1 + - const: nvidia,tegra124 + - items: + - enum: + - nvidia,norrin + - const: nvidia,tegra132 + - const: nvidia,tegra124 + - items: + - enum: + - nvidia,darcy + - nvidia,p2371-0000 + - nvidia,p2371-2180 + - nvidia,p2571 + - nvidia,p2894-0050-a08 + - const: nvidia,tegra210 + - items: + - enum: + - nvidia,p2771-0000 + - const: nvidia,tegra186 + - items: + - enum: + - nvidia,p2972-0000 + - const: nvidia,tegra194 diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt index 5a3bf7c5a7a0..2d89cdc39eb0 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.txt @@ -15,6 +15,9 @@ Required properties: Optional properties: - nvidia,invert-interrupt: If present, inverts the PMU interrupt signal. +- interrupt-controller: Identifies the node as an interrupt controller. +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source. The value must be 2. Example: @@ -34,3 +37,96 @@ Board DTS: pmc@c360000 { nvidia,invert-interrupt; }; + +== Pad Control == + +On Tegra SoCs a pad is a set of pins which are configured as a group. +The pin grouping is a fixed attribute of the hardware. The PMC can be +used to set pad power state and signaling voltage. A pad can be either +in active or power down mode. The support for power state and signaling +voltage configuration varies depending on the pad in question. 3.3 V and +1.8 V signaling voltages are supported on pins where software +controllable signaling voltage switching is available. + +Pad configurations are described with pin configuration nodes which +are placed under the pmc node and they are referred to by the pinctrl +client properties. For more information see +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt. + +The following pads are present on Tegra186: +csia csib dsi mipi-bias +pex-clk-bias pex-clk3 pex-clk2 pex-clk1 +usb0 usb1 usb2 usb-bias +uart audio hsic dbg +hdmi-dp0 hdmi-dp1 pex-cntrl sdmmc2-hv +sdmmc4 cam dsib dsic +dsid csic csid csie +dsif spi ufs dmic-hv +edp sdmmc1-hv sdmmc3-hv conn +audio-hv ao-hv + +Required pin configuration properties: + - pins: A list of strings, each of which contains the name of a pad + to be configured. + +Optional pin configuration properties: + - low-power-enable: Configure the pad into power down mode + - low-power-disable: Configure the pad into active mode + - power-source: Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 or + TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. + The values are defined in + include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h. + +Note: The power state can be configured on all of the above pads except + for ao-hv. Following pads have software configurable signaling + voltages: sdmmc2-hv, dmic-hv, sdmmc1-hv, sdmmc3-hv, audio-hv, + ao-hv. + +Pad configuration state example: + pmc: pmc@7000e400 { + compatible = "nvidia,tegra186-pmc"; + reg = <0 0x0c360000 0 0x10000>, + <0 0x0c370000 0 0x10000>, + <0 0x0c380000 0 0x10000>, + <0 0x0c390000 0 0x10000>; + reg-names = "pmc", "wake", "aotag", "scratch"; + + ... + + sdmmc1_3v3: sdmmc1-3v3 { + pins = "sdmmc1-hv"; + power-source = <TEGRA_IO_PAD_VOLTAGE_3V3>; + }; + + sdmmc1_1v8: sdmmc1-1v8 { + pins = "sdmmc1-hv"; + power-source = <TEGRA_IO_PAD_VOLTAGE_1V8>; + }; + + hdmi_off: hdmi-off { + pins = "hdmi"; + low-power-enable; + } + + hdmi_on: hdmi-on { + pins = "hdmi"; + low-power-disable; + } + }; + +Pinctrl client example: + sdmmc1: sdhci@3400000 { + ... + pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; + pinctrl-0 = <&sdmmc1_3v3>; + pinctrl-1 = <&sdmmc1_1v8>; + }; + + ... + + sor0: sor@15540000 { + ... + pinctrl-0 = <&hdmi_off>; + pinctrl-1 = <&hdmi_on>; + pinctrl-names = "hdmi-on", "hdmi-off"; + }; diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt index a74b37b07e5c..cb12f33a247f 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-pmc.txt @@ -195,3 +195,106 @@ Example: power-domains = <&pd_audio>; ... }; + +== Pad Control == + +On Tegra SoCs a pad is a set of pins which are configured as a group. +The pin grouping is a fixed attribute of the hardware. The PMC can be +used to set pad power state and signaling voltage. A pad can be either +in active or power down mode. The support for power state and signaling +voltage configuration varies depending on the pad in question. 3.3 V and +1.8 V signaling voltages are supported on pins where software +controllable signaling voltage switching is available. + +The pad configuration state nodes are placed under the pmc node and they +are referred to by the pinctrl client properties. For more information +see Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt. +The pad name should be used as the value of the pins property in pin +configuration nodes. + +The following pads are present on Tegra124 and Tegra132: +audio bb cam comp +csia csb cse dsi +dsib dsic dsid hdmi +hsic hv lvds mipi-bias +nand pex-bias pex-clk1 pex-clk2 +pex-cntrl sdmmc1 sdmmc3 sdmmc4 +sys_ddc uart usb0 usb1 +usb2 usb_bias + +The following pads are present on Tegra210: +audio audio-hv cam csia +csib csic csid csie +csif dbg debug-nonao dmic +dp dsi dsib dsic +dsid emmc emmc2 gpio +hdmi hsic lvds mipi-bias +pex-bias pex-clk1 pex-clk2 pex-cntrl +sdmmc1 sdmmc3 spi spi-hv +uart usb0 usb1 usb2 +usb3 usb-bias + +Required pin configuration properties: + - pins: Must contain name of the pad(s) to be configured. + +Optional pin configuration properties: + - low-power-enable: Configure the pad into power down mode + - low-power-disable: Configure the pad into active mode + - power-source: Must contain either TEGRA_IO_PAD_VOLTAGE_1V8 + or TEGRA_IO_PAD_VOLTAGE_3V3 to select between signaling voltages. + The values are defined in + include/dt-bindings/pinctrl/pinctrl-tegra-io-pad.h. + +Note: The power state can be configured on all of the Tegra124 and + Tegra132 pads. None of the Tegra124 or Tegra132 pads support + signaling voltage switching. + +Note: All of the listed Tegra210 pads except pex-cntrl support power + state configuration. Signaling voltage switching is supported on + following Tegra210 pads: audio, audio-hv, cam, dbg, dmic, gpio, + pex-cntrl, sdmmc1, sdmmc3, spi, spi-hv, and uart. + +Pad configuration state example: + pmc: pmc@7000e400 { + compatible = "nvidia,tegra210-pmc"; + reg = <0x0 0x7000e400 0x0 0x400>; + clocks = <&tegra_car TEGRA210_CLK_PCLK>, <&clk32k_in>; + clock-names = "pclk", "clk32k_in"; + + ... + + sdmmc1_3v3: sdmmc1-3v3 { + pins = "sdmmc1"; + power-source = <TEGRA_IO_PAD_VOLTAGE_3V3>; + }; + + sdmmc1_1v8: sdmmc1-1v8 { + pins = "sdmmc1"; + power-source = <TEGRA_IO_PAD_VOLTAGE_1V8>; + }; + + hdmi_off: hdmi-off { + pins = "hdmi"; + low-power-enable; + } + + hdmi_on: hdmi-on { + pins = "hdmi"; + low-power-disable; + } + }; + +Pinctrl client example: + sdmmc1: sdhci@700b0000 { + ... + pinctrl-names = "sdmmc-3v3", "sdmmc-1v8"; + pinctrl-0 = <&sdmmc1_3v3>; + pinctrl-1 = <&sdmmc1_1v8>; + }; + ... + sor@54540000 { + ... + pinctrl-0 = <&hdmi_off>; + pinctrl-1 = <&hdmi_on>; + pinctrl-names = "hdmi-on", "hdmi-off"; + }; diff --git a/Documentation/devicetree/bindings/arm/ti/nspire.yaml b/Documentation/devicetree/bindings/arm/ti/nspire.yaml new file mode 100644 index 000000000000..e372b43da62f --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ti/nspire.yaml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/ti/nspire.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI-NSPIRE calculators + +maintainers: + - Daniel Tang <dt.tangr@gmail.com> + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + # CX models + - ti,nspire-cx + # Touchpad models + - ti,nspire-tp + # Clickpad models + - ti,nspire-clp +... diff --git a/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml b/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml new file mode 100644 index 000000000000..4326d2cfa15d --- /dev/null +++ b/Documentation/devicetree/bindings/arm/ti/ti,davinci.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/ti/davinci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments DaVinci Platforms Device Tree Bindings + +maintainers: + - Sekhar Nori <nsekhar@ti.com> + +description: + DA850/OMAP-L138/AM18x based boards + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - ti,da850-evm # DA850/OMAP-L138/AM18x Evaluation Module (EVM) board + - ti,da850-lcdk # DA850/OMAP-L138/AM18x L138/C6748 Development Kit (LCDK) board + - enbw,cmc # EnBW AM1808 based CMC board + - lego,ev3 # LEGO MINDSTORMS EV3 (AM1808 based) + - const: ti,da850 +... diff --git a/Documentation/devicetree/bindings/arm/topology.txt b/Documentation/devicetree/bindings/arm/topology.txt index de9eb0486630..b0d80c0fb265 100644 --- a/Documentation/devicetree/bindings/arm/topology.txt +++ b/Documentation/devicetree/bindings/arm/topology.txt @@ -472,4 +472,4 @@ cpus { =============================================================================== [1] ARM Linux kernel documentation - Documentation/devicetree/bindings/arm/cpus.txt + Documentation/devicetree/bindings/arm/cpus.yaml diff --git a/Documentation/devicetree/bindings/arm/ux500/boards.txt b/Documentation/devicetree/bindings/arm/ux500/boards.txt index 0fa429534f49..89408de55bfd 100644 --- a/Documentation/devicetree/bindings/arm/ux500/boards.txt +++ b/Documentation/devicetree/bindings/arm/ux500/boards.txt @@ -60,7 +60,7 @@ Example: <0xa0410100 0x100>; }; - scu@a04100000 { + scu@a0410000 { compatible = "arm,cortex-a9-scu"; reg = <0xa0410000 0x100>; }; diff --git a/Documentation/devicetree/bindings/arm/vt8500.txt b/Documentation/devicetree/bindings/arm/vt8500.txt deleted file mode 100644 index 87dc1ddf4770..000000000000 --- a/Documentation/devicetree/bindings/arm/vt8500.txt +++ /dev/null @@ -1,22 +0,0 @@ -VIA/Wondermedia VT8500 Platforms Device Tree Bindings ---------------------------------------- - -Boards with the VIA VT8500 SoC shall have the following properties: -Required root node property: -compatible = "via,vt8500"; - -Boards with the Wondermedia WM8505 SoC shall have the following properties: -Required root node property: -compatible = "wm,wm8505"; - -Boards with the Wondermedia WM8650 SoC shall have the following properties: -Required root node property: -compatible = "wm,wm8650"; - -Boards with the Wondermedia WM8750 SoC shall have the following properties: -Required root node property: -compatible = "wm,wm8750"; - -Boards with the Wondermedia WM8850 SoC shall have the following properties: -Required root node property: -compatible = "wm,wm8850"; diff --git a/Documentation/devicetree/bindings/arm/vt8500.yaml b/Documentation/devicetree/bindings/arm/vt8500.yaml new file mode 100644 index 000000000000..7b25b6fa34e9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/vt8500.yaml @@ -0,0 +1,23 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/vt8500.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: VIA/Wondermedia VT8500 Platforms Device Tree Bindings + +maintainers: + - Tony Prisk <linux@prisktech.co.nz> +description: test + +properties: + $nodename: + const: '/' + compatible: + items: + - enum: + - via,vt8500 + - wm,wm8505 + - wm,wm8650 + - wm,wm8750 + - wm,wm8850 diff --git a/Documentation/devicetree/bindings/arm/xilinx.txt b/Documentation/devicetree/bindings/arm/xilinx.txt deleted file mode 100644 index 26fe5ecc4332..000000000000 --- a/Documentation/devicetree/bindings/arm/xilinx.txt +++ /dev/null @@ -1,83 +0,0 @@ -Xilinx Zynq Platforms Device Tree Bindings - -Boards with Zynq-7000 SOC based on an ARM Cortex A9 processor -shall have the following properties. - -Required root node properties: - - compatible = "xlnx,zynq-7000"; - -Additional compatible strings: - -- Adapteva Parallella board - "adapteva,parallella" - -- Avnet MicroZed board - "avnet,zynq-microzed" - "xlnx,zynq-microzed" - -- Avnet ZedBoard board - "avnet,zynq-zed" - "xlnx,zynq-zed" - -- Digilent Zybo board - "digilent,zynq-zybo" - -- Digilent Zybo Z7 board - "digilent,zynq-zybo-z7" - -- Xilinx CC108 internal board - "xlnx,zynq-cc108" - -- Xilinx ZC702 internal board - "xlnx,zynq-zc702" - -- Xilinx ZC706 internal board - "xlnx,zynq-zc706" - -- Xilinx ZC770 internal board, with different FMC cards - "xlnx,zynq-zc770-xm010" - "xlnx,zynq-zc770-xm011" - "xlnx,zynq-zc770-xm012" - "xlnx,zynq-zc770-xm013" - ---------------------------------------------------------------- - -Xilinx Zynq UltraScale+ MPSoC Platforms Device Tree Bindings - -Boards with ZynqMP SOC based on an ARM Cortex A53 processor -shall have the following properties. - -Required root node properties: - - compatible = "xlnx,zynqmp"; - - -Additional compatible strings: - -- Xilinx internal board zc1232 - "xlnx,zynqmp-zc1232-revA", "xlnx,zynqmp-zc1232" - -- Xilinx internal board zc1254 - "xlnx,zynqmp-zc1254-revA", "xlnx,zynqmp-zc1254" - -- Xilinx internal board zc1275 - "xlnx,zynqmp-zc1275-revA", "xlnx,zynqmp-zc1275" - -- Xilinx internal board zc1751 - "xlnx,zynqmp-zc1751" - -- Xilinx 96boards compatible board zcu100 - "xlnx,zynqmp-zcu100-revC", "xlnx,zynqmp-zcu100" - -- Xilinx evaluation board zcu102 - "xlnx,zynqmp-zcu102-revA", "xlnx,zynqmp-zcu102" - "xlnx,zynqmp-zcu102-revB", "xlnx,zynqmp-zcu102" - "xlnx,zynqmp-zcu102-rev1.0", "xlnx,zynqmp-zcu102" - -- Xilinx evaluation board zcu104 - "xlnx,zynqmp-zcu104-revA", "xlnx,zynqmp-zcu104" - -- Xilinx evaluation board zcu106 - "xlnx,zynqmp-zcu106-revA", "xlnx,zynqmp-zcu106" - -- Xilinx evaluation board zcu111 - "xlnx,zynqmp-zcu111-revA", "xlnx,zynqmp-zcu111" diff --git a/Documentation/devicetree/bindings/arm/xilinx.yaml b/Documentation/devicetree/bindings/arm/xilinx.yaml new file mode 100644 index 000000000000..c73b1f5c7f49 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/xilinx.yaml @@ -0,0 +1,114 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/xilinx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx Zynq Platforms Device Tree Bindings + +maintainers: + - Michal Simek <michal.simek@xilinx.com> + +description: | + Xilinx boards with Zynq-7000 SOC or Zynq UltraScale+ MPSoC + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - adapteva,parallella + - digilent,zynq-zybo + - digilent,zynq-zybo-z7 + - xlnx,zynq-cc108 + - xlnx,zynq-zc702 + - xlnx,zynq-zc706 + - xlnx,zynq-zc770-xm010 + - xlnx,zynq-zc770-xm011 + - xlnx,zynq-zc770-xm012 + - xlnx,zynq-zc770-xm013 + - const: xlnx,zynq-7000 + + - items: + - const: avnet,zynq-microzed + - const: xlnx,zynq-microzed + - const: xlnx,zynq-7000 + + - items: + - const: avnet,zynq-zed + - const: xlnx,zynq-zed + - const: xlnx,zynq-7000 + + - items: + - enum: + - xlnx,zynqmp-zc1751 + - const: xlnx,zynqmp + + - description: Xilinx internal board zc1232 + items: + - const: xlnx,zynqmp-zc1232-revA + - const: xlnx,zynqmp-zc1232 + - const: xlnx,zynqmp + + - description: Xilinx internal board zc1254 + items: + - const: xlnx,zynqmp-zc1254-revA + - const: xlnx,zynqmp-zc1254 + - const: xlnx,zynqmp + + - description: Xilinx internal board zc1275 + items: + - const: xlnx,zynqmp-zc1275-revA + - const: xlnx,zynqmp-zc1275 + - const: xlnx,zynqmp + + - description: Xilinx 96boards compatible board zcu100 + items: + - const: xlnx,zynqmp-zcu100-revC + - const: xlnx,zynqmp-zcu100 + - const: xlnx,zynqmp + + - description: Xilinx 96boards compatible board Ultra96 + items: + - const: avnet,ultra96-rev1 + - const: avnet,ultra96 + - const: xlnx,zynqmp-zcu100-revC + - const: xlnx,zynqmp-zcu100 + - const: xlnx,zynqmp + + - description: Xilinx evaluation board zcu102 + items: + - enum: + - xlnx,zynqmp-zcu102-revA + - xlnx,zynqmp-zcu102-revB + - xlnx,zynqmp-zcu102-rev1.0 + - const: xlnx,zynqmp-zcu102 + - const: xlnx,zynqmp + + - description: Xilinx evaluation board zcu104 + items: + - enum: + - xlnx,zynqmp-zcu104-revA + - xlnx,zynqmp-zcu104-rev1.0 + - const: xlnx,zynqmp-zcu104 + - const: xlnx,zynqmp + + - description: Xilinx evaluation board zcu106 + items: + - enum: + - xlnx,zynqmp-zcu106-revA + - xlnx,zynqmp-zcu106-rev1.0 + - const: xlnx,zynqmp-zcu106 + - const: xlnx,zynqmp + + - description: Xilinx evaluation board zcu111 + items: + - enum: + - xlnx,zynqmp-zcu111-revA + - xlnx,zynqmp-zcu11-rev1.0 + - const: xlnx,zynqmp-zcu111 + - const: xlnx,zynqmp + +... diff --git a/Documentation/devicetree/bindings/arm/zte.txt b/Documentation/devicetree/bindings/arm/zte,sysctrl.txt index 83369785d29c..7e66b7f7ba96 100644 --- a/Documentation/devicetree/bindings/arm/zte.txt +++ b/Documentation/devicetree/bindings/arm/zte,sysctrl.txt @@ -1,9 +1,6 @@ -ZTE platforms device tree bindings ---------------------------------------- +ZTE sysctrl Registers -- ZX296702 board: - Required root node properties: - - compatible = "zte,zx296702-ad1", "zte,zx296702" +Registers for 'zte,zx296702' SoC: System management required properties: - compatible = "zte,sysctrl" @@ -15,13 +12,7 @@ Bus matrix required properties: - compatible = "zte,zx-bus-matrix" ---------------------------------------- -- ZX296718 SoC: - Required root node properties: - - compatible = "zte,zx296718" - -ZX296718 EVB board: - - "zte,zx296718-evb" +Registers for 'zte,zx296718' SoC: System management required properties: - compatible = "zte,zx296718-aon-sysctrl" diff --git a/Documentation/devicetree/bindings/arm/zte.yaml b/Documentation/devicetree/bindings/arm/zte.yaml new file mode 100644 index 000000000000..2d3fefdccdff --- /dev/null +++ b/Documentation/devicetree/bindings/arm/zte.yaml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/arm/zte.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ZTE platforms device tree bindings + +maintainers: + - Jun Nie <jun.nie@linaro.org> + +properties: + $nodename: + const: '/' + compatible: + oneOf: + - items: + - enum: + - zte,zx296702-ad1 + - const: zte,zx296702 + - items: + - enum: + - zte,zx296718-evb + - const: zte,zx296718 + +... diff --git a/Documentation/devicetree/bindings/bus/imx-weim.txt b/Documentation/devicetree/bindings/bus/imx-weim.txt index 683eaf3aed79..dda7d6d66479 100644 --- a/Documentation/devicetree/bindings/bus/imx-weim.txt +++ b/Documentation/devicetree/bindings/bus/imx-weim.txt @@ -47,9 +47,9 @@ Optional properties: Timing property for child nodes. It is mandatory, not optional. - fsl,weim-cs-timing: The timing array, contains timing values for the - child node. We can get the CS index from the child - node's "reg" property. The number of registers depends - on the selected chip. + child node. We get the CS indexes from the address + ranges in the child node's "reg" property. + The number of registers depends on the selected chip: For i.MX1, i.MX21 ("fsl,imx1-weim") there are two registers: CSxU, CSxL. For i.MX25, i.MX27, i.MX31 and i.MX35 ("fsl,imx27-weim") @@ -80,3 +80,29 @@ Example for an imx6q-sabreauto board, the NOR flash connected to the WEIM: 0x0000c000 0x1404a38e 0x00000000>; }; }; + +Example for an imx6q-based board, a multi-chipselect device connected to WEIM: + +In this case, both chip select 0 and 1 will be configured with the same timing +array values. + + weim: weim@21b8000 { + compatible = "fsl,imx6q-weim"; + reg = <0x021b8000 0x4000>; + clocks = <&clks 196>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0 0 0x08000000 0x02000000 + 1 0 0x0a000000 0x02000000 + 2 0 0x0c000000 0x02000000 + 3 0 0x0e000000 0x02000000>; + fsl,weim-cs-gpr = <&gpr>; + + acme@0 { + compatible = "acme,whatever"; + reg = <0 0 0x100>, <0 0x400000 0x800>, + <1 0x400000 0x800>; + fsl,weim-cs-timing = <0x024400b1 0x00001010 0x20081100 + 0x00000000 0xa0000240 0x00000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt b/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt index 87dfb33fb3be..b9d533717dff 100644 --- a/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt +++ b/Documentation/devicetree/bindings/bus/sun50i-de2-bus.txt @@ -1,11 +1,14 @@ -Device tree bindings for Allwinner A64 DE2 bus +Device tree bindings for Allwinner DE2/3 bus The Allwinner A64 DE2 is on a special bus, which needs a SRAM region (SRAM C) -to be claimed for enabling the access. +to be claimed for enabling the access. The DE3 on Allwinner H6 is at the same +situation, and the binding also applies. Required properties: - - compatible: Should contain "allwinner,sun50i-a64-de2" + - compatible: Should be one of: + - "allwinner,sun50i-a64-de2" + - "allwinner,sun50i-h6-de3", "allwinner,sun50i-a64-de2" - reg: A resource specifier for the register space - #address-cells: Must be set to 1 - #size-cells: Must be set to 1 diff --git a/Documentation/devicetree/bindings/bus/ti-sysc.txt b/Documentation/devicetree/bindings/bus/ti-sysc.txt index 91dc2333af01..85a23f551f02 100644 --- a/Documentation/devicetree/bindings/bus/ti-sysc.txt +++ b/Documentation/devicetree/bindings/bus/ti-sysc.txt @@ -35,6 +35,7 @@ Required standard properties: "ti,sysc-omap3-sham" "ti,sysc-omap-aes" "ti,sysc-mcasp" + "ti,sysc-dra7-mcasp" "ti,sysc-usb-host-fs" "ti,sysc-dra7-mcan" diff --git a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt b/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt index d1e60d297387..2ef86ae96df8 100644 --- a/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt +++ b/Documentation/devicetree/bindings/clock/actions,owl-cmu.txt @@ -13,6 +13,7 @@ Required Properties: region. - clocks: Reference to the parent clocks ("hosc", "losc") - #clock-cells: should be 1. +- #reset-cells: should be 1. Each clock is assigned an identifier, and client nodes can use this identifier to specify the clock which they consume. @@ -36,6 +37,7 @@ Example: Clock Management Unit node: reg = <0x0 0xe0160000 0x0 0x1000>; clocks = <&hosc>, <&losc>; #clock-cells = <1>; + #reset-cells = <1>; }; Example: UART controller node that consumes clock generated by the clock diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt index 3a880528030e..79511d7bb321 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-aoclkc.txt @@ -11,6 +11,13 @@ Required Properties: - GXM (S912) : "amlogic,meson-gxm-aoclkc" - AXG (A113D, A113X) : "amlogic,meson-axg-aoclkc" followed by the common "amlogic,meson-gx-aoclkc" +- clocks: list of clock phandle, one for each entry clock-names. +- clock-names: should contain the following: + * "xtal" : the platform xtal + * "mpeg-clk" : the main clock controller mother clock (aka clk81) + * "ext-32k-0" : external 32kHz reference #0 if any (optional) + * "ext-32k-1" : external 32kHz reference #1 if any (optional - gx only) + * "ext-32k-2" : external 32kHz reference #2 if any (optional - gx only) - #clock-cells: should be 1. @@ -40,8 +47,9 @@ ao_sysctrl: sys-ctrl@0 { compatible = "amlogic,meson-gxbb-aoclkc", "amlogic,meson-gx-aoclkc"; #clock-cells = <1>; #reset-cells = <1>; + clocks = <&xtal>, <&clkc CLKID_CLK81>; + clock-names = "xtal", "mpeg-clk"; }; -}; Example: UART controller node that consumes the clock and reset generated by the clock controller: diff --git a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt index e950599566a9..a6871953bf04 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,gxbb-clkc.txt @@ -9,6 +9,9 @@ Required Properties: "amlogic,gxbb-clkc" for GXBB SoC, "amlogic,gxl-clkc" for GXL and GXM SoC, "amlogic,axg-clkc" for AXG SoC. +- clocks : list of clock phandle, one for each entry clock-names. +- clock-names : should contain the following: + * "xtal": the platform xtal - #clock-cells: should be 1. @@ -31,6 +34,8 @@ sysctrl: system-controller@0 { clkc: clock-controller { #clock-cells = <1>; compatible = "amlogic,gxbb-clkc"; + clocks = <&xtal>; + clock-names = "xtal"; }; }; diff --git a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt index b455c5aa9139..4d94091c1d2d 100644 --- a/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt +++ b/Documentation/devicetree/bindings/clock/amlogic,meson8b-clkc.txt @@ -9,15 +9,13 @@ Required Properties: - "amlogic,meson8-clkc" for Meson8 (S802) SoCs - "amlogic,meson8b-clkc" for Meson8 (S805) SoCs - "amlogic,meson8m2-clkc" for Meson8m2 (S812) SoCs -- reg: it must be composed by two tuples: - 0) physical base address of the xtal register and length of memory - mapped region. - 1) physical base address of the clock controller and length of memory - mapped region. - - #clock-cells: should be 1. - #reset-cells: should be 1. +Parent node should have the following properties : +- compatible: "amlogic,meson-hhi-sysctrl", "simple-mfd", "syscon" +- reg: base address and size of the HHI system control register space. + 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/meson8b-clkc.h header and can be @@ -30,9 +28,8 @@ device tree sources). Example: Clock controller node: - clkc: clock-controller@c1104000 { + clkc: clock-controller { compatible = "amlogic,meson8b-clkc"; - reg = <0xc1108000 0x4>, <0xc1104000 0x460>; #clock-cells = <1>; #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/at91-clock.txt b/Documentation/devicetree/bindings/clock/at91-clock.txt index 8f8f95056f3d..e9f70fcdfe80 100644 --- a/Documentation/devicetree/bindings/clock/at91-clock.txt +++ b/Documentation/devicetree/bindings/clock/at91-clock.txt @@ -4,6 +4,8 @@ This binding uses the common clock binding[1]. [1] Documentation/devicetree/bindings/clock/clock-bindings.txt +Slow Clock controller: + Required properties: - compatible : shall be one of the following: "atmel,at91sam9x5-sckc" or @@ -16,84 +18,6 @@ Required properties: "atmel,at91sam9x5-clk-slow-rc-osc": at91 internal slow RC oscillator - - "atmel,<chip>-pmc": - at91 PMC (Power Management Controller) - All at91 specific clocks (clocks defined below) must be child - node of the PMC node. - <chip> can be: at91rm9200, at91sam9260, at91sam9261, - at91sam9263, at91sam9g45, at91sam9n12, at91sam9rl, at91sam9x5, - sama5d2, sama5d3 or sama5d4. - - "atmel,at91sam9x5-clk-slow" (under sckc node) - or - "atmel,at91sam9260-clk-slow" (under pmc node): - at91 slow clk - - "atmel,at91rm9200-clk-main-osc" - "atmel,at91sam9x5-clk-main-rc-osc" - at91 main clk sources - - "atmel,at91sam9x5-clk-main" - "atmel,at91rm9200-clk-main": - at91 main clock - - "atmel,at91rm9200-clk-master" or - "atmel,at91sam9x5-clk-master": - at91 master clock - - "atmel,at91sam9x5-clk-peripheral" or - "atmel,at91rm9200-clk-peripheral": - at91 peripheral clocks - - "atmel,at91rm9200-clk-pll" or - "atmel,at91sam9g45-clk-pll" or - "atmel,at91sam9g20-clk-pllb" or - "atmel,sama5d3-clk-pll": - at91 pll clocks - - "atmel,at91sam9x5-clk-plldiv": - at91 plla divisor - - "atmel,at91rm9200-clk-programmable" or - "atmel,at91sam9g45-clk-programmable" or - "atmel,at91sam9x5-clk-programmable": - at91 programmable clocks - - "atmel,at91sam9x5-clk-smd": - at91 SMD (Soft Modem) clock - - "atmel,at91rm9200-clk-system": - at91 system clocks - - "atmel,at91rm9200-clk-usb" or - "atmel,at91sam9x5-clk-usb" or - "atmel,at91sam9n12-clk-usb": - at91 usb clock - - "atmel,at91sam9x5-clk-utmi": - at91 utmi clock - - "atmel,sama5d4-clk-h32mx": - at91 h32mx clock - - "atmel,sama5d2-clk-generated": - at91 generated clock - - "atmel,sama5d2-clk-audio-pll-frac": - at91 audio fractional pll - - "atmel,sama5d2-clk-audio-pll-pad": - at91 audio pll CLK_AUDIO output pin - - "atmel,sama5d2-clk-audio-pll-pmc" - at91 audio pll output on AUDIOPLLCLK that feeds the PMC - and can be used by peripheral clock or generic clock - - "atmel,sama5d2-clk-i2s-mux" (under pmc node): - at91 I2S clock source selection - -Required properties for SCKC node: - reg : defines the IO memory reserved for the SCKC. - #size-cells : shall be 0 (reg is used to encode clk id). - #address-cells : shall be 1 (reg is used to encode clk id). @@ -109,428 +33,30 @@ For example: /* put at91 slow clocks here */ }; +Power Management Controller (PMC): -Required properties for internal slow RC oscillator: -- #clock-cells : from common clock binding; shall be set to 0. -- clock-frequency : define the internal RC oscillator frequency. - -Optional properties: -- clock-accuracy : define the internal RC oscillator accuracy. - -For example: - slow_rc_osc: slow_rc_osc { - compatible = "atmel,at91sam9x5-clk-slow-rc-osc"; - clock-frequency = <32768>; - clock-accuracy = <50000000>; - }; - -Required properties for slow oscillator: -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall encode the main osc source clk sources (see atmel datasheet). +Required properties: +- compatible : shall be "atmel,<chip>-pmc", "syscon": + <chip> can be: at91rm9200, at91sam9260, at91sam9261, + at91sam9263, at91sam9g45, at91sam9n12, at91sam9rl, at91sam9g15, + at91sam9g25, at91sam9g35, at91sam9x25, at91sam9x35, at91sam9x5, + sama5d2, sama5d3 or sama5d4. +- #clock-cells : from common clock binding; shall be set to 2. The first entry + is the type of the clock (core, system, peripheral or generated) and the + second entry its index as provided by the datasheet +- clocks : Must contain an entry for each entry in clock-names. +- clock-names: Must include the following entries: "slow_clk", "main_xtal" Optional properties: - atmel,osc-bypass : boolean property. Set this when a clock signal is directly provided on XIN. For example: - slow_osc: slow_osc { - compatible = "atmel,at91rm9200-clk-slow-osc"; - #clock-cells = <0>; - clocks = <&slow_xtal>; - }; - -Required properties for slow clock: -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall encode the slow clk sources (see atmel datasheet). - -For example: - clk32k: slck { - compatible = "atmel,at91sam9x5-clk-slow"; - #clock-cells = <0>; - clocks = <&slow_rc_osc &slow_osc>; - }; - -Required properties for PMC node: -- reg : defines the IO memory reserved for the PMC. -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). -- interrupts : shall be set to PMC interrupt line. -- interrupt-controller : tell that the PMC is an interrupt controller. -- #interrupt-cells : must be set to 1. The first cell encodes the interrupt id, - and reflect the bit position in the PMC_ER/DR/SR registers. - You can use the dt macros defined in dt-bindings/clock/at91.h. - 0 (AT91_PMC_MOSCS) -> main oscillator ready - 1 (AT91_PMC_LOCKA) -> PLL A ready - 2 (AT91_PMC_LOCKB) -> PLL B ready - 3 (AT91_PMC_MCKRDY) -> master clock ready - 6 (AT91_PMC_LOCKU) -> UTMI PLL clock ready - 8 .. 15 (AT91_PMC_PCKRDY(id)) -> programmable clock ready - 16 (AT91_PMC_MOSCSELS) -> main oscillator selected - 17 (AT91_PMC_MOSCRCS) -> RC main oscillator stabilized - 18 (AT91_PMC_CFDEV) -> clock failure detected - -For example: - pmc: pmc@fffffc00 { - compatible = "atmel,sama5d3-pmc"; - interrupts = <1 4 7>; - interrupt-controller; - #interrupt-cells = <2>; - #size-cells = <0>; - #address-cells = <1>; - - /* put at91 clocks here */ - }; - -Required properties for main clock internal RC oscillator: -- interrupts : shall be set to "<0>". -- clock-frequency : define the internal RC oscillator frequency. - -Optional properties: -- clock-accuracy : define the internal RC oscillator accuracy. - -For example: - main_rc_osc: main_rc_osc { - compatible = "atmel,at91sam9x5-clk-main-rc-osc"; - interrupt-parent = <&pmc>; - interrupts = <0>; - clock-frequency = <12000000>; - clock-accuracy = <50000000>; - }; - -Required properties for main clock oscillator: -- interrupts : shall be set to "<0>". -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall encode the main osc source clk sources (see atmel datasheet). - -Optional properties: -- atmel,osc-bypass : boolean property. Specified if a clock signal is provided - on XIN. - - clock signal is directly provided on XIN pin. - -For example: - main_osc: main_osc { - compatible = "atmel,at91rm9200-clk-main-osc"; - interrupt-parent = <&pmc>; - interrupts = <0>; - #clock-cells = <0>; - clocks = <&main_xtal>; - }; - -Required properties for main clock: -- interrupts : shall be set to "<0>". -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall encode the main clk sources (see atmel datasheet). - -For example: - main: mainck { - compatible = "atmel,at91sam9x5-clk-main"; - interrupt-parent = <&pmc>; - interrupts = <0>; - #clock-cells = <0>; - clocks = <&main_rc_osc &main_osc>; - }; - -Required properties for master clock: -- interrupts : shall be set to "<3>". -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the master clock sources (see atmel datasheet) phandles. - e.g. "<&ck32k>, <&main>, <&plla>, <&pllb>". -- atmel,clk-output-range : minimum and maximum clock frequency (two u32 - fields). - e.g. output = <0 133000000>; <=> 0 to 133MHz. -- atmel,clk-divisors : master clock divisors table (four u32 fields). - 0 <=> reserved value. - e.g. divisors = <1 2 4 6>; -- atmel,master-clk-have-div3-pres : some SoC use the reserved value 7 in the - PRES field as CLOCK_DIV3 (e.g sam9x5). - -For example: - mck: mck { - compatible = "atmel,at91rm9200-clk-master"; - interrupt-parent = <&pmc>; - interrupts = <3>; - #clock-cells = <0>; - atmel,clk-output-range = <0 133000000>; - atmel,clk-divisors = <1 2 4 0>; - }; - -Required properties for peripheral clocks: -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). -- clocks : shall be the master clock phandle. - e.g. clocks = <&mck>; -- name: device tree node describing a specific peripheral clock. - * #clock-cells : from common clock binding; shall be set to 0. - * reg: peripheral id. See Atmel's datasheets to get a full - list of peripheral ids. - * atmel,clk-output-range : minimum and maximum clock frequency - (two u32 fields). Only valid on at91sam9x5-clk-peripheral - compatible IPs. - -For example: - periph: periphck { - compatible = "atmel,at91sam9x5-clk-peripheral"; - #size-cells = <0>; - #address-cells = <1>; - clocks = <&mck>; - - ssc0_clk { - #clock-cells = <0>; - reg = <2>; - atmel,clk-output-range = <0 133000000>; - }; - - usart0_clk { - #clock-cells = <0>; - reg = <3>; - atmel,clk-output-range = <0 66000000>; - }; - }; - - -Required properties for pll clocks: -- interrupts : shall be set to "<1>". -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the main clock phandle. -- reg : pll id. - 0 -> PLL A - 1 -> PLL B -- atmel,clk-input-range : minimum and maximum source clock frequency (two u32 - fields). - e.g. input = <1 32000000>; <=> 1 to 32MHz. -- #atmel,pll-clk-output-range-cells : number of cells reserved for pll output - range description. Sould be set to 2, 3 - or 4. - * 1st and 2nd cells represent the frequency range (min-max). - * 3rd cell is optional and represents the OUT field value for the given - range. - * 4th cell is optional and represents the ICPLL field (PLLICPR - register) -- atmel,pll-clk-output-ranges : pll output frequency ranges + optional parameter - depending on #atmel,pll-output-range-cells - property value. - -For example: - plla: pllack { - compatible = "atmel,at91sam9g45-clk-pll"; - interrupt-parent = <&pmc>; - interrupts = <1>; - #clock-cells = <0>; - clocks = <&main>; - reg = <0>; - atmel,clk-input-range = <2000000 32000000>; - #atmel,pll-clk-output-range-cells = <4>; - atmel,pll-clk-output-ranges = <74500000 800000000 0 0 - 69500000 750000000 1 0 - 64500000 700000000 2 0 - 59500000 650000000 3 0 - 54500000 600000000 0 1 - 49500000 550000000 1 1 - 44500000 500000000 2 1 - 40000000 450000000 3 1>; - }; - -Required properties for plldiv clocks (plldiv = pll / 2): -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the plla clock phandle. - -The pll divisor is equal to 2 and cannot be changed. - -For example: - plladiv: plladivck { - compatible = "atmel,at91sam9x5-clk-plldiv"; - #clock-cells = <0>; - clocks = <&plla>; - }; - -Required properties for programmable clocks: -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). -- clocks : shall be the programmable clock source phandles. - e.g. clocks = <&clk32k>, <&main>, <&plla>, <&pllb>; -- name: device tree node describing a specific prog clock. - * #clock-cells : from common clock binding; shall be set to 0. - * reg : programmable clock id (register offset from PCKx - register). - * interrupts : shall be set to "<(8 + id)>". - -For example: - prog: progck { - compatible = "atmel,at91sam9g45-clk-programmable"; - #size-cells = <0>; - #address-cells = <1>; - interrupt-parent = <&pmc>; - clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>; - - prog0 { - #clock-cells = <0>; - reg = <0>; - interrupts = <8>; - }; - - prog1 { - #clock-cells = <0>; - reg = <1>; - interrupts = <9>; - }; - }; - - -Required properties for smd clock: -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the smd clock source phandles. - e.g. clocks = <&plladiv>, <&utmi>; - -For example: - smd: smdck { - compatible = "atmel,at91sam9x5-clk-smd"; - #clock-cells = <0>; - clocks = <&plladiv>, <&utmi>; - }; - -Required properties for system clocks: -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). -- name: device tree node describing a specific system clock. - * #clock-cells : from common clock binding; shall be set to 0. - * reg: system clock id (bit position in SCER/SCDR/SCSR registers). - See Atmel's datasheet to get a full list of system clock ids. - -For example: - system: systemck { - compatible = "atmel,at91rm9200-clk-system"; - #address-cells = <1>; - #size-cells = <0>; - - ddrck { - #clock-cells = <0>; - reg = <2>; - clocks = <&mck>; - }; - - uhpck { - #clock-cells = <0>; - reg = <6>; - clocks = <&usb>; - }; - - udpck { - #clock-cells = <0>; - reg = <7>; - clocks = <&usb>; - }; - }; - - -Required properties for usb clock: -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the smd clock source phandles. - e.g. clocks = <&pllb>; -- atmel,clk-divisors (only available for "atmel,at91rm9200-clk-usb"): - usb clock divisor table. - e.g. divisors = <1 2 4 0>; - -For example: - usb: usbck { - compatible = "atmel,at91sam9x5-clk-usb"; - #clock-cells = <0>; - clocks = <&plladiv>, <&utmi>; - }; - - usb: usbck { - compatible = "atmel,at91rm9200-clk-usb"; - #clock-cells = <0>; - clocks = <&pllb>; - atmel,clk-divisors = <1 2 4 0>; - }; - - -Required properties for utmi clock: -- interrupts : shall be set to "<AT91_PMC_LOCKU IRQ_TYPE_LEVEL_HIGH>". -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the main clock source phandle. - -For example: - utmi: utmick { - compatible = "atmel,at91sam9x5-clk-utmi"; - interrupt-parent = <&pmc>; - interrupts = <AT91_PMC_LOCKU IRQ_TYPE_LEVEL_HIGH>; - #clock-cells = <0>; - clocks = <&main>; - }; - -Required properties for 32 bits bus Matrix clock (h32mx clock): -- #clock-cells : from common clock binding; shall be set to 0. -- clocks : shall be the master clock source phandle. - -For example: - h32ck: h32mxck { - #clock-cells = <0>; - compatible = "atmel,sama5d4-clk-h32mx"; - clocks = <&mck>; - }; - -Required properties for generated clocks: -- #size-cells : shall be 0 (reg is used to encode clk id). -- #address-cells : shall be 1 (reg is used to encode clk id). -- clocks : shall be the generated clock source phandles. - e.g. clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>, <&audio_pll_pmc>; -- name: device tree node describing a specific generated clock. - * #clock-cells : from common clock binding; shall be set to 0. - * reg: peripheral id. See Atmel's datasheets to get a full - list of peripheral ids. - * atmel,clk-output-range : minimum and maximum clock frequency - (two u32 fields). - -For example: - gck { - compatible = "atmel,sama5d2-clk-generated"; - #address-cells = <1>; - #size-cells = <0>; - clocks = <&clk32k>, <&main>, <&plladiv>, <&utmi>, <&mck>, <&audio_pll_pmc>; - - tcb0_gclk: tcb0_gclk { - #clock-cells = <0>; - reg = <35>; - atmel,clk-output-range = <0 83000000>; - }; - - pwm_gclk: pwm_gclk { - #clock-cells = <0>; - reg = <38>; - atmel,clk-output-range = <0 83000000>; - }; - }; - -Required properties for I2S mux clocks: -- #size-cells : shall be 0 (reg is used to encode I2S bus id). -- #address-cells : shall be 1 (reg is used to encode I2S bus id). -- name: device tree node describing a specific mux clock. - * #clock-cells : from common clock binding; shall be set to 0. - * clocks : shall be the mux clock parent phandles; shall be 2 phandles: - peripheral and generated clock; the first phandle shall belong to the - peripheral clock and the second one shall belong to the generated - clock; "clock-indices" property can be user to specify - the correct order. - * reg: I2S bus id of the corresponding mux clock. - e.g. reg = <0>; for i2s0, reg = <1>; for i2s1 - -For example: - i2s_clkmux { - compatible = "atmel,sama5d2-clk-i2s-mux"; - #address-cells = <1>; - #size-cells = <0>; - - i2s0muxck: i2s0_muxclk { - clocks = <&i2s0_clk>, <&i2s0_gclk>; - #clock-cells = <0>; - reg = <0>; - }; - - i2s1muxck: i2s1_muxclk { - clocks = <&i2s1_clk>, <&i2s1_gclk>; - #clock-cells = <0>; - reg = <1>; - }; + pmc: pmc@f0018000 { + compatible = "atmel,sama5d4-pmc", "syscon"; + reg = <0xf0018000 0x120>; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH 7>; + #clock-cells = <2>; + clocks = <&clk32k>, <&main_xtal>; + clock-names = "slow_clk", "main_xtal"; }; diff --git a/Documentation/devicetree/bindings/clock/clock-bindings.txt b/Documentation/devicetree/bindings/clock/clock-bindings.txt index 2ec489eebe72..b646bbcf7f92 100644 --- a/Documentation/devicetree/bindings/clock/clock-bindings.txt +++ b/Documentation/devicetree/bindings/clock/clock-bindings.txt @@ -168,3 +168,19 @@ a shared clock is forbidden. Configuration of common clocks, which affect multiple consumer devices can be similarly specified in the clock provider node. + +==Protected clocks== + +Some platforms or firmwares may not fully expose all the clocks to the OS, such +as in situations where those clks are used by drivers running in ARM secure +execution levels. Such a configuration can be specified in device tree with the +protected-clocks property in the form of a clock specifier list. This property should +only be specified in the node that is providing the clocks being protected: + + clock-controller@a000f000 { + compatible = "vendor,clk95; + reg = <0xa000f000 0x1000> + #clocks-cells = <1>; + ... + protected-clocks = <UART3_CLK>, <SPI5_CLK>; + }; diff --git a/Documentation/devicetree/bindings/clock/hi3670-clock.txt b/Documentation/devicetree/bindings/clock/hi3670-clock.txt new file mode 100644 index 000000000000..66f3697eca78 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/hi3670-clock.txt @@ -0,0 +1,43 @@ +* Hisilicon Hi3670 Clock Controller + +The Hi3670 clock controller generates and supplies clock to various +controllers within the Hi3670 SoC. + +Required Properties: + +- compatible: the compatible should be one of the following strings to + indicate the clock controller functionality. + + - "hisilicon,hi3670-crgctrl" + - "hisilicon,hi3670-pctrl" + - "hisilicon,hi3670-pmuctrl" + - "hisilicon,hi3670-sctrl" + - "hisilicon,hi3670-iomcu" + - "hisilicon,hi3670-media1-crg" + - "hisilicon,hi3670-media2-crg" + +- 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/hi3670-clock.h>. + +Examples: + crg_ctrl: clock-controller@fff35000 { + compatible = "hisilicon,hi3670-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 HI3670_CLK_GATE_UART0>, + <&crg_ctrl HI3670_PCLK>; + clock-names = "uartclk", "apb_pclk"; + }; diff --git a/Documentation/devicetree/bindings/clock/imx6q-clock.txt b/Documentation/devicetree/bindings/clock/imx6q-clock.txt index a45ca67a9d5f..13d36d4c6991 100644 --- a/Documentation/devicetree/bindings/clock/imx6q-clock.txt +++ b/Documentation/devicetree/bindings/clock/imx6q-clock.txt @@ -6,6 +6,17 @@ Required properties: - interrupts: Should contain CCM interrupt - #clock-cells: Should be <1> +Optional properties: +- fsl,pmic-stby-poweroff: Configure CCM to assert PMIC_STBY_REQ signal + on power off. + Use this property if the SoC should be powered off by external power + management IC (PMIC) triggered via PMIC_STBY_REQ signal. + Boards that are designed to initiate poweroff on PMIC_ON_REQ signal should + be using "syscon-poweroff" driver instead. +- clocks: list of clock specifiers, must contain an entry for each entry + in clock-names +- clock-names: valid names are "osc", "ckil", "ckih1", "anaclk1" and "anaclk2" + The clock consumer should specify the desired clock by having the clock ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx6qdl-clock.h for the full list of i.MX6 Quad and DualLite clock IDs. diff --git a/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt b/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt new file mode 100644 index 000000000000..a4f8cd478f92 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx7ulp-clock.txt @@ -0,0 +1,104 @@ +* Clock bindings for Freescale i.MX7ULP + +i.MX7ULP Clock functions are under joint control of the System +Clock Generation (SCG) modules, Peripheral Clock Control (PCC) +modules, and Core Mode Controller (CMC)1 blocks + +The clocking scheme provides clear separation between M4 domain +and A7 domain. Except for a few clock sources shared between two +domains, such as the System Oscillator clock, the Slow IRC (SIRC), +and and the Fast IRC clock (FIRCLK), clock sources and clock +management are separated and contained within each domain. + +M4 clock management consists of SCG0, PCC0, PCC1, and CMC0 modules. +A7 clock management consists of SCG1, PCC2, PCC3, and CMC1 modules. + +Note: this binding doc is only for A7 clock domain. + +System Clock Generation (SCG) modules: +--------------------------------------------------------------------- +The System Clock Generation (SCG) is responsible for clock generation +and distribution across this device. Functions performed by the SCG +include: clock reference selection, generation of clock used to derive +processor, system, peripheral bus and external memory interface clocks, +source selection for peripheral clocks and control of power saving +clock gating mode. + +Required properties: + +- compatible: Should be "fsl,imx7ulp-scg1". +- reg : Should contain registers location and length. +- #clock-cells: Should be <1>. +- clocks: Should contain the fixed input clocks. +- clock-names: Should contain the following clock names: + "rosc", "sosc", "sirc", "firc", "upll", "mpll". + +Peripheral Clock Control (PCC) modules: +--------------------------------------------------------------------- +The Peripheral Clock Control (PCC) is responsible for clock selection, +optional division and clock gating mode for peripherals in their +respected power domain + +Required properties: +- compatible: Should be one of: + "fsl,imx7ulp-pcc2", + "fsl,imx7ulp-pcc3". +- reg : Should contain registers location and length. +- #clock-cells: Should be <1>. +- clocks: Should contain the fixed input clocks. +- clock-names: Should contain the following clock names: + "nic1_bus_clk", "nic1_clk", "ddr_clk", "apll_pfd2", + "apll_pfd1", "apll_pfd0", "upll", "sosc_bus_clk", + "mpll", "firc_bus_clk", "rosc", "spll_bus_clk"; + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. +See include/dt-bindings/clock/imx7ulp-clock.h +for the full list of i.MX7ULP clock IDs of each module. + +Examples: + +#include <dt-bindings/clock/imx7ulp-clock.h> + +scg1: scg1@403e0000 { + compatible = "fsl,imx7ulp-scg1; + reg = <0x403e0000 0x10000>; + clocks = <&rosc>, <&sosc>, <&sirc>, + <&firc>, <&upll>, <&mpll>; + clock-names = "rosc", "sosc", "sirc", + "firc", "upll", "mpll"; + #clock-cells = <1>; +}; + +pcc2: pcc2@403f0000 { + compatible = "fsl,imx7ulp-pcc2"; + reg = <0x403f0000 0x10000>; + #clock-cells = <1>; + clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, + <&scg1 IMX7ULP_CLK_NIC1_DIV>, + <&scg1 IMX7ULP_CLK_DDR_DIV>, + <&scg1 IMX7ULP_CLK_APLL_PFD2>, + <&scg1 IMX7ULP_CLK_APLL_PFD1>, + <&scg1 IMX7ULP_CLK_APLL_PFD0>, + <&scg1 IMX7ULP_CLK_UPLL>, + <&scg1 IMX7ULP_CLK_SOSC_BUS_CLK>, + <&scg1 IMX7ULP_CLK_MIPI_PLL>, + <&scg1 IMX7ULP_CLK_FIRC_BUS_CLK>, + <&scg1 IMX7ULP_CLK_ROSC>, + <&scg1 IMX7ULP_CLK_SPLL_BUS_CLK>; + clock-names = "nic1_bus_clk", "nic1_clk", "ddr_clk", + "apll_pfd2", "apll_pfd1", "apll_pfd0", + "upll", "sosc_bus_clk", "mpll", + "firc_bus_clk", "rosc", "spll_bus_clk"; +}; + +usdhc1: usdhc@40380000 { + compatible = "fsl,imx7ulp-usdhc"; + reg = <0x40380000 0x10000>; + interrupts = <GIC_SPI 43 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&scg1 IMX7ULP_CLK_NIC1_BUS_DIV>, + <&scg1 IMX7ULP_CLK_NIC1_DIV>, + <&pcc2 IMX7ULP_CLK_USDHC1>; + clock-names ="ipg", "ahb", "per"; + bus-width = <4>; +}; diff --git a/Documentation/devicetree/bindings/clock/imx8mq-clock.txt b/Documentation/devicetree/bindings/clock/imx8mq-clock.txt new file mode 100644 index 000000000000..52de8263e012 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx8mq-clock.txt @@ -0,0 +1,20 @@ +* Clock bindings for NXP i.MX8M Quad + +Required properties: +- compatible: Should be "fsl,imx8mq-ccm" +- reg: Address and length of the register set +- #clock-cells: Should be <1> +- clocks: list of clock specifiers, must contain an entry for each required + entry in clock-names +- clock-names: should include the following entries: + - "ckil" + - "osc_25m" + - "osc_27m" + - "clk_ext1" + - "clk_ext2" + - "clk_ext3" + - "clk_ext4" + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx8mq-clock.h +for the full list of i.MX8M Quad clock IDs. diff --git a/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.txt b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.txt new file mode 100644 index 000000000000..965cfa42e025 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx8qxp-lpcg.txt @@ -0,0 +1,51 @@ +* NXP i.MX8QXP LPCG (Low-Power Clock Gating) Clock bindings + +The Low-Power Clock Gate (LPCG) modules contain a local programming +model to control the clock gates for the peripherals. An LPCG module +is used to locally gate the clocks for the associated peripheral. + +Note: +This level of clock gating is provided after the clocks are generated +by the SCU resources and clock controls. Thus even if the clock is +enabled by these control bits, it might still not be running based +on the base resource. + +Required properties: +- compatible: Should be one of: + "fsl,imx8qxp-lpcg-adma", + "fsl,imx8qxp-lpcg-conn", + "fsl,imx8qxp-lpcg-dc", + "fsl,imx8qxp-lpcg-dsp", + "fsl,imx8qxp-lpcg-gpu", + "fsl,imx8qxp-lpcg-hsio", + "fsl,imx8qxp-lpcg-img", + "fsl,imx8qxp-lpcg-lsio", + "fsl,imx8qxp-lpcg-vpu" +- reg: Address and length of the register set +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. +See the full list of clock IDs from: +include/dt-bindings/clock/imx8qxp-clock.h + +Examples: + +#include <dt-bindings/clock/imx8qxp-clock.h> + +conn_lpcg: clock-controller@5b200000 { + compatible = "fsl,imx8qxp-lpcg-conn"; + reg = <0x5b200000 0xb0000>; + #clock-cells = <1>; +}; + +usdhc1: mmc@5b010000 { + compatible = "fsl,imx8qxp-usdhc", "fsl,imx7d-usdhc"; + interrupt-parent = <&gic>; + interrupts = <GIC_SPI 232 IRQ_TYPE_LEVEL_HIGH>; + reg = <0x5b010000 0x10000>; + clocks = <&conn_lpcg IMX8QXP_CONN_LPCG_SDHC0_IPG_CLK>, + <&conn_lpcg IMX8QXP_CONN_LPCG_SDHC0_PER_CLK>, + <&conn_lpcg IMX8QXP_CONN_LPCG_SDHC0_HCLK>; + clock-names = "ipg", "per", "ahb"; +}; diff --git a/Documentation/devicetree/bindings/clock/ingenic,cgu.txt b/Documentation/devicetree/bindings/clock/ingenic,cgu.txt index f8d4134ae409..ba5a442026b7 100644 --- a/Documentation/devicetree/bindings/clock/ingenic,cgu.txt +++ b/Documentation/devicetree/bindings/clock/ingenic,cgu.txt @@ -6,8 +6,11 @@ to provide many different clock signals derived from only 2 external source clocks. Required properties: -- compatible : Should be "ingenic,<soctype>-cgu". - For example "ingenic,jz4740-cgu" or "ingenic,jz4780-cgu". +- compatible : Should be one of: + * ingenic,jz4740-cgu + * ingenic,jz4725b-cgu + * ingenic,jz4770-cgu + * ingenic,jz4780-cgu - reg : The address & length of the CGU registers. - clocks : List of phandle & clock specifiers for clocks external to the CGU. Two such external clocks should be specified - first the external crystal diff --git a/Documentation/devicetree/bindings/clock/marvell,mmp2.txt b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt index af376a01f2b7..23b52dc02266 100644 --- a/Documentation/devicetree/bindings/clock/marvell,mmp2.txt +++ b/Documentation/devicetree/bindings/clock/marvell,mmp2.txt @@ -18,4 +18,4 @@ Required Properties: 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/marvell-mmp2.h>. +All these identifiers could be found in <dt-bindings/clock/marvell,mmp2.h>. diff --git a/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt b/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt index dff236f524a7..958e0ad78c52 100644 --- a/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt +++ b/Documentation/devicetree/bindings/clock/nvidia,tegra124-dfll.txt @@ -8,10 +8,11 @@ the fast CPU cluster. It consists of a free-running voltage controlled oscillator connected to the CPU voltage rail (VDD_CPU), and a closed loop control module that will automatically adjust the VDD_CPU voltage by communicating with an off-chip PMIC either via an I2C bus or via PWM signals. -Currently only the I2C mode is supported by these bindings. Required properties: -- compatible : should be "nvidia,tegra124-dfll" +- compatible : should be one of: + - "nvidia,tegra124-dfll": for Tegra124 + - "nvidia,tegra210-dfll": for Tegra210 - reg : Defines the following set of registers, in the order listed: - registers for the DFLL control logic. - registers for the I2C output logic. @@ -45,10 +46,31 @@ Required properties for the control loop parameters: Optional properties for the control loop parameters: - nvidia,cg-scale: Boolean value, see the field DFLL_PARAMS_CG_SCALE in the TRM. +Optional properties for mode selection: +- nvidia,pwm-to-pmic: Use PWM to control regulator rather then I2C. + Required properties for I2C mode: - nvidia,i2c-fs-rate: I2C transfer rate, if using full speed mode. -Example: +Required properties for PWM mode: +- nvidia,pwm-period-nanoseconds: period of PWM square wave in nanoseconds. +- nvidia,pwm-tristate-microvolts: Regulator voltage in micro volts when PWM + control is disabled and the PWM output is tristated. Note that this voltage is + configured in hardware, typically via a resistor divider. +- nvidia,pwm-min-microvolts: Regulator voltage in micro volts when PWM control + is enabled and PWM output is low. Hence, this is the minimum output voltage + that the regulator supports when PWM control is enabled. +- nvidia,pwm-voltage-step-microvolts: Voltage increase in micro volts + corresponding to a 1/33th increase in duty cycle. Eg the voltage for 2/33th + duty cycle would be: nvidia,pwm-min-microvolts + + nvidia,pwm-voltage-step-microvolts * 2. +- pinctrl-0: I/O pad configuration when PWM control is enabled. +- pinctrl-1: I/O pad configuration when PWM control is disabled. +- pinctrl-names: must include the following entries: + - dvfs_pwm_enable: I/O pad configuration when PWM control is enabled. + - dvfs_pwm_disable: I/O pad configuration when PWM control is disabled. + +Example for I2C: clock@70110000 { compatible = "nvidia,tegra124-dfll"; @@ -76,3 +98,58 @@ clock@70110000 { nvidia,i2c-fs-rate = <400000>; }; + +Example for PWM: + +clock@70110000 { + compatible = "nvidia,tegra124-dfll"; + reg = <0 0x70110000 0 0x100>, /* DFLL control */ + <0 0x70110000 0 0x100>, /* I2C output control */ + <0 0x70110100 0 0x100>, /* Integrated I2C controller */ + <0 0x70110200 0 0x100>; /* Look-up table RAM */ + interrupts = <GIC_SPI 62 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA210_CLK_DFLL_SOC>, + <&tegra_car TEGRA210_CLK_DFLL_REF>, + <&tegra_car TEGRA124_CLK_I2C5>;; + clock-names = "soc", "ref", "i2c"; + resets = <&tegra_car TEGRA124_RST_DFLL_DVCO>; + reset-names = "dvco"; + #clock-cells = <0>; + clock-output-names = "dfllCPU_out"; + + nvidia,sample-rate = <25000>; + nvidia,droop-ctrl = <0x00000f00>; + nvidia,force-mode = <1>; + nvidia,cf = <6>; + nvidia,ci = <0>; + nvidia,cg = <2>; + + nvidia,pwm-min-microvolts = <708000>; /* 708mV */ + nvidia,pwm-period-nanoseconds = <2500>; /* 2.5us */ + nvidia,pwm-to-pmic; + nvidia,pwm-tristate-microvolts = <1000000>; + nvidia,pwm-voltage-step-microvolts = <19200>; /* 19.2mV */ + + pinctrl-names = "dvfs_pwm_enable", "dvfs_pwm_disable"; + pinctrl-0 = <&dvfs_pwm_active_state>; + pinctrl-1 = <&dvfs_pwm_inactive_state>; +}; + +/* pinmux nodes added for completeness. Binding doc can be found in: + * Documentation/devicetree/bindings/pinctrl/nvidia,tegra210-pinmux.txt + */ + +pinmux: pinmux@700008d4 { + dvfs_pwm_active_state: dvfs_pwm_active { + dvfs_pwm_pbb1 { + nvidia,pins = "dvfs_pwm_pbb1"; + nvidia,tristate = <TEGRA_PIN_DISABLE>; + }; + }; + dvfs_pwm_inactive_state: dvfs_pwm_inactive { + dvfs_pwm_pbb1 { + nvidia,pins = "dvfs_pwm_pbb1"; + nvidia,tristate = <TEGRA_PIN_ENABLE>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/clock/qcom,camcc.txt b/Documentation/devicetree/bindings/clock/qcom,camcc.txt new file mode 100644 index 000000000000..c5eb6694fda9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,camcc.txt @@ -0,0 +1,18 @@ +Qualcomm Camera Clock & Reset Controller Binding +------------------------------------------------ + +Required properties : +- compatible : shall contain "qcom,sdm845-camcc". +- reg : shall contain base register location and length. +- #clock-cells : from common clock binding, shall contain 1. +- #reset-cells : from common reset binding, shall contain 1. +- #power-domain-cells : from generic power domain binding, shall contain 1. + +Example: + camcc: clock-controller@ad00000 { + compatible = "qcom,sdm845-camcc"; + reg = <0xad00000 0x10000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc.txt b/Documentation/devicetree/bindings/clock/qcom,gcc.txt index 664ea1fd6c76..8661c3cd3ccf 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,gcc.txt @@ -19,6 +19,9 @@ Required properties : "qcom,gcc-msm8996" "qcom,gcc-msm8998" "qcom,gcc-mdm9615" + "qcom,gcc-qcs404" + "qcom,gcc-sdm630" + "qcom,gcc-sdm660" "qcom,gcc-sdm845" - reg : shall contain base register location and length @@ -32,6 +35,8 @@ be part of GCC and hence the TSENS properties can also be part of the GCC/clock-controller node. For more details on the TSENS properties please refer Documentation/devicetree/bindings/thermal/qcom-tsens.txt +- protected-clocks : Protected clock specifier list as per common clock + binding. Example: clock-controller@900000 { @@ -52,3 +57,17 @@ Example of GCC with TSENS properties: #reset-cells = <1>; #thermal-sensor-cells = <1>; }; + +Example of GCC with protected-clocks properties: + clock-controller@100000 { + compatible = "qcom,gcc-sdm845"; + reg = <0x100000 0x1f0000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + protected-clocks = <GCC_QSPI_CORE_CLK>, + <GCC_QSPI_CORE_CLK_SRC>, + <GCC_QSPI_CNOC_PERIPH_AHB_CLK>, + <GCC_LPASS_Q6_AXI_CLK>, + <GCC_LPASS_SWAY_CLK>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.txt b/Documentation/devicetree/bindings/clock/qcom,gpucc.txt new file mode 100644 index 000000000000..4e5215ef1acd --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.txt @@ -0,0 +1,22 @@ +Qualcomm Graphics Clock & Reset Controller Binding +-------------------------------------------------- + +Required properties : +- compatible : shall contain "qcom,sdm845-gpucc" +- reg : shall contain base register location and length +- #clock-cells : from common clock binding, shall contain 1 +- #reset-cells : from common reset binding, shall contain 1 +- #power-domain-cells : from generic power domain binding, shall contain 1 +- clocks : shall contain the XO clock +- clock-names : shall be "xo" + +Example: + gpucc: clock-controller@5090000 { + compatible = "qcom,sdm845-gpucc"; + reg = <0x5090000 0x9000>; + #clock-cells = <1>; + #reset-cells = <1>; + #power-domain-cells = <1>; + clocks = <&rpmhcc RPMH_CXO_CLK>; + clock-names = "xo"; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,hfpll.txt b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt new file mode 100644 index 000000000000..ec02a024424c --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,hfpll.txt @@ -0,0 +1,60 @@ +High-Frequency PLL (HFPLL) + +PROPERTIES + +- compatible: + Usage: required + Value type: <string>: + shall contain only one of the following. The generic + compatible "qcom,hfpll" should be also included. + + "qcom,hfpll-ipq8064", "qcom,hfpll" + "qcom,hfpll-apq8064", "qcom,hfpll" + "qcom,hfpll-msm8974", "qcom,hfpll" + "qcom,hfpll-msm8960", "qcom,hfpll" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: address and size of HPLL registers. An optional second + element specifies the address and size of the alias + register region. + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the xo clock. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "xo". + +- clock-output-names: + Usage: required + Value type: <string> + Definition: Name of the PLL. Typically hfpllX where X is a CPU number + starting at 0. Otherwise hfpll_Y where Y is more specific + such as "l2". + +Example: + +1) An HFPLL for the L2 cache. + + clock-controller@f9016000 { + compatible = "qcom,hfpll-ipq8064", "qcom,hfpll"; + reg = <0xf9016000 0x30>; + clocks = <&xo_board>; + clock-names = "xo"; + clock-output-names = "hfpll_l2"; + }; + +2) An HFPLL for CPU0. This HFPLL has the alias register region. + + clock-controller@f908a000 { + compatible = "qcom,hfpll-ipq8064", "qcom,hfpll"; + reg = <0xf908a000 0x30>, <0xf900a000 0x30>; + clocks = <&xo_board>; + clock-names = "xo"; + clock-output-names = "hfpll0"; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,krait-cc.txt b/Documentation/devicetree/bindings/clock/qcom,krait-cc.txt new file mode 100644 index 000000000000..030ba60dab08 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,krait-cc.txt @@ -0,0 +1,34 @@ +Krait Clock Controller + +PROPERTIES + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,krait-cc-v1" + "qcom,krait-cc-v2" + +- #clock-cells: + Usage: required + Value type: <u32> + Definition: must be 1 + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: reference to the clock parents of hfpll, secondary muxes. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: must be "hfpll0", "hfpll1", "acpu0_aux", "acpu1_aux", "qsb". + +Example: + + kraitcc: clock-controller { + compatible = "qcom,krait-cc-v1"; + clocks = <&hfpll0>, <&hfpll1>, <&acpu0_aux>, <&acpu1_aux>, <qsb>; + clock-names = "hfpll0", "hfpll1", "acpu0_aux", "acpu1_aux", "qsb"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt b/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt new file mode 100644 index 000000000000..b9e9787045b9 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/qcom,lpasscc.txt @@ -0,0 +1,26 @@ +Qualcomm LPASS Clock Controller Binding +----------------------------------------------- + +Required properties : +- compatible : shall contain "qcom,sdm845-lpasscc" +- #clock-cells : from common clock binding, shall contain 1. +- reg : shall contain base register address and size, + in the order + Index-0 maps to LPASS_CC register region + Index-1 maps to LPASS_QDSP6SS register region + +Optional properties : +- reg-names : register names of LPASS domain + "cc", "qdsp6ss". + +Example: + +The below node has to be defined in the cases where the LPASS peripheral loader +would bring the subsystem out of reset. + + lpasscc: clock-controller@17014000 { + compatible = "qcom,sdm845-lpasscc"; + reg = <0x17014000 0x1f004>, <0x17300000 0x200>; + reg-names = "cc", "qdsp6ss"; + #clock-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt index 4491d1c104aa..87b4949e9bc8 100644 --- a/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,rpmcc.txt @@ -16,6 +16,7 @@ Required properties : "qcom,rpmcc-msm8974", "qcom,rpmcc" "qcom,rpmcc-apq8064", "qcom,rpmcc" "qcom,rpmcc-msm8996", "qcom,rpmcc" + "qcom,rpmcc-qcs404", "qcom,rpmcc" - #clock-cells : shall contain 1 diff --git a/Documentation/devicetree/bindings/clock/qcom,videocc.txt b/Documentation/devicetree/bindings/clock/qcom,videocc.txt index e7c035afa778..8a8622c65c5a 100644 --- a/Documentation/devicetree/bindings/clock/qcom,videocc.txt +++ b/Documentation/devicetree/bindings/clock/qcom,videocc.txt @@ -6,8 +6,6 @@ Required properties : - reg : shall contain base register location and length - #clock-cells : from common clock binding, shall contain 1. - #power-domain-cells : from generic power domain binding, shall contain 1. - -Optional properties : - #reset-cells : from common reset binding, shall contain 1. Example: @@ -16,4 +14,5 @@ Example: reg = <0xab00000 0x10000>; #clock-cells = <1>; #power-domain-cells = <1>; + #reset-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/clock/qoriq-clock.txt b/Documentation/devicetree/bindings/clock/qoriq-clock.txt index 97f46adac85f..c655f28d5918 100644 --- a/Documentation/devicetree/bindings/clock/qoriq-clock.txt +++ b/Documentation/devicetree/bindings/clock/qoriq-clock.txt @@ -28,6 +28,12 @@ Required properties: * "fsl,p4080-clockgen" * "fsl,p5020-clockgen" * "fsl,p5040-clockgen" + * "fsl,t1023-clockgen" + * "fsl,t1024-clockgen" + * "fsl,t1040-clockgen" + * "fsl,t1042-clockgen" + * "fsl,t2080-clockgen" + * "fsl,t2081-clockgen" * "fsl,t4240-clockgen" * "fsl,b4420-clockgen" * "fsl,b4860-clockgen" diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt index db542abadb75..916a601b76a7 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.txt @@ -13,9 +13,13 @@ They provide the following functionalities: Required Properties: - compatible: Must be one of: + - "renesas,r7s9210-cpg-mssr" for the r7s9210 SoC (RZ/A2) - "renesas,r8a7743-cpg-mssr" for the r8a7743 SoC (RZ/G1M) + - "renesas,r8a7744-cpg-mssr" for the r8a7744 SoC (RZ/G1N) - "renesas,r8a7745-cpg-mssr" for the r8a7745 SoC (RZ/G1E) - "renesas,r8a77470-cpg-mssr" for the r8a77470 SoC (RZ/G1C) + - "renesas,r8a774a1-cpg-mssr" for the r8a774a1 SoC (RZ/G2M) + - "renesas,r8a774c0-cpg-mssr" for the r8a774c0 SoC (RZ/G2E) - "renesas,r8a7790-cpg-mssr" for the r8a7790 SoC (R-Car H2) - "renesas,r8a7791-cpg-mssr" for the r8a7791 SoC (R-Car M2-W) - "renesas,r8a7792-cpg-mssr" for the r8a7792 SoC (R-Car V2H) @@ -35,12 +39,13 @@ Required Properties: - clocks: References to external parent clocks, one entry for each entry in clock-names - clock-names: List of external parent clock names. Valid names are: - - "extal" (r8a7743, r8a7745, r8a77470, r8a7790, r8a7791, r8a7792, - r8a7793, r8a7794, r8a7795, r8a7796, r8a77965, r8a77970, - r8a77980, r8a77990, r8a77995) - - "extalr" (r8a7795, r8a7796, r8a77965, r8a77970, r8a77980) - - "usb_extal" (r8a7743, r8a7745, r8a77470, r8a7790, r8a7791, r8a7793, - r8a7794) + - "extal" (r7s9210, r8a7743, r8a7744, r8a7745, r8a77470, r8a774a1, + r8a774c0, r8a7790, r8a7791, r8a7792, r8a7793, r8a7794, + r8a7795, r8a7796, r8a77965, r8a77970, r8a77980, r8a77990, + r8a77995) + - "extalr" (r8a774a1, r8a7795, r8a7796, r8a77965, r8a77970, r8a77980) + - "usb_extal" (r8a7743, r8a7744, r8a7745, r8a77470, r8a7790, r8a7791, + r8a7793, r8a7794) - #clock-cells: Must be 2 - For CPG core clocks, the two clock specifier cells must be "CPG_CORE" diff --git a/Documentation/devicetree/bindings/clock/sun8i-de2.txt b/Documentation/devicetree/bindings/clock/sun8i-de2.txt index e94582e8b8a9..41a52c2acffd 100644 --- a/Documentation/devicetree/bindings/clock/sun8i-de2.txt +++ b/Documentation/devicetree/bindings/clock/sun8i-de2.txt @@ -1,5 +1,5 @@ -Allwinner Display Engine 2.0 Clock Control Binding --------------------------------------------------- +Allwinner Display Engine 2.0/3.0 Clock Control Binding +------------------------------------------------------ Required properties : - compatible: must contain one of the following compatibles: @@ -8,6 +8,7 @@ Required properties : - "allwinner,sun8i-v3s-de2-clk" - "allwinner,sun50i-a64-de2-clk" - "allwinner,sun50i-h5-de2-clk" + - "allwinner,sun50i-h6-de3-clk" - reg: Must contain the registers base address and length - clocks: phandle to the clocks feeding the display engine subsystem. diff --git a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt index 47d2e902ced4..e3bd88ae456b 100644 --- a/Documentation/devicetree/bindings/clock/sunxi-ccu.txt +++ b/Documentation/devicetree/bindings/clock/sunxi-ccu.txt @@ -22,6 +22,7 @@ Required properties : - "allwinner,sun50i-h5-ccu" - "allwinner,sun50i-h6-ccu" - "allwinner,sun50i-h6-r-ccu" + - "allwinner,suniv-f1c100s-ccu" - "nextthing,gr8-ccu" - reg: Must contain the registers base address and length diff --git a/Documentation/devicetree/bindings/connector/usb-connector.txt b/Documentation/devicetree/bindings/connector/usb-connector.txt index 8855bfcfd778..a9a2f2fc44f2 100644 --- a/Documentation/devicetree/bindings/connector/usb-connector.txt +++ b/Documentation/devicetree/bindings/connector/usb-connector.txt @@ -14,6 +14,8 @@ Optional properties: - label: symbolic name for the connector, - type: size of the connector, should be specified in case of USB-A, USB-B non-fullsize connectors: "mini", "micro". +- self-powered: Set this property if the usb device that has its own power + source. Optional properties for usb-c-connector: - power-role: should be one of "source", "sink" or "dual"(DRP) if typec @@ -29,15 +31,15 @@ Required properties for usb-c-connector with power delivery support: in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2 Source_Capabilities Message, the order of each entry(PDO) should follow the PD spec chapter 6.4.1. Required for power source and power dual role. - User can specify the source PDO array via PDO_FIXED/BATT/VAR() defined in - dt-bindings/usb/pd.h. + User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() + defined in dt-bindings/usb/pd.h. - sink-pdos: An array of u32 with each entry providing supported power sink data object(PDO), the detailed bit definitions of PDO can be found in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3 Sink Capabilities Message, the order of each entry(PDO) should follow the PD spec chapter 6.4.1. Required for power sink and power dual role. - User can specify the sink PDO array via PDO_FIXED/BATT/VAR() defined in - dt-bindings/usb/pd.h. + User can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined + in dt-bindings/usb/pd.h. - op-sink-microwatt: Sink required operating power in microwatt, if source can't offer the power, Capability Mismatch is set. Required for power sink and power dual role. diff --git a/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt b/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt deleted file mode 100644 index 2aa06ac0fac5..000000000000 --- a/Documentation/devicetree/bindings/cpufreq/arm_big_little_dt.txt +++ /dev/null @@ -1,65 +0,0 @@ -Generic ARM big LITTLE cpufreq driver's DT glue ------------------------------------------------ - -This is DT specific glue layer for generic cpufreq driver for big LITTLE -systems. - -Both required and optional properties listed below must be defined -under node /cpus/cpu@x. Where x is the first cpu inside a cluster. - -FIXME: Cpus should boot in the order specified in DT and all cpus for a cluster -must be present contiguously. Generic DT driver will check only node 'x' for -cpu:x. - -Required properties: -- operating-points: Refer to Documentation/devicetree/bindings/opp/opp.txt - for details - -Optional properties: -- clock-latency: Specify the possible maximum transition latency for clock, - in unit of nanoseconds. - -Examples: - -cpus { - #address-cells = <1>; - #size-cells = <0>; - - cpu@0 { - compatible = "arm,cortex-a15"; - reg = <0>; - next-level-cache = <&L2>; - operating-points = < - /* kHz uV */ - 792000 1100000 - 396000 950000 - 198000 850000 - >; - clock-latency = <61036>; /* two CLK32 periods */ - }; - - cpu@1 { - compatible = "arm,cortex-a15"; - reg = <1>; - next-level-cache = <&L2>; - }; - - cpu@100 { - compatible = "arm,cortex-a7"; - reg = <100>; - next-level-cache = <&L2>; - operating-points = < - /* kHz uV */ - 792000 950000 - 396000 750000 - 198000 450000 - >; - clock-latency = <61036>; /* two CLK32 periods */ - }; - - cpu@101 { - compatible = "arm,cortex-a7"; - reg = <101>; - next-level-cache = <&L2>; - }; -}; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.txt new file mode 100644 index 000000000000..33856947c561 --- /dev/null +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-qcom-hw.txt @@ -0,0 +1,172 @@ +Qualcomm Technologies, Inc. CPUFREQ Bindings + +CPUFREQ HW is a hardware engine used by some Qualcomm Technologies, Inc. (QTI) +SoCs to manage frequency in hardware. It is capable of controlling frequency +for multiple clusters. + +Properties: +- compatible + Usage: required + Value type: <string> + Definition: must be "qcom,cpufreq-hw". + +- clocks + Usage: required + Value type: <phandle> From common clock binding. + Definition: clock handle for XO clock and GPLL0 clock. + +- clock-names + Usage: required + Value type: <string> From common clock binding. + Definition: must be "xo", "alternate". + +- reg + Usage: required + Value type: <prop-encoded-array> + Definition: Addresses and sizes for the memory of the HW bases in + each frequency domain. +- reg-names + Usage: Optional + Value type: <string> + Definition: Frequency domain name i.e. + "freq-domain0", "freq-domain1". + +- #freq-domain-cells: + Usage: required. + Definition: Number of cells in a freqency domain specifier. + +* Property qcom,freq-domain +Devices supporting freq-domain must set their "qcom,freq-domain" property with +phandle to a cpufreq_hw followed by the Domain ID(0/1) in the CPU DT node. + + +Example: + +Example 1: Dual-cluster, Quad-core per cluster. CPUs within a cluster switch +DCVS state together. + +/ { + cpus { + #address-cells = <2>; + #size-cells = <0>; + + CPU0: cpu@0 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x0>; + enable-method = "psci"; + next-level-cache = <&L2_0>; + qcom,freq-domain = <&cpufreq_hw 0>; + L2_0: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + L3_0: l3-cache { + compatible = "cache"; + }; + }; + }; + + CPU1: cpu@100 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x100>; + enable-method = "psci"; + next-level-cache = <&L2_100>; + qcom,freq-domain = <&cpufreq_hw 0>; + L2_100: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU2: cpu@200 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x200>; + enable-method = "psci"; + next-level-cache = <&L2_200>; + qcom,freq-domain = <&cpufreq_hw 0>; + L2_200: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU3: cpu@300 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x300>; + enable-method = "psci"; + next-level-cache = <&L2_300>; + qcom,freq-domain = <&cpufreq_hw 0>; + L2_300: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU4: cpu@400 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x400>; + enable-method = "psci"; + next-level-cache = <&L2_400>; + qcom,freq-domain = <&cpufreq_hw 1>; + L2_400: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU5: cpu@500 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x500>; + enable-method = "psci"; + next-level-cache = <&L2_500>; + qcom,freq-domain = <&cpufreq_hw 1>; + L2_500: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU6: cpu@600 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x600>; + enable-method = "psci"; + next-level-cache = <&L2_600>; + qcom,freq-domain = <&cpufreq_hw 1>; + L2_600: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + + CPU7: cpu@700 { + device_type = "cpu"; + compatible = "qcom,kryo385"; + reg = <0x0 0x700>; + enable-method = "psci"; + next-level-cache = <&L2_700>; + qcom,freq-domain = <&cpufreq_hw 1>; + L2_700: l2-cache { + compatible = "cache"; + next-level-cache = <&L3_0>; + }; + }; + }; + + soc { + cpufreq_hw: cpufreq@17d43000 { + compatible = "qcom,cpufreq-hw"; + reg = <0x17d43000 0x1400>, <0x17d45800 0x1400>; + reg-names = "freq-domain0", "freq-domain1"; + + clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GPLL0>; + clock-names = "xo", "alternate"; + + #freq-domain-cells = <1>; + }; +} diff --git a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra124-cpufreq.txt b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra124-cpufreq.txt index b1669fbfb740..03196d5ea515 100644 --- a/Documentation/devicetree/bindings/cpufreq/nvidia,tegra124-cpufreq.txt +++ b/Documentation/devicetree/bindings/cpufreq/nvidia,tegra124-cpufreq.txt @@ -9,11 +9,9 @@ Required properties: See ../clocks/clock-bindings.txt for details. - clock-names: Must include the following entries: - cpu_g: Clock mux for the fast CPU cluster. - - cpu_lp: Clock mux for the low-power CPU cluster. - pll_x: Fast PLL clocksource. - pll_p: Auxiliary PLL used during fast PLL rate changes. - dfll: Fast DFLL clocksource that also automatically scales CPU voltage. -- vdd-cpu-supply: Regulator for CPU voltage Optional properties: - clock-latency: Specify the possible maximum transition latency for clock, @@ -31,13 +29,11 @@ cpus { reg = <0>; clocks = <&tegra_car TEGRA124_CLK_CCLK_G>, - <&tegra_car TEGRA124_CLK_CCLK_LP>, <&tegra_car TEGRA124_CLK_PLL_X>, <&tegra_car TEGRA124_CLK_PLL_P>, <&dfll>; - clock-names = "cpu_g", "cpu_lp", "pll_x", "pll_p", "dfll"; + clock-names = "cpu_g", "pll_x", "pll_p", "dfll"; clock-latency = <300000>; - vdd-cpu-supply: <&vdd_cpu>; }; <...> diff --git a/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt index 999fb2a810f6..6130e6eb4af8 100644 --- a/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt +++ b/Documentation/devicetree/bindings/crypto/arm-cryptocell.txt @@ -1,8 +1,12 @@ Arm TrustZone CryptoCell cryptographic engine Required properties: -- compatible: Should be one of: "arm,cryptocell-712-ree", - "arm,cryptocell-710-ree" or "arm,cryptocell-630p-ree". +- compatible: Should be one of - + "arm,cryptocell-713-ree" + "arm,cryptocell-703-ree" + "arm,cryptocell-712-ree" + "arm,cryptocell-710-ree" + "arm,cryptocell-630p-ree" - reg: Base physical address of the engine and length of memory mapped region. - interrupts: Interrupt number for the device. diff --git a/Documentation/devicetree/bindings/crypto/fsl-dcp.txt b/Documentation/devicetree/bindings/crypto/fsl-dcp.txt index 76a0b4e80e83..4e4d387e38a5 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-dcp.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-dcp.txt @@ -6,6 +6,8 @@ Required properties: - interrupts : Should contain MXS DCP interrupt numbers, VMI IRQ and DCP IRQ must be supplied, optionally Secure IRQ can be present, but is currently not implemented and not used. +- clocks : Clock reference (only required on some SOCs: 6ull and 6sll). +- clock-names : Must be "dcp". Example: diff --git a/Documentation/devicetree/bindings/crypto/hisilicon,hip07-sec.txt b/Documentation/devicetree/bindings/crypto/hisilicon,hip07-sec.txt index 78d2db9d4de5..d28fd1af01b4 100644 --- a/Documentation/devicetree/bindings/crypto/hisilicon,hip07-sec.txt +++ b/Documentation/devicetree/bindings/crypto/hisilicon,hip07-sec.txt @@ -24,7 +24,7 @@ Optional properties: Example: -p1_sec_a: crypto@400,d2000000 { +p1_sec_a: crypto@400d2000000 { compatible = "hisilicon,hip07-sec"; reg = <0x400 0xd0000000 0x0 0x10000 0x400 0xd2000000 0x0 0x10000 diff --git a/Documentation/devicetree/bindings/crypto/samsung-slimsss.txt b/Documentation/devicetree/bindings/crypto/samsung-slimsss.txt new file mode 100644 index 000000000000..7ec9a5a7727a --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/samsung-slimsss.txt @@ -0,0 +1,19 @@ +Samsung SoC SlimSSS (Slim Security SubSystem) module + +The SlimSSS module in Exynos5433 SoC supports the following: +-- Feeder (FeedCtrl) +-- Advanced Encryption Standard (AES) with ECB,CBC,CTR,XTS and (CBC/XTS)/CTS +-- SHA-1/SHA-256 and (SHA-1/SHA-256)/HMAC + +Required properties: + +- compatible : Should contain entry for slimSSS version: + - "samsung,exynos5433-slim-sss" for Exynos5433 SoC. +- reg : Offset and length of the register set for the module +- interrupts : interrupt specifiers of SlimSSS module interrupts (one feed + control interrupt). + +- clocks : list of clock phandle and specifier pairs for all clocks listed in + clock-names property. +- clock-names : list of device clock input names; should contain "pclk" and + "aclk" for slim-sss in Exynos5433. diff --git a/Documentation/devicetree/bindings/csky/cpus.txt b/Documentation/devicetree/bindings/csky/cpus.txt new file mode 100644 index 000000000000..ae79412f2680 --- /dev/null +++ b/Documentation/devicetree/bindings/csky/cpus.txt @@ -0,0 +1,73 @@ +================== +C-SKY CPU Bindings +================== + +The device tree allows to describe the layout of CPUs in a system through +the "cpus" node, which in turn contains a number of subnodes (ie "cpu") +defining properties for every cpu. + +Only SMP system need to care about the cpus node and single processor +needn't define cpus node at all. + +===================================== +cpus and cpu node bindings definition +===================================== + +- cpus node + + Description: Container of cpu nodes + + The node name must be "cpus". + + A cpus node must define the following properties: + + - #address-cells + Usage: required + Value type: <u32> + Definition: must be set to 1 + - #size-cells + Usage: required + Value type: <u32> + Definition: must be set to 0 + +- cpu node + + Description: Describes one of SMP cores + + PROPERTIES + + - device_type + Usage: required + Value type: <string> + Definition: must be "cpu" + - reg + Usage: required + Value type: <u32> + Definition: CPU index + - compatible: + Usage: required + Value type: <string> + Definition: must contain "csky", eg: + "csky,610" + "csky,807" + "csky,810" + "csky,860" + +Example: +-------- + + cpus { + #address-cells = <1>; + #size-cells = <0>; + cpu@0 { + device_type = "cpu"; + reg = <0>; + status = "ok"; + }; + + cpu@1 { + device_type = "cpu"; + reg = <1>; + status = "ok"; + }; + }; diff --git a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt index 057b81335775..c65fd7a7467c 100644 --- a/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt +++ b/Documentation/devicetree/bindings/display/amlogic,meson-vpu.txt @@ -67,6 +67,8 @@ Required properties: Optional properties: - power-domains: Optional phandle to associated power domain as described in the file ../power/power_domain.txt +- amlogic,canvas: phandle to canvas provider node as described in the file + ../soc/amlogic/amlogic,canvas.txt Required nodes: diff --git a/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt b/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt new file mode 100644 index 000000000000..aaa6c24c8e70 --- /dev/null +++ b/Documentation/devicetree/bindings/display/amlogic,simple-framebuffer.txt @@ -0,0 +1,33 @@ +Meson specific Simple Framebuffer bindings + +This binding documents meson specific extensions to the simple-framebuffer +bindings. The meson simplefb u-boot code relies on the devicetree containing +pre-populated simplefb nodes. + +These extensions are intended so that u-boot can select the right node based +on which pipeline is being used. As such they are solely intended for +firmware / bootloader use, and the OS should ignore them. + +Required properties: +- compatible: "amlogic,simple-framebuffer", "simple-framebuffer" +- amlogic,pipeline, one of: + "vpu-cvbs" + "vpu-hdmi" + +Example: + +chosen { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + simplefb_hdmi: framebuffer-hdmi { + compatible = "amlogic,simple-framebuffer", + "simple-framebuffer"; + amlogic,pipeline = "vpu-hdmi"; + clocks = <&clkc CLKID_HDMI_PCLK>, + <&clkc CLKID_CLK81>, + <&clkc CLKID_GCLK_VENCI_INT0>; + power-domains = <&pwrc_vpu>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/arm,komeda.txt b/Documentation/devicetree/bindings/display/arm,komeda.txt new file mode 100644 index 000000000000..02b226532ebd --- /dev/null +++ b/Documentation/devicetree/bindings/display/arm,komeda.txt @@ -0,0 +1,73 @@ +Device Tree bindings for Arm Komeda display driver + +Required properties: +- compatible: Should be "arm,mali-d71" +- reg: Physical base address and length of the registers in the system +- interrupts: the interrupt line number of the device in the system +- clocks: A list of phandle + clock-specifier pairs, one for each entry + in 'clock-names' +- clock-names: A list of clock names. It should contain: + - "mclk": for the main processor clock + - "pclk": for the APB interface clock +- #address-cells: Must be 1 +- #size-cells: Must be 0 + +Required properties for sub-node: pipeline@nq +Each device contains one or two pipeline sub-nodes (at least one), each +pipeline node should provide properties: +- reg: Zero-indexed identifier for the pipeline +- clocks: A list of phandle + clock-specifier pairs, one for each entry + in 'clock-names' +- clock-names: should contain: + - "pxclk": pixel clock + - "aclk": AXI interface clock + +- port: each pipeline connect to an encoder input port. The connection is + modeled using the OF graph bindings specified in + Documentation/devicetree/bindings/graph.txt + +Optional properties: + - memory-region: phandle to a node describing memory (see + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt) + to be used for the framebuffer; if not present, the framebuffer may + be located anywhere in memory. + +Example: +/ { + ... + + dp0: display@c00000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "arm,mali-d71"; + reg = <0xc00000 0x20000>; + interrupts = <0 168 4>; + clocks = <&dpu_mclk>, <&dpu_aclk>; + clock-names = "mclk", "pclk"; + + dp0_pipe0: pipeline@0 { + clocks = <&fpgaosc2>, <&dpu_aclk>; + clock-names = "pxclk", "aclk"; + reg = <0>; + + port { + dp0_pipe0_out: endpoint { + remote-endpoint = <&db_dvi0_in>; + }; + }; + }; + + dp0_pipe1: pipeline@1 { + clocks = <&fpgaosc2>, <&dpu_aclk>; + clock-names = "pxclk", "aclk"; + reg = <1>; + + port { + dp0_pipe1_out: endpoint { + remote-endpoint = <&db_dvi1_in>; + }; + }; + }; + }; + ... +}; diff --git a/Documentation/devicetree/bindings/display/arm,pl11x.txt b/Documentation/devicetree/bindings/display/arm,pl11x.txt index ef89ab46b2c9..572fa2773ec4 100644 --- a/Documentation/devicetree/bindings/display/arm,pl11x.txt +++ b/Documentation/devicetree/bindings/display/arm,pl11x.txt @@ -1,6 +1,6 @@ * ARM PrimeCell Color LCD Controller PL110/PL111 -See also Documentation/devicetree/bindings/arm/primecell.txt +See also Documentation/devicetree/bindings/arm/primecell.yaml Required properties: diff --git a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt index 82f2acb3d374..0398aec488ac 100644 --- a/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt +++ b/Documentation/devicetree/bindings/display/atmel/hlcdc-dc.txt @@ -15,6 +15,13 @@ Required children nodes: to external devices using the OF graph reprensentation (see ../graph.txt). At least one port node is required. +Optional properties in grandchild nodes: + Any endpoint grandchild node may specify a desired video interface + according to ../../media/video-interfaces.txt, specifically + - bus-width: recognized values are <12>, <16>, <18> and <24>, and + override any output mode selection heuristic, forcing "rgb444", + "rgb565", "rgb666" and "rgb888" respectively. + Example: hlcdc: hlcdc@f0030000 { @@ -50,3 +57,19 @@ Example: #pwm-cells = <3>; }; }; + +Example 2: With a video interface override to force rgb565; as above +but with these changes/additions: + + &hlcdc { + hlcdc-display-controller { + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb565>; + + port@0 { + hlcdc_panel_output: endpoint@0 { + bus-width = <16>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt index f5725bb6c61c..525a4bfd8634 100644 --- a/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt +++ b/Documentation/devicetree/bindings/display/bridge/cdns,dsi.txt @@ -31,28 +31,7 @@ Required subnodes: - one subnode per DSI device connected on the DSI bus. Each DSI device should contain a reg property encoding its virtual channel. -Cadence DPHY -============ - -Cadence DPHY block. - -Required properties: -- compatible: should be set to "cdns,dphy". -- reg: physical base address and length of the DPHY registers. -- clocks: DPHY reference clocks. -- clock-names: must contain "psm" and "pll_ref". -- #phy-cells: must be set to 0. - - Example: - dphy0: dphy@fd0e0000{ - compatible = "cdns,dphy"; - reg = <0x0 0xfd0e0000 0x0 0x1000>; - clocks = <&psm_clk>, <&pll_ref_clk>; - clock-names = "psm", "pll_ref"; - #phy-cells = <0>; - }; - dsi0: dsi@fd0c0000 { compatible = "cdns,dsi"; reg = <0x0 0xfd0c0000 0x0 0x1000>; diff --git a/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt b/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt index fd39ad34c383..60091db5dfa5 100644 --- a/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt +++ b/Documentation/devicetree/bindings/display/bridge/lvds-transmitter.txt @@ -24,6 +24,10 @@ Required properties: - compatible: Must be "lvds-encoder" + Any encoder compatible with this generic binding, but with additional + properties not listed here, must list a device specific compatible first + followed by this generic compatible. + Required nodes: This device has two video ports. Their connections are modeled using the OF @@ -38,8 +42,6 @@ Example lvds-encoder { compatible = "lvds-encoder"; - #address-cells = <1>; - #size-cells = <0>; ports { #address-cells = <1>; diff --git a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt index 4f0ab3ed3b6f..900a884ad9f5 100644 --- a/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt +++ b/Documentation/devicetree/bindings/display/bridge/renesas,lvds.txt @@ -8,16 +8,31 @@ Required properties: - compatible : Shall contain one of - "renesas,r8a7743-lvds" for R8A7743 (RZ/G1M) compatible LVDS encoders + - "renesas,r8a7744-lvds" for R8A7744 (RZ/G1N) compatible LVDS encoders + - "renesas,r8a774c0-lvds" for R8A774C0 (RZ/G2E) compatible LVDS encoders - "renesas,r8a7790-lvds" for R8A7790 (R-Car H2) compatible LVDS encoders - "renesas,r8a7791-lvds" for R8A7791 (R-Car M2-W) compatible LVDS encoders - "renesas,r8a7793-lvds" for R8A7793 (R-Car M2-N) compatible LVDS encoders - "renesas,r8a7795-lvds" for R8A7795 (R-Car H3) compatible LVDS encoders - "renesas,r8a7796-lvds" for R8A7796 (R-Car M3-W) compatible LVDS encoders + - "renesas,r8a77965-lvds" for R8A77965 (R-Car M3-N) compatible LVDS encoders - "renesas,r8a77970-lvds" for R8A77970 (R-Car V3M) compatible LVDS encoders + - "renesas,r8a77980-lvds" for R8A77980 (R-Car V3H) compatible LVDS encoders + - "renesas,r8a77990-lvds" for R8A77990 (R-Car E3) compatible LVDS encoders - "renesas,r8a77995-lvds" for R8A77995 (R-Car D3) compatible LVDS encoders - reg: Base address and length for the memory-mapped registers -- clocks: A phandle + clock-specifier pair for the functional clock +- clocks: A list of phandles + clock-specifier pairs, one for each entry in + the clock-names property. +- clock-names: Name of the clocks. This property is model-dependent. + - The functional clock, which mandatory for all models, shall be listed + first, and shall be named "fck". + - On R8A77990, R8A77995 and R8A774C0, the LVDS encoder can use the EXTAL or + DU_DOTCLKINx clocks. Those clocks are optional. When supplied they must be + named "extal" and "dclkin.x" respectively, with "x" being the DU_DOTCLKIN + numerical index. + - When the clocks property only contains the functional clock, the + clock-names property may be omitted. - resets: A phandle + reset specifier for the module reset Required nodes: diff --git a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt index 527e236e9a2a..fee3c88e1a17 100644 --- a/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt +++ b/Documentation/devicetree/bindings/display/bridge/thine,thc63lvdm83d.txt @@ -10,7 +10,7 @@ Required properties: Optional properties: -- pwdn-gpios: Power down control GPIO +- powerdown-gpios: Power down control GPIO (the /PWDN pin, active low). Required nodes: diff --git a/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt b/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt new file mode 100644 index 000000000000..e575f996959a --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/ti,ds90c185.txt @@ -0,0 +1,55 @@ +Texas Instruments FPD-Link (LVDS) Serializer +-------------------------------------------- + +The DS90C185 and DS90C187 are low-power serializers for portable +battery-powered applications that reduces the size of the RGB +interface between the host GPU and the display. + +Required properties: + +- compatible: Should be + "ti,ds90c185", "lvds-encoder" for the TI DS90C185 FPD-Link Serializer + "ti,ds90c187", "lvds-encoder" for the TI DS90C187 FPD-Link Serializer + +Optional properties: + +- powerdown-gpios: Power down control GPIO (the PDB pin, active-low) + +Required nodes: + +The devices have two video ports. Their connections are modeled using the OF +graph bindings specified in Documentation/devicetree/bindings/graph.txt. + +- Video port 0 for parallel input +- Video port 1 for LVDS output + + +Example +------- + +lvds-encoder { + compatible = "ti,ds90c185", "lvds-encoder"; + + powerdown-gpios = <&gpio 17 GPIO_ACTIVE_LOW>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + lvds_enc_in: endpoint { + remote-endpoint = <&lcdc_out_rgb>; + }; + }; + + port@1 { + reg = <1>; + + lvds_enc_out: endpoint { + remote-endpoint = <&lvds_panel_in>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt new file mode 100644 index 000000000000..0a3fbb53a16e --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.txt @@ -0,0 +1,87 @@ +SN65DSI86 DSI to eDP bridge chip +-------------------------------- + +This is the binding for Texas Instruments SN65DSI86 bridge. +http://www.ti.com/general/docs/lit/getliterature.tsp?genericPartNumber=sn65dsi86&fileType=pdf + +Required properties: +- compatible: Must be "ti,sn65dsi86" +- reg: i2c address of the chip, 0x2d as per datasheet +- enable-gpios: gpio specification for bridge_en pin (active high) + +- vccio-supply: A 1.8V supply that powers up the digital IOs. +- vpll-supply: A 1.8V supply that powers up the displayport PLL. +- vcca-supply: A 1.2V supply that powers up the analog circuits. +- vcc-supply: A 1.2V supply that powers up the digital core. + +Optional properties: +- interrupts-extended: Specifier for the SN65DSI86 interrupt line. + +- gpio-controller: Marks the device has a GPIO controller. +- #gpio-cells : Should be two. The first cell is the pin number and + the second cell is used to specify flags. + See ../../gpio/gpio.txt for more information. +- #pwm-cells : Should be one. See ../../pwm/pwm.txt for description of + the cell formats. + +- clock-names: should be "refclk" +- clocks: Specification for input reference clock. The reference + clock rate must be 12 MHz, 19.2 MHz, 26 MHz, 27 MHz or 38.4 MHz. + +- data-lanes: See ../../media/video-interface.txt +- lane-polarities: See ../../media/video-interface.txt + +- suspend-gpios: specification for GPIO1 pin on bridge (active low) + +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 DSI input +- Video port 1 for eDP output + +Example +------- + +edp-bridge@2d { + compatible = "ti,sn65dsi86"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x2d>; + + enable-gpios = <&msmgpio 33 GPIO_ACTIVE_HIGH>; + suspend-gpios = <&msmgpio 34 GPIO_ACTIVE_LOW>; + + interrupts-extended = <&gpio3 4 IRQ_TYPE_EDGE_FALLING>; + + vccio-supply = <&pm8916_l17>; + vcca-supply = <&pm8916_l6>; + vpll-supply = <&pm8916_l17>; + vcc-supply = <&pm8916_l6>; + + clock-names = "refclk"; + clocks = <&input_refclk>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + edp_bridge_in: endpoint { + remote-endpoint = <&dsi_out>; + }; + }; + + port@1 { + reg = <1>; + + edp_bridge_out: endpoint { + data-lanes = <2 1 3 0>; + lane-polarities = <0 1 0 1>; + remote-endpoint = <&edp_panel_in>; + }; + }; + }; +} diff --git a/Documentation/devicetree/bindings/display/bridge/toshiba,tc358764.txt b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358764.txt new file mode 100644 index 000000000000..8f9abf28a8fa --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/toshiba,tc358764.txt @@ -0,0 +1,35 @@ +TC358764 MIPI-DSI to LVDS panel bridge + +Required properties: + - compatible: "toshiba,tc358764" + - reg: the virtual channel number of a DSI peripheral + - vddc-supply: core voltage supply, 1.2V + - vddio-supply: I/O voltage supply, 1.8V or 3.3V + - vddlvds-supply: LVDS1/2 voltage supply, 3.3V + - reset-gpios: a GPIO spec for the reset pin + +The device node can contain following 'port' child nodes, +according to the OF graph bindings defined in [1]: + 0: DSI Input, not required, if the bridge is DSI controlled + 1: LVDS Output, mandatory + +[1]: Documentation/devicetree/bindings/media/video-interfaces.txt + +Example: + + bridge@0 { + reg = <0>; + compatible = "toshiba,tc358764"; + vddc-supply = <&vcc_1v2_reg>; + vddio-supply = <&vcc_1v8_reg>; + vddlvds-supply = <&vcc_3v3_reg>; + reset-gpios = <&gpd1 6 GPIO_ACTIVE_LOW>; + #address-cells = <1>; + #size-cells = <0>; + port@1 { + reg = <1>; + lvds_ep: endpoint { + remote-endpoint = <&panel_ep>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt index 2fff8b406f4c..be377786e8cd 100644 --- a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt +++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt @@ -21,6 +21,9 @@ Required properties: - samsung,pll-clock-frequency: specifies frequency of the oscillator clock - #address-cells, #size-cells: should be set respectively to <1> and <0> according to DSI host bindings (see MIPI DSI bindings [1]) + - samsung,burst-clock-frequency: specifies DSI frequency in high-speed burst + mode + - samsung,esc-clock-frequency: specifies DSI frequency in escape mode Optional properties: - power-domains: a phandle to DSIM power domain node @@ -29,25 +32,9 @@ Child nodes: Should contain DSI peripheral nodes (see MIPI DSI bindings [1]). Video interfaces: - Device node can contain video interface port nodes according to [2]. - The following are properties specific to those nodes: - - port node inbound: - - reg: (required) must be 0. - port node outbound: - - reg: (required) must be 1. - - endpoint node connected from mic node (reg = 0): - - remote-endpoint: specifies the endpoint in mic node. This node is required - for Exynos5433 mipi dsi. So mic can access to panel node - throughout this dsi node. - endpoint node connected to panel node (reg = 1): - - remote-endpoint: specifies the endpoint in panel node. This node is - required in all kinds of exynos mipi dsi to represent - the connection between mipi dsi and panel. - - samsung,burst-clock-frequency: specifies DSI frequency in high-speed burst - mode - - samsung,esc-clock-frequency: specifies DSI frequency in escape mode + Device node can contain following video interface port nodes according to [2]: + 0: RGB input, + 1: DSI output [1]: Documentation/devicetree/bindings/display/mipi-dsi-bus.txt [2]: Documentation/devicetree/bindings/media/video-interfaces.txt diff --git a/Documentation/devicetree/bindings/display/himax,hx8357d.txt b/Documentation/devicetree/bindings/display/himax,hx8357d.txt new file mode 100644 index 000000000000..e641f664763d --- /dev/null +++ b/Documentation/devicetree/bindings/display/himax,hx8357d.txt @@ -0,0 +1,26 @@ +Himax HX8357D display panels + +This binding is for display panels using a Himax HX8357D controller in SPI +mode, such as the Adafruit 3.5" TFT for Raspberry Pi. + +Required properties: +- compatible: "adafruit,yx350hv15", "himax,hx8357d" +- dc-gpios: D/C pin +- reg: address of the panel on the SPI bus + +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: +- rotation: panel rotation in degrees counter clockwise (0,90,180,270) +- backlight: phandle of the backlight device attached to the panel + +Example: + display@0{ + compatible = "adafruit,yx350hv15", "himax,hx8357d"; + reg = <0>; + spi-max-frequency = <32000000>; + dc-gpios = <&gpio0 25 GPIO_ACTIVE_HIGH>; + rotation = <90>; + backlight = <&backlight>; + }; diff --git a/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt b/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt index 973c27273772..a336599f6c03 100644 --- a/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt +++ b/Documentation/devicetree/bindings/display/mipi-dsi-bus.txt @@ -16,7 +16,7 @@ The following assumes that only a single peripheral is connected to a DSI host. Experience shows that this is true for the large majority of setups. DSI host --------- +======== In addition to the standard properties and those defined by the parent bus of a DSI host, the following properties apply to a node representing a DSI host. @@ -29,12 +29,24 @@ Required properties: - #size-cells: Should be 0. There are cases where it makes sense to use a different value here. See below. +Optional properties: +- clock-master: boolean. Should be enabled if the host is being used in + conjunction with another DSI host to drive the same peripheral. Hardware + supporting such a configuration generally requires the data on both the busses + to be driven by the same clock. Only the DSI host instance controlling this + clock should contain this property. + DSI peripheral --------------- +============== + +Peripherals with DSI as control bus, or no control bus +------------------------------------------------------ -Peripherals are represented as child nodes of the DSI host's node. Properties -described here apply to all DSI peripherals, but individual bindings may want -to define additional, device-specific properties. +Peripherals with the DSI bus as the primary control bus, or peripherals with +no control bus but use the DSI bus to transmit pixel data are represented +as child nodes of the DSI host's node. Properties described here apply to all +DSI peripherals, but individual bindings may want to define additional, +device-specific properties. Required properties: - reg: The virtual channel number of a DSI peripheral. Must be in the range @@ -49,9 +61,37 @@ case two alternative representations can be chosen: property is the number of the first virtual channel and the second cell is the number of consecutive virtual channels. -Example -------- - +Peripherals with a different control bus +---------------------------------------- + +There are peripherals that have I2C/SPI (or some other non-DSI bus) as the +primary control bus, but are also connected to a DSI bus (mostly for the data +path). Connections between such peripherals and a DSI host can be represented +using the graph bindings [1], [2]. + +Peripherals that support dual channel DSI +----------------------------------------- + +Peripherals with higher bandwidth requirements can be connected to 2 DSI +busses. Each DSI bus/channel drives some portion of the pixel data (generally +left/right half of each line of the display, or even/odd lines of the display). +The graph bindings should be used to represent the multiple DSI busses that are +connected to this peripheral. Each DSI host's output endpoint can be linked to +an input endpoint of the DSI peripheral. + +[1] Documentation/devicetree/bindings/graph.txt +[2] Documentation/devicetree/bindings/media/video-interfaces.txt + +Examples +======== +- (1), (2) and (3) are examples of a DSI host and peripheral on the DSI bus + with different virtual channel configurations. +- (4) is an example of a peripheral on a I2C control bus connected to a + DSI host using of-graph bindings. +- (5) is an example of 2 DSI hosts driving a dual-channel DSI peripheral, + which uses I2C as its primary control bus. + +1) dsi-host { ... @@ -67,6 +107,7 @@ Example ... }; +2) dsi-host { ... @@ -82,6 +123,7 @@ Example ... }; +3) dsi-host { ... @@ -96,3 +138,98 @@ Example ... }; + +4) + i2c-host { + ... + + dsi-bridge@35 { + compatible = "..."; + reg = <0x35>; + + ports { + ... + + port { + bridge_mipi_in: endpoint { + remote-endpoint = <&host_mipi_out>; + }; + }; + }; + }; + }; + + dsi-host { + ... + + ports { + ... + + port { + host_mipi_out: endpoint { + remote-endpoint = <&bridge_mipi_in>; + }; + }; + }; + }; + +5) + i2c-host { + dsi-bridge@35 { + compatible = "..."; + reg = <0x35>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + dsi0_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + + port@1 { + reg = <1>; + dsi1_in: endpoint { + remote-endpoint = <&dsi1_out>; + }; + }; + }; + }; + }; + + dsi0-host { + ... + + /* + * this DSI instance drives the clock for both the host + * controllers + */ + clock-master; + + ports { + ... + + port { + dsi0_out: endpoint { + remote-endpoint = <&dsi0_in>; + }; + }; + }; + }; + + dsi1-host { + ... + + ports { + ... + + port { + dsi1_out: endpoint { + remote-endpoint = <&dsi1_in>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt index dfc743219bd8..9ae946942720 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi.txt +++ b/Documentation/devicetree/bindings/display/msm/dsi.txt @@ -106,6 +106,7 @@ Required properties: - clocks: Phandles to device clocks. See [1] for details on clock bindings. - clock-names: the following clocks are required: * "iface" + * "ref" (only required for new DTS files/entries) For 28nm HPM/LP, 28nm 8960 PHYs: - vddio-supply: phandle to vdd-io regulator device node For 20nm PHY: diff --git a/Documentation/devicetree/bindings/display/msm/gmu.txt b/Documentation/devicetree/bindings/display/msm/gmu.txt new file mode 100644 index 000000000000..3439b38e60f2 --- /dev/null +++ b/Documentation/devicetree/bindings/display/msm/gmu.txt @@ -0,0 +1,59 @@ +Qualcomm adreno/snapdragon GMU (Graphics management unit) + +The GMU is a programmable power controller for the GPU. the CPU controls the +GMU which in turn handles power controls for the GPU. + +Required properties: +- compatible: "qcom,adreno-gmu-XYZ.W", "qcom,adreno-gmu" + for example: "qcom,adreno-gmu-630.2", "qcom,adreno-gmu" + Note that you need to list the less specific "qcom,adreno-gmu" + for generic matches and the more specific identifier to identify + the specific device. +- reg: Physical base address and length of the GMU registers. +- reg-names: Matching names for the register regions + * "gmu" + * "gmu_pdc" + * "gmu_pdc_seg" +- interrupts: The interrupt signals from the GMU. +- interrupt-names: Matching names for the interrupts + * "hfi" + * "gmu" +- clocks: phandles to the device clocks +- clock-names: Matching names for the clocks + * "gmu" + * "cxo" + * "axi" + * "mnoc" +- power-domains: should be <&clock_gpucc GPU_CX_GDSC> +- iommus: phandle to the adreno iommu +- operating-points-v2: phandle to the OPP operating points + +Example: + +/ { + ... + + gmu: gmu@506a000 { + compatible="qcom,adreno-gmu-630.2", "qcom,adreno-gmu"; + + reg = <0x506a000 0x30000>, + <0xb280000 0x10000>, + <0xb480000 0x10000>; + reg-names = "gmu", "gmu_pdc", "gmu_pdc_seq"; + + interrupts = <GIC_SPI 304 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 305 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "hfi", "gmu"; + + clocks = <&gpucc GPU_CC_CX_GMU_CLK>, + <&gpucc GPU_CC_CXO_CLK>, + <&gcc GCC_DDRSS_GPU_AXI_CLK>, + <&gcc GCC_GPU_MEMNOC_GFX_CLK>; + clock-names = "gmu", "cxo", "axi", "memnoc"; + + power-domains = <&gpucc GPU_CX_GDSC>; + iommus = <&adreno_smmu 5>; + + operating-points-v2 = <&gmu_opp_table>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/msm/gpu.txt b/Documentation/devicetree/bindings/display/msm/gpu.txt index 43fac0fe09bb..aad1aef682f7 100644 --- a/Documentation/devicetree/bindings/display/msm/gpu.txt +++ b/Documentation/devicetree/bindings/display/msm/gpu.txt @@ -1,21 +1,32 @@ Qualcomm adreno/snapdragon GPU Required properties: -- compatible: "qcom,adreno-XYZ.W", "qcom,adreno" +- compatible: "qcom,adreno-XYZ.W", "qcom,adreno" or + "amd,imageon-XYZ.W", "amd,imageon" 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. + If "amd,imageon" is used, there should be no top level msm device. - reg: Physical base address and length of the controller's registers. - interrupts: The interrupt signal from the gpu. -- clocks: device clocks +- clocks: device clocks (if applicable) See ../clocks/clock-bindings.txt for details. -- clock-names: the following clocks are required: +- clock-names: the following clocks are required by a3xx, a4xx and a5xx + cores: * "core" * "iface" * "mem_iface" + For GMU attached devices the GPU clocks are not used and are not required. The + following devices should not list clocks: + - qcom,adreno-630.2 +- iommus: optional phandle to an adreno iommu instance +- operating-points-v2: optional phandle to the OPP operating points +- qcom,gmu: For GMU attached devices a phandle to the GMU device that will + control the power for the GPU. Applicable targets: + - qcom,adreno-630.2 -Example: +Example 3xx/4xx/a5xx: / { ... @@ -25,7 +36,6 @@ Example: reg = <0x04300000 0x20000>; reg-names = "kgsl_3d0_reg_memory"; interrupts = <GIC_SPI 80 0>; - interrupt-names = "kgsl_3d0_irq"; clock-names = "core", "iface", @@ -36,3 +46,30 @@ Example: <&mmcc MMSS_IMEM_AHB_CLK>; }; }; + +Example a6xx (with GMU): + +/ { + ... + + gpu@5000000 { + compatible = "qcom,adreno-630.2", "qcom,adreno"; + #stream-id-cells = <16>; + + reg = <0x5000000 0x40000>, <0x509e000 0x10>; + reg-names = "kgsl_3d0_reg_memory", "cx_mem"; + + /* + * Look ma, no clocks! The GPU clocks and power are + * controlled entirely by the GMU + */ + + interrupts = <GIC_SPI 300 IRQ_TYPE_LEVEL_HIGH>; + + iommus = <&adreno_smmu 0>; + + operating-points-v2 = <&gpu_opp_table>; + + qcom,gmu = <&gmu>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/msm/mdp4.txt b/Documentation/devicetree/bindings/display/msm/mdp4.txt index 3c341a15ccdc..b07eeb38f709 100644 --- a/Documentation/devicetree/bindings/display/msm/mdp4.txt +++ b/Documentation/devicetree/bindings/display/msm/mdp4.txt @@ -38,6 +38,8 @@ Required properties: Optional properties: - clock-names: the following clocks are optional: * "lut_clk" +- qcom,lcdc-align-lsb: Boolean value indicating that LSB alignment should be + used for LCDC. This is only valid for 18bpp panels. Example: diff --git a/Documentation/devicetree/bindings/display/panel/auo,g101evn010.txt b/Documentation/devicetree/bindings/display/panel/auo,g101evn010.txt new file mode 100644 index 000000000000..bc6a0c858e23 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/auo,g101evn010.txt @@ -0,0 +1,12 @@ +AU Optronics Corporation 10.1" (1280x800) color TFT LCD panel + +Required properties: +- compatible: should be "auo,g101evn010" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +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/bananapi,s070wv20-ct16.txt b/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.txt new file mode 100644 index 000000000000..35bc0c839f49 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/bananapi,s070wv20-ct16.txt @@ -0,0 +1,12 @@ +Banana Pi 7" (S070WV20-CT16) TFT LCD Panel + +Required properties: +- compatible: should be "bananapi,s070wv20-ct16" +- power-supply: see ./panel-common.txt + +Optional properties: +- enable-gpios: see ./simple-panel.txt +- backlight: see ./simple-panel.txt + +This binding is compatible with the simple-panel binding, which is specified +in ./simple-panel.txt. diff --git a/Documentation/devicetree/bindings/display/panel/cdtech,s043wq26h-ct7.txt b/Documentation/devicetree/bindings/display/panel/cdtech,s043wq26h-ct7.txt new file mode 100644 index 000000000000..057f7f3f6dbe --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/cdtech,s043wq26h-ct7.txt @@ -0,0 +1,12 @@ +CDTech(H.K.) Electronics Limited 4.3" 480x272 color TFT-LCD panel + +Required properties: +- compatible: should be "cdtech,s043wq26h-ct7" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +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/cdtech,s070wv95-ct16.txt b/Documentation/devicetree/bindings/display/panel/cdtech,s070wv95-ct16.txt new file mode 100644 index 000000000000..505615dfa0df --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/cdtech,s070wv95-ct16.txt @@ -0,0 +1,12 @@ +CDTech(H.K.) Electronics Limited 7" 800x480 color TFT-LCD panel + +Required properties: +- compatible: should be "cdtech,s070wv95-ct16" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +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/dlc,dlc1010gig.txt b/Documentation/devicetree/bindings/display/panel/dlc,dlc1010gig.txt new file mode 100644 index 000000000000..fbf5dcd15661 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/dlc,dlc1010gig.txt @@ -0,0 +1,12 @@ +DLC Display Co. DLC1010GIG 10.1" WXGA TFT LCD Panel + +Required properties: +- compatible: should be "dlc,dlc1010gig" +- power-supply: See simple-panel.txt + +Optional properties: +- enable-gpios: See simple-panel.txt +- backlight: See simple-panel.txt + +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/innolux,ee101ia-01d.txt b/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.txt new file mode 100644 index 000000000000..e5ca4ccd55ed --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/innolux,ee101ia-01d.txt @@ -0,0 +1,7 @@ +Innolux Corporation 10.1" EE101IA-01D WXGA (1280x800) LVDS panel + +Required properties: +- compatible: should be "innolux,ee101ia-01d" + +This binding is compatible with the lvds-panel binding, which is specified +in panel-lvds.txt in this directory. diff --git a/Documentation/devicetree/bindings/display/panel/innolux,tv123wam.txt b/Documentation/devicetree/bindings/display/panel/innolux,p120zdg-bf1.txt index a9b35265fa13..513f03466aba 100644 --- a/Documentation/devicetree/bindings/display/panel/innolux,tv123wam.txt +++ b/Documentation/devicetree/bindings/display/panel/innolux,p120zdg-bf1.txt @@ -1,20 +1,22 @@ -Innolux TV123WAM 12.3 inch eDP 2K display panel +Innolux P120ZDG-BF1 12.02 inch eDP 2K display panel This binding is compatible with the simple-panel binding, which is specified in simple-panel.txt in this directory. Required properties: -- compatible: should be "innolux,tv123wam" +- compatible: should be "innolux,p120zdg-bf1" - power-supply: regulator to provide the supply voltage Optional properties: - enable-gpios: GPIO pin to enable or disable the panel - backlight: phandle of the backlight device attached to the panel +- no-hpd: If HPD isn't hooked up; add this property. Example: panel_edp: panel-edp { - compatible = "innolux,tv123wam"; + compatible = "innolux,p120zdg-bf1"; enable-gpios = <&msmgpio 31 GPIO_ACTIVE_LOW>; power-supply = <&pm8916_l2>; backlight = <&backlight>; + no-hpd; }; diff --git a/Documentation/devicetree/bindings/display/panel/lemaker,bl035-rgb-002.txt b/Documentation/devicetree/bindings/display/panel/lemaker,bl035-rgb-002.txt new file mode 100644 index 000000000000..74ee7ea6b493 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/lemaker,bl035-rgb-002.txt @@ -0,0 +1,12 @@ +LeMaker BL035-RGB-002 3.5" QVGA TFT LCD panel + +Required properties: +- compatible: should be "lemaker,bl035-rgb-002" +- power-supply: as specified in the base binding + +Optional properties: +- backlight: as specified in the base binding +- enable-gpios: as specified in the base binding + +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/olimex,lcd-olinuxino.txt b/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.txt new file mode 100644 index 000000000000..a89f9c830a85 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/olimex,lcd-olinuxino.txt @@ -0,0 +1,42 @@ +Binding for Olimex Ltd. LCD-OLinuXino bridge panel. + +This device can be used as bridge between a host controller and LCD panels. +Currently supported LCDs are: + - LCD-OLinuXino-4.3TS + - LCD-OLinuXino-5 + - LCD-OLinuXino-7 + - LCD-OLinuXino-10 + +The panel itself contains: + - AT24C16C EEPROM holding panel identification and timing requirements + - AR1021 resistive touch screen controller (optional) + - FT5x6 capacitive touch screnn controller (optional) + - GT911/GT928 capacitive touch screen controller (optional) + +The above chips share same I2C bus. The EEPROM is factory preprogrammed with +device information (id, serial, etc.) and timing requirements. + +Touchscreen bingings can be found in these files: + - input/touchscreen/goodix.txt + - input/touchscreen/edt-ft5x06.txt + - input/touchscreen/ar1021.txt + +Required properties: + - compatible: should be "olimex,lcd-olinuxino" + - reg: address of the configuration EEPROM, should be <0x50> + - power-supply: phandle of the regulator that provides the supply voltage + +Optional properties: + - enable-gpios: GPIO pin to enable or disable the panel + - backlight: phandle of the backlight device attacked to the panel + +Example: +&i2c2 { + panel@50 { + compatible = "olimex,lcd-olinuxino"; + reg = <0x50>; + power-supply = <®_vcc5v0>; + enable-gpios = <&pio 7 8 GPIO_ACTIVE_HIGH>; + backlight = <&backlight>; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt b/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt new file mode 100644 index 000000000000..1639fb17a9f0 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/pda,91-00156-a0.txt @@ -0,0 +1,14 @@ +PDA 91-00156-A0 5.0" WVGA TFT LCD panel + +Required properties: +- compatible: should be "pda,91-00156-a0" +- power-supply: this panel requires a single power supply. A phandle to a +regulator needs to be specified here. Compatible with panel-common binding which +is specified in the panel-common.txt in this directory. +- backlight: this panel's backlight is controlled by an external backlight +controller. A phandle to this controller needs to be specified here. +Compatible with panel-common binding which is specified in the panel-common.txt +in this directory. + +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/samsung,s6d16d0.txt b/Documentation/devicetree/bindings/display/panel/samsung,s6d16d0.txt new file mode 100644 index 000000000000..b94e366f451b --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/samsung,s6d16d0.txt @@ -0,0 +1,30 @@ +Samsung S6D16D0 4" 864x480 AMOLED panel + +Required properties: + - compatible: should be: + "samsung,s6d16d0", + - reg: the virtual channel number of a DSI peripheral + - vdd1-supply: I/O voltage supply + - reset-gpios: a GPIO spec for the reset pin (active low) + +The device node can contain one 'port' child node with one child +'endpoint' node, according to the bindings defined in +media/video-interfaces.txt. This node should describe panel's video bus. + +Example: +&dsi { + ... + + panel@0 { + compatible = "samsung,s6d16d0"; + reg = <0>; + vdd1-supply = <&foo>; + reset-gpios = <&foo_gpio 0 GPIO_ACTIVE_LOW>; + + port { + panel_in: endpoint { + remote-endpoint = <&dsi_out>; + }; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/display/panel/simple-panel.txt b/Documentation/devicetree/bindings/display/panel/simple-panel.txt index 45a457ad38f0..b2b872c710f2 100644 --- a/Documentation/devicetree/bindings/display/panel/simple-panel.txt +++ b/Documentation/devicetree/bindings/display/panel/simple-panel.txt @@ -11,6 +11,9 @@ Optional properties: - ddc-i2c-bus: phandle of an I2C controller used for DDC EDID probing - enable-gpios: GPIO pin to enable or disable the panel - backlight: phandle of the backlight device attached to the panel +- no-hpd: This panel is supposed to communicate that it's ready via HPD + (hot plug detect) signal, but the signal isn't hooked up so we should + hardcode the max delay from the panel spec when powering up the panel. Example: diff --git a/Documentation/devicetree/bindings/display/panel/sitronix,st7701.txt b/Documentation/devicetree/bindings/display/panel/sitronix,st7701.txt new file mode 100644 index 000000000000..ccd17597f1f6 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/sitronix,st7701.txt @@ -0,0 +1,30 @@ +Sitronix ST7701 based LCD panels + +ST7701 designed for small and medium sizes of TFT LCD display, is +capable of supporting up to 480RGBX864 in resolution. It provides +several system interfaces like MIPI/RGB/SPI. + +Techstar TS8550B is 480x854, 2-lane MIPI DSI LCD panel which has +inbuilt ST7701 chip. + +Required properties: +- compatible: must be "sitronix,st7701" and one of + * "techstar,ts8550b" +- reset-gpios: a GPIO phandle for the reset pin + +Required properties for techstar,ts8550b: +- reg: DSI virtual channel used by that screen +- VCC-supply: analog regulator for MIPI circuit +- IOVCC-supply: I/O system regulator + +Optional properties: +- backlight: phandle for the backlight control. + +panel@0 { + compatible = "techstar,ts8550b", "sitronix,st7701"; + reg = <0>; + VCC-supply = <®_dldo2>; + IOVCC-supply = <®_dldo2>; + reset-gpios = <&pio 3 24 GPIO_ACTIVE_HIGH>; /* LCD-RST: PD24 */ + backlight = <&backlight>; +}; diff --git a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt index f5e3c6f2095a..40f3d7c713bb 100644 --- a/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt +++ b/Documentation/devicetree/bindings/display/panel/tpo,tpg110.txt @@ -1,47 +1,70 @@ TPO TPG110 Panel ================ -This binding builds on the DPI bindings, adding a few properties -as a superset of a DPI. See panel-dpi.txt for the required DPI -bindings. +This panel driver is a component that acts as an intermediary +between an RGB output and a variety of panels. The panel +driver is strapped up in electronics to the desired resolution +and other properties, and has a control interface over 3WIRE +SPI. By talking to the TPG110 over SPI, the strapped properties +can be discovered and the hardware is therefore mostly +self-describing. + + +--------+ +SPI -> | TPO | -> physical display +RGB -> | TPG110 | + +--------+ + +If some electrical strap or alternate resolution is desired, +this can be set up by taking software control of the display +over the SPI interface. The interface can also adjust +for properties of the display such as gamma correction and +certain electrical driving levels. + +The TPG110 does not know the physical dimensions of the panel +connected, so this needs to be specified in the device tree. + +It requires a GPIO line for control of its reset line. + +The serial protocol has line names that resemble I2C but the +protocol is not I2C but 3WIRE SPI. Required properties: -- compatible : "tpo,tpg110" +- compatible : one of: + "ste,nomadik-nhk15-display", "tpo,tpg110" + "tpo,tpg110" - grestb-gpios : panel reset GPIO -- scen-gpios : serial control enable GPIO -- scl-gpios : serial control clock line GPIO -- sda-gpios : serial control data line GPIO +- width-mm : see display/panel/panel-common.txt +- height-mm : see display/panel/panel-common.txt + +The device needs to be a child of an SPI bus, see +spi/spi-bus.txt. The SPI child must set the following +properties: +- spi-3wire +- spi-max-frequency = <3000000>; +as these are characteristics of this device. -Required nodes: -- Video port for DPI input, see panel-dpi.txt -- Panel timing for DPI setup, see panel-dpi.txt +The device node can contain one 'port' child node with one child +'endpoint' node, according to the bindings defined in +media/video-interfaces.txt. This node should describe panel's video bus. Example ------- -panel { - compatible = "tpo,tpg110", "panel-dpi"; - grestb-gpios = <&stmpe_gpio44 5 GPIO_ACTIVE_LOW>; - scen-gpios = <&gpio0 6 GPIO_ACTIVE_LOW>; - scl-gpios = <&gpio0 5 GPIO_ACTIVE_HIGH>; - sda-gpios = <&gpio0 4 GPIO_ACTIVE_HIGH>; +panel: display@0 { + compatible = "tpo,tpg110"; + reg = <0>; + spi-3wire; + /* 320 ns min period ~= 3 MHz */ + spi-max-frequency = <3000000>; + /* Width and height from data sheet */ + width-mm = <116>; + height-mm = <87>; + grestb-gpios = <&foo_gpio 5 GPIO_ACTIVE_LOW>; backlight = <&bl>; port { nomadik_clcd_panel: endpoint { - remote-endpoint = <&nomadik_clcd_pads>; + remote-endpoint = <&foo>; }; }; - - panel-timing { - clock-frequency = <33200000>; - hactive = <800>; - hback-porch = <216>; - hfront-porch = <40>; - hsync-len = <1>; - vactive = <480>; - vback-porch = <35>; - vfront-porch = <10>; - vsync-len = <1>; - }; }; diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt index ec9d34be2ff7..aedb22b4d161 100644 --- a/Documentation/devicetree/bindings/display/renesas,du.txt +++ b/Documentation/devicetree/bindings/display/renesas,du.txt @@ -4,7 +4,10 @@ Required Properties: - compatible: must be one of the following. - "renesas,du-r8a7743" for R8A7743 (RZ/G1M) compatible DU + - "renesas,du-r8a7744" for R8A7744 (RZ/G1N) compatible DU - "renesas,du-r8a7745" for R8A7745 (RZ/G1E) compatible DU + - "renesas,du-r8a77470" for R8A77470 (RZ/G1C) compatible DU + - "renesas,du-r8a774c0" for R8A774C0 (RZ/G2E) compatible DU - "renesas,du-r8a7779" for R8A7779 (R-Car H1) compatible DU - "renesas,du-r8a7790" for R8A7790 (R-Car H2) compatible DU - "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU @@ -15,6 +18,8 @@ Required Properties: - "renesas,du-r8a7796" for R8A7796 (R-Car M3-W) compatible DU - "renesas,du-r8a77965" for R8A77965 (R-Car M3-N) compatible DU - "renesas,du-r8a77970" for R8A77970 (R-Car V3M) compatible DU + - "renesas,du-r8a77980" for R8A77980 (R-Car V3H) compatible DU + - "renesas,du-r8a77990" for R8A77990 (R-Car E3) compatible DU - "renesas,du-r8a77995" for R8A77995 (R-Car D3) compatible DU - reg: the memory-mapped I/O registers base address and length @@ -50,7 +55,10 @@ corresponding to each DU output. Port0 Port1 Port2 Port3 ----------------------------------------------------------------------------- R8A7743 (RZ/G1M) DPAD 0 LVDS 0 - - + R8A7744 (RZ/G1N) DPAD 0 LVDS 0 - - R8A7745 (RZ/G1E) DPAD 0 DPAD 1 - - + R8A77470 (RZ/G1C) DPAD 0 DPAD 1 LVDS 0 - + R8A774C0 (RZ/G2E) DPAD 0 LVDS 0 LVDS 1 - R8A7779 (R-Car H1) DPAD 0 DPAD 1 - - R8A7790 (R-Car H2) DPAD 0 LVDS 0 LVDS 1 - R8A7791 (R-Car M2-W) DPAD 0 LVDS 0 - - @@ -61,6 +69,8 @@ corresponding to each DU output. R8A7796 (R-Car M3-W) DPAD 0 HDMI 0 LVDS 0 - R8A77965 (R-Car M3-N) DPAD 0 HDMI 0 LVDS 0 - R8A77970 (R-Car V3M) DPAD 0 LVDS 0 - - + R8A77980 (R-Car V3H) DPAD 0 LVDS 0 - - + R8A77990 (R-Car E3) DPAD 0 LVDS 0 LVDS 1 - R8A77995 (R-Car D3) DPAD 0 LVDS 0 LVDS 1 - diff --git a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt index adc94fc3c9f8..39143424a474 100644 --- a/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt +++ b/Documentation/devicetree/bindings/display/rockchip/dw_hdmi-rockchip.txt @@ -13,6 +13,7 @@ Required properties: - compatible: should be one of the following: "rockchip,rk3288-dw-hdmi" + "rockchip,rk3328-dw-hdmi" "rockchip,rk3399-dw-hdmi" - reg: See dw_hdmi.txt. - reg-io-width: See dw_hdmi.txt. Shall be 4. @@ -34,6 +35,8 @@ Optional properties - clock-names: May contain "cec" as defined in dw_hdmi.txt. - clock-names: May contain "grf", power for grf io. - clock-names: May contain "vpll", external clock for some hdmi phy. +- phys: from general PHY binding: the phandle for the PHY device. +- phy-names: Should be "hdmi" if phys references an external phy. Example: diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt index eeda3597011e..4f58c5a2d195 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip-vop.txt @@ -8,6 +8,10 @@ Required properties: - compatible: value should be one of the following "rockchip,rk3036-vop"; "rockchip,rk3126-vop"; + "rockchip,px30-vop-lit"; + "rockchip,px30-vop-big"; + "rockchip,rk3066-vop"; + "rockchip,rk3188-vop"; "rockchip,rk3288-vop"; "rockchip,rk3368-vop"; "rockchip,rk3366-vop"; diff --git a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt index f8773ecb7525..31ab72cba3d4 100644 --- a/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt +++ b/Documentation/devicetree/bindings/display/sunxi/sun4i-drm.txt @@ -78,6 +78,8 @@ Required properties: - compatible: value must be one of: * "allwinner,sun8i-a83t-dw-hdmi" + * "allwinner,sun50i-a64-dw-hdmi", "allwinner,sun8i-a83t-dw-hdmi" + * "allwinner,sun50i-h6-dw-hdmi" - reg: base address and size of memory-mapped region - reg-io-width: See dw_hdmi.txt. Shall be 1. - interrupts: HDMI interrupt number @@ -85,9 +87,14 @@ Required properties: * iahb: the HDMI bus clock * isfr: the HDMI register clock * tmds: TMDS clock + * cec: HDMI CEC clock (H6 only) + * hdcp: HDCP clock (H6 only) + * hdcp-bus: HDCP bus clock (H6 only) - clock-names: the clock names mentioned above - - resets: phandle to the reset controller - - reset-names: must be "ctrl" + - resets: + * ctrl: HDMI controller reset + * hdcp: HDCP reset (H6 only) + - reset-names: reset names mentioned above - phys: phandle to the DWC HDMI PHY - phy-names: must be "phy" @@ -96,6 +103,9 @@ Required properties: first port should be the input endpoint. The second should be the output, usually to an HDMI connector. +Optional properties: + - hvcc-supply: the VCC power supply of the controller + DWC HDMI PHY ------------ @@ -103,7 +113,9 @@ Required properties: - compatible: value must be one of: * allwinner,sun8i-a83t-hdmi-phy * allwinner,sun8i-h3-hdmi-phy + * allwinner,sun8i-r40-hdmi-phy * allwinner,sun50i-a64-hdmi-phy + * allwinner,sun50i-h6-hdmi-phy - reg: base address and size of memory-mapped region - clocks: phandles to the clocks feeding the HDMI PHY * bus: the HDMI PHY interface clock @@ -112,9 +124,9 @@ Required properties: - resets: phandle to the reset controller driving the PHY - reset-names: must be "phy" -H3 and A64 HDMI PHY require additional clocks: +H3, A64 and R40 HDMI PHY require additional clocks: - pll-0: parent of phy clock - - pll-1: second possible phy clock parent (A64 only) + - pll-1: second possible phy clock parent (A64/R40 only) TV Encoder ---------- @@ -144,6 +156,7 @@ Required properties: * allwinner,sun6i-a31-tcon * allwinner,sun6i-a31s-tcon * allwinner,sun7i-a20-tcon + * allwinner,sun8i-a23-tcon * allwinner,sun8i-a33-tcon * allwinner,sun8i-a83t-tcon-lcd * allwinner,sun8i-a83t-tcon-tv @@ -151,6 +164,9 @@ Required properties: * allwinner,sun8i-v3s-tcon * allwinner,sun9i-a80-tcon-lcd * allwinner,sun9i-a80-tcon-tv + * "allwinner,sun50i-a64-tcon-lcd", "allwinner,sun8i-a83t-tcon-lcd" + * "allwinner,sun50i-a64-tcon-tv", "allwinner,sun8i-a83t-tcon-tv" + * allwinner,sun50i-h6-tcon-tv, allwinner,sun8i-r40-tcon-tv - reg: base address and size of memory-mapped region - interrupts: interrupt associated to this IP - clocks: phandles to the clocks feeding the TCON. @@ -213,24 +229,26 @@ It allows display pipeline to be configured in very different ways: \ [3] TCON-TV1 [1] - TVE1/RGB Note that both TCON TOP references same physical unit. Both mixers can be -connected to any TCON. +connected to any TCON. Not all TCON TOP variants support all features. Required properties: - compatible: value must be one of: * allwinner,sun8i-r40-tcon-top + * allwinner,sun50i-h6-tcon-top - reg: base address and size of the memory-mapped region. - clocks: phandle to the clocks feeding the TCON TOP * bus: TCON TOP interface clock * tcon-tv0: TCON TV0 clock - * tve0: TVE0 clock - * tcon-tv1: TCON TV1 clock - * tve1: TVE0 clock - * dsi: MIPI DSI clock + * tve0: TVE0 clock (R40 only) + * tcon-tv1: TCON TV1 clock (R40 only) + * tve1: TVE0 clock (R40 only) + * dsi: MIPI DSI clock (R40 only) - clock-names: clock name mentioned above - resets: phandle to the reset line driving the TCON TOP - #clock-cells : must contain 1 - clock-output-names: Names of clocks created for TCON TV0 channel clock, - TCON TV1 channel clock and DSI channel clock, in that order. + TCON TV1 channel clock (R40 only) and DSI channel clock (R40 only), in + that order. - ports: A ports node with endpoint definitions as defined in Documentation/devicetree/bindings/media/video-interfaces.txt. 6 ports should @@ -259,6 +277,7 @@ Required properties: - compatible: value must be one of: * allwinner,sun6i-a31-drc * allwinner,sun6i-a31s-drc + * allwinner,sun8i-a23-drc * allwinner,sun8i-a33-drc * allwinner,sun9i-a80-drc - reg: base address and size of the memory-mapped region. @@ -286,6 +305,7 @@ Required properties: * allwinner,sun5i-a13-display-backend * allwinner,sun6i-a31-display-backend * allwinner,sun7i-a20-display-backend + * allwinner,sun8i-a23-display-backend * allwinner,sun8i-a33-display-backend * allwinner,sun9i-a80-display-backend - reg: base address and size of the memory-mapped region. @@ -343,6 +363,7 @@ Required properties: * allwinner,sun5i-a13-display-frontend * allwinner,sun6i-a31-display-frontend * allwinner,sun7i-a20-display-frontend + * allwinner,sun8i-a23-display-frontend * allwinner,sun8i-a33-display-frontend * allwinner,sun9i-a80-display-frontend - reg: base address and size of the memory-mapped region. @@ -369,7 +390,12 @@ Required properties: * allwinner,sun8i-a83t-de2-mixer-0 * allwinner,sun8i-a83t-de2-mixer-1 * allwinner,sun8i-h3-de2-mixer-0 + * allwinner,sun8i-r40-de2-mixer-0 + * allwinner,sun8i-r40-de2-mixer-1 * allwinner,sun8i-v3s-de2-mixer + * allwinner,sun50i-a64-de2-mixer-0 + * allwinner,sun50i-a64-de2-mixer-1 + * allwinner,sun50i-h6-de3-mixer-0 - reg: base address and size of the memory-mapped region. - clocks: phandles to the clocks feeding the mixer * bus: the mixer interface clock @@ -397,15 +423,18 @@ Required properties: * allwinner,sun6i-a31-display-engine * allwinner,sun6i-a31s-display-engine * allwinner,sun7i-a20-display-engine + * allwinner,sun8i-a23-display-engine * allwinner,sun8i-a33-display-engine * allwinner,sun8i-a83t-display-engine * allwinner,sun8i-h3-display-engine * allwinner,sun8i-r40-display-engine * allwinner,sun8i-v3s-display-engine * allwinner,sun9i-a80-display-engine + * allwinner,sun50i-a64-display-engine + * allwinner,sun50i-h6-display-engine - allwinner,pipelines: list of phandle to the display engine - frontends (DE 1.0) or mixers (DE 2.0) available. + frontends (DE 1.0) or mixers (DE 2.0/3.0) available. Example: diff --git a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt index 593be44a53c9..9999255ac5b6 100644 --- a/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt +++ b/Documentation/devicetree/bindings/display/tegra/nvidia,tegra20-host1x.txt @@ -238,6 +238,9 @@ of the following host1x client modules: - nvidia,hpd-gpio: specifies a GPIO used for hotplug detection - nvidia,edid: supplies a binary EDID blob - nvidia,panel: phandle of a display panel + - nvidia,xbar-cfg: 5 cells containing the crossbar configuration. Each lane + of the SOR, identified by the cell's index, is mapped via the crossbar to + the pad specified by the cell's value. Optional properties when driving an eDP output: - nvidia,dpaux: phandle to a DispayPort AUX interface diff --git a/Documentation/devicetree/bindings/display/truly,nt35597.txt b/Documentation/devicetree/bindings/display/truly,nt35597.txt new file mode 100644 index 000000000000..f39c77ee36ea --- /dev/null +++ b/Documentation/devicetree/bindings/display/truly,nt35597.txt @@ -0,0 +1,59 @@ +Truly model NT35597 DSI display driver + +The Truly NT35597 is a generic display driver, currently only configured +for use in the 2K display on the Qualcomm SDM845 MTP board. + +Required properties: +- compatible: should be "truly,nt35597-2K-display" +- vdda-supply: phandle of the regulator that provides the supply voltage + Power IC supply +- vdispp-supply: phandle of the regulator that provides the supply voltage + for positive LCD bias +- vdispn-supply: phandle of the regulator that provides the supply voltage + for negative LCD bias +- reset-gpios: phandle of gpio for reset line + This should be 8mA, gpio can be configured using mux, pinctrl, pinctrl-names + (active low) +- mode-gpios: phandle of the gpio for choosing the mode of the display + for single DSI or Dual DSI + This should be low for dual DSI and high for single DSI mode +- ports: This device has two video ports driven by two DSIs. Their connections + are modeled using the OF graph bindings specified in + Documentation/devicetree/bindings/graph.txt. + - port@0: DSI input port driven by master DSI + - port@1: DSI input port driven by secondary DSI + +Example: + + dsi@ae94000 { + panel@0 { + compatible = "truly,nt35597-2K-display"; + reg = <0>; + vdda-supply = <&pm8998_l14>; + vdispp-supply = <&lab_regulator>; + vdispn-supply = <&ibb_regulator>; + pinctrl-names = "default", "suspend"; + pinctrl-0 = <&dpu_dsi_active>; + pinctrl-1 = <&dpu_dsi_suspend>; + + reset-gpios = <&tlmm 6 GPIO_ACTIVE_LOW>; + mode-gpios = <&tlmm 52 GPIO_ACTIVE_HIGH>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + panel0_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + + port@1 { + reg = <1>; + panel1_in: endpoint { + remote-endpoint = <&dsi1_out>; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt b/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt new file mode 100644 index 000000000000..3fe0961bcf64 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/8250_mtk_dma.txt @@ -0,0 +1,33 @@ +* Mediatek UART APDMA Controller + +Required properties: +- compatible should contain: + * "mediatek,mt2712-uart-dma" for MT2712 compatible APDMA + * "mediatek,mt6577-uart-dma" for MT6577 and all of the above + +- reg: The base address of the APDMA register bank. + +- interrupts: A single interrupt specifier. + +- clocks : Must contain an entry for each entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: The APDMA clock for register accesses + +Examples: + + apdma: dma-controller@11000380 { + compatible = "mediatek,mt2712-uart-dma"; + reg = <0 0x11000380 0 0x400>; + interrupts = <GIC_SPI 63 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 64 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 65 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 66 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 67 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 68 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 69 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 70 IRQ_TYPE_LEVEL_LOW>; + clocks = <&pericfg CLK_PERI_AP_DMA>; + clock-names = "apdma"; + #dma-cells = <1>; + }; + diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt index a5a7c3f5a1e3..5a512c5ea76a 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt @@ -1,6 +1,6 @@ * Renesas R-Car (RZ/G) DMA Controller Device Tree bindings -Renesas R-Car Generation 2 SoCs have multiple multi-channel DMA +Renesas R-Car (Gen 2/3) and RZ/G SoCs have multiple multi-channel DMA controller instances named DMAC capable of serving multiple clients. Channels can be dedicated to specific clients or shared between a large number of clients. @@ -20,6 +20,8 @@ Required Properties: - "renesas,dmac-r8a7744" (RZ/G1N) - "renesas,dmac-r8a7745" (RZ/G1E) - "renesas,dmac-r8a77470" (RZ/G1C) + - "renesas,dmac-r8a774a1" (RZ/G2M) + - "renesas,dmac-r8a774c0" (RZ/G2E) - "renesas,dmac-r8a7790" (R-Car H2) - "renesas,dmac-r8a7791" (R-Car M2-W) - "renesas,dmac-r8a7792" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt index 1743017bd948..372f0eeb5a2a 100644 --- a/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt +++ b/Documentation/devicetree/bindings/dma/renesas,usb-dmac.txt @@ -6,6 +6,9 @@ Required Properties: - "renesas,r8a7743-usb-dmac" (RZ/G1M) - "renesas,r8a7744-usb-dmac" (RZ/G1N) - "renesas,r8a7745-usb-dmac" (RZ/G1E) + - "renesas,r8a77470-usb-dmac" (RZ/G1C) + - "renesas,r8a774a1-usb-dmac" (RZ/G2M) + - "renesas,r8a774c0-usb-dmac" (RZ/G2E) - "renesas,r8a7790-usb-dmac" (R-Car H2) - "renesas,r8a7791-usb-dmac" (R-Car M2-W) - "renesas,r8a7793-usb-dmac" (R-Car M2-N) diff --git a/Documentation/devicetree/bindings/dma/snps-dma.txt b/Documentation/devicetree/bindings/dma/snps-dma.txt index 39e2b26be344..db757df7057d 100644 --- a/Documentation/devicetree/bindings/dma/snps-dma.txt +++ b/Documentation/devicetree/bindings/dma/snps-dma.txt @@ -27,6 +27,10 @@ Optional properties: general purpose DMA channel allocator. False if not passed. - multi-block: Multi block transfers supported by hardware. Array property with one cell per channel. 0: not supported, 1 (default): supported. +- snps,dma-protection-control: AHB HPROT[3:1] protection setting. + The default value is 0 (for non-cacheable, non-buffered, + unprivileged data access). + Refer to include/dt-bindings/dma/dw-dmac.h for possible values. Example: diff --git a/Documentation/devicetree/bindings/dma/uniphier-mio-dmac.txt b/Documentation/devicetree/bindings/dma/uniphier-mio-dmac.txt new file mode 100644 index 000000000000..b12388dc7eac --- /dev/null +++ b/Documentation/devicetree/bindings/dma/uniphier-mio-dmac.txt @@ -0,0 +1,25 @@ +UniPhier Media IO DMA controller + +This works as an external DMA engine for SD/eMMC controllers etc. +found in UniPhier LD4, Pro4, sLD8 SoCs. + +Required properties: +- compatible: should be "socionext,uniphier-mio-dmac". +- reg: offset and length of the register set for the device. +- interrupts: a list of interrupt specifiers associated with the DMA channels. +- clocks: a single clock specifier. +- #dma-cells: should be <1>. The single cell represents the channel index. + +Example: + dmac: dma-controller@5a000000 { + compatible = "socionext,uniphier-mio-dmac"; + reg = <0x5a000000 0x1000>; + interrupts = <0 68 4>, <0 68 4>, <0 69 4>, <0 70 4>, + <0 71 4>, <0 72 4>, <0 73 4>, <0 74 4>; + clocks = <&mio_clk 7>; + #dma-cells = <1>; + }; + +Note: +In the example above, "interrupts = <0 68 4>, <0 68 4>, ..." is not a typo. +The first two channels share a single interrupt line. diff --git a/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt new file mode 100644 index 000000000000..6a0f3d90d682 --- /dev/null +++ b/Documentation/devicetree/bindings/edac/aspeed-sdram-edac.txt @@ -0,0 +1,25 @@ +Aspeed AST2500 SoC EDAC node + +The Aspeed AST2500 SoC supports DDR3 and DDR4 memory with and without ECC (error +correction check). + +The memory controller supports SECDED (single bit error correction, double bit +error detection) and single bit error auto scrubbing by reserving 8 bits for +every 64 bit word (effectively reducing available memory to 8/9). + +Note, the bootloader must configure ECC mode in the memory controller. + + +Required properties: +- compatible: should be "aspeed,ast2500-sdram-edac" +- reg: sdram controller register set should be <0x1e6e0000 0x174> +- interrupts: should be AVIC interrupt #0 + + +Example: + + edac: sdram@1e6e0000 { + compatible = "aspeed,ast2500-sdram-edac"; + reg = <0x1e6e0000 0x174>; + interrupts = <0>; + }; diff --git a/Documentation/devicetree/bindings/eeprom/at24.txt b/Documentation/devicetree/bindings/eeprom/at24.txt index aededdbc262b..0e456bbc1213 100644 --- a/Documentation/devicetree/bindings/eeprom/at24.txt +++ b/Documentation/devicetree/bindings/eeprom/at24.txt @@ -27,6 +27,7 @@ Required properties: "atmel,24c256", "atmel,24c512", "atmel,24c1024", + "atmel,24c2048", If <manufacturer> is not "atmel", then a fallback must be used with the same <model> and "atmel" as manufacturer. @@ -74,6 +75,8 @@ Optional properties: - address-width: number of address bits (one of 8, 16). + - num-addresses: total number of i2c slave addresses this device takes + Example: eeprom@52 { @@ -81,4 +84,5 @@ eeprom@52 { reg = <0x52>; pagesize = <32>; wp-gpios = <&gpio1 3 0>; + num-addresses = <8>; }; diff --git a/Documentation/devicetree/bindings/example-schema.yaml b/Documentation/devicetree/bindings/example-schema.yaml new file mode 100644 index 000000000000..9175d67f355d --- /dev/null +++ b/Documentation/devicetree/bindings/example-schema.yaml @@ -0,0 +1,170 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +# Copyright 2018 Linaro Ltd. +%YAML 1.2 +--- +# All the top-level keys are standard json-schema keywords except for +# 'maintainers' and 'select' + +# $id is a unique idenifier based on the filename. There may or may not be a +# file present at the URL. +$id: "http://devicetree.org/schemas/example-schema.yaml#" +# $schema is the meta-schema this schema should be validated with. +$schema: "http://devicetree.org/meta-schemas/core.yaml#" + +title: An example schema annotated with jsonschema details + +maintainers: + - Rob Herring <robh@kernel.org> + +description: | + A more detailed multi-line description of the binding. + + Details about the hardware device and any links to datasheets can go here. + + Literal blocks are marked with the '|' at the beginning. The end is marked by + indentation less than the first line of the literal block. Lines also cannot + begin with a tab character. + +select: false + # 'select' is a schema applied to a DT node to determine if this binding + # schema should be applied to the node. It is optional and by default the + # possible compatible strings are extracted and used to match. + + # In this case, a 'false' schema will never match. + +properties: + # A dictionary of DT properties for this binding schema + compatible: + # More complicated schema can use oneOf (XOR), anyOf (OR), or allOf (AND) + # to handle different conditions. + # In this case, it's needed to handle a variable number of values as there + # isn't another way to express a constraint of the last string value. + # The boolean schema must be a list of schemas. + oneOf: + - items: + # items is a list of possible values for the property. The number of + # values is determined by the number of elements in the list. + # Order in lists is significant, order in dicts is not + # Must be one of the 1st enums followed by the 2nd enum + # + # Each element in items should be 'enum' or 'const' + - enum: + - vendor,soc4-ip + - vendor,soc3-ip + - vendor,soc2-ip + - enum: + - vendor,soc1-ip + # additionalItems being false is implied + # minItems/maxItems equal to 2 is implied + - items: + # 'const' is just a special case of an enum with a single possible value + - const: vendor,soc1-ip + + reg: + # The core schema already checks that reg values are numbers, so device + # specific schema don't need to do those checks. + # The description of each element defines the order and implicitly defines + # the number of reg entries. + items: + - description: core registers + - description: aux registers + # minItems/maxItems equal to 2 is implied + + reg-names: + # The core schema enforces this is a string array + items: + - const: core + - const: aux + + clocks: + # Cases that have only a single entry just need to express that with maxItems + maxItems: 1 + description: bus clock + + clock-names: + items: + - const: bus + + interrupts: + # Either 1 or 2 interrupts can be present + minItems: 1 + maxItems: 2 + items: + - description: tx or combined interrupt + - description: rx interrupt + description: + A variable number of interrupts warrants a description of what conditions + affect the number of interrupts. Otherwise, descriptions on standard + properties are not necessary. + + interrupt-names: + # minItems must be specified here because the default would be 2 + minItems: 1 + maxItems: 2 + items: + - const: tx irq + - const: rx irq + + # Property names starting with '#' must be quoted + '#interrupt-cells': + # A simple case where the value must always be '2'. + # The core schema handles that this must be a single integer. + const: 2 + + interrupt-controller: true + # The core checks this is a boolean, so just have to list it here to be + # valid for this binding. + + clock-frequency: + # The type is set in the core schema. Per device schema only need to set + # constraints on the possible values. + minimum: 100 + maximum: 400000 + # The value that should be used if the property is not present + default: 200 + + foo-gpios: + maxItems: 1 + description: A connection of the 'foo' gpio line. + + vendor,int-property: + description: Vendor specific properties must have a description + # 'allOf' is the json-schema way of subclassing a schema. Here the base + # type schema is referenced and then additional constraints on the values + # are added. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - enum: [2, 4, 6, 8, 10] + + vendor,bool-property: + description: Vendor specific properties must have a description + # boolean properties is one case where the json-schema 'type' keyword + # can be used directly + type: boolean + + vendor,string-array-property: + description: Vendor specific properties should reference a type in the + core schema. + allOf: + - $ref: /schemas/types.yaml#/definitions/string-array + - items: + - enum: [ foo, bar ] + - enum: [ baz, boo ] + +required: + - compatible + - reg + - interrupts + - interrupt-controller + +examples: + # Examples are now compiled with dtc + - | + node@1000 { + compatible = "vendor,soc4-ip", "vendor,soc1-ip"; + reg = <0x1000 0x80>, + <0x3000 0x80>; + reg-names = "core", "aux"; + interrupts = <10>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/extcon/extcon-ptn5150.txt b/Documentation/devicetree/bindings/extcon/extcon-ptn5150.txt new file mode 100644 index 000000000000..936fbdf12815 --- /dev/null +++ b/Documentation/devicetree/bindings/extcon/extcon-ptn5150.txt @@ -0,0 +1,27 @@ +* PTN5150 CC (Configuration Channel) Logic device + +PTN5150 is a small thin low power CC logic chip supporting the USB Type-C +connector application with CC control logic detection and indication functions. +It is interfaced to the host controller using an I2C interface. + +Required properties: +- compatible: should be "nxp,ptn5150" +- reg: specifies the I2C slave address of the device +- int-gpio: should contain a phandle and GPIO specifier for the GPIO pin + connected to the PTN5150's INTB pin. +- vbus-gpio: should contain a phandle and GPIO specifier for the GPIO pin which + is used to control VBUS. +- pinctrl-names : a pinctrl state named "default" must be defined. +- pinctrl-0 : phandle referencing pin configuration of interrupt and vbus + control. + +Example: + ptn5150@1d { + compatible = "nxp,ptn5150"; + reg = <0x1d>; + int-gpio = <&msmgpio 78 GPIO_ACTIVE_HIGH>; + vbus-gpio = <&msmgpio 148 GPIO_ACTIVE_HIGH>; + pinctrl-names = "default"; + pinctrl-0 = <&ptn5150_default>; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt b/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt new file mode 100644 index 000000000000..1fa66065acc6 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt @@ -0,0 +1,57 @@ +Intel Service Layer Driver for Stratix10 SoC +============================================ +Intel Stratix10 SoC is composed of a 64 bit quad-core ARM Cortex A53 hard +processor system (HPS) and Secure Device Manager (SDM). When the FPGA is +configured from HPS, there needs to be a way for HPS to notify SDM the +location and size of the configuration data. Then SDM will get the +configuration data from that location and perform the FPGA configuration. + +To meet the whole system security needs and support virtual machine requesting +communication with SDM, only the secure world of software (EL3, Exception +Layer 3) can interface with SDM. All software entities running on other +exception layers must channel through the EL3 software whenever it needs +service from SDM. + +Intel Stratix10 service layer driver, running at privileged exception level +(EL1, Exception Layer 1), interfaces with the service providers and provides +the services for FPGA configuration, QSPI, Crypto and warm reset. Service layer +driver also manages secure monitor call (SMC) to communicate with secure monitor +code running in EL3. + +Required properties: +------------------- +The svc node has the following mandatory properties, must be located under +the firmware node. + +- compatible: "intel,stratix10-svc" +- method: smc or hvc + smc - Secure Monitor Call + hvc - Hypervisor Call +- memory-region: + phandle to the reserved memory node. See + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + for details + +Example: +------- + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + service_reserved: svcbuffer@0 { + compatible = "shared-dma-pool"; + reg = <0x0 0x0 0x0 0x1000000>; + alignment = <0x1000>; + no-map; + }; + }; + + firmware { + svc { + compatible = "intel,stratix10-svc"; + method = "smc"; + memory-region = <&service_reserved>; + }; + }; diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt index 0c10802c8327..ff380dadb5f9 100644 --- a/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt +++ b/Documentation/devicetree/bindings/firmware/nvidia,tegra186-bpmp.txt @@ -8,7 +8,6 @@ which can create the interprocessor communication (IPC) between the CPU and BPMP. Required properties: -- name : Should be bpmp - compatible Array of strings One of: diff --git a/Documentation/devicetree/bindings/firmware/nvidia,tegra210-bpmp.txt b/Documentation/devicetree/bindings/firmware/nvidia,tegra210-bpmp.txt new file mode 100644 index 000000000000..68d814e8c09d --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/nvidia,tegra210-bpmp.txt @@ -0,0 +1,35 @@ +NVIDIA Tegra210 Boot and Power Management Processor (BPMP) + +The Boot and Power Management Processor (BPMP) is a co-processor found +in Tegra210 SoC. It is designed to handle the early stages of the boot +process as well as to assisting in entering deep low power state +(suspend to ram), and also offloading DRAM memory clock scaling on +some platforms. The binding document defines the resources that would +be used by the BPMP T210 firmware driver, which can create the +interprocessor communication (IPC) between the CPU and BPMP. + +Required properties: +- compatible + Array of strings + One of: + - "nvidia,tegra210-bpmp" +- reg: physical base address and length for HW synchornization primitives + 1) base address and length to Tegra 'atomics' hardware + 2) base address and length to Tegra 'semaphore' hardware +- interrupts: specifies the interrupt number for receiving messages ("rx") + and for triggering messages ("tx") + +Optional properties: +- #clock-cells : Should be 1 for platforms where DRAM clock control is + offloaded to bpmp. + +Example: + +bpmp@70016000 { + compatible = "nvidia,tegra210-bpmp"; + reg = <0x0 0x70016000 0x0 0x2000 + 0x0 0x60001000 0x0 0x1000>; + interrupts = <GIC_SPI 6 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 4 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "tx", "rx"; +}; diff --git a/Documentation/devicetree/bindings/firmware/qcom,scm.txt b/Documentation/devicetree/bindings/firmware/qcom,scm.txt index fcf6979c0b6d..41f133a4e2fa 100644 --- a/Documentation/devicetree/bindings/firmware/qcom,scm.txt +++ b/Documentation/devicetree/bindings/firmware/qcom,scm.txt @@ -7,16 +7,23 @@ assorted actions. Required properties: - compatible: must contain one of the following: - * "qcom,scm-apq8064" for APQ8064 platforms - * "qcom,scm-msm8660" for MSM8660 platforms - * "qcom,scm-msm8690" for MSM8690 platforms - * "qcom,scm-msm8996" for MSM8996 platforms - * "qcom,scm-ipq4019" for IPQ4019 platforms - * "qcom,scm" for later processors (MSM8916, APQ8084, MSM8974, etc) -- clocks: One to three clocks may be required based on compatible. - * No clock required for "qcom,scm-msm8996", "qcom,scm-ipq4019" - * Only core clock required for "qcom,scm-apq8064", "qcom,scm-msm8660", and "qcom,scm-msm8960" - * Core, iface, and bus clocks required for "qcom,scm" + * "qcom,scm-apq8064" + * "qcom,scm-apq8084" + * "qcom,scm-msm8660" + * "qcom,scm-msm8916" + * "qcom,scm-msm8960" + * "qcom,scm-msm8974" + * "qcom,scm-msm8996" + * "qcom,scm-msm8998" + * "qcom,scm-ipq4019" + * "qcom,scm-sdm845" + and: + * "qcom,scm" +- clocks: Specifies clocks needed by the SCM interface, if any: + * core clock required for "qcom,scm-apq8064", "qcom,scm-msm8660" and + "qcom,scm-msm8960" + * core, iface and bus clocks required for "qcom,scm-apq8084", + "qcom,scm-msm8916" and "qcom,scm-msm8974" - clock-names: Must contain "core" for the core clock, "iface" for the interface clock and "bus" for the bus clock per the requirements of the compatible. - qcom,dload-mode: phandle to the TCSR hardware block and offset of the @@ -26,8 +33,10 @@ Example for MSM8916: firmware { scm { - compatible = "qcom,scm"; - clocks = <&gcc GCC_CRYPTO_CLK> , <&gcc GCC_CRYPTO_AXI_CLK>, <&gcc GCC_CRYPTO_AHB_CLK>; + compatible = "qcom,msm8916", "qcom,scm"; + clocks = <&gcc GCC_CRYPTO_CLK> , + <&gcc GCC_CRYPTO_AXI_CLK>, + <&gcc GCC_CRYPTO_AHB_CLK>; clock-names = "core", "bus", "iface"; }; }; diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt new file mode 100644 index 000000000000..614bac55df86 --- /dev/null +++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.txt @@ -0,0 +1,82 @@ +----------------------------------------------------------------- +Device Tree Bindings for the Xilinx Zynq MPSoC Firmware Interface +----------------------------------------------------------------- + +The zynqmp-firmware node describes the interface to platform firmware. +ZynqMP has an interface to communicate with secure firmware. Firmware +driver provides an interface to firmware APIs. Interface APIs can be +used by any driver to communicate to PMUFW(Platform Management Unit). +These requests include clock management, pin control, device control, +power management service, FPGA service and other platform management +services. + +Required properties: + - compatible: Must contain: "xlnx,zynqmp-firmware" + - method: The method of calling the PM-API firmware layer. + Permitted values are: + - "smc" : SMC #0, following the SMCCC + - "hvc" : HVC #0, following the SMCCC + +-------------------------------------------------------------------------- +Device Tree Clock bindings for the Zynq Ultrascale+ MPSoC controlled using +Zynq MPSoC firmware interface +-------------------------------------------------------------------------- +The clock controller is a h/w block of Zynq Ultrascale+ MPSoC clock +tree. It reads required input clock frequencies from the devicetree and acts +as clock provider for all clock consumers of PS clocks. + +See clock_bindings.txt for more information on the generic clock bindings. + +Required properties: + - #clock-cells: Must be 1 + - compatible: Must contain: "xlnx,zynqmp-clk" + - clocks: List of clock specifiers which are external input + clocks to the given clock controller. Please refer + the next section to find the input clocks for a + given controller. + - clock-names: List of clock names which are exteral input clocks + to the given clock controller. Please refer to the + clock bindings for more details. + +Input clocks for zynqmp Ultrascale+ clock controller: + +The Zynq UltraScale+ MPSoC has one primary and four alternative reference clock +inputs. These required clock inputs are: + - pss_ref_clk (PS reference clock) + - video_clk (reference clock for video system ) + - pss_alt_ref_clk (alternative PS reference clock) + - aux_ref_clk + - gt_crx_ref_clk (transceiver reference clock) + +The following strings are optional parameters to the 'clock-names' property in +order to provide an optional (E)MIO clock source: + - swdt0_ext_clk + - swdt1_ext_clk + - gem0_emio_clk + - gem1_emio_clk + - gem2_emio_clk + - gem3_emio_clk + - mio_clk_XX # with XX = 00..77 + - mio_clk_50_or_51 #for the mux clock to gem tsu from 50 or 51 + + +Output clocks are registered based on clock information received +from firmware. Output clocks indexes are mentioned in +include/dt-bindings/clock/xlnx,zynqmp-clk.h. + +------- +Example +------- + +firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + zynqmp_clk: clock-controller { + #clock-cells = <1>; + compatible = "xlnx,zynqmp-clk"; + clocks = <&pss_ref_clk>, <&video_clk>, <&pss_alt_ref_clk>, <&aux_ref_clk>, <>_crx_ref_clk>; + clock-names = "pss_ref_clk", "video_clk", "pss_alt_ref_clk","aux_ref_clk", "gt_crx_ref_clk"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt index 6db8aeda461a..90c44694a30b 100644 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -415,7 +415,7 @@ DT Overlay contains: firmware-name = "base.rbf"; fpga-bridge@4400 { - compatible = "altr,freeze-bridge"; + compatible = "altr,freeze-bridge-controller"; reg = <0x4400 0x10>; fpga_region1: fpga-region1 { @@ -427,7 +427,7 @@ DT Overlay contains: }; fpga-bridge@4420 { - compatible = "altr,freeze-bridge"; + compatible = "altr,freeze-bridge-controller"; reg = <0x4420 0x10>; fpga_region2: fpga-region2 { diff --git a/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt new file mode 100644 index 000000000000..6e03f79287fb --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/intel-stratix10-soc-fpga-mgr.txt @@ -0,0 +1,17 @@ +Intel Stratix10 SoC FPGA Manager + +Required properties: +The fpga_mgr node has the following mandatory property, must be located under +firmware/svc node. + +- compatible : should contain "intel,stratix10-soc-fpga-mgr" + +Example: + + firmware { + svc { + fpga_mgr: fpga-mgr { + compatible = "intel,stratix10-soc-fpga-mgr"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt b/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt new file mode 100644 index 000000000000..99ca9862a586 --- /dev/null +++ b/Documentation/devicetree/bindings/fsi/ibm,p9-occ.txt @@ -0,0 +1,16 @@ +Device-tree bindings for FSI-attached POWER9 On-Chip Controller (OCC) +--------------------------------------------------------------------- + +This is the binding for the P9 On-Chip Controller accessed over FSI from a +service processor. See fsi.txt for details on bindings for FSI slave and CFAM +nodes. The OCC is not an FSI slave device itself, rather it is accessed +through the SBE fifo. + +Required properties: + - compatible = "ibm,p9-occ" + +Examples: + + occ { + compatible = "ibm,p9-occ"; + }; diff --git a/Documentation/devicetree/bindings/gnss/gnss.txt b/Documentation/devicetree/bindings/gnss/gnss.txt index f1e4a2ff47c5..f547bd4549fe 100644 --- a/Documentation/devicetree/bindings/gnss/gnss.txt +++ b/Documentation/devicetree/bindings/gnss/gnss.txt @@ -17,6 +17,7 @@ Required properties: represents Optional properties: +- lna-supply : Separate supply for an LNA - enable-gpios : GPIO used to enable the device - timepulse-gpios : Time pulse GPIO diff --git a/Documentation/devicetree/bindings/gnss/mediatek.txt b/Documentation/devicetree/bindings/gnss/mediatek.txt new file mode 100644 index 000000000000..80cb802813c5 --- /dev/null +++ b/Documentation/devicetree/bindings/gnss/mediatek.txt @@ -0,0 +1,35 @@ +Mediatek-based GNSS Receiver DT binding + +Mediatek chipsets are used in GNSS-receiver modules produced by several +vendors and can use a UART interface. + +Please see Documentation/devicetree/bindings/gnss/gnss.txt for generic +properties. + +Required properties: + +- compatible : Must be + + "globaltop,pa6h" + +- vcc-supply : Main voltage regulator (pin name: VCC) + +Optional properties: + +- current-speed : Default UART baud rate +- gnss-fix-gpios : GPIO used to determine device position fix state + (pin name: FIX, 3D_FIX) +- reset-gpios : GPIO used to reset the device (pin name: RESET, NRESET) +- timepulse-gpios : Time pulse GPIO (pin name: PPS1, 1PPS) +- vbackup-supply : Backup voltage regulator (pin name: VBAT, VBACKUP) + +Example: + +serial@1234 { + compatible = "ns16550a"; + + gnss { + compatible = "globaltop,pa6h"; + vcc-supply = <&vcc_3v3>; + }; +}; diff --git a/Documentation/devicetree/bindings/gnss/sirfstar.txt b/Documentation/devicetree/bindings/gnss/sirfstar.txt index 648d183cdb77..f4252b6b660b 100644 --- a/Documentation/devicetree/bindings/gnss/sirfstar.txt +++ b/Documentation/devicetree/bindings/gnss/sirfstar.txt @@ -12,6 +12,7 @@ Required properties: "fastrax,uc430" "linx,r4" + "wi2wi,w2sg0004" "wi2wi,w2sg0008i" "wi2wi,w2sg0084i" diff --git a/Documentation/devicetree/bindings/gpio/cdns,gpio.txt b/Documentation/devicetree/bindings/gpio/cdns,gpio.txt new file mode 100644 index 000000000000..706ef00f5c64 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/cdns,gpio.txt @@ -0,0 +1,43 @@ +Cadence GPIO controller bindings + +Required properties: +- compatible: should be "cdns,gpio-r1p02". +- reg: the register base address and size. +- #gpio-cells: should be 2. + * first cell is the GPIO number. + * second cell specifies the GPIO flags, as defined in + <dt-bindings/gpio/gpio.h>. Only the GPIO_ACTIVE_HIGH + and GPIO_ACTIVE_LOW flags are supported. +- gpio-controller: marks the device as a GPIO controller. +- clocks: should contain one entry referencing the peripheral clock driving + the GPIO controller. + +Optional properties: +- ngpios: integer number of gpio lines supported by this controller, up to 32. +- interrupts: interrupt specifier for the controllers interrupt. +- interrupt-controller: marks the device as an interrupt controller. When + defined, interrupts, interrupt-parent and #interrupt-cells + are required. +- interrupt-cells: should be 2. + * first cell is the GPIO number you want to use as an IRQ source. + * second cell specifies the IRQ type, as defined in + <dt-bindings/interrupt-controller/irq.h>. + Currently only level sensitive IRQs are supported. + + +Example: + gpio0: gpio-controller@fd060000 { + compatible = "cdns,gpio-r1p02"; + reg =<0xfd060000 0x1000>; + + clocks = <&gpio_clk>; + + interrupt-parent = <&gic>; + interrupts = <0 5 IRQ_TYPE_LEVEL_HIGH>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt b/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt new file mode 100644 index 000000000000..6e81f8b755c5 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gateworks,pld-gpio.txt @@ -0,0 +1,20 @@ +Gateworks PLD GPIO controller bindings + +The GPIO controller should be a child node on an I2C bus, +see: i2c/i2c.txt for details. + +Required properties: +- compatible: Should be "gateworks,pld-gpio" +- reg: I2C slave address +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells: Should be <2>. The first cell is the gpio number and + the second cell is used to specify optional parameters. + +Example: + +pld@56 { + compatible = "gateworks,pld-gpio"; + reg = <0x56>; + gpio-controller; + #gpio-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt index 93d98d09d92b..54040a2bfe3a 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt @@ -33,7 +33,7 @@ Required properties: "sprd,sc9860-eic-latch", "sprd,sc9860-eic-async", "sprd,sc9860-eic-sync", - "sprd,sc27xx-eic". + "sprd,sc2731-eic". - reg: Define the base and range of the I/O address space containing the GPIO controller registers. - gpio-controller: Marks the device node as a GPIO controller. @@ -86,7 +86,7 @@ Example: }; pmic_eic: gpio@300 { - compatible = "sprd,sc27xx-eic"; + compatible = "sprd,sc2731-eic"; reg = <0x300>; interrupt-parent = <&sc2731_pmic>; interrupts = <5 IRQ_TYPE_LEVEL_HIGH>; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt index 38ca2201e8ae..2e097b57f170 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt @@ -14,8 +14,6 @@ Required properties: "marvell,armada-8k-gpio" should be used for the Armada 7K and 8K SoCs (either from AP or CP), see - Documentation/devicetree/bindings/arm/marvell/cp110-system-controller0.txt - and Documentation/devicetree/bindings/arm/marvell/ap806-system-controller.txt for specific details about the offset property. diff --git a/Documentation/devicetree/bindings/gpio/gpio-omap.txt b/Documentation/devicetree/bindings/gpio/gpio-omap.txt index 8d950522e7fa..e57b2cb28f6c 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-omap.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-omap.txt @@ -5,6 +5,8 @@ Required properties: - "ti,omap2-gpio" for OMAP2 controllers - "ti,omap3-gpio" for OMAP3 controllers - "ti,omap4-gpio" for OMAP4 controllers +- reg : Physical base address of the controller and length of memory mapped + region. - gpio-controller : Marks the device node as a GPIO controller. - #gpio-cells : Should be two. - first cell is the pin number @@ -18,6 +20,8 @@ Required properties: 2 = high-to-low edge triggered. 4 = active high level-sensitive. 8 = active low level-sensitive. +- interrupts : The interrupt the controller is rising as output when an + interrupt occures OMAP specific properties: - ti,hwmods: Name of the hwmod associated to the GPIO: @@ -29,11 +33,13 @@ OMAP specific properties: Example: -gpio4: gpio4 { +gpio0: gpio@44e07000 { compatible = "ti,omap4-gpio"; - ti,hwmods = "gpio4"; + reg = <0x44e07000 0x1000>; + ti,hwmods = "gpio1"; gpio-controller; #gpio-cells = <2>; interrupt-controller; #interrupt-cells = <2>; + interrupts = <96>; }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt index 4e3c550e319a..fb144e2b6522 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt @@ -16,6 +16,7 @@ Required properties: nxp,pca9574 nxp,pca9575 nxp,pca9698 + nxp,pcal6416 nxp,pcal6524 nxp,pcal9555a maxim,max7310 diff --git a/Documentation/devicetree/bindings/gpio/gpio-vf610.txt b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt index 0ccbae44019c..ae254aadee35 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-vf610.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-vf610.txt @@ -24,6 +24,12 @@ Required properties for GPIO node: 4 = active high level-sensitive. 8 = active low level-sensitive. +Optional properties: +-clocks: Must contain an entry for each entry in clock-names. + See common clock-bindings.txt for details. +-clock-names: A list of clock names. For imx7ulp, it must contain + "gpio", "port". + Note: Each GPIO port should have an alias correctly numbered in "aliases" node. diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt index f0ba154b5723..a8895d339bfe 100644 --- a/Documentation/devicetree/bindings/gpio/gpio.txt +++ b/Documentation/devicetree/bindings/gpio/gpio.txt @@ -67,6 +67,18 @@ Optional standard bitfield specifiers for the last cell: https://en.wikipedia.org/wiki/Open_collector - Bit 3: 0 means the output should be maintained during sleep/low-power mode 1 means the output state can be lost during sleep/low-power mode +- Bit 4: 0 means no pull-up resistor should be enabled + 1 means a pull-up resistor should be enabled + This setting only applies to hardware with a simple on/off + control for pull-up configuration. If the hardware has more + elaborate pull-up configuration, it should be represented + using a pin control binding. +- Bit 5: 0 means no pull-down resistor should be enabled + 1 means a pull-down resistor should be enabled + This setting only applies to hardware with a simple on/off + control for pull-down configuration. If the hardware has more + elaborate pull-down configuration, it should be represented + using a pin control binding. 1.1) GPIO specifier best practices ---------------------------------- diff --git a/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt new file mode 100644 index 000000000000..8dc41ed99685 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/intel,ixp4xx-gpio.txt @@ -0,0 +1,38 @@ +Intel IXP4xx XScale Networking Processors GPIO + +This GPIO controller is found in the Intel IXP4xx processors. +It supports 16 GPIO lines. + +The interrupt portions of the GPIO controller is hierarchical: +the synchronous edge detector is part of the GPIO block, but the +actual enabling/disabling of the interrupt line is done in the +main IXP4xx interrupt controller which has a 1:1 mapping for +the first 12 GPIO lines to 12 system interrupts. + +The remaining 4 GPIO lines can not be used for receiving +interrupts. + +The interrupt parent of this GPIO controller must be the +IXP4xx interrupt controller. + +Required properties: + +- compatible : Should be + "intel,ixp4xx-gpio" +- reg : Should contain registers location and length +- 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, see + interrupt-controller/interrupts.txt + +Example: + +gpio0: gpio@c8004000 { + compatible = "intel,ixp4xx-gpio"; + reg = <0xc8004000 0x1000>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt b/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt index eb7cdd69e10b..627efc78ecf2 100644 --- a/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/nxp,lpc1850-gpio.txt @@ -3,12 +3,24 @@ NXP LPC18xx/43xx GPIO controller Device Tree Bindings Required properties: - compatible : Should be "nxp,lpc1850-gpio" -- reg : Address and length of the register set for the device -- clocks : Clock specifier (see clock bindings for details) -- gpio-controller : Marks the device node as a GPIO controller. -- #gpio-cells : Should be two - - First cell is the GPIO line number - - Second cell is used to specify polarity +- reg : List of addresses and lengths of the GPIO controller + register sets +- reg-names : Should be "gpio", "gpio-pin-ic", "gpio-group0-ic" and + "gpio-gpoup1-ic" +- clocks : Phandle and clock specifier pair for GPIO controller +- resets : Phandle and reset specifier pair for GPIO controller +- gpio-controller : Marks the device node as a GPIO controller +- #gpio-cells : Should be two: + - The first cell is the GPIO line number + - The second cell is used to specify polarity +- interrupt-controller : Marks the device node as an interrupt controller +- #interrupt-cells : Should be two: + - The first cell is an interrupt number within + 0..9 range, for GPIO pin interrupts it is equal + to 'nxp,gpio-pin-interrupt' property value of + GPIO pin configuration, 8 is for GPIO GROUP0 + interrupt, 9 is for GPIO GROUP1 interrupt + - The second cell is used to specify interrupt type Optional properties: - gpio-ranges : Mapping between GPIO and pinctrl @@ -19,21 +31,29 @@ Example: gpio: gpio@400f4000 { compatible = "nxp,lpc1850-gpio"; - reg = <0x400f4000 0x4000>; + reg = <0x400f4000 0x4000>, <0x40087000 0x1000>, + <0x40088000 0x1000>, <0x40089000 0x1000>; + reg-names = "gpio", "gpio-pin-ic", + "gpio-group0-ic", "gpio-gpoup1-ic"; clocks = <&ccu1 CLK_CPU_GPIO>; + resets = <&rgu 28>; gpio-controller; #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; gpio-ranges = <&pinctrl LPC_GPIO(0,0) LPC_PIN(0,0) 2>, ... <&pinctrl LPC_GPIO(7,19) LPC_PIN(f,5) 7>; }; gpio_joystick { - compatible = "gpio-keys-polled"; + compatible = "gpio-keys"; ... - button@0 { + button0 { ... + interrupt-parent = <&gpio>; + interrupts = <1 IRQ_TYPE_EDGE_BOTH>; gpios = <&gpio LPC_GPIO(4,8) GPIO_ACTIVE_LOW>; }; }; diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt index 2889bbcd7416..f3f2c468c1b6 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt +++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt @@ -8,6 +8,7 @@ Required Properties: - "renesas,gpio-r8a7745": for R8A7745 (RZ/G1E) compatible GPIO controller. - "renesas,gpio-r8a77470": for R8A77470 (RZ/G1C) compatible GPIO controller. - "renesas,gpio-r8a774a1": for R8A774A1 (RZ/G2M) compatible GPIO controller. + - "renesas,gpio-r8a774c0": for R8A774C0 (RZ/G2E) compatible GPIO controller. - "renesas,gpio-r8a7778": for R8A7778 (R-Car M1) compatible GPIO controller. - "renesas,gpio-r8a7779": for R8A7779 (R-Car H1) compatible GPIO controller. - "renesas,gpio-r8a7790": for R8A7790 (R-Car H2) compatible GPIO controller. diff --git a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt index 7276b50c3506..839dd32ffe11 100644 --- a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt +++ b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt @@ -43,7 +43,7 @@ gpio: gpio@20000 { #address-cells = <1>; #size-cells = <0>; - porta: gpio-controller@0 { + porta: gpio@0 { compatible = "snps,dw-apb-gpio-port"; gpio-controller; #gpio-cells = <2>; @@ -55,7 +55,7 @@ gpio: gpio@20000 { interrupts = <0>; }; - portb: gpio-controller@1 { + portb: gpio@1 { compatible = "snps,dw-apb-gpio-port"; gpio-controller; #gpio-cells = <2>; diff --git a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt index 63cd91176a68..ae63f09fda7d 100644 --- a/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt +++ b/Documentation/devicetree/bindings/gpu/arm,mali-utgard.txt @@ -11,7 +11,10 @@ Required properties: + allwinner,sun4i-a10-mali + allwinner,sun7i-a20-mali + allwinner,sun8i-h3-mali + + allwinner,sun50i-a64-mali + allwinner,sun50i-h5-mali + + amlogic,meson8-mali + + amlogic,meson8b-mali + amlogic,meson-gxbb-mali + amlogic,meson-gxl-mali + rockchip,rk3036-mali @@ -73,10 +76,18 @@ to specify one more vendor-specific compatible, among: Required properties: * resets: phandle to the reset line for the GPU + - allwinner,sun50i-a64-mali + Required properties: + * resets: phandle to the reset line for the GPU + - allwinner,sun50i-h5-mali Required properties: * resets: phandle to the reset line for the GPU + - amlogic,meson8-mali and amlogic,meson8b-mali + Required properties: + * resets: phandle to the reset line for the GPU + - Rockchip variants: Required properties: * resets: phandle to the reset line for the GPU diff --git a/Documentation/devicetree/bindings/gpu/samsung-rotator.txt b/Documentation/devicetree/bindings/gpu/samsung-rotator.txt index 82cd1ed0be93..3aca2578da0b 100644 --- a/Documentation/devicetree/bindings/gpu/samsung-rotator.txt +++ b/Documentation/devicetree/bindings/gpu/samsung-rotator.txt @@ -2,9 +2,10 @@ Required properties: - compatible : value should be one of the following: - (a) "samsung,exynos4210-rotator" for Rotator IP in Exynos4210 - (b) "samsung,exynos4212-rotator" for Rotator IP in Exynos4212/4412 - (c) "samsung,exynos5250-rotator" for Rotator IP in Exynos5250 + * "samsung,s5pv210-rotator" for Rotator IP in S5PV210 + * "samsung,exynos4210-rotator" for Rotator IP in Exynos4210 + * "samsung,exynos4212-rotator" for Rotator IP in Exynos4212/4412 + * "samsung,exynos5250-rotator" for Rotator IP in Exynos5250 - reg : Physical base address of the IP registers and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.txt b/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.txt new file mode 100644 index 000000000000..adf4f000ea3d --- /dev/null +++ b/Documentation/devicetree/bindings/hwlock/st,stm32-hwspinlock.txt @@ -0,0 +1,23 @@ +STM32 Hardware Spinlock Device Binding +------------------------------------- + +Required properties : +- compatible : should be "st,stm32-hwspinlock". +- reg : the register address of hwspinlock. +- #hwlock-cells : hwlock users only use the hwlock id to represent a specific + hwlock, so the number of cells should be <1> here. +- clock-names : Must contain "hsem". +- clocks : Must contain a phandle entry for the clock in clock-names, see the + common clock bindings. + +Please look at the generic hwlock binding for usage information for consumers, +"Documentation/devicetree/bindings/hwlock/hwlock.txt" + +Example of hwlock provider: + hwspinlock@4c000000 { + compatible = "st,stm32-hwspinlock"; + #hwlock-cells = <1>; + reg = <0x4c000000 0x400>; + clocks = <&rcc HSEM>; + clock-names = "hsem"; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ad741x.txt b/Documentation/devicetree/bindings/hwmon/ad741x.txt new file mode 100644 index 000000000000..9102152c8410 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/ad741x.txt @@ -0,0 +1,15 @@ +* AD7416/AD7417/AD7418 Temperature Sensor Device Tree Bindings + +Required properties: +- compatible: one of + "adi,ad7416" + "adi,ad7417" + "adi,ad7418" +- reg: I2C address + +Example: + +hwmon@28 { + compatible = "adi,ad7418"; + reg = <0x28>; +}; diff --git a/Documentation/devicetree/bindings/hwmon/adm1275.txt b/Documentation/devicetree/bindings/hwmon/adm1275.txt new file mode 100644 index 000000000000..1ecd03f3da4d --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adm1275.txt @@ -0,0 +1,25 @@ +adm1275 properties + +Required properties: +- compatible: Must be one of the supported compatible strings: + - "adi,adm1075" for adm1075 + - "adi,adm1272" for adm1272 + - "adi,adm1275" for adm1275 + - "adi,adm1276" for adm1276 + - "adi,adm1278" for adm1278 + - "adi,adm1293" for adm1293 + - "adi,adm1294" for adm1294 +- reg: I2C address + +Optional properties: + +- shunt-resistor-micro-ohms + Shunt resistor value in micro-Ohm + +Example: + +adm1272@10 { + compatible = "adi,adm1272"; + reg = <0x10>; + shunt-resistor-micro-ohms = <500>; +}; diff --git a/Documentation/devicetree/bindings/hwmon/dps650ab.txt b/Documentation/devicetree/bindings/hwmon/dps650ab.txt new file mode 100644 index 000000000000..76780e795899 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/dps650ab.txt @@ -0,0 +1,11 @@ +Bindings for Delta Electronics DPS-650-AB power supply + +Required properties: +- compatible : "delta,dps650ab" +- reg : I2C address, one of 0x58, 0x59. + +Example: + dps650ab@58 { + compatible = "delta,dps650ab"; + reg = <0x58>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/hih6130.txt b/Documentation/devicetree/bindings/hwmon/hih6130.txt new file mode 100644 index 000000000000..2c43837af4c2 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/hih6130.txt @@ -0,0 +1,12 @@ +Honeywell Humidicon HIH-6130 humidity/temperature sensor +-------------------------------------------------------- + +Requires node properties: +- compatible : "honeywell,hi6130" +- reg : the I2C address of the device. This is 0x27. + +Example: + hih6130@27 { + compatible = "honeywell,hih6130"; + reg = <0x27>; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ina3221.txt b/Documentation/devicetree/bindings/hwmon/ina3221.txt index a7b25caa2b8e..fa63b6171407 100644 --- a/Documentation/devicetree/bindings/hwmon/ina3221.txt +++ b/Documentation/devicetree/bindings/hwmon/ina3221.txt @@ -6,6 +6,16 @@ Texas Instruments INA3221 Device Tree Bindings - reg: I2C address Optional properties: + - ti,single-shot: This chip has two power modes: single-shot (chip takes one + measurement and then shuts itself down) and continuous ( + chip takes continuous measurements). The continuous mode is + more reliable and suitable for hardware monitor type device, + but the single-shot mode is more power-friendly and useful + for battery-powered device which cares power consumptions + while still needs some measurements occasionally. + If this property is present, the single-shot mode will be + used, instead of the default continuous one for monitoring. + = The node contains optional child nodes for three channels = = Each child node describes the information of input source = diff --git a/Documentation/devicetree/bindings/hwmon/lm75.txt b/Documentation/devicetree/bindings/hwmon/lm75.txt new file mode 100644 index 000000000000..12d8cf7cf592 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/lm75.txt @@ -0,0 +1,37 @@ +*LM75 hwmon sensor. + +Required properties: +- compatible: manufacturer and chip name, one of + "adi,adt75", + "dallas,ds1775", + "dallas,ds75", + "dallas,ds7505", + "gmt,g751", + "national,lm75", + "national,lm75a", + "national,lm75b", + "maxim,max6625", + "maxim,max6626", + "maxim,max31725", + "maxim,max31726", + "maxim,mcp980x", + "st,stds75", + "st,stlm75", + "microchip,tcn75", + "ti,tmp100", + "ti,tmp101", + "ti,tmp105", + "ti,tmp112", + "ti,tmp175", + "ti,tmp275", + "ti,tmp75", + "ti,tmp75c", + +- reg: I2C bus address of the device + +Example: + +sensor@48 { + compatible = "st,stlm75"; + reg = <0x48>; +}; diff --git a/Documentation/devicetree/bindings/hwmon/lm90.txt b/Documentation/devicetree/bindings/hwmon/lm90.txt index 97581266e329..c76a7ac47c34 100644 --- a/Documentation/devicetree/bindings/hwmon/lm90.txt +++ b/Documentation/devicetree/bindings/hwmon/lm90.txt @@ -23,6 +23,7 @@ Required node properties: "onnn,nct1008" "winbond,w83l771" "nxp,sa56004" + "ti,tmp451" - reg: I2C bus address of the device diff --git a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt index c3b9c4cfe8df..37f18d684f6a 100644 --- a/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt +++ b/Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt @@ -4,6 +4,7 @@ NTC Thermistor hwmon sensors Requires node properties: - "compatible" value : one of "epcos,b57330v2103" + "epcos,b57891s0103" "murata,ncp15wb473" "murata,ncp18wb473" "murata,ncp21wb473" diff --git a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt index c6d533202d3e..49ca5d83ed13 100644 --- a/Documentation/devicetree/bindings/hwmon/pwm-fan.txt +++ b/Documentation/devicetree/bindings/hwmon/pwm-fan.txt @@ -6,6 +6,9 @@ Required properties: - cooling-levels : PWM duty cycle values in a range from 0 to 255 which correspond to thermal cooling states +Optional properties: +- fan-supply : phandle to the regulator that provides power to the fan + Example: fan0: pwm-fan { compatible = "pwm-fan"; diff --git a/Documentation/devicetree/bindings/hwmon/tmp108.txt b/Documentation/devicetree/bindings/hwmon/tmp108.txt index 8c4b10df86d9..54d4beed4ee5 100644 --- a/Documentation/devicetree/bindings/hwmon/tmp108.txt +++ b/Documentation/devicetree/bindings/hwmon/tmp108.txt @@ -7,6 +7,10 @@ Requires node properties: - compatible : "ti,tmp108" - reg : the I2C address of the device. This is 0x48, 0x49, 0x4a, or 0x4b. +Optional properties: +- interrupts: Reference to the TMP108 alert interrupt. +- #thermal-sensor-cells: should be set to 0. + Example: tmp108@48 { compatible = "ti,tmp108"; diff --git a/Documentation/devicetree/bindings/i2c/i2c-at91.txt b/Documentation/devicetree/bindings/i2c/i2c-at91.txt index ef973a0343c7..b7cec17c3daf 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-at91.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-at91.txt @@ -33,7 +33,7 @@ i2c0: i2c@fff84000 { clock-frequency = <400000>; 24c512@50 { - compatible = "24c512"; + compatible = "atmel,24c512"; reg = <0x50>; pagesize = <128>; } diff --git a/Documentation/devicetree/bindings/i2c/i2c-designware.txt b/Documentation/devicetree/bindings/i2c/i2c-designware.txt index fbb0a6d8b964..3e4bcc2fb6f7 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-designware.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-designware.txt @@ -3,6 +3,7 @@ Required properties : - compatible : should be "snps,designware-i2c" + or "mscc,ocelot-i2c" with "snps,designware-i2c" for fallback - reg : Offset and length of the register set for the device - interrupts : <IRQ> where IRQ is the interrupt number. @@ -11,8 +12,12 @@ Recommended properties : - clock-frequency : desired I2C bus clock frequency in Hz. Optional properties : + - reg : for "mscc,ocelot-i2c", a second register set to configure the SDA hold + time, named ICPU_CFG:TWI_DELAY in the datasheet. + - i2c-sda-hold-time-ns : should contain the SDA hold time in nanoseconds. - This option is only supported in hardware blocks version 1.11a or newer. + This option is only supported in hardware blocks version 1.11a or newer and + on Microsemi SoCs ("mscc,ocelot-i2c" compatible). - i2c-scl-falling-time-ns : should contain the SCL falling time in nanoseconds. This value which is by default 300ns is used to compute the tLOW period. diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.txt b/Documentation/devicetree/bindings/i2c/i2c-gpio.txt deleted file mode 100644 index 38a05562d1d2..000000000000 --- a/Documentation/devicetree/bindings/i2c/i2c-gpio.txt +++ /dev/null @@ -1,46 +0,0 @@ -Device-Tree bindings for i2c gpio driver - -Required properties: - - compatible = "i2c-gpio"; - - sda-gpios: gpio used for the sda signal, this should be flagged as - active high using open drain with (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN) - from <dt-bindings/gpio/gpio.h> since the signal is by definition - open drain. - - scl-gpios: gpio used for the scl signal, this should be flagged as - active high using open drain with (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN) - from <dt-bindings/gpio/gpio.h> since the signal is by definition - open drain. - -Optional properties: - - i2c-gpio,scl-output-only: scl as output only - - i2c-gpio,delay-us: delay between GPIO operations (may depend on each platform) - - i2c-gpio,timeout-ms: timeout to get data - -Deprecated properties, do not use in new device tree sources: - - gpios: sda and scl gpio, alternative for {sda,scl}-gpios - - i2c-gpio,sda-open-drain: this means that something outside of our - control has put the GPIO line used for SDA into open drain mode, and - that something is not the GPIO chip. It is essentially an - inconsistency flag. - - i2c-gpio,scl-open-drain: this means that something outside of our - control has put the GPIO line used for SCL into open drain mode, and - that something is not the GPIO chip. It is essentially an - inconsistency flag. - -Example nodes: - -#include <dt-bindings/gpio/gpio.h> - -i2c@0 { - compatible = "i2c-gpio"; - sda-gpios = <&pioA 23 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; - scl-gpios = <&pioA 24 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; - i2c-gpio,delay-us = <2>; /* ~100 kHz */ - #address-cells = <1>; - #size-cells = <0>; - - rv3029c2@56 { - compatible = "rv3029c2"; - reg = <0x56>; - }; -}; diff --git a/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml new file mode 100644 index 000000000000..da6129090a8e --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-gpio.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/i2c/i2c-gpio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Bindings for GPIO bitbanged I2C + +maintainers: + - Wolfram Sang <wolfram@the-dreams.de> + +allOf: + - $ref: /schemas/i2c/i2c-controller.yaml# + +properties: + compatible: + items: + - const: i2c-gpio + + sda-gpios: + description: + gpio used for the sda signal, this should be flagged as + active high using open drain with (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN) + from <dt-bindings/gpio/gpio.h> since the signal is by definition + open drain. + maxItems: 1 + + scl-gpios: + description: + gpio used for the scl signal, this should be flagged as + active high using open drain with (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN) + from <dt-bindings/gpio/gpio.h> since the signal is by definition + open drain. + maxItems: 1 + + i2c-gpio,scl-output-only: + description: scl as output only + type: boolean + + i2c-gpio,delay-us: + description: delay between GPIO operations (may depend on each platform) + $ref: /schemas/types.yaml#/definitions/uint32 + + i2c-gpio,timeout-ms: + description: timeout to get data + $ref: /schemas/types.yaml#/definitions/uint32 + + # Deprecated properties, do not use in new device tree sources: + gpios: + minItems: 2 + maxItems: 2 + description: sda and scl gpio, alternative for {sda,scl}-gpios + + i2c-gpio,sda-open-drain: + # Generate a warning if present + not: true + description: this means that something outside of our control has put + the GPIO line used for SDA into open drain mode, and that something is + not the GPIO chip. It is essentially an inconsistency flag. + + i2c-gpio,scl-open-drain: + # Generate a warning if present + not: true + description: this means that something outside of our control has put the + GPIO line used for SCL into open drain mode, and that something is not + the GPIO chip. It is essentially an inconsistency flag. + +required: + - compatible + - sda-gpios + - scl-gpios + +... diff --git a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt index 091c8dfd3229..b245363d6d60 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-imx-lpi2c.txt @@ -3,6 +3,7 @@ Required properties: - compatible : - "fsl,imx7ulp-lpi2c" for LPI2C compatible with the one integrated on i.MX7ULP soc + - "fsl,imx8qxp-lpi2c" for LPI2C compatible with the one integrated on i.MX8QXP soc - reg : address and length of the lpi2c master registers - interrupts : lpi2c interrupt - clocks : lpi2c clock specifier diff --git a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt index e199695b1c96..ee4c32454198 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mtk.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mtk.txt @@ -10,6 +10,7 @@ Required properties: "mediatek,mt6589-i2c": for MediaTek MT6589 "mediatek,mt7622-i2c": for MediaTek MT7622 "mediatek,mt7623-i2c", "mediatek,mt6577-i2c": for MediaTek MT7623 + "mediatek,mt7629-i2c", "mediatek,mt2712-i2c": for MediaTek MT7629 "mediatek,mt8173-i2c": for MediaTek MT8173 - reg: physical base address of the controller and dma base, length of memory mapped region. diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt index 1e98c6b3a721..8b1e49cdce3f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-ltc4306.txt @@ -43,7 +43,7 @@ Example: reg = <0>; eeprom@50 { - compatible = "at,24c02"; + compatible = "atmel,24c02"; reg = <0x50>; }; }; @@ -54,7 +54,7 @@ Example: reg = <1>; eeprom@50 { - compatible = "at,24c02"; + compatible = "atmel,24c02"; reg = <0x50>; }; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt index ccf6c86ed076..30ac6a60f041 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.txt @@ -54,7 +54,7 @@ Example: reg = <2>; eeprom@54 { - compatible = "at,24c08"; + compatible = "atmel,24c08"; reg = <0x54>; }; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-omap.txt b/Documentation/devicetree/bindings/i2c/i2c-omap.txt index 7e49839d4124..4b90ba9f31b7 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-omap.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-omap.txt @@ -1,8 +1,12 @@ I2C for OMAP platforms Required properties : -- compatible : Must be "ti,omap2420-i2c", "ti,omap2430-i2c", "ti,omap3-i2c" - or "ti,omap4-i2c" +- compatible : Must be + "ti,omap2420-i2c" for OMAP2420 SoCs + "ti,omap2430-i2c" for OMAP2430 SoCs + "ti,omap3-i2c" for OMAP3 SoCs + "ti,omap4-i2c" for OMAP4+ SoCs + "ti,am654-i2c", "ti,omap4-i2c" for AM654 SoCs - ti,hwmods : Must be "i2c<n>", n being the instance number (1-based) - #address-cells = <1>; - #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/i2c/i2c-owl.txt b/Documentation/devicetree/bindings/i2c/i2c-owl.txt index b743fe444e9f..54c05dbdb2e4 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-owl.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-owl.txt @@ -2,7 +2,9 @@ Actions Semiconductor Owl I2C controller Required properties: -- compatible : Should be "actions,s900-i2c". +- compatible : Should be one of the following: + - "actions,s700-i2c" for S700 SoC + - "actions,s900-i2c" for S900 SoC - reg : Offset and length of the register set for the device. - #address-cells : Should be 1. - #size-cells : Should be 0. diff --git a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt index 39cd21d95810..3ee5e8f6ee01 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-rcar.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-rcar.txt @@ -3,8 +3,11 @@ I2C for R-Car platforms Required properties: - compatible: "renesas,i2c-r8a7743" if the device is a part of a R8A7743 SoC. + "renesas,i2c-r8a7744" if the device is a part of a R8A7744 SoC. "renesas,i2c-r8a7745" if the device is a part of a R8A7745 SoC. + "renesas,i2c-r8a77470" if the device is a part of a R8A77470 SoC. "renesas,i2c-r8a774a1" if the device is a part of a R8A774A1 SoC. + "renesas,i2c-r8a774c0" if the device is a part of a R8A774C0 SoC. "renesas,i2c-r8a7778" if the device is a part of a R8A7778 SoC. "renesas,i2c-r8a7779" if the device is a part of a R8A7779 SoC. "renesas,i2c-r8a7790" if the device is a part of a R8A7790 SoC. diff --git a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt index 872673adff5a..202602e6e837 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-sh_mobile.txt @@ -5,8 +5,10 @@ Required properties: - "renesas,iic-r8a73a4" (R-Mobile APE6) - "renesas,iic-r8a7740" (R-Mobile A1) - "renesas,iic-r8a7743" (RZ/G1M) + - "renesas,iic-r8a7744" (RZ/G1N) - "renesas,iic-r8a7745" (RZ/G1E) - "renesas,iic-r8a774a1" (RZ/G2M) + - "renesas,iic-r8a774c0" (RZ/G2E) - "renesas,iic-r8a7790" (R-Car H2) - "renesas,iic-r8a7791" (R-Car M2-W) - "renesas,iic-r8a7792" (R-Car V2H) @@ -15,6 +17,7 @@ Required properties: - "renesas,iic-r8a7795" (R-Car H3) - "renesas,iic-r8a7796" (R-Car M3-W) - "renesas,iic-r8a77965" (R-Car M3-N) + - "renesas,iic-r8a77990" (R-Car E3) - "renesas,iic-sh73a0" (SH-Mobile AG5) - "renesas,rcar-gen2-iic" (generic R-Car Gen2 or RZ/G1 compatible device) @@ -27,7 +30,13 @@ Required properties: the platform first followed by the generic R-Car version. - renesas,rmobile-iic must always follow. + When compatible with "renesas,rmobile-iic" it should + be the last compatibility string listed. + + The r8a77990 (R-Car E3) and r8a774c0 (RZ/G2E) + controllers are not considered compatible with + "renesas,rcar-gen3-iic" or "renesas,rmobile-iic" + due to the absence of automatic transmission registers. - reg : address start and address range size of device - interrupts : interrupt of device diff --git a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt index 3b5489966634..69240e189b01 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-stm32.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-stm32.txt @@ -26,6 +26,11 @@ Optional properties : - i2c-scl-falling-time-ns : Only for STM32F7, I2C SCL Falling time for the board (default: 10) I2C Timings are derived from these 2 values +- st,syscfg-fmp: Only for STM32F7, use to set Fast Mode Plus bit within SYSCFG + whether Fast Mode Plus speed is selected by slave. + 1st cell : phandle to syscfg + 2nd cell : register offset within SYSCFG + 3rd cell : register bitmask for FMP bit Example : @@ -53,4 +58,5 @@ Example : clocks = <&rcc 1 CLK_I2C1>; pinctrl-0 = <&i2c1_sda_pin>, <&i2c1_scl_pin>; pinctrl-names = "default"; + st,syscfg-fmp = <&syscfg 0x4 0x1>; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-xscale.txt b/Documentation/devicetree/bindings/i2c/i2c-xscale.txt new file mode 100644 index 000000000000..dcc8390e0d24 --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/i2c-xscale.txt @@ -0,0 +1,20 @@ +i2c Controller on XScale platforms such as IOP3xx and IXP4xx + +Required properties: +- compatible : Must be one of + "intel,iop3xx-i2c" + "intel,ixp4xx-i2c"; +- reg +- #address-cells = <1>; +- #size-cells = <0>; + +Optional properties: +- Child nodes conforming to i2c bus binding + +Example: + +i2c@c8011000 { + compatible = "intel,ixp4xx-i2c"; + reg = <0xc8011000 0x18>; + interrupts = <33 IRQ_TYPE_LEVEL_LOW>; +}; diff --git a/Documentation/devicetree/bindings/i2c/i2c.txt b/Documentation/devicetree/bindings/i2c/i2c.txt index 11263982470e..44efafdfd7f5 100644 --- a/Documentation/devicetree/bindings/i2c/i2c.txt +++ b/Documentation/devicetree/bindings/i2c/i2c.txt @@ -84,7 +84,7 @@ Binding may contain optional "interrupts" property, describing interrupts used by the device. I2C core will assign "irq" interrupt (or the very first interrupt if not using interrupt names) as primary interrupt for the slave. -Alternatively, devices supporting SMbus Host Notify, and connected to +Alternatively, devices supporting SMBus Host Notify, and connected to adapters that support this feature, may use "host-notify" property. I2C core will create a virtual interrupt for Host Notify and assign it as primary interrupt for the slave. diff --git a/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt b/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt new file mode 100644 index 000000000000..5dc5d2e2573d --- /dev/null +++ b/Documentation/devicetree/bindings/i2c/ibm,p8-occ-hwmon.txt @@ -0,0 +1,25 @@ +Device-tree bindings for I2C-based On-Chip Controller hwmon device +------------------------------------------------------------------ + +Required properties: + - compatible = "ibm,p8-occ-hwmon"; + - reg = <I2C address>; : I2C bus address + +Examples: + + i2c-bus@100 { + #address-cells = <1>; + #size-cells = <0>; + clock-frequency = <100000>; + < more properties > + + occ-hwmon@1 { + compatible = "ibm,p8-occ-hwmon"; + reg = <0x50>; + }; + + occ-hwmon@2 { + compatible = "ibm,p8-occ-hwmon"; + reg = <0x51>; + }; + }; diff --git a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt index 0fbbc6970ec5..42bfc09c8918 100644 --- a/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt +++ b/Documentation/devicetree/bindings/i2c/nxp,pca9541.txt @@ -22,7 +22,7 @@ Example: #size-cells = <0>; eeprom@54 { - compatible = "at,24c08"; + compatible = "atmel,24c08"; reg = <0x54>; }; }; diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt new file mode 100644 index 000000000000..69da2115abdc --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.txt @@ -0,0 +1,43 @@ +Bindings for cadence I3C master block +===================================== + +Required properties: +-------------------- +- compatible: shall be "cdns,i3c-master" +- clocks: shall reference the pclk and sysclk +- clock-names: shall contain "pclk" and "sysclk" +- interrupts: the interrupt line connected to this I3C master +- reg: I3C master registers + +Mandatory properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- #address-cells: shall be set to 1 +- #size-cells: shall be set to 0 + +Optional properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- i2c-scl-hz +- i3c-scl-hz + +I3C device connected on the bus follow the generic description (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details). + +Example: + + i3c-master@0d040000 { + compatible = "cdns,i3c-master"; + clocks = <&coreclock>, <&i3csysclock>; + clock-names = "pclk", "sysclk"; + interrupts = <3 0>; + reg = <0x0d040000 0x1000>; + #address-cells = <1>; + #size-cells = <0>; + i2c-scl-hz = <100000>; + + nunchuk: nunchuk@52 { + compatible = "nintendo,nunchuk"; + reg = <0x52 0x80000010 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/i3c/i3c.txt b/Documentation/devicetree/bindings/i3c/i3c.txt new file mode 100644 index 000000000000..ab729a0a86ae --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/i3c.txt @@ -0,0 +1,138 @@ +Generic device tree bindings for I3C busses +=========================================== + +This document describes generic bindings that should be used to describe I3C +busses in a device tree. + +Required properties +------------------- + +- #address-cells - should be <3>. Read more about addresses below. +- #size-cells - should be <0>. +- compatible - name of the I3C master controller driving the I3C bus + +For other required properties e.g. to describe register sets, +clocks, etc. check the binding documentation of the specific driver. +The node describing an I3C bus should be named i3c-master. + +Optional properties +------------------- + +These properties may not be supported by all I3C master drivers. Each I3C +master bindings should specify which of them are supported. + +- i3c-scl-hz: frequency of the SCL signal used for I3C transfers. + When undefined the core sets it to 12.5MHz. + +- i2c-scl-hz: frequency of the SCL signal used for I2C transfers. + When undefined, the core looks at LVR (Legacy Virtual Register) + values of I2C devices described in the device tree to determine + the maximum I2C frequency. + +I2C devices +=========== + +Each I2C device connected to the bus should be described in a subnode. All +properties described in Documentation/devicetree/bindings/i2c/i2c.txt are +valid here, but several new properties have been added. + +New constraint on existing properties: +-------------------------------------- +- reg: contains 3 cells + + first cell : still encoding the I2C address + + + second cell: shall be 0 + + + third cell: shall encode the I3C LVR (Legacy Virtual Register) + bit[31:8]: unused/ignored + bit[7:5]: I2C device index. Possible values + * 0: I2C device has a 50 ns spike filter + * 1: I2C device does not have a 50 ns spike filter but supports high + frequency on SCL + * 2: I2C device does not have a 50 ns spike filter and is not tolerant + to high frequencies + * 3-7: reserved + + bit[4]: tell whether the device operates in FM (Fast Mode) or FM+ mode + * 0: FM+ mode + * 1: FM mode + + bit[3:0]: device type + * 0-15: reserved + +The I2C node unit-address should always match the first cell of the reg +property: <device-type>@<i2c-address>. + +I3C devices +=========== + +All I3C devices are supposed to support DAA (Dynamic Address Assignment), and +are thus discoverable. So, by default, I3C devices do not have to be described +in the device tree. +This being said, one might want to attach extra resources to these devices, +and those resources may have to be described in the device tree, which in turn +means we have to describe I3C devices. + +Another use case for describing an I3C device in the device tree is when this +I3C device has a static I2C address and we want to assign it a specific I3C +dynamic address before the DAA takes place (so that other devices on the bus +can't take this dynamic address). + +The I3C device should be names <device-type>@<static-i2c-address>,<i3c-pid>, +where device-type is describing the type of device connected on the bus +(gpio-controller, sensor, ...). + +Required properties +------------------- +- reg: contains 3 cells + + first cell : encodes the static I2C address. Should be 0 if the device does + not have one (0 is not a valid I2C address). + + + second and third cells: should encode the ProvisionalID. The second cell + contains the manufacturer ID left-shifted by 1. + The third cell contains ORing of the part ID + left-shifted by 16, the instance ID left-shifted + by 12 and the extra information. This encoding is + following the PID definition provided by the I3C + specification. + +Optional properties +------------------- +- assigned-address: dynamic address to be assigned to this device. This + property is only valid if the I3C device has a static + address (first cell of the reg property != 0). + + +Example: + + i3c-master@d040000 { + compatible = "cdns,i3c-master"; + clocks = <&coreclock>, <&i3csysclock>; + clock-names = "pclk", "sysclk"; + interrupts = <3 0>; + reg = <0x0d040000 0x1000>; + #address-cells = <3>; + #size-cells = <0>; + i2c-scl-hz = <100000>; + + /* I2C device. */ + nunchuk: nunchuk@52 { + compatible = "nintendo,nunchuk"; + reg = <0x52 0x0 0x10>; + }; + + /* I3C device with a static I2C address. */ + thermal_sensor: sensor@68,39200144004 { + reg = <0x68 0x392 0x144004>; + assigned-address = <0xa>; + }; + + /* + * I3C device without a static I2C address but requiring + * resources described in the DT. + */ + sensor@0,39200154004 { + reg = <0x0 0x392 0x154004>; + clocks = <&clock_provider 0>; + }; + }; diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt new file mode 100644 index 000000000000..5020eb71eb8d --- /dev/null +++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.txt @@ -0,0 +1,41 @@ +Bindings for Synopsys DesignWare I3C master block +================================================= + +Required properties: +-------------------- +- compatible: shall be "snps,dw-i3c-master-1.00a" +- clocks: shall reference the core_clk +- interrupts: the interrupt line connected to this I3C master +- reg: Offset and length of I3C master registers + +Mandatory properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- #address-cells: shall be set to 3 +- #size-cells: shall be set to 0 + +Optional properties defined by the generic binding (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details): + +- i2c-scl-hz +- i3c-scl-hz + +I3C device connected on the bus follow the generic description (see +Documentation/devicetree/bindings/i3c/i3c.txt for more details). + +Example: + + i3c-master@2000 { + compatible = "snps,dw-i3c-master-1.00a"; + #address-cells = <3>; + #size-cells = <0>; + reg = <0x02000 0x1000>; + interrupts = <0>; + clocks = <&i3cclk>; + + eeprom@57{ + compatible = "atmel,24c01"; + reg = <0x57 0x0 0x10>; + pagesize = <0x8>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/adxl372.txt b/Documentation/devicetree/bindings/iio/accel/adxl372.txt new file mode 100644 index 000000000000..a289964756a7 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/accel/adxl372.txt @@ -0,0 +1,33 @@ +Analog Devices ADXL372 3-Axis, +/-(200g) Digital Accelerometer + +http://www.analog.com/media/en/technical-documentation/data-sheets/adxl372.pdf + +Required properties: + - compatible : should be "adi,adxl372" + - reg: the I2C address or SPI chip select number for the device + +Required properties for SPI bus usage: + - spi-max-frequency: Max SPI frequency to use + +Optional properties: + - interrupts: interrupt mapping for IRQ as documented in + Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Example for a I2C device node: + + accelerometer@53 { + compatible = "adi,adxl372"; + reg = <0x53>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + }; + +Example for a SPI device node: + + accelerometer@0 { + compatible = "adi,adxl372"; + reg = <0>; + spi-max-frequency = <1000000>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + }; diff --git a/Documentation/devicetree/bindings/iio/accel/lis302.txt b/Documentation/devicetree/bindings/iio/accel/lis302.txt index dfdce67826ba..764e28ec1a0a 100644 --- a/Documentation/devicetree/bindings/iio/accel/lis302.txt +++ b/Documentation/devicetree/bindings/iio/accel/lis302.txt @@ -64,7 +64,7 @@ Optional properties for all bus drivers: Example for a SPI device node: - lis302@0 { + accelerometer@0 { compatible = "st,lis302dl-spi"; reg = <0>; spi-max-frequency = <1000000>; @@ -89,7 +89,7 @@ Example for a SPI device node: Example for a I2C device node: - lis331dlh: lis331dlh@18 { + lis331dlh: accelerometer@18 { compatible = "st,lis331dlh", "st,lis3lv02d"; reg = <0x18>; Vdd-supply = <&lis3_reg>; diff --git a/Documentation/devicetree/bindings/iio/accel/mma8452.txt b/Documentation/devicetree/bindings/iio/accel/mma8452.txt index 2100e9af379c..e132394375a1 100644 --- a/Documentation/devicetree/bindings/iio/accel/mma8452.txt +++ b/Documentation/devicetree/bindings/iio/accel/mma8452.txt @@ -20,6 +20,10 @@ Optional properties: - interrupt-names: should contain "INT1" and/or "INT2", the accelerometer's interrupt line in use. + - vdd-supply: phandle to the regulator that provides vdd power to the accelerometer. + + - vddio-supply: phandle to the regulator that provides vddio power to the accelerometer. + Example: mma8453fc@1d { diff --git a/Documentation/devicetree/bindings/iio/adc/ad7949.txt b/Documentation/devicetree/bindings/iio/adc/ad7949.txt new file mode 100644 index 000000000000..c7f5057356b1 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ad7949.txt @@ -0,0 +1,16 @@ +* Analog Devices AD7949/AD7682/AD7689 + +Required properties: + - compatible: Should be one of + * "adi,ad7949" + * "adi,ad7682" + * "adi,ad7689" + - reg: spi chip select number for the device + - vref-supply: The regulator supply for ADC reference voltage + +Example: +adc@0 { + compatible = "adi,ad7949"; + reg = <0>; + vref-supply = <&vdd_supply>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/adc.txt b/Documentation/devicetree/bindings/iio/adc/adc.txt new file mode 100644 index 000000000000..5bbaa330a250 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adc.txt @@ -0,0 +1,23 @@ +Common ADCs properties + +Optional properties for child nodes: +- bipolar : Boolean, if set the channel is used in bipolar mode. +- diff-channels : Differential channels muxed for this ADC. The first value + specifies the positive input pin, the second value the negative + input pin. + +Example: + adc@0 { + compatible = "some,adc"; + ... + channel@0 { + bipolar; + diff-channels = <0 1>; + ... + }; + + channel@1 { + diff-channels = <2 3>; + ... + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7124.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.txt new file mode 100644 index 000000000000..416273dce569 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7124.txt @@ -0,0 +1,75 @@ +Analog Devices AD7124 ADC device driver + +Required properties for the AD7124: + - compatible: Must be one of "adi,ad7124-4" or "adi,ad7124-8" + - reg: SPI chip select number for the device + - spi-max-frequency: Max SPI frequency to use + see: Documentation/devicetree/bindings/spi/spi-bus.txt + - clocks: phandle to the master clock (mclk) + see: Documentation/devicetree/bindings/clock/clock-bindings.txt + - clock-names: Must be "mclk". + - interrupts: IRQ line for the ADC + see: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + + Required properties: + * #address-cells: Must be 1. + * #size-cells: Must be 0. + + Subnode(s) represent the external channels which are connected to the ADC. + Each subnode represents one channel and has the following properties: + Required properties: + * reg: The channel number. It can have up to 4 channels on ad7124-4 + and 8 channels on ad7124-8, numbered from 0 to 15. + * diff-channels: see: Documentation/devicetree/bindings/iio/adc/adc.txt + + Optional properties: + * bipolar: see: Documentation/devicetree/bindings/iio/adc/adc.txt + * adi,reference-select: Select the reference source to use when + converting on the the specific channel. Valid values are: + 0: REFIN1(+)/REFIN1(−). + 1: REFIN2(+)/REFIN2(−). + 3: AVDD + If this field is left empty, internal reference is selected. + +Optional properties: + - refin1-supply: refin1 supply can be used as reference for conversion. + - refin2-supply: refin2 supply can be used as reference for conversion. + - avdd-supply: avdd supply can be used as reference for conversion. + +Example: + adc@0 { + compatible = "adi,ad7124-4"; + reg = <0>; + spi-max-frequency = <5000000>; + interrupts = <25 2>; + interrupt-parent = <&gpio>; + refin1-supply = <&adc_vref>; + clocks = <&ad7124_mclk>; + clock-names = "mclk"; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + diff-channels = <0 1>; + adi,reference-select = <0>; + }; + + channel@1 { + reg = <1>; + bipolar; + diff-channels = <2 3>; + adi,reference-select = <0>; + }; + + channel@2 { + reg = <2>; + diff-channels = <4 5>; + }; + + channel@3 { + reg = <3>; + diff-channels = <6 7>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt new file mode 100644 index 000000000000..d7b6241ca881 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7606.txt @@ -0,0 +1,65 @@ +Analog Devices AD7606 Simultaneous Sampling ADC + +Required properties for the AD7606: + +- compatible: Must be one of + * "adi,ad7605-4" + * "adi,ad7606-8" + * "adi,ad7606-6" + * "adi,ad7606-4" +- reg: SPI chip select number for the device +- spi-max-frequency: Max SPI frequency to use + see: Documentation/devicetree/bindings/spi/spi-bus.txt +- spi-cpha: See Documentation/devicetree/bindings/spi/spi-bus.txt +- avcc-supply: phandle to the Avcc power supply +- interrupts: IRQ line for the ADC + see: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +- adi,conversion-start-gpios: must be the device tree identifier of the CONVST pin. + This logic input is used to initiate conversions on the analog + input channels. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. + +Optional properties: + +- reset-gpios: must be the device tree identifier of the RESET pin. If specified, + it will be asserted during driver probe. As the line is active high, + it should be marked GPIO_ACTIVE_HIGH. +- standby-gpios: must be the device tree identifier of the STBY pin. This pin is used + to place the AD7606 into one of two power-down modes, Standby mode or + Shutdown mode. As the line is active low, it should be marked + GPIO_ACTIVE_LOW. +- adi,first-data-gpios: must be the device tree identifier of the FRSTDATA pin. + The FRSTDATA output indicates when the first channel, V1, is + being read back on either the parallel, byte or serial interface. + As the line is active high, it should be marked GPIO_ACTIVE_HIGH. +- adi,range-gpios: must be the device tree identifier of the RANGE pin. The polarity on + this pin determines the input range of the analog input channels. If + this pin is tied to a logic high, the analog input range is ±10V for + all channels. If this pin is tied to a logic low, the analog input range + is ±5V for all channels. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. +- adi,oversampling-ratio-gpios: must be the device tree identifier of the over-sampling + mode pins. As the line is active high, it should be marked + GPIO_ACTIVE_HIGH. + +Example: + + adc@0 { + compatible = "adi,ad7606-8"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpol; + + avcc-supply = <&adc_vref>; + + interrupts = <25 IRQ_TYPE_EDGE_FALLING>; + interrupt-parent = <&gpio>; + + adi,conversion-start-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; + reset-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; + adi,first-data-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; + adi,oversampling-ratio-gpios = <&gpio 18 GPIO_ACTIVE_HIGH + &gpio 23 GPIO_ACTIVE_HIGH + &gpio 26 GPIO_ACTIVE_HIGH>; + standby-gpios = <&gpio 24 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.txt b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.txt new file mode 100644 index 000000000000..9f5b88cf680d --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad7768-1.txt @@ -0,0 +1,41 @@ +Analog Devices AD7768-1 ADC device driver + +Required properties for the AD7768-1: + +- compatible: Must be "adi,ad7768-1" +- reg: SPI chip select number for the device +- spi-max-frequency: Max SPI frequency to use + see: Documentation/devicetree/bindings/spi/spi-bus.txt +- clocks: phandle to the master clock (mclk) + see: Documentation/devicetree/bindings/clock/clock-bindings.txt +- clock-names: Must be "mclk". +- interrupts: IRQ line for the ADC + see: Documentation/devicetree/bindings/interrupt-controller/interrupts.txt +- vref-supply: vref supply can be used as reference for conversion +- adi,sync-in-gpios: must be the device tree identifier of the SYNC-IN pin. Enables + synchronization of multiple devices that require simultaneous sampling. + A pulse is always required if the configuration is changed in any way, for example + if the filter decimation rate changes. As the line is active low, it should + be marked GPIO_ACTIVE_LOW. + +Optional properties: + + - reset-gpios : GPIO spec for the RESET pin. If specified, it will be asserted during + driver probe. As the line is active low, it should be marked GPIO_ACTIVE_LOW. + +Example: + + adc@0 { + compatible = "adi,ad7768-1"; + reg = <0>; + spi-max-frequency = <2000000>; + spi-cpol; + spi-cpha; + vref-supply = <&adc_vref>; + interrupts = <25 IRQ_TYPE_EDGE_RISING>; + interrupt-parent = <&gpio>; + adi,sync-in-gpios = <&gpio 22 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio 27 GPIO_ACTIVE_LOW>; + clocks = <&ad7768_mclk>; + clock-names = "mclk"; + }; diff --git a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt index 54b823f3a453..75c775954102 100644 --- a/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt +++ b/Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.txt @@ -22,6 +22,16 @@ Required properties: - vref-supply: the regulator supply for the ADC reference voltage - #io-channel-cells: must be 1, see ../iio-bindings.txt +Optional properties: +- amlogic,hhi-sysctrl: phandle to the syscon which contains the 5th bit + of the TSC (temperature sensor coefficient) on + Meson8b and Meson8m2 (which used to calibrate the + temperature sensor) +- nvmem-cells: phandle to the temperature_calib eFuse cells +- nvmem-cell-names: if present (to enable the temperature sensor + calibration) this must contain "temperature_calib" + + Example: saradc: adc@8680 { compatible = "amlogic,meson-gxl-saradc", "amlogic,meson-saradc"; diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt new file mode 100644 index 000000000000..f01159f20d87 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt @@ -0,0 +1,48 @@ +* Ingenic JZ47xx ADC controller IIO bindings + +Required properties: + +- compatible: Should be one of: + * ingenic,jz4725b-adc + * ingenic,jz4740-adc +- reg: ADC controller registers location and length. +- clocks: phandle to the SoC's ADC clock. +- clock-names: Must be set to "adc". +- #io-channel-cells: Must be set to <1> to indicate channels are selected + by index. + +ADC clients must use the format described in iio-bindings.txt, giving +a phandle and IIO specifier pair ("io-channels") to the ADC controller. + +Example: + +#include <dt-bindings/iio/adc/ingenic,adc.h> + +adc: adc@10070000 { + compatible = "ingenic,jz4740-adc"; + #io-channel-cells = <1>; + + reg = <0x10070000 0x30>; + + clocks = <&cgu JZ4740_CLK_ADC>; + clock-names = "adc"; + + interrupt-parent = <&intc>; + interrupts = <18>; +}; + +adc-keys { + ... + compatible = "adc-keys"; + io-channels = <&adc INGENIC_ADC_AUX>; + io-channel-names = "buttons"; + ... +}; + +battery { + ... + compatible = "ingenic,jz4740-battery"; + io-channels = <&adc INGENIC_ADC_BATTERY>; + io-channel-names = "battery"; + ... +}; diff --git a/Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt b/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt index b3629d3a9adf..b3629d3a9adf 100644 --- a/Documentation/devicetree/bindings/staging/iio/adc/lpc32xx-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/lpc32xx-adc.txt diff --git a/Documentation/devicetree/bindings/iio/adc/mcp3911.txt b/Documentation/devicetree/bindings/iio/adc/mcp3911.txt new file mode 100644 index 000000000000..3071f48fb30b --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/mcp3911.txt @@ -0,0 +1,30 @@ +* Microchip MCP3911 Dual channel analog front end (ADC) + +Required properties: + - compatible: Should be "microchip,mcp3911" + - reg: SPI chip select number for the device + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt. + Max frequency for this chip is 20MHz. + +Optional properties: + - clocks: Phandle and clock identifier for sampling clock + - interrupt-parent: Phandle to the parent interrupt controller + - interrupts: IRQ line for the ADC + - microchip,device-addr: Device address when multiple MCP3911 chips are present on the + same SPI bus. Valid values are 0-3. Defaults to 0. + - vref-supply: Phandle to the external reference voltage supply. + +Example: +adc@0 { + compatible = "microchip,mcp3911"; + reg = <0>; + interrupt-parent = <&gpio5>; + interrupts = <15 IRQ_TYPE_EDGE_RISING>; + spi-max-frequency = <20000000>; + microchip,device-addr = <0>; + vref-supply = <&vref_reg>; + clocks = <&xtal>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm-adc.txt b/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm-adc.txt new file mode 100644 index 000000000000..eb939fe77836 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/nuvoton,npcm-adc.txt @@ -0,0 +1,24 @@ +Nuvoton NPCM Analog to Digital Converter (ADC) + +The NPCM ADC is a 10-bit converter for eight channel inputs. + +Required properties: +- compatible: "nuvoton,npcm750-adc" for the NPCM7XX BMC. +- reg: specifies physical base address and size of the registers. +- interrupts: Contain the ADC interrupt with flags for falling edge. + +Optional properties: +- clocks: phandle of ADC reference clock, in case the clock is not + added the ADC will use the default ADC sample rate. +- vref-supply: The regulator supply ADC reference voltage, in case the + vref-supply is not added the ADC will use internal voltage + reference. + +Example: + +adc: adc@f000c000 { + compatible = "nuvoton,npcm750-adc"; + reg = <0xf000c000 0x8>; + interrupts = <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk NPCM7XX_CLK_ADC>; +}; diff --git a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt index 0fb46137f936..c81993f8d8c3 100644 --- a/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt +++ b/Documentation/devicetree/bindings/iio/adc/qcom,spmi-vadc.txt @@ -1,7 +1,9 @@ -Qualcomm's SPMI PMIC voltage ADC +Qualcomm's SPMI PMIC ADC -SPMI PMIC voltage ADC (VADC) provides interface to clients to read -voltage. The VADC is a 15-bit sigma-delta ADC. +- SPMI PMIC voltage ADC (VADC) provides interface to clients to read + voltage. The VADC is a 15-bit sigma-delta ADC. +- SPMI PMIC5 voltage ADC (ADC) provides interface to clients to read + voltage. The VADC is a 16-bit sigma-delta ADC. VADC node: @@ -9,11 +11,13 @@ VADC node: Usage: required Value type: <string> Definition: Should contain "qcom,spmi-vadc". + Should contain "qcom,spmi-adc5" for PMIC5 ADC driver. + Should contain "qcom,spmi-adc-rev2" for PMIC rev2 ADC driver. - reg: Usage: required Value type: <prop-encoded-array> - Definition: VADC base address and length in the SPMI PMIC register map. + Definition: VADC base address in the SPMI PMIC register map. - #address-cells: Usage: required @@ -45,13 +49,26 @@ Channel node properties: Definition: ADC channel number. See include/dt-bindings/iio/qcom,spmi-vadc.h +- label: + Usage: required for "qcom,spmi-adc5" and "qcom,spmi-adc-rev2" + Value type: <empty> + Definition: ADC input of the platform as seen in the schematics. + For thermistor inputs connected to generic AMUX or GPIO inputs + these can vary across platform for the same pins. Hence select + the platform schematics name for this channel. + - qcom,decimation: Usage: optional Value type: <u32> Definition: This parameter is used to decrease ADC sampling rate. Quicker measurements can be made by reducing decimation ratio. - Valid values are 512, 1024, 2048, 4096. - If property is not found, default value of 512 will be used. + - For compatible property "qcom,spmi-vadc", valid values are + 512, 1024, 2048, 4096. If property is not found, default value + of 512 will be used. + - For compatible property "qcom,spmi-adc5", valid values are 250, 420 + and 840. If property is not found, default value of 840 is used. + - For compatible property "qcom,spmi-adc-rev2", valid values are 256, + 512 and 1024. If property is not present, default value is 1024. - qcom,pre-scaling: Usage: optional @@ -66,21 +83,38 @@ Channel node properties: - qcom,ratiometric: Usage: optional Value type: <empty> - Definition: Channel calibration type. If this property is specified - VADC will use the VDD reference (1.8V) and GND for channel - calibration. If property is not found, channel will be - calibrated with 0.625V and 1.25V reference channels, also - known as absolute calibration. + Definition: Channel calibration type. + - For compatible property "qcom,spmi-vadc", if this property is + specified VADC will use the VDD reference (1.8V) and GND for + channel calibration. If property is not found, channel will be + calibrated with 0.625V and 1.25V reference channels, also + known as absolute calibration. + - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", + if this property is specified VADC will use the VDD reference + (1.875V) and GND for channel calibration. If property is not found, + channel will be calibrated with 0V and 1.25V reference channels, + also known as absolute calibration. - qcom,hw-settle-time: Usage: optional Value type: <u32> Definition: Time between AMUX getting configured and the ADC starting - conversion. Delay = 100us * (value) for value < 11, and - 2ms * (value - 10) otherwise. - Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800, - 900 us and 1, 2, 4, 6, 8, 10 ms - If property is not found, channel will use 0us. + conversion. The 'hw_settle_time' is an index used from valid values + and programmed in hardware to achieve the hardware settling delay. + - For compatible property "qcom,spmi-vadc" and "qcom,spmi-adc-rev2", + Delay = 100us * (hw_settle_time) for hw_settle_time < 11, + and 2ms * (hw_settle_time - 10) otherwise. + Valid values are: 0, 100, 200, 300, 400, 500, 600, 700, 800, + 900 us and 1, 2, 4, 6, 8, 10 ms. + If property is not found, channel will use 0us. + - For compatible property "qcom,spmi-adc5", delay = 15us for + value 0, 100us * (value) for values < 11, + and 2ms * (value - 10) otherwise. + Valid values are: 15, 100, 200, 300, 400, 500, 600, 700, 800, + 900 us and 1, 2, 4, 6, 8, 10 ms + Certain controller digital versions have valid values of + 15, 100, 200, 300, 400, 500, 600, 700, 1, 2, 4, 8, 16, 32, 64, 128 ms + If property is not found, channel will use 15us. - qcom,avg-samples: Usage: optional @@ -89,22 +123,31 @@ Channel node properties: Averaging provides the option to obtain a single measurement from the ADC that is an average of multiple samples. The value selected is 2^(value). - Valid values are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 - If property is not found, 1 sample will be used. + - For compatible property "qcom,spmi-vadc", valid values + are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512 + If property is not found, 1 sample will be used. + - For compatible property "qcom,spmi-adc5" and "qcom,spmi-adc-rev2", + valid values are: 1, 2, 4, 8, 16 + If property is not found, 1 sample will be used. NOTE: -Following channels, also known as reference point channels, are used for -result calibration and their channel configuration nodes should be defined: +For compatible property "qcom,spmi-vadc" following channels, also known as +reference point channels, are used for result calibration and their channel +configuration nodes should be defined: VADC_REF_625MV and/or VADC_SPARE1(based on PMIC version) VADC_REF_1250MV, VADC_GND_REF and VADC_VDD_VADC. Example: +#include <dt-bindings/iio/qcom,spmi-vadc.h> +#include <linux/irq.h> +/* ... */ + /* VADC node */ pmic_vadc: vadc@3100 { compatible = "qcom,spmi-vadc"; - reg = <0x3100 0x100>; + reg = <0x3100>; interrupts = <0x0 0x31 0x0 IRQ_TYPE_EDGE_RISING>; #address-cells = <1>; #size-cells = <0>; @@ -112,7 +155,7 @@ Example: io-channel-ranges; /* Channel node */ - usb_id_nopull { + adc-chan@VADC_LR_MUX10_USB_ID { reg = <VADC_LR_MUX10_USB_ID>; qcom,decimation = <512>; qcom,ratiometric; diff --git a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.txt b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.txt index 6c49db7f8ad2..e1fe02f3e3e9 100644 --- a/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/samsung,exynos-adc.txt @@ -11,11 +11,13 @@ New driver handles the following Required properties: - compatible: Must be "samsung,exynos-adc-v1" - for exynos4412/5250 and s5pv210 controllers. + for Exynos5250 controllers. Must be "samsung,exynos-adc-v2" for future controllers. Must be "samsung,exynos3250-adc" for controllers compatible with ADC of Exynos3250. + Must be "samsung,exynos4212-adc" for + controllers compatible with ADC of Exynos4212 and Exynos4412. Must be "samsung,exynos7-adc" for the ADC in Exynos7 and compatibles Must be "samsung,s3c2410-adc" for @@ -28,6 +30,8 @@ Required properties: the ADC in s3c2443 and compatibles Must be "samsung,s3c6410-adc" for the ADC in s3c6410 and compatibles + Must be "samsung,s5pv210-adc" for + the ADC in s5pv210 and compatibles - reg: List of ADC register address range - The base address and range of ADC register - The base address and range of ADC_PHY register (every diff --git a/Documentation/devicetree/bindings/iio/adc/sprd,sc27xx-adc.txt b/Documentation/devicetree/bindings/iio/adc/sprd,sc27xx-adc.txt index 8aad960de50b..b4daa15dcf15 100644 --- a/Documentation/devicetree/bindings/iio/adc/sprd,sc27xx-adc.txt +++ b/Documentation/devicetree/bindings/iio/adc/sprd,sc27xx-adc.txt @@ -12,6 +12,8 @@ Required properties: - interrupts: The interrupt number for the ADC device. - #io-channel-cells: Number of cells in an IIO specifier. - hwlocks: Reference to a phandle of a hwlock provider node. +- nvmem-cells: A phandle to the calibration cells provided by eFuse device. +- nvmem-cell-names: Should be "big_scale_calib", "small_scale_calib". Example: @@ -32,5 +34,7 @@ Example: interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; #io-channel-cells = <1>; hwlocks = <&hwlock 4>; + nvmem-cells = <&adc_big_scale>, <&adc_small_scale>; + nvmem-cell-names = "big_scale_calib", "small_scale_calib"; }; }; diff --git a/Documentation/devicetree/bindings/iio/adc/stmpe-adc.txt b/Documentation/devicetree/bindings/iio/adc/stmpe-adc.txt new file mode 100644 index 000000000000..480e66422625 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/stmpe-adc.txt @@ -0,0 +1,21 @@ +STMPE ADC driver +---------------- + +Required properties: + - compatible: "st,stmpe-adc" + +Optional properties: +Note that the ADC is shared with the STMPE touchscreen. ADC related settings +have to be done in the mfd. +- st,norequest-mask: bitmask specifying which ADC channels should _not_ be + requestable due to different usage (e.g. touch) + +Node name must be stmpe_adc and should be child node of stmpe node to +which it belongs. + +Example: + + stmpe_adc { + compatible = "st,stmpe-adc"; + st,norequest-mask = <0x0F>; /* dont use ADC CH3-0 */ + }; diff --git a/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt b/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt index daa2b2c29428..c07ce1a3f5c4 100644 --- a/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt +++ b/Documentation/devicetree/bindings/iio/adc/ti-adc128s052.txt @@ -1,7 +1,14 @@ * Texas Instruments' ADC128S052, ADC122S021 and ADC124S021 ADC chip Required properties: - - compatible: Should be "ti,adc128s052", "ti,adc122s021" or "ti,adc124s021" + - compatible: Should be one of: + - "ti,adc128s052" + - "ti,adc122s021" + - "ti,adc122s051" + - "ti,adc122s101" + - "ti,adc124s021" + - "ti,adc124s051" + - "ti,adc124s101" - reg: spi chip select number for the device - vref-supply: The regulator supply for ADC reference voltage diff --git a/Documentation/devicetree/bindings/iio/adc/ti-ads124s08.txt b/Documentation/devicetree/bindings/iio/adc/ti-ads124s08.txt new file mode 100644 index 000000000000..ecf807bb32f7 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti-ads124s08.txt @@ -0,0 +1,25 @@ +* Texas Instruments' ads124s08 and ads124s06 ADC chip + +Required properties: + - compatible : + "ti,ads124s08" + "ti,ads124s06" + - reg : spi chip select number for the device + +Recommended properties: + - spi-max-frequency : Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + - spi-cpha : Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: + - reset-gpios : GPIO pin used to reset the device. + +Example: +adc@0 { + compatible = "ti,ads124s08"; + reg = <0>; + spi-max-frequency = <1000000>; + spi-cpha; + reset-gpios = <&gpio1 16 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/bme680.txt b/Documentation/devicetree/bindings/iio/chemical/bme680.txt new file mode 100644 index 000000000000..7f3827cfb2ff --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/bme680.txt @@ -0,0 +1,11 @@ +Bosch Sensortec BME680 pressure/temperature/humidity/voc sensors + +Required properties: +- compatible: must be "bosch,bme680" + +Example: + +bme680@76 { + compatible = "bosch,bme680"; + reg = <0x76>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt new file mode 100644 index 000000000000..7b5f06f324c8 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/plantower,pms7003.txt @@ -0,0 +1,20 @@ +* Plantower PMS7003 particulate matter sensor + +Required properties: +- compatible: must be "plantower,pms7003" +- vcc-supply: phandle to the regulator that provides power to the sensor + +Optional properties: +- plantower,set-gpios: phandle to the GPIO connected to the SET line +- reset-gpios: phandle to the GPIO connected to the RESET line + +Refer to serial/slave-device.txt for generic serial attached device bindings. + +Example: + +&uart0 { + air-pollution-sensor { + compatible = "plantower,pms7003"; + vcc-supply = <®_vcc5v0>; + }; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,sgp30.txt b/Documentation/devicetree/bindings/iio/chemical/sensirion,sgp30.txt new file mode 100644 index 000000000000..5844ed58173c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,sgp30.txt @@ -0,0 +1,15 @@ +* Sensirion SGP30/SGPC3 multi-pixel Gas Sensor + +Required properties: + + - compatible: must be one of + "sensirion,sgp30" + "sensirion,sgpc3" + - reg: the I2C address of the sensor + +Example: + +gas@58 { + compatible = "sensirion,sgp30"; + reg = <0x58>; +}; diff --git a/Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.txt b/Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.txt new file mode 100644 index 000000000000..6eee2709b5b6 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/chemical/sensirion,sps30.txt @@ -0,0 +1,12 @@ +* Sensirion SPS30 particulate matter sensor + +Required properties: +- compatible: must be "sensirion,sps30" +- reg: the I2C address of the sensor + +Example: + +sps30@69 { + compatible = "sensirion,sps30"; + reg = <0x69>; +}; diff --git a/Documentation/devicetree/bindings/iio/dac/ad5758.txt b/Documentation/devicetree/bindings/iio/dac/ad5758.txt index bba01a5cab1b..2f607f41f9d3 100644 --- a/Documentation/devicetree/bindings/iio/dac/ad5758.txt +++ b/Documentation/devicetree/bindings/iio/dac/ad5758.txt @@ -50,6 +50,9 @@ Required properties: Optional properties: + - reset-gpios : GPIO spec for the RESET pin. If specified, it will be + asserted during driver probe. + - adi,dc-dc-ilim-microamp: The dc-to-dc converter current limit The following values are currently supported [uA]: * 150000 @@ -71,6 +74,8 @@ AD5758 Example: spi-max-frequency = <1000000>; spi-cpha; + reset-gpios = <&gpio 22 0>; + adi,dc-dc-mode = <2>; adi,range-microvolt = <0 10000000>; adi,dc-dc-ilim-microamp = <200000>; diff --git a/Documentation/devicetree/bindings/iio/dac/ltc1660.txt b/Documentation/devicetree/bindings/iio/dac/ltc1660.txt new file mode 100644 index 000000000000..c5b5f22d6c64 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ltc1660.txt @@ -0,0 +1,21 @@ +* Linear Technology Micropower octal 8-Bit and 10-Bit DACs + +Required properties: + - compatible: Must be one of the following: + "lltc,ltc1660" + "lltc,ltc1665" + - reg: SPI chip select number for the device + - vref-supply: Phandle to the voltage reference supply + +Recommended properties: + - spi-max-frequency: Definition as per + Documentation/devicetree/bindings/spi/spi-bus.txt. + Max frequency for this chip is 5 MHz. + +Example: +dac@0 { + compatible = "lltc,ltc1660"; + reg = <0>; + spi-max-frequency = <5000000>; + vref-supply = <&vref_reg>; +}; diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7311.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7311.txt new file mode 100644 index 000000000000..e5a507db5e01 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7311.txt @@ -0,0 +1,23 @@ +TI DAC7311 device tree bindings + +Required properties: +- compatible: must be set to: + * "ti,dac7311" + * "ti,dac6311" + * "ti,dac5311" +- reg: spi chip select number for the device +- vref-supply: The regulator supply for ADC reference voltage + +Optional properties: +- spi-max-frequency: Max SPI frequency to use + +Example: + + spi_master { + dac@0 { + compatible = "ti,dac7311"; + reg = <0>; /* CS0 */ + spi-max-frequency = <1000000>; + vref-supply = <&vdd_supply>; + }; + }; diff --git a/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt new file mode 100644 index 000000000000..639c94ed83e9 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/dac/ti,dac7612.txt @@ -0,0 +1,28 @@ +* Texas Instruments Dual, 12-Bit Serial Input Digital-to-Analog Converter + +The DAC7612 is a dual, 12-bit digital-to-analog converter (DAC) with guaranteed +12-bit monotonicity performance over the industrial temperature range. +Is is programmable through an SPI interface. + +The internal DACs are loaded when the LOADDACS pin is pulled down. + +http://www.ti.com/lit/ds/sbas106/sbas106.pdf + +Required Properties: +- compatible: Should be one of: + "ti,dac7612" + "ti,dac7612u" + "ti,dac7612ub" +- reg: Definition as per Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional Properties: +- ti,loaddacs-gpios: GPIO descriptor for the LOADDACS pin. +- spi-*: Definition as per Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: + + dac@1 { + compatible = "ti,dac7612"; + reg = <0x1>; + ti,loaddacs-gpios = <&msmgpio 25 GPIO_ACTIVE_LOW>; + }; diff --git a/Documentation/devicetree/bindings/iio/impedance-analyzer/ad5933.txt b/Documentation/devicetree/bindings/iio/impedance-analyzer/ad5933.txt new file mode 100644 index 000000000000..5ff38728ff91 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/impedance-analyzer/ad5933.txt @@ -0,0 +1,26 @@ +Analog Devices AD5933/AD5934 Impedance Converter, Network Analyzer + +https://www.analog.com/media/en/technical-documentation/data-sheets/AD5933.pdf +https://www.analog.com/media/en/technical-documentation/data-sheets/AD5934.pdf + +Required properties: + - compatible : should be one of + "adi,ad5933" + "adi,ad5934" + - reg : the I2C address. + - vdd-supply : The regulator supply for DVDD, AVDD1 and AVDD2 when they + are connected together. + +Optional properties: +- clocks : external clock reference. +- clock-names : must be "mclk" if clocks is set. + +Example for a I2C device node: + + impedance-analyzer@0d { + compatible = "adi,adxl345"; + reg = <0x0d>; + vdd-supply = <&vdd_supply>; + clocks = <&ref_clk>; + clock-names = "mclk"; + }; diff --git a/Documentation/devicetree/bindings/iio/imu/bmi160.txt b/Documentation/devicetree/bindings/iio/imu/bmi160.txt index 0c1c105fb503..900c169de00f 100644 --- a/Documentation/devicetree/bindings/iio/imu/bmi160.txt +++ b/Documentation/devicetree/bindings/iio/imu/bmi160.txt @@ -9,9 +9,11 @@ Required properties: - spi-max-frequency : set maximum clock frequency (only for SPI) Optional properties: - - interrupts : interrupt mapping for IRQ, must be IRQ_TYPE_LEVEL_LOW + - interrupts : interrupt mapping for IRQ - interrupt-names : set to "INT1" if INT1 pin should be used as interrupt input, set to "INT2" if INT2 pin should be used instead + - drive-open-drain : set if the specified interrupt pin should be configured as + open drain. If not set, defaults to push-pull. Examples: @@ -20,7 +22,7 @@ bmi160@68 { reg = <0x68>; interrupt-parent = <&gpio4>; - interrupts = <12 IRQ_TYPE_LEVEL_LOW>; + interrupts = <12 IRQ_TYPE_EDGE_RISING>; interrupt-names = "INT1"; }; diff --git a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt b/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt index b2f27da847b8..268bf7568e19 100644 --- a/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt +++ b/Documentation/devicetree/bindings/iio/imu/inv_mpu6050.txt @@ -11,6 +11,7 @@ Required properties: "invensense,mpu9250" "invensense,mpu9255" "invensense,icm20608" + "invensense,icm20602" - reg : the I2C address of the sensor - interrupts: interrupt mapping for IRQ. It should be configured with flags IRQ_TYPE_LEVEL_HIGH, IRQ_TYPE_EDGE_RISING, IRQ_TYPE_LEVEL_LOW or @@ -20,6 +21,7 @@ Required properties: bindings. Optional properties: + - vddio-supply: regulator phandle for VDDIO supply - mount-matrix: an optional 3x3 mounting rotation matrix - i2c-gate node. These devices also support an auxiliary i2c bus. This is simple enough to be described using the i2c-gate binding. See diff --git a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt index ea2d6e0ae4c5..69d53d98d0f0 100644 --- a/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt +++ b/Documentation/devicetree/bindings/iio/imu/st_lsm6dsx.txt @@ -7,11 +7,13 @@ Required properties: "st,lsm6dsl" "st,lsm6dsm" "st,ism330dlc" + "st,lsm6dso" - 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). +- st,pullups : enable/disable internal i2c controller pullup resistors. - drive-open-drain: the interrupt/data ready line will be configured as open drain, which is useful if several sensors share the same interrupt line. This is a boolean property. diff --git a/Documentation/devicetree/bindings/iio/light/bh1750.txt b/Documentation/devicetree/bindings/iio/light/bh1750.txt new file mode 100644 index 000000000000..1e7685797d7a --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/bh1750.txt @@ -0,0 +1,18 @@ +ROHM BH1750 - ALS, Ambient light sensor + +Required properties: + +- compatible: Must be one of: + "rohm,bh1710" + "rohm,bh1715" + "rohm,bh1721" + "rohm,bh1750" + "rohm,bh1751" +- reg: the I2C address of the sensor + +Example: + +light-sensor@23 { + compatible = "rohm,bh1750"; + reg = <0x23>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/max44009.txt b/Documentation/devicetree/bindings/iio/light/max44009.txt new file mode 100644 index 000000000000..4a98848e35c0 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/max44009.txt @@ -0,0 +1,24 @@ +* MAX44009 Ambient Light Sensor + +Required properties: + +- compatible: should be "maxim,max44009" +- reg: the I2C address of the device (default is <0x4a>) + +Optional properties: + +- interrupts: interrupt mapping for GPIO IRQ. Should be configured with + IRQ_TYPE_EDGE_FALLING. + +Refer to interrupt-controller/interrupts.txt for generic interrupt client +node bindings. + +Example: + +light-sensor@4a { + compatible = "maxim,max44009"; + reg = <0x4a>; + + interrupt-parent = <&gpio1>; + interrupts = <17 IRQ_TYPE_EDGE_FALLING>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.txt b/Documentation/devicetree/bindings/iio/light/tsl2772.txt new file mode 100644 index 000000000000..1c5e6f17a1df --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/tsl2772.txt @@ -0,0 +1,42 @@ +* AMS/TAOS ALS and proximity sensor + +Required properties: + + - compatible: Should be one of + "amstaos,tsl2571" + "amstaos,tsl2671" + "amstaos,tmd2671" + "amstaos,tsl2771" + "amstaos,tmd2771" + "amstaos,tsl2572" + "amstaos,tsl2672" + "amstaos,tmd2672" + "amstaos,tsl2772" + "amstaos,tmd2772" + "avago,apds9930" + - reg: the I2C address of the device + +Optional properties: + + - amstaos,proximity-diodes - proximity diodes to enable. <0>, <1>, or <0 1> + are the only valid values. + - led-max-microamp - current for the proximity LED. Must be 100000, 50000, + 25000, or 13000. + - vdd-supply: phandle to the regulator that provides power to the sensor. + - vddio-supply: phandle to the regulator that provides power to the bus. + - interrupts: the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + +Example: + +tsl2772@39 { + compatible = "amstaos,tsl2772"; + reg = <0x39>; + interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>; + vdd-supply = <&pm8941_l17>; + vddio-supply = <&pm8941_lvs1>; + amstaos,proximity-diodes = <0>; + led-max-microamp = <100000>; +}; diff --git a/Documentation/devicetree/bindings/iio/light/vcnl4035.txt b/Documentation/devicetree/bindings/iio/light/vcnl4035.txt new file mode 100644 index 000000000000..c07c7f052556 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/light/vcnl4035.txt @@ -0,0 +1,18 @@ +VISHAY VCNL4035 - Ambient Light and proximity sensor + +Link to datasheet: https://www.vishay.com/docs/84251/vcnl4035x01.pdf + +Required properties: + + -compatible: should be "vishay,vcnl4035" + -reg: I2C address of the sensor, should be 0x60 + -interrupts: interrupt mapping for GPIO IRQ (level active low) + +Example: + +light-sensor@60 { + compatible = "vishay,vcnl4035"; + reg = <0x60>; + interrupt-parent = <&gpio4>; + interrupts = <11 IRQ_TYPE_LEVEL_LOW>; +}; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/mag3110.txt b/Documentation/devicetree/bindings/iio/magnetometer/mag3110.txt new file mode 100644 index 000000000000..bdd40bcaaa1f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/mag3110.txt @@ -0,0 +1,27 @@ +* FREESCALE MAG3110 magnetometer sensor + +Required properties: + + - compatible : should be "fsl,mag3110" + - reg : the I2C address of the magnetometer + +Optional properties: + + - interrupts: the sole interrupt generated by the device + + Refer to interrupt-controller/interrupts.txt for generic interrupt client + node bindings. + + - vdd-supply: phandle to the regulator that provides power to the sensor. + - vddio-supply: phandle to the regulator that provides power to the sensor's IO. + +Example: + +magnetometer@e { + compatible = "fsl,mag3110"; + reg = <0x0e>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_i2c3_mag3110_int>; + interrupt-parent = <&gpio3>; + interrupts = <16 IRQ_TYPE_EDGE_RISING>; +}; diff --git a/Documentation/devicetree/bindings/iio/magnetometer/pni,rm3100.txt b/Documentation/devicetree/bindings/iio/magnetometer/pni,rm3100.txt new file mode 100644 index 000000000000..497c932e9e39 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/magnetometer/pni,rm3100.txt @@ -0,0 +1,20 @@ +* PNI RM3100 3-axis magnetometer sensor + +Required properties: + +- compatible : should be "pni,rm3100" +- reg : the I2C address or SPI chip select number of the sensor. + +Optional properties: + +- interrupts: data ready (DRDY) from the chip. + The interrupts can be triggered on level high. + +Example: + +rm3100: rm3100@20 { + compatible = "pni,rm3100"; + reg = <0x20>; + interrupt-parent = <&gpio0>; + interrupts = <4 IRQ_TYPE_LEVEL_HIGH>; +}; diff --git a/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt new file mode 100644 index 000000000000..566711b9950c --- /dev/null +++ b/Documentation/devicetree/bindings/iio/potentiometer/mcp41010.txt @@ -0,0 +1,28 @@ +* Microchip MCP41010/41050/41100/42010/42050/42100 Digital Potentiometer + +Datasheet publicly available at: +http://ww1.microchip.com/downloads/en/devicedoc/11195c.pdf + +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: + "microchip,mcp41010" + "microchip,mcp41050" + "microchip,mcp41100" + "microchip,mcp42010" + "microchip,mcp42050" + "microchip,mcp42100" + +Example: +potentiometer@0 { + compatible = "microchip,mcp41010"; + reg = <0>; + spi-max-frequency = <500000>; +}; diff --git a/Documentation/devicetree/bindings/iio/proximity/vl53l0x.txt b/Documentation/devicetree/bindings/iio/proximity/vl53l0x.txt new file mode 100644 index 000000000000..aac5f621f8dc --- /dev/null +++ b/Documentation/devicetree/bindings/iio/proximity/vl53l0x.txt @@ -0,0 +1,12 @@ +ST VL53L0X ToF ranging sensor + +Required properties: + - compatible: must be "st,vl53l0x" + - reg: i2c address where to find the device + +Example: + +vl53l0x@29 { + compatible = "st,vl53l0x"; + reg = <0x29>; +}; diff --git a/Documentation/devicetree/bindings/iio/resolver/ad2s90.txt b/Documentation/devicetree/bindings/iio/resolver/ad2s90.txt new file mode 100644 index 000000000000..477d41fa6467 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/resolver/ad2s90.txt @@ -0,0 +1,31 @@ +Analog Devices AD2S90 Resolver-to-Digital Converter + +https://www.analog.com/en/products/ad2s90.html + +Required properties: + - compatible: should be "adi,ad2s90" + - reg: SPI chip select number for the device + - spi-max-frequency: set maximum clock frequency, must be 830000 + - spi-cpol and spi-cpha: + Either SPI mode (0,0) or (1,1) must be used, so specify none or both of + spi-cpha, spi-cpol. + +See for more details: + Documentation/devicetree/bindings/spi/spi-bus.txt + +Note about max frequency: + Chip's max frequency, as specified in its datasheet, is 2Mhz. But a 600ns + delay is expected between the application of a logic LO to CS and the + application of SCLK, as also specified. And since the delay is not + implemented in the spi code, to satisfy it, SCLK's period should be at most + 2 * 600ns, so the max frequency should be 1 / (2 * 6e-7), which gives + roughly 830000Hz. + +Example: +resolver@0 { + compatible = "adi,ad2s90"; + reg = <0>; + spi-max-frequency = <830000>; + spi-cpol; + spi-cpha; +}; diff --git a/Documentation/devicetree/bindings/iio/st-sensors.txt b/Documentation/devicetree/bindings/iio/st-sensors.txt index 6f626f73417e..52ee4baec6f0 100644 --- a/Documentation/devicetree/bindings/iio/st-sensors.txt +++ b/Documentation/devicetree/bindings/iio/st-sensors.txt @@ -48,6 +48,7 @@ Accelerometers: - st,lis3l02dq - st,lis2dw12 - st,lis3dhh +- st,lis3de Gyroscopes: - st,l3g4200d-gyro @@ -67,6 +68,7 @@ Magnetometers: - st,lsm303dlm-magn - st,lis3mdl-magn - st,lis2mdl +- st,lsm9ds1-magn Pressure sensors: - st,lps001wp-press @@ -75,3 +77,4 @@ Pressure sensors: - st,lps22hb-press - st,lps33hw - st,lps35hw +- st,lps22hh diff --git a/Documentation/devicetree/bindings/input/input-reset.txt b/Documentation/devicetree/bindings/input/input-reset.txt index 2bb2626fdb78..1ca6cc5ebf8e 100644 --- a/Documentation/devicetree/bindings/input/input-reset.txt +++ b/Documentation/devicetree/bindings/input/input-reset.txt @@ -12,7 +12,7 @@ The /chosen node should contain a 'linux,sysrq-reset-seq' child node to define a set of keys. Required property: -sysrq-reset-seq: array of Linux keycodes, one keycode per cell. +keyset: array of Linux keycodes, one keycode per cell. Optional property: timeout-ms: duration keys must be pressed together in milliseconds before diff --git a/Documentation/devicetree/bindings/input/pwm-vibrator.txt b/Documentation/devicetree/bindings/input/pwm-vibrator.txt index 09145d18491d..88c775a3fe21 100644 --- a/Documentation/devicetree/bindings/input/pwm-vibrator.txt +++ b/Documentation/devicetree/bindings/input/pwm-vibrator.txt @@ -58,8 +58,8 @@ Example from Motorola Droid 4: vibrator { compatible = "pwm-vibrator"; - pwms = <&pwm8 0 1000000000 0>, - <&pwm9 0 1000000000 0>; + pwms = <&pwm9 0 1000000000 0>, + <&pwm8 0 1000000000 0>; pwm-names = "enable", "direction"; direction-duty-cycle-ns = <1000000000>; }; diff --git a/Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt b/Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt new file mode 100644 index 000000000000..4494613ae7ad --- /dev/null +++ b/Documentation/devicetree/bindings/input/st,stpmic1-onkey.txt @@ -0,0 +1,28 @@ +STMicroelectronics STPMIC1 Onkey + +Required properties: + +- compatible = "st,stpmic1-onkey"; +- interrupts: interrupt line to use +- interrupt-names = "onkey-falling", "onkey-rising" + onkey-falling: happens when onkey is pressed; IT_PONKEY_F of pmic + onkey-rising: happens when onkey is released; IT_PONKEY_R of pmic + +Optional properties: + +- st,onkey-clear-cc-flag: onkey is able power on after an + over-current shutdown event. +- st,onkey-pu-inactive: onkey pull up is not active +- power-off-time-sec: Duration in seconds which the key should be kept + pressed for device to power off automatically (from 1 to 16 seconds). + see See Documentation/devicetree/bindings/input/keys.txt + +Example: + +onkey { + compatible = "st,stpmic1-onkey"; + interrupt-parent = <&pmic>; + interrupts = <IT_PONKEY_F 0>,<IT_PONKEY_R 1>; + interrupt-names = "onkey-falling", "onkey-rising"; + power-off-time-sec = <10>; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt b/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt new file mode 100644 index 000000000000..2a1af240ccc3 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/raspberrypi,firmware-ts.txt @@ -0,0 +1,26 @@ +Raspberry Pi firmware based 7" touchscreen +===================================== + +Required properties: + - compatible: "raspberrypi,firmware-ts" + +Optional properties: + - firmware: Reference to RPi's firmware device node + - 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: + +firmware: firmware-rpi { + compatible = "raspberrypi,bcm2835-firmware"; + mboxes = <&mailbox>; + + ts: touchscreen { + compatible = "raspberrypi,firmware-ts"; + touchscreen-size-x = <800>; + touchscreen-size-y = <480>; + }; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt b/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt index 127baa31a77a..c549924603d2 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/stmpe.txt @@ -5,39 +5,105 @@ Required properties: - compatible: "st,stmpe-ts" Optional properties: -- st,sample-time: ADC converstion time in number of clock. (0 -> 36 clocks, 1 -> - 44 clocks, 2 -> 56 clocks, 3 -> 64 clocks, 4 -> 80 clocks, 5 -> 96 clocks, 6 - -> 144 clocks), recommended is 4. -- st,mod-12b: ADC Bit mode (0 -> 10bit ADC, 1 -> 12bit ADC) -- st,ref-sel: ADC reference source (0 -> internal reference, 1 -> external - reference) -- st,adc-freq: ADC Clock speed (0 -> 1.625 MHz, 1 -> 3.25 MHz, 2 || 3 -> 6.5 MHz) -- st,ave-ctrl: Sample average control (0 -> 1 sample, 1 -> 2 samples, 2 -> 4 - samples, 3 -> 8 samples) -- st,touch-det-delay: Touch detect interrupt delay (0 -> 10 us, 1 -> 50 us, 2 -> - 100 us, 3 -> 500 us, 4-> 1 ms, 5 -> 5 ms, 6 -> 10 ms, 7 -> 50 ms) recommended - is 3 -- st,settling: Panel driver settling time (0 -> 10 us, 1 -> 100 us, 2 -> 500 us, 3 - -> 1 ms, 4 -> 5 ms, 5 -> 10 ms, 6 for 50 ms, 7 -> 100 ms) recommended is 2 -- st,fraction-z: Length of the fractional part in z (fraction-z ([0..7]) = Count of - the fractional part) recommended is 7 -- st,i-drive: current limit value of the touchscreen drivers (0 -> 20 mA typical 35 - mA max, 1 -> 50 mA typical 80 mA max) +- st,ave-ctrl : Sample average control + 0 -> 1 sample + 1 -> 2 samples + 2 -> 4 samples + 3 -> 8 samples +- st,touch-det-delay : Touch detect interrupt delay (recommended is 3) + 0 -> 10 us + 1 -> 50 us + 2 -> 100 us + 3 -> 500 us + 4 -> 1 ms + 5 -> 5 ms + 6 -> 10 ms + 7 -> 50 ms +- st,settling : Panel driver settling time (recommended is 2) + 0 -> 10 us + 1 -> 100 us + 2 -> 500 us + 3 -> 1 ms + 4 -> 5 ms + 5 -> 10 ms + 6 -> 50 ms + 7 -> 100 ms +- st,fraction-z : Length of the fractional part in z (recommended is 7) + (fraction-z ([0..7]) = Count of the fractional part) +- st,i-drive : current limit value of the touchscreen drivers + 0 -> 20 mA (typical 35mA max) + 1 -> 50 mA (typical 80 mA max) + +Optional properties common with MFD (deprecated): + - st,sample-time : ADC conversion time in number of clock. + 0 -> 36 clocks + 1 -> 44 clocks + 2 -> 56 clocks + 3 -> 64 clocks + 4 -> 80 clocks (recommended) + 5 -> 96 clocks + 6 -> 124 clocks + - st,mod-12b : ADC Bit mode + 0 -> 10bit ADC + 1 -> 12bit ADC + - st,ref-sel : ADC reference source + 0 -> internal + 1 -> external + - st,adc-freq : ADC Clock speed + 0 -> 1.625 MHz + 1 -> 3.25 MHz + 2 || 3 -> 6.5 MHz Node name must be stmpe_touchscreen and should be child node of stmpe node to which it belongs. +Note that common ADC settings of stmpe_touchscreen (child) will take precedence +over the settings done in MFD. + Example: +stmpe811@41 { + compatible = "st,stmpe811"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_touch_int>; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x41>; + interrupts = <10 IRQ_TYPE_LEVEL_LOW>; + interrupt-parent = <&gpio4>; + interrupt-controller; + id = <0>; + blocks = <0x5>; + irq-trigger = <0x1>; + /* Common ADC settings */ + /* 3.25 MHz ADC clock speed */ + st,adc-freq = <1>; + /* 12-bit ADC */ + st,mod-12b = <1>; + /* internal ADC reference */ + st,ref-sel = <0>; + /* ADC converstion time: 80 clocks */ + st,sample-time = <4>; + stmpe_touchscreen { compatible = "st,stmpe-ts"; - st,sample-time = <4>; - st,mod-12b = <1>; - st,ref-sel = <0>; - st,adc-freq = <1>; - st,ave-ctrl = <1>; - st,touch-det-delay = <2>; - st,settling = <2>; + reg = <0>; + /* 8 sample average control */ + st,ave-ctrl = <3>; + /* 5 ms touch detect interrupt delay */ + st,touch-det-delay = <5>; + /* 1 ms panel driver settling time */ + st,settling = <3>; + /* 7 length fractional part in z */ st,fraction-z = <7>; + /* + * 50 mA typical 80 mA max touchscreen drivers + * current limit value + */ st,i-drive = <1>; }; + stmpe_adc { + compatible = "st,stmpe-adc"; + st,norequest-mask = <0x0F>; + }; +}; diff --git a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt index b1163bf97146..aad5e34965eb 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/ti-tsc-adc.txt @@ -2,7 +2,12 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Required properties: +- mfd + compatible: Should be + "ti,am3359-tscadc" for AM335x/AM437x SoCs + "ti,am654-tscadc", "ti,am3359-tscadc" for AM654 SoCs - child "tsc" + compatible: Should be "ti,am3359-tsc". ti,wires: Wires refer to application modes i.e. 4/5/8 wire touchscreen support on the platform. ti,x-plate-resistance: X plate resistance @@ -25,6 +30,9 @@ Required properties: AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7. XP = 0, XN = 1, YP = 2, YN = 3. - child "adc" + compatible: Should be + "ti,am3359-adc" for AM335x/AM437x SoCs + "ti,am654-adc", "ti,am3359-adc" for AM654 SoCs ti,adc-channels: List of analog inputs available for ADC. AIN0 = 0, AIN1 = 1 and so on till AIN7 = 7. diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt index d092d5d033a0..8641a2d70851 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.txt @@ -1,10 +1,12 @@ General Touchscreen Properties: Optional properties for Touchscreens: + - touchscreen-min-x : minimum x coordinate reported (0 if not set) + - touchscreen-min-y : minimum y coordinate reported (0 if not set) - touchscreen-size-x : horizontal resolution of touchscreen - (in pixels) + (maximum x coordinate reported + 1) - touchscreen-size-y : vertical resolution of touchscreen - (in pixels) + (maximum y coordinate reported + 1) - touchscreen-max-pressure : maximum reported pressure (arbitrary range dependent on the controller) - touchscreen-min-pressure : minimum pressure on the touchscreen to be diff --git a/Documentation/devicetree/bindings/interconnect/interconnect.txt b/Documentation/devicetree/bindings/interconnect/interconnect.txt new file mode 100644 index 000000000000..5a3c575b387a --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/interconnect.txt @@ -0,0 +1,60 @@ +Interconnect Provider Device Tree Bindings +========================================= + +The purpose of this document is to define a common set of generic interconnect +providers/consumers properties. + + += interconnect providers = + +The interconnect provider binding is intended to represent the interconnect +controllers in the system. Each provider registers a set of interconnect +nodes, which expose the interconnect related capabilities of the interconnect +to consumer drivers. These capabilities can be throughput, latency, priority +etc. The consumer drivers set constraints on interconnect path (or endpoints) +depending on the use case. Interconnect providers can also be interconnect +consumers, such as in the case where two network-on-chip fabrics interface +directly. + +Required properties: +- compatible : contains the interconnect provider compatible string +- #interconnect-cells : number of cells in a interconnect specifier needed to + encode the interconnect node id + +Example: + + snoc: interconnect@580000 { + compatible = "qcom,msm8916-snoc"; + #interconnect-cells = <1>; + reg = <0x580000 0x14000>; + clock-names = "bus_clk", "bus_a_clk"; + clocks = <&rpmcc RPM_SMD_SNOC_CLK>, + <&rpmcc RPM_SMD_SNOC_A_CLK>; + }; + + += interconnect consumers = + +The interconnect consumers are device nodes which dynamically express their +bandwidth requirements along interconnect paths they are connected to. There +can be multiple interconnect providers on a SoC and the consumer may consume +multiple paths from different providers depending on use case and the +components it has to interact with. + +Required properties: +interconnects : Pairs of phandles and interconnect provider specifier to denote + the edge source and destination ports of the interconnect path. + +Optional properties: +interconnect-names : List of interconnect path name strings sorted in the same + order as the interconnects property. Consumers drivers will use + interconnect-names to match interconnect paths with interconnect + specifier pairs. + +Example: + + sdhci@7864000 { + ... + interconnects = <&pnoc MASTER_SDCC_1 &bimc SLAVE_EBI_CH0>; + interconnect-names = "sdhc-mem"; + }; diff --git a/Documentation/devicetree/bindings/interconnect/qcom,sdm845.txt b/Documentation/devicetree/bindings/interconnect/qcom,sdm845.txt new file mode 100644 index 000000000000..5c4f1d911630 --- /dev/null +++ b/Documentation/devicetree/bindings/interconnect/qcom,sdm845.txt @@ -0,0 +1,24 @@ +Qualcomm SDM845 Network-On-Chip interconnect driver binding +----------------------------------------------------------- + +SDM845 interconnect providers support system bandwidth requirements through +RPMh hardware accelerators known as Bus Clock Manager (BCM). The provider is +able to communicate with the BCM through the Resource State Coordinator (RSC) +associated with each execution environment. Provider nodes must reside within +an RPMh device node pertaining to their RSC and each provider maps to a single +RPMh resource. + +Required properties : +- compatible : shall contain only one of the following: + "qcom,sdm845-rsc-hlos" +- #interconnect-cells : should contain 1 + +Examples: + +apps_rsc: rsc { + rsc_hlos: interconnect { + compatible = "qcom,sdm845-rsc-hlos"; + #interconnect-cells = <1>; + }; +}; + diff --git a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt index b290ca150d30..404352524c3a 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/allwinner,sun4i-ic.txt @@ -2,7 +2,9 @@ Allwinner Sunxi Interrupt Controller Required properties: -- compatible : should be "allwinner,sun4i-a10-ic" +- compatible : should be one of the following: + "allwinner,sun4i-a10-ic" + "allwinner,suniv-f1c100s-ic" - reg : Specifies base physical address and size of the registers. - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Specifies the number of cells needed to encode an diff --git a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt index 3ea78c4ef887..a3be5298a5eb 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/arm,gic-v3.txt @@ -7,7 +7,9 @@ Interrupts (LPI). Main node required properties: -- compatible : should at least contain "arm,gic-v3". +- compatible : should at least contain "arm,gic-v3" or either + "qcom,msm8996-gic-v3", "arm,gic-v3" for msm8996 SoCs + to address SoC specific bugs/quirks - interrupt-controller : Identifies the node as an interrupt controller - #interrupt-cells : Specifies the number of cells needed to encode an interrupt source. Must be a single cell with a value of at least 3. @@ -76,7 +78,7 @@ Sub-nodes: PPI affinity can be expressed as a single "ppi-partitions" node, containing a set of sub-nodes, each with the following property: - affinity: Should be a list of phandles to CPU nodes (as described in -Documentation/devicetree/bindings/arm/cpus.txt). + Documentation/devicetree/bindings/arm/cpus.yaml). GICv3 has one or more Interrupt Translation Services (ITS) that are used to route Message Signalled Interrupts (MSI) to the CPUs. diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt new file mode 100644 index 000000000000..44286dcbac62 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/csky,apb-intc.txt @@ -0,0 +1,62 @@ +============================== +C-SKY APB Interrupt Controller +============================== + +C-SKY APB Interrupt Controller is a simple soc interrupt controller +on the apb bus and we only use it as root irq controller. + + - csky,apb-intc is used in a lot of csky fpgas and socs, it support 64 irq nums. + - csky,dual-apb-intc consists of 2 apb-intc and 128 irq nums supported. + - csky,gx6605s-intc is gx6605s soc internal irq interrupt controller, 64 irq nums. + +============================= +intc node bindings definition +============================= + + Description: Describes APB interrupt controller + + PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: must be "csky,apb-intc" + "csky,dual-apb-intc" + "csky,gx6605s-intc" + - #interrupt-cells + Usage: required + Value type: <u32> + Definition: must be <1> + - reg + Usage: required + Value type: <u32 u32> + Definition: <phyaddr size> in soc from cpu view + - interrupt-controller: + Usage: required + - csky,support-pulse-signal: + Usage: select + Description: to support pulse signal flag + +Examples: +--------- + + intc: interrupt-controller@500000 { + compatible = "csky,apb-intc"; + #interrupt-cells = <1>; + reg = <0x00500000 0x400>; + interrupt-controller; + }; + + intc: interrupt-controller@500000 { + compatible = "csky,dual-apb-intc"; + #interrupt-cells = <1>; + reg = <0x00500000 0x400>; + interrupt-controller; + }; + + intc: interrupt-controller@500000 { + compatible = "csky,gx6605s-intc"; + #interrupt-cells = <1>; + reg = <0x00500000 0x400>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt new file mode 100644 index 000000000000..ab921f1698fb --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/csky,mpintc.txt @@ -0,0 +1,40 @@ +=========================================== +C-SKY Multi-processors Interrupt Controller +=========================================== + +C-SKY Multi-processors Interrupt Controller is designed for ck807/ck810/ck860 +SMP soc, and it also could be used in non-SMP system. + +Interrupt number definition: + + 0-15 : software irq, and we use 15 as our IPI_IRQ. + 16-31 : private irq, and we use 16 as the co-processor timer. + 31-1024: common irq for soc ip. + +============================= +intc node bindings definition +============================= + + Description: Describes SMP interrupt controller + + PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: must be "csky,mpintc" + - #interrupt-cells + Usage: required + Value type: <u32> + Definition: must be <1> + - interrupt-controller: + Usage: required + +Examples: +--------- + + intc: interrupt-controller { + compatible = "csky,mpintc"; + #interrupt-cells = <1>; + interrupt-controller; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.txt b/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.txt new file mode 100644 index 000000000000..582991c426ee --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/fsl,irqsteer.txt @@ -0,0 +1,35 @@ +Freescale IRQSTEER Interrupt multiplexer + +Required properties: + +- compatible: should be: + - "fsl,imx8m-irqsteer" + - "fsl,imx-irqsteer" +- reg: Physical base address and size of registers. +- interrupts: Should contain the up to 8 parent interrupt lines used to + multiplex the input interrupts. They should be specified sequentially + from output 0 to 7. +- clocks: Should contain one clock for entry in clock-names + see Documentation/devicetree/bindings/clock/clock-bindings.txt +- clock-names: + - "ipg": main logic clock +- interrupt-controller: Identifies the node as an interrupt controller. +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- fsl,channel: The output channel that all input IRQs should be steered into. +- fsl,num-irqs: Number of input interrupts of this channel. + Should be multiple of 32 input interrupts and up to 512 interrupts. + +Example: + + interrupt-controller@32e2d000 { + compatible = "fsl,imx8m-irqsteer", "fsl,imx-irqsteer"; + reg = <0x32e2d000 0x1000>; + interrupts = <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX8MQ_CLK_DISP_APB_ROOT>; + clock-names = "ipg"; + fsl,channel = <0>; + fsl,num-irqs = <64>; + interrupt-controller; + #interrupt-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt new file mode 100644 index 000000000000..a63ed9fcb535 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/loongson,ls1x-intc.txt @@ -0,0 +1,24 @@ +Loongson ls1x Interrupt Controller + +Required properties: + +- compatible : should be "loongson,ls1x-intc". Valid strings are: + +- reg : Specifies base physical address and size of the registers. +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value shall be 2. +- interrupts : Specifies the CPU interrupt the controller is connected to. + +Example: + +intc: interrupt-controller@1fd01040 { + compatible = "loongson,ls1x-intc"; + reg = <0x1fd01040 0x18>; + + interrupt-controller; + #interrupt-cells = <2>; + + interrupt-parent = <&cpu_intc>; + interrupts = <2>; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt index 33a98eb44949..c5d589108a94 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt @@ -9,6 +9,7 @@ Required properties: "mediatek,mt8135-sysirq", "mediatek,mt6577-sysirq": for MT8135 "mediatek,mt8127-sysirq", "mediatek,mt6577-sysirq": for MT8127 "mediatek,mt7622-sysirq", "mediatek,mt6577-sysirq": for MT7622 + "mediatek,mt7623-sysirq", "mediatek,mt6577-sysirq": for MT7623 "mediatek,mt6795-sysirq", "mediatek,mt6577-sysirq": for MT6795 "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq": for MT6797 "mediatek,mt6765-sysirq", "mediatek,mt6577-sysirq": for MT6765 diff --git a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt index 8b53273cb22f..608fee15a4cf 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/mrvl,intc.txt @@ -5,7 +5,7 @@ Required properties: "mrvl,mmp2-mux-intc" - reg : Address and length of the register set of the interrupt controller. If the interrupt controller is intc, address and length means the range - of the whold interrupt controller. If the interrupt controller is mux-intc, + of the whole interrupt controller. If the interrupt controller is mux-intc, address and length means one register. Since address of mux-intc is in the range of intc. mux-intc is secondary interrupt controller. - reg-names : Name of the register set of the interrupt controller. It's diff --git a/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt b/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt new file mode 100644 index 000000000000..e0062aebf025 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/rda,8810pl-intc.txt @@ -0,0 +1,61 @@ +RDA Micro RDA8810PL Interrupt Controller + +The interrupt controller in RDA8810PL SoC is a custom interrupt controller +which supports up to 32 interrupts. + +Required properties: + +- compatible: Should be "rda,8810pl-intc". +- reg: Specifies base physical address of the registers set. +- interrupt-controller: Identifies the node as an interrupt controller. +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt source. The value shall be 2. + +The interrupt sources are as follows: + +ID Name +------------ +0: PULSE_DUMMY +1: I2C +2: NAND_NFSC +3: SDMMC1 +4: SDMMC2 +5: SDMMC3 +6: SPI1 +7: SPI2 +8: SPI3 +9: UART1 +10: UART2 +11: UART3 +12: GPIO1 +13: GPIO2 +14: GPIO3 +15: KEYPAD +16: TIMER +17: TIMEROS +18: COMREG0 +19: COMREG1 +20: USB +21: DMC +22: DMA +23: CAMERA +24: GOUDA +25: GPU +26: VPU_JPG +27: VPU_HOST +28: VOC +29: AUIFC0 +30: AUIFC1 +31: L2CC + +Example: + apb@20800000 { + compatible = "simple-bus"; + ... + intc: interrupt-controller@0 { + compatible = "rda,8810pl-intc"; + reg = <0x0 0x1000>; + interrupt-controller; + #interrupt-cells = <2>; + }; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt index 6a36bf66d932..cd01b2292ec6 100644 --- a/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt +++ b/Documentation/devicetree/bindings/interrupt-controller/st,stm32-exti.txt @@ -14,6 +14,10 @@ Required properties: (only needed for exti controller with multiple exti under same parent interrupt: st,stm32-exti and st,stm32h7-exti) +Optional properties: + +- hwlocks: reference to a phandle of a hardware spinlock provider node. + Example: exti: interrupt-controller@40013c00 { diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt index 8a6ffce12af5..3133f3ba7567 100644 --- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt @@ -17,10 +17,20 @@ conditions. "arm,mmu-401" "arm,mmu-500" "cavium,smmu-v2" + "qcom,smmu-v2" depending on the particular implementation and/or the version of the architecture implemented. + Qcom SoCs must contain, as below, SoC-specific compatibles + along with "qcom,smmu-v2": + "qcom,msm8996-smmu-v2", "qcom,smmu-v2", + "qcom,sdm845-smmu-v2", "qcom,smmu-v2". + + Qcom SoCs implementing "arm,mmu-500" must also include, + as below, SoC-specific compatibles: + "qcom,sdm845-smmu-500", "arm,mmu-500" + - reg : Base address and size of the SMMU. - #global-interrupts : The number of global interrupts exposed by the @@ -71,6 +81,22 @@ conditions. or using stream matching with #iommu-cells = <2>, and may be ignored if present in such cases. +- clock-names: List of the names of clocks input to the device. The + required list depends on particular implementation and + is as follows: + - for "qcom,smmu-v2": + - "bus": clock required for downstream bus access and + for the smmu ptw, + - "iface": clock required to access smmu's registers + through the TCU's programming interface. + - unspecified for other implementations. + +- clocks: Specifiers for all clocks listed in the clock-names property, + as per generic clock bindings. + +- power-domains: Specifiers for power domains required to be powered on for + the SMMU to operate, as per generic power domain bindings. + ** Deprecated properties: - mmu-masters (deprecated in favour of the generic "iommus" binding) : @@ -137,3 +163,20 @@ conditions. iommu-map = <0 &smmu3 0 0x400>; ... }; + + /* Qcom's arm,smmu-v2 implementation */ + smmu4: iommu@d00000 { + compatible = "qcom,msm8996-smmu-v2", "qcom,smmu-v2"; + reg = <0xd00000 0x10000>; + + #global-interrupts = <1>; + interrupts = <GIC_SPI 73 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 320 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 321 IRQ_TYPE_LEVEL_HIGH>; + #iommu-cells = <1>; + power-domains = <&mmcc MDSS_GDSC>; + + clocks = <&mmcc SMMU_MDP_AXI_CLK>, + <&mmcc SMMU_MDP_AHB_CLK>; + clock-names = "bus", "iface"; + }; diff --git a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt index df5db732138d..6922db598def 100644 --- a/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt +++ b/Documentation/devicetree/bindings/iommu/mediatek,iommu.txt @@ -41,6 +41,8 @@ Required properties: - compatible : must be one of the following string: "mediatek,mt2701-m4u" for mt2701 which uses generation one m4u HW. "mediatek,mt2712-m4u" for mt2712 which uses generation two m4u HW. + "mediatek,mt7623-m4u", "mediatek,mt2701-m4u" for mt7623 which uses + generation one m4u HW. "mediatek,mt8173-m4u" for mt8173 which uses generation two m4u HW. - reg : m4u register base and size. - interrupts : the interrupt of m4u. @@ -51,7 +53,7 @@ Required properties: according to the local arbiter index, like larb0, larb1, larb2... - iommu-cells : must be 1. This is the mtk_m4u_id according to the HW. Specifies the mtk_m4u_id as defined in - dt-binding/memory/mt2701-larb-port.h for mt2701, + dt-binding/memory/mt2701-larb-port.h for mt2701, mt7623 dt-binding/memory/mt2712-larb-port.h for mt2712, and dt-binding/memory/mt8173-larb-port.h for mt8173. diff --git a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt index c6e2d855fe13..b6bfbec3a849 100644 --- a/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt +++ b/Documentation/devicetree/bindings/iommu/renesas,ipmmu-vmsa.txt @@ -12,7 +12,10 @@ Required Properties: - "renesas,ipmmu-r8a73a4" for the R8A73A4 (R-Mobile APE6) IPMMU. - "renesas,ipmmu-r8a7743" for the R8A7743 (RZ/G1M) IPMMU. + - "renesas,ipmmu-r8a7744" for the R8A7744 (RZ/G1N) IPMMU. - "renesas,ipmmu-r8a7745" for the R8A7745 (RZ/G1E) IPMMU. + - "renesas,ipmmu-r8a774a1" for the R8A774A1 (RZ/G2M) IPMMU. + - "renesas,ipmmu-r8a774c0" for the R8A774C0 (RZ/G2E) IPMMU. - "renesas,ipmmu-r8a7790" for the R8A7790 (R-Car H2) IPMMU. - "renesas,ipmmu-r8a7791" for the R8A7791 (R-Car M2-W) IPMMU. - "renesas,ipmmu-r8a7793" for the R8A7793 (R-Car M2-N) IPMMU. diff --git a/Documentation/devicetree/bindings/leds/common.txt b/Documentation/devicetree/bindings/leds/common.txt index aa1399814a2a..70876ac11367 100644 --- a/Documentation/devicetree/bindings/leds/common.txt +++ b/Documentation/devicetree/bindings/leds/common.txt @@ -37,6 +37,18 @@ Optional properties for child nodes: "ide-disk" - LED indicates IDE disk activity (deprecated), in new implementations use "disk-activity" "timer" - LED flashes at a fixed, configurable rate + "pattern" - LED alters the brightness for the specified duration with one + software timer (requires "led-pattern" property) + +- led-pattern : Array of integers with default pattern for certain triggers. + Each trigger may parse this property differently: + - one-shot : two numbers specifying delay on and delay off (in ms), + - timer : two numbers specifying delay on and delay off (in ms), + - pattern : the pattern is given by a series of tuples, of + brightness and duration (in ms). The exact format is + described in: + Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt + - led-max-microamp : Maximum LED supply current in microamperes. This property can be made mandatory for the board configurations diff --git a/Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt b/Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt new file mode 100644 index 000000000000..d3696680bfc8 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/leds-trigger-pattern.txt @@ -0,0 +1,49 @@ +* Pattern format for LED pattern trigger + +The pattern is given by a series of tuples, of brightness and duration (ms). +The LED is expected to traverse the series and each brightness value for the +specified duration. Duration of 0 means brightness should immediately change to +new value, and writing malformed pattern deactivates any active one. + +1. For gradual dimming, the dimming interval now is set as 50 milliseconds. So +the tuple with duration less than dimming interval (50ms) is treated as a step +change of brightness, i.e. the subsequent brightness will be applied without +adding intervening dimming intervals. + +The gradual dimming format of the software pattern values should be: +"brightness_1 duration_1 brightness_2 duration_2 brightness_3 duration_3 ...". +For example (using sysfs interface): + +echo 0 1000 255 2000 > pattern + +It will make the LED go gradually from zero-intensity to max (255) intensity in +1000 milliseconds, then back to zero intensity in 2000 milliseconds: + +LED brightness + ^ +255-| / \ / \ / + | / \ / \ / + | / \ / \ / + | / \ / \ / + 0-| / \/ \/ + +---0----1----2----3----4----5----6------------> time (s) + +2. To make the LED go instantly from one brightness value to another, we should +use zero-time lengths (the brightness must be same as the previous tuple's). So +the format should be: "brightness_1 duration_1 brightness_1 0 brightness_2 +duration_2 brightness_2 0 ...". +For example (using sysfs interface): + +echo 0 1000 0 0 255 2000 255 0 > pattern + +It will make the LED stay off for one second, then stay at max brightness for +two seconds: + +LED brightness + ^ +255-| +---------+ +---------+ + | | | | | + | | | | | + | | | | | + 0-| -----+ +----+ +---- + +---0----1----2----3----4----5----6------------> time (s) diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt index b99d25fc2f26..ff3eafc5a882 100644 --- a/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt +++ b/Documentation/devicetree/bindings/mailbox/nvidia,tegra186-hsp.txt @@ -15,12 +15,15 @@ Required properties: Array of strings. one of: - "nvidia,tegra186-hsp" + - "nvidia,tegra194-hsp", "nvidia,tegra186-hsp" - reg : Offset and length of the register set for the device. - interrupt-names Array of strings. Contains a list of names for the interrupts described by the interrupt property. May contain the following entries, in any order: - "doorbell" + - "sharedN", where 'N' is a number from zero up to the number of + external interrupts supported by the HSP instance minus one. Users of this binding MUST look up entries in the interrupt property by name, using this interrupt-names property to do so. - interrupts @@ -29,12 +32,29 @@ Required properties: in a matching order. - #mbox-cells : Should be 2. -The mbox specifier of the "mboxes" property in the client node should -contain two data. The first one should be the HSP type and the second -one should be the ID that the client is going to use. Those information -can be found in the following file. +The mbox specifier of the "mboxes" property in the client node should contain +two cells. The first cell determines the HSP type and the second cell is used +to identify the mailbox that the client is going to use. -- <dt-bindings/mailbox/tegra186-hsp.h>. +For doorbells, the second cell specifies the index of the doorbell to use. + +For shared mailboxes, the second cell is composed of two fields: +- bits 31..24: + A bit mask of flags that further specify how the shared mailbox will be + used. Valid flags are: + - bit 31: + Defines the direction of the mailbox. If set, the mailbox will be used + as a producer (i.e. used to send data). If cleared, the mailbox is the + consumer of data sent by a producer. + +- bits 23.. 0: + The index of the shared mailbox to use. The number of available mailboxes + may vary by instance of the HSP block and SoC generation. + +The following file contains definitions that can be used to construct mailbox +specifiers: + + <dt-bindings/mailbox/tegra186-hsp.h> Example: diff --git a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt index 6e8a9ab0fdae..1232fc9fc709 100644 --- a/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt +++ b/Documentation/devicetree/bindings/mailbox/qcom,apcs-kpss-global.txt @@ -11,6 +11,7 @@ platforms. "qcom,msm8916-apcs-kpss-global", "qcom,msm8996-apcs-hmss-global" "qcom,msm8998-apcs-hmss-global" + "qcom,qcs404-apcs-apps-global" "qcom,sdm845-apss-shared" - reg: diff --git a/Documentation/devicetree/bindings/media/aspeed-video.txt b/Documentation/devicetree/bindings/media/aspeed-video.txt new file mode 100644 index 000000000000..78b464ae2672 --- /dev/null +++ b/Documentation/devicetree/bindings/media/aspeed-video.txt @@ -0,0 +1,26 @@ +* Device tree bindings for Aspeed Video Engine + +The Video Engine (VE) embedded in the Aspeed AST2400 and AST2500 SOCs can +capture and compress video data from digital or analog sources. + +Required properties: + - compatible: "aspeed,ast2400-video-engine" or + "aspeed,ast2500-video-engine" + - reg: contains the offset and length of the VE memory region + - clocks: clock specifiers for the syscon clocks associated with + the VE (ordering must match the clock-names property) + - clock-names: "vclk" and "eclk" + - resets: reset specifier for the syscon reset associated with + the VE + - interrupts: the interrupt associated with the VE on this platform + +Example: + +video-engine@1e700000 { + compatible = "aspeed,ast2500-video-engine"; + reg = <0x1e700000 0x20000>; + clocks = <&syscon ASPEED_CLK_GATE_VCLK>, <&syscon ASPEED_CLK_GATE_ECLK>; + clock-names = "vclk", "eclk"; + resets = <&syscon ASPEED_RESET_VIDEO>; + interrupts = <7>; +}; diff --git a/Documentation/devicetree/bindings/media/cedrus.txt b/Documentation/devicetree/bindings/media/cedrus.txt new file mode 100644 index 000000000000..bce0705df953 --- /dev/null +++ b/Documentation/devicetree/bindings/media/cedrus.txt @@ -0,0 +1,56 @@ +Device-tree bindings for the VPU found in Allwinner SoCs, referred to as the +Video Engine (VE) in Allwinner literature. + +The VPU can only access the first 256 MiB of DRAM, that are DMA-mapped starting +from the DRAM base. This requires specific memory allocation and handling. + +Required properties: +- compatible : must be one of the following compatibles: + - "allwinner,sun4i-a10-video-engine" + - "allwinner,sun5i-a13-video-engine" + - "allwinner,sun7i-a20-video-engine" + - "allwinner,sun8i-a33-video-engine" + - "allwinner,sun8i-h3-video-engine" + - "allwinner,sun50i-a64-video-engine" + - "allwinner,sun50i-h5-video-engine" +- reg : register base and length of VE; +- clocks : list of clock specifiers, corresponding to entries in + the clock-names property; +- clock-names : should contain "ahb", "mod" and "ram" entries; +- resets : phandle for reset; +- interrupts : VE interrupt number; +- allwinner,sram : SRAM region to use with the VE. + +Optional properties: +- memory-region : CMA pool to use for buffers allocation instead of the + default CMA pool. + +Example: + +reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + /* Address must be kept in the lower 256 MiBs of DRAM for VE. */ + cma_pool: default-pool { + compatible = "shared-dma-pool"; + size = <0x6000000>; + alloc-ranges = <0x4a000000 0x6000000>; + reusable; + linux,cma-default; + }; +}; + +video-codec@1c0e000 { + compatible = "allwinner,sun7i-a20-video-engine"; + reg = <0x01c0e000 0x1000>; + + clocks = <&ccu CLK_AHB_VE>, <&ccu CLK_VE>, + <&ccu CLK_DRAM_VE>; + clock-names = "ahb", "mod", "ram"; + + resets = <&ccu RST_VE>; + interrupts = <GIC_SPI 53 IRQ_TYPE_LEVEL_HIGH>; + allwinner,sram = <&ve_sram 1>; +}; diff --git a/Documentation/devicetree/bindings/media/fsl-pxp.txt b/Documentation/devicetree/bindings/media/fsl-pxp.txt new file mode 100644 index 000000000000..2477e7f87381 --- /dev/null +++ b/Documentation/devicetree/bindings/media/fsl-pxp.txt @@ -0,0 +1,26 @@ +Freescale Pixel Pipeline +======================== + +The Pixel Pipeline (PXP) is a memory-to-memory graphics processing engine +that supports scaling, colorspace conversion, alpha blending, rotation, and +pixel conversion via lookup table. Different versions are present on various +i.MX SoCs from i.MX23 to i.MX7. + +Required properties: +- compatible: should be "fsl,<soc>-pxp", where SoC can be one of imx23, imx28, + imx6dl, imx6sl, imx6ul, imx6sx, imx6ull, or imx7d. +- reg: the register base and size for the device registers +- interrupts: the PXP interrupt, two interrupts for imx6ull and imx7d. +- clock-names: should be "axi" +- clocks: the PXP AXI clock + +Example: + +pxp@21cc000 { + compatible = "fsl,imx6ull-pxp"; + reg = <0x021cc000 0x4000>; + interrupts = <GIC_SPI 8 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 18 IRQ_TYPE_LEVEL_HIGH>; + clock-names = "axi"; + clocks = <&clks IMX6UL_CLK_PXP>; +}; diff --git a/Documentation/devicetree/bindings/media/i2c/adv748x.txt b/Documentation/devicetree/bindings/media/i2c/adv748x.txt index 21ffb5ed8183..5dddc95f9cc4 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv748x.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv748x.txt @@ -10,7 +10,11 @@ Required Properties: - "adi,adv7481" for the ADV7481 - "adi,adv7482" for the ADV7482 - - reg: I2C slave address + - reg: I2C slave addresses + The ADV748x has up to twelve 256-byte maps that can be accessed via the + main I2C ports. Each map has it own I2C address and acts as a standard + slave device on the I2C bus. The main address is mandatory, others are + optional and remain at default values if not specified. Optional Properties: @@ -18,6 +22,11 @@ Optional Properties: "intrq3". All interrupts are optional. The "intrq3" interrupt is only available on the adv7481 - interrupts: Specify the interrupt lines for the ADV748x + - reg-names : Names of maps with programmable addresses. + It shall contain all maps needing a non-default address. + Possible map names are: + "main", "dpll", "cp", "hdmi", "edid", "repeater", + "infoframe", "cbus", "cec", "sdp", "txa", "txb" The device node must contain one 'port' child node per device input and output port, in accordance with the video interface bindings defined in @@ -47,7 +56,10 @@ Example: video-receiver@70 { compatible = "adi,adv7482"; - reg = <0x70>; + reg = <0x70 0x71 0x72 0x73 0x74 0x75 + 0x60 0x61 0x62 0x63 0x64 0x65>; + reg-names = "main", "dpll", "cp", "hdmi", "edid", "repeater", + "infoframe", "cbus", "cec", "sdp", "txa", "txb"; #address-cells = <1>; #size-cells = <0>; @@ -73,7 +85,7 @@ Example: }; }; - port@10 { + port@a { reg = <10>; adv7482_txa: endpoint { @@ -83,7 +95,7 @@ Example: }; }; - port@11 { + port@b { reg = <11>; adv7482_txb: endpoint { diff --git a/Documentation/devicetree/bindings/media/i2c/adv7604.txt b/Documentation/devicetree/bindings/media/i2c/adv7604.txt index dcf57e7c60eb..b3e688b77a38 100644 --- a/Documentation/devicetree/bindings/media/i2c/adv7604.txt +++ b/Documentation/devicetree/bindings/media/i2c/adv7604.txt @@ -66,7 +66,7 @@ Example: * other maps will retain their default addresses. */ reg = <0x4c>, <0x66>; - reg-names "main", "edid"; + reg-names = "main", "edid"; reset-gpios = <&ioexp 0 GPIO_ACTIVE_LOW>; hpd-gpios = <&ioexp 2 GPIO_ACTIVE_HIGH>; diff --git a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807.txt b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.txt index c4701f1eaaf6..c4701f1eaaf6 100644 --- a/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807.txt +++ b/Documentation/devicetree/bindings/media/i2c/dongwoon,dw9807-vcm.txt diff --git a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt index 6b910036b57e..d0bed6fa901a 100644 --- a/Documentation/devicetree/bindings/media/i2c/mt9m111.txt +++ b/Documentation/devicetree/bindings/media/i2c/mt9m111.txt @@ -9,8 +9,14 @@ Required Properties: - clocks: reference to the master clock. - clock-names: shall be "mclk". -For further reading on port node refer to -Documentation/devicetree/bindings/media/video-interfaces.txt. +The device node must contain one 'port' child node with one 'endpoint' child +sub-node for its digital output video port, in accordance with the video +interface bindings defined in: +Documentation/devicetree/bindings/media/video-interfaces.txt + +Optional endpoint properties: +- pclk-sample: For information see ../video-interfaces.txt. The value is set to + 0 if it isn't specified. Example: @@ -21,11 +27,10 @@ Example: clocks = <&mclk>; clock-names = "mclk"; - remote = <&pxa_camera>; port { mt9m111_1: endpoint { - bus-width = <8>; remote-endpoint = <&pxa_camera>; + pclk-sample = <1>; }; }; }; diff --git a/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt b/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt new file mode 100644 index 000000000000..f11f28a5fda4 --- /dev/null +++ b/Documentation/devicetree/bindings/media/i2c/sony,imx214.txt @@ -0,0 +1,53 @@ +* Sony 1/3.06-Inch 13.13Mp CMOS Digital Image Sensor + +The Sony imx214 is a 1/3.06-inch CMOS active pixel digital image sensor with +an active array size of 4224H x 3200V. It is programmable through an I2C +interface. +Image data is sent through MIPI CSI-2, through 2 or 4 lanes at a maximum +throughput of 1.2Gbps/lane. + + +Required Properties: +- compatible: Shall be "sony,imx214". +- reg: I2C bus address of the device. Depending on how the sensor is wired, + it shall be <0x10> or <0x1a>; +- enable-gpios: GPIO descriptor for the enable pin. +- vdddo-supply: Chip digital IO regulator (1.8V). +- vdda-supply: Chip analog regulator (2.7V). +- vddd-supply: Chip digital core regulator (1.12V). +- clocks: Reference to the xclk clock. +- clock-frequency: Frequency of the xclk clock. + +Optional Properties: +- flash-leds: See ../video-interfaces.txt +- lens-focus: See ../video-interfaces.txt + +The imx214 device node shall contain one 'port' child node with +an 'endpoint' subnode. For further reading on port node refer to +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Required Properties on endpoint: +- data-lanes: check ../video-interfaces.txt +- link-frequencies: check ../video-interfaces.txt +- remote-endpoint: check ../video-interfaces.txt + +Example: + + camera-sensor@1a { + compatible = "sony,imx214"; + reg = <0x1a>; + vdddo-supply = <&pm8994_lvs1>; + vddd-supply = <&camera_vddd_1v12>; + vdda-supply = <&pm8994_l17>; + lens-focus = <&ad5820>; + enable-gpios = <&msmgpio 25 GPIO_ACTIVE_HIGH>; + clocks = <&mmcc CAMSS_MCLK0_CLK>; + clock-frequency = <24000000>; + port { + imx214_ep: endpoint { + data-lanes = <1 2 3 4>; + link-frequencies = /bits/ 64 <480000000>; + remote-endpoint = <&csiphy0_ep>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt index 3813947b4d4f..044b11913c49 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-decoder.txt @@ -5,6 +5,7 @@ Mediatek JPEG Decoder is the JPEG decode hardware present in Mediatek SoCs Required properties: - compatible : must be one of the following string: "mediatek,mt8173-jpgdec" + "mediatek,mt7623-jpgdec", "mediatek,mt2701-jpgdec" "mediatek,mt2701-jpgdec" - reg : physical base address of the jpeg decoder registers and length of memory mapped region. diff --git a/Documentation/devicetree/bindings/media/qcom,venus.txt b/Documentation/devicetree/bindings/media/qcom,venus.txt index 00d0d1bf7647..b602c4c025e7 100644 --- a/Documentation/devicetree/bindings/media/qcom,venus.txt +++ b/Documentation/devicetree/bindings/media/qcom,venus.txt @@ -53,7 +53,8 @@ * Subnodes The Venus video-codec node must contain two subnodes representing -video-decoder and video-encoder. +video-decoder and video-encoder, and one optional firmware subnode. +Firmware subnode is needed when the platform does not have TrustZone. Every of video-encoder or video-decoder subnode should have: @@ -79,6 +80,13 @@ Every of video-encoder or video-decoder subnode should have: power domain which is responsible for collapsing and restoring power to the subcore. +The firmware subnode must have: + +- iommus: + Usage: required + Value type: <prop-encoded-array> + Definition: A list of phandle and IOMMU specifier pairs. + * An Example video-codec@1d00000 { compatible = "qcom,msm8916-venus"; @@ -105,4 +113,8 @@ Every of video-encoder or video-decoder subnode should have: clock-names = "core"; power-domains = <&mmcc VENUS_CORE1_GDSC>; }; + + video-firmware { + iommus = <&apps_iommu 0x10b2 0x0>; + }; }; diff --git a/Documentation/devicetree/bindings/media/rcar_vin.txt b/Documentation/devicetree/bindings/media/rcar_vin.txt index 2f420050d57f..0dd84a183ca7 100644 --- a/Documentation/devicetree/bindings/media/rcar_vin.txt +++ b/Documentation/devicetree/bindings/media/rcar_vin.txt @@ -11,6 +11,7 @@ on Gen3 platforms to a CSI-2 receiver. - compatible: Must be one or more of the following - "renesas,vin-r8a7743" for the R8A7743 device + - "renesas,vin-r8a7744" for the R8A7744 device - "renesas,vin-r8a7745" for the R8A7745 device - "renesas,vin-r8a7778" for the R8A7778 device - "renesas,vin-r8a7779" for the R8A7779 device @@ -23,6 +24,8 @@ on Gen3 platforms to a CSI-2 receiver. - "renesas,vin-r8a7796" for the R8A7796 device - "renesas,vin-r8a77965" for the R8A77965 device - "renesas,vin-r8a77970" for the R8A77970 device + - "renesas,vin-r8a77980" for the R8A77980 device + - "renesas,vin-r8a77990" for the R8A77990 device - "renesas,vin-r8a77995" for the R8A77995 device - "renesas,rcar-gen2-vin" for a generic R-Car Gen2 or RZ/G1 compatible device. diff --git a/Documentation/devicetree/bindings/media/renesas,ceu.txt b/Documentation/devicetree/bindings/media/renesas,ceu.txt index 8a7a616e9019..3e2a2652eb19 100644 --- a/Documentation/devicetree/bindings/media/renesas,ceu.txt +++ b/Documentation/devicetree/bindings/media/renesas,ceu.txt @@ -17,15 +17,19 @@ Required properties: The CEU supports a single parallel input and should contain a single 'port' subnode with a single 'endpoint'. Connection to input devices are modeled according to the video interfaces OF bindings specified in: -Documentation/devicetree/bindings/media/video-interfaces.txt +[1] Documentation/devicetree/bindings/media/video-interfaces.txt Optional endpoint properties applicable to parallel input bus described in the above mentioned "video-interfaces.txt" file are supported. -- hsync-active: Active state of the HSYNC signal, 0/1 for LOW/HIGH respectively. - If property is not present, default is active high. -- vsync-active: Active state of the VSYNC signal, 0/1 for LOW/HIGH respectively. - If property is not present, default is active high. +- hsync-active: See [1] for description. If property is not present, + default is active high. +- vsync-active: See [1] for description. If property is not present, + default is active high. +- bus-width: See [1] for description. Accepted values are '8' and '16'. + If property is not present, default is '8'. +- field-even-active: See [1] for description. If property is not present, + an even field is identified by a logic 0 (active-low signal). Example: diff --git a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt index 2d385b65b275..541d936b62e8 100644 --- a/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt +++ b/Documentation/devicetree/bindings/media/renesas,rcar-csi2.txt @@ -12,6 +12,8 @@ Mandatory properties - "renesas,r8a7796-csi2" for the R8A7796 device. - "renesas,r8a77965-csi2" for the R8A77965 device. - "renesas,r8a77970-csi2" for the R8A77970 device. + - "renesas,r8a77980-csi2" for the R8A77980 device. + - "renesas,r8a77990-csi2" for the R8A77990 device. - reg: the register base and size for the device registers - interrupts: the interrupt for the device diff --git a/Documentation/devicetree/bindings/media/rockchip-vpu.txt b/Documentation/devicetree/bindings/media/rockchip-vpu.txt new file mode 100644 index 000000000000..35dc464ad7c8 --- /dev/null +++ b/Documentation/devicetree/bindings/media/rockchip-vpu.txt @@ -0,0 +1,29 @@ +device-tree bindings for rockchip VPU codec + +Rockchip (Video Processing Unit) present in various Rockchip platforms, +such as RK3288 and RK3399. + +Required properties: +- compatible: value should be one of the following + "rockchip,rk3288-vpu"; + "rockchip,rk3399-vpu"; +- interrupts: encoding and decoding interrupt specifiers +- interrupt-names: should be "vepu" and "vdpu" +- clocks: phandle to VPU aclk, hclk clocks +- clock-names: should be "aclk" and "hclk" +- power-domains: phandle to power domain node +- iommus: phandle to a iommu node + +Example: +SoC-specific DT entry: + vpu: video-codec@ff9a0000 { + compatible = "rockchip,rk3288-vpu"; + reg = <0x0 0xff9a0000 0x0 0x800>; + interrupts = <GIC_SPI 9 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 10 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "vepu", "vdpu"; + clocks = <&cru ACLK_VCODEC>, <&cru HCLK_VCODEC>; + clock-names = "aclk", "hclk"; + power-domains = <&power RK3288_PD_VIDEO>; + iommus = <&vpu_mmu>; + }; diff --git a/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt b/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt index fc5aa263abe5..98a72c0b3c64 100644 --- a/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt +++ b/Documentation/devicetree/bindings/media/spi/sony-cxd2880.txt @@ -5,6 +5,10 @@ Required properties: - reg: SPI chip select number for the device. - spi-max-frequency: Maximum bus speed, should be set to <55000000> (55MHz). +Optional properties: +- vcc-supply: Optional phandle to the vcc regulator to power the adapter, + as described in the file ../regulator/regulator.txt + Example: cxd2880@0 { diff --git a/Documentation/devicetree/bindings/media/sun6i-csi.txt b/Documentation/devicetree/bindings/media/sun6i-csi.txt new file mode 100644 index 000000000000..d4ab34f2240c --- /dev/null +++ b/Documentation/devicetree/bindings/media/sun6i-csi.txt @@ -0,0 +1,59 @@ +Allwinner V3s Camera Sensor Interface +------------------------------------- + +Allwinner V3s SoC features a CSI module(CSI1) with parallel interface. + +Required properties: + - compatible: value must be one of: + * "allwinner,sun6i-a31-csi" + * "allwinner,sun8i-h3-csi", "allwinner,sun6i-a31-csi" + * "allwinner,sun8i-v3s-csi" + - reg: base address and size of the memory-mapped region. + - interrupts: interrupt associated to this IP + - clocks: phandles to the clocks feeding the CSI + * bus: the CSI interface clock + * mod: the CSI module clock + * ram: the CSI DRAM clock + - clock-names: the clock names mentioned above + - resets: phandles to the reset line driving the CSI + +The CSI node should contain one 'port' child node with one child 'endpoint' +node, according to the bindings defined in +Documentation/devicetree/bindings/media/video-interfaces.txt. + +Endpoint node properties for CSI +--------------------------------- +See the video-interfaces.txt for a detailed description of these properties. +- remote-endpoint : (required) a phandle to the bus receiver's endpoint + node +- bus-width: : (required) must be 8, 10, 12 or 16 +- pclk-sample : (optional) (default: sample on falling edge) +- hsync-active : (required; parallel-only) +- vsync-active : (required; parallel-only) + +Example: + +csi1: csi@1cb4000 { + compatible = "allwinner,sun8i-v3s-csi"; + reg = <0x01cb4000 0x1000>; + interrupts = <GIC_SPI 84 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&ccu CLK_BUS_CSI>, + <&ccu CLK_CSI1_SCLK>, + <&ccu CLK_DRAM_CSI>; + clock-names = "bus", "mod", "ram"; + resets = <&ccu RST_BUS_CSI>; + + port { + /* Parallel bus endpoint */ + csi1_ep: endpoint { + remote-endpoint = <&adv7611_ep>; + bus-width = <16>; + + /* If hsync-active/vsync-active are missing, + embedded BT.656 sync is used */ + hsync-active = <0>; /* Active low */ + vsync-active = <0>; /* Active low */ + pclk-sample = <1>; /* Rising */ + }; + }; +}; diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt index baf9d9756b3c..f884ada0bffc 100644 --- a/Documentation/devicetree/bindings/media/video-interfaces.txt +++ b/Documentation/devicetree/bindings/media/video-interfaces.txt @@ -100,10 +100,12 @@ Optional endpoint properties slave device (data source) by the master device (data sink). In the master mode the data source device is also the source of the synchronization signals. - bus-type: data bus type. Possible values are: - 0 - autodetect based on other properties (MIPI CSI-2 D-PHY, parallel or Bt656) 1 - MIPI CSI-2 C-PHY 2 - MIPI CSI1 3 - CCP2 + 4 - MIPI CSI-2 D-PHY + 5 - Parallel + 6 - Bt.656 - bus-width: number of data lines actively used, valid for the parallel busses. - data-shift: on the parallel data busses, if bus-width is used to specify the number of data lines, data-shift can be used to specify which data lines are diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt index 615abdd0eb0d..e937ddd871a6 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-common.txt @@ -17,6 +17,7 @@ Required properties: - compatible : must be one of : "mediatek,mt2701-smi-common" "mediatek,mt2712-smi-common" + "mediatek,mt7623-smi-common", "mediatek,mt2701-smi-common" "mediatek,mt8173-smi-common" - reg : the register and size of the SMI block. - power-domains : a phandle to the power domain of this local arbiter. diff --git a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt index 083155cdc2a0..94eddcae77ab 100644 --- a/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt +++ b/Documentation/devicetree/bindings/memory-controllers/mediatek,smi-larb.txt @@ -6,6 +6,7 @@ Required properties: - compatible : must be one of : "mediatek,mt2701-smi-larb" "mediatek,mt2712-smi-larb" + "mediatek,mt7623-smi-larb", "mediatek,mt2701-smi-larb" "mediatek,mt8173-smi-larb" - reg : the register and size of this local arbiter. - mediatek,smi : a phandle to the smi_common node. @@ -16,7 +17,7 @@ Required properties: the register. - "smi" : It's the clock for transfer data and command. -Required property for mt2701 and mt2712: +Required property for mt2701, mt2712 and mt7623: - mediatek,larb-id :the hardware id of this larb. Example: diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-emc.txt b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt index 4c33b29dc660..add95367640b 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra20-emc.txt +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.txt @@ -10,6 +10,8 @@ Properties: and chosen using the ramcode board selector. If omitted, only one set of tables can be present and said tables will be used irrespective of ram-code configuration. +- interrupts : Should contain EMC General interrupt. +- clocks : Should contain EMC clock. Child device nodes describe the memory settings for different configurations and clock rates. @@ -20,6 +22,8 @@ Example: #size-cells = < 0 >; compatible = "nvidia,tegra20-emc"; reg = <0x7000f4000 0x200>; + interrupts = <0 78 0x04>; + clocks = <&tegra_car TEGRA20_CLK_EMC>; } diff --git a/Documentation/devicetree/bindings/memory-controllers/pl353-smc.txt b/Documentation/devicetree/bindings/memory-controllers/pl353-smc.txt new file mode 100644 index 000000000000..d56615fd343a --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/pl353-smc.txt @@ -0,0 +1,47 @@ +Device tree bindings for ARM PL353 static memory controller + +PL353 static memory controller supports two kinds of memory +interfaces.i.e NAND and SRAM/NOR interfaces. +The actual devices are instantiated from the child nodes of pl353 smc node. + +Required properties: +- compatible : Should be "arm,pl353-smc-r2p1", "arm,primecell". +- reg : Controller registers map and length. +- clock-names : List of input clock names - "memclk", "apb_pclk" + (See clock bindings for details). +- clocks : Clock phandles (see clock bindings for details). +- address-cells : Must be 2. +- size-cells : Must be 1. + +Child nodes: + For NAND the "arm,pl353-nand-r2p1" and for NOR the "cfi-flash" drivers are +supported as child nodes. + +for NAND partition information please refer the below file +Documentation/devicetree/bindings/mtd/partition.txt + +Example: + smcc: memory-controller@e000e000 + compatible = "arm,pl353-smc-r2p1", "arm,primecell"; + clock-names = "memclk", "apb_pclk"; + clocks = <&clkc 11>, <&clkc 44>; + reg = <0xe000e000 0x1000>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0x0 0x0 0xe1000000 0x1000000 //Nand CS Region + 0x1 0x0 0xe2000000 0x2000000 //SRAM/NOR CS Region + 0x2 0x0 0xe4000000 0x2000000>; //SRAM/NOR CS Region + nand_0: flash@e1000000 { + compatible = "arm,pl353-nand-r2p1" + reg = <0 0 0x1000000>; + (...) + }; + nor0: flash@e2000000 { + compatible = "cfi-flash"; + reg = <1 0 0x2000000>; + }; + nor1: flash@e4000000 { + compatible = "cfi-flash"; + reg = <2 0 0x2000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/synopsys.txt b/Documentation/devicetree/bindings/memory-controllers/synopsys.txt index a43d26d41e04..9d32762c47e1 100644 --- a/Documentation/devicetree/bindings/memory-controllers/synopsys.txt +++ b/Documentation/devicetree/bindings/memory-controllers/synopsys.txt @@ -1,15 +1,32 @@ Binding for Synopsys IntelliDDR Multi Protocol Memory Controller -This controller has an optional ECC support in half-bus width (16-bit) -configuration. The ECC controller corrects one bit error and detects -two bit errors. +The ZynqMP DDR ECC controller has an optional ECC support in 64-bit and 32-bit +bus width configurations. + +The Zynq DDR ECC controller has an optional ECC support in half-bus width +(16-bit) configuration. + +These both ECC controllers correct single bit ECC errors and detect double bit +ECC errors. Required properties: - - compatible: Should be 'xlnx,zynq-ddrc-a05' - - reg: Base address and size of the controllers memory area + - compatible: One of: + - 'xlnx,zynq-ddrc-a05' : Zynq DDR ECC controller + - 'xlnx,zynqmp-ddrc-2.40a' : ZynqMP DDR ECC controller + - reg: Should contain DDR controller registers location and length. + +Required properties for "xlnx,zynqmp-ddrc-2.40a": + - interrupts: Property with a value describing the interrupt number. Example: memory-controller@f8006000 { compatible = "xlnx,zynq-ddrc-a05"; reg = <0xf8006000 0x1000>; }; + + mc: memory-controller@fd070000 { + compatible = "xlnx,zynqmp-ddrc-2.40a"; + reg = <0x0 0xfd070000 0x0 0x30000>; + interrupt-parent = <&gic>; + interrupts = <0 112 4>; + }; diff --git a/Documentation/devicetree/bindings/mfd/arizona.txt b/Documentation/devicetree/bindings/mfd/arizona.txt index 9b62831fdf3e..148ef621a5e5 100644 --- a/Documentation/devicetree/bindings/mfd/arizona.txt +++ b/Documentation/devicetree/bindings/mfd/arizona.txt @@ -76,7 +76,7 @@ Deprecated properties: Also see child specific device properties: Regulator - ../regulator/arizona-regulator.txt Extcon - ../extcon/extcon-arizona.txt - Sound - ../sound/arizona.txt + Sound - ../sound/wlf,arizona.txt Example: diff --git a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt index 34dd89087cff..86446074e206 100644 --- a/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt +++ b/Documentation/devicetree/bindings/mfd/aspeed-lpc.txt @@ -135,6 +135,8 @@ Required properties: - clocks: contains a phandle to the syscon node describing the clocks. There should then be one cell representing the clock to use +Optional properties: + - memory-region: A phandle to a reserved_memory region to be used for the LPC to AHB mapping diff --git a/Documentation/devicetree/bindings/mfd/axp20x.txt b/Documentation/devicetree/bindings/mfd/axp20x.txt index 188f0373d441..2af4ff95d6bc 100644 --- a/Documentation/devicetree/bindings/mfd/axp20x.txt +++ b/Documentation/devicetree/bindings/mfd/axp20x.txt @@ -32,6 +32,15 @@ Required properties: - interrupt-controller: The PMIC has its own internal IRQs - #interrupt-cells: Should be set to 1 +Supported common regulator properties, see ../regulator/regulator.txt for +more information: +- regulator-ramp-delay: sets the ramp up delay in uV/us + AXP20x/DCDC2: 1600, 800 + AXP20x/LDO3: 1600, 800 +- regulator-soft-start: enable the output at the lowest possible voltage and + only then set the desired voltage + AXP20x/LDO3: software-based implementation + Optional properties: - x-powers,dcdc-freq: defines the work frequency of DC-DC in KHz AXP152/20X: range: 750-1875, Default: 1.5 MHz diff --git a/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt new file mode 100644 index 000000000000..004b0158cf4d --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/cirrus,lochnagar.txt @@ -0,0 +1,68 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +Also see these documents for generic binding information: + [1] GPIO : ../gpio/gpio.txt + +And these for relevant defines: + [2] include/dt-bindings/pinctrl/lochnagar.h + [3] include/dt-bindings/clock/lochnagar.h + +And these documents for the required sub-node binding details: + [4] Clock: ../clock/cirrus,lochnagar.txt + [5] Pinctrl: ../pinctrl/cirrus,lochnagar.txt + [6] Regulator: ../regulator/cirrus,lochnagar.txt + +Required properties: + + - compatible : One of the following strings: + "cirrus,lochnagar1" + "cirrus,lochnagar2" + + - reg : I2C slave address + + - reset-gpios : Reset line to the Lochnagar, see [1]. + +Required sub-nodes: + + - lochnagar-clk : Binding for the clocking components, see [4]. + + - lochnagar-pinctrl : Binding for the pin control components, see [5]. + +Optional sub-nodes: + + - Bindings for the regulator components, see [6]. Only available on + Lochnagar 2. + +Optional properties: + + - present-gpios : Host present line, indicating the presence of a + host system, see [1]. This can be omitted if the present line is + tied in hardware. + +Example: + +lochnagar: lochnagar@22 { + compatible = "cirrus,lochnagar2"; + reg = <0x22>; + + reset-gpios = <&gpio0 55 0>; + present-gpios = <&gpio0 60 0>; + + lochnagar-clk { + compatible = "cirrus,lochnagar2-clk"; + ... + }; + + lochnagar-pinctrl { + compatible = "cirrus,lochnagar-pinctrl"; + ... + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt b/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt index a4b056761eaa..d5f68ac78d15 100644 --- a/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt +++ b/Documentation/devicetree/bindings/mfd/rohm,bd71837-pmic.txt @@ -23,6 +23,20 @@ Required properties: Optional properties: - clock-output-names : Should contain name for output clock. +- rohm,reset-snvs-powered : Transfer BD718x7 to SNVS state at reset. + +The BD718x7 supports two different HW states as reset target states. States +are called as SNVS and READY. At READY state all the PMIC power outputs go +down and OTP is reload. At the SNVS state all other logic and external +devices apart from the SNVS power domain are shut off. Please refer to NXP +i.MX8 documentation for further information regarding SNVS state. When a +reset is done via SNVS state the PMIC OTP data is not reload. This causes +power outputs that have been under SW control to stay down when reset has +switched power state to SNVS. If reset is done via READY state the power +outputs will be returned to HW control by OTP loading. Thus the reset +target state is set to READY by default. If SNVS state is used the boot +crucial regulators must have the regulator-always-on and regulator-boot-on +properties set in regulator node. Example: @@ -43,6 +57,7 @@ Example: #clock-cells = <0>; clocks = <&osc 0>; clock-output-names = "bd71837-32k-out"; + rohm,reset-snvs-powered; regulators { buck1: BUCK1 { @@ -50,8 +65,10 @@ Example: regulator-min-microvolt = <700000>; regulator-max-microvolt = <1300000>; regulator-boot-on; + regulator-always-on; regulator-ramp-delay = <1250>; }; + // [...] }; }; diff --git a/Documentation/devicetree/bindings/mfd/st,stpmic1.txt b/Documentation/devicetree/bindings/mfd/st,stpmic1.txt new file mode 100644 index 000000000000..afd45c089585 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/st,stpmic1.txt @@ -0,0 +1,61 @@ +* STMicroelectronics STPMIC1 Power Management IC + +Required properties: +- compatible: : "st,stpmic1" +- reg: : The I2C slave address for the STPMIC1 chip. +- interrupts: : The interrupt line the device is connected to. +- #interrupt-cells: : Should be 1. +- interrupt-controller: : Marks the device node as an interrupt controller. + Interrupt numbers are defined at + dt-bindings/mfd/st,stpmic1.h. + +STPMIC1 consists in a varied group of sub-devices. +Each sub-device binding is be described in own documentation file. + +Device Description +------ ------------ +st,stpmic1-onkey : Power on key, see ../input/st,stpmic1-onkey.txt +st,stpmic1-regulators : Regulators, see ../regulator/st,stpmic1-regulator.txt +st,stpmic1-wdt : Watchdog, see ../watchdog/st,stpmic1-wdt.txt + +Example: + +#include <dt-bindings/mfd/st,stpmic1.h> + +pmic: pmic@33 { + compatible = "st,stpmic1"; + reg = <0x33>; + interrupt-parent = <&gpioa>; + interrupts = <0 2>; + + interrupt-controller; + #interrupt-cells = <2>; + + onkey { + compatible = "st,stpmic1-onkey"; + interrupts = <IT_PONKEY_F 0>,<IT_PONKEY_R 1>; + interrupt-names = "onkey-falling", "onkey-rising"; + power-off-time-sec = <10>; + }; + + watchdog { + compatible = "st,stpmic1-wdt"; + }; + + regulators { + compatible = "st,stpmic1-regulators"; + + vdd_core: buck1 { + regulator-name = "vdd_core"; + regulator-boot-on; + regulator-min-microvolt = <700000>; + regulator-max-microvolt = <1200000>; + }; + vdd: buck3 { + regulator-name = "vdd"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-pull-down; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/stmpe.txt b/Documentation/devicetree/bindings/mfd/stmpe.txt index c797c05cd3c2..d4408a417193 100644 --- a/Documentation/devicetree/bindings/mfd/stmpe.txt +++ b/Documentation/devicetree/bindings/mfd/stmpe.txt @@ -4,15 +4,29 @@ STMPE is an MFD device which may expose the following inbuilt devices: gpio, keypad, touchscreen, adc, pwm, rotator. Required properties: - - compatible : "st,stmpe[610|801|811|1600|1601|2401|2403]" - - reg : I2C/SPI address of the device + - compatible : "st,stmpe[610|801|811|1600|1601|2401|2403]" + - reg : I2C/SPI address of the device Optional properties: - - interrupts : The interrupt outputs from the controller - - interrupt-controller : Marks the device node as an interrupt controller - - wakeup-source : Marks the input device as wakable - - st,autosleep-timeout : Valid entries (ms); 4, 16, 32, 64, 128, 256, 512 and 1024 - - irq-gpio : If present, which GPIO to use for event IRQ + - interrupts : The interrupt outputs from the controller + - interrupt-controller : Marks the device node as an interrupt controller + - wakeup-source : Marks the input device as wakable + - st,autosleep-timeout : Valid entries (ms); 4, 16, 32, 64, 128, 256, 512 and 1024 + - irq-gpio : If present, which GPIO to use for event IRQ + +Optional properties for devices with touch and ADC (STMPE811|STMPE610): + - st,sample-time : ADC conversion time in number of clock. + 0 -> 36 clocks 4 -> 80 clocks (recommended) + 1 -> 44 clocks 5 -> 96 clocks + 2 -> 56 clocks 6 -> 124 clocks + 3 -> 64 clocks + - st,mod-12b : ADC Bit mode + 0 -> 10bit ADC 1 -> 12bit ADC + - st,ref-sel : ADC reference source + 0 -> internal 1 -> external + - st,adc-freq : ADC Clock speed + 0 -> 1.625 MHz 2 || 3 -> 6.5 MHz + 1 -> 3.25 MHz Example: diff --git a/Documentation/devicetree/bindings/mips/lantiq/rcu-gphy.txt b/Documentation/devicetree/bindings/mips/lantiq/rcu-gphy.txt deleted file mode 100644 index a0c19bd1ce66..000000000000 --- a/Documentation/devicetree/bindings/mips/lantiq/rcu-gphy.txt +++ /dev/null @@ -1,36 +0,0 @@ -Lantiq XWAY SoC GPHY binding -============================ - -This binding describes a software-defined ethernet PHY, provided by the RCU -module on newer Lantiq XWAY SoCs (xRX200 and newer). - -------------------------------------------------------------------------------- -Required properties: -- compatible : Should be one of - "lantiq,xrx200a1x-gphy" - "lantiq,xrx200a2x-gphy" - "lantiq,xrx300-gphy" - "lantiq,xrx330-gphy" -- reg : Addrress of the GPHY FW load address register -- resets : Must reference the RCU GPHY reset bit -- reset-names : One entry, value must be "gphy" or optional "gphy2" -- clocks : A reference to the (PMU) GPHY clock gate - -Optional properties: -- lantiq,gphy-mode : GPHY_MODE_GE (default) or GPHY_MODE_FE as defined in - <dt-bindings/mips/lantiq_xway_gphy.h> - - -------------------------------------------------------------------------------- -Example for the GPHys on the xRX200 SoCs: - -#include <dt-bindings/mips/lantiq_rcu_gphy.h> - gphy0: gphy@20 { - compatible = "lantiq,xrx200a2x-gphy"; - reg = <0x20 0x4>; - - resets = <&reset0 31 30>, <&reset1 7 7>; - reset-names = "gphy", "gphy2"; - clocks = <&pmu0 XRX200_PMU_GATE_GPHY>; - lantiq,gphy-mode = <GPHY_MODE_GE>; - }; diff --git a/Documentation/devicetree/bindings/mips/lantiq/rcu.txt b/Documentation/devicetree/bindings/mips/lantiq/rcu.txt index 7f0822b4beae..58d51f480c9e 100644 --- a/Documentation/devicetree/bindings/mips/lantiq/rcu.txt +++ b/Documentation/devicetree/bindings/mips/lantiq/rcu.txt @@ -26,24 +26,6 @@ Example of the RCU bindings on a xRX200 SoC: ranges = <0x0 0x203000 0x100>; big-endian; - gphy0: gphy@20 { - compatible = "lantiq,xrx200a2x-gphy"; - reg = <0x20 0x4>; - - resets = <&reset0 31 30>, <&reset1 7 7>; - reset-names = "gphy", "gphy2"; - lantiq,gphy-mode = <GPHY_MODE_GE>; - }; - - gphy1: gphy@68 { - compatible = "lantiq,xrx200a2x-gphy"; - reg = <0x68 0x4>; - - resets = <&reset0 29 28>, <&reset1 6 6>; - reset-names = "gphy", "gphy2"; - lantiq,gphy-mode = <GPHY_MODE_GE>; - }; - reset0: reset-controller@10 { compatible = "lantiq,xrx200-reset"; reg = <0x10 4>, <0x14 4>; diff --git a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt index 6611a7c2053a..bb7e896cb644 100644 --- a/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt +++ b/Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt @@ -9,6 +9,25 @@ blocks that can be used to create functional hardware objects/devices such as network interfaces, crypto accelerator instances, L2 switches, etc. +For an overview of the DPAA2 architecture and fsl-mc bus see: +Documentation/networking/device_drivers/freescale/dpaa2/overview.rst + +As described in the above overview, all DPAA2 objects in a DPRC share the +same hardware "isolation context" and a 10-bit value called an ICID +(isolation context id) is expressed by the hardware to identify +the requester. + +The generic 'iommus' property is insufficient to describe the relationship +between ICIDs and IOMMUs, so an iommu-map property is used to define +the set of possible ICIDs under a root DPRC and how they map to +an IOMMU. + +For generic IOMMU bindings, see +Documentation/devicetree/bindings/iommu/iommu.txt. + +For arm-smmu binding, see: +Documentation/devicetree/bindings/iommu/arm,smmu.txt. + Required properties: - compatible @@ -88,14 +107,34 @@ Sub-nodes: Value type: <phandle> Definition: Specifies the phandle to the PHY device node associated with the this dpmac. +Optional properties: + +- iommu-map: Maps an ICID to an IOMMU and associated iommu-specifier + data. + + The property is an arbitrary number of tuples of + (icid-base,iommu,iommu-base,length). + + Any ICID i in the interval [icid-base, icid-base + length) is + associated with the listed IOMMU, with the iommu-specifier + (i - icid-base + iommu-base). Example: + smmu: iommu@5000000 { + compatible = "arm,mmu-500"; + #iommu-cells = <1>; + stream-match-mask = <0x7C00>; + ... + }; + fsl_mc: fsl-mc@80c000000 { compatible = "fsl,qoriq-mc"; reg = <0x00000008 0x0c000000 0 0x40>, /* MC portal base */ <0x00000000 0x08340000 0 0x40000>; /* MC control reg */ msi-parent = <&its>; + /* define map for ICIDs 23-64 */ + iommu-map = <23 &smmu 23 41>; #address-cells = <3>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/misc/lwn-bk4.txt b/Documentation/devicetree/bindings/misc/lwn-bk4.txt new file mode 100644 index 000000000000..d6a8c188c087 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/lwn-bk4.txt @@ -0,0 +1,26 @@ +* Liebherr's BK4 controller external SPI + +A device which handles data acquisition from compatible industrial +peripherals. +The SPI is used for data and management purposes in both master and +slave modes. + +Required properties: + +- compatible : Should be "lwn,bk4" + +Required SPI properties: + +- reg : Should be address of the device chip select within + the controller. + +- spi-max-frequency : Maximum SPI clocking speed of device in Hz, should be + 30MHz at most for the Liebherr's BK4 external bus. + +Example: + +spidev0: spi@0 { + compatible = "lwn,bk4"; + spi-max-frequency = <30000000>; + reg = <0>; +}; diff --git a/Documentation/devicetree/bindings/misc/pvpanic-mmio.txt b/Documentation/devicetree/bindings/misc/pvpanic-mmio.txt new file mode 100644 index 000000000000..985e90736780 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/pvpanic-mmio.txt @@ -0,0 +1,29 @@ +* QEMU PVPANIC MMIO Configuration bindings + +QEMU's emulation / virtualization targets provide the following PVPANIC +MMIO Configuration interface on the "virt" machine. +type: + +- a read-write, 16-bit wide data register. + +QEMU exposes the data register to guests as memory mapped registers. + +Required properties: + +- compatible: "qemu,pvpanic-mmio". +- reg: the MMIO region used by the device. + * Bytes 0x0 Write panic event to the reg when guest OS panics. + * Bytes 0x1 Reserved. + +Example: + +/ { + #size-cells = <0x2>; + #address-cells = <0x2>; + + pvpanic-mmio@9060000 { + compatible = "qemu,pvpanic-mmio"; + reg = <0x0 0x9060000 0x0 0x2>; + }; +}; + diff --git a/Documentation/devicetree/bindings/misc/qcom,fastrpc.txt b/Documentation/devicetree/bindings/misc/qcom,fastrpc.txt new file mode 100644 index 000000000000..2a1827ab50d2 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/qcom,fastrpc.txt @@ -0,0 +1,78 @@ +Qualcomm Technologies, Inc. FastRPC Driver + +The FastRPC implements an IPC (Inter-Processor Communication) +mechanism that allows for clients to transparently make remote method +invocations across DSP and APPS boundaries. This enables developers +to offload tasks to the DSP and free up the application processor for +other tasks. + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,fastrpc" + +- label + Usage: required + Value type: <string> + Definition: should specify the dsp domain name this fastrpc + corresponds to. must be one of this: "adsp", "mdsp", "sdsp", "cdsp" + +- #address-cells + Usage: required + Value type: <u32> + Definition: Must be 1 + +- #size-cells + Usage: required + Value type: <u32> + Definition: Must be 0 + += COMPUTE BANKS +Each subnode of the Fastrpc represents compute context banks available +on the dsp. +- All Compute context banks MUST contain the following properties: + +- compatible: + Usage: required + Value type: <stringlist> + Definition: must be "qcom,fastrpc-compute-cb" + +- reg + Usage: required + Value type: <u32> + Definition: Context Bank ID. + +- qcom,nsessions: + Usage: Optional + Value type: <u32> + Defination: A value indicating how many sessions can share this + context bank. Defaults to 1 when this property + is not specified. + +Example: + +adsp-pil { + compatible = "qcom,msm8996-adsp-pil"; + ... + smd-edge { + label = "lpass"; + fastrpc { + compatible = "qcom,fastrpc"; + qcom,smd-channels = "fastrpcsmd-apps-dsp"; + label = "adsp"; + #address-cells = <1>; + #size-cells = <0>; + + cb@1 { + compatible = "qcom,fastrpc-compute-cb"; + reg = <1>; + }; + + cb@2 { + compatible = "qcom,fastrpc-compute-cb"; + reg = <2>; + }; + ... + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt index e2effe17f05e..1edbb049cccb 100644 --- a/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/arasan,sdhci.txt @@ -16,6 +16,10 @@ Required Properties: - "rockchip,rk3399-sdhci-5.1", "arasan,sdhci-5.1": rk3399 eMMC PHY For this device it is strongly suggested to include arasan,soc-ctl-syscon. - "ti,am654-sdhci-5.1", "arasan,sdhci-5.1": TI AM654 MMC PHY + Note: This binding has been deprecated and moved to [5]. + + [5] Documentation/devicetree/bindings/mmc/sdhci-am654.txt + - reg: From mmc bindings: Register location and length. - clocks: From clock bindings: Handles to clock inputs. - clock-names: From clock bindings: Tuple including "clk_xin" and "clk_ahb" diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt index 3e29050ec769..540c65ed9cba 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.txt @@ -15,7 +15,9 @@ Required properties: "fsl,imx6q-usdhc" "fsl,imx6sl-usdhc" "fsl,imx6sx-usdhc" + "fsl,imx6ull-usdhc" "fsl,imx7d-usdhc" + "fsl,imx8qxp-usdhc" Optional properties: - fsl,wp-controller : Indicate to use controller internal write protection diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index f5a0923b34ca..cdbcfd3a4ff2 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -62,6 +62,8 @@ Optional properties: be referred to mmc-pwrseq-simple.txt. But now it's reused as a tunable delay waiting for I/O signalling and card power supply to be stable, regardless of whether pwrseq-simple is used. Default to 10ms if no available. +- supports-cqe : The presence of this property indicates that the corresponding + MMC host controller supports HW command queue feature. *NOTE* on CD and WP polarity. To use common for all SD/MMC host controllers line polarity properties, we have to fix the meaning of the "normal" and "inverted" diff --git a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt index 32b4b4e41923..2cecdc71d94c 100644 --- a/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt +++ b/Documentation/devicetree/bindings/mmc/nvidia,tegra20-sdhci.txt @@ -39,12 +39,16 @@ sdhci@c8000200 { bus-width = <8>; }; -Optional properties for Tegra210 and Tegra186: +Optional properties for Tegra210, Tegra186 and Tegra194: - pinctrl-names, pinctrl-0, pinctrl-1 : Specify pad voltage configurations. Valid pinctrl-names are "sdmmc-3v3" and "sdmmc-1v8" for controllers supporting multiple voltage levels. The order of names should correspond to the pin configuration states in pinctrl-0 and pinctrl-1. +- pinctrl-names : "sdmmc-3v3-drv" and "sdmmc-1v8-drv" are applicable for + Tegra210 where pad config registers are in the pinmux register domain + for pull-up-strength and pull-down-strength values configuration when + using pads at 3V3 and 1V8 levels. - nvidia,only-1-8-v : The presence of this property indicates that the controller operates at a 1.8 V fixed I/O voltage. - nvidia,pad-autocal-pull-up-offset-3v3, diff --git a/Documentation/devicetree/bindings/mmc/sdhci-am654.txt b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt new file mode 100644 index 000000000000..15dbbbace27e --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sdhci-am654.txt @@ -0,0 +1,36 @@ +Device Tree Bindings for the SDHCI Controllers present on TI's AM654 SOCs + +The bindings follow the mmc[1], clock[2] and interrupt[3] bindings. +Only deviations are documented here. + + [1] Documentation/devicetree/bindings/mmc/mmc.txt + [2] Documentation/devicetree/bindings/clock/clock-bindings.txt + [3] Documentation/devicetree/bindings/interrupt-controller/interrupts.txt + +Required Properties: + - compatible: should be "ti,am654-sdhci-5.1" + - reg: Must be two entries. + - The first should be the sdhci register space + - The second should the subsystem/phy register space + - clocks: Handles to the clock inputs. + - clock-names: Tuple including "clk_xin" and "clk_ahb" + - interrupts: Interrupt specifiers + - ti,otap-del-sel: Output Tap Delay select + - ti,trm-icp: DLL trim select + - ti,driver-strength-ohm: driver strength in ohms. + Valid values are 33, 40, 50, 66 and 100 ohms. + +Example: + + sdhci0: sdhci@4f80000 { + compatible = "ti,am654-sdhci-5.1"; + reg = <0x0 0x4f80000 0x0 0x260>, <0x0 0x4f90000 0x0 0x134>; + power-domains = <&k3_pds 47>; + clocks = <&k3_clks 47 0>, <&k3_clks 47 1>; + clock-names = "clk_ahb", "clk_xin"; + interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH>; + sdhci-caps-mask = <0x80000007 0x0>; + mmc-ddr-1_8v; + ti,otap-del-sel = <0x2>; + ti,trm-icp = <0x8>; + }; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt index 502b3b851ebb..da4edb146a98 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-msm.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-msm.txt @@ -4,15 +4,28 @@ This file documents differences between the core properties in mmc.txt and the properties used by the sdhci-msm driver. Required properties: -- compatible: Should contain: +- compatible: Should contain a SoC-specific string and a IP version string: + version strings: "qcom,sdhci-msm-v4" for sdcc versions less than 5.0 - "qcom,sdhci-msm-v5" for sdcc versions >= 5.0 + "qcom,sdhci-msm-v5" for sdcc version 5.0 For SDCC version 5.0.0, MCI registers are removed from SDCC interface and some registers are moved to HC. New compatible string is added to support this change - "qcom,sdhci-msm-v5". + full compatible strings with SoC and version: + "qcom,apq8084-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8916-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8992-sdhci", "qcom,sdhci-msm-v4" + "qcom,msm8996-sdhci", "qcom,sdhci-msm-v4" + "qcom,sdm845-sdhci", "qcom,sdhci-msm-v5" + "qcom,qcs404-sdhci", "qcom,sdhci-msm-v5" + NOTE that some old device tree files may be floating around that only + have the string "qcom,sdhci-msm-v4" without the SoC compatible string + but doing that should be considered a deprecated practice. + - reg: Base address and length of the register in the following order: - Host controller register map (required) - - SD Core register map (required) + - SD Core register map (required for msm-v4 and below) - interrupts: Should contain an interrupt-specifiers for the interrupts: - Host controller interrupt (required) - pinctrl-names: Should contain only one value - "default". @@ -29,7 +42,7 @@ Required properties: Example: sdhc_1: sdhci@f9824900 { - compatible = "qcom,sdhci-msm-v4"; + compatible = "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4"; reg = <0xf9824900 0x11c>, <0xf9824000 0x800>; interrupts = <0 123 0>; bus-width = <8>; @@ -46,7 +59,7 @@ Example: }; sdhc_2: sdhci@f98a4900 { - compatible = "qcom,sdhci-msm-v4"; + compatible = "qcom,msm8974-sdhci", "qcom,sdhci-msm-v4"; reg = <0xf98a4900 0x11c>, <0xf98a4000 0x800>; interrupts = <0 125 0>; bus-width = <4>; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt index 393848c2138e..72c4dec7e1db 100644 --- a/Documentation/devicetree/bindings/mmc/sdhci-omap.txt +++ b/Documentation/devicetree/bindings/mmc/sdhci-omap.txt @@ -2,6 +2,8 @@ Refer to mmc.txt for standard MMC bindings. +For UHS devices which require tuning, the device tree should have a "cpu_thermal" node which maps to the appropriate thermal zone. This is used to get the temperature of the zone during tuning. + Required properties: - compatible: Should be "ti,dra7-sdhci" for DRA7 and DRA72 controllers Should be "ti,k2g-sdhci" for K2G diff --git a/Documentation/devicetree/bindings/mmc/ti-omap.txt b/Documentation/devicetree/bindings/mmc/ti-omap.txt index 8de579969763..02fd31cf361d 100644 --- a/Documentation/devicetree/bindings/mmc/ti-omap.txt +++ b/Documentation/devicetree/bindings/mmc/ti-omap.txt @@ -24,31 +24,3 @@ Examples: dmas = <&sdma 61 &sdma 62>; dma-names = "tx", "rx"; }; - -* TI MMC host controller for OMAP1 and 2420 - -The MMC Host Controller on TI OMAP1 and 2420 family provides -an interface for MMC, SD, and SDIO types of memory cards. - -This file documents differences between the core properties described -by mmc.txt and the properties used by the omap mmc driver. - -Note that this driver will not work with omap2430 or later omaps, -please see the omap hsmmc driver for the current omaps. - -Required properties: -- compatible: Must be "ti,omap2420-mmc", for OMAP2420 controllers -- ti,hwmods: For 2420, must be "msdi<n>", where n is controller - instance starting 1 - -Examples: - - msdi1: mmc@4809c000 { - compatible = "ti,omap2420-mmc"; - ti,hwmods = "msdi1"; - reg = <0x4809c000 0x80>; - interrupts = <83>; - dmas = <&sdma 61 &sdma 62>; - dma-names = "tx", "rx"; - }; - diff --git a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt index 27f2eab2981d..2b4f17ca9087 100644 --- a/Documentation/devicetree/bindings/mmc/tmio_mmc.txt +++ b/Documentation/devicetree/bindings/mmc/tmio_mmc.txt @@ -13,12 +13,14 @@ Required properties: - compatible: should contain one or more of the following: "renesas,sdhi-sh73a0" - SDHI IP on SH73A0 SoC "renesas,sdhi-r7s72100" - SDHI IP on R7S72100 SoC + "renesas,sdhi-r7s9210" - SDHI IP on R7S9210 SoC "renesas,sdhi-r8a73a4" - SDHI IP on R8A73A4 SoC "renesas,sdhi-r8a7740" - SDHI IP on R8A7740 SoC "renesas,sdhi-r8a7743" - SDHI IP on R8A7743 SoC "renesas,sdhi-r8a7744" - SDHI IP on R8A7744 SoC "renesas,sdhi-r8a7745" - SDHI IP on R8A7745 SoC "renesas,sdhi-r8a774a1" - SDHI IP on R8A774A1 SoC + "renesas,sdhi-r8a774c0" - SDHI IP on R8A774C0 SoC "renesas,sdhi-r8a77470" - SDHI IP on R8A77470 SoC "renesas,sdhi-mmc-r8a77470" - SDHI/MMC IP on R8A77470 SoC "renesas,sdhi-r8a7778" - SDHI IP on R8A7778 SoC @@ -56,7 +58,7 @@ Required properties: "core" and "cd". If the controller only has 1 clock, naming is not required. Devices which have more than 1 clock are listed below: - 2: R7S72100 + 2: R7S72100, R7S9210 Optional properties: - pinctrl-names: should be "default", "state_uhs" diff --git a/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.txt b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.txt new file mode 100644 index 000000000000..3983c11e062c --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/amlogic,meson-nand.txt @@ -0,0 +1,60 @@ +Amlogic NAND Flash Controller (NFC) for GXBB/GXL/AXG family SoCs + +This file documents the properties in addition to those available in +the MTD NAND bindings. + +Required properties: +- compatible : contains one of: + - "amlogic,meson-gxl-nfc" + - "amlogic,meson-axg-nfc" +- clocks : + A list of phandle + clock-specifier pairs for the clocks listed + in clock-names. + +- clock-names: Should contain the following: + "core" - NFC module gate clock + "device" - device clock from eMMC sub clock controller + "rx" - rx clock phase + "tx" - tx clock phase + +- amlogic,mmc-syscon : Required for NAND clocks, it's shared with SD/eMMC + controller port C + +Optional children nodes: +Children nodes represent the available nand chips. + +Other properties: +see Documentation/devicetree/bindings/mtd/nand.txt for generic bindings. + +Example demonstrate on AXG SoC: + + sd_emmc_c_clkc: mmc@7000 { + compatible = "amlogic,meson-axg-mmc-clkc", "syscon"; + reg = <0x0 0x7000 0x0 0x800>; + }; + + nand-controller@7800 { + compatible = "amlogic,meson-axg-nfc"; + reg = <0x0 0x7800 0x0 0x100>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <GIC_SPI 34 IRQ_TYPE_EDGE_RISING>; + + clocks = <&clkc CLKID_SD_EMMC_C>, + <&sd_emmc_c_clkc CLKID_MMC_DIV>, + <&sd_emmc_c_clkc CLKID_MMC_PHASE_RX>, + <&sd_emmc_c_clkc CLKID_MMC_PHASE_TX>; + clock-names = "core", "device", "rx", "tx"; + amlogic,mmc-syscon = <&sd_emmc_c_clkc>; + + pinctrl-names = "default"; + pinctrl-0 = <&nand_pins>; + + nand@0 { + reg = <0>; + #address-cells = <1>; + #size-cells = <1>; + + nand-on-flash-bbt; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt b/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt index bb2075df9b38..4345c3a6f530 100644 --- a/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/cadence-quadspi.txt @@ -4,6 +4,7 @@ Required properties: - compatible : should be one of the following: Generic default - "cdns,qspi-nor". For TI 66AK2G SoC - "ti,k2g-qspi", "cdns,qspi-nor". + For TI AM654 SoC - "ti,am654-ospi", "cdns,qspi-nor". - reg : Contains two entries, each of which is a tuple consisting of a physical address and length. The first entry is the address and length of the controller register set. The second entry is the diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index 232fa12e90ef..7df0dcaccb7d 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt @@ -29,6 +29,8 @@ file systems on embedded devices. - use-advanced-sector-protection: boolean to enable support for the advanced sector protection (Spansion: PPB - Persistent Protection Bits) locking. + - addr-gpios : (optional) List of GPIO descriptors that will be used to + address the MSBs address lines. The order goes from LSB to MSB. For JEDEC compatible devices, the following additional properties are defined: diff --git a/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt b/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt index 56d3668e2c50..a12e3b5c495d 100644 --- a/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt +++ b/Documentation/devicetree/bindings/mtd/mtk-quadspi.txt @@ -1,4 +1,4 @@ -* Serial NOR flash controller for MTK MT81xx (and similar) +* Serial NOR flash controller for MediaTek SoCs Required properties: - compatible: For mt8173, compatible should be "mediatek,mt8173-nor", @@ -10,6 +10,7 @@ Required properties: "mediatek,mt2712-nor", "mediatek,mt8173-nor" "mediatek,mt7622-nor", "mediatek,mt8173-nor" "mediatek,mt7623-nor", "mediatek,mt8173-nor" + "mediatek,mt7629-nor", "mediatek,mt8173-nor" "mediatek,mt8173-nor" - reg: physical base address and length of the controller's register - clocks: the phandle of the clocks needed by the nor controller diff --git a/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt new file mode 100644 index 000000000000..fd0ebe4e3415 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/partitions/redboot-fis.txt @@ -0,0 +1,27 @@ +RedBoot FLASH Image System (FIS) Partitions +=========================================== + +The FLASH Image System (FIS) directory is a flash description +format closely associated with the RedBoot boot loader. + +It uses one single flash eraseblock in the flash to store an index of +all images in the flash. + +This block size will vary depending on flash but is typically +32 KB in size. + +Required properties: +- compatible : (required) must be "redboot-fis" +- fis-index-block : (required) a index to the eraseblock containing + the FIS directory on this device. On a flash memory with 32KB + eraseblocks, 0 means the first eraseblock at 0x00000000, 1 means the + second eraseblock at 0x00008000 and so on. + +Example: + +flash@0 { + partitions { + compatible = "redboot-fis"; + fis-index-block = <0>; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/stm32-fmc2-nand.txt b/Documentation/devicetree/bindings/mtd/stm32-fmc2-nand.txt new file mode 100644 index 000000000000..ad2bef826582 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/stm32-fmc2-nand.txt @@ -0,0 +1,61 @@ +STMicroelectronics Flexible Memory Controller 2 (FMC2) +NAND Interface + +Required properties: +- compatible: Should be one of: + * st,stm32mp15-fmc2 +- reg: NAND flash controller memory areas. + First region contains the register location. + Regions 2 to 4 respectively contain the data, command, + and address space for CS0. + Regions 5 to 7 contain the same areas for CS1. +- interrupts: The interrupt number +- pinctrl-0: Standard Pinctrl phandle (see: pinctrl/pinctrl-bindings.txt) +- clocks: The clock needed by the NAND flash controller + +Optional properties: +- resets: Reference to a reset controller asserting the FMC controller +- dmas: DMA specifiers (see: dma/stm32-mdma.txt) +- dma-names: Must be "tx", "rx" and "ecc" + +* NAND device bindings: + +Required properties: +- reg: describes the CS lines assigned to the NAND device. + +Optional properties: +- nand-on-flash-bbt: see nand.txt +- nand-ecc-strength: see nand.txt +- nand-ecc-step-size: see nand.txt + +The following ECC strength and step size are currently supported: + - nand-ecc-strength = <1>, nand-ecc-step-size = <512> (Hamming) + - nand-ecc-strength = <4>, nand-ecc-step-size = <512> (BCH4) + - nand-ecc-strength = <8>, nand-ecc-step-size = <512> (BCH8) (default) + +Example: + + fmc: nand-controller@58002000 { + compatible = "st,stm32mp15-fmc2"; + reg = <0x58002000 0x1000>, + <0x80000000 0x1000>, + <0x88010000 0x1000>, + <0x88020000 0x1000>, + <0x81000000 0x1000>, + <0x89010000 0x1000>, + <0x89020000 0x1000>; + interrupts = <GIC_SPI 48 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&rcc FMC_K>; + resets = <&rcc FMC_R>; + pinctrl-names = "default"; + pinctrl-0 = <&fmc_pins_a>; + #address-cells = <1>; + #size-cells = <0>; + + nand@0 { + reg = <0>; + nand-on-flash-bbt; + #address-cells = <1>; + #size-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt index 4194ff7e6ee6..c26f4e11037c 100644 --- a/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/broadcom-bluetooth.txt @@ -10,6 +10,8 @@ device the slave device is attached to. Required properties: - compatible: should contain one of the following: + * "brcm,bcm20702a1" + * "brcm,bcm4330-bt" * "brcm,bcm43438-bt" Optional properties: @@ -18,8 +20,13 @@ Optional properties: - shutdown-gpios: GPIO specifier, used to enable the BT module - device-wakeup-gpios: GPIO specifier, used to wakeup the controller - host-wakeup-gpios: GPIO specifier, used to wakeup the host processor - - clocks: clock specifier if external clock provided to the controller - - clock-names: should be "extclk" + - clocks: 1 or 2 clocks as defined in clock-names below, in that order + - clock-names: names for clock inputs, matching the clocks given + - "extclk": deprecated, replaced by "txco" + - "txco": external reference clock (not a standalone crystal) + - "lpo": external low power 32.768 kHz clock + - vbat-supply: phandle to regulator supply for VBAT + - vddio-supply: phandle to regulator supply for VDDIO Example: diff --git a/Documentation/devicetree/bindings/net/btusb.txt b/Documentation/devicetree/bindings/net/btusb.txt index 37d67926dd6d..b1ad6ee68e90 100644 --- a/Documentation/devicetree/bindings/net/btusb.txt +++ b/Documentation/devicetree/bindings/net/btusb.txt @@ -9,6 +9,9 @@ Required properties: (more may be added later) are: "usb1286,204e" (Marvell 8997) + "usbcf3,e300" (Qualcomm QCA6174A) + "usb4ca,301a" (Qualcomm QCA6174A (Lite-On)) + Also, vendors that use btusb may have device additional properties, e.g: Documentation/devicetree/bindings/net/marvell-bt-8xxx.txt diff --git a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt index bfc0c433654f..bc77477c6878 100644 --- a/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt +++ b/Documentation/devicetree/bindings/net/can/fsl-flexcan.txt @@ -24,6 +24,14 @@ Optional properties: if this property is present then controller is assumed to be big endian. +- fsl,stop-mode: register bits of stop mode control, the format is + <&gpr req_gpr req_bit ack_gpr ack_bit>. + gpr is the phandle to general purpose register node. + req_gpr is the gpr register offset of CAN stop request. + req_bit is the bit offset of CAN stop request. + ack_gpr is the gpr register offset of CAN stop acknowledge. + ack_bit is the bit offset of CAN stop acknowledge. + Example: can@1c000 { diff --git a/Documentation/devicetree/bindings/net/can/holt_hi311x.txt b/Documentation/devicetree/bindings/net/can/holt_hi311x.txt index 903a78da65be..3a9926f99937 100644 --- a/Documentation/devicetree/bindings/net/can/holt_hi311x.txt +++ b/Documentation/devicetree/bindings/net/can/holt_hi311x.txt @@ -17,7 +17,7 @@ Example: reg = <1>; clocks = <&clk32m>; interrupt-parent = <&gpio4>; - interrupts = <13 IRQ_TYPE_EDGE_RISING>; + interrupts = <13 IRQ_TYPE_LEVEL_HIGH>; vdd-supply = <®5v0>; xceiver-supply = <®5v0>; }; diff --git a/Documentation/devicetree/bindings/net/can/rcar_can.txt b/Documentation/devicetree/bindings/net/can/rcar_can.txt index 94a7f33ac5e9..9936b9ee67c3 100644 --- a/Documentation/devicetree/bindings/net/can/rcar_can.txt +++ b/Documentation/devicetree/bindings/net/can/rcar_can.txt @@ -3,7 +3,9 @@ Renesas R-Car CAN controller Device Tree Bindings Required properties: - compatible: "renesas,can-r8a7743" if CAN controller is a part of R8A7743 SoC. + "renesas,can-r8a7744" if CAN controller is a part of R8A7744 SoC. "renesas,can-r8a7745" if CAN controller is a part of R8A7745 SoC. + "renesas,can-r8a774a1" if CAN controller is a part of R8A774A1 SoC. "renesas,can-r8a7778" if CAN controller is a part of R8A7778 SoC. "renesas,can-r8a7779" if CAN controller is a part of R8A7779 SoC. "renesas,can-r8a7790" if CAN controller is a part of R8A7790 SoC. @@ -13,26 +15,32 @@ Required properties: "renesas,can-r8a7794" if CAN controller is a part of R8A7794 SoC. "renesas,can-r8a7795" if CAN controller is a part of R8A7795 SoC. "renesas,can-r8a7796" if CAN controller is a part of R8A7796 SoC. + "renesas,can-r8a77965" if CAN controller is a part of R8A77965 SoC. "renesas,rcar-gen1-can" for a generic R-Car Gen1 compatible device. "renesas,rcar-gen2-can" for a generic R-Car Gen2 or RZ/G1 compatible device. - "renesas,rcar-gen3-can" for a generic R-Car Gen3 compatible device. + "renesas,rcar-gen3-can" for a generic R-Car Gen3 or RZ/G2 + compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first followed by the generic version. - reg: physical base address and size of the R-Car CAN register map. - interrupts: interrupt specifier for the sole interrupt. -- clocks: phandles and clock specifiers for 3 CAN clock inputs. -- clock-names: 3 clock input name strings: "clkp1", "clkp2", "can_clk". +- clocks: phandles and clock specifiers for 2 CAN clock inputs for RZ/G2 + devices. + phandles and clock specifiers for 3 CAN clock inputs for every other + SoC. +- clock-names: 2 clock input name strings for RZ/G2: "clkp1", "can_clk". + 3 clock input name strings for every other SoC: "clkp1", "clkp2", + "can_clk". - pinctrl-0: pin control group to be used for this controller. - pinctrl-names: must be "default". -Required properties for "renesas,can-r8a7795" and "renesas,can-r8a7796" -compatible: -In R8A7795 and R8A7796 SoCs, "clkp2" can be CANFD clock. This is a div6 clock -and can be used by both CAN and CAN FD controller at the same time. It needs to -be scaled to maximum frequency if any of these controllers use it. This is done +Required properties for R8A7795, R8A7796 and R8A77965: +For the denoted SoCs, "clkp2" can be CANFD clock. This is a div6 clock and can +be used by both CAN and CAN FD controller at the same time. It needs to be +scaled to maximum frequency if any of these controllers use it. This is done using the below properties: - assigned-clocks: phandle of clkp2(CANFD) clock. @@ -41,8 +49,9 @@ using the below properties: Optional properties: - renesas,can-clock-select: R-Car CAN Clock Source Select. Valid values are: <0x0> (default) : Peripheral clock (clkp1) - <0x1> : Peripheral clock (clkp2) - <0x3> : Externally input clock + <0x1> : Peripheral clock (clkp2) (not supported by + RZ/G2 devices) + <0x3> : External input clock Example ------- diff --git a/Documentation/devicetree/bindings/net/can/xilinx_can.txt b/Documentation/devicetree/bindings/net/can/xilinx_can.txt index 060e2d46bad9..100cc40b8510 100644 --- a/Documentation/devicetree/bindings/net/can/xilinx_can.txt +++ b/Documentation/devicetree/bindings/net/can/xilinx_can.txt @@ -6,6 +6,7 @@ Required properties: - "xlnx,zynq-can-1.0" for Zynq CAN controllers - "xlnx,axi-can-1.00.a" for Axi CAN controllers - "xlnx,canfd-1.0" for CAN FD controllers + - "xlnx,canfd-2.0" for CAN FD 2.0 controllers - reg : Physical base address and size of the controller registers map. - interrupts : Property with a value describing the interrupt diff --git a/Documentation/devicetree/bindings/net/cpsw-phy-sel.txt b/Documentation/devicetree/bindings/net/cpsw-phy-sel.txt index 764c0c79b43d..5d76f991c027 100644 --- a/Documentation/devicetree/bindings/net/cpsw-phy-sel.txt +++ b/Documentation/devicetree/bindings/net/cpsw-phy-sel.txt @@ -1,4 +1,4 @@ -TI CPSW Phy mode Selection Device Tree Bindings +TI CPSW Phy mode Selection Device Tree Bindings (DEPRECATED) ----------------------------------------------- Required properties: diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index b3acebe08eb0..3264e1978d25 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -22,7 +22,8 @@ Required properties: - cpsw-phy-sel : Specifies the phandle to the CPSW phy mode selection device. See also cpsw-phy-sel.txt for it's binding. Note that in legacy cases cpsw-phy-sel may be - a child device instead of a phandle. + a child device instead of a phandle + (DEPRECATED, use phys property instead). Optional properties: - ti,hwmods : Must be "cpgmac0" @@ -44,6 +45,7 @@ Optional properties: Slave Properties: Required properties: - phy-mode : See ethernet.txt file in the same directory +- phys : phandle on phy-gmii-sel PHY (see phy/ti-phy-gmii-sel.txt) Optional properties: - dual_emac_res_vlan : Specifies VID to be used to segregate the ports @@ -85,12 +87,14 @@ Examples: phy-mode = "rgmii-txid"; /* Filled in by U-Boot */ mac-address = [ 00 00 00 00 00 00 ]; + phys = <&phy_gmii_sel 1 0>; }; cpsw_emac1: slave@1 { phy_id = <&davinci_mdio>, <1>; phy-mode = "rgmii-txid"; /* Filled in by U-Boot */ mac-address = [ 00 00 00 00 00 00 ]; + phys = <&phy_gmii_sel 2 0>; }; }; @@ -114,11 +118,13 @@ Examples: phy-mode = "rgmii-txid"; /* Filled in by U-Boot */ mac-address = [ 00 00 00 00 00 00 ]; + phys = <&phy_gmii_sel 1 0>; }; cpsw_emac1: slave@1 { phy_id = <&davinci_mdio>, <1>; phy-mode = "rgmii-txid"; /* Filled in by U-Boot */ mac-address = [ 00 00 00 00 00 00 ]; + phys = <&phy_gmii_sel 2 0>; }; }; diff --git a/Documentation/devicetree/bindings/net/dsa/b53.txt b/Documentation/devicetree/bindings/net/dsa/b53.txt index 1811e1972a7a..5201bc15fdd6 100644 --- a/Documentation/devicetree/bindings/net/dsa/b53.txt +++ b/Documentation/devicetree/bindings/net/dsa/b53.txt @@ -46,6 +46,42 @@ Required properties: "brcm,bcm6328-switch" "brcm,bcm6368-switch" and the mandatory "brcm,bcm63xx-switch" +Required properties for BCM585xx/586xx/88312 SoCs: + + - reg: a total of 3 register base addresses, the first one must be the + Switch Register Access block base, the second is the port 5/4 mux + configuration register and the third one is the SGMII configuration + and status register base address. + + - interrupts: a total of 13 interrupts must be specified, in the following + order: port 0-5, 7-8 link status change, then the integrated PHY interrupt, + then the timestamping interrupt and the sleep timer interrupts for ports + 5,7,8. + +Optional properties for BCM585xx/586xx/88312 SoCs: + + - reg-names: a total of 3 names matching the 3 base register address, must + be in the following order: + "srab" + "mux_config" + "sgmii_config" + + - interrupt-names: a total of 13 names matching the 13 interrupts specified + must be in the following order: + "link_state_p0" + "link_state_p1" + "link_state_p2" + "link_state_p3" + "link_state_p4" + "link_state_p5" + "link_state_p7" + "link_state_p8" + "phy" + "ts" + "imp_sleep_timer_p5" + "imp_sleep_timer_p7" + "imp_sleep_timer_p8" + See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional required and optional properties. diff --git a/Documentation/devicetree/bindings/net/dsa/dsa.txt b/Documentation/devicetree/bindings/net/dsa/dsa.txt index 3ceeb8de1196..35694c0c376b 100644 --- a/Documentation/devicetree/bindings/net/dsa/dsa.txt +++ b/Documentation/devicetree/bindings/net/dsa/dsa.txt @@ -7,7 +7,7 @@ limitations. Current Binding --------------- -Switches are true Linux devices and can be probes by any means. Once +Switches are true Linux devices and can be probed by any means. Once probed, they register to the DSA framework, passing a node pointer. This node is expected to fulfil the following binding, and may contain additional properties as required by the device it is diff --git a/Documentation/devicetree/bindings/net/dsa/ksz.txt b/Documentation/devicetree/bindings/net/dsa/ksz.txt index ac145b885e95..e7db7268fd0f 100644 --- a/Documentation/devicetree/bindings/net/dsa/ksz.txt +++ b/Documentation/devicetree/bindings/net/dsa/ksz.txt @@ -7,6 +7,15 @@ Required properties: of the following: - "microchip,ksz9477" - "microchip,ksz9897" + - "microchip,ksz9896" + - "microchip,ksz9567" + - "microchip,ksz8565" + - "microchip,ksz9893" + - "microchip,ksz9563" + +Optional properties: + +- reset-gpios : Should be a gpio specifier for a reset line See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional required and optional properties. @@ -15,58 +24,96 @@ Examples: Ethernet switch connected via SPI to the host, CPU port wired to eth0: - eth0: ethernet@10001000 { - fixed-link { - speed = <1000>; - full-duplex; - }; - }; + eth0: ethernet@10001000 { + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + + spi1: spi@f8008000 { + pinctrl-0 = <&pinctrl_spi_ksz>; + cs-gpios = <&pioC 25 0>; + id = <1>; + + ksz9477: ksz9477@0 { + compatible = "microchip,ksz9477"; + reg = <0>; - spi1: spi@f8008000 { - pinctrl-0 = <&pinctrl_spi_ksz>; - cs-gpios = <&pioC 25 0>; - id = <1>; + spi-max-frequency = <44000000>; + spi-cpha; + spi-cpol; - ksz9477: ksz9477@0 { - compatible = "microchip,ksz9477"; - reg = <0>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + label = "lan1"; + }; + port@1 { + reg = <1>; + label = "lan2"; + }; + port@2 { + reg = <2>; + label = "lan3"; + }; + port@3 { + reg = <3>; + label = "lan4"; + }; + port@4 { + reg = <4>; + label = "lan5"; + }; + port@5 { + reg = <5>; + label = "cpu"; + ethernet = <ð0>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; + ksz8565: ksz8565@0 { + compatible = "microchip,ksz8565"; + reg = <0>; - spi-max-frequency = <44000000>; - spi-cpha; - spi-cpol; + spi-max-frequency = <44000000>; + spi-cpha; + spi-cpol; - ports { - #address-cells = <1>; - #size-cells = <0>; - port@0 { - reg = <0>; - label = "lan1"; - }; - port@1 { - reg = <1>; - label = "lan2"; - }; - port@2 { - reg = <2>; - label = "lan3"; - }; - port@3 { - reg = <3>; - label = "lan4"; - }; - port@4 { - reg = <4>; - label = "lan5"; - }; - port@5 { - reg = <5>; - label = "cpu"; - ethernet = <ð0>; - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - }; - }; - }; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + label = "lan1"; + }; + port@1 { + reg = <1>; + label = "lan2"; + }; + port@2 { + reg = <2>; + label = "lan3"; + }; + port@3 { + reg = <3>; + label = "lan4"; + }; + port@6 { + reg = <6>; + label = "cpu"; + ethernet = <ð0>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/dsa/mt7530.txt b/Documentation/devicetree/bindings/net/dsa/mt7530.txt index aa3527f71fdc..47aa205ee0bd 100644 --- a/Documentation/devicetree/bindings/net/dsa/mt7530.txt +++ b/Documentation/devicetree/bindings/net/dsa/mt7530.txt @@ -3,12 +3,16 @@ Mediatek MT7530 Ethernet switch Required properties: -- compatible: Must be compatible = "mediatek,mt7530"; +- compatible: may be compatible = "mediatek,mt7530" + or compatible = "mediatek,mt7621" - #address-cells: Must be 1. - #size-cells: Must be 0. - mediatek,mcm: Boolean; if defined, indicates that either MT7530 is the part on multi-chip module belong to MT7623A has or the remotely standalone chip as the function MT7623N reference board provided for. + +If compatible mediatek,mt7530 is set then the following properties are required + - core-supply: Phandle to the regulator node necessary for the core power. - io-supply: Phandle to the regulator node necessary for the I/O power. See Documentation/devicetree/bindings/regulator/mt6323-regulator.txt diff --git a/Documentation/devicetree/bindings/net/dwmac-sun8i.txt b/Documentation/devicetree/bindings/net/dwmac-sun8i.txt index 5bb3a18cc38d..54c66d0611cb 100644 --- a/Documentation/devicetree/bindings/net/dwmac-sun8i.txt +++ b/Documentation/devicetree/bindings/net/dwmac-sun8i.txt @@ -10,6 +10,7 @@ Required properties: "allwinner,sun8i-r40-gmac" "allwinner,sun8i-v3s-emac" "allwinner,sun50i-a64-emac" + "allwinner,sun50i-h6-emac", "allwinner-sun50i-a64-emac" - reg: address and length of the register for the device. - interrupts: interrupt for the device - interrupt-names: must be "macirq" diff --git a/Documentation/devicetree/bindings/net/fsl-enetc.txt b/Documentation/devicetree/bindings/net/fsl-enetc.txt new file mode 100644 index 000000000000..c812e25ae90f --- /dev/null +++ b/Documentation/devicetree/bindings/net/fsl-enetc.txt @@ -0,0 +1,69 @@ +* ENETC ethernet device tree bindings + +Depending on board design and ENETC port type (internal or +external) there are two supported link modes specified by +below device tree bindings. + +Required properties: + +- reg : Specifies PCIe Device Number and Function + Number of the ENETC endpoint device, according + to parent node bindings. +- compatible : Should be "fsl,enetc". + +1) The ENETC external port is connected to a MDIO configurable phy: + +In this case, the ENETC node should include a "mdio" sub-node +that in turn should contain the "ethernet-phy" node describing the +external phy. Below properties are required, their bindings +already defined in ethernet.txt or phy.txt, under +Documentation/devicetree/bindings/net/*. + +Required: + +- phy-handle : Phandle to a PHY on the MDIO bus. + Defined in ethernet.txt. + +- phy-connection-type : Defined in ethernet.txt. + +- mdio : "mdio" node, defined in mdio.txt. + +- ethernet-phy : "ethernet-phy" node, defined in phy.txt. + +Example: + + ethernet@0,0 { + compatible = "fsl,enetc"; + reg = <0x000000 0 0 0 0>; + phy-handle = <&sgmii_phy0>; + phy-connection-type = "sgmii"; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + sgmii_phy0: ethernet-phy@2 { + reg = <0x2>; + }; + }; + }; + +2) The ENETC port is an internal port or has a fixed-link external +connection: + +In this case, the ENETC port node defines a fixed link connection, +as specified by "fixed-link.txt", under +Documentation/devicetree/bindings/net/*. + +Required: + +- fixed-link : "fixed-link" node, defined in "fixed-link.txt". + +Example: + ethernet@0,2 { + compatible = "fsl,enetc"; + reg = <0x000200 0 0 0 0>; + fixed-link { + speed = <1000>; + full-duplex; + }; + }; diff --git a/Documentation/devicetree/bindings/net/icplus-ip101ag.txt b/Documentation/devicetree/bindings/net/icplus-ip101ag.txt new file mode 100644 index 000000000000..a784592bbb15 --- /dev/null +++ b/Documentation/devicetree/bindings/net/icplus-ip101ag.txt @@ -0,0 +1,19 @@ +IC Plus Corp. IP101A / IP101G Ethernet PHYs + +There are different models of the IP101G Ethernet PHY: +- IP101GR (32-pin QFN package) +- IP101G (die only, no package) +- IP101GA (48-pin LQFP package) + +There are different models of the IP101A Ethernet PHY (which is the +predecessor of the IP101G): +- IP101A (48-pin LQFP package) +- IP101AH (48-pin LQFP package) + +Optional properties for the IP101GR (32-pin QFN package): + +- icplus,select-rx-error: + pin 21 ("RXER/INTR_32") will output the receive error status. + interrupts are not routed outside the PHY in this mode. +- icplus,select-interrupt: + pin 21 ("RXER/INTR_32") will output the interrupt signal. diff --git a/Documentation/devicetree/bindings/net/macb.txt b/Documentation/devicetree/bindings/net/macb.txt index 3e17ac1d5d58..174f292d8a3e 100644 --- a/Documentation/devicetree/bindings/net/macb.txt +++ b/Documentation/devicetree/bindings/net/macb.txt @@ -3,8 +3,8 @@ Required properties: - compatible: Should be "cdns,[<chip>-]{macb|gem}" Use "cdns,at91rm9200-emac" Atmel at91rm9200 SoC. - Use "cdns,at91sam9260-macb" for Atmel at91sam9 SoCs or the 10/100Mbit IP - available on sama5d3 SoCs. + Use "cdns,at91sam9260-macb" for Atmel at91sam9 SoCs. + Use "cdns,sam9x60-macb" for Microchip sam9x60 SoC. Use "cdns,np4-macb" for NP4 SoC devices. Use "cdns,at32ap7000-macb" for other 10/100 usage or use the generic form: "cdns,macb". Use "cdns,pc302-gem" for Picochip picoXcell pc302 and later devices based on diff --git a/Documentation/devicetree/bindings/net/marvell,prestera.txt b/Documentation/devicetree/bindings/net/marvell,prestera.txt index c329608fa887..83370ebf5b89 100644 --- a/Documentation/devicetree/bindings/net/marvell,prestera.txt +++ b/Documentation/devicetree/bindings/net/marvell,prestera.txt @@ -2,7 +2,7 @@ Marvell Prestera Switch Chip bindings ------------------------------------- Required properties: -- compatible: one of the following +- compatible: must be "marvell,prestera" and one of the following "marvell,prestera-98dx3236", "marvell,prestera-98dx3336", "marvell,prestera-98dx4251", @@ -21,7 +21,7 @@ switch { ranges = <0 MBUS_ID(0x03, 0x00) 0 0x100000>; packet-processor@0 { - compatible = "marvell,prestera-98dx3236"; + compatible = "marvell,prestera-98dx3236", "marvell,prestera"; reg = <0 0x4000000>; interrupts = <33>, <34>, <35>; dfx = <&dfx>; diff --git a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt index bedcfd5a52cd..691f886cfc4a 100644 --- a/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt +++ b/Documentation/devicetree/bindings/net/marvell-armada-370-neta.txt @@ -19,7 +19,7 @@ Optional properties: "marvell,armada-370-neta" and 9800B for others. - clock-names: List of names corresponding to clocks property; shall be "core" for core clock and "bus" for the optional bus clock. - +- phys: comphy for the ethernet port, see ../phy/phy-bindings.txt Optional properties (valid only for Armada XP/38x): diff --git a/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt b/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt new file mode 100644 index 000000000000..534e38058fe0 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mdio-mux-multiplexer.txt @@ -0,0 +1,82 @@ +Properties for an MDIO bus multiplexer consumer device + +This is a special case of MDIO mux when MDIO mux is defined as a consumer +of a mux producer device. The mux producer can be of any type like mmio mux +producer, gpio mux producer or generic register based mux producer. + +Required properties in addition to the MDIO Bus multiplexer properties: + +- compatible : should be "mmio-mux-multiplexer" +- mux-controls : mux controller node to use for operating the mux +- mdio-parent-bus : phandle to the parent MDIO bus. + +each child node of mdio bus multiplexer consumer device represent a mdio +bus. + +for more information please refer +Documentation/devicetree/bindings/mux/mux-controller.txt +and Documentation/devicetree/bindings/net/mdio-mux.txt + +Example: +In below example the Mux producer and consumer are separate nodes. + +&i2c0 { + fpga@66 { // fpga connected to i2c + compatible = "fsl,lx2160aqds-fpga", "fsl,fpga-qixis-i2c", + "simple-mfd"; + reg = <0x66>; + + mux: mux-controller { // Mux Producer + compatible = "reg-mux"; + #mux-control-cells = <1>; + mux-reg-masks = <0x54 0xf8>, /* 0: reg 0x54, bits 7:3 */ + <0x54 0x07>; /* 1: reg 0x54, bits 2:0 */ + }; + }; +}; + +mdio-mux-1 { // Mux consumer + compatible = "mdio-mux-multiplexer"; + mux-controls = <&mux 0>; + mdio-parent-bus = <&emdio1>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + mdio@8 { + reg = <0x8>; + #address-cells = <1>; + #size-cells = <0>; + }; + + .. + .. +}; + +mdio-mux-2 { // Mux consumer + compatible = "mdio-mux-multiplexer"; + mux-controls = <&mux 1>; + mdio-parent-bus = <&emdio2>; + #address-cells = <1>; + #size-cells = <0>; + + mdio@0 { + reg = <0x0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + mdio@1 { + reg = <0x1>; + #address-cells = <1>; + #size-cells = <0>; + }; + + .. + .. +}; diff --git a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt index 14ceb2a5b4e8..41a7dcc80f5b 100644 --- a/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt +++ b/Documentation/devicetree/bindings/net/mediatek-bluetooth.txt @@ -33,3 +33,67 @@ Example: clock-names = "ref"; }; }; + +MediaTek UART based Bluetooth Devices +================================== + +This device is a serial attached device to UART device and thus it must be a +child node of the serial node with UART. + +Please refer to the following documents for generic properties: + + Documentation/devicetree/bindings/serial/slave-device.txt + +Required properties: + +- compatible: Must be + "mediatek,mt7663u-bluetooth": for MT7663U device + "mediatek,mt7668u-bluetooth": for MT7668U device +- vcc-supply: Main voltage regulator +- pinctrl-names: Should be "default", "runtime" +- pinctrl-0: Should contain UART RXD low when the device is powered up to + enter proper bootstrap mode. +- pinctrl-1: Should contain UART mode pin ctrl + +Optional properties: + +- reset-gpios: GPIO used to reset the device whose initial state keeps low, + if the GPIO is missing, then board-level design should be + guaranteed. +- current-speed: Current baud rate of the device whose defaults to 921600 + +Example: + + uart1_pins_boot: uart1-default { + pins-dat { + pinmux = <MT7623_PIN_81_URXD1_FUNC_GPIO81>; + output-low; + }; + }; + + uart1_pins_runtime: uart1-runtime { + pins-dat { + pinmux = <MT7623_PIN_81_URXD1_FUNC_URXD1>, + <MT7623_PIN_82_UTXD1_FUNC_UTXD1>; + }; + }; + + uart1: serial@11003000 { + compatible = "mediatek,mt7623-uart", + "mediatek,mt6577-uart"; + reg = <0 0x11003000 0 0x400>; + interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_LOW>; + clocks = <&pericfg CLK_PERI_UART1_SEL>, + <&pericfg CLK_PERI_UART1>; + clock-names = "baud", "bus"; + + bluetooth { + compatible = "mediatek,mt7663u-bluetooth"; + vcc-supply = <®_5v>; + reset-gpios = <&pio 24 GPIO_ACTIVE_LOW>; + pinctrl-names = "default", "runtime"; + pinctrl-0 = <&uart1_pins_boot>; + pinctrl-1 = <&uart1_pins_runtime>; + current-speed = <921600>; + }; + }; diff --git a/Documentation/devicetree/bindings/net/mediatek-dwmac.txt b/Documentation/devicetree/bindings/net/mediatek-dwmac.txt new file mode 100644 index 000000000000..8a08621a5b54 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mediatek-dwmac.txt @@ -0,0 +1,78 @@ +MediaTek DWMAC glue layer controller + +This file documents platform glue layer for stmmac. +Please see stmmac.txt for the other unchanged properties. + +The device node has following properties. + +Required properties: +- compatible: Should be "mediatek,mt2712-gmac" for MT2712 SoC +- reg: Address and length of the register set for the device +- interrupts: Should contain the MAC interrupts +- interrupt-names: Should contain a list of interrupt names corresponding to + the interrupts in the interrupts property, if available. + Should be "macirq" for the main MAC IRQ +- clocks: Must contain a phandle for each entry in clock-names. +- clock-names: The name of the clock listed in the clocks property. These are + "axi", "apb", "mac_main", "ptp_ref" for MT2712 SoC +- mac-address: See ethernet.txt in the same directory +- phy-mode: See ethernet.txt in the same directory +- mediatek,pericfg: A phandle to the syscon node that control ethernet + interface and timing delay. + +Optional properties: +- mediatek,tx-delay-ps: TX clock delay macro value. Default is 0. + It should be defined for RGMII/MII interface. +- mediatek,rx-delay-ps: RX clock delay macro value. Default is 0. + It should be defined for RGMII/MII/RMII interface. +Both delay properties need to be a multiple of 170 for RGMII interface, +or will round down. Range 0~31*170. +Both delay properties need to be a multiple of 550 for MII/RMII interface, +or will round down. Range 0~31*550. + +- mediatek,rmii-rxc: boolean property, if present indicates that the RMII + reference clock, which is from external PHYs, is connected to RXC pin + on MT2712 SoC. + Otherwise, is connected to TXC pin. +- mediatek,txc-inverse: boolean property, if present indicates that + 1. tx clock will be inversed in MII/RGMII case, + 2. tx clock inside MAC will be inversed relative to reference clock + which is from external PHYs in RMII case, and it rarely happen. +- mediatek,rxc-inverse: boolean property, if present indicates that + 1. rx clock will be inversed in MII/RGMII case. + 2. reference clock will be inversed when arrived at MAC in RMII case. +- assigned-clocks: mac_main and ptp_ref clocks +- assigned-clock-parents: parent clocks of the assigned clocks + +Example: + eth: ethernet@1101c000 { + compatible = "mediatek,mt2712-gmac"; + reg = <0 0x1101c000 0 0x1300>; + interrupts = <GIC_SPI 237 IRQ_TYPE_LEVEL_LOW>; + interrupt-names = "macirq"; + phy-mode ="rgmii"; + mac-address = [00 55 7b b5 7d f7]; + clock-names = "axi", + "apb", + "mac_main", + "ptp_ref", + "ptp_top"; + clocks = <&pericfg CLK_PERI_GMAC>, + <&pericfg CLK_PERI_GMAC_PCLK>, + <&topckgen CLK_TOP_ETHER_125M_SEL>, + <&topckgen CLK_TOP_ETHER_50M_SEL>; + assigned-clocks = <&topckgen CLK_TOP_ETHER_125M_SEL>, + <&topckgen CLK_TOP_ETHER_50M_SEL>; + assigned-clock-parents = <&topckgen CLK_TOP_ETHERPLL_125M>, + <&topckgen CLK_TOP_APLL1_D3>; + mediatek,pericfg = <&pericfg>; + mediatek,tx-delay-ps = <1530>; + mediatek,rx-delay-ps = <1530>; + mediatek,rmii-rxc; + mediatek,txc-inverse; + mediatek,rxc-inverse; + snps,txpbl = <32>; + snps,rxpbl = <32>; + snps,reset-gpio = <&pio 87 GPIO_ACTIVE_LOW>; + snps,reset-active-low; + }; diff --git a/Documentation/devicetree/bindings/net/nixge.txt b/Documentation/devicetree/bindings/net/nixge.txt index e55af7f0881a..85d7240a9b20 100644 --- a/Documentation/devicetree/bindings/net/nixge.txt +++ b/Documentation/devicetree/bindings/net/nixge.txt @@ -1,17 +1,53 @@ * NI XGE Ethernet controller Required properties: -- compatible: Should be "ni,xge-enet-2.00" -- reg: Address and length of the register set for the device +- compatible: Should be "ni,xge-enet-3.00", but can be "ni,xge-enet-2.00" for + older device trees with DMA engines co-located in the address map, + with the one reg entry to describe the whole device. +- reg: Address and length of the register set for the device. It contains the + information of registers in the same order as described by reg-names. +- reg-names: Should contain the reg names + "dma": DMA engine control and status region + "ctrl": MDIO and PHY control and status region - interrupts: Should contain tx and rx interrupt - interrupt-names: Should be "rx" and "tx" - phy-mode: See ethernet.txt file in the same directory. -- phy-handle: See ethernet.txt file in the same directory. - nvmem-cells: Phandle of nvmem cell containing the MAC address - nvmem-cell-names: Should be "address" +Optional properties: +- mdio subnode to indicate presence of MDIO controller +- fixed-link : Assume a fixed link. See fixed-link.txt in the same directory. + Use instead of phy-handle. +- phy-handle: See ethernet.txt file in the same directory. + Examples (10G generic PHY): nixge0: ethernet@40000000 { + compatible = "ni,xge-enet-3.00"; + reg = <0x40000000 0x4000 + 0x41002000 0x2000>; + reg-names = "dma", "ctrl"; + + nvmem-cells = <ð1_addr>; + nvmem-cell-names = "address"; + + interrupts = <0 29 IRQ_TYPE_LEVEL_HIGH>, <0 30 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "rx", "tx"; + interrupt-parent = <&intc>; + + phy-mode = "xgmii"; + phy-handle = <ðernet_phy1>; + + mdio { + ethernet_phy1: ethernet-phy@4 { + compatible = "ethernet-phy-ieee802.3-c45"; + reg = <4>; + }; + }; + }; + +Examples (10G generic PHY, no MDIO): + nixge0: ethernet@40000000 { compatible = "ni,xge-enet-2.00"; reg = <0x40000000 0x6000>; @@ -24,9 +60,33 @@ Examples (10G generic PHY): phy-mode = "xgmii"; phy-handle = <ðernet_phy1>; + }; + +Examples (1G generic fixed-link + MDIO): + nixge0: ethernet@40000000 { + compatible = "ni,xge-enet-2.00"; + reg = <0x40000000 0x6000>; - ethernet_phy1: ethernet-phy@4 { - compatible = "ethernet-phy-ieee802.3-c45"; - reg = <4>; + nvmem-cells = <ð1_addr>; + nvmem-cell-names = "address"; + + interrupts = <0 29 IRQ_TYPE_LEVEL_HIGH>, <0 30 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "rx", "tx"; + interrupt-parent = <&intc>; + + phy-mode = "xgmii"; + + fixed-link { + speed = <1000>; + pause; + link-gpios = <&gpio0 63 GPIO_ACTIVE_HIGH>; + }; + + mdio { + ethernet_phy1: ethernet-phy@4 { + compatible = "ethernet-phy-ieee802.3-c22"; + reg = <4>; + }; }; + }; diff --git a/Documentation/devicetree/bindings/net/qcom,ethqos.txt b/Documentation/devicetree/bindings/net/qcom,ethqos.txt new file mode 100644 index 000000000000..fcf5035810b5 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qcom,ethqos.txt @@ -0,0 +1,64 @@ +Qualcomm Ethernet ETHQOS device + +This documents dwmmac based ethernet device which supports Gigabit +ethernet for version v2.3.0 onwards. + +This device has following properties: + +Required properties: + +- compatible: Should be qcom,qcs404-ethqos" + +- reg: Address and length of the register set for the device + +- reg-names: Should contain register names "stmmaceth", "rgmii" + +- clocks: Should contain phandle to clocks + +- clock-names: Should contain clock names "stmmaceth", "pclk", + "ptp_ref", "rgmii" + +- interrupts: Should contain phandle to interrupts + +- interrupt-names: Should contain interrupt names "macirq", "eth_lpi" + +Rest of the properties are defined in stmmac.txt file in same directory + + +Example: + +ethernet: ethernet@7a80000 { + compatible = "qcom,qcs404-ethqos"; + reg = <0x07a80000 0x10000>, + <0x07a96000 0x100>; + reg-names = "stmmaceth", "rgmii"; + clock-names = "stmmaceth", "pclk", "ptp_ref", "rgmii"; + clocks = <&gcc GCC_ETH_AXI_CLK>, + <&gcc GCC_ETH_SLAVE_AHB_CLK>, + <&gcc GCC_ETH_PTP_CLK>, + <&gcc GCC_ETH_RGMII_CLK>; + interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 55 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "macirq", "eth_lpi"; + snps,reset-gpio = <&tlmm 60 GPIO_ACTIVE_LOW>; + snps,reset-active-low; + + snps,txpbl = <8>; + snps,rxpbl = <2>; + snps,aal; + snps,tso; + + phy-handle = <&phy1>; + phy-mode = "rgmii"; + + mdio { + #address-cells = <0x1>; + #size-cells = <0x0>; + compatible = "snps,dwmac-mdio"; + phy1: phy@4 { + device_type = "ethernet-phy"; + reg = <0x4>; + }; + }; + +}; diff --git a/Documentation/devicetree/bindings/net/renesas,ravb.txt b/Documentation/devicetree/bindings/net/renesas,ravb.txt index 3530256a879c..7ad36213093e 100644 --- a/Documentation/devicetree/bindings/net/renesas,ravb.txt +++ b/Documentation/devicetree/bindings/net/renesas,ravb.txt @@ -18,6 +18,7 @@ Required properties: R-Car Gen2 and RZ/G1 devices. - "renesas,etheravb-r8a774a1" for the R8A774A1 SoC. + - "renesas,etheravb-r8a774c0" for the R8A774C0 SoC. - "renesas,etheravb-r8a7795" for the R8A7795 SoC. - "renesas,etheravb-r8a7796" for the R8A7796 SoC. - "renesas,etheravb-r8a77965" for the R8A77965 SoC. diff --git a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt index 0c17a0ec9b7b..7b9a776230c0 100644 --- a/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt +++ b/Documentation/devicetree/bindings/net/wireless/mediatek,mt76.txt @@ -4,6 +4,13 @@ This node provides properties for configuring the MediaTek mt76xx wireless device. The node is expected to be specified as a child node of the PCI controller to which the wireless chip is connected. +Alternatively, it can specify the wireless part of the MT7628/MT7688 SoC. +For SoC, use the compatible string "mediatek,mt7628-wmac" and the following +properties: + +- reg: Address and length of the register set for the device. +- interrupts: Main device interrupt + Optional properties: - mac-address: See ethernet.txt in the parent directory @@ -30,3 +37,15 @@ Optional nodes: }; }; }; + +MT7628 example: + +wmac: wmac@10300000 { + compatible = "mediatek,mt7628-wmac"; + reg = <0x10300000 0x100000>; + + interrupt-parent = <&cpuintc>; + interrupts = <6>; + + mediatek,mtd-eeprom = <&factory 0x0000>; +}; diff --git a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt index 2196d1ab3c8c..ae661e65354e 100644 --- a/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt +++ b/Documentation/devicetree/bindings/net/wireless/qcom,ath10k.txt @@ -21,10 +21,22 @@ can be provided per device. SNOC based devices (i.e. wcn3990) uses compatible string "qcom,wcn3990-wifi". -Optional properties: - reg: Address and length of the register set for the device. - reg-names: Must include the list of following reg names, "membase" +- interrupts: reference to the list of 17 interrupt numbers for "qcom,ipq4019-wifi" + compatible target. + reference to the list of 12 interrupt numbers for "qcom,wcn3990-wifi" + compatible target. + Must contain interrupt-names property per entry for + "qcom,ath10k", "qcom,ipq4019-wifi" compatible targets. + +- interrupt-names: Must include the entries for MSI interrupt + names ("msi0" to "msi15") and legacy interrupt + name ("legacy") for "qcom,ath10k", "qcom,ipq4019-wifi" + compatible targets. + +Optional properties: - resets: Must contain an entry for each entry in reset-names. See ../reset/reseti.txt for details. - reset-names: Must include the list of following reset names, @@ -37,12 +49,9 @@ Optional properties: - clocks: List of clock specifiers, must contain an entry for each required entry in clock-names. - clock-names: Should contain the clock names "wifi_wcss_cmd", "wifi_wcss_ref", - "wifi_wcss_rtc". -- interrupts: List of interrupt lines. Must contain an entry - for each entry in the interrupt-names property. -- interrupt-names: Must include the entries for MSI interrupt - names ("msi0" to "msi15") and legacy interrupt - name ("legacy"), + "wifi_wcss_rtc" for "qcom,ipq4019-wifi" compatible target and + "cxo_ref_clk_pin" for "qcom,wcn3990-wifi" + compatible target. - qcom,msi_addr: MSI interrupt address. - qcom,msi_base: Base value to add before writing MSI data into MSI address register. @@ -55,14 +64,25 @@ Optional properties: - qcom,ath10k-pre-calibration-data : pre calibration data as an array, the length can vary between hw versions. - <supply-name>-supply: handle to the regulator device tree node - optional "supply-name" is "vdd-0.8-cx-mx". + optional "supply-name" are "vdd-0.8-cx-mx", + "vdd-1.8-xo", "vdd-1.3-rfa" and "vdd-3.3-ch0". - memory-region: Usage: optional Value type: <phandle> Definition: reference to the reserved-memory for the msa region used by the wifi firmware running in Q6. +- iommus: + Usage: optional + Value type: <prop-encoded-array> + Definition: A list of phandle and IOMMU specifier pairs. +- ext-fem-name: + Usage: Optional + Value type: string + Definition: Name of external front end module used. Some valid FEM names + for example: "microsemi-lx5586", "sky85703-11" + and "sky85803" etc. -Example (to supply the calibration data alone): +Example (to supply PCI based wifi block details): In this example, the node is defined as child node of the PCI controller. @@ -74,10 +94,10 @@ pci { #address-cells = <3>; device_type = "pci"; - ath10k@0,0 { + wifi@0,0 { reg = <0 0 0 0 0>; - device_type = "pci"; qcom,ath10k-calibration-data = [ 01 02 03 ... ]; + ext-fem-name = "microsemi-lx5586"; }; }; }; @@ -138,21 +158,25 @@ wifi@18000000 { compatible = "qcom,wcn3990-wifi"; reg = <0x18800000 0x800000>; reg-names = "membase"; - clocks = <&clock_gcc clk_aggre2_noc_clk>; - clock-names = "smmu_aggre2_noc_clk" + clocks = <&clock_gcc clk_rf_clk2_pin>; + clock-names = "cxo_ref_clk_pin"; interrupts = - <0 130 0 /* CE0 */ >, - <0 131 0 /* CE1 */ >, - <0 132 0 /* CE2 */ >, - <0 133 0 /* CE3 */ >, - <0 134 0 /* CE4 */ >, - <0 135 0 /* CE5 */ >, - <0 136 0 /* CE6 */ >, - <0 137 0 /* CE7 */ >, - <0 138 0 /* CE8 */ >, - <0 139 0 /* CE9 */ >, - <0 140 0 /* CE10 */ >, - <0 141 0 /* CE11 */ >; + <GIC_SPI 414 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 415 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 416 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 417 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 418 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 419 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 420 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 421 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 422 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 423 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 424 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 425 IRQ_TYPE_LEVEL_HIGH>; vdd-0.8-cx-mx-supply = <&pm8998_l5>; + vdd-1.8-xo-supply = <&vreg_l7a_1p8>; + vdd-1.3-rfa-supply = <&vreg_l17a_1p3>; + vdd-3.3-ch0-supply = <&vreg_l25a_3p3>; memory-region = <&wifi_msa_mem>; + iommus = <&apps_smmu 0x0040 0x1>; }; diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt index e319fe5e205a..99c4ba6a3f61 100644 --- a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt +++ b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt @@ -7,6 +7,7 @@ Required properties: "allwinner,sun8i-a83t-sid" "allwinner,sun8i-h3-sid" "allwinner,sun50i-a64-sid" + "allwinner,sun50i-h5-sid" - reg: Should contain registers location and length diff --git a/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt b/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt index e3298e18de26..2e0723ab3384 100644 --- a/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt +++ b/Documentation/devicetree/bindings/nvmem/amlogic-efuse.txt @@ -2,6 +2,8 @@ Required properties: - compatible: should be "amlogic,meson-gxbb-efuse" +- clocks: phandle to the efuse peripheral clock provided by the + clock controller. = Data cells = Are child nodes of eFuse, bindings of which as described in @@ -11,6 +13,7 @@ Example: efuse: efuse { compatible = "amlogic,meson-gxbb-efuse"; + clocks = <&clkc CLKID_EFUSE>; #address-cells = <1>; #size-cells = <1>; diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt index 792bc5fafeb9..7a999a135e56 100644 --- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt +++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt @@ -1,7 +1,7 @@ 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, i.MX6SX, i.MX6UL and i.MX6SLL SoCs. +i.MX6Q/D, i.MX6DL/S, i.MX6SL, i.MX6SX, i.MX6UL, i.MX6ULL/ULZ and i.MX6SLL SoCs. Required properties: - compatible: should be one of @@ -9,8 +9,10 @@ Required properties: "fsl,imx6sl-ocotp" (i.MX6SL), or "fsl,imx6sx-ocotp" (i.MX6SX), "fsl,imx6ul-ocotp" (i.MX6UL), + "fsl,imx6ull-ocotp" (i.MX6ULL/ULZ), "fsl,imx7d-ocotp" (i.MX7D/S), "fsl,imx6sll-ocotp" (i.MX6SLL), + "fsl,imx7ulp-ocotp" (i.MX7ULP), followed by "syscon". - #address-cells : Should be 1 - #size-cells : Should be 1 diff --git a/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt b/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt new file mode 100644 index 000000000000..4881561b3a02 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt @@ -0,0 +1,46 @@ +-------------------------------------------------------------------------- += Zynq UltraScale+ MPSoC nvmem firmware driver binding = +-------------------------------------------------------------------------- +The nvmem_firmware node provides access to the hardware related data +like soc revision, IDCODE... etc, By using the firmware interface. + +Required properties: +- compatible: should be "xlnx,zynqmp-nvmem-fw" + += Data cells = +Are child nodes of silicon id, bindings of which as described in +bindings/nvmem/nvmem.txt + +------- + Example +------- +firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + + nvmem_firmware { + compatible = "xlnx,zynqmp-nvmem-fw"; + #address-cells = <1>; + #size-cells = <1>; + + /* Data cells */ + soc_revision: soc_revision { + reg = <0x0 0x4>; + }; + }; + }; +}; + += Data consumers = +Are device nodes which consume nvmem data cells. + +For example: + pcap { + ... + + nvmem-cells = <&soc_revision>; + nvmem-cell-names = "soc_revision"; + + ... + }; diff --git a/Documentation/devicetree/bindings/opp/opp.txt b/Documentation/devicetree/bindings/opp/opp.txt index c396c4c0af92..76b6c79604a5 100644 --- a/Documentation/devicetree/bindings/opp/opp.txt +++ b/Documentation/devicetree/bindings/opp/opp.txt @@ -129,6 +129,9 @@ Optional properties: - opp-microamp-<name>: Named opp-microamp property. Similar to opp-microvolt-<name> property, but for microamp instead. +- opp-level: A value representing the performance level of the device, + expressed as a 32-bit integer. + - clock-latency-ns: Specifies the maximum possible transition latency (in nanoseconds) for switching to this OPP from any other OPP. diff --git a/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt b/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt new file mode 100644 index 000000000000..12b18f82d441 --- /dev/null +++ b/Documentation/devicetree/bindings/pci/amlogic,meson-pcie.txt @@ -0,0 +1,70 @@ +Amlogic Meson AXG DWC PCIE SoC controller + +Amlogic Meson PCIe host controller is based on the Synopsys DesignWare PCI core. +It shares common functions with the PCIe DesignWare core driver and +inherits common properties defined in +Documentation/devicetree/bindings/pci/designware-pci.txt. + +Additional properties are described here: + +Required properties: +- compatible: + should contain "amlogic,axg-pcie" to identify the core. +- reg: + should contain the configuration address space. +- reg-names: Must be + - "elbi" External local bus interface registers + - "cfg" Meson specific registers + - "phy" Meson PCIE PHY registers + - "config" PCIe configuration space +- reset-gpios: The GPIO to generate PCIe PERST# assert and deassert signal. +- clocks: Must contain an entry for each entry in clock-names. +- clock-names: Must include the following entries: + - "pclk" PCIe GEN 100M PLL clock + - "port" PCIe_x(A or B) RC clock gate + - "general" PCIe Phy clock + - "mipi" PCIe_x(A or B) 100M ref clock gate +- resets: phandle to the reset lines. +- reset-names: must contain "phy" "port" and "apb" + - "phy" Share PHY reset + - "port" Port A or B reset + - "apb" Share APB reset +- device_type: + should be "pci". As specified in designware-pcie.txt + + +Example configuration: + + pcie: pcie@f9800000 { + compatible = "amlogic,axg-pcie", "snps,dw-pcie"; + reg = <0x0 0xf9800000 0x0 0x400000 + 0x0 0xff646000 0x0 0x2000 + 0x0 0xff644000 0x0 0x2000 + 0x0 0xf9f00000 0x0 0x100000>; + reg-names = "elbi", "cfg", "phy", "config"; + reset-gpios = <&gpio GPIOX_19 GPIO_ACTIVE_HIGH>; + interrupts = <GIC_SPI 177 IRQ_TYPE_EDGE_RISING>; + #interrupt-cells = <1>; + interrupt-map-mask = <0 0 0 0>; + interrupt-map = <0 0 0 0 &gic GIC_SPI 179 IRQ_TYPE_EDGE_RISING>; + bus-range = <0x0 0xff>; + #address-cells = <3>; + #size-cells = <2>; + device_type = "pci"; + ranges = <0x82000000 0 0 0x0 0xf9c00000 0 0x00300000>; + + clocks = <&clkc CLKID_USB + &clkc CLKID_MIPI_ENABLE + &clkc CLKID_PCIE_A + &clkc CLKID_PCIE_CML_EN0>; + clock-names = "general", + "mipi", + "pclk", + "port"; + resets = <&reset RESET_PCIE_PHY>, + <&reset RESET_PCIE_A>, + <&reset RESET_PCIE_APB>; + reset-names = "phy", + "port", + "apb"; + }; diff --git a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt index f37494d5a7be..d514c1f2365f 100644 --- a/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt +++ b/Documentation/devicetree/bindings/pci/fsl,imx6q-pcie.txt @@ -41,7 +41,9 @@ Optional properties: Additional required properties for imx6sx-pcie: - clock names: Must include the following additional entries: - "pcie_inbound_axi" -- power-domains: Must be set to a phandle pointing to the PCIE_PHY power domain +- power-domains: Must be set to phandles pointing to the DISPLAY and + PCIE_PHY power domains +- power-domain-names: Must be "pcie", "pcie_phy" Additional required properties for imx7d-pcie: - power-domains: Must be set to a phandle pointing to PCIE_PHY power domain diff --git a/Documentation/devicetree/bindings/pci/host-generic-pci.txt b/Documentation/devicetree/bindings/pci/host-generic-pci.txt index 3f1d3fca62bb..614b594f4e72 100644 --- a/Documentation/devicetree/bindings/pci/host-generic-pci.txt +++ b/Documentation/devicetree/bindings/pci/host-generic-pci.txt @@ -56,7 +56,7 @@ For CAM, this 24-bit offset is: cfg_offset(bus, device, function, register) = bus << 16 | device << 11 | function << 8 | register -Whilst ECAM extends this by 4 bits to accommodate 4k of function space: +While ECAM extends this by 4 bits to accommodate 4k of function space: cfg_offset(bus, device, function, register) = bus << 20 | device << 15 | function << 12 | register diff --git a/Documentation/devicetree/bindings/pci/layerscape-pci.txt b/Documentation/devicetree/bindings/pci/layerscape-pci.txt index 66df1e81e0b8..9b2b8d66d1f4 100644 --- a/Documentation/devicetree/bindings/pci/layerscape-pci.txt +++ b/Documentation/devicetree/bindings/pci/layerscape-pci.txt @@ -13,11 +13,12 @@ information. Required properties: - compatible: should contain the platform identifier such as: - "fsl,ls1021a-pcie", "snps,dw-pcie" - "fsl,ls2080a-pcie", "fsl,ls2085a-pcie", "snps,dw-pcie" + "fsl,ls1021a-pcie" + "fsl,ls2080a-pcie", "fsl,ls2085a-pcie" "fsl,ls2088a-pcie" "fsl,ls1088a-pcie" "fsl,ls1046a-pcie" + "fsl,ls1043a-pcie" "fsl,ls1012a-pcie" - reg: base addresses and lengths of the PCIe controller register blocks. - interrupts: A list of interrupt outputs of the controller. Must contain an @@ -35,7 +36,7 @@ Required properties: Example: pcie@3400000 { - compatible = "fsl,ls1021a-pcie", "snps,dw-pcie"; + compatible = "fsl,ls1021a-pcie"; reg = <0x00 0x03400000 0x0 0x00010000 /* controller registers */ 0x40 0x00000000 0x0 0x00002000>; /* configuration space */ reg-names = "regs", "config"; diff --git a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt index 20227a875ac8..92437a366e5f 100644 --- a/Documentation/devicetree/bindings/pci/mediatek-pcie.txt +++ b/Documentation/devicetree/bindings/pci/mediatek-pcie.txt @@ -65,7 +65,6 @@ Required properties: explanation. - ranges: Sub-ranges distributed from the PCIe controller node. An empty property is sufficient. -- num-lanes: Number of lanes to use for this port. Examples for MT7623: @@ -118,7 +117,6 @@ Examples for MT7623: interrupt-map-mask = <0 0 0 0>; interrupt-map = <0 0 0 0 &sysirq GIC_SPI 193 IRQ_TYPE_LEVEL_LOW>; ranges; - num-lanes = <1>; }; pcie@1,0 { @@ -129,7 +127,6 @@ Examples for MT7623: interrupt-map-mask = <0 0 0 0>; interrupt-map = <0 0 0 0 &sysirq GIC_SPI 194 IRQ_TYPE_LEVEL_LOW>; ranges; - num-lanes = <1>; }; pcie@2,0 { @@ -140,7 +137,6 @@ Examples for MT7623: interrupt-map-mask = <0 0 0 0>; interrupt-map = <0 0 0 0 &sysirq GIC_SPI 195 IRQ_TYPE_LEVEL_LOW>; ranges; - num-lanes = <1>; }; }; @@ -172,7 +168,6 @@ Examples for MT2712: #size-cells = <2>; #interrupt-cells = <1>; ranges; - num-lanes = <1>; interrupt-map-mask = <0 0 0 7>; interrupt-map = <0 0 0 1 &pcie_intc0 0>, <0 0 0 2 &pcie_intc0 1>, @@ -191,7 +186,6 @@ Examples for MT2712: #size-cells = <2>; #interrupt-cells = <1>; ranges; - num-lanes = <1>; interrupt-map-mask = <0 0 0 7>; interrupt-map = <0 0 0 1 &pcie_intc1 0>, <0 0 0 2 &pcie_intc1 1>, @@ -245,7 +239,6 @@ Examples for MT7622: #size-cells = <2>; #interrupt-cells = <1>; ranges; - num-lanes = <1>; interrupt-map-mask = <0 0 0 7>; interrupt-map = <0 0 0 1 &pcie_intc0 0>, <0 0 0 2 &pcie_intc0 1>, @@ -264,7 +257,6 @@ Examples for MT7622: #size-cells = <2>; #interrupt-cells = <1>; ranges; - num-lanes = <1>; interrupt-map-mask = <0 0 0 7>; interrupt-map = <0 0 0 1 &pcie_intc1 0>, <0 0 0 2 &pcie_intc1 1>, diff --git a/Documentation/devicetree/bindings/pci/uniphier-pcie.txt b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt new file mode 100644 index 000000000000..1fa2c5906d4d --- /dev/null +++ b/Documentation/devicetree/bindings/pci/uniphier-pcie.txt @@ -0,0 +1,81 @@ +Socionext UniPhier PCIe host controller bindings + +This describes the devicetree bindings for PCIe host controller implemented +on Socionext UniPhier SoCs. + +UniPhier PCIe host controller is based on the Synopsys DesignWare PCI core. +It shares common functions with the PCIe DesignWare core driver and inherits +common properties defined in +Documentation/devicetree/bindings/pci/designware-pcie.txt. + +Required properties: +- compatible: Should be "socionext,uniphier-pcie". +- reg: Specifies offset and length of the register set for the device. + According to the reg-names, appropriate register sets are required. +- reg-names: Must include the following entries: + "dbi" - controller configuration registers + "link" - SoC-specific glue layer registers + "config" - PCIe configuration space +- clocks: A phandle to the clock gate for PCIe glue layer including + the host controller. +- resets: A phandle to the reset line for PCIe glue layer including + the host controller. +- interrupts: A list of interrupt specifiers. According to the + interrupt-names, appropriate interrupts are required. +- interrupt-names: Must include the following entries: + "dma" - DMA interrupt + "msi" - MSI interrupt + +Optional properties: +- phys: A phandle to generic PCIe PHY. According to the phy-names, appropriate + phys are required. +- phy-names: Must be "pcie-phy". + +Required sub-node: +- legacy-interrupt-controller: Specifies interrupt controller for legacy PCI + interrupts. + +Required properties for legacy-interrupt-controller: +- interrupt-controller: identifies the node as an interrupt controller. +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. The value must be 1. +- interrupt-parent: Phandle to the parent interrupt controller. +- interrupts: An interrupt specifier for legacy interrupt. + +Example: + + pcie: pcie@66000000 { + compatible = "socionext,uniphier-pcie", "snps,dw-pcie"; + status = "disabled"; + reg-names = "dbi", "link", "config"; + reg = <0x66000000 0x1000>, <0x66010000 0x10000>, + <0x2fff0000 0x10000>; + #address-cells = <3>; + #size-cells = <2>; + clocks = <&sys_clk 24>; + resets = <&sys_rst 24>; + num-lanes = <1>; + num-viewport = <1>; + bus-range = <0x0 0xff>; + device_type = "pci"; + ranges = + /* downstream I/O */ + <0x81000000 0 0x00000000 0x2ffe0000 0 0x00010000 + /* non-prefetchable memory */ + 0x82000000 0 0x00000000 0x20000000 0 0x0ffe0000>; + #interrupt-cells = <1>; + interrupt-names = "dma", "msi"; + interrupts = <0 224 4>, <0 225 4>; + interrupt-map-mask = <0 0 0 7>; + interrupt-map = <0 0 0 1 &pcie_intc 0>, /* INTA */ + <0 0 0 2 &pcie_intc 1>, /* INTB */ + <0 0 0 3 &pcie_intc 2>, /* INTC */ + <0 0 0 4 &pcie_intc 3>; /* INTD */ + + pcie_intc: legacy-interrupt-controller { + interrupt-controller; + #interrupt-cells = <1>; + interrupt-parent = <&gic>; + interrupts = <0 226 4>; + }; + }; diff --git a/Documentation/devicetree/bindings/perf/nds32v3-pmu.txt b/Documentation/devicetree/bindings/perf/nds32v3-pmu.txt new file mode 100644 index 000000000000..1bd15785b4ae --- /dev/null +++ b/Documentation/devicetree/bindings/perf/nds32v3-pmu.txt @@ -0,0 +1,17 @@ +* NDS32 Performance Monitor Units + +NDS32 core have a PMU for counting cpu and cache events like cache misses. +The NDS32 PMU representation in the device tree should be done as under: + +Required properties: + +- compatible : + "andestech,nds32v3-pmu" + +- interrupts : The interrupt number for NDS32 PMU is 13. + +Example: +pmu{ + compatible = "andestech,nds32v3-pmu"; + interrupts = <13>; +} diff --git a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt index 0aced97d8092..b640845fec67 100644 --- a/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt +++ b/Documentation/devicetree/bindings/phy/brcm-sata-phy.txt @@ -8,6 +8,7 @@ Required properties: "brcm,iproc-nsp-sata-phy" "brcm,phy-sata3" "brcm,iproc-sr-sata-phy" + "brcm,bcm63138-sata-phy" - address-cells: should be 1 - size-cells: should be 0 - reg: register ranges for the PHY PCB interface diff --git a/Documentation/devicetree/bindings/phy/cdns,dphy.txt b/Documentation/devicetree/bindings/phy/cdns,dphy.txt new file mode 100644 index 000000000000..1095bc4e72d9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/cdns,dphy.txt @@ -0,0 +1,20 @@ +Cadence DPHY +============ + +Cadence DPHY block. + +Required properties: +- compatible: should be set to "cdns,dphy". +- reg: physical base address and length of the DPHY registers. +- clocks: DPHY reference clocks. +- clock-names: must contain "psm" and "pll_ref". +- #phy-cells: must be set to 0. + +Example: + dphy0: dphy@fd0e0000{ + compatible = "cdns,dphy"; + reg = <0x0 0xfd0e0000 0x0 0x1000>; + clocks = <&psm_clk>, <&pll_ref_clk>; + clock-names = "psm", "pll_ref"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt new file mode 100644 index 000000000000..a22e853d710c --- /dev/null +++ b/Documentation/devicetree/bindings/phy/fsl,imx8mq-usb-phy.txt @@ -0,0 +1,17 @@ +* Freescale i.MX8MQ USB3 PHY binding + +Required properties: +- compatible: Should be "fsl,imx8mq-usb-phy" +- #phys-cells: must be 0 (see phy-bindings.txt in this directory) +- reg: The base address and length of the registers +- clocks: phandles to the clocks for each clock listed in clock-names +- clock-names: must contain "phy" + +Example: + usb3_phy0: phy@381f0040 { + compatible = "fsl,imx8mq-usb-phy"; + reg = <0x381f0040 0x40>; + clocks = <&clk IMX8MQ_CLK_USB1_PHY_ROOT>; + clock-names = "phy"; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt new file mode 100644 index 000000000000..ad49e5c01334 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-armada38x-comphy.txt @@ -0,0 +1,40 @@ +mvebu armada 38x comphy driver +------------------------------ + +This comphy controller can be found on Marvell Armada 38x. It provides a +number of shared PHYs used by various interfaces (network, sata, usb, +PCIe...). + +Required properties: + +- compatible: should be "marvell,armada-380-comphy" +- reg: should contain the comphy register location and length. +- #address-cells: should be 1. +- #size-cells: should be 0. + +A sub-node is required for each comphy lane provided by the comphy. + +Required properties (child nodes): + +- reg: comphy lane number. +- #phy-cells : from the generic phy bindings, must be 1. Defines the + input port to use for a given comphy lane. + +Example: + + comphy: phy@18300 { + compatible = "marvell,armada-380-comphy"; + reg = <0x18300 0x100>; + #address-cells = <1>; + #size-cells = <0>; + + cpm_comphy0: phy@0 { + reg = <0>; + #phy-cells = <1>; + }; + + cpm_comphy1: phy@1 { + reg = <1>; + #phy-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-dp.txt b/Documentation/devicetree/bindings/phy/phy-cadence-dp.txt new file mode 100644 index 000000000000..7f49fd54ebc1 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-cadence-dp.txt @@ -0,0 +1,30 @@ +Cadence MHDP DisplayPort SD0801 PHY binding +=========================================== + +This binding describes the Cadence SD0801 PHY hardware included with +the Cadence MHDP DisplayPort controller. + +------------------------------------------------------------------------------- +Required properties (controller (parent) node): +- compatible : Should be "cdns,dp-phy" +- reg : Defines the following sets of registers in the parent + mhdp device: + - Offset of the DPTX PHY configuration registers + - Offset of the SD0801 PHY configuration registers +- #phy-cells : from the generic PHY bindings, must be 0. + +Optional properties: +- num_lanes : Number of DisplayPort lanes to use (1, 2 or 4) +- max_bit_rate : Maximum DisplayPort link bit rate to use, in Mbps (2160, + 2430, 2700, 3240, 4320, 5400 or 8100) +------------------------------------------------------------------------------- + +Example: + dp_phy: phy@f0fb030a00 { + compatible = "cdns,dp-phy"; + reg = <0xf0 0xfb030a00 0x0 0x00000040>, + <0xf0 0xfb500000 0x0 0x00100000>; + num_lanes = <4>; + max_bit_rate = <8100>; + #phy-cells = <0>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt new file mode 100644 index 000000000000..6e1b47bfce43 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-cadence-sierra.txt @@ -0,0 +1,67 @@ +Cadence Sierra PHY +----------------------- + +Required properties: +- compatible: cdns,sierra-phy-t0 +- clocks: Must contain an entry in clock-names. + See ../clocks/clock-bindings.txt for details. +- clock-names: Must be "phy_clk" +- resets: Must contain an entry for each in reset-names. + See ../reset/reset.txt for details. +- reset-names: Must include "sierra_reset" and "sierra_apb". + "sierra_reset" must control the reset line to the PHY. + "sierra_apb" must control the reset line to the APB PHY + interface. +- reg: register range for the PHY. +- #address-cells: Must be 1 +- #size-cells: Must be 0 + +Optional properties: +- cdns,autoconf: A boolean property whose presence indicates that the + PHY registers will be configured by hardware. If not + present, all sub-node optional properties must be + provided. + +Sub-nodes: + Each group of PHY lanes with a single master lane should be represented as + a sub-node. Note that the actual configuration of each lane is determined by + hardware strapping, and must match the configuration specified here. + +Sub-node required properties: +- #phy-cells: Generic PHY binding; must be 0. +- reg: The master lane number. This is the lowest numbered lane + in the lane group. +- resets: Must contain one entry which controls the reset line for the + master lane of the sub-node. + See ../reset/reset.txt for details. + +Sub-node optional properties: +- cdns,num-lanes: Number of lanes in this group. From 1 to 4. The + group is made up of consecutive lanes. +- cdns,phy-type: Can be PHY_TYPE_PCIE or PHY_TYPE_USB3, depending on + configuration of lanes. + +Example: + pcie_phy4: pcie-phy@fd240000 { + compatible = "cdns,sierra-phy-t0"; + reg = <0x0 0xfd240000 0x0 0x40000>; + resets = <&phyrst 0>, <&phyrst 1>; + reset-names = "sierra_reset", "sierra_apb"; + clocks = <&phyclock>; + clock-names = "phy_clk"; + #address-cells = <1>; + #size-cells = <0>; + pcie0_phy0: pcie-phy@0 { + reg = <0>; + resets = <&phyrst 2>; + cdns,num-lanes = <2>; + #phy-cells = <0>; + cdns,phy-type = <PHY_TYPE_PCIE>; + }; + pcie0_phy1: pcie-phy@2 { + reg = <2>; + resets = <&phyrst 4>; + cdns,num-lanes = <1>; + #phy-cells = <0>; + cdns,phy-type = <PHY_TYPE_PCIE>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt index bfcf80341657..cf2cd86db267 100644 --- a/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt +++ b/Documentation/devicetree/bindings/phy/phy-mvebu-comphy.txt @@ -1,16 +1,27 @@ -mvebu comphy driver -------------------- +MVEBU comphy drivers +-------------------- -A comphy controller can be found on Marvell Armada 7k/8k on the CP110. It -provides a number of shared PHYs used by various interfaces (network, sata, -usb, PCIe...). +COMPHY controllers can be found on the following Marvell MVEBU SoCs: +* Armada 7k/8k (on the CP110) +* Armada 3700 +It provides a number of shared PHYs used by various interfaces (network, SATA, +USB, PCIe...). Required properties: -- compatible: should be "marvell,comphy-cp110" -- reg: should contain the comphy register location and length. -- marvell,system-controller: should contain a phandle to the - system controller node. +- compatible: should be one of: + * "marvell,comphy-cp110" for Armada 7k/8k + * "marvell,comphy-a3700" for Armada 3700 +- reg: should contain the COMPHY register(s) location(s) and length(s). + * 1 entry for Armada 7k/8k + * 4 entries for Armada 3700 along with the corresponding reg-names + properties, memory areas are: + * Generic COMPHY registers + * Lane 1 (PCIe/GbE) + * Lane 0 (USB3/GbE) + * Lane 2 (SATA/USB3) +- marvell,system-controller: should contain a phandle to the system + controller node (only for Armada 7k/8k) - #address-cells: should be 1. - #size-cells: should be 0. @@ -18,11 +29,11 @@ A sub-node is required for each comphy lane provided by the comphy. Required properties (child nodes): -- reg: comphy lane number. -- #phy-cells : from the generic phy bindings, must be 1. Defines the +- reg: COMPHY lane number. +- #phy-cells : from the generic PHY bindings, must be 1. Defines the input port to use for a given comphy lane. -Example: +Examples: cpm_comphy: phy@120000 { compatible = "marvell,comphy-cp110"; @@ -41,3 +52,33 @@ Example: #phy-cells = <1>; }; }; + + comphy: phy@18300 { + compatible = "marvell,comphy-a3700"; + reg = <0x18300 0x300>, + <0x1F000 0x400>, + <0x5C000 0x400>, + <0xe0178 0x8>; + reg-names = "comphy", + "lane1_pcie_gbe", + "lane0_usb3_gbe", + "lane2_sata_usb3"; + #address-cells = <1>; + #size-cells = <0>; + + + comphy0: phy@0 { + reg = <0>; + #phy-cells = <1>; + }; + + comphy1: phy@1 { + reg = <1>; + #phy-cells = <1>; + }; + + comphy2: phy@2 { + reg = <2>; + #phy-cells = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt b/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt new file mode 100644 index 000000000000..aa99ceec73b0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-mvebu-utmi.txt @@ -0,0 +1,38 @@ +MVEBU A3700 UTMI PHY +-------------------- + +USB2 UTMI+ PHY controllers can be found on the following Marvell MVEBU SoCs: +* Armada 3700 + +On Armada 3700, there are two USB controllers, one is compatible with the USB2 +and USB3 specifications and supports OTG. The other one is USB2 compliant and +only supports host mode. Both of these controllers come with a slightly +different UTMI PHY. + +Required Properties: + +- compatible: Should be one of: + * "marvell,a3700-utmi-host-phy" for the PHY connected to + the USB2 host-only controller. + * "marvell,a3700-utmi-otg-phy" for the PHY connected to + the USB3 and USB2 OTG capable controller. +- reg: PHY IP register range. +- marvell,usb-misc-reg: handle on the "USB miscellaneous registers" shared + region covering registers related to both the host + controller and the PHY. +- #phy-cells: Standard property (Documentation: phy-bindings.txt) Should be 0. + + +Example: + + usb2_utmi_host_phy: phy@5f000 { + compatible = "marvell,armada-3700-utmi-host-phy"; + reg = <0x5f000 0x800>; + marvell,usb-misc-reg = <&usb2_syscon>; + #phy-cells = <0>; + }; + + usb2_syscon: system-controller@5f800 { + compatible = "marvell,armada-3700-usb2-host-misc", "syscon"; + reg = <0x5f800 0x800>; + }; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-hdmi.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-hdmi.txt new file mode 100644 index 000000000000..710cccd5ee56 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-hdmi.txt @@ -0,0 +1,43 @@ +ROCKCHIP HDMI PHY WITH INNO IP BLOCK + +Required properties: + - compatible : should be one of the listed compatibles: + * "rockchip,rk3228-hdmi-phy", + * "rockchip,rk3328-hdmi-phy"; + - reg : Address and length of the hdmi phy control register set + - clocks : phandle + clock specifier for the phy clocks + - clock-names : string, clock name, must contain "sysclk" for system + control and register configuration, "refoclk" for crystal- + oscillator reference PLL clock input and "refpclk" for pclk- + based refeference PLL clock input. + - #clock-cells: should be 0. + - clock-output-names : shall be the name for the output clock. + - interrupts : phandle + interrupt specified for the hdmiphy interrupt + - #phy-cells : must be 0. See ./phy-bindings.txt for details. + +Optional properties for rk3328-hdmi-phy: + - nvmem-cells = phandle + nvmem specifier for the cpu-version efuse + - nvmem-cell-names : "cpu-version" to read the chip version, required + for adjustment to some frequency settings + +Example: + hdmi_phy: hdmi-phy@12030000 { + compatible = "rockchip,rk3228-hdmi-phy"; + reg = <0x12030000 0x10000>; + #phy-cells = <0>; + clocks = <&cru PCLK_HDMI_PHY>, <&xin24m>, <&cru DCLK_HDMIPHY>; + clock-names = "sysclk", "refoclk", "refpclk"; + #clock-cells = <0>; + clock-output-names = "hdmi_phy"; + status = "disabled"; + }; + +Then the PHY can be used in other nodes such as: + + hdmi: hdmi@200a0000 { + compatible = "rockchip,rk3228-dw-hdmi"; + ... + phys = <&hdmi_phy>; + phy-names = "hdmi"; + ... + }; diff --git a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt index 074a7b3b0425..00639baae74a 100644 --- a/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt +++ b/Documentation/devicetree/bindings/phy/phy-rockchip-inno-usb2.txt @@ -23,6 +23,8 @@ Optional properties: register files". When set driver will request its phandle as one companion-grf for some special SoCs (e.g RV1108). + - extcon : phandle to the extcon device providing the cable state for + the otg phy. Required nodes : a sub-node is required for each port the phy provides. The sub-node name is used to identify host or otg port, diff --git a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt index 0c7629e88bf3..5d181fc3cc18 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qmp-phy.txt @@ -9,22 +9,24 @@ Required properties: "qcom,ipq8074-qmp-pcie-phy" for PCIe phy on IPQ8074 "qcom,msm8996-qmp-pcie-phy" for 14nm PCIe phy on msm8996, "qcom,msm8996-qmp-usb3-phy" for 14nm USB3 phy on msm8996, + "qcom,msm8998-qmp-usb3-phy" for USB3 QMP V3 phy on msm8998, + "qcom,msm8998-qmp-ufs-phy" for UFS QMP phy on msm8998, "qcom,sdm845-qmp-usb3-phy" for USB3 QMP V3 phy on sdm845, - "qcom,sdm845-qmp-usb3-uni-phy" for USB3 QMP V3 UNI phy on sdm845. - - - reg: - - For "qcom,sdm845-qmp-usb3-phy": - - index 0: address and length of register set for PHY's common serdes - block. - - named register "dp_com" (using reg-names): address and length of the - DP_COM control block. - - For all others: - - offset and length of register set for PHY's common serdes block. - - - #clock-cells: must be 1 - - Phy pll outputs a bunch of clocks for Tx, Rx and Pipe - interface (for pipe based PHYs). These clock are then gate-controlled - by gcc. + "qcom,sdm845-qmp-usb3-uni-phy" for USB3 QMP V3 UNI phy on sdm845, + "qcom,sdm845-qmp-ufs-phy" for UFS QMP phy on sdm845. + +- reg: + - index 0: address and length of register set for PHY's common + serdes block. + - index 1: address and length of the DP_COM control block (for + "qcom,sdm845-qmp-usb3-phy" only). + +- reg-names: + - For "qcom,sdm845-qmp-usb3-phy": + - Should be: "reg-base", "dp_com" + - For all others: + - The reg-names property shouldn't be defined. + - #address-cells: must be 1 - #size-cells: must be 1 - ranges: must be present @@ -35,24 +37,44 @@ Required properties: "aux" for phy aux clock, "ref" for 19.2 MHz ref clk, "com_aux" for phy common block aux clock, + "ref_aux" for phy reference aux clock, + + For "qcom,ipq8074-qmp-pcie-phy": no clocks are listed. For "qcom,msm8996-qmp-pcie-phy" must contain: "aux", "cfg_ahb", "ref". For "qcom,msm8996-qmp-usb3-phy" must contain: "aux", "cfg_ahb", "ref". - For "qcom,qmp-v3-usb3-phy" must contain: + For "qcom,msm8998-qmp-usb3-phy" must contain: + "aux", "cfg_ahb", "ref". + For "qcom,msm8998-qmp-ufs-phy" must contain: + "ref", "ref_aux". + For "qcom,sdm845-qmp-usb3-phy" must contain: + "aux", "cfg_ahb", "ref", "com_aux". + For "qcom,sdm845-qmp-usb3-uni-phy" must contain: "aux", "cfg_ahb", "ref", "com_aux". + For "qcom,sdm845-qmp-ufs-phy" must contain: + "ref", "ref_aux". - resets: a list of phandles and reset controller specifier pairs, one for each entry in reset-names. - reset-names: "phy" for reset of phy block, "common" for phy common block reset, - "cfg" for phy's ahb cfg block reset (Optional). + "cfg" for phy's ahb cfg block reset. + + For "qcom,ipq8074-qmp-pcie-phy" must contain: + "phy", "common". For "qcom,msm8996-qmp-pcie-phy" must contain: - "phy", "common", "cfg". + "phy", "common", "cfg". For "qcom,msm8996-qmp-usb3-phy" must contain - "phy", "common". - For "qcom,ipq8074-qmp-pcie-phy" must contain: - "phy", "common". + "phy", "common". + For "qcom,msm8998-qmp-usb3-phy" must contain + "phy", "common". + For "qcom,msm8998-qmp-ufs-phy": no resets are listed. + For "qcom,sdm845-qmp-usb3-phy" must contain: + "phy", "common". + For "qcom,sdm845-qmp-usb3-uni-phy" must contain: + "phy", "common". + For "qcom,sdm845-qmp-ufs-phy": no resets are listed. - vdda-phy-supply: Phandle to a regulator supply to PHY core block. - vdda-pll-supply: Phandle to 1.8V regulator supply to PHY refclk pll block. @@ -65,37 +87,45 @@ Required nodes: - Each device node of QMP phy is required to have as many child nodes as the number of lanes the PHY has. -Required properties for child node: +Required properties for child nodes of PCIe PHYs (one child per lane): - reg: list of offset and length pairs of register sets for PHY blocks - - - index 0: tx - - index 1: rx - - index 2: pcs - - index 3: pcs_misc (optional) + tx, rx, pcs, and pcs_misc (optional). + - #phy-cells: must be 0 +Required properties for a single "lanes" child node of non-PCIe PHYs: + - reg: list of offset and length pairs of register sets for PHY blocks + For 1-lane devices: + tx, rx, pcs, and (optionally) pcs_misc + For 2-lane devices: + tx0, rx0, pcs, tx1, rx1, and (optionally) pcs_misc - #phy-cells: must be 0 +Required properties for child node of PCIe and USB3 qmp phys: - clocks: a list of phandles and clock-specifier pairs, one for each entry in clock-names. - - clock-names: Must contain following for pcie and usb qmp phys: + - clock-names: Must contain following: "pipe<lane-number>" for pipe clock specific to each lane. - clock-output-names: Name of the PHY clock that will be the parent for the above pipe clock. - For "qcom,ipq8074-qmp-pcie-phy": - "pcie20_phy0_pipe_clk" Pipe Clock parent (or) "pcie20_phy1_pipe_clk" + - #clock-cells: must be 0 + - Phy pll outputs pipe clocks for pipe based PHYs. These clocks are then + gate-controlled by the gcc. +Required properties for child node of PHYs with lane reset, AKA: + "qcom,msm8996-qmp-pcie-phy" - resets: a list of phandles and reset controller specifier pairs, one for each entry in reset-names. - - reset-names: Must contain following for pcie qmp phys: + - reset-names: Must contain following: "lane<lane-number>" for reset specific to each lane. Example: phy@34000 { compatible = "qcom,msm8996-qmp-pcie-phy"; reg = <0x34000 0x488>; - #clock-cells = <1>; #address-cells = <1>; #size-cells = <1>; ranges; @@ -117,6 +147,7 @@ Example: reg = <0x35000 0x130>, <0x35200 0x200>, <0x35400 0x1dc>; + #clock-cells = <0>; #phy-cells = <0>; clocks = <&gcc GCC_PCIE_0_PIPE_CLK>; @@ -130,3 +161,54 @@ Example: ... ... }; + + phy@88eb000 { + compatible = "qcom,sdm845-qmp-usb3-uni-phy"; + reg = <0x88eb000 0x18c>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + + clocks = <&gcc GCC_USB3_SEC_PHY_AUX_CLK>, + <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, + <&gcc GCC_USB3_SEC_CLKREF_CLK>, + <&gcc GCC_USB3_SEC_PHY_COM_AUX_CLK>; + clock-names = "aux", "cfg_ahb", "ref", "com_aux"; + + resets = <&gcc GCC_USB3PHY_PHY_SEC_BCR>, + <&gcc GCC_USB3_PHY_SEC_BCR>; + reset-names = "phy", "common"; + + lane@88eb200 { + reg = <0x88eb200 0x128>, + <0x88eb400 0x1fc>, + <0x88eb800 0x218>, + <0x88eb600 0x70>; + #clock-cells = <0>; + #phy-cells = <0>; + clocks = <&gcc GCC_USB3_SEC_PHY_PIPE_CLK>; + clock-names = "pipe0"; + clock-output-names = "usb3_uni_phy_pipe_clk_src"; + }; + }; + + phy@1d87000 { + compatible = "qcom,sdm845-qmp-ufs-phy"; + reg = <0x1d87000 0x18c>; + #address-cells = <1>; + #size-cells = <1>; + ranges; + clock-names = "ref", + "ref_aux"; + clocks = <&gcc GCC_UFS_MEM_CLKREF_CLK>, + <&gcc GCC_UFS_PHY_PHY_AUX_CLK>; + + lanes@1d87400 { + reg = <0x1d87400 0x108>, + <0x1d87600 0x1e0>, + <0x1d87c00 0x1dc>, + <0x1d87800 0x108>, + <0x1d87a00 0x1e0>; + #phy-cells = <0>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt index 03025d97998b..fe29f9e0af6d 100644 --- a/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt +++ b/Documentation/devicetree/bindings/phy/qcom-qusb2-phy.txt @@ -6,6 +6,7 @@ QUSB2 controller supports LS/FS/HS usb connectivity on Qualcomm chipsets. Required properties: - compatible: compatible list, contains "qcom,msm8996-qusb2-phy" for 14nm PHY on msm8996, + "qcom,msm8998-qusb2-phy" for 10nm PHY on msm8998, "qcom,sdm845-qusb2-phy" for 10nm PHY on sdm845. - reg: offset and length of the PHY register set. diff --git a/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt index eeb9e1874ea6..4f0879a0ca12 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen2-phy.txt @@ -5,6 +5,7 @@ This file provides information on what the device node for the R-Car generation Required properties: - compatible: "renesas,usb-phy-r8a7743" if the device is a part of R8A7743 SoC. + "renesas,usb-phy-r8a7744" if the device is a part of R8A7744 SoC. "renesas,usb-phy-r8a7745" if the device is a part of R8A7745 SoC. "renesas,usb-phy-r8a7790" if the device is a part of R8A7790 SoC. "renesas,usb-phy-r8a7791" if the device is a part of R8A7791 SoC. diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt index fb4a204da2bf..ad9c290d8f15 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb2.txt @@ -1,10 +1,14 @@ * Renesas R-Car generation 3 USB 2.0 PHY This file provides information on what the device node for the R-Car generation -3 USB 2.0 PHY contains. +3 and RZ/G2 USB 2.0 PHY contain. Required properties: -- compatible: "renesas,usb2-phy-r8a7795" if the device is a part of an R8A7795 +- compatible: "renesas,usb2-phy-r8a774a1" if the device is a part of an R8A774A1 + SoC. + "renesas,usb2-phy-r8a774c0" if the device is a part of an R8A774C0 + SoC. + "renesas,usb2-phy-r8a7795" if the device is a part of an R8A7795 SoC. "renesas,usb2-phy-r8a7796" if the device is a part of an R8A7796 SoC. @@ -14,7 +18,8 @@ Required properties: R8A77990 SoC. "renesas,usb2-phy-r8a77995" if the device is a part of an R8A77995 SoC. - "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3 compatible device. + "renesas,rcar-gen3-usb2-phy" for a generic R-Car Gen3 or RZ/G2 + compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first @@ -31,6 +36,8 @@ channel as USB OTG: - interrupts: interrupt specifier for the PHY. - vbus-supply: Phandle to a regulator that provides power to the VBUS. This regulator will be managed during the PHY power on/off sequence. +- renesas,no-otg-pins: boolean, specify when a board does not provide proper + otg pins. Example (R-Car H3): diff --git a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt index 47dd296ecead..9d9826609c2f 100644 --- a/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt +++ b/Documentation/devicetree/bindings/phy/rcar-gen3-phy-usb3.txt @@ -1,20 +1,22 @@ * Renesas R-Car generation 3 USB 3.0 PHY This file provides information on what the device node for the R-Car generation -3 USB 3.0 PHY contains. +3 and RZ/G2 USB 3.0 PHY contain. If you want to enable spread spectrum clock (ssc), you should use USB_EXTAL instead of USB3_CLK. However, if you don't want to these features, you don't need this driver. Required properties: -- compatible: "renesas,r8a7795-usb3-phy" if the device is a part of an R8A7795 +- compatible: "renesas,r8a774a1-usb3-phy" if the device is a part of an R8A774A1 + SoC. + "renesas,r8a7795-usb3-phy" if the device is a part of an R8A7795 SoC. "renesas,r8a7796-usb3-phy" if the device is a part of an R8A7796 SoC. "renesas,r8a77965-usb3-phy" if the device is a part of an R8A77965 SoC. - "renesas,rcar-gen3-usb3-phy" for a generic R-Car Gen3 compatible - device. + "renesas,rcar-gen3-usb3-phy" for a generic R-Car Gen3 or RZ/G2 + compatible device. When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first diff --git a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt index 07ca4ec4a745..f2e120af17f0 100644 --- a/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt +++ b/Documentation/devicetree/bindings/phy/sun4i-usb-phy.txt @@ -14,13 +14,14 @@ Required properties: * allwinner,sun8i-r40-usb-phy * allwinner,sun8i-v3s-usb-phy * allwinner,sun50i-a64-usb-phy + * allwinner,sun50i-h6-usb-phy - reg : a list of offset + length pairs - reg-names : * "phy_ctrl" - * "pmu0" for H3, V3s and A64 + * "pmu0" for H3, V3s, A64 or H6 * "pmu1" * "pmu2" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 - * "pmu3" for sun8i-h3 + * "pmu3" for sun8i-h3 or sun50i-h6 - #phy-cells : from the generic phy bindings, must be 1 - clocks : phandle + clock specifier for the phy clocks - clock-names : @@ -29,12 +30,13 @@ Required properties: * "usb0_phy", "usb1_phy" for sun8i * "usb0_phy", "usb1_phy", "usb2_phy" and "usb2_hsic_12M" for sun8i-a83t * "usb0_phy", "usb1_phy", "usb2_phy" and "usb3_phy" for sun8i-h3 + * "usb0_phy" and "usb3_phy" for sun50i-h6 - resets : a list of phandle + reset specifier pairs - reset-names : * "usb0_reset" * "usb1_reset" * "usb2_reset" for sun4i, sun6i, sun7i, sun8i-a83t or sun8i-h3 - * "usb3_reset" for sun8i-h3 + * "usb3_reset" for sun8i-h3 and sun50i-h6 Optional properties: - usb0_id_det-gpios : gpio phandle for reading the otg id pin value diff --git a/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt b/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt new file mode 100644 index 000000000000..50ce9ae0f7a5 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/ti-phy-gmii-sel.txt @@ -0,0 +1,68 @@ +CPSW Port's Interface Mode Selection PHY Tree Bindings +----------------------------------------------- + +TI am335x/am437x/dra7(am5)/dm814x CPSW3G Ethernet Subsystem supports +two 10/100/1000 Ethernet ports with selectable G/MII, RMII, and RGMII interfaces. +The interface mode is selected by configuring the MII mode selection register(s) +(GMII_SEL) in the System Control Module chapter (SCM). GMII_SEL register(s) and +bit fields placement in SCM are different between SoCs while fields meaning +is the same. + +--------------+ + +-------------------------------+ |SCM | + | CPSW | | +---------+ | + | +--------------------------------+gmii_sel | | + | | | | +---------+ | + | +----v---+ +--------+ | +--------------+ + | |Port 1..<--+-->GMII/MII<-------> + | | | | | | | + | +--------+ | +--------+ | + | | | + | | +--------+ | + | | | RMII <-------> + | +--> | | + | | +--------+ | + | | | + | | +--------+ | + | | | RGMII <-------> + | +--> | | + | +--------+ | + +-------------------------------+ + +CPSW Port's Interface Mode Selection PHY describes MII interface mode between +CPSW Port and Ethernet PHY which depends on Eth PHY and board configuration. + +CPSW Port's Interface Mode Selection PHY device should defined as child device +of SCM node (scm_conf) and can be attached to each CPSW port node using standard +PHY bindings (See phy/phy-bindings.txt). + +Required properties: +- compatible : Should be "ti,am3352-phy-gmii-sel" for am335x platform + "ti,dra7xx-phy-gmii-sel" for dra7xx/am57xx platform + "ti,am43xx-phy-gmii-sel" for am43xx platform + "ti,dm814-phy-gmii-sel" for dm814x platform +- reg : Address and length of the register set for the device +- #phy-cells : must be 2. + cell 1 - CPSW port number (starting from 1) + cell 2 - RMII refclk mode + +Examples: + phy_gmii_sel: phy-gmii-sel { + compatible = "ti,am3352-phy-gmii-sel"; + reg = <0x650 0x4>; + #phy-cells = <2>; + }; + + mac: ethernet@4a100000 { + compatible = "ti,am335x-cpsw","ti,cpsw"; + ... + + cpsw_emac0: slave@4a100200 { + ... + phys = <&phy_gmii_sel 1 1>; + }; + + cpsw_emac1: slave@4a100300 { + ... + phys = <&phy_gmii_sel 2 1>; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/ti-phy.txt b/Documentation/devicetree/bindings/phy/ti-phy.txt index 57dfda8a7a1d..8f93c3b694a7 100644 --- a/Documentation/devicetree/bindings/phy/ti-phy.txt +++ b/Documentation/devicetree/bindings/phy/ti-phy.txt @@ -35,6 +35,7 @@ Required properties: DRA7x Should be "ti,dra7x-usb2-phy2" for the 2nd instance of USB2 PHY in DRA7x + Should be "ti,am654-usb2" for the USB2 PHYs on AM654. - reg : Address and length of the register set for the device. - #phy-cells: determine the number of cells that should be given in the phandle while referencing this phy. diff --git a/Documentation/devicetree/bindings/phy/uniphier-pcie-phy.txt b/Documentation/devicetree/bindings/phy/uniphier-pcie-phy.txt new file mode 100644 index 000000000000..1889d3b89d68 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/uniphier-pcie-phy.txt @@ -0,0 +1,31 @@ +Socionext UniPhier PCIe PHY bindings + +This describes the devicetree bindings for PHY interface built into +PCIe controller implemented on Socionext UniPhier SoCs. + +Required properties: +- compatible: Should contain one of the following: + "socionext,uniphier-ld20-pcie-phy" - for LD20 PHY + "socionext,uniphier-pxs3-pcie-phy" - for PXs3 PHY +- reg: Specifies offset and length of the register set for the device. +- #phy-cells: Must be zero. +- clocks: A phandle to the clock gate for PCIe glue layer including + this phy. +- resets: A phandle to the reset line for PCIe glue layer including + this phy. + +Optional properties: +- socionext,syscon: A phandle to system control to set configurations + for phy. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties. + +Example: + pcie_phy: phy@66038000 { + compatible = "socionext,uniphier-ld20-pcie-phy"; + reg = <0x66038000 0x4000>; + #phy-cells = <0>; + clocks = <&sys_clk 24>; + resets = <&sys_rst 24>; + socionext,syscon = <&soc_glue>; + }; diff --git a/Documentation/devicetree/bindings/phy/uniphier-usb2-phy.txt b/Documentation/devicetree/bindings/phy/uniphier-usb2-phy.txt new file mode 100644 index 000000000000..b43b28250cc0 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/uniphier-usb2-phy.txt @@ -0,0 +1,45 @@ +Socionext UniPhier USB2 PHY + +This describes the devicetree bindings for PHY interface built into +USB2 controller implemented on Socionext UniPhier SoCs. + +Pro4 SoC has both USB2 and USB3 host controllers, however, this USB3 +controller doesn't include its own High-Speed PHY. This needs to specify +USB2 PHY instead of USB3 HS-PHY. + +Required properties: +- compatible: Should contain one of the following: + "socionext,uniphier-pro4-usb2-phy" - for Pro4 SoC + "socionext,uniphier-ld11-usb2-phy" - for LD11 SoC + +Sub-nodes: +Each PHY should be represented as a sub-node. + +Sub-nodes required properties: +- #phy-cells: Should be 0. +- reg: The number of the PHY. + +Sub-nodes optional properties: +- vbus-supply: A phandle to the regulator for USB VBUS. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties. + +Example: + soc-glue@5f800000 { + ... + usb-phy { + compatible = "socionext,uniphier-ld11-usb2-phy"; + usb_phy0: phy@0 { + reg = <0>; + #phy-cells = <0>; + }; + ... + }; + }; + + usb@5a800100 { + compatible = "socionext,uniphier-ehci", "generic-ehci"; + ... + phy-names = "usb"; + phys = <&usb_phy0>; + }; diff --git a/Documentation/devicetree/bindings/phy/uniphier-usb3-hsphy.txt b/Documentation/devicetree/bindings/phy/uniphier-usb3-hsphy.txt new file mode 100644 index 000000000000..e8d8086a7ae9 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/uniphier-usb3-hsphy.txt @@ -0,0 +1,69 @@ +Socionext UniPhier USB3 High-Speed (HS) PHY + +This describes the devicetree bindings for PHY interfaces built into +USB3 controller implemented on Socionext UniPhier SoCs. +Although the controller includes High-Speed PHY and Super-Speed PHY, +this describes about High-Speed PHY. + +Required properties: +- compatible: Should contain one of the following: + "socionext,uniphier-pro4-usb3-hsphy" - for Pro4 SoC + "socionext,uniphier-pxs2-usb3-hsphy" - for PXs2 SoC + "socionext,uniphier-ld20-usb3-hsphy" - for LD20 SoC + "socionext,uniphier-pxs3-usb3-hsphy" - for PXs3 SoC +- reg: Specifies offset and length of the register set for the device. +- #phy-cells: Should be 0. +- clocks: A list of phandles to the clock gate for USB3 glue layer. + According to the clock-names, appropriate clocks are required. +- clock-names: Should contain the following: + "gio", "link" - for Pro4 SoC + "phy", "phy-ext", "link" - for PXs3 SoC, "phy-ext" is optional. + "phy", "link" - for others +- resets: A list of phandles to the reset control for USB3 glue layer. + According to the reset-names, appropriate resets are required. +- reset-names: Should contain the following: + "gio", "link" - for Pro4 SoC + "phy", "link" - for others + +Optional properties: +- vbus-supply: A phandle to the regulator for USB VBUS. +- nvmem-cells: Phandles to nvmem cell that contains the trimming data. + Available only for HS-PHY implemented on LD20 and PXs3, and + if unspecified, default value is used. +- nvmem-cell-names: Should be the following names, which correspond to + each nvmem-cells. + All of the 3 parameters associated with the following names are + required for each port, if any one is omitted, the trimming data + of the port will not be set at all. + "rterm", "sel_t", "hs_i" - Each cell name for phy parameters + +Refer to phy/phy-bindings.txt for the generic PHY binding properties. + +Example: + + usb-glue@65b00000 { + compatible = "socionext,uniphier-ld20-dwc3-glue", + "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65b00000 0x400>; + + usb_vbus0: regulator { + ... + }; + + usb_hsphy0: hs-phy@200 { + compatible = "socionext,uniphier-ld20-usb3-hsphy"; + reg = <0x200 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 16>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 16>; + vbus-supply = <&usb_vbus0>; + nvmem-cell-names = "rterm", "sel_t", "hs_i"; + nvmem-cells = <&usb_rterm0>, <&usb_sel_t0>, + <&usb_hs_i0>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/phy/uniphier-usb3-ssphy.txt b/Documentation/devicetree/bindings/phy/uniphier-usb3-ssphy.txt new file mode 100644 index 000000000000..490b815445e8 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/uniphier-usb3-ssphy.txt @@ -0,0 +1,57 @@ +Socionext UniPhier USB3 Super-Speed (SS) PHY + +This describes the devicetree bindings for PHY interfaces built into +USB3 controller implemented on Socionext UniPhier SoCs. +Although the controller includes High-Speed PHY and Super-Speed PHY, +this describes about Super-Speed PHY. + +Required properties: +- compatible: Should contain one of the following: + "socionext,uniphier-pro4-usb3-ssphy" - for Pro4 SoC + "socionext,uniphier-pxs2-usb3-ssphy" - for PXs2 SoC + "socionext,uniphier-ld20-usb3-ssphy" - for LD20 SoC + "socionext,uniphier-pxs3-usb3-ssphy" - for PXs3 SoC +- reg: Specifies offset and length of the register set for the device. +- #phy-cells: Should be 0. +- clocks: A list of phandles to the clock gate for USB3 glue layer. + According to the clock-names, appropriate clocks are required. +- clock-names: + "gio", "link" - for Pro4 SoC + "phy", "phy-ext", "link" - for PXs3 SoC, "phy-ext" is optional. + "phy", "link" - for others +- resets: A list of phandles to the reset control for USB3 glue layer. + According to the reset-names, appropriate resets are required. +- reset-names: + "gio", "link" - for Pro4 SoC + "phy", "link" - for others + +Optional properties: +- vbus-supply: A phandle to the regulator for USB VBUS. + +Refer to phy/phy-bindings.txt for the generic PHY binding properties. + +Example: + + usb-glue@65b00000 { + compatible = "socionext,uniphier-ld20-dwc3-glue", + "simple-mfd"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x65b00000 0x400>; + + usb_vbus0: regulator { + ... + }; + + usb_ssphy0: ss-phy@300 { + compatible = "socionext,uniphier-ld20-usb3-ssphy"; + reg = <0x300 0x10>; + #phy-cells = <0>; + clock-names = "link", "phy"; + clocks = <&sys_clk 14>, <&sys_clk 16>; + reset-names = "link", "phy"; + resets = <&sys_rst 14>, <&sys_rst 16>; + vbus-supply = <&usb_vbus0>; + }; + ... + }; diff --git a/Documentation/devicetree/bindings/pinctrl/actions,s700-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/actions,s700-pinctrl.txt new file mode 100644 index 000000000000..d13ff82f8518 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/actions,s700-pinctrl.txt @@ -0,0 +1,170 @@ +Actions Semi S700 Pin Controller + +This binding describes the pin controller found in the S700 SoC. + +Required Properties: + +- compatible: Should be "actions,s700-pinctrl" +- reg: Should contain the register base address and size of + the pin controller. +- clocks: phandle of the clock feeding the pin controller +- gpio-controller: Marks the device node as a GPIO controller. +- gpio-ranges: Specifies the mapping between gpio controller and + pin-controller pins. +- #gpio-cells: Should be two. The first cell is the gpio pin number + and the second cell is used for optional parameters. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Specifies the number of cells needed to encode an + interrupt. Shall be set to 2. The first cell + defines the interrupt number, the second encodes + the trigger flags described in + bindings/interrupt-controller/interrupts.txt +- interrupts: The interrupt outputs from the controller. There is one GPIO + interrupt per GPIO bank. The number of interrupts listed depends + on the number of GPIO banks on the SoC. The interrupts must be + ordered by bank, starting with bank 0. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +The pin configuration nodes act as a container for an arbitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those group(s), and various pin configuration +parameters, such as pull-up, drive strength, etc. + +PIN CONFIGURATION NODES: + +The name of each subnode is not important; all subnodes should be enumerated +and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +Pinmux functions are available only for the pin groups while pinconf +parameters are available for both pin groups and individual pins. + +The following generic properties as defined in pinctrl-bindings.txt are valid +to specify in a pin configuration subnode: + +Required Properties: + +- pins: An array of strings, each string containing the name of a pin. + These pins are used for selecting the pull control and schmitt + trigger parameters. The following are the list of pins + available: + + eth_txd0, eth_txd1, eth_txd2, eth_txd3, eth_txen, eth_rxer, + eth_crs_dv, eth_rxd1, eth_rxd0, eth_rxd2, eth_rxd3, eth_ref_clk, + eth_mdc, eth_mdio, sirq0, sirq1, sirq2, i2s_d0, i2s_bclk0, + i2s_lrclk0, i2s_mclk0, i2s_d1, i2s_bclk1, i2s_lrclk1, i2s_mclk1, + pcm1_in, pcm1_clk, pcm1_sync, pcm1_out, ks_in0, ks_in1, ks_in2, + ks_in3, ks_out0, ks_out1, ks_out2, lvds_oep, lvds_oen, lvds_odp, + lvds_odn, lvds_ocp, lvds_ocn, lvds_obp, lvds_obn, lvds_oap, + lvds_oan, lvds_eep, lvds_een, lvds_edp, lvds_edn, lvds_ecp, + lvds_ecn, lvds_ebp, lvds_ebn, lvds_eap, lvds_ean, lcd0_d18, + lcd0_d2, dsi_dp3, dsi_dn3, dsi_dp1, dsi_dn1, dsi_cp, dsi_cn, + dsi_dp0, dsi_dn0, dsi_dp2, dsi_dn2, sd0_d0, sd0_d1, sd0_d2, + sd0_d3, sd1_d0, sd1_d1, sd1_d2, sd1_d3, sd0_cmd, sd0_clk, + sd1_cmd, sd1_clk, spi0_ss, spi0_miso, uart0_rx, uart0_tx, + uart2_rx, uart2_tx, uart2_rtsb, uart2_ctsb, uart3_rx, uart3_tx, + uart3_rtsb, uart3_ctsb, i2c0_sclk, i2c0_sdata, i2c1_sclk, + i2c1_sdata, i2c2_sdata, csi_dn0, csi_dp0, csi_dn1, csi_dp1, + csi_cn, csi_cp, csi_dn2, csi_dp2, csi_dn3, csi_dp3, + sensor0_pclk, sensor0_ckout, dnand_d0, dnand_d1, dnand_d2, + dnand_d3, dnand_d4, dnand_d5, dnand_d6, dnand_d7, dnand_wrb, + dnand_rdb, dnand_rdbn, dnand_dqs, dnand_dqsn, dnand_rb0, + dnand_ale, dnand_cle, dnand_ceb0, dnand_ceb1, dnand_ceb2, + dnand_ceb3, porb, clko_25m, bsel, pkg0, pkg1, pkg2, pkg3 + +- groups: An array of strings, each string containing the name of a pin + group. These pin groups are used for selecting the pinmux + functions. + rgmii_txd23_mfp, rgmii_rxd2_mfp, rgmii_rxd3_mfp, lcd0_d18_mfp, + rgmii_txd01_mfp, rgmii_txd0_mfp, rgmii_txd1_mfp, rgmii_txen_mfp, + rgmii_rxen_mfp, rgmii_rxd1_mfp, rgmii_rxd0_mfp, rgmii_ref_clk_mfp, + i2s_d0_mfp, i2s_pcm1_mfp, i2s0_pcm0_mfp, i2s1_pcm0_mfp, + i2s_d1_mfp, ks_in2_mfp, ks_in1_mfp, ks_in0_mfp, ks_in3_mfp, + ks_out0_mfp, ks_out1_mfp, ks_out2_mfp, lvds_o_pn_mfp, dsi_dn0_mfp, + dsi_dp2_mfp, lcd0_d2_mfp, dsi_dp3_mfp, dsi_dn3_mfp, dsi_dp0_mfp, + lvds_ee_pn_mfp, uart2_rx_tx_mfp, spi0_i2c_pcm_mfp, dsi_dnp1_cp_d2_mfp, + dsi_dnp1_cp_d17_mfp, lvds_e_pn_mfp, dsi_dn2_mfp, uart2_rtsb_mfp, + uart2_ctsb_mfp, uart3_rtsb_mfp, uart3_ctsb_mfp, sd0_d0_mfp, sd0_d1_mfp, + sd0_d2_d3_mfp, sd1_d0_d3_mfp, sd0_cmd_mfp, sd0_clk_mfp, sd1_cmd_mfp, + uart0_rx_mfp, clko_25m_mfp, csi_cn_cp_mfp, sens0_ckout_mfp, uart0_tx_mfp, + i2c0_mfp, csi_dn_dp_mfp, sen0_pclk_mfp, pcm1_in_mfp, pcm1_clk_mfp, + pcm1_sync_mfp, pcm1_out_mfp, dnand_data_wr_mfp, dnand_acle_ce0_mfp, + nand_ceb2_mfp, nand_ceb3_mfp + + These pin groups are used for selecting the drive strength + parameters. + + sirq_drv, rgmii_txd23_drv, rgmii_rxd23_drv, rgmii_txd01_txen_drv, + rgmii_rxer_drv, rgmii_crs_drv, rgmii_rxd10_drv, rgmii_ref_clk_drv, + smi_mdc_mdio_drv, i2s_d0_drv, i2s_bclk0_drv, i2s3_drv, i2s13_drv, + pcm1_drv, ks_in_drv, ks_out_drv, lvds_all_drv, lcd_d18_d2_drv, + dsi_all_drv, sd0_d0_d3_drv, sd0_cmd_drv, sd0_clk_drv, spi0_all_drv, + uart0_rx_drv, uart0_tx_drv, uart2_all_drv, i2c0_all_drv, i2c12_all_drv, + sens0_pclk_drv, sens0_ckout_drv, uart3_all_drv + +- function: An array of strings, each string containing the name of the + pinmux functions. These functions can only be selected by + the corresponding pin groups. The following are the list of + pinmux functions available: + + nor, eth_rgmii, eth_sgmii, spi0, spi1, spi2, spi3, seNs0, sens1, + uart0, uart1, uart2, uart3, uart4, uart5, uart6, i2s0, i2s1, + pcm1, pcm0, ks, jtag, pwm0, pwm1, pwm2, pwm3, pwm4, pwm5, p0, + sd0, sd1, sd2, i2c0, i2c1, i2c2, i2c3, dsi, lvds, usb30, + clko_25m, mipi_csi, nand, spdif, sirq0, sirq1, sirq2, bt, lcd0 + +Optional Properties: + +- bias-pull-down: No arguments. The specified pins should be configured as + pull down. +- bias-pull-up: No arguments. The specified pins should be configured as + pull up. +- input-schmitt-enable: No arguments: Enable schmitt trigger for the specified + pins +- input-schmitt-disable: No arguments: Disable schmitt trigger for the specified + pins +- drive-strength: Integer. Selects the drive strength for the specified + pins in mA. + Valid values are: + <2> + <4> + <8> + <12> + +Example: + + pinctrl: pinctrl@e01b0000 { + compatible = "actions,s700-pinctrl"; + reg = <0x0 0xe01b0000 0x0 0x1000>; + clocks = <&cmu CLK_GPIO>; + gpio-controller; + gpio-ranges = <&pinctrl 0 0 136>; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 40 IRQ_TYPE_LEVEL_HIGH>; + + uart3-default: uart3-default { + pinmux { + groups = "uart3_rtsb_mfp", "uart3_ctsb_mfp"; + function = "uart3"; + }; + pinconf { + groups = "uart3_all_drv"; + drive-strength = <2>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt index 258a4648ab81..cf96b7c20e4d 100644 --- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt @@ -29,6 +29,7 @@ Required properties: "allwinner,sun50i-h5-pinctrl" "allwinner,sun50i-h6-pinctrl" "allwinner,sun50i-h6-r-pinctrl" + "allwinner,suniv-f1c100s-pinctrl" "nextthing,gr8-pinctrl" - reg: Should contain the register physical address and length for the @@ -43,6 +44,19 @@ Note: For backward compatibility reasons, the hosc and losc clocks are only required if you need to use the optional input-debounce property. Any new device tree should set them. +Each pin bank, depending on the SoC, can have an associated regulator: + +- vcc-pa-supply: for the A10, A20, A31, A31s, A80 and R40 SoCs +- vcc-pb-supply: for the A31, A31s, A80 and V3s SoCs +- vcc-pc-supply: for the A10, A20, A31, A31s, A64, A80, H5, R40 and V3s SoCs +- vcc-pd-supply: for the A23, A31, A31s, A64, A80, A83t, H3, H5 and R40 SoCs +- vcc-pe-supply: for the A10, A20, A31, A31s, A64, A80, R40 and V3s SoCs +- vcc-pf-supply: for the A10, A20, A31, A31s, A80, R40 and V3s SoCs +- vcc-pg-supply: for the A10, A20, A31, A31s, A64, A80, H3, H5, R40 and V3s SoCs +- vcc-ph-supply: for the A31, A31s and A80 SoCs +- vcc-pl-supply: for the r-pinctrl of the A64, A80 and A83t SoCs +- vcc-pm-supply: for the r-pinctrl of the A31, A31s and A80 SoCs + Optional properties: - input-debounce: Array of debouncing periods in microseconds. One period per irq bank found in the controller. 0 if no setup required. diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm4708-pinmux.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm4708-pinmux.txt index 4fa9539070cb..8ab2d468dbdb 100644 --- a/Documentation/devicetree/bindings/pinctrl/brcm,bcm4708-pinmux.txt +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm4708-pinmux.txt @@ -7,13 +7,15 @@ configure controller correctly. A list of pins varies across chipsets so few bindings are available. +Node of the pinmux must be nested in the CRU (Central Resource Unit) "syscon" +noce. + Required properties: - compatible: must be one of: "brcm,bcm4708-pinmux" "brcm,bcm4709-pinmux" "brcm,bcm53012-pinmux" -- reg: iomem address range of CRU (Central Resource Unit) pin registers -- reg-names: "cru_gpio_control" - the only needed & supported reg right now +- offset: offset of pin registers in the CRU block Functions and their groups available for all chipsets: - "spi": "spi_grp" @@ -37,16 +39,12 @@ Example: #size-cells = <1>; cru@100 { - compatible = "simple-bus"; + compatible = "syscon", "simple-mfd"; reg = <0x100 0x1a4>; - ranges; - #address-cells = <1>; - #size-cells = <1>; - pin-controller@1c0 { + pinctrl { compatible = "brcm,bcm4708-pinmux"; - reg = <0x1c0 0x24>; - reg-names = "cru_gpio_control"; + offset = <0xc0>; spi-pins { function = "spi"; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx7ulp-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx7ulp-pinctrl.txt index 44ad670ae11e..bfa3703a7446 100644 --- a/Documentation/devicetree/bindings/pinctrl/fsl,imx7ulp-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx7ulp-pinctrl.txt @@ -7,55 +7,47 @@ Note: This binding doc is only for the IOMUXC1 support in A7 Domain and it only supports generic pin config. -Please also refer pinctrl-bindings.txt in this directory for generic pinctrl -binding. - -=== Pin Controller Node === +Please refer to fsl,imx-pinctrl.txt in this directory for common binding +part and usage. Required properties: -- compatible: "fsl,imx7ulp-iomuxc1" -- reg: Should contain the base physical address and size of the iomuxc - registers. - -=== Pin Configuration Node === -- pinmux: One integers array, represents a group of pins mux setting. - The format is pinmux = <PIN_FUNC_ID>, PIN_FUNC_ID is a pin working on - a specific function. - - NOTE: i.MX7ULP PIN_FUNC_ID consists of 4 integers as it shares one mux - and config register as follows: - <mux_conf_reg input_reg mux_mode input_val> - - Refer to imx7ulp-pinfunc.h in in device tree source folder for all - available imx7ulp PIN_FUNC_ID. - -Optional Properties: -- drive-strength Integer. Controls Drive Strength - 0: Standard - 1: Hi Driver -- drive-push-pull Bool. Enable Pin Push-pull -- drive-open-drain Bool. Enable Pin Open-drian -- slew-rate: Integer. Controls Slew Rate - 0: Standard - 1: Slow -- bias-disable: Bool. Pull disabled -- bias-pull-down: Bool. Pull down on pin -- bias-pull-up: Bool. Pull up on pin +- compatible: "fsl,imx7ulp-iomuxc1". +- fsl,pins: Each entry consists of 5 integers which represents the mux + and config setting for one pin. The first 4 integers + <mux_conf_reg input_reg mux_mode input_val> are specified + using a PIN_FUNC_ID macro, which can be found in + imx7ulp-pinfunc.h in the device tree source folder. + The last integer CONFIG is the pad setting value like + pull-up on this pin. + + Please refer to i.MX7ULP Reference Manual for detailed + CONFIG settings. + +CONFIG bits definition: +PAD_CTL_OBE (1 << 17) +PAD_CTL_IBE (1 << 16) +PAD_CTL_LK (1 << 16) +PAD_CTL_DSE_HI (1 << 6) +PAD_CTL_DSE_STD (0 << 6) +PAD_CTL_ODE (1 << 5) +PAD_CTL_PUSH_PULL (0 << 5) +PAD_CTL_SRE_SLOW (1 << 2) +PAD_CTL_SRE_STD (0 << 2) +PAD_CTL_PE (1 << 0) Examples: #include "imx7ulp-pinfunc.h" /* Pin Controller Node */ -iomuxc1: iomuxc@40ac0000 { +iomuxc1: pinctrl@40ac0000 { compatible = "fsl,imx7ulp-iomuxc1"; reg = <0x40ac0000 0x1000>; /* Pin Configuration Node */ pinctrl_lpuart4: lpuart4grp { - pinmux = < - IMX7ULP_PAD_PTC3__LPUART4_RX - IMX7ULP_PAD_PTC2__LPUART4_TX + fsl,pins = < + IMX7ULP_PAD_PTC3__LPUART4_RX 0x1 + IMX7ULP_PAD_PTC2__LPUART4_TX 0x1 >; - bias-pull-up; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt index 24a210e0c59a..32a8a8fa7805 100644 --- a/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/mscc,ocelot-pinctrl.txt @@ -2,7 +2,8 @@ Microsemi Ocelot pin controller Device Tree Bindings ---------------------------------------------------- Required properties: - - compatible : Should be "mscc,ocelot-pinctrl" + - compatible : Should be "mscc,ocelot-pinctrl" or + "mscc,jaguar2-pinctrl" - reg : Address and length of the register set for the device - gpio-controller : Indicates this device is a GPIO controller - #gpio-cells : Must be 2. diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt new file mode 100644 index 000000000000..bd83401e6179 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt6797.txt @@ -0,0 +1,83 @@ +* MediaTek MT6797 Pin Controller + +The MediaTek's MT6797 Pin controller is used to control SoC pins. + +Required properties: +- compatible: Value should be one of the following. + "mediatek,mt6797-pinctrl", compatible with mt6797 pinctrl. +- reg: Should contain address and size for gpio, iocfgl, iocfgb, + iocfgr and iocfgt register bases. +- reg-names: An array of strings describing the "reg" entries. Must + contain "gpio", "iocfgl", "iocfgb", "iocfgr", "iocfgt". +- gpio-controller: Marks the device node as a gpio controller. +- #gpio-cells: Should be two. The first cell is the gpio pin number + and the second cell is used for optional parameters. + +Optional properties: +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells: Should be two. +- interrupts : The interrupt outputs from the controller. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices. + +Subnode format +A pinctrl node should contain at least one subnodes representing the +pinctrl groups available on the machine. Each subnode will list the +pins it needs, and how they should be configured, with regard to muxer +configuration, pullups, drive strength, input enable/disable and input schmitt. + + node { + pinmux = <PIN_NUMBER_PINMUX>; + GENERIC_PINCONFIG; + }; + +Required properties: +- pinmux: Integer array, represents gpio pin number and mux setting. + Supported pin number and mux varies for different SoCs, and are defined + as macros in dt-bindings/pinctrl/<soc>-pinfunc.h directly. + +Optional properties: +- GENERIC_PINCONFIG: is the generic pinconfig options to use, bias-disable, + bias-pull, bias-pull-down, input-enable, input-schmitt-enable, + input-schmitt-disable, output-enable output-low, output-high, + drive-strength, and slew-rate are valid. + + Valid arguments for 'slew-rate' are '0' for no slew rate controlled and + '1' for slower slew rate respectively. Valid arguments for 'drive-strength' + is limited, such as 2, 4, 8, 12, or 16 in mA. + + Some optional vendor properties as defined are valid to specify in a + pinconf subnode: + - mediatek,tdsel: An integer describing the steps for output level shifter + duty cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 15. + - mediatek,rdsel: An integer describing the steps for input level shifter + duty cycle when asserted (high pulse width adjustment). Valid arguments + are from 0 to 63. + - mediatek,pull-up-adv: An integer describing the code R1R0 as 0, 1, 2 + or 3 for the advanced pull-up resistors. + - mediatek,pull-down-adv: An integer describing the code R1R0 as 0, 1, 2, + or 3 for the advanced pull-down resistors. + +Examples: + + pio: pinctrl@10005000 { + compatible = "mediatek,mt6797-pinctrl"; + reg = <0 0x10005000 0 0x1000>, + <0 0x10002000 0 0x400>, + <0 0x10002400 0 0x400>, + <0 0x10002800 0 0x400>, + <0 0x10002C00 0 0x400>; + reg-names = "gpio", "iocfgl", "iocfgb", + "iocfgr", "iocfgt"; + gpio-controller; + #gpio-cells = <2>; + + uart1_pins_a: uart1 { + pins1 { + pinmux = <MT6797_GPIO232__FUNC_URXD1>, + <MT6797_GPIO233__FUNC_UTXD1>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt index 3b695131c51b..7a7aca1ed705 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-mt7622.txt @@ -3,6 +3,7 @@ Required properties for the root node: - compatible: Should be one of the following "mediatek,mt7622-pinctrl" for MT7622 SoC + "mediatek,mt7629-pinctrl" for MT7629 SoC - reg: offset and length of the pinctrl space - gpio-controller: Marks the device node as a GPIO controller. @@ -324,6 +325,136 @@ group. "uart4_2_rts_cts" "uart" 95, 96 "watchdog" "watchdog" 78 + +== Valid values for pins, function and groups on MT7629 == + + Pin #: Valid values for pins + ----------------------------- + PIN 0: "TOP_5G_CLK" + PIN 1: "TOP_5G_DATA" + PIN 2: "WF0_5G_HB0" + PIN 3: "WF0_5G_HB1" + PIN 4: "WF0_5G_HB2" + PIN 5: "WF0_5G_HB3" + PIN 6: "WF0_5G_HB4" + PIN 7: "WF0_5G_HB5" + PIN 8: "WF0_5G_HB6" + PIN 9: "XO_REQ" + PIN 10: "TOP_RST_N" + PIN 11: "SYS_WATCHDOG" + PIN 12: "EPHY_LED0_N_JTDO" + PIN 13: "EPHY_LED1_N_JTDI" + PIN 14: "EPHY_LED2_N_JTMS" + PIN 15: "EPHY_LED3_N_JTCLK" + PIN 16: "EPHY_LED4_N_JTRST_N" + PIN 17: "WF2G_LED_N" + PIN 18: "WF5G_LED_N" + PIN 19: "I2C_SDA" + PIN 20: "I2C_SCL" + PIN 21: "GPIO_9" + PIN 22: "GPIO_10" + PIN 23: "GPIO_11" + PIN 24: "GPIO_12" + PIN 25: "UART1_TXD" + PIN 26: "UART1_RXD" + PIN 27: "UART1_CTS" + PIN 28: "UART1_RTS" + PIN 29: "UART2_TXD" + PIN 30: "UART2_RXD" + PIN 31: "UART2_CTS" + PIN 32: "UART2_RTS" + PIN 33: "MDI_TP_P1" + PIN 34: "MDI_TN_P1" + PIN 35: "MDI_RP_P1" + PIN 36: "MDI_RN_P1" + PIN 37: "MDI_RP_P2" + PIN 38: "MDI_RN_P2" + PIN 39: "MDI_TP_P2" + PIN 40: "MDI_TN_P2" + PIN 41: "MDI_TP_P3" + PIN 42: "MDI_TN_P3" + PIN 43: "MDI_RP_P3" + PIN 44: "MDI_RN_P3" + PIN 45: "MDI_RP_P4" + PIN 46: "MDI_RN_P4" + PIN 47: "MDI_TP_P4" + PIN 48: "MDI_TN_P4" + PIN 49: "SMI_MDC" + PIN 50: "SMI_MDIO" + PIN 51: "PCIE_PERESET_N" + PIN 52: "PWM_0" + PIN 53: "GPIO_0" + PIN 54: "GPIO_1" + PIN 55: "GPIO_2" + PIN 56: "GPIO_3" + PIN 57: "GPIO_4" + PIN 58: "GPIO_5" + PIN 59: "GPIO_6" + PIN 60: "GPIO_7" + PIN 61: "GPIO_8" + PIN 62: "SPI_CLK" + PIN 63: "SPI_CS" + PIN 64: "SPI_MOSI" + PIN 65: "SPI_MISO" + PIN 66: "SPI_WP" + PIN 67: "SPI_HOLD" + PIN 68: "UART0_TXD" + PIN 69: "UART0_RXD" + PIN 70: "TOP_2G_CLK" + PIN 71: "TOP_2G_DATA" + PIN 72: "WF0_2G_HB0" + PIN 73: "WF0_2G_HB1" + PIN 74: "WF0_2G_HB2" + PIN 75: "WF0_2G_HB3" + PIN 76: "WF0_2G_HB4" + PIN 77: "WF0_2G_HB5" + PIN 78: "WF0_2G_HB6" + +Valid values for function are: + "eth", "i2c", "led", "flash", "pcie", "pwm", "spi", "uart", + "watchdog", "wifi" + +Valid values for groups are: + Valid value function pins (in pin#) + ---------------------------------------------------------------- + "mdc_mdio" "eth" 23, 24 + "i2c_0" "i2c" 19, 20 + "i2c_1" "i2c" 53, 54 + "ephy_leds" "led" 12, 13, 14, 15, 16, + 17, 18 + "ephy0_led" "led" 12 + "ephy1_led" "led" 13 + "ephy2_led" "led" 14 + "ephy3_led" "led" 15 + "ephy4_led" "led" 16 + "wf2g_led" "led" 17 + "wf5g_led" "led" 18 + "snfi" "flash" 62, 63, 64, 65, 66, 67 + "spi_nor" "flash" 62, 63, 64, 65, 66, 67 + "pcie_pereset" "pcie" 51 + "pcie_wake" "pcie" 55 + "pcie_clkreq" "pcie" 56 + "pwm_0" "pwm" 52 + "pwm_1" "pwm" 61 + "spi_0" "spi" 21, 22, 23, 24 + "spi_1" "spi" 62, 63, 64, 65 + "spi_wp" "spi" 66 + "spi_hold" "spi" 67 + "uart0_txd_rxd" "uart" 68, 69 + "uart1_0_txd_rxd" "uart" 25, 26 + "uart1_0_cts_rts" "uart" 27, 28 + "uart1_1_txd_rxd" "uart" 53, 54 + "uart1_1_cts_rts" "uart" 55, 56 + "uart2_0_txd_rxd" "uart" 29, 30 + "uart2_0_cts_rts" "uart" 31, 32 + "uart2_1_txd_rxd" "uart" 57, 58 + "uart2_1_cts_rts" "uart" 59, 60 + "watchdog" "watchdog" 11 + "wf0_2g" "wifi" 70, 71, 72, 73, 74, + 75, 76, 77, 78 + "wf0_5g" "wifi" 0, 1, 2, 3, 4, 5, 6, + 7, 8, 9, 10 + Example: pio: pinctrl@10211000 { diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt index ab4000eab07d..7f64a7e92c28 100644 --- a/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt +++ b/Documentation/devicetree/bindings/pinctrl/qcom,pmic-gpio.txt @@ -19,6 +19,7 @@ PMIC's from Qualcomm. "qcom,pm8998-gpio" "qcom,pma8084-gpio" "qcom,pmi8994-gpio" + "qcom,pmi8998-gpio" "qcom,pms405-gpio" And must contain either "qcom,spmi-gpio" or "qcom,ssbi-gpio" @@ -92,7 +93,7 @@ to specify in a pin configuration subnode: gpio1-gpio26 for pm8998 gpio1-gpio22 for pma8084 gpio1-gpio10 for pmi8994 - gpio1-gpio11 for pms405 + gpio1-gpio12 for pms405 (holes on gpio1, gpio9 and gpio10) - function: Usage: required diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt new file mode 100644 index 000000000000..a63ccd476cda --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza2-pinctrl.txt @@ -0,0 +1,87 @@ +Renesas RZ/A2 combined Pin and GPIO controller + +The Renesas SoCs of the RZ/A2 series feature a combined Pin and GPIO controller. +Pin multiplexing and GPIO configuration is performed on a per-pin basis. +Each port features up to 8 pins, each of them configurable for GPIO +function (port mode) or in alternate function mode. +Up to 8 different alternate function modes exist for each single pin. + +Pin controller node +------------------- + +Required properties: + - compatible: shall be: + - "renesas,r7s9210-pinctrl": for RZ/A2M + - reg + Address base and length of the memory area where the pin controller + hardware is mapped to. + - gpio-controller + This pin controller also controls pins as GPIO + - #gpio-cells + Must be 2 + - gpio-ranges + Expresses the total number of GPIO ports/pins in this SoC + +Example: Pin controller node for RZ/A2M SoC (r7s9210) + + pinctrl: pin-controller@fcffe000 { + compatible = "renesas,r7s9210-pinctrl"; + reg = <0xfcffe000 0x1000>; + + gpio-controller; + #gpio-cells = <2>; + gpio-ranges = <&pinctrl 0 0 176>; + }; + +Sub-nodes +--------- + +The child nodes of the pin controller designate pins to be used for +specific peripheral functions or as GPIO. + +- Pin multiplexing sub-nodes: + A pin multiplexing sub-node describes how to configure a set of + (or a single) pin in some desired alternate function mode. + The values for the pinmux properties are a combination of port name, pin + number and the desired function index. Use the RZA2_PINMUX macro located + in include/dt-bindings/pinctrl/r7s9210-pinctrl.h to easily define these. + For assigning GPIO pins, use the macro RZA2_PIN also in r7s9210-pinctrl.h + to express the desired port pin. + + Required properties: + - pinmux: + integer array representing pin number and pin multiplexing configuration. + When a pin has to be configured in alternate function mode, use this + property to identify the pin by its global index, and provide its + alternate function configuration number along with it. + When multiple pins are required to be configured as part of the same + alternate function they shall be specified as members of the same + argument list of a single "pinmux" property. + Helper macros to ease assembling the pin index from its position + (port where it sits on and pin number) and alternate function identifier + are provided by the pin controller header file at: + <dt-bindings/pinctrl/r7s9210-pinctrl.h> + Integers values in "pinmux" argument list are assembled as: + ((PORT * 8 + PIN) | MUX_FUNC << 16) + + Example: Board specific pins configuration + + &pinctrl { + /* Serial Console */ + scif4_pins: serial4 { + pinmux = <RZA2_PINMUX(PORT9, 0, 4)>, /* TxD4 */ + <RZA2_PINMUX(PORT9, 1, 4)>; /* RxD4 */ + }; + }; + + Example: Assigning a GPIO: + + leds { + status = "okay"; + compatible = "gpio-leds"; + + led0 { + /* P6_0 */ + gpios = <&pinctrl RZA2_PIN(PORT6, 0) GPIO_ACTIVE_HIGH>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt index ef4f2ff4a1aa..48df30a36b01 100644 --- a/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt +++ b/Documentation/devicetree/bindings/pinctrl/st,stm32-pinctrl.txt @@ -56,6 +56,7 @@ Optional properties: More details in Documentation/devicetree/bindings/gpio/gpio.txt. - st,bank-ioport: should correspond to the EXTI IOport selection (EXTI line used to select GPIOs as interrupts). + - hwlocks: reference to a phandle of a hardware spinlock provider node. Example 1: #include <dt-bindings/pinctrl/stm32f429-pinfunc.h> diff --git a/Documentation/devicetree/bindings/power/actions,owl-sps.txt b/Documentation/devicetree/bindings/power/actions,owl-sps.txt index 78edd63641e8..a3571937b019 100644 --- a/Documentation/devicetree/bindings/power/actions,owl-sps.txt +++ b/Documentation/devicetree/bindings/power/actions,owl-sps.txt @@ -3,11 +3,13 @@ Actions Semi Owl Smart Power System (SPS) Required properties: - compatible : "actions,s500-sps" for S500 "actions,s700-sps" for S700 + "actions,s900-sps" for S900 - reg : Offset and length of the register set for the device. - #power-domain-cells : Must be 1. See macros in: include/dt-bindings/power/owl-s500-powergate.h for S500 include/dt-bindings/power/owl-s700-powergate.h for S700 + include/dt-bindings/power/owl-s900-powergate.h for S900 Example: diff --git a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt index 9acce75b29ab..7c7e972aaa42 100644 --- a/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt +++ b/Documentation/devicetree/bindings/power/fsl,imx-gpcv2.txt @@ -6,7 +6,9 @@ Control (PGC) for various power domains. Required properties: -- compatible: Should be "fsl,imx7d-gpc" +- compatible: Should be one of: + - "fsl,imx7d-gpc" + - "fsl,imx8mq-gpc" - reg: should be register base and length as documented in the datasheet @@ -22,13 +24,17 @@ which, in turn, is expected to contain the following: Required properties: - reg: Power domain index. Valid values are defined in - include/dt-bindings/power/imx7-power.h + include/dt-bindings/power/imx7-power.h for fsl,imx7d-gpc and + include/dt-bindings/power/imx8m-power.h for fsl,imx8mq-gpc - #power-domain-cells: Should be 0 Optional properties: - power-supply: Power supply used to power the domain +- clocks: a number of phandles to clocks that need to be enabled during + domain power-up sequencing to ensure reset propagation into devices + located inside this power domain Example: diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.txt b/Documentation/devicetree/bindings/power/qcom,rpmpd.txt new file mode 100644 index 000000000000..980e5413d18f --- /dev/null +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.txt @@ -0,0 +1,145 @@ +Qualcomm RPM/RPMh Power domains + +For RPM/RPMh Power domains, we communicate a performance state to RPM/RPMh +which then translates it into a corresponding voltage on a rail + +Required Properties: + - compatible: Should be one of the following + * qcom,msm8996-rpmpd: RPM Power domain for the msm8996 family of SoC + * qcom,sdm845-rpmhpd: RPMh Power domain for the sdm845 family of SoC + - #power-domain-cells: number of cells in Power domain specifier + must be 1. + - operating-points-v2: Phandle to the OPP table for the Power domain. + Refer to Documentation/devicetree/bindings/power/power_domain.txt + and Documentation/devicetree/bindings/opp/opp.txt for more details + +Refer to <dt-bindings/power/qcom-rpmpd.h> for the level values for +various OPPs for different platforms as well as Power domain indexes + +Example: rpmh power domain controller and OPP table + +#include <dt-bindings/power/qcom-rpmhpd.h> + +opp-level values specified in the OPP tables for RPMh power domains +should use the RPMH_REGULATOR_LEVEL_* constants from +<dt-bindings/power/qcom-rpmhpd.h> + + rpmhpd: power-controller { + compatible = "qcom,sdm845-rpmhpd"; + #power-domain-cells = <1>; + operating-points-v2 = <&rpmhpd_opp_table>; + + rpmhpd_opp_table: opp-table { + compatible = "operating-points-v2"; + + rpmhpd_opp_ret: opp1 { + opp-level = <RPMH_REGULATOR_LEVEL_RETENTION>; + }; + + rpmhpd_opp_min_svs: opp2 { + opp-level = <RPMH_REGULATOR_LEVEL_MIN_SVS>; + }; + + rpmhpd_opp_low_svs: opp3 { + opp-level = <RPMH_REGULATOR_LEVEL_LOW_SVS>; + }; + + rpmhpd_opp_svs: opp4 { + opp-level = <RPMH_REGULATOR_LEVEL_SVS>; + }; + + rpmhpd_opp_svs_l1: opp5 { + opp-level = <RPMH_REGULATOR_LEVEL_SVS_L1>; + }; + + rpmhpd_opp_nom: opp6 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM>; + }; + + rpmhpd_opp_nom_l1: opp7 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM_L1>; + }; + + rpmhpd_opp_nom_l2: opp8 { + opp-level = <RPMH_REGULATOR_LEVEL_NOM_L2>; + }; + + rpmhpd_opp_turbo: opp9 { + opp-level = <RPMH_REGULATOR_LEVEL_TURBO>; + }; + + rpmhpd_opp_turbo_l1: opp10 { + opp-level = <RPMH_REGULATOR_LEVEL_TURBO_L1>; + }; + }; + }; + +Example: rpm power domain controller and OPP table + + rpmpd: power-controller { + compatible = "qcom,msm8996-rpmpd"; + #power-domain-cells = <1>; + operating-points-v2 = <&rpmpd_opp_table>; + + rpmpd_opp_table: opp-table { + compatible = "operating-points-v2"; + + rpmpd_opp_low: opp1 { + opp-level = <1>; + }; + + rpmpd_opp_ret: opp2 { + opp-level = <2>; + }; + + rpmpd_opp_svs: opp3 { + opp-level = <3>; + }; + + rpmpd_opp_normal: opp4 { + opp-level = <4>; + }; + + rpmpd_opp_high: opp5 { + opp-level = <5>; + }; + + rpmpd_opp_turbo: opp6 { + opp-level = <6>; + }; + }; + }; + +Example: Client/Consumer device using OPP table + + leaky-device0@12350000 { + compatible = "foo,i-leak-current"; + reg = <0x12350000 0x1000>; + power-domains = <&rpmhpd SDM845_MX>; + operating-points-v2 = <&leaky_opp_table>; + }; + + + leaky_opp_table: opp-table { + compatible = "operating-points-v2"; + + opp1 { + opp-hz = /bits/ 64 <144000>; + required-opps = <&rpmhpd_opp_low>; + }; + + opp2 { + opp-hz = /bits/ 64 <400000>; + required-opps = <&rpmhpd_opp_ret>; + }; + + opp3 { + opp-hz = /bits/ 64 <20000000>; + required-opps = <&rpmpd_opp_svs>; + }; + + opp4 { + opp-hz = /bits/ 64 <25000000>; + required-opps = <&rpmpd_opp_normal>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/renesas,apmu.txt b/Documentation/devicetree/bindings/power/renesas,apmu.txt index f747f95eee58..5f24586c8cf3 100644 --- a/Documentation/devicetree/bindings/power/renesas,apmu.txt +++ b/Documentation/devicetree/bindings/power/renesas,apmu.txt @@ -8,7 +8,9 @@ Required properties: - compatible: Should be "renesas,<soctype>-apmu", "renesas,apmu" as fallback. Examples with soctypes are: - "renesas,r8a7743-apmu" (RZ/G1M) + - "renesas,r8a7744-apmu" (RZ/G1N) - "renesas,r8a7745-apmu" (RZ/G1E) + - "renesas,r8a77470-apmu" (RZ/G1C) - "renesas,r8a7790-apmu" (R-Car H2) - "renesas,r8a7791-apmu" (R-Car M2-W) - "renesas,r8a7792-apmu" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt index 180ae65be753..eae2a880155a 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.txt @@ -8,8 +8,11 @@ and various coprocessors. Required properties: - compatible: Must contain exactly one of the following: - "renesas,r8a7743-sysc" (RZ/G1M) + - "renesas,r8a7744-sysc" (RZ/G1N) - "renesas,r8a7745-sysc" (RZ/G1E) - "renesas,r8a77470-sysc" (RZ/G1C) + - "renesas,r8a774a1-sysc" (RZ/G2M) + - "renesas,r8a774c0-sysc" (RZ/G2E) - "renesas,r8a7779-sysc" (R-Car H1) - "renesas,r8a7790-sysc" (R-Car H2) - "renesas,r8a7791-sysc" (R-Car M2-W) diff --git a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt index 6d8980c18c34..3e56c1b34a4c 100644 --- a/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt +++ b/Documentation/devicetree/bindings/power/reset/gpio-poweroff.txt @@ -27,6 +27,8 @@ Optional properties: 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. +- active-delay-ms: Delay (default 100) to wait after driving gpio active +- inactive-delay-ms: Delay (default 100) to wait after driving gpio inactive - timeout-ms: Time to wait before asserting a WARN_ON(1). If nothing is specified, 3000 ms is used. diff --git a/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt new file mode 100644 index 000000000000..d366f1eb623a --- /dev/null +++ b/Documentation/devicetree/bindings/power/reset/xlnx,zynqmp-power.txt @@ -0,0 +1,25 @@ +-------------------------------------------------------------------- +Device Tree Bindings for the Xilinx Zynq MPSoC Power Management +-------------------------------------------------------------------- +The zynqmp-power node describes the power management configurations. +It will control remote suspend/shutdown interfaces. + +Required properties: + - compatible: Must contain: "xlnx,zynqmp-power" + - interrupts: Interrupt specifier + +------- +Example +------- + +firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + + zynqmp_power: zynqmp-power { + compatible = "xlnx,zynqmp-power"; + interrupts = <0 35 4>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt b/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt index 826e8a879121..7a1fb532abe5 100644 --- a/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt +++ b/Documentation/devicetree/bindings/power/supply/axp20x_ac_power.txt @@ -4,6 +4,7 @@ Required Properties: - compatible: One of: "x-powers,axp202-ac-power-supply" "x-powers,axp221-ac-power-supply" + "x-powers,axp813-ac-power-supply" This node is a subnode of the axp20x PMIC. @@ -13,6 +14,8 @@ reading ADC channels from the AXP20X ADC. The AXP22X is only able to tell if an AC power supply is present and usable. +AXP813/AXP803 are able to limit current and supply voltage + Example: &axp209 { diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt index f4d3b4a10b43..5c913d4cf36c 100644 --- a/Documentation/devicetree/bindings/power/supply/battery.txt +++ b/Documentation/devicetree/bindings/power/supply/battery.txt @@ -16,12 +16,25 @@ Required Properties: Optional Properties: - voltage-min-design-microvolt: drained battery voltage + - voltage-max-design-microvolt: fully charged battery voltage - energy-full-design-microwatt-hours: battery design energy - charge-full-design-microamp-hours: battery design capacity - precharge-current-microamp: current for pre-charge phase - charge-term-current-microamp: current for charge termination phase - constant-charge-current-max-microamp: maximum constant input current - constant-charge-voltage-max-microvolt: maximum constant input voltage + - factory-internal-resistance-micro-ohms: battery factory internal resistance + - ocv-capacity-table-0: An array providing the open circuit voltage (OCV) + of the battery and corresponding battery capacity percent, which is used + to look up battery capacity according to current OCV value. And the open + circuit voltage unit is microvolt. + - ocv-capacity-table-1: Same as ocv-capacity-table-0 + ...... + - ocv-capacity-table-n: Same as ocv-capacity-table-0 + - ocv-capacity-celsius: An array containing the temperature in degree Celsius, + for each of the battery capacity lookup table. The first temperature value + specifies the OCV table 0, and the second temperature value specifies the + OCV table 1, and so on. Battery properties are named, where possible, for the corresponding elements in enum power_supply_property, defined in @@ -36,12 +49,18 @@ Example: bat: battery { compatible = "simple-battery"; voltage-min-design-microvolt = <3200000>; + voltage-max-design-microvolt = <4200000>; energy-full-design-microwatt-hours = <5290000>; charge-full-design-microamp-hours = <1430000>; precharge-current-microamp = <256000>; charge-term-current-microamp = <128000>; constant-charge-current-max-microamp = <900000>; constant-charge-voltage-max-microvolt = <4200000>; + factory-internal-resistance-micro-ohms = <250000>; + ocv-capacity-celsius = <(-10) 0 10>; + ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, ...; + ocv-capacity-table-1 = <4200000 100>, <4185000 95>, <4113000 90>, ...; + ocv-capacity-table-2 = <4250000 100>, <4200000 95>, <4185000 90>, ...; }; charger: charger@11 { diff --git a/Documentation/devicetree/bindings/power/supply/bq24190.txt b/Documentation/devicetree/bindings/power/supply/bq24190.txt index 9e517d307070..ffe2be408bb6 100644 --- a/Documentation/devicetree/bindings/power/supply/bq24190.txt +++ b/Documentation/devicetree/bindings/power/supply/bq24190.txt @@ -3,7 +3,9 @@ TI BQ24190 Li-Ion Battery Charger Required properties: - compatible: contains one of the following: * "ti,bq24190" + * "ti,bq24192" * "ti,bq24192i" + * "ti,bq24196" - reg: integer, I2C address of the charger. - interrupts[-extended]: configuration for charger INT pin. @@ -19,6 +21,12 @@ Optional properties: - ti,system-minimum-microvolt: when power is connected and the battery is below minimum system voltage, the system will be regulated above this setting. +child nodes: +- usb-otg-vbus: + Usage: optional + Description: Regulator that is used to control the VBUS voltage direction for + either USB host mode or for charging on the OTG port. + Notes: - Some circuit boards wire the chip's "OTG" pin high (enabling 500mA default charge current on USB SDP ports, among other features). To simulate this on @@ -39,6 +47,8 @@ Example: interrupts-extended = <&gpiochip 10 IRQ_TYPE_EDGE_FALLING>; monitored-battery = <&bat>; ti,system-minimum-microvolt = <3200000>; + + usb_otg_vbus: usb-otg-vbus { }; }; &twl_gpio { diff --git a/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt new file mode 100644 index 000000000000..0a5705b8b592 --- /dev/null +++ b/Documentation/devicetree/bindings/power/supply/sc27xx-fg.txt @@ -0,0 +1,56 @@ +Spreadtrum SC27XX PMICs Fuel Gauge Unit Power Supply Bindings + +Required properties: +- compatible: Should be one of the following: + "sprd,sc2720-fgu", + "sprd,sc2721-fgu", + "sprd,sc2723-fgu", + "sprd,sc2730-fgu", + "sprd,sc2731-fgu". +- reg: The address offset of fuel gauge unit. +- battery-detect-gpios: GPIO for battery detection. +- io-channels: Specify the IIO ADC channels to get temperature and charge voltage. +- io-channel-names: Should be "bat-temp" or "charge-vol". +- nvmem-cells: A phandle to the calibration cells provided by eFuse device. +- nvmem-cell-names: Should be "fgu_calib". +- monitored-battery: Phandle of battery characteristics devicetree node. + See Documentation/devicetree/bindings/power/supply/battery.txt + +Example: + + bat: battery { + compatible = "simple-battery"; + charge-full-design-microamp-hours = <1900000>; + constant-charge-voltage-max-microvolt = <4350000>; + ocv-capacity-celsius = <20>; + ocv-capacity-table-0 = <4185000 100>, <4113000 95>, <4066000 90>, + <4022000 85>, <3983000 80>, <3949000 75>, + <3917000 70>, <3889000 65>, <3864000 60>, + <3835000 55>, <3805000 50>, <3787000 45>, + <3777000 40>, <3773000 35>, <3770000 30>, + <3765000 25>, <3752000 20>, <3724000 15>, + <3680000 10>, <3605000 5>, <3400000 0>; + ...... + }; + + sc2731_pmic: pmic@0 { + compatible = "sprd,sc2731"; + reg = <0>; + spi-max-frequency = <26000000>; + interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; + interrupt-controller; + #interrupt-cells = <2>; + #address-cells = <1>; + #size-cells = <0>; + + fgu@a00 { + compatible = "sprd,sc2731-fgu"; + reg = <0xa00>; + battery-detect-gpios = <&pmic_eic 9 GPIO_ACTIVE_HIGH>; + io-channels = <&pmic_adc 5>, <&pmic_adc 14>; + io-channel-names = "bat-temp", "charge-vol"; + nvmem-cells = <&fgu_calib>; + nvmem-cell-names = "fgu_calib"; + monitored-battery = <&bat>; + }; + }; diff --git a/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt b/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt new file mode 100644 index 000000000000..8d1b8200ebd0 --- /dev/null +++ b/Documentation/devicetree/bindings/power/xlnx,zynqmp-genpd.txt @@ -0,0 +1,34 @@ +----------------------------------------------------------- +Device Tree Bindings for the Xilinx Zynq MPSoC PM domains +----------------------------------------------------------- +The binding for zynqmp-power-controller follow the common +generic PM domain binding[1]. + +[1] Documentation/devicetree/bindings/power/power_domain.txt + +== Zynq MPSoC Generic PM Domain Node == + +Required property: + - Below property should be in zynqmp-firmware node. + - #power-domain-cells: Number of cells in a PM domain specifier. Must be 1. + +Power domain ID indexes are mentioned in +include/dt-bindings/power/xlnx-zynqmp-power.h. + +------- +Example +------- + +firmware { + zynqmp_firmware: zynqmp-firmware { + ... + #power-domain-cells = <1>; + ... + }; +}; + +sata { + ... + power-domains = <&zynqmp_firmware 28>; + ... +}; diff --git a/Documentation/devicetree/bindings/property-units.txt b/Documentation/devicetree/bindings/property-units.txt index 45ce054d844d..bfd33734faca 100644 --- a/Documentation/devicetree/bindings/property-units.txt +++ b/Documentation/devicetree/bindings/property-units.txt @@ -31,6 +31,7 @@ Electricity -microwatt-hours: micro Watt-hours -microvolt : micro volts -picofarads : picofarads +-femtofarads : femtofarads Temperature ---------------------------------------- diff --git a/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt index c5d0e7998e2b..454c937076a2 100644 --- a/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt +++ b/Documentation/devicetree/bindings/ptp/ptp-qoriq.txt @@ -17,6 +17,11 @@ Clock Properties: - fsl,tmr-fiper1 Fixed interval period pulse generator. - fsl,tmr-fiper2 Fixed interval period pulse generator. - fsl,max-adj Maximum frequency adjustment in parts per billion. + - fsl,extts-fifo The presence of this property indicates hardware + support for the external trigger stamp FIFO. + - little-endian The presence of this property indicates the 1588 timer + IP block is little-endian mode. The default endian mode + is big-endian. These properties set the operational parameters for the PTP clock. You must choose these carefully for the clock to work right. diff --git a/Documentation/devicetree/bindings/pwm/pwm-tiecap.txt b/Documentation/devicetree/bindings/pwm/pwm-tiecap.txt index 06a363d9ccef..b9a1d7402128 100644 --- a/Documentation/devicetree/bindings/pwm/pwm-tiecap.txt +++ b/Documentation/devicetree/bindings/pwm/pwm-tiecap.txt @@ -7,6 +7,7 @@ Required properties: for da850 - compatible = "ti,da850-ecap", "ti,am3352-ecap", "ti,am33xx-ecap"; for dra746 - compatible = "ti,dra746-ecap", "ti,am3352-ecap"; for 66ak2g - compatible = "ti,k2g-ecap", "ti,am3352-ecap"; + for am654 - compatible = "ti,am654-ecap", "ti,am3352-ecap"; - #pwm-cells: should be 3. See pwm.txt in this directory for a description of the cells format. The PWM channel index ranges from 0 to 4. The only third cell flag supported by this binding is PWM_POLARITY_INVERTED. diff --git a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt index e1ef6afbe3a7..fbd6a4f943ce 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt +++ b/Documentation/devicetree/bindings/pwm/renesas,pwm-rcar.txt @@ -3,7 +3,10 @@ Required Properties: - compatible: should be "renesas,pwm-rcar" and one of the following. - "renesas,pwm-r8a7743": for RZ/G1M + - "renesas,pwm-r8a7744": for RZ/G1N - "renesas,pwm-r8a7745": for RZ/G1E + - "renesas,pwm-r8a774a1": for RZ/G2M + - "renesas,pwm-r8a774c0": for RZ/G2E - "renesas,pwm-r8a7778": for R-Car M1A - "renesas,pwm-r8a7779": for R-Car H1 - "renesas,pwm-r8a7790": for R-Car H2 @@ -12,6 +15,8 @@ Required Properties: - "renesas,pwm-r8a7795": for R-Car H3 - "renesas,pwm-r8a7796": for R-Car M3-W - "renesas,pwm-r8a77965": for R-Car M3-N + - "renesas,pwm-r8a77970": for R-Car V3M + - "renesas,pwm-r8a77980": for R-Car V3H - "renesas,pwm-r8a77990": for R-Car E3 - "renesas,pwm-r8a77995": for R-Car D3 - reg: base address and length of the registers block for the PWM. diff --git a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt index d53a16715da6..848a92b53d81 100644 --- a/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/renesas,tpu-pwm.txt @@ -2,13 +2,19 @@ Required Properties: - - compatible: should be one of the following. + - compatible: must contain one or more of the following: - "renesas,tpu-r8a73a4": for R8A73A4 (R-Mobile APE6) compatible PWM controller. - "renesas,tpu-r8a7740": for R8A7740 (R-Mobile A1) compatible PWM controller. - "renesas,tpu-r8a7743": for R8A7743 (RZ/G1M) compatible PWM controller. + - "renesas,tpu-r8a7744": for R8A7744 (RZ/G1N) compatible PWM controller. - "renesas,tpu-r8a7745": for R8A7745 (RZ/G1E) compatible PWM controller. - "renesas,tpu-r8a7790": for R8A7790 (R-Car H2) compatible PWM controller. - - "renesas,tpu": for generic R-Car and RZ/G1 TPU PWM controller. + - "renesas,tpu-r8a77970": for R8A77970 (R-Car V3M) compatible PWM + controller. + - "renesas,tpu-r8a77980": for R8A77980 (R-Car V3H) compatible PWM + controller. + - "renesas,tpu": for the generic TPU PWM controller; this is a fallback for + the entries listed above. - reg: Base address and length of each memory resource used by the PWM controller hardware module. diff --git a/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt b/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt index ac955dea00d1..4017527619ab 100644 --- a/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/act8945a-regulator.txt @@ -15,11 +15,17 @@ Optional input supply properties: - inl67-supply: The input supply for REG_LDO3 and REG_LDO4 Any standard regulator properties can be used to configure the single regulator. +regulator-initial-mode, regulator-allowed-modes and regulator-mode could be +specified using mode values from dt-bindings/regulator/active-semi,8945a-regulator.h +file. The valid names for regulators are: REG_DCDC1, REG_DCDC2, REG_DCDC3, REG_LDO1, REG_LDO2, REG_LDO3, REG_LDO4. Example: + +#include <dt-bindings/regulator/active-semi,8945a-regulator.h> + pmic@5b { compatible = "active-semi,act8945a"; reg = <0x5b>; @@ -32,6 +38,18 @@ Example: regulator-min-microvolt = <1350000>; regulator-max-microvolt = <1350000>; regulator-always-on; + + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; + + regulator-state-mem { + regulator-on-in-suspend; + regulator-suspend-min-microvolt=<1400000>; + regulator-suspend-max-microvolt=<1400000>; + regulator-changeable-in-suspend; + regulator-mode=<ACT8945A_REGULATOR_MODE_LOWPOWER>; + }; }; vdd_1v2_reg: REG_DCDC2 { @@ -39,6 +57,14 @@ Example: regulator-min-microvolt = <1100000>; regulator-max-microvolt = <1300000>; regulator-always-on; + + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_FIXED>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_FIXED>; + + regulator-state-mem { + regulator-off-in-suspend; + }; }; vdd_3v3_reg: REG_DCDC3 { @@ -53,6 +79,14 @@ Example: regulator-min-microvolt = <2500000>; regulator-max-microvolt = <2500000>; regulator-always-on; + + regulator-allowed-modes = <ACT8945A_REGULATOR_MODE_NORMAL>, + <ACT8945A_REGULATOR_MODE_LOWPOWER>; + regulator-initial-mode = <ACT8945A_REGULATOR_MODE_NORMAL>; + + regulator-state-mem { + regulator-off-in-suspend; + }; }; vdd_3v3_lp_reg: REG_LDO2 { diff --git a/Documentation/devicetree/bindings/regulator/cirrus,lochnagar.txt b/Documentation/devicetree/bindings/regulator/cirrus,lochnagar.txt new file mode 100644 index 000000000000..91974e6ee251 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/cirrus,lochnagar.txt @@ -0,0 +1,82 @@ +Cirrus Logic Lochnagar Audio Development Board + +Lochnagar is an evaluation and development board for Cirrus Logic +Smart CODEC and Amp devices. It allows the connection of most Cirrus +Logic devices on mini-cards, as well as allowing connection of +various application processor systems to provide a full evaluation +platform. Audio system topology, clocking and power can all be +controlled through the Lochnagar, allowing the device under test +to be used in a variety of possible use cases. + +This binding document describes the binding for the regulator portion +of the driver. + +Also see these documents for generic binding information: + [1] Regulator: ../regulator/regulator.txt + +This binding must be part of the Lochnagar MFD binding: + [2] ../mfd/cirrus,lochnagar.txt + +Optional sub-nodes: + + - VDDCORE : Initialisation data for the VDDCORE regulator, which + supplies the CODECs digital core if it has no build regulator for that + purpose. + Required Properties: + - compatible : One of the following strings: + "cirrus,lochnagar2-vddcore" + - SYSVDD-supply: Primary power supply for the Lochnagar. + + - MICVDD : Initialisation data for the MICVDD regulator, which + supplies the CODECs MICVDD. + Required Properties: + - compatible : One of the following strings: + "cirrus,lochnagar2-micvdd" + - SYSVDD-supply: Primary power supply for the Lochnagar. + + - MIC1VDD, MIC2VDD : Initialisation data for the MICxVDD supplies. + Required Properties: + - compatible : One of the following strings: + "cirrus,lochnagar2-mic1vdd", "cirrus,lochnagar2-mic2vdd" + Optional Properties: + - cirrus,micbias-input : A property selecting which of the CODEC + minicard micbias outputs should be used, valid values are 1 - 4. + - MICBIAS1-supply, MICBIAS2-supply: Regulator supplies for the + MICxVDD outputs, supplying the digital microphones, normally + supplied from the attached CODEC. + + - VDD1V8 : Recommended fixed regulator for the VDD1V8 regulator, which supplies the + CODECs analog and 1.8V digital supplies. + Required Properties: + - compatible : Should be set to "regulator-fixed" + - regulator-min-microvolt : Should be set to 1.8V + - regulator-max-microvolt : Should be set to 1.8V + - regulator-boot-on + - regulator-always-on + - vin-supply : Should be set to same supply as SYSVDD + +Example: + +lochnagar { + lochnagar-micvdd: MICVDD { + compatible = "cirrus,lochnagar2-micvdd"; + + SYSVDD-supply = <&wallvdd>; + + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + }; + + lochnagar-vdd1v8: VDD1V8 { + compatible = "regulator-fixed"; + + regulator-name = "VDD1V8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + regulator-always-on; + + vin-supply = <&wallvdd>; + }; +}; + diff --git a/Documentation/devicetree/bindings/regulator/fan53555.txt b/Documentation/devicetree/bindings/regulator/fan53555.txt index 54a3f2c80e3a..e7fc045281d1 100644 --- a/Documentation/devicetree/bindings/regulator/fan53555.txt +++ b/Documentation/devicetree/bindings/regulator/fan53555.txt @@ -1,7 +1,8 @@ Binding for Fairchild FAN53555 regulators Required properties: - - compatible: one of "fcs,fan53555", "silergy,syr827", "silergy,syr828" + - compatible: one of "fcs,fan53555", "fcs,fan53526", "silergy,syr827" or + "silergy,syr828" - reg: I2C address Optional properties: diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt b/Documentation/devicetree/bindings/regulator/fixed-regulator.txt deleted file mode 100644 index 0c2a6c8a1536..000000000000 --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.txt +++ /dev/null @@ -1,35 +0,0 @@ -Fixed Voltage regulators - -Required properties: -- compatible: Must be "regulator-fixed"; -- regulator-name: Defined in regulator.txt as optional, but required here. - -Optional properties: -- gpio: gpio to use for enable control -- startup-delay-us: startup time in microseconds -- enable-active-high: Polarity of GPIO is Active high -If this property is missing, the default assumed is Active low. -- gpio-open-drain: GPIO is open drain type. - If this property is missing then default assumption is false. --vin-supply: Input supply name. - -Any property defined as part of the core regulator -binding, defined in regulator.txt, can also be used. -However a fixed voltage regulator is expected to have the -regulator-min-microvolt and regulator-max-microvolt -to be the same. - -Example: - - abc: fixedregulator@0 { - compatible = "regulator-fixed"; - regulator-name = "fixed-supply"; - regulator-min-microvolt = <1800000>; - regulator-max-microvolt = <1800000>; - gpio = <&gpio1 16 0>; - startup-delay-us = <70000>; - enable-active-high; - regulator-boot-on; - gpio-open-drain; - vin-supply = <&parent_reg>; - }; diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml new file mode 100644 index 000000000000..d289c2f7455a --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/fixed-regulator.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Fixed Voltage regulators + +maintainers: + - Liam Girdwood <lgirdwood@gmail.com> + - Mark Brown <broonie@kernel.org> + +description: + Any property defined as part of the core regulator binding, defined in + regulator.txt, can also be used. However a fixed voltage regulator is + expected to have the regulator-min-microvolt and regulator-max-microvolt + to be the same. + +properties: + compatible: + const: regulator-fixed + + regulator-name: true + + gpio: + description: gpio to use for enable control + maxItems: 1 + + startup-delay-us: + description: startup time in microseconds + $ref: /schemas/types.yaml#/definitions/uint32 + + enable-active-high: + description: + Polarity of GPIO is Active high. If this property is missing, + the default assumed is Active low. + type: boolean + + gpio-open-drain: + description: + GPIO is open drain type. If this property is missing then default + assumption is false. + type: boolean + + vin-supply: + description: Input supply phandle. + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - compatible + - regulator-name + +examples: + - | + reg_1v8: regulator-1v8 { + compatible = "regulator-fixed"; + regulator-name = "1v8"; + regulator-min-microvolt = <1800000>; + regulator-max-microvolt = <1800000>; + gpio = <&gpio1 16 0>; + startup-delay-us = <70000>; + enable-active-high; + regulator-boot-on; + gpio-open-drain; + vin-supply = <&parent_reg>; + }; +... diff --git a/Documentation/devicetree/bindings/regulator/max77650-regulator.txt b/Documentation/devicetree/bindings/regulator/max77650-regulator.txt new file mode 100644 index 000000000000..f1cbe813c30f --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/max77650-regulator.txt @@ -0,0 +1,41 @@ +Regulator driver for MAX77650 PMIC from Maxim Integrated. + +This module is part of the MAX77650 MFD device. For more details +see Documentation/devicetree/bindings/mfd/max77650.txt. + +The regulator controller is represented as a sub-node of the PMIC node +on the device tree. + +The device has a single LDO regulator and a SIMO buck-boost regulator with +three independent power rails. + +Required properties: +-------------------- +- compatible: Must be "maxim,max77650-regulator" + +Each rail must be instantiated under the regulators subnode of the top PMIC +node. Up to four regulators can be defined. For standard regulator properties +refer to Documentation/devicetree/bindings/regulator/regulator.txt. + +Available regulator compatible strings are: "ldo", "sbb0", "sbb1", "sbb2". + +Example: +-------- + + regulators { + compatible = "maxim,max77650-regulator"; + + max77650_ldo: regulator@0 { + regulator-compatible = "ldo"; + regulator-name = "max77650-ldo"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <2937500>; + }; + + max77650_sbb0: regulator@1 { + regulator-compatible = "sbb0"; + regulator-name = "max77650-sbb0"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1587500>; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt b/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt new file mode 100644 index 000000000000..b8f843fa6092 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt @@ -0,0 +1,143 @@ +MCP16502 PMIC + +Required properties: +- compatible: "microchip,mcp16502" +- reg: I2C slave address +- lpm-gpios: GPIO for LPM pin. Note that this GPIO *must* remain high during + suspend-to-ram, keeping the PMIC into HIBERNATE mode. +- regulators: A node that houses a sub-node for each regulator within + the device. Each sub-node is identified using the node's + name. The content of each sub-node is defined by the + standard binding for regulators; see regulator.txt. + +Regualtors of MCP16502 PMIC: +1) VDD_IO - Buck (1.2 - 3.7 V) +2) VDD_DDR - Buck (0.6 - 1.85 V) +3) VDD_CORE - Buck (0.6 - 1.85 V) +4) VDD_OTHER - BUCK (0.6 - 1.85 V) +5) LDO1 - LDO (1.2 - 3.7 V) +6) LDO2 - LDO (1.2 - 3.7 V) + +Regulator modes: +2 - FPWM: higher precision, higher consumption +4 - AutoPFM: lower precision, lower consumption + +Each regulator is defined using the standard binding for regulators. + +Example: + +mcp16502@5b { + compatible = "microchip,mcp16502"; + reg = <0x5b>; + status = "okay"; + lpm-gpios = <&pioBU 7 GPIO_ACTIVE_HIGH>; + + regulators { + VDD_IO { + regulator-name = "VDD_IO"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3700000>; + regulator-initial-mode = <2>; + regulator-allowed-modes = <2>, <4>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + regulator-mode = <4>; + }; + + regulator-state-mem { + regulator-off-in-suspend; + regulator-mode = <4>; + }; + }; + + VDD_DDR { + regulator-name = "VDD_DDR"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1850000>; + regulator-initial-mode = <2>; + regulator-allowed-modes = <2>, <4>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + regulator-mode = <4>; + }; + + regulator-state-mem { + regulator-on-in-suspend; + regulator-mode = <4>; + }; + }; + + VDD_CORE { + regulator-name = "VDD_CORE"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1850000>; + regulator-initial-mode = <2>; + regulator-allowed-modes = <2>, <4>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + regulator-mode = <4>; + }; + + regulator-state-mem { + regulator-off-in-suspend; + regulator-mode = <4>; + }; + }; + + VDD_OTHER { + regulator-name = "VDD_OTHER"; + regulator-min-microvolt = <600000>; + regulator-max-microvolt = <1850000>; + regulator-initial-mode = <2>; + regulator-allowed-modes = <2>, <4>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + regulator-mode = <4>; + }; + + regulator-state-mem { + regulator-off-in-suspend; + regulator-mode = <4>; + }; + }; + + LDO1 { + regulator-name = "LDO1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3700000>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + }; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + LDO2 { + regulator-name = "LDO2"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3700000>; + regulator-always-on; + + regulator-state-standby { + regulator-on-in-suspend; + }; + + regulator-state-mem { + regulator-off-in-suspend; + }; + }; + + }; +}; diff --git a/Documentation/devicetree/bindings/regulator/pfuze100.txt b/Documentation/devicetree/bindings/regulator/pfuze100.txt index f9be1acf891c..4d3b12b92cb3 100644 --- a/Documentation/devicetree/bindings/regulator/pfuze100.txt +++ b/Documentation/devicetree/bindings/regulator/pfuze100.txt @@ -8,7 +8,7 @@ Optional properties: - fsl,pfuze-support-disable-sw: Boolean, if present disable all unused switch regulators to save power consumption. Attention, ensure that all important regulators (e.g. DDR ref, DDR supply) has set the "regulator-always-on" - property. If not present, the switched regualtors are always on and can't be + property. If not present, the switched regulators are always on and can't be disabled. This binding is a workaround to keep backward compatibility with old dtb's which rely on the fact that the switched regulators are always on and don't mark them explicit as "regulator-always-on". diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index a7cd36877bfe..0a3f087d5844 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -33,13 +33,16 @@ Optional properties: decreases of any level. This is useful for regulators with exponential voltage changes. - regulator-soft-start: Enable soft start so that voltage ramps slowly +- regulator-state-standby sub-root node for Standby mode + : equivalent with standby Linux sleep state, which provides energy savings + with a relatively quick transition back time. - regulator-state-mem sub-root node for Suspend-to-RAM mode : suspend to memory, the device goes to sleep, but all data stored in memory, only some external interrupt can wake the device. - regulator-state-disk sub-root node for Suspend-to-DISK mode : suspend to disk, this state operates similarly to Suspend-to-RAM, but includes a final step of writing memory contents to disk. -- regulator-state-[mem/disk] node has following common properties: +- regulator-state-[mem/disk/standby] node has following common properties: - regulator-on-in-suspend: regulator should be on in suspend state. - regulator-off-in-suspend: regulator should be off in suspend state. - regulator-suspend-min-microvolt: minimum voltage may be set in @@ -76,8 +79,11 @@ Optional properties: - regulator-coupled-with: Regulators with which the regulator is coupled. The linkage is 2-way - all coupled regulators should be linked with each other. A regulator should not be coupled with its supplier. -- regulator-coupled-max-spread: Max spread between voltages of coupled regulators - in microvolts. +- regulator-coupled-max-spread: Array of maximum spread between voltages of + coupled regulators in microvolts, each value in the array relates to the + corresponding couple specified by the regulator-coupled-with property. +- regulator-max-step-microvolt: Maximum difference between current and target + voltages that can be changed safely in a single step. Deprecated properties: - regulator-compatible: If a regulator chip contains multiple diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt b/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt new file mode 100644 index 000000000000..698cfc3bc3dd --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/rohm,bd70528-regulator.txt @@ -0,0 +1,68 @@ +ROHM BD70528 Power Management Integrated Circuit regulator bindings + +Required properties: + - regulator-name: should be "buck1", "buck2", "buck3", "ldo1", "ldo2", "ldo3", + "led_ldo1", "led_ldo2" + +List of regulators provided by this controller. BD70528 regulators node +should be sub node of the BD70528 MFD node. See BD70528 MFD bindings at +Documentation/devicetree/bindings/mfd/rohm,bd70528-pmic.txt + +The valid names for BD70528 regulator nodes are: +BUCK1, BUCK2, BUCK3, LDO1, LDO2, LDO3, LED_LDO1, LED_LDO2 + +Optional properties: +- Any optional property defined in bindings/regulator/regulator.txt + +Example: +regulators { + buck1: BUCK1 { + regulator-name = "buck1"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3400000>; + regulator-boot-on; + regulator-ramp-delay = <125>; + }; + buck2: BUCK2 { + regulator-name = "buck2"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + regulator-ramp-delay = <125>; + }; + buck3: BUCK3 { + regulator-name = "buck3"; + regulator-min-microvolt = <800000>; + regulator-max-microvolt = <1800000>; + regulator-boot-on; + regulator-ramp-delay = <250>; + }; + ldo1: LDO1 { + regulator-name = "ldo1"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + ldo2: LDO2 { + regulator-name = "ldo2"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + regulator-boot-on; + }; + + ldo3: LDO3 { + regulator-name = "ldo3"; + regulator-min-microvolt = <1650000>; + regulator-max-microvolt = <3300000>; + }; + led_ldo1: LED_LDO1 { + regulator-name = "led_ldo1"; + regulator-min-microvolt = <200000>; + regulator-max-microvolt = <300000>; + }; + led_ldo2: LED_LDO2 { + regulator-name = "led_ldo2"; + regulator-min-microvolt = <200000>; + regulator-max-microvolt = <300000>; + }; +}; diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.txt b/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.txt index 4b98ca26e61a..cbce62c22b60 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.txt @@ -27,8 +27,38 @@ BUCK1, BUCK2, BUCK3, BUCK4, BUCK5, BUCK6 LDO1, LDO2, LDO3, LDO4, LDO5, LDO6 Optional properties: +- rohm,dvs-run-voltage : PMIC default "RUN" state voltage in uV. + See below table for bucks which support this. +- rohm,dvs-idle-voltage : PMIC default "IDLE" state voltage in uV. + See below table for bucks which support this. +- rohm,dvs-suspend-voltage : PMIC default "SUSPEND" state voltage in uV. + See below table for bucks which support this. - Any optional property defined in bindings/regulator/regulator.txt +Supported default DVS states: + +BD71837: +buck | dvs-run-voltage | dvs-idle-voltage | dvs-suspend-voltage +----------------------------------------------------------------------------- +1 | supported | supported | supported +---------------------------------------------------------------------------- +2 | supported | supported | not supported +---------------------------------------------------------------------------- +3 | supported | not supported | not supported +---------------------------------------------------------------------------- +4 | supported | not supported | not supported +---------------------------------------------------------------------------- +rest | not supported | not supported | not supported + +BD71847: +buck | dvs-run-voltage | dvs-idle-voltage | dvs-suspend-voltage +----------------------------------------------------------------------------- +1 | supported | supported | supported +---------------------------------------------------------------------------- +2 | supported | supported | not supported +---------------------------------------------------------------------------- +rest | not supported | not supported | not supported + Example: regulators { buck1: BUCK1 { @@ -36,7 +66,11 @@ regulators { regulator-min-microvolt = <700000>; regulator-max-microvolt = <1300000>; regulator-boot-on; + regulator-always-on; regulator-ramp-delay = <1250>; + rohm,dvs-run-voltage = <900000>; + rohm,dvs-idle-voltage = <850000>; + rohm,dvs-suspend-voltage = <800000>; }; buck2: BUCK2 { regulator-name = "buck2"; @@ -45,18 +79,22 @@ regulators { regulator-boot-on; regulator-always-on; regulator-ramp-delay = <1250>; + rohm,dvs-run-voltage = <1000000>; + rohm,dvs-idle-voltage = <900000>; }; buck3: BUCK3 { regulator-name = "buck3"; regulator-min-microvolt = <700000>; regulator-max-microvolt = <1300000>; regulator-boot-on; + rohm,dvs-run-voltage = <1000000>; }; buck4: BUCK4 { regulator-name = "buck4"; regulator-min-microvolt = <700000>; regulator-max-microvolt = <1300000>; regulator-boot-on; + rohm,dvs-run-voltage = <1000000>; }; buck5: BUCK5 { regulator-name = "buck5"; diff --git a/Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt b/Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt index a3f476240565..6189df71ea98 100644 --- a/Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt +++ b/Documentation/devicetree/bindings/regulator/st,stpmic1-regulator.txt @@ -23,16 +23,14 @@ Switches are fixed voltage regulators with only enable/disable capability. Optional properties: - st,mask-reset: mask reset for this regulator: the regulator configuration is maintained during pmic reset. -- regulator-pull-down: enable high pull down - if not specified light pull down is used - regulator-over-current-protection: if set, all regulators are switched off in case of over-current detection on this regulator, if not set, the driver only sends an over-current event. -- interrupt-parent: phandle to the parent interrupt controller - interrupts: index of current limit detection interrupt - <regulator>-supply: phandle to the parent supply/regulator node each regulator supply can be described except vref_ddr. +- regulator-active-discharge: can be used on pwr_sw1 and pwr_sw2. Example: regulators { @@ -43,7 +41,6 @@ regulators { vdd_core: buck1 { regulator-name = "vdd_core"; interrupts = <IT_CURLIM_BUCK1 0>; - interrupt-parent = <&pmic>; st,mask-reset; regulator-pull-down; regulator-min-microvolt = <700000>; @@ -53,7 +50,6 @@ regulators { v3v3: buck4 { regulator-name = "v3v3"; interrupts = <IT_CURLIM_BUCK4 0>; - interrupt-parent = <&mypmic>; regulator-min-microvolt = <3300000>; regulator-max-microvolt = <3300000>; diff --git a/Documentation/devicetree/bindings/regulator/tps65218.txt b/Documentation/devicetree/bindings/regulator/tps65218.txt index 02f0e9bbfbf8..54aded3b78e2 100644 --- a/Documentation/devicetree/bindings/regulator/tps65218.txt +++ b/Documentation/devicetree/bindings/regulator/tps65218.txt @@ -71,8 +71,13 @@ tps65218: tps65218@24 { regulator-always-on; }; + ls2: regulator-ls2 { + regulator-min-microamp = <100000>; + regulator-max-microamp = <1000000>; + }; + ls3: regulator-ls3 { - regulator-min-microvolt = <100000>; - regulator-max-microvolt = <1000000>; + regulator-min-microamp = <100000>; + regulator-max-microamp = <1000000>; }; }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt new file mode 100644 index 000000000000..a842a782b557 --- /dev/null +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp-pil.txt @@ -0,0 +1,126 @@ +Qualcomm Technology Inc. ADSP Peripheral Image Loader + +This document defines the binding for a component that loads and boots firmware +on the Qualcomm Technology Inc. ADSP Hexagon core. + +- compatible: + Usage: required + Value type: <string> + Definition: must be one of: + "qcom,sdm845-adsp-pil" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: must specify the base address and size of the qdsp6ss register + +- interrupts-extended: + Usage: required + Value type: <prop-encoded-array> + Definition: must list the watchdog, fatal IRQs ready, handover and + stop-ack IRQs + +- interrupt-names: + Usage: required + Value type: <stringlist> + Definition: must be "wdog", "fatal", "ready", "handover", "stop-ack" + +- clocks: + Usage: required + Value type: <prop-encoded-array> + Definition: List of 8 phandle and clock specifier pairs for the adsp. + +- clock-names: + Usage: required + Value type: <stringlist> + Definition: List of clock input name strings sorted in the same + order as the clocks property. Definition must have + "xo", "sway_cbcr", "lpass_aon", "lpass_ahbs_aon_cbcr", + "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", "qdsp6ss_sleep" + and "qdsp6ss_core". + +- power-domains: + Usage: required + Value type: <phandle> + Definition: reference to cx power domain node. + +- resets: + Usage: required + Value type: <phandle> + Definition: reference to the list of 2 reset-controller for the adsp. + +- reset-names: + Usage: required + Value type: <stringlist> + Definition: must be "pdc_sync" and "cc_lpass" + +- qcom,halt-regs: + Usage: required + Value type: <prop-encoded-array> + Definition: a phandle reference to a syscon representing TCSR followed + by the offset within syscon for lpass halt register. + +- memory-region: + Usage: required + Value type: <phandle> + Definition: reference to the reserved-memory for the ADSP + +- qcom,smem-states: + Usage: required + Value type: <phandle> + Definition: reference to the smem state for requesting the ADSP to + shut down + +- qcom,smem-state-names: + Usage: required + Value type: <stringlist> + Definition: must be "stop" + + += SUBNODES +The adsp node may have an subnode named "glink-edge" that describes the +communication edge, channels and devices related to the ADSP. +See ../soc/qcom/qcom,glink.txt for details on how to describe these. + += EXAMPLE +The following example describes the resources needed to boot control the +ADSP, as it is found on SDM845 boards. + + remoteproc@17300000 { + compatible = "qcom,sdm845-adsp-pil"; + reg = <0x17300000 0x40c>; + + interrupts-extended = <&intc GIC_SPI 162 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 0 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 1 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 2 IRQ_TYPE_EDGE_RISING>, + <&adsp_smp2p_in 3 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "wdog", "fatal", "ready", + "handover", "stop-ack"; + + clocks = <&rpmhcc RPMH_CXO_CLK>, + <&gcc GCC_LPASS_SWAY_CLK>, + <&lpasscc LPASS_AUDIO_WRAPPER_AON_CLK>, + <&lpasscc LPASS_Q6SS_AHBS_AON_CLK>, + <&lpasscc LPASS_Q6SS_AHBM_AON_CLK>, + <&lpasscc LPASS_QDSP6SS_XO_CLK>, + <&lpasscc LPASS_QDSP6SS_SLEEP_CLK>, + <&lpasscc LPASS_QDSP6SS_CORE_CLK>; + clock-names = "xo", "sway_cbcr", "lpass_aon", + "lpass_ahbs_aon_cbcr", + "lpass_ahbm_aon_cbcr", "qdsp6ss_xo", + "qdsp6ss_sleep", "qdsp6ss_core"; + + power-domains = <&rpmhpd SDM845_CX>; + + resets = <&pdc_reset PDC_AUDIO_SYNC_RESET>, + <&aoss_reset AOSS_CC_LPASS_RESTART>; + reset-names = "pdc_sync", "cc_lpass"; + + qcom,halt-regs = <&tcsr_mutex_regs 0x22000>; + + memory-region = <&pil_adsp_mem>; + + qcom,smem-states = <&adsp_smp2p_out 0>; + qcom,smem-state-names = "stop"; + }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt index 728e4193f7a6..9c0cff3a5ed8 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,adsp.txt @@ -10,6 +10,11 @@ on the Qualcomm ADSP Hexagon core. "qcom,msm8974-adsp-pil" "qcom,msm8996-adsp-pil" "qcom,msm8996-slpi-pil" + "qcom,qcs404-adsp-pas" + "qcom,qcs404-cdsp-pas" + "qcom,qcs404-wcss-pas" + "qcom,sdm845-adsp-pas" + "qcom,sdm845-cdsp-pas" - interrupts-extended: Usage: required diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt index 601dd9f389aa..9ff5b0309417 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt +++ b/Documentation/devicetree/bindings/remoteproc/qcom,q6v5.txt @@ -53,13 +53,17 @@ on the Qualcomm Hexagon core. Definition: reference to the reset-controller for the modem sub-system reference to the list of 3 reset-controllers for the wcss sub-system + reference to the list of 2 reset-controllers for the modem + sub-system on SDM845 SoCs - reset-names: Usage: required Value type: <stringlist> Definition: must be "mss_restart" for the modem sub-system - Definition: must be "wcss_aon_reset", "wcss_reset", "wcss_q6_reset" - for the wcss syb-system + must be "wcss_aon_reset", "wcss_reset", "wcss_q6_reset" + for the wcss sub-system + must be "mss_restart", "pdc_reset" for the modem + sub-system on SDM845 SoCs - cx-supply: - mss-supply: diff --git a/Documentation/devicetree/bindings/reserved-memory/xen,shared-memory.txt b/Documentation/devicetree/bindings/reserved-memory/xen,shared-memory.txt new file mode 100644 index 000000000000..d483a2103d70 --- /dev/null +++ b/Documentation/devicetree/bindings/reserved-memory/xen,shared-memory.txt @@ -0,0 +1,24 @@ +* Xen hypervisor reserved-memory binding + +Expose one or more memory regions as reserved-memory to the guest +virtual machine. Typically, a region is configured at VM creation time +to be a shared memory area across multiple virtual machines for +communication among them. + +For each of these pre-shared memory regions, a range is exposed under +the /reserved-memory node as a child node. Each range sub-node is named +xen-shmem@<address> and has the following properties: + +- compatible: + compatible = "xen,shared-memory-v1" + +- reg: + the base guest physical address and size of the shared memory region + +- xen,offset: (borrower VMs only) + 64 bit integer offset within the owner virtual machine's shared + memory region used for the mapping in the borrower VM. + +- xen,id: + a string that identifies the shared memory region as specified in + the VM config file diff --git a/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt b/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt new file mode 100644 index 000000000000..6e5341b4f891 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/brcm,brcmstb-reset.txt @@ -0,0 +1,27 @@ +Broadcom STB SW_INIT-style reset controller +=========================================== + +Broadcom STB SoCs have a SW_INIT-style reset controller with separate +SET/CLEAR/STATUS registers and possibly multiple banks, each of 32 bit +reset lines. + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +Required properties: +- compatible: should be brcm,brcmstb-reset +- reg: register base and length +- #reset-cells: must be set to 1 + +Example: + + reset: reset-controller@8404318 { + compatible = "brcm,brcmstb-reset"; + reg = <0x8404318 0x30>; + #reset-cells = <1>; + }; + + ðernet_switch { + resets = <&reset>; + reset-names = "switch"; + }; diff --git a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt index 5e1afc3d8480..2ecf33815d18 100644 --- a/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt +++ b/Documentation/devicetree/bindings/reset/fsl,imx7-src.txt @@ -5,7 +5,9 @@ Please also refer to reset.txt in this directory for common reset controller binding usage. Required properties: -- compatible: Should be "fsl,imx7-src", "syscon" +- compatible: + - For i.MX7 SoCs should be "fsl,imx7d-src", "syscon" + - For i.MX8MQ SoCs should be "fsl,imx8mq-src", "syscon" - reg: should be register base and length as documented in the datasheet - interrupts: Should contain SRC interrupt @@ -44,4 +46,5 @@ Example: For list of all valid reset indicies see -<dt-bindings/reset/imx7-reset.h> +<dt-bindings/reset/imx7-reset.h> for i.MX7 and +<dt-bindings/reset/imx8mq-reset.h> for i.MX8MQ diff --git a/Documentation/devicetree/bindings/reset/qcom,pdc-global.txt b/Documentation/devicetree/bindings/reset/qcom,pdc-global.txt new file mode 100644 index 000000000000..a62a492843e7 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/qcom,pdc-global.txt @@ -0,0 +1,52 @@ +PDC Global +====================================== + +This binding describes a reset-controller found on PDC-Global (Power Domain +Controller) block for Qualcomm Technologies Inc SDM845 SoCs. + +Required properties: +- compatible: + Usage: required + Value type: <string> + Definition: must be: + "qcom,sdm845-pdc-global" + +- reg: + Usage: required + Value type: <prop-encoded-array> + Definition: must specify the base address and size of the register + space. + +- #reset-cells: + Usage: required + Value type: <uint> + Definition: must be 1; cell entry represents the reset index. + +Example: + +pdc_reset: reset-controller@b2e0000 { + compatible = "qcom,sdm845-pdc-global"; + reg = <0xb2e0000 0x20000>; + #reset-cells = <1>; +}; + +PDC reset clients +====================================== + +Device nodes that need access to reset lines should +specify them as a reset phandle in their corresponding node as +specified in reset.txt. + +For a list of all valid reset indices see +<dt-bindings/reset/qcom,sdm845-pdc.h> + +Example: + +modem-pil@4080000 { + ... + + resets = <&pdc_reset PDC_MODEM_SYNC_RESET>; + reset-names = "pdc_reset"; + + ... +}; diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.txt b/Documentation/devicetree/bindings/reset/renesas,rst.txt index 67e83b02e10b..b03c48a1150e 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.txt +++ b/Documentation/devicetree/bindings/reset/renesas,rst.txt @@ -16,8 +16,11 @@ Required properties: - "renesas,<soctype>-rst" for R-Car Gen2 and Gen3, and RZ/G Examples with soctypes are: - "renesas,r8a7743-rst" (RZ/G1M) + - "renesas,r8a7744-rst" (RZ/G1N) - "renesas,r8a7745-rst" (RZ/G1E) - "renesas,r8a77470-rst" (RZ/G1C) + - "renesas,r8a774a1-rst" (RZ/G2M) + - "renesas,r8a774c0-rst" (RZ/G2E) - "renesas,r8a7778-reset-wdt" (R-Car M1A) - "renesas,r8a7779-reset-wdt" (R-Car H1) - "renesas,r8a7790-rst" (R-Car H2) diff --git a/Documentation/devicetree/bindings/reset/socfpga-reset.txt b/Documentation/devicetree/bindings/reset/socfpga-reset.txt index 98c9f560e5c5..38fe34fd8b8a 100644 --- a/Documentation/devicetree/bindings/reset/socfpga-reset.txt +++ b/Documentation/devicetree/bindings/reset/socfpga-reset.txt @@ -1,7 +1,8 @@ Altera SOCFPGA Reset Manager Required properties: -- compatible : "altr,rst-mgr" +- compatible : "altr,rst-mgr" for (Cyclone5/Arria5/Arria10) + "altr,stratix10-rst-mgr","altr,rst-mgr" for Stratix10 ARM64 SoC - reg : Should contain 1 register ranges(address and length) - altr,modrst-offset : Should contain the offset of the first modrst register. - #reset-cells: 1 diff --git a/Documentation/devicetree/bindings/reset/uniphier-reset.txt b/Documentation/devicetree/bindings/reset/uniphier-reset.txt index 101743dda223..ea005177d20a 100644 --- a/Documentation/devicetree/bindings/reset/uniphier-reset.txt +++ b/Documentation/devicetree/bindings/reset/uniphier-reset.txt @@ -120,27 +120,30 @@ Example: }; -USB3 core reset ---------------- +Peripheral core reset in glue layer +----------------------------------- -USB3 core reset belongs to USB3 glue layer. Before using the core reset, -it is necessary to control the clocks and resets to enable this layer. -These clocks and resets should be described in each property. +Some peripheral core reset belongs to its own glue layer. Before using +this core reset, it is necessary to control the clocks and resets to enable +this layer. These clocks and resets should be described in each property. Required properties: - compatible: Should be - "socionext,uniphier-pro4-usb3-reset" - for Pro4 SoC - "socionext,uniphier-pxs2-usb3-reset" - for PXs2 SoC - "socionext,uniphier-ld20-usb3-reset" - for LD20 SoC - "socionext,uniphier-pxs3-usb3-reset" - for PXs3 SoC + "socionext,uniphier-pro4-usb3-reset" - for Pro4 SoC USB3 + "socionext,uniphier-pxs2-usb3-reset" - for PXs2 SoC USB3 + "socionext,uniphier-ld20-usb3-reset" - for LD20 SoC USB3 + "socionext,uniphier-pxs3-usb3-reset" - for PXs3 SoC USB3 + "socionext,uniphier-pro4-ahci-reset" - for Pro4 SoC AHCI + "socionext,uniphier-pxs2-ahci-reset" - for PXs2 SoC AHCI + "socionext,uniphier-pxs3-ahci-reset" - for PXs3 SoC AHCI - #reset-cells: Should be 1. - reg: Specifies offset and length of the register set for the device. -- clocks: A list of phandles to the clock gate for USB3 glue layer. +- clocks: A list of phandles to the clock gate for the glue layer. According to the clock-names, appropriate clocks are required. - clock-names: Should contain "gio", "link" - for Pro4 SoC "link" - for others -- resets: A list of phandles to the reset control for USB3 glue layer. +- resets: A list of phandles to the reset control for the glue layer. According to the reset-names, appropriate resets are required. - reset-names: Should contain "gio", "link" - for Pro4 SoC diff --git a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt new file mode 100644 index 000000000000..27a45fe5ecf1 --- /dev/null +++ b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.txt @@ -0,0 +1,52 @@ +-------------------------------------------------------------------------- + = Zynq UltraScale+ MPSoC reset driver binding = +-------------------------------------------------------------------------- +The Zynq UltraScale+ MPSoC has several different resets. + +See Chapter 36 of the Zynq UltraScale+ MPSoC TRM (UG) for more information +about zynqmp resets. + +Please also refer to reset.txt in this directory for common reset +controller binding usage. + +Required Properties: +- compatible: "xlnx,zynqmp-reset" +- #reset-cells: Specifies the number of cells needed to encode reset + line, should be 1 + +------- +Example +------- + +firmware { + zynqmp_firmware: zynqmp-firmware { + compatible = "xlnx,zynqmp-firmware"; + method = "smc"; + + zynqmp_reset: reset-controller { + compatible = "xlnx,zynqmp-reset"; + #reset-cells = <1>; + }; + }; +}; + +Specifying reset lines connected to IP modules +============================================== + +Device nodes that need access to reset lines should +specify them as a reset phandle in their corresponding node as +specified in reset.txt. + +For list of all valid reset indicies see +<dt-bindings/reset/xlnx-zynqmp-resets.h> + +Example: + +serdes: zynqmp_phy@fd400000 { + ... + + resets = <&zynqmp_reset ZYNQMP_RESET_SATA>; + reset-names = "sata_rst"; + + ... +}; diff --git a/Documentation/devicetree/bindings/rng/mtk-rng.txt b/Documentation/devicetree/bindings/rng/mtk-rng.txt index 366b99bff8cd..2bc89f133701 100644 --- a/Documentation/devicetree/bindings/rng/mtk-rng.txt +++ b/Documentation/devicetree/bindings/rng/mtk-rng.txt @@ -1,9 +1,10 @@ Device-Tree bindings for Mediatek random number generator -found in Mediatek SoC family +found in MediaTek SoC family Required properties: - compatible : Should be "mediatek,mt7622-rng", "mediatek,mt7623-rng" : for MT7622 + "mediatek,mt7629-rng", "mediatek,mt7623-rng" : for MT7629 "mediatek,mt7623-rng" : for MT7623 - clocks : list of clock specifiers, corresponding to entries in clock-names property; diff --git a/Documentation/devicetree/bindings/rtc/abracon,abx80x.txt b/Documentation/devicetree/bindings/rtc/abracon,abx80x.txt index be789685a1c2..2405e35a1bc0 100644 --- a/Documentation/devicetree/bindings/rtc/abracon,abx80x.txt +++ b/Documentation/devicetree/bindings/rtc/abracon,abx80x.txt @@ -16,6 +16,7 @@ Required properties: "abracon,ab1803" "abracon,ab1804" "abracon,ab1805" + "microcrystal,rv1805" Using "abracon,abx80x" will enable chip autodetection. - "reg": I2C bus address of the device @@ -27,4 +28,4 @@ and valid to enable charging: - "abracon,tc-diode": should be "standard" (0.6V) or "schottky" (0.3V) - "abracon,tc-resistor": should be <0>, <3>, <6> or <11>. 0 disables the output - resistor, the other values are in ohm. + resistor, the other values are in kOhm. diff --git a/Documentation/devicetree/bindings/rtc/cdns,rtc.txt b/Documentation/devicetree/bindings/rtc/cdns,rtc.txt new file mode 100644 index 000000000000..14a04487b432 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/cdns,rtc.txt @@ -0,0 +1,25 @@ +Cadence Real Time Clock + +The Cadence RTC controller with date, time and alarm capabilities. +The alarm may wake the system from low-power state. + +Required properties: +- compatible: Should be "cdns,rtc-r109v3" +- reg: Specifies base physical address and size of the register area. +- interrupts: A single interrupt specifier. +- clocks: Must contain two entries: + - pclk: APB registers clock + - ref_clk: reference 1Hz or 100Hz clock, depending on IP configuration + See ../clocks/clock-bindings.txt for details. + +Example: + rtc0: rtc@fd080000 { + compatible = "cdns,rtc-r109v3"; + reg = <0xfd080000 0x1000>; + + clock-names = "pclk", "ref_clk"; + clocks = <&sysclock>, <&refclock>; + + interrupt-parent = <&gic>; + interrupts = <0 6 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/rtc/isil,isl1208.txt b/Documentation/devicetree/bindings/rtc/isil,isl1208.txt new file mode 100644 index 000000000000..51f003006f04 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/isil,isl1208.txt @@ -0,0 +1,38 @@ +Intersil ISL1209/19 I2C RTC/Alarm chip with event in + +ISL12X9 have additional pins EVIN and #EVDET for tamper detection, while the +ISL1208 and ISL1218 do not. They are all use the same driver with the bindings +described here, with chip specific properties as noted. + +Required properties supported by the device: + - "compatible": Should be one of the following: + - "isil,isl1208" + - "isil,isl1209" + - "isil,isl1218" + - "isil,isl1219" + - "reg": I2C bus address of the device + +Optional properties: + - "interrupt-names": list which may contains "irq" and "evdet" + evdet applies to isl1209 and isl1219 only + - "interrupts": list of interrupts for "irq" and "evdet" + evdet applies to isl1209 and isl1219 only + - "isil,ev-evienb": Enable or disable internal pull on EVIN pin + Applies to isl1209 and isl1219 only + Possible values are 0 and 1 + Value 0 enables internal pull-up on evin pin, 1 disables it. + Default will leave the non-volatile configuration of the pullup + as is. + +Example isl1219 node with #IRQ pin connected to SoC gpio1 pin12 and #EVDET pin +connected to SoC gpio2 pin 24 and internal pull-up enabled in EVIN pin. + + isl1219: rtc@68 { + compatible = "isil,isl1219"; + reg = <0x68>; + interrupt-names = "irq", "evdet"; + interrupts-extended = <&gpio1 12 IRQ_TYPE_EDGE_FALLING>, + <&gpio2 24 IRQ_TYPE_EDGE_FALLING>; + isil,ev-evienb = <1>; + }; + diff --git a/Documentation/devicetree/bindings/rtc/isil,isl1219.txt b/Documentation/devicetree/bindings/rtc/isil,isl1219.txt deleted file mode 100644 index c3efd48e91c2..000000000000 --- a/Documentation/devicetree/bindings/rtc/isil,isl1219.txt +++ /dev/null @@ -1,29 +0,0 @@ -Intersil ISL1219 I2C RTC/Alarm chip with event in - -ISL1219 has additional pins EVIN and #EVDET for tamper detection. - -Required properties supported by the device: - - - "compatible": must be "isil,isl1219" - - "reg": I2C bus address of the device - -Optional properties: - - - "interrupt-names": list which may contains "irq" and "evdet" - - "interrupts": list of interrupts for "irq" and "evdet" - - "isil,ev-evienb": if present EV.EVIENB bit is set to the specified - value for proper operation. - - -Example isl1219 node with #IRQ pin connected to SoC gpio1 pin12 - and #EVDET pin connected to SoC gpio2 pin 24: - - isl1219: rtc@68 { - compatible = "isil,isl1219"; - reg = <0x68>; - interrupt-names = "irq", "evdet"; - interrupts-extended = <&gpio1 12 IRQ_TYPE_EDGE_FALLING>, - <&gpio2 24 IRQ_TYPE_EDGE_FALLING>; - isil,ev-evienb = <1>; - }; - diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt b/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt new file mode 100644 index 000000000000..d3e380ad712d --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf85063.txt @@ -0,0 +1,18 @@ +* NXP PCF85063 Real Time Clock + +Required properties: +- compatible: Should contain "nxp,pcf85063". +- reg: I2C address for chip. + +Optional property: +- quartz-load-femtofarads: The capacitive load of the quartz(x-tal), + expressed in femto Farad (fF). Valid values are 7000 and 12500. + Default value (if no value is specified) is 7000fF. + +Example: + +pcf85063: rtc@51 { + compatible = "nxp,pcf85063"; + reg = <0x51>; + quartz-load-femtofarads = <12500>; +}; diff --git a/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt b/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt new file mode 100644 index 000000000000..0b1080c60f63 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/nxp,pcf8523.txt @@ -0,0 +1,18 @@ +* NXP PCF8523 Real Time Clock + +Required properties: +- compatible: Should contain "nxp,pcf8523". +- reg: I2C address for chip. + +Optional property: +- quartz-load-femtofarads: The capacitive load of the quartz(x-tal), + expressed in femto Farad (fF). Valid values are 7000 and 12500. + Default value (if no value is specified) is 12500fF. + +Example: + +pcf8523: rtc@68 { + compatible = "nxp,pcf8523"; + reg = <0x68>; + quartz-load-femtofarads = <7000>; +}; diff --git a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt index 811124a36d16..1994f601800a 100644 --- a/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt +++ b/Documentation/devicetree/bindings/rtc/nxp,rtc-2123.txt @@ -2,6 +2,7 @@ NXP PCF2123 SPI Real Time Clock Required properties: - compatible: should be: "nxp,rtc-pcf2123" + or "microcrystal,rv2123" - reg: should be the SPI slave chipselect address Optional properties: diff --git a/Documentation/devicetree/bindings/rtc/pcf85363.txt b/Documentation/devicetree/bindings/rtc/pcf85363.txt index 76fdabc59742..94adc1cf93d9 100644 --- a/Documentation/devicetree/bindings/rtc/pcf85363.txt +++ b/Documentation/devicetree/bindings/rtc/pcf85363.txt @@ -1,8 +1,8 @@ -NXP PCF85363 Real Time Clock +NXP PCF85263/PCF85363 Real Time Clock ============================ Required properties: -- compatible: Should contain "nxp,pcf85363". +- compatible: Should contain "nxp,pcf85263" or "nxp,pcf85363". - reg: I2C address for chip. Optional properties: diff --git a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt index eebfbe04207a..eaee19b60960 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-ds1307.txt @@ -35,7 +35,7 @@ Optional properties: Should be given if internal trickle charger diode should be disabled Example: - rtc1: ds1339@68 { + ds1339: rtc@68 { compatible = "dallas,ds1339"; reg = <0x68>; interrupt-parent = <&gpio4>; diff --git a/Documentation/devicetree/bindings/rtc/rtc-meson.txt b/Documentation/devicetree/bindings/rtc/rtc-meson.txt new file mode 100644 index 000000000000..e921fe66a362 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc-meson.txt @@ -0,0 +1,35 @@ +* Amlogic Meson6, Meson8, Meson8b and Meson8m2 RTC + +Required properties: +- compatible: should be one of the following describing the hardware: + * "amlogic,meson6-rtc" + * "amlogic,meson8-rtc" + * "amlogic,meson8b-rtc" + * "amlogic,meson8m2-rtc" + +- reg: physical register space for the controller's memory mapped registers. +- interrupts: the interrupt line of the RTC block. +- clocks: reference to the external 32.768kHz crystal oscillator. +- vdd-supply: reference to the power supply of the RTC block. +- resets: reset controller reference to allow reset of the controller + +Optional properties for the battery-backed non-volatile memory: +- #address-cells: should be 1 to address the battery-backed non-volatile memory +- #size-cells: should be 1 to reference the battery-backed non-volatile memory + +Optional child nodes: +- see ../nvmem/nvmem.txt + +Example: + + rtc: rtc@740 { + compatible = "amlogic,meson6-rtc"; + reg = <0x740 0x14>; + interrupts = <GIC_SPI 72 IRQ_TYPE_EDGE_RISING>; + clocks = <&rtc32k_xtal>; + vdd-supply = <&rtc_vdd>; + resets = <&reset RESET_RTC>; + + #address-cells = <1>; + #size-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/rtc/rtc.txt b/Documentation/devicetree/bindings/rtc/rtc.txt new file mode 100644 index 000000000000..f4687c68c08c --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/rtc.txt @@ -0,0 +1,71 @@ +Generic device tree bindings for Real Time Clock devices +======================================================== + +This document describes generic bindings which can be used to describe Real Time +Clock devices in a device tree. + +Required properties +------------------- + +- compatible : name of RTC device following generic names recommended practice. + +For other required properties e.g. to describe register sets, +clocks, etc. check the binding documentation of the specific driver. + +Optional properties +------------------- + +- start-year : if provided, the default hardware range supported by the RTC is + shifted so the first usable year is the specified one. + +The following properties may not be supported by all drivers. However, if a +driver wants to support one of the below features, it should adapt the bindings +below. +- trickle-resistor-ohms : Selected resistor for trickle charger. Should be given + if trickle charger should be enabled +- trickle-diode-disable : Do not use internal trickle charger diode Should be + given if internal trickle charger diode should be + disabled +- wakeup-source : Enables wake up of host system on alarm +- quartz-load-femtofarads : The capacitive load of the quartz(x-tal), + expressed in femto Farad (fF). + The default value shall be listed (if optional), + and likewise all valid values. + +Trivial RTCs +------------ + +This is a list of trivial RTC devices that have simple device tree +bindings, consisting only of a compatible field, an address and +possibly an interrupt line. + + +Compatible Vendor / Chip +========== ============= +abracon,abb5zes3 AB-RTCMC-32.768kHz-B5ZE-S3: Real Time Clock/Calendar Module with I2C Interface +abracon,abeoz9 AB-RTCMC-32.768kHz-EOZ9: Real Time Clock/Calendar Module with I2C Interface +dallas,ds1374 I2C, 32-Bit Binary Counter Watchdog RTC with Trickle Charger and Reset Input/Output +dallas,ds1672 Dallas DS1672 Real-time Clock +dallas,ds3232 Extremely Accurate I²C RTC with Integrated Crystal and SRAM +epson,rx8010 I2C-BUS INTERFACE REAL TIME CLOCK MODULE +epson,rx8571 I2C-BUS INTERFACE REAL TIME CLOCK MODULE with Battery Backed RAM +epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE +emmicro,em3027 EM Microelectronic EM3027 Real-time Clock +isil,isl1208 Intersil ISL1208 Low Power RTC with Battery Backed SRAM +isil,isl1218 Intersil ISL1218 Low Power RTC with Battery Backed SRAM +isil,isl12022 Intersil ISL12022 Real-time Clock +microcrystal,rv3028 Real Time Clock Module with I2C-Bus +microcrystal,rv3029 Real Time Clock Module with I2C-Bus +microcrystal,rv8523 Real Time Clock +nxp,pcf2127 Real-time clock +nxp,pcf2129 Real-time clock +nxp,pcf8563 Real-time clock/calendar +pericom,pt7c4338 Real-time Clock Module +ricoh,r2025sd I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,r2221tl I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rs5c372a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rs5c372b I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC +sii,s35390a 2-wire CMOS real-time clock +whwave,sd3078 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC diff --git a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt index 12c083c1140a..6b732c41392b 100644 --- a/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt +++ b/Documentation/devicetree/bindings/rtc/sun6i-rtc.txt @@ -3,25 +3,44 @@ RTC controller for the Allwinner A31 Required properties: -- compatible : Should be "allwinner,sun6i-a31-rtc" +- compatible : Should be one of the following combinations: + - "allwinner,sun6i-a31-rtc" + - "allwinner,sun8i-a23-rtc" + - "allwinner,sun8i-h3-rtc" + - "allwinner,sun8i-r40-rtc", "allwinner,sun8i-h3-rtc" + - "allwinner,sun8i-v3-rtc" + - "allwinner,sun50i-a64-rtc", "allwinner,sun8i-h3-rtc" + - "allwinner,sun50i-h5-rtc" + + Where there are two or more compatible strings, this + denotes the hardware covered by the most specific one + is backward-compatible with the latter ones, and the + implementation for the latter ones can be used, albeit + with reduced functionality. + - reg : physical base address of the controller and length of 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 : names of the LOSC and its external output clocks 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. +- clock-output-names : names of up to three clock outputs. See below. +- #clock-cells : must be equal to 1. + +The RTC provides the following clocks at the given indices: +- 0: LOSC +- 1: LOSC external output, known as X32KFOUT in the datasheet. + This clock is not available on the A31 and is deprecated for old + device trees still using the "allwinner,sun6i-a31-rtc" compatible. +- 2: InternalOSC, or internal RC oscillator (A64/H3/H5 only) Example: rtc: rtc@1f00000 { compatible = "allwinner,sun6i-a31-rtc"; - reg = <0x01f00000 0x54>; + reg = <0x01f00000 0x400>; interrupts = <0 40 4>, <0 41 4>; - clock-output-names = "osc32k", "osc32k-out"; + 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 aeb6db4e35c3..3cba12f855b7 100644 --- a/Documentation/devicetree/bindings/serial/8250.txt +++ b/Documentation/devicetree/bindings/serial/8250.txt @@ -21,6 +21,7 @@ Required properties: - "altr,16550-FIFO128" - "fsl,16550-FIFO64" - "fsl,ns16550" + - "intel,xscale-uart" - "ti,da830-uart" - "aspeed,ast2400-vuart" - "aspeed,ast2500-vuart" @@ -51,6 +52,7 @@ Optional properties: - tx-threshold: Specify the TX FIFO low water indication for parts with programmable TX FIFO thresholds. - resets : phandle + reset specifier pairs +- overrun-throttle-ms : how long to pause uart rx when input overrun is encountered. Note: * fsl,ns16550: diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt index 6bd3f2e93d61..21483ba820bc 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.txt +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.txt @@ -8,6 +8,8 @@ Required properties: on LS1021A SoC with 32-bit big-endian register organization - "fsl,imx7ulp-lpuart" for lpuart compatible with the one integrated on i.MX7ULP SoC with 32-bit little-endian register organization + - "fsl,imx8qxp-lpuart" for lpuart compatible with the one integrated + on i.MX8QXP SoC with 32-bit little-endian register organization - reg : Address and length of the register set for the device - interrupts : Should contain uart interrupt - clocks : phandle + clock specifier pairs, one for each entry in clock-names diff --git a/Documentation/devicetree/bindings/serial/ingenic,uart.txt b/Documentation/devicetree/bindings/serial/ingenic,uart.txt index c3c6406d5cfe..24ed8769f4af 100644 --- a/Documentation/devicetree/bindings/serial/ingenic,uart.txt +++ b/Documentation/devicetree/bindings/serial/ingenic,uart.txt @@ -6,7 +6,8 @@ Required properties: - "ingenic,jz4760-uart", - "ingenic,jz4770-uart", - "ingenic,jz4775-uart", - - "ingenic,jz4780-uart". + - "ingenic,jz4780-uart", + - "ingenic,x1000-uart". - reg : offset and length of the register set for the device. - interrupts : should contain uart interrupt. - clocks : phandles to the module & baud clocks. diff --git a/Documentation/devicetree/bindings/serial/lantiq_asc.txt b/Documentation/devicetree/bindings/serial/lantiq_asc.txt index 3acbd309ab9d..40e81a5818f6 100644 --- a/Documentation/devicetree/bindings/serial/lantiq_asc.txt +++ b/Documentation/devicetree/bindings/serial/lantiq_asc.txt @@ -6,8 +6,23 @@ Required properties: - interrupts: the 3 (tx rx err) interrupt numbers. The interrupt specifier depends on the interrupt-parent interrupt controller. +Optional properties: +- clocks: Should contain frequency clock and gate clock +- clock-names: Should be "freq" and "asc" + Example: +asc0: serial@16600000 { + compatible = "lantiq,asc"; + reg = <0x16600000 0x100000>; + interrupt-parent = <&gic>; + interrupts = <GIC_SHARED 103 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 105 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SHARED 106 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cgu CLK_SSX4>, <&cgu GCLK_UART>; + clock-names = "freq", "asc"; +}; + asc1: serial@e100c00 { compatible = "lantiq,asc"; reg = <0xE100C00 0x400>; diff --git a/Documentation/devicetree/bindings/serial/milbeaut-uart.txt b/Documentation/devicetree/bindings/serial/milbeaut-uart.txt new file mode 100644 index 000000000000..3d2fb1a7ba94 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/milbeaut-uart.txt @@ -0,0 +1,21 @@ +Socionext Milbeaut UART controller + +Required properties: +- compatible: should be "socionext,milbeaut-usio-uart". +- reg: offset and length of the register set for the device. +- interrupts: two interrupts specifier. +- interrupt-names: should be "rx", "tx". +- clocks: phandle to the input clock. + +Optional properties: +- auto-flow-control: flow control enable. + +Example: + usio1: usio_uart@1e700010 { + compatible = "socionext,milbeaut-usio-uart"; + reg = <0x1e700010 0x10>; + interrupts = <0 141 0x4>, <0 149 0x4>; + interrupt-names = "rx", "tx"; + clocks = <&clk 2>; + auto-flow-control; + }; diff --git a/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt b/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt new file mode 100644 index 000000000000..085a8591accd --- /dev/null +++ b/Documentation/devicetree/bindings/serial/nvidia,tegra194-tcu.txt @@ -0,0 +1,35 @@ +NVIDIA Tegra Combined UART (TCU) + +The TCU is a system for sharing a hardware UART instance among multiple +systems within the Tegra SoC. It is implemented through a mailbox- +based protocol where each "virtual UART" has a pair of mailboxes, one +for transmitting and one for receiving, that is used to communicate +with the hardware implementing the TCU. + +Required properties: +- name : Should be tcu +- compatible + Array of strings + One of: + - "nvidia,tegra194-tcu" +- mbox-names: + "rx" - Mailbox for receiving data from hardware UART + "tx" - Mailbox for transmitting data to hardware UART +- mboxes: Mailboxes corresponding to the mbox-names. + +This node is a mailbox consumer. See the following files for details of +the mailbox subsystem, and the specifiers implemented by the relevant +provider(s): + +- .../mailbox/mailbox.txt +- .../mailbox/nvidia,tegra186-hsp.txt + +Example bindings: +----------------- + +tcu: tcu { + compatible = "nvidia,tegra194-tcu"; + mboxes = <&hsp_top0 TEGRA_HSP_MBOX_TYPE_SM 0>, + <&hsp_aon TEGRA_HSP_MBOX_TYPE_SM 1>; + mbox-names = "rx", "tx"; +}; diff --git a/Documentation/devicetree/bindings/serial/omap_serial.txt b/Documentation/devicetree/bindings/serial/omap_serial.txt index c35d5ece1156..0a9b5444f4e6 100644 --- a/Documentation/devicetree/bindings/serial/omap_serial.txt +++ b/Documentation/devicetree/bindings/serial/omap_serial.txt @@ -22,6 +22,8 @@ Optional properties: - dma-names : "rx" for receive channel, "tx" for transmit channel. - rs485-rts-delay, rs485-rx-during-tx, linux,rs485-enabled-at-boot-time: see rs485.txt - rs485-rts-active-high: drive RTS high when sending (default is low). +- clocks: phandle to the functional clock as per + Documentation/devicetree/bindings/clock/clock-bindings.txt Example: diff --git a/Documentation/devicetree/bindings/serial/pl011.txt b/Documentation/devicetree/bindings/serial/pl011.txt deleted file mode 100644 index 77863aefe9ef..000000000000 --- a/Documentation/devicetree/bindings/serial/pl011.txt +++ /dev/null @@ -1,51 +0,0 @@ -* ARM AMBA Primecell PL011 serial UART - -Required properties: -- compatible: must be "arm,primecell", "arm,pl011", "zte,zx296702-uart" -- reg: exactly one register range with length 0x1000 -- interrupts: exactly one interrupt specifier - -Optional properties: -- pinctrl: - When present, must have one state named "default", - and may contain a second name named "sleep". The former - state sets up pins for ordinary operation whereas - the latter state will put the associated pins to sleep - when the UART is unused -- clocks: - When present, the first clock listed must correspond to - the clock named UARTCLK on the IP block, i.e. the clock - to the external serial line, whereas the second clock - must correspond to the PCLK clocking the internal logic - of the block. Just listing one clock (the first one) is - deprecated. -- clock-names: - When present, the first clock listed must be named - "uartclk" and the second clock listed must be named - "apb_pclk" -- dmas: - When present, may have one or two dma channels. - The first one must be named "rx", the second one - must be named "tx". -- auto-poll: - Enables polling when using RX DMA. -- poll-rate-ms: - Rate at which poll occurs when auto-poll is set, - default 100ms. -- poll-timeout-ms: - Poll timeout when auto-poll is set, default - 3000ms. - -See also bindings/arm/primecell.txt - -Example: - -uart@80120000 { - compatible = "arm,pl011", "arm,primecell"; - reg = <0x80120000 0x1000>; - interrupts = <0 11 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&dma 13 0 0x2>, <&dma 13 0 0x0>; - dma-names = "rx", "tx"; - clocks = <&foo_clk>, <&bar_clk>; - clock-names = "uartclk", "apb_pclk"; -}; diff --git a/Documentation/devicetree/bindings/serial/pl011.yaml b/Documentation/devicetree/bindings/serial/pl011.yaml new file mode 100644 index 000000000000..1a64d59152aa --- /dev/null +++ b/Documentation/devicetree/bindings/serial/pl011.yaml @@ -0,0 +1,126 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/pl011.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM AMBA Primecell PL011 serial UART + +maintainers: + - Rob Herring <robh@kernel.org> + +allOf: + - $ref: /schemas/serial.yaml# + +# Need a custom select here or 'arm,primecell' will match on lots of nodes +select: + properties: + compatible: + contains: + enum: + - arm,pl011 + - zte,zx296702-uart + required: + - compatible + +properties: + compatible: + oneOf: + - items: + - const: arm,pl011 + - const: arm,primecell + - items: + - const: zte,zx296702-uart + - const: arm,primecell + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + pinctrl-0: true + pinctrl-1: true + + pinctrl-names: + description: + When present, must have one state named "default", + and may contain a second name named "sleep". The former + state sets up pins for ordinary operation whereas + the latter state will put the associated pins to sleep + when the UART is unused + minItems: 1 + items: + - const: default + - const: sleep + + clocks: + description: + When present, the first clock listed must correspond to + the clock named UARTCLK on the IP block, i.e. the clock + to the external serial line, whereas the second clock + must correspond to the PCLK clocking the internal logic + of the block. Just listing one clock (the first one) is + deprecated. + maxItems: 2 + + clock-names: + items: + - const: uartclk + - const: apb_pclk + + dmas: + minItems: 1 + maxItems: 2 + + dma-names: + minItems: 1 + items: + - const: rx + - const: tx + + auto-poll: + description: + Enables polling when using RX DMA. + type: boolean + + poll-rate-ms: + description: + Rate at which poll occurs when auto-poll is set. + default 100ms. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - default: 100 + + poll-timeout-ms: + description: + Poll timeout when auto-poll is set, default + 3000ms. + allOf: + - $ref: /schemas/types.yaml#/definitions/uint32 + - default: 3000 + +required: + - compatible + - reg + - interrupts + +dependencies: + poll-rate-ms: [ auto-poll ] + poll-timeout-ms: [ auto-poll ] + +additionalProperties: false + +examples: + - | + serial@80120000 { + compatible = "arm,pl011", "arm,primecell"; + reg = <0x80120000 0x1000>; + interrupts = <0 11 4>; + dmas = <&dma 13 0 0x2>, <&dma 13 0 0x0>; + dma-names = "rx", "tx"; + clocks = <&foo_clk>, <&bar_clk>; + clock-names = "uartclk", "apb_pclk"; + }; + +... diff --git a/Documentation/devicetree/bindings/serial/rda,8810pl-uart.txt b/Documentation/devicetree/bindings/serial/rda,8810pl-uart.txt new file mode 100644 index 000000000000..a08df97a69e6 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/rda,8810pl-uart.txt @@ -0,0 +1,17 @@ +RDA Micro UART + +Required properties: +- compatible : "rda,8810pl-uart" for RDA8810PL SoCs. +- reg : Offset and length of the register set for the device. +- interrupts : Should contain UART interrupt. +- clocks : Phandle to the input clock. + + +Example: + + uart2: serial@20a90000 { + compatible = "rda,8810pl-uart"; + reg = <0x20a90000 0x1000>; + interrupts = <11 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&uart_clk>; + }; diff --git a/Documentation/devicetree/bindings/serial/renesas,rzn1-uart.txt b/Documentation/devicetree/bindings/serial/renesas,rzn1-uart.txt deleted file mode 100644 index 8b9e0d4dc2e4..000000000000 --- a/Documentation/devicetree/bindings/serial/renesas,rzn1-uart.txt +++ /dev/null @@ -1,10 +0,0 @@ -Renesas RZ/N1 UART - -This controller is based on the Synopsys DesignWare ABP UART and inherits all -properties defined in snps-dw-apb-uart.txt except for the compatible property. - -Required properties: -- compatible : The device specific string followed by the generic RZ/N1 string. - Therefore it must be one of: - "renesas,r9a06g032-uart", "renesas,rzn1-uart" - "renesas,r9a06g033-uart", "renesas,rzn1-uart" diff --git a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt index eaca9da79d83..dd63151dc8b6 100644 --- a/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt +++ b/Documentation/devicetree/bindings/serial/renesas,sci-serial.txt @@ -14,14 +14,24 @@ Required properties: - "renesas,scifa-r8a7743" for R8A7743 (RZ/G1M) SCIFA compatible UART. - "renesas,scifb-r8a7743" for R8A7743 (RZ/G1M) SCIFB compatible UART. - "renesas,hscif-r8a7743" for R8A7743 (RZ/G1M) HSCIF compatible UART. + - "renesas,scif-r8a7744" for R8A7744 (RZ/G1N) SCIF compatible UART. + - "renesas,scifa-r8a7744" for R8A7744 (RZ/G1N) SCIFA compatible UART. + - "renesas,scifb-r8a7744" for R8A7744 (RZ/G1N) SCIFB compatible UART. + - "renesas,hscif-r8a7744" for R8A7744 (RZ/G1N) HSCIF compatible UART. - "renesas,scif-r8a7745" for R8A7745 (RZ/G1E) SCIF compatible UART. - "renesas,scifa-r8a7745" for R8A7745 (RZ/G1E) SCIFA compatible UART. - "renesas,scifb-r8a7745" for R8A7745 (RZ/G1E) SCIFB compatible UART. - "renesas,hscif-r8a7745" for R8A7745 (RZ/G1E) HSCIF compatible UART. - "renesas,scif-r8a77470" for R8A77470 (RZ/G1C) SCIF compatible UART. - "renesas,hscif-r8a77470" for R8A77470 (RZ/G1C) HSCIF compatible UART. + - "renesas,scif-r8a774a1" for R8A774A1 (RZ/G2M) SCIF compatible UART. + - "renesas,hscif-r8a774a1" for R8A774A1 (RZ/G2M) HSCIF compatible UART. + - "renesas,scif-r8a774c0" for R8A774C0 (RZ/G2E) SCIF compatible UART. + - "renesas,hscif-r8a774c0" for R8A774C0 (RZ/G2E) HSCIF compatible UART. - "renesas,scif-r8a7778" for R8A7778 (R-Car M1) SCIF compatible UART. + - "renesas,hscif-r8a7778" for R8A7778 (R-Car M1) HSCIF compatible UART. - "renesas,scif-r8a7779" for R8A7779 (R-Car H1) SCIF compatible UART. + - "renesas,hscif-r8a7779" for R8A7779 (R-Car H1) HSCIF compatible UART. - "renesas,scif-r8a7790" for R8A7790 (R-Car H2) SCIF compatible UART. - "renesas,scifa-r8a7790" for R8A7790 (R-Car H2) SCIFA compatible UART. - "renesas,scifb-r8a7790" for R8A7790 (R-Car H2) SCIFB compatible UART. @@ -50,18 +60,20 @@ Required properties: - "renesas,hscif-r8a77970" for R8A77970 (R-Car V3M) HSCIF compatible UART. - "renesas,scif-r8a77980" for R8A77980 (R-Car V3H) SCIF compatible UART. - "renesas,hscif-r8a77980" for R8A77980 (R-Car V3H) HSCIF compatible UART. + - "renesas,scif-r8a77990" for R8A77990 (R-Car E3) SCIF compatible UART. + - "renesas,hscif-r8a77990" for R8A77990 (R-Car E3) HSCIF compatible UART. - "renesas,scif-r8a77995" for R8A77995 (R-Car D3) SCIF compatible UART. - "renesas,hscif-r8a77995" for R8A77995 (R-Car D3) HSCIF compatible UART. - "renesas,scifa-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFA compatible UART. - "renesas,scifb-sh73a0" for SH73A0 (SH-Mobile AG5) SCIFB compatible UART. - "renesas,rcar-gen1-scif" for R-Car Gen1 SCIF compatible UART, - - "renesas,rcar-gen2-scif" for R-Car Gen2 SCIF compatible UART, - - "renesas,rcar-gen3-scif" for R-Car Gen3 SCIF compatible UART, - - "renesas,rcar-gen2-scifa" for R-Car Gen2 SCIFA compatible UART, - - "renesas,rcar-gen2-scifb" for R-Car Gen2 SCIFB compatible UART, + - "renesas,rcar-gen2-scif" for R-Car Gen2 and RZ/G1 SCIF compatible UART, + - "renesas,rcar-gen3-scif" for R-Car Gen3 and RZ/G2 SCIF compatible UART, + - "renesas,rcar-gen2-scifa" for R-Car Gen2 and RZ/G1 SCIFA compatible UART, + - "renesas,rcar-gen2-scifb" for R-Car Gen2 and RZ/G1 SCIFB compatible UART, - "renesas,rcar-gen1-hscif" for R-Car Gen1 HSCIF compatible UART, - - "renesas,rcar-gen2-hscif" for R-Car Gen2 HSCIF compatible UART, - - "renesas,rcar-gen3-hscif" for R-Car Gen3 HSCIF compatible UART, + - "renesas,rcar-gen2-hscif" for R-Car Gen2 and RZ/G1 HSCIF compatible UART, + - "renesas,rcar-gen3-hscif" for R-Car Gen3 and RZ/G2 HSCIF compatible UART, - "renesas,scif" for generic SCIF compatible UART. - "renesas,scifa" for generic SCIFA compatible UART. - "renesas,scifb" for generic SCIFB compatible UART. diff --git a/Documentation/devicetree/bindings/serial/rs485.txt b/Documentation/devicetree/bindings/serial/rs485.txt index b7c29f74ebb2..b92592dff6dd 100644 --- a/Documentation/devicetree/bindings/serial/rs485.txt +++ b/Documentation/devicetree/bindings/serial/rs485.txt @@ -16,7 +16,7 @@ Optional properties: - linux,rs485-enabled-at-boot-time: empty property telling to enable the rs485 feature at boot time. It can be disabled later with proper ioctl. - rs485-rx-during-tx: empty property that enables the receiving of data even - whilst sending data. + while sending data. RS485 example for Atmel USART: usart0: serial@fff8c000 { diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt deleted file mode 100644 index 12bbe9f22560..000000000000 --- a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.txt +++ /dev/null @@ -1,76 +0,0 @@ -* Synopsys DesignWare ABP UART - -Required properties: -- compatible : "snps,dw-apb-uart" -- reg : offset and length of the register set for the device. -- interrupts : should contain uart interrupt. - -Clock handling: -The clock rate of the input clock needs to be supplied by one of -- clock-frequency : the input clock frequency for the UART. -- clocks : phandle to the input clock - -The supplying peripheral clock can also be handled, needing a second property -- clock-names: tuple listing input clock names. - Required elements: "baudclk", "apb_pclk" - -Optional properties: -- snps,uart-16550-compatible : reflects the value of UART_16550_COMPATIBLE - configuration parameter. Define this if your UART does not implement the busy - functionality. -- resets : phandle to the parent reset controller. -- reg-shift : quantity to shift the register offsets by. If this property is - not present then the register offsets are not shifted. -- reg-io-width : the size (in bytes) of the IO accesses that should be - performed on the device. If this property is not present then single byte - accesses are used. -- dcd-override : Override the DCD modem status signal. This signal will always - be reported as active instead of being obtained from the modem status - register. Define this if your serial port does not use this pin. -- dsr-override : Override the DTS modem status signal. This signal will always - be reported as active instead of being obtained from the modem status - register. Define this if your serial port does not use this pin. -- cts-override : Override the CTS modem status signal. This signal will always - be reported as active instead of being obtained from the modem status - register. Define this if your serial port does not use this pin. -- ri-override : Override the RI modem status signal. This signal will always be - reported as inactive instead of being obtained from the modem status register. - Define this if your serial port does not use this pin. - -Example: - - uart@80230000 { - compatible = "snps,dw-apb-uart"; - reg = <0x80230000 0x100>; - clock-frequency = <3686400>; - interrupts = <10>; - reg-shift = <2>; - reg-io-width = <4>; - dcd-override; - dsr-override; - cts-override; - ri-override; - }; - -Example with one clock: - - uart@80230000 { - compatible = "snps,dw-apb-uart"; - reg = <0x80230000 0x100>; - clocks = <&baudclk>; - interrupts = <10>; - reg-shift = <2>; - reg-io-width = <4>; - }; - -Example with two clocks: - - uart@80230000 { - compatible = "snps,dw-apb-uart"; - reg = <0x80230000 0x100>; - clocks = <&baudclk>, <&apb_pclk>; - clock-names = "baudclk", "apb_pclk"; - interrupts = <10>; - reg-shift = <2>; - reg-io-width = <4>; - }; diff --git a/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml new file mode 100644 index 000000000000..b42002542690 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/snps-dw-apb-uart.yaml @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/serial/snps-dw-apb-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Synopsys DesignWare ABP UART + +maintainers: + - Rob Herring <robh@kernel.org> + +allOf: + - $ref: /schemas/serial.yaml# + +properties: + compatible: + oneOf: + - items: + - enum: + - renesas,r9a06g032-uart + - renesas,r9a06g033-uart + - const: renesas,rzn1-uart + - items: + - enum: + - rockchip,px30-uart + - rockchip,rk3036-uart + - rockchip,rk3066-uart + - rockchip,rk3188-uart + - rockchip,rk3288-uart + - rockchip,rk3328-uart + - rockchip,rk3368-uart + - rockchip,rk3399-uart + - rockchip,rv1108-uart + - const: snps,dw-apb-uart + - items: + - enum: + - brcm,bcm11351-dw-apb-uart + - brcm,bcm21664-dw-apb-uart + - const: snps,dw-apb-uart + - const: snps,dw-apb-uart + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clock-frequency: true + + clocks: + minItems: 1 + maxItems: 2 + + clock-names: + items: + - const: baudclk + - const: apb_pclk + + snps,uart-16550-compatible: + description: reflects the value of UART_16550_COMPATIBLE configuration + parameter. Define this if your UART does not implement the busy functionality. + type: boolean + + resets: + maxItems: 1 + + reg-shift: true + + reg-io-width: true + + dcd-override: + description: Override the DCD modem status signal. This signal will + always be reported as active instead of being obtained from the modem + status register. Define this if your serial port does not use this + pin. + type: boolean + + dsr-override: + description: Override the DTS modem status signal. This signal will + always be reported as active instead of being obtained from the modem + status register. Define this if your serial port does not use this + pin. + type: boolean + + cts-override: + description: Override the CTS modem status signal. This signal will + always be reported as active instead of being obtained from the modem + status register. Define this if your serial port does not use this + pin. + type: boolean + + ri-override: + description: Override the RI modem status signal. This signal will always + be reported as inactive instead of being obtained from the modem status + register. Define this if your serial port does not use this pin. + type: boolean + +required: + - compatible + - reg + - interrupts + +examples: + - | + serial@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clock-frequency = <3686400>; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + dcd-override; + dsr-override; + cts-override; + ri-override; + }; + + - | + // Example with one clock: + serial@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clocks = <&baudclk>; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + }; + + - | + // Example with two clocks: + serial@80230000 { + compatible = "snps,dw-apb-uart"; + reg = <0x80230000 0x100>; + clocks = <&baudclk>, <&apb_pclk>; + clock-names = "baudclk", "apb_pclk"; + interrupts = <10>; + reg-shift = <2>; + reg-io-width = <4>; + }; +... diff --git a/Documentation/devicetree/bindings/serial/uniphier-uart.txt b/Documentation/devicetree/bindings/serial/uniphier-uart.txt index 0b3892a7a528..7a1bf02bb869 100644 --- a/Documentation/devicetree/bindings/serial/uniphier-uart.txt +++ b/Documentation/devicetree/bindings/serial/uniphier-uart.txt @@ -7,7 +7,7 @@ Required properties: - clocks: phandle to the input clock. Optional properties: -- fifo-size: the RX/TX FIFO size. Defaults to 64 if not specified. +-auto-flow-control: enable automatic flow control support. Example: aliases { @@ -19,5 +19,4 @@ Example: reg = <0x54006800 0x40>; interrupts = <0 33 4>; clocks = <&uart_clk>; - fifo-size = <64>; }; diff --git a/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt new file mode 100644 index 000000000000..436d2106e80d --- /dev/null +++ b/Documentation/devicetree/bindings/soc/amlogic/amlogic,canvas.txt @@ -0,0 +1,29 @@ +Amlogic Canvas +================================ + +A canvas is a collection of metadata that describes a pixel buffer. +Those metadata include: width, height, phyaddr, wrapping, block mode +and endianness. + +Many IPs within Amlogic SoCs rely on canvas indexes to read/write pixel data +rather than use the phy addresses directly. For instance, this is the case for +the video decoders and the display. + +Amlogic SoCs have 256 canvas. + +Device Tree Bindings: +--------------------- + +Video Lookup Table +-------------------------- + +Required properties: +- compatible: "amlogic,canvas" +- reg: Base physical address and size of the canvas registers. + +Example: + +canvas: video-lut@48 { + compatible = "amlogic,canvas"; + reg = <0x0 0x48 0x0 0x14>; +}; diff --git a/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt new file mode 100644 index 000000000000..6bf6b43f8dd8 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/amlogic/clk-measure.txt @@ -0,0 +1,20 @@ +Amlogic Internal Clock Measurer +=============================== + +The Amlogic SoCs contains an IP to measure the internal clocks. +The precision is multiple of MHz, useful to debug the clock states. + +Required properties: +- compatible: Shall contain one of the following : + "amlogic,meson-gx-clk-measure" for GX SoCs + "amlogic,meson8-clk-measure" for Meson8 SoCs + "amlogic,meson8b-clk-measure" for Meson8b SoCs + "amlogic,meson-axg-clk-measure" for AXG SoCs + "amlogic,meson-g12a-clk-measure" for G12a SoCs +- reg: base address and size of the Clock Measurer register space. + +Example: + clock-measure@8758 { + compatible = "amlogic,meson-gx-clk-measure"; + reg = <0x0 0x8758 0x0 0x10>; + }; diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt new file mode 100644 index 000000000000..3b7d32956391 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-pm.txt @@ -0,0 +1,46 @@ +BCM2835 PM (Power domains, watchdog) + +The PM block controls power domains and some reset lines, and includes +a watchdog timer. This binding supersedes the brcm,bcm2835-pm-wdt +binding which covered some of PM's register range and functionality. + +Required properties: + +- compatible: Should be "brcm,bcm2835-pm" +- reg: Specifies base physical address and size of the two + register ranges ("PM" and "ASYNC_BRIDGE" in that + order) +- clocks: a) v3d: The V3D clock from CPRMAN + b) peri_image: The PERI_IMAGE clock from CPRMAN + c) h264: The H264 clock from CPRMAN + d) isp: The ISP clock from CPRMAN +- #reset-cells: Should be 1. This property follows the reset controller + bindings[1]. +- #power-domain-cells: Should be 1. This property follows the power domain + bindings[2]. + +Optional properties: + +- timeout-sec: Contains the watchdog timeout in seconds +- system-power-controller: Whether the watchdog is controlling the + system power. This node follows the power controller bindings[3]. + +[1] Documentation/devicetree/bindings/reset/reset.txt +[2] Documentation/devicetree/bindings/power/power_domain.txt +[3] Documentation/devicetree/bindings/power/power-controller.txt + +Example: + +pm { + compatible = "brcm,bcm2835-pm", "brcm,bcm2835-pm-wdt"; + #power-domain-cells = <1>; + #reset-cells = <1>; + reg = <0x7e100000 0x114>, + <0x7e00a000 0x24>; + clocks = <&clocks BCM2835_CLOCK_V3D>, + <&clocks BCM2835_CLOCK_PERI_IMAGE>, + <&clocks BCM2835_CLOCK_H264>, + <&clocks BCM2835_CLOCK_ISP>; + clock-names = "v3d", "peri_image", "h264", "isp"; + system-power-controller; +}; diff --git a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt index 8dd7b3a7de65..f331316183f6 100644 --- a/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt +++ b/Documentation/devicetree/bindings/soc/bcm/brcm,bcm2835-vchiq.txt @@ -2,7 +2,8 @@ Broadcom VCHIQ firmware services Required properties: -- compatible: Should be "brcm,bcm2835-vchiq" +- compatible: Should be "brcm,bcm2835-vchiq" on BCM2835, otherwise + "brcm,bcm2836-vchiq". - reg: Physical base address and length of the doorbell register pair - interrupts: The interrupt number See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt diff --git a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt index f9987c30f0d5..5a2ef1726e2a 100644 --- a/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt +++ b/Documentation/devicetree/bindings/soc/mediatek/pwrap.txt @@ -19,10 +19,12 @@ IP Pairing Required properties in pwrap device node. - compatible: "mediatek,mt2701-pwrap" for MT2701/7623 SoCs + "mediatek,mt6765-pwrap" for MT6765 SoCs "mediatek,mt6797-pwrap" for MT6797 SoCs "mediatek,mt7622-pwrap" for MT7622 SoCs "mediatek,mt8135-pwrap" for MT8135 SoCs "mediatek,mt8173-pwrap" for MT8173 SoCs + "mediatek,mt8183-pwrap" for MT8183 SoCs - interrupts: IRQ for pwrap in SOC - reg-names: Must include the following entries: "pwrap": Main registers base diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt index 0b8cc533ca83..cf759e5f9b10 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,glink.txt @@ -55,7 +55,7 @@ of these nodes are defined by the individual bindings for the specific function = EXAMPLE The following example represents the GLINK RPM node on a MSM8996 device, with the function for the "rpm_request" channel defined, which is used for -regualtors and root clocks. +regulators and root clocks. apcs_glb: mailbox@9820000 { compatible = "qcom,msm8996-apcs-hmss-global"; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt index 89e1cb9212f6..f3fa313963d5 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smd-rpm.txt @@ -23,6 +23,8 @@ resources. "qcom,rpm-msm8916" "qcom,rpm-msm8974" "qcom,rpm-msm8998" + "qcom,rpm-sdm660" + "qcom,rpm-qcs404" - qcom,smd-channels: Usage: required diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt index a35af2dafdad..49e1d72d3648 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,smp2p.txt @@ -41,12 +41,12 @@ processor ID) and a string identifier. - qcom,local-pid: Usage: required Value type: <u32> - Definition: specifies the identfier of the local endpoint of this edge + Definition: specifies the identifier of the local endpoint of this edge - qcom,remote-pid: Usage: required Value type: <u32> - Definition: specifies the identfier of the remote endpoint of this edge + Definition: specifies the identifier of the remote endpoint of this edge = SUBNODES Each SMP2P pair contain a set of inbound and outbound entries, these are diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.txt b/Documentation/devicetree/bindings/soc/rockchip/grf.txt index 7dc5ce858a0e..46e27cd69f18 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.txt +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.txt @@ -13,6 +13,7 @@ On RK3328 SoCs, the GRF adds a section for USB2PHYGRF, Required Properties: - compatible: GRF should be one of the following: + - "rockchip,px30-grf", "syscon": for px30 - "rockchip,rk3036-grf", "syscon": for rk3036 - "rockchip,rk3066-grf", "syscon": for rk3066 - "rockchip,rk3188-grf", "syscon": for rk3188 @@ -23,6 +24,7 @@ Required Properties: - "rockchip,rk3399-grf", "syscon": for rk3399 - "rockchip,rv1108-grf", "syscon": for rv1108 - compatible: PMUGRF should be one of the following: + - "rockchip,px30-pmugrf", "syscon": for px30 - "rockchip,rk3368-pmugrf", "syscon": for rk3368 - "rockchip,rk3399-pmugrf", "syscon": for rk3399 - compatible: SGRF should be one of the following diff --git a/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt index 5d49d0a2ff29..8304eceb62e4 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt +++ b/Documentation/devicetree/bindings/soc/rockchip/power_domain.txt @@ -7,7 +7,9 @@ Required properties for power domain controller: - compatible: Should be one of the following. "rockchip,px30-power-controller" - for PX30 SoCs. "rockchip,rk3036-power-controller" - for RK3036 SoCs. + "rockchip,rk3066-power-controller" - for RK3066 SoCs. "rockchip,rk3128-power-controller" - for RK3128 SoCs. + "rockchip,rk3188-power-controller" - for RK3188 SoCs. "rockchip,rk3228-power-controller" - for RK3228 SoCs. "rockchip,rk3288-power-controller" - for RK3288 SoCs. "rockchip,rk3328-power-controller" - for RK3328 SoCs. @@ -23,7 +25,9 @@ Required properties for power domain sub nodes: - reg: index of the power domain, should use macros in: "include/dt-bindings/power/px30-power.h" - for PX30 type power domain. "include/dt-bindings/power/rk3036-power.h" - for RK3036 type power domain. + "include/dt-bindings/power/rk3066-power.h" - for RK3066 type power domain. "include/dt-bindings/power/rk3128-power.h" - for RK3128 type power domain. + "include/dt-bindings/power/rk3188-power.h" - for RK3188 type power domain. "include/dt-bindings/power/rk3228-power.h" - for RK3228 type power domain. "include/dt-bindings/power/rk3288-power.h" - for RK3288 type power domain. "include/dt-bindings/power/rk3328-power.h" - for RK3328 type power domain. diff --git a/Documentation/devicetree/bindings/sound/adi,adau1977.txt b/Documentation/devicetree/bindings/sound/adi,adau1977.txt index e79aeef73f28..9225472c80b4 100644 --- a/Documentation/devicetree/bindings/sound/adi,adau1977.txt +++ b/Documentation/devicetree/bindings/sound/adi,adau1977.txt @@ -17,12 +17,18 @@ Required properties: Documentation/devicetree/bindings/regulator/regulator.txt Optional properties: - - reset-gpio: the reset pin for the chip, for more details consult + - reset-gpios: the reset pin for the chip, for more details consult Documentation/devicetree/bindings/gpio/gpio.txt - DVDD-supply: supply voltage for the digital core, please consult Documentation/devicetree/bindings/regulator/regulator.txt +- adi,micbias: configures the voltage setting for the MICBIAS pin. + Select 0/1/2/3/4/5/6/7/8 to specify MICBIAS voltage + 5V/5.5V/6V/6.5V/7V/7.5V/8V/8.5V/9V + If not specified the default value will be "7" meaning 8.5 Volts. + This property is only valid for the ADAU1977 + For required properties on SPI, please consult Documentation/devicetree/bindings/spi/spi-bus.txt @@ -40,7 +46,8 @@ Examples: AVDD-supply = <®ulator>; DVDD-supply = <®ulator_digital>; - reset_gpio = <&gpio 10 GPIO_ACTIVE_LOW>; + adi,micbias = <3>; + reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; }; adau1977_i2c: adau1977@11 { @@ -50,5 +57,5 @@ Examples: AVDD-supply = <®ulator>; DVDD-supply = <®ulator_digital>; - reset_gpio = <&gpio 10 GPIO_ACTIVE_LOW>; + reset-gpios = <&gpio 10 GPIO_ACTIVE_LOW>; }; diff --git a/Documentation/devicetree/bindings/sound/ak4104.txt b/Documentation/devicetree/bindings/sound/ak4104.txt index deca5e18f304..ae5f7f057dc3 100644 --- a/Documentation/devicetree/bindings/sound/ak4104.txt +++ b/Documentation/devicetree/bindings/sound/ak4104.txt @@ -12,8 +12,8 @@ Required properties: Optional properties: - - reset-gpio : a GPIO spec for the reset pin. If specified, it will be - deasserted before communication to the device starts. + - reset-gpios : a GPIO spec for the reset pin. If specified, it will be + deasserted before communication to the device starts. Example: diff --git a/Documentation/devicetree/bindings/sound/ak4118.txt b/Documentation/devicetree/bindings/sound/ak4118.txt new file mode 100644 index 000000000000..6e11a2f7404c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ak4118.txt @@ -0,0 +1,22 @@ +AK4118 S/PDIF transceiver + +This device supports I2C mode. + +Required properties: + +- compatible : "asahi-kasei,ak4118" +- reg : The I2C address of the device for I2C +- reset-gpios: A GPIO specifier for the reset pin +- irq-gpios: A GPIO specifier for the IRQ pin + +Example: + +&i2c { + ak4118: ak4118@13 { + #sound-dai-cells = <0>; + compatible = "asahi-kasei,ak4118"; + reg = <0x13>; + reset-gpios = <&gpio 0 GPIO_ACTIVE_LOW> + irq-gpios = <&gpio 1 GPIO_ACTIVE_HIGH>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/ak4458.txt b/Documentation/devicetree/bindings/sound/ak4458.txt index 7839be78448d..e5820235e0d5 100644 --- a/Documentation/devicetree/bindings/sound/ak4458.txt +++ b/Documentation/devicetree/bindings/sound/ak4458.txt @@ -4,7 +4,7 @@ This device supports I2C mode. Required properties: -- compatible : "asahi-kasei,ak4458" +- compatible : "asahi-kasei,ak4458" or "asahi-kasei,ak4497" - reg : The I2C address of the device for I2C Optional properties: diff --git a/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt new file mode 100644 index 000000000000..2e6cb7d9b202 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/amlogic,axg-spdifin.txt @@ -0,0 +1,22 @@ +* Amlogic Audio SPDIF Input + +Required properties: +- compatible: 'amlogic,axg-spdifin' +- interrupts: interrupt specifier for the spdif input. +- clocks: list of clock phandle, one for each entry clock-names. +- clock-names: should contain the following: + * "pclk" : peripheral clock. + * "refclk" : spdif input reference clock +- #sound-dai-cells: must be 0. + +Example on the A113 SoC: + +spdifin: audio-controller@400 { + compatible = "amlogic,axg-spdifin"; + reg = <0x0 0x400 0x0 0x30>; + #sound-dai-cells = <0>; + interrupts = <GIC_SPI 87 IRQ_TYPE_EDGE_RISING>; + clocks = <&clkc_audio AUD_CLKID_SPDIFIN>, + <&clkc_audio AUD_CLKID_SPDIFIN_CLK>; + clock-names = "pclk", "refclk"; +}; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-card.txt index 7e63e53a901c..269682619a70 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-card.txt +++ b/Documentation/devicetree/bindings/sound/audio-graph-card.txt @@ -32,7 +32,9 @@ Required properties: Optional properties: - pa-gpios: GPIO used to control external amplifier. +----------------------- Example: Single DAI case +----------------------- sound_card { compatible = "audio-graph-card"; @@ -61,7 +63,9 @@ Example: Single DAI case }; }; +----------------------- Example: Multi DAI case +----------------------- sound-card { compatible = "audio-graph-card"; @@ -130,3 +134,204 @@ Example: Multi DAI case }; }; + +----------------------- +Example: Sampling Rate Conversion +----------------------- + + sound_card { + compatible = "audio-graph-card"; + + label = "sound-card"; + prefix = "codec"; + routing = "codec Playback", "DAI0 Playback", + "DAI0 Capture", "codec Capture"; + convert-rate = <48000>; + + dais = <&cpu_port>; + }; + + audio-codec { + ... + port { + codec_endpoint: endpoint { + remote-endpoint = <&cpu_endpoint>; + }; + }; + }; + + dai-controller { + ... + cpu_port: port { + cpu_endpoint: endpoint { + remote-endpoint = <&codec_endpoint>; + + dai-format = "left_j"; + ... + }; + }; + }; + +----------------------- +Example: 2 CPU 1 Codec (Mixing) +----------------------- + + sound_card { + compatible = "audio-graph-card"; + + label = "sound-card"; + routing = "codec Playback", "DAI0 Playback", + "codec Playback", "DAI1 Playback", + "DAI0 Capture", "codec Capture"; + + dais = <&cpu_port>; + }; + + audio-codec { + ... + + audio-graph-card,prefix = "codec"; + audio-graph-card,convert-rate = <48000>; + port { + reg = <0>; + codec_endpoint0: endpoint@0 { + remote-endpoint = <&cpu_endpoint0>; + }; + codec_endpoint1: endpoint@1 { + remote-endpoint = <&cpu_endpoint1>; + }; + }; + }; + + dai-controller { + ... + cpu_port: port { + cpu_endpoint0: endpoint@0 { + remote-endpoint = <&codec_endpoint0>; + + dai-format = "left_j"; + ... + }; + cpu_endpoint1: endpoint@1 { + remote-endpoint = <&codec_endpoint1>; + + dai-format = "left_j"; + ... + }; + }; + }; + +----------------------- +Example: Multi DAI with DPCM +----------------------- + + CPU0 ------ ak4613 + CPU1 ------ HDMI + CPU2 ------ PCM3168A-p /* DPCM 1ch/2ch */ + CPU3 --/ /* DPCM 3ch/4ch */ + CPU4 --/ /* DPCM 5ch/6ch */ + CPU5 --/ /* DPCM 7ch/8ch */ + CPU6 ------ PCM3168A-c + + sound_card: sound { + compatible = "audio-graph-card"; + + label = "sound-card"; + + routing = "pcm3168a Playback", "DAI2 Playback", + "pcm3168a Playback", "DAI3 Playback", + "pcm3168a Playback", "DAI4 Playback", + "pcm3168a Playback", "DAI5 Playback"; + + dais = <&snd_port0 /* ak4613 */ + &snd_port1 /* HDMI0 */ + &snd_port2 /* pcm3168a playback */ + &snd_port3 /* pcm3168a capture */ + >; + }; + + ak4613: codec@10 { + ... + port { + ak4613_endpoint: endpoint { + remote-endpoint = <&rsnd_endpoint0>; + }; + }; + }; + + pcm3168a: audio-codec@44 { + ... + audio-graph-card,prefix = "pcm3168a"; + audio-graph-card,convert-channels = <8>; /* TDM Split */ + ports { + port@0 { + reg = <0>; + pcm3168a_endpoint_p1: endpoint@1 { + remote-endpoint = <&rsnd_endpoint2>; + ... + }; + pcm3168a_endpoint_p2: endpoint@2 { + remote-endpoint = <&rsnd_endpoint3>; + ... + }; + pcm3168a_endpoint_p3: endpoint@3 { + remote-endpoint = <&rsnd_endpoint4>; + ... + }; + pcm3168a_endpoint_p4: endpoint@4 { + remote-endpoint = <&rsnd_endpoint5>; + ... + }; + }; + port@1 { + reg = <1>; + pcm3168a_endpoint_c: endpoint { + remote-endpoint = <&rsnd_endpoint6>; + ... + }; + }; + }; + }; + + &sound { + ports { + snd_port0: port@0 { + rsnd_endpoint0: endpoint { + remote-endpoint = <&ak4613_endpoint>; + ... + }; + }; + snd_port1: port@1 { + rsnd_endpoint1: endpoint { + remote-endpoint = <&dw_hdmi0_snd_in>; + ... + }; + }; + snd_port2: port@2 { + #address-cells = <1>; + #size-cells = <0>; + rsnd_endpoint2: endpoint@2 { + remote-endpoint = <&pcm3168a_endpoint_p1>; + ... + }; + rsnd_endpoint3: endpoint@3 { + remote-endpoint = <&pcm3168a_endpoint_p2>; + ... + }; + rsnd_endpoint4: endpoint@4 { + remote-endpoint = <&pcm3168a_endpoint_p3>; + ... + }; + rsnd_endpoint5: endpoint@5 { + remote-endpoint = <&pcm3168a_endpoint_p4>; + ... + }; + }; + snd_port3: port@6 { + rsnd_endpoint6: endpoint { + remote-endpoint = <&pcm3168a_endpoint_c>; + ... + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt b/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt deleted file mode 100644 index 441dd6f29df1..000000000000 --- a/Documentation/devicetree/bindings/sound/audio-graph-scu-card.txt +++ /dev/null @@ -1,123 +0,0 @@ -Audio-Graph-SCU-Card: - -Audio-Graph-SCU-Card is "Audio-Graph-Card" + "ALSA DPCM". - -It is based on common bindings for device graphs. -see ${LINUX}/Documentation/devicetree/bindings/graph.txt - -Basically, Audio-Graph-SCU-Card property is same as -Simple-Card / Simple-SCU-Card / Audio-Graph-Card. -see ${LINUX}/Documentation/devicetree/bindings/sound/simple-card.txt - ${LINUX}/Documentation/devicetree/bindings/sound/simple-scu-card.txt - ${LINUX}/Documentation/devicetree/bindings/sound/audio-graph-card.txt - -Below are same as Simple-Card / Audio-Graph-Card. - -- label -- dai-format -- frame-master -- bitclock-master -- bitclock-inversion -- frame-inversion -- dai-tdm-slot-num -- dai-tdm-slot-width -- clocks / system-clock-frequency - -Below are same as Simple-SCU-Card. - -- convert-rate -- convert-channels -- prefix -- routing - -Required properties: - -- compatible : "audio-graph-scu-card"; -- dais : list of CPU DAI port{s} - -Example 1. Sampling Rate Conversion - - sound_card { - compatible = "audio-graph-scu-card"; - - label = "sound-card"; - prefix = "codec"; - routing = "codec Playback", "DAI0 Playback", - "DAI0 Capture", "codec Capture"; - convert-rate = <48000>; - - dais = <&cpu_port>; - }; - - audio-codec { - ... - - port { - codec_endpoint: endpoint { - remote-endpoint = <&cpu_endpoint>; - }; - }; - }; - - dai-controller { - ... - cpu_port: port { - cpu_endpoint: endpoint { - remote-endpoint = <&codec_endpoint>; - - dai-format = "left_j"; - ... - }; - }; - }; - -Example 2. 2 CPU 1 Codec (Mixing) - - sound_card { - compatible = "audio-graph-scu-card"; - - label = "sound-card"; - prefix = "codec"; - routing = "codec Playback", "DAI0 Playback", - "codec Playback", "DAI1 Playback", - "DAI0 Capture", "codec Capture"; - convert-rate = <48000>; - - dais = <&cpu_port0 - &cpu_port1>; - }; - - audio-codec { - ... - - port { - codec_endpoint0: endpoint { - remote-endpoint = <&cpu_endpoint0>; - }; - codec_endpoint1: endpoint { - remote-endpoint = <&cpu_endpoint1>; - }; - }; - }; - - dai-controller { - ... - ports { - cpu_port0: port { - cpu_endpoint0: endpoint { - remote-endpoint = <&codec_endpoint0>; - - dai-format = "left_j"; - ... - }; - }; - cpu_port1: port { - cpu_endpoint1: endpoint { - remote-endpoint = <&codec_endpoint1>; - - dai-format = "left_j"; - ... - }; - }; - }; - }; diff --git a/Documentation/devicetree/bindings/sound/cs35l36.txt b/Documentation/devicetree/bindings/sound/cs35l36.txt new file mode 100644 index 000000000000..912bd162b477 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs35l36.txt @@ -0,0 +1,168 @@ +CS35L36 Speaker Amplifier + +Required properties: + + - compatible : "cirrus,cs35l36" + + - reg : the I2C address of the device for I2C + + - VA-supply, VP-supply : power supplies for the device, + as covered in + Documentation/devicetree/bindings/regulator/regulator.txt. + + - cirrus,boost-ctl-millivolt : Boost Voltage Value. Configures the boost + converter's output voltage in mV. The range is from 2550mV to 12000mV with + increments of 50mV. + (Default) VP + + - cirrus,boost-peak-milliamp : Boost-converter peak current limit in mA. + Configures the peak current by monitoring the current through the boost FET. + Range starts at 1600mA and goes to a maximum of 4500mA with increments of + 50mA. + (Default) 4.50 Amps + + - cirrus,boost-ind-nanohenry : Inductor estimation LBST reference value. + Seeds the digital boost converter's inductor estimation block with the initial + inductance value to reference. + + 1000 = 1uH (Default) + 1200 = 1.2uH + +Optional properties: + - cirrus,multi-amp-mode : Boolean to determine if there are more than + one amplifier in the system. If more than one it is best to Hi-Z the ASP + port to prevent bus contention on the output signal + + - cirrus,boost-ctl-select : Boost conerter control source selection. + Selects the source of the BST_CTL target VBST voltage for the boost + converter to generate. + 0x00 - Control Port Value + 0x01 - Class H Tracking (Default) + 0x10 - MultiDevice Sync Value + + - cirrus,amp-pcm-inv : Boolean to determine Amplifier will invert incoming + PCM data + + - cirrus,imon-pol-inv : Boolean to determine Amplifier will invert the + polarity of outbound IMON feedback data + + - cirrus,vmon-pol-inv : Boolean to determine Amplifier will invert the + polarity of outbound VMON feedback data + + - cirrus,dcm-mode-enable : Boost converter automatic DCM Mode enable. + This enables the digital boost converter to operate in a low power + (Discontinuous Conduction) mode during low loading conditions. + + - cirrus,weak-fet-disable : Boolean : The strength of the output drivers is + reduced when operating in a Weak-FET Drive Mode and must not be used to drive + a large load. + + - cirrus,classh-wk-fet-delay : Weak-FET entry delay. Controls the delay + (in ms) before the Class H algorithm switches to the weak-FET voltage + (after the audio falls and remains below the value specified in WKFET_AMP_THLD). + + 0 = 0ms + 1 = 5ms + 2 = 10ms + 3 = 50ms + 4 = 100ms (Default) + 5 = 200ms + 6 = 500ms + 7 = 1000ms + + - cirrus,classh-weak-fet-thld-millivolt : Weak-FET amplifier drive threshold. + Configures the signal threshold at which the PWM output stage enters + weak-FET operation. The range is 50mV to 700mV in 50mV increments. + + - cirrus,temp-warn-threshold : Amplifier overtemperature warning threshold. + Configures the threshold at which the overtemperature warning condition occurs. + When the threshold is met, the overtemperature warning attenuation is applied + and the TEMP_WARN_EINT interrupt status bit is set. + If TEMP_WARN_MASK = 0, INTb is asserted. + + 0 = 105C + 1 = 115C + 2 = 125C (Default) + 3 = 135C + + - cirrus,irq-drive-select : Selects the driver type of the selected interrupt + output. + + 0 = Open-drain + 1 = Push-pull (Default) + + - cirrus,irq-gpio-select : Selects the pin to serve as the programmable + interrupt output. + + 0 = PDM_DATA / SWIRE_SD / INT (Default) + 1 = GPIO + +Optional properties for the "cirrus,vpbr-config" Sub-node + + - cirrus,vpbr-en : VBST brownout prevention enable. Configures whether the + VBST brownout prevention algorithm is enabled or disabled. + + 0 = VBST brownout prevention disabled (default) + 1 = VBST brownout prevention enabled + + See Section 7.31.1 VPBR Config for configuration options & further details + + - cirrus,vpbr-thld : Initial VPBR threshold. Configures the VP brownout + threshold voltage + + - cirrus,cirrus,vpbr-atk-rate : Attenuation attack step rate. Configures the + amount delay between consecutive volume attenuation steps when a brownout + condition is present and the VP brownout condition is in an attacking state. + + - cirrus,vpbr-atk-vol : VP brownout prevention step size. Configures the VP + brownout prevention attacking attenuation step size when operating in either + digital volume or analog gain modes. + + - cirrus,vpbr-max-attn : Maximum attenuation that the VP brownout prevention + can apply to the audio signal. + + - cirrus,vpbr-wait : Configures the delay time between a brownout condition + no longer being present and the VP brownout prevention entering an attenuation + release state. + + - cirrus,vpbr-rel-rate : Attenuation release step rate. Configures the delay + between consecutive volume attenuation release steps when a brownout condition + is not longer present and the VP brownout is in an attenuation release state. + + - cirrus,vpbr-mute-en : During the attack state, if the vpbr-max-attn value + is reached, the error condition still remains, and this bit is set, the audio + is muted. + +Example: + +cs35l36: cs35l36@40 { + compatible = "cirrus,cs35l36"; + reg = <0x40>; + VA-supply = <&dummy_vreg>; + VP-supply = <&dummy_vreg>; + reset-gpios = <&gpio0 54 0>; + interrupt-parent = <&gpio8>; + interrupts = <3 IRQ_TYPE_LEVEL_LOW>; + + cirrus,boost-ind-nanohenry = <1000>; + cirrus,boost-ctl-millivolt = <10000>; + cirrus,boost-peak-milliamp = <4500>; + cirrus,boost-ctl-select = <0x00>; + cirrus,weak-fet-delay = <0x04>; + cirrus,weak-fet-thld = <0x01>; + cirrus,temp-warn-threshold = <0x01>; + cirrus,multi-amp-mode; + cirrus,irq-drive-select = <0x01>; + cirrus,irq-gpio-select = <0x01>; + + cirrus,vpbr-config { + cirrus,vpbr-en = <0x00>; + cirrus,vpbr-thld = <0x05>; + cirrus,vpbr-atk-rate = <0x02>; + cirrus,vpbr-atk-vol = <0x01>; + cirrus,vpbr-max-attn = <0x09>; + cirrus,vpbr-wait = <0x01>; + cirrus,vpbr-rel-rate = <0x05>; + cirrus,vpbr-mute-en = <0x00>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/cs4270.txt b/Documentation/devicetree/bindings/sound/cs4270.txt index 6b222f9b8ef5..c33770ec4c3c 100644 --- a/Documentation/devicetree/bindings/sound/cs4270.txt +++ b/Documentation/devicetree/bindings/sound/cs4270.txt @@ -10,8 +10,8 @@ Required properties: Optional properties: - - reset-gpio : a GPIO spec for the reset pin. If specified, it will be - deasserted before communication to the codec starts. + - reset-gpios : a GPIO spec for the reset pin. If specified, it will be + deasserted before communication to the codec starts. Example: diff --git a/Documentation/devicetree/bindings/sound/cs4341.txt b/Documentation/devicetree/bindings/sound/cs4341.txt new file mode 100644 index 000000000000..12b4aa8ef0db --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs4341.txt @@ -0,0 +1,22 @@ +Cirrus Logic CS4341 audio DAC + +This device supports both I2C and SPI (configured with pin strapping +on the board). + +Required properties: + - compatible: "cirrus,cs4341a" + - reg : the I2C address of the device for I2C, the chip select + number for SPI. + +For required properties on I2C-bus, please consult +Documentation/devicetree/bindings/i2c/i2c.txt +For required properties on SPI-bus, please consult +Documentation/devicetree/bindings/spi/spi-bus.txt + +Example: + codec: cs4341@0 { + #sound-dai-cells = <0>; + compatible = "cirrus,cs4341a"; + reg = <0>; + spi-max-frequency = <6000000>; + }; diff --git a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt index 46bc9829c71a..a58f79f5345c 100644 --- a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt @@ -30,6 +30,11 @@ Optional properties: - ti,hwmods : Must be "mcasp<n>", n is controller instance starting 0 - tx-num-evt : FIFO levels. - rx-num-evt : FIFO levels. +- dismod : Specify the drive on TX pin during inactive slots + 0 : 3-state + 2 : logic low + 3 : logic high + Defaults to 'logic low' when the property is not present - sram-size-playback : size of sram to be allocated during playback - sram-size-capture : size of sram to be allocated during capture - interrupts : Interrupt numbers for McASP @@ -40,6 +45,23 @@ Optional properties: - fck_parent : Should contain a valid clock name which will be used as parent for the McASP fck +Optional GPIO support: +If any McASP pin need to be used as GPIO then the McASP node must have: +... + gpio-controller + #gpio-cells = <2>; +... + +When requesting a GPIO, the first parameter is the PIN index in McASP_P* +registers. +For example to request the AXR2 pin of mcasp8: +function-gpios = <&mcasp8 2 0>; + +Or to request the ACLKR pin of mcasp8: +function-gpios = <&mcasp8 29 0>; + +For generic gpio information, please refer to bindings/gpio/gpio.txt + Example: mcasp0: mcasp0@1d00000 { diff --git a/Documentation/devicetree/bindings/sound/dmic.txt b/Documentation/devicetree/bindings/sound/dmic.txt index e957b4136716..32e871037269 100644 --- a/Documentation/devicetree/bindings/sound/dmic.txt +++ b/Documentation/devicetree/bindings/sound/dmic.txt @@ -9,6 +9,7 @@ Optional properties: - dmicen-gpios: GPIO specifier for dmic to control start and stop - num-channels: Number of microphones on this DAI - wakeup-delay-ms: Delay (in ms) after enabling the DMIC + - modeswitch-delay-ms: Delay (in ms) to complete DMIC mode switch Example node: @@ -17,4 +18,5 @@ Example node: dmicen-gpios = <&gpio4 3 GPIO_ACTIVE_HIGH>; num-channels = <1>; wakeup-delay-ms <50>; + modeswitch-delay-ms <35>; }; diff --git a/Documentation/devicetree/bindings/sound/fsl,micfil.txt b/Documentation/devicetree/bindings/sound/fsl,micfil.txt new file mode 100644 index 000000000000..53e227b15277 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,micfil.txt @@ -0,0 +1,32 @@ +NXP MICFIL Digital Audio Interface (MICFIL). + +The MICFIL digital interface provides a 16-bit audio signal from a PDM +microphone bitstream in a configurable output sampling rate. + +Required properties: + + - compatible : Compatible list, contains "fsl,imx8mm-micfil" + + - reg : Offset and length of the register set for the device. + + - interrupts : Contains the micfil interrupts. + + - clocks : Must contain an entry for each entry in clock-names. + + - clock-names : Must include the "ipg_clk" for register access and + "ipg_clk_app" for internal micfil clock. + + - dmas : Generic dma devicetree binding as described in + Documentation/devicetree/bindings/dma/dma.txt. + +Example: +micfil: micfil@30080000 { + compatible = "fsl,imx8mm-micfil"; + reg = <0x0 0x30080000 0x0 0x10000>; + interrupts = <GIC_SPI 109 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 110 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX8MM_CLK_PDM_IPG>, + <&clk IMX8MM_CLK_PDM_ROOT>; + clock-names = "ipg_clk", "ipg_clk_app"; + dmas = <&sdma2 24 26 0x80000000>; +}; diff --git a/Documentation/devicetree/bindings/sound/fsl-sai.txt b/Documentation/devicetree/bindings/sound/fsl-sai.txt index dd9e59738e08..2e726b983845 100644 --- a/Documentation/devicetree/bindings/sound/fsl-sai.txt +++ b/Documentation/devicetree/bindings/sound/fsl-sai.txt @@ -35,13 +35,13 @@ Required properties: - fsl,sai-synchronous-rx: This is a boolean property. If present, indicating that SAI will work in the synchronous mode (sync Tx - with Rx) which means both the transimitter and the + with Rx) which means both the transmitter and the receiver will send and receive data by following receiver's bit clocks and frame sync clocks. - fsl,sai-asynchronous: This is a boolean property. If present, indicating that SAI will work in the asynchronous mode, which - means both transimitter and receiver will send and + means both transmitter and receiver will send and receive data by following their own bit clocks and frame sync clocks separately. @@ -58,8 +58,8 @@ Optional properties (for mx6ul): Note: - If both fsl,sai-asynchronous and fsl,sai-synchronous-rx are absent, the default synchronous mode (sync Rx with Tx) will be used, which means both - transimitter and receiver will send and receive data by following clocks - of transimitter. + transmitter and receiver will send and receive data by following clocks + of transmitter. - fsl,sai-asynchronous and fsl,sai-synchronous-rx are exclusive. Example: diff --git a/Documentation/devicetree/bindings/sound/google,cros-ec-codec.txt b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.txt new file mode 100644 index 000000000000..1084f7f22eea --- /dev/null +++ b/Documentation/devicetree/bindings/sound/google,cros-ec-codec.txt @@ -0,0 +1,26 @@ +* Audio codec controlled by ChromeOS EC + +Google's ChromeOS EC codec is a digital mic codec provided by the +Embedded Controller (EC) and is controlled via a host-command interface. + +An EC codec node should only be found as a sub-node of the EC node (see +Documentation/devicetree/bindings/mfd/cros-ec.txt). + +Required properties: +- compatible: Must contain "google,cros-ec-codec" +- #sound-dai-cells: Should be 1. The cell specifies number of DAIs. +- max-dmic-gain: A number for maximum gain in dB on digital microphone. + +Example: + +cros-ec@0 { + compatible = "google,cros-ec-spi"; + + ... + + cros_ec_codec: ec-codec { + compatible = "google,cros-ec-codec"; + #sound-dai-cells = <1>; + max-dmic-gain = <43>; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt b/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt new file mode 100644 index 000000000000..05adc0d47b13 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ingenic,jz4725b-codec.txt @@ -0,0 +1,20 @@ +Ingenic JZ4725B codec controller + +Required properties: +- compatible : "ingenic,jz4725b-codec" +- reg : codec registers location and length +- clocks : phandle to the AIC clock. +- clock-names: must be set to "aic". +- #sound-dai-cells: Must be set to 0. + +Example: + +codec: audio-codec@100200a4 { + compatible = "ingenic,jz4725b-codec"; + reg = <0x100200a4 0x8>; + + #sound-dai-cells = <0>; + + clocks = <&cgu JZ4725B_CLK_AIC>; + clock-names = "aic"; +}; diff --git a/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt b/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt new file mode 100644 index 000000000000..1ffcade87e7b --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ingenic,jz4740-codec.txt @@ -0,0 +1,20 @@ +Ingenic JZ4740 codec controller + +Required properties: +- compatible : "ingenic,jz4740-codec" +- reg : codec registers location and length +- clocks : phandle to the AIC clock. +- clock-names: must be set to "aic". +- #sound-dai-cells: Must be set to 0. + +Example: + +codec: audio-codec@10020080 { + compatible = "ingenic,jz4740-codec"; + reg = <0x10020080 0x8>; + + #sound-dai-cells = <0>; + + clocks = <&cgu JZ4740_CLK_AIC>; + clock-names = "aic"; +}; diff --git a/Documentation/devicetree/bindings/sound/mt6358.txt b/Documentation/devicetree/bindings/sound/mt6358.txt new file mode 100644 index 000000000000..5465730013a1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt6358.txt @@ -0,0 +1,18 @@ +Mediatek MT6358 Audio Codec + +The communication between MT6358 and SoC is through Mediatek PMIC wrapper. +For more detail, please visit Mediatek PMIC wrapper documentation. + +Must be a child node of PMIC wrapper. + +Required properties: + +- compatible : "mediatek,mt6358-sound". +- Avdd-supply : power source of AVDD + +Example: + +mt6358_snd { + compatible = "mediatek,mt6358-sound"; + Avdd-supply = <&mt6358_vaud28_reg>; +}; diff --git a/Documentation/devicetree/bindings/sound/mt8183-afe-pcm.txt b/Documentation/devicetree/bindings/sound/mt8183-afe-pcm.txt new file mode 100644 index 000000000000..396ba38619f6 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mt8183-afe-pcm.txt @@ -0,0 +1,36 @@ +Mediatek AFE PCM controller for mt8183 + +Required properties: +- compatible = "mediatek,mt68183-audio"; +- reg: register location and size +- interrupts: should contain AFE interrupt +- power-domains: should define the power domain +- clocks: Must contain an entry for each entry in clock-names +- clock-names: should have these clock names: + "infra_sys_audio_clk", + "mtkaif_26m_clk", + "top_mux_audio", + "top_mux_aud_intbus", + "top_sys_pll3_d4", + "top_clk26m_clk"; + +Example: + + afe: mt8183-afe-pcm@11220000 { + compatible = "mediatek,mt8183-audio"; + reg = <0 0x11220000 0 0x1000>; + interrupts = <GIC_SPI 161 IRQ_TYPE_LEVEL_LOW>; + power-domains = <&scpsys MT8183_POWER_DOMAIN_AUDIO>; + clocks = <&infrasys CLK_INFRA_AUDIO>, + <&infrasys CLK_INFRA_AUDIO_26M_BCLK>, + <&topckgen CLK_TOP_MUX_AUDIO>, + <&topckgen CLK_TOP_MUX_AUD_INTBUS>, + <&topckgen CLK_TOP_SYSPLL_D2_D4>, + <&clk26m>; + clock-names = "infra_sys_audio_clk", + "mtkaif_26m_clk", + "top_mux_audio", + "top_mux_aud_intbus", + "top_sys_pll_d2_d4", + "top_clk26m_clk"; + }; diff --git a/Documentation/devicetree/bindings/sound/mtk-btcvsd-snd.txt b/Documentation/devicetree/bindings/sound/mtk-btcvsd-snd.txt new file mode 100644 index 000000000000..679e44839b48 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/mtk-btcvsd-snd.txt @@ -0,0 +1,24 @@ +Mediatek ALSA BT SCO CVSD/MSBC Driver + +Required properties: +- compatible = "mediatek,mtk-btcvsd-snd"; +- reg: register location and size of PKV and SRAM_BANK2 +- interrupts: should contain BTSCO interrupt +- mediatek,infracfg: the phandles of INFRASYS +- mediatek,offset: Array contains of register offset and mask + infra_misc_offset, + infra_conn_bt_cvsd_mask, + cvsd_mcu_read_offset, + cvsd_mcu_write_offset, + cvsd_packet_indicator_offset + +Example: + + mtk-btcvsd-snd@18000000 { + compatible = "mediatek,mtk-btcvsd-snd"; + reg=<0 0x18000000 0 0x1000>, + <0 0x18080000 0 0x8000>; + interrupts = <GIC_SPI 286 IRQ_TYPE_LEVEL_LOW>; + mediatek,infracfg = <&infrasys>; + mediatek,offset = <0xf00 0x800 0xfd0 0xfd4 0xfd8>; + }; diff --git a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt index 44d27456e8a4..21cd310963b1 100644 --- a/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt +++ b/Documentation/devicetree/bindings/sound/nvidia,tegra30-hda.txt @@ -13,6 +13,10 @@ Required properties: See ../reset/reset.txt for details. - reset-names : Must include the following entries: hda, hda2hdmi, hda2codec_2x +Optional properties: +- nvidia,model : The user-visible name of this sound complex. Since the property + is optional, legacy boards can use default name provided in hda driver. + Example: hda@70030000 { @@ -27,4 +31,5 @@ hda@70030000 { <&tegra_car 128>, /* hda2hdmi */ <&tegra_car 111>; /* hda2codec_2x */ reset-names = "hda", "hda2hdmi", "hda2codec_2x"; + nvidia,model = "jetson-tk1-hda"; }; diff --git a/Documentation/devicetree/bindings/sound/omap-mcpdm.txt b/Documentation/devicetree/bindings/sound/omap-mcpdm.txt index 5f4e68ca228c..ff98a0cb5b3f 100644 --- a/Documentation/devicetree/bindings/sound/omap-mcpdm.txt +++ b/Documentation/devicetree/bindings/sound/omap-mcpdm.txt @@ -7,6 +7,8 @@ Required properties: <L3 interconnect address, size>; - interrupts: Interrupt number for McPDM - ti,hwmods: Name of the hwmod associated to the McPDM +- clocks: phandle for the pdmclk provider, likely <&twl6040> +- clock-names: Must be "pdmclk" Example: @@ -18,3 +20,11 @@ mcpdm: mcpdm@40132000 { interrupt-parent = <&gic>; ti,hwmods = "mcpdm"; }; + +In board DTS file the pdmclk needs to be added: + +&mcpdm { + clocks = <&twl6040>; + clock-names = "pdmclk"; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/sound/pcm3060.txt b/Documentation/devicetree/bindings/sound/pcm3060.txt index 90fcb8523099..97de66932d44 100644 --- a/Documentation/devicetree/bindings/sound/pcm3060.txt +++ b/Documentation/devicetree/bindings/sound/pcm3060.txt @@ -9,9 +9,15 @@ Required properties: - reg : the I2C address of the device for I2C, the chip select number for SPI. +Optional properties: + +- ti,out-single-ended: "true" if output is single-ended; + "false" or not specified if output is differential. + Examples: pcm3060: pcm3060@46 { compatible = "ti,pcm3060"; reg = <0x46>; + ti,out-single-ended = "true"; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt b/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt index fdcea3d12ee5..e7d17dda55db 100644 --- a/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt +++ b/Documentation/devicetree/bindings/sound/qcom,msm8916-wcd-analog.txt @@ -30,6 +30,7 @@ Required properties - vdd-cdc-io-supply: phandle to VDD_CDC_IO regulator DT node. - vdd-cdc-tx-rx-cx-supply: phandle to VDD_CDC_TX/RX/CX regulator DT node. - vdd-micbias-supply: phandle of VDD_MICBIAS supply's regulator DT node. + Optional Properties: - qcom,mbhc-vthreshold-low: Array of 5 threshold voltages in mV for 5 buttons detection on headset when the mbhc is powered up @@ -92,9 +93,9 @@ spmi_bus { "cdc_ear_cnp_int", "cdc_hphr_cnp_int", "cdc_hphl_cnp_int"; - VDD-CDC-IO-supply = <&pm8916_l5>; - VDD-CDC-TX-RX-CX-supply = <&pm8916_l5>; - VDD-MICBIAS-supply = <&pm8916_l13>; + vdd-cdc-io-supply = <&pm8916_l5>; + vdd-cdc-tx-rx-cx-supply = <&pm8916_l5>; + vdd-micbias-supply = <&pm8916_l13>; #sound-dai-cells = <1>; }; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt index f9c7bd8c1bc0..9f5378c51686 100644 --- a/Documentation/devicetree/bindings/sound/qcom,q6asm.txt +++ b/Documentation/devicetree/bindings/sound/qcom,q6asm.txt @@ -27,6 +27,28 @@ used by the apr service device. Value type: <u32> Definition: Must be 1 +== ASM DAI is subnode of "dais" and represent a dai, it includes board specific +configuration of each dai. Must contain the following properties. + +- reg + Usage: required + Value type: <u32> + Definition: Must be dai id + +- direction: + Usage: Required for Compress offload dais + Value type: <u32> + Definition: Specifies the direction of the dai stream + 0 for both tx and rx + 1 for only tx (Capture/Encode) + 2 for only rx (Playback/Decode) + +- is-compress-dai: + Usage: Required for Compress offload dais + Value type: <boolean> + Definition: present for Compress offload dais + + = EXAMPLE q6asm@7 { @@ -35,5 +57,10 @@ q6asm@7 { q6asmdai: dais { compatible = "qcom,q6asm-dais"; #sound-dai-cells = <1>; + mm@0 { + reg = <0>; + direction = <2>; + is-compress-dai; + }; }; }; diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt b/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt index 1d8d49e30af7..5d6ea66a863f 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt +++ b/Documentation/devicetree/bindings/sound/qcom,wcd9335.txt @@ -34,12 +34,12 @@ Required properties with SLIMbus Interface: Definition: Interrupt names of WCD INTR1 and INTR2 Should be: "intr1", "intr2" -- reset-gpio: +- reset-gpios: Usage: required Value type: <String Array> Definition: Reset gpio line -- qcom,ifd: +- slim-ifc-dev: Usage: required Value type: <phandle> Definition: SLIM interface device @@ -104,13 +104,13 @@ Required properties with SLIMbus Interface: Value type: <u32> Definition: Must be 1 -codec@1{ +audio-codec@1{ compatible = "slim217,1a0"; reg = <1 0>; interrupts = <&msmgpio 54 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "intr2" - reset-gpio = <&msmgpio 64 0>; - qcom,ifd = <&wc9335_ifd>; + reset-gpios = <&msmgpio 64 0>; + slim-ifc-dev = <&wc9335_ifd>; clock-names = "mclk", "native"; clocks = <&rpmcc RPM_SMD_DIV_CLK1>, <&rpmcc RPM_SMD_BB_CLK1>; diff --git a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt index d92b705e7917..648d43e1b1e9 100644 --- a/Documentation/devicetree/bindings/sound/renesas,rsnd.txt +++ b/Documentation/devicetree/bindings/sound/renesas,rsnd.txt @@ -39,15 +39,7 @@ This is example of Playback: [MEM] -> [SRC2] -> [DVC0] -> [SSIU0/SSI0] -> [codec] Capture: [MEM] <- [DVC1] <- [SRC3] <- [SSIU1/SSI1] <- [codec] - &rcar_sound { - ... - rcar_sound,dai { - dai0 { - playback = <&ssi0 &src2 &dvc0>; - capture = <&ssi1 &src3 &dvc1>; - }; - }; - }; +see "Example: simple sound card" You can use below. ${LINUX}/arch/arm/boot/dts/r8a7790.dts can be good example. @@ -83,29 +75,8 @@ SRC can convert [xx]Hz to [yy]Hz. Then, it has below 2 modes ** Asynchronous mode ------------------ -You need to use "simple-scu-audio-card" sound card for it. -example) - - sound { - compatible = "simple-scu-audio-card"; - ... - /* - * SRC Asynchronous mode setting - * Playback: - * All input data will be converted to 48kHz - * Capture: - * Inputed 48kHz data will be converted to - * system specified Hz - */ - simple-audio-card,convert-rate = <48000>; - ... - simple-audio-card,cpu { - sound-dai = <&rcar_sound>; - }; - simple-audio-card,codec { - ... - }; - }; +You need to use "simple-scu-audio-card" or "audio-graph-scu-card" for it. +see "Example: simple sound card for Asynchronous mode" ------------------ ** Synchronous mode @@ -141,26 +112,8 @@ For more detail information, see below ${LINUX}/sound/soc/sh/rcar/ctu.c - comment of header -You need to use "simple-scu-audio-card" sound card for it. -example) - - sound { - compatible = "simple-scu-audio-card"; - ... - /* - * CTU setting - * All input data will be converted to 2ch - * as output data - */ - simple-audio-card,convert-channels = <2>; - ... - simple-audio-card,cpu { - sound-dai = <&rcar_sound>; - }; - simple-audio-card,codec { - ... - }; - }; +You need to use "simple-scu-audio-card" or "audio-graph-scu-card" for it. +see "Example: simple sound card for channel convert" Ex) Exchange output channel Input -> Output @@ -190,42 +143,13 @@ and these sounds will be merged by MIX. aplay -D plughw:0,0 xxxx.wav & aplay -D plughw:0,1 yyyy.wav -You need to use "simple-scu-audio-card" sound card for it. +You need to use "simple-scu-audio-card" or "audio-graph-scu-card" for it. Ex) [MEM] -> [SRC1] -> [CTU02] -+-> [MIX0] -> [DVC0] -> [SSI0] | [MEM] -> [SRC2] -> [CTU03] -+ - sound { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "simple-scu-audio-card"; - ... - simple-audio-card,cpu@0 { - reg = <0>; - sound-dai = <&rcar_sound 0>; - }; - simple-audio-card,cpu@1 { - reg = <1>; - sound-dai = <&rcar_sound 1>; - }; - simple-audio-card,codec { - ... - }; - }; - - &rcar_sound { - ... - rcar_sound,dai { - dai0 { - playback = <&src1 &ctu02 &mix0 &dvc0 &ssi0>; - }; - dai1 { - playback = <&src2 &ctu03 &mix0 &dvc0 &ssi0>; - }; - }; - }; +see "Example: simple sound card for MIXer" ============================================= * DVC (Digital Volume and Mute Function) @@ -257,15 +181,31 @@ Volume Ramp * SSIU (Serial Sound Interface Unit) ============================================= -There is no DT settings for SSIU, because SSIU will be automatically -selected via SSI. SSIU can avoid some under/over run error, because it has some buffer. But you can't use it if SSI was PIO mode. -In DMA mode, you can select not to use SSIU by using "no-busif" on DT. +In DMA mode, you can select not to use SSIU by using "no-busif" via SSI. - &ssi0 { - no-busif; - }; +SSIU handles BUSIF which will be used for TDM Split mode. +This driver is assuming that audio-graph card will be used. + +TDM Split mode merges 4 sounds. You can see 4 sound interface on system, +and these sounds will be merged SSIU/SSI. + + aplay -D plughw:0,0 xxxx.wav & + aplay -D plughw:0,1 xxxx.wav & + aplay -D plughw:0,2 xxxx.wav & + aplay -D plughw:0,3 xxxx.wav + + 2ch 8ch + [MEM] -> [SSIU 30] -+-> [SSIU 3] --> [Codec] + 2ch | + [MEM] -> [SSIU 31] -+ + 2ch | + [MEM] -> [SSIU 32] -+ + 2ch | + [MEM] -> [SSIU 33] -+ + +see "Example: simple sound card for TDM Split" ============================================= * SSI (Serial Sound Interface) @@ -304,14 +244,7 @@ This is example if SSI1 want to share WS pin with SSI0 You can use Multi-SSI. This is example of SSI0/SSI1/SSI2 (= for 6ch) - &rcar_sound { - ... - rcar_sound,dai { - dai0 { - playback = <&ssi0 &ssi1 &ssi2 &src0 &dvc0>; - }; - }; - }; +see "Example: simple sound card for Multi channel" ** TDM-SSI @@ -319,19 +252,7 @@ You can use TDM with SSI. This is example of TDM 6ch. Driver can automatically switches TDM <-> stereo mode in this case. - rsnd_tdm: sound { - compatible = "simple-audio-card"; - ... - simple-audio-card,cpu { - /* system can use TDM 6ch */ - dai-tdm-slot-num = <6>; - sound-dai = <&rcar_sound>; - }; - simple-audio-card,codec { - ... - }; - }; - +see "Example: simple sound card for TDM" ============================================= Required properties: @@ -346,6 +267,7 @@ Required properties: - "renesas,rcar_sound-r8a7744" (RZ/G1N) - "renesas,rcar_sound-r8a7745" (RZ/G1E) - "renesas,rcar_sound-r8a774a1" (RZ/G2M) + - "renesas,rcar_sound-r8a774c0" (RZ/G2E) - "renesas,rcar_sound-r8a7778" (R-Car M1A) - "renesas,rcar_sound-r8a7779" (R-Car H1) - "renesas,rcar_sound-r8a7790" (R-Car H2) @@ -356,6 +278,7 @@ Required properties: - "renesas,rcar_sound-r8a7796" (R-Car M3-W) - "renesas,rcar_sound-r8a77965" (R-Car M3-N) - "renesas,rcar_sound-r8a77990" (R-Car E3) + - "renesas,rcar_sound-r8a77995" (R-Car D3) - reg : Should contain the register physical address. required register is SRU/ADG/SSI if generation1 @@ -363,6 +286,9 @@ Required properties: - rcar_sound,ssi : Should contain SSI feature. The number of SSI subnode should be same as HW. see below for detail. +- rcar_sound,ssiu : Should contain SSIU feature. + The number of SSIU subnode should be same as HW. + see below for detail. - rcar_sound,src : Should contain SRC feature. The number of SRC subnode should be same as HW. see below for detail. @@ -402,8 +328,13 @@ SSI subnode properties: - no-busif : BUSIF is not ussed when [mem -> SSI] via DMA case - dma : Should contain Audio DMAC entry - dma-names : SSI case "rx" (=playback), "tx" (=capture) + Deprecated: see SSIU subnode properties SSIU case "rxu" (=playback), "txu" (=capture) +SSIU subnode properties: +- dma : Should contain Audio DMAC entry +- dma-names : "rx" (=playback), "tx" (=capture) + SRC subnode properties: - dma : Should contain Audio DMAC entry - dma-names : "rx" (=playback), "tx" (=capture) @@ -532,56 +463,55 @@ rcar_sound: sound@ec500000 { }; }; + rcar_sound,ssiu { + ssiu00: ssiu-0 { + dmas = <&audma0 0x15>, <&audma1 0x16>; + dma-names = "rx", "tx"; + }; + ssiu01: ssiu-1 { + dmas = <&audma0 0x35>, <&audma1 0x36>; + dma-names = "rx", "tx"; + }; + + ... + + ssiu95: ssiu-49 { + dmas = <&audma0 0xA5>, <&audma1 0xA6>; + dma-names = "rx", "tx"; + }; + ssiu96: ssiu-50 { + dmas = <&audma0 0xA7>, <&audma1 0xA8>; + dma-names = "rx", "tx"; + }; + ssiu97: ssiu-51 { + dmas = <&audma0 0xA9>, <&audma1 0xAA>; + dma-names = "rx", "tx"; + }; + }; + rcar_sound,ssi { ssi0: ssi-0 { interrupts = <0 370 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x01>, <&audma1 0x02>, <&audma0 0x15>, <&audma1 0x16>; - dma-names = "rx", "tx", "rxu", "txu"; + dmas = <&audma0 0x01>, <&audma1 0x02>; + dma-names = "rx", "tx"; }; ssi1: ssi-1 { interrupts = <0 371 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x03>, <&audma1 0x04>, <&audma0 0x49>, <&audma1 0x4a>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi2: ssi-2 { - interrupts = <0 372 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x05>, <&audma1 0x06>, <&audma0 0x63>, <&audma1 0x64>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi3: ssi-3 { - interrupts = <0 373 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x07>, <&audma1 0x08>, <&audma0 0x6f>, <&audma1 0x70>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi4: ssi-4 { - interrupts = <0 374 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x09>, <&audma1 0x0a>, <&audma0 0x71>, <&audma1 0x72>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi5: ssi-5 { - interrupts = <0 375 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x0b>, <&audma1 0x0c>, <&audma0 0x73>, <&audma1 0x74>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi6: ssi-6 { - interrupts = <0 376 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x0d>, <&audma1 0x0e>, <&audma0 0x75>, <&audma1 0x76>; - dma-names = "rx", "tx", "rxu", "txu"; - }; - ssi7: ssi-7 { - interrupts = <0 377 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x0f>, <&audma1 0x10>, <&audma0 0x79>, <&audma1 0x7a>; - dma-names = "rx", "tx", "rxu", "txu"; + dmas = <&audma0 0x03>, <&audma1 0x04>; + dma-names = "rx", "tx"; }; + + ... + ssi8: ssi-8 { interrupts = <0 378 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x11>, <&audma1 0x12>, <&audma0 0x7b>, <&audma1 0x7c>; - dma-names = "rx", "tx", "rxu", "txu"; + dmas = <&audma0 0x11>, <&audma1 0x12>; + dma-names = "rx", "tx"; }; ssi9: ssi-9 { interrupts = <0 379 IRQ_TYPE_LEVEL_HIGH>; - dmas = <&audma0 0x13>, <&audma1 0x14>, <&audma0 0x7d>, <&audma1 0x7e>; - dma-names = "rx", "tx", "rxu", "txu"; + dmas = <&audma0 0x13>, <&audma1 0x14>; + dma-names = "rx", "tx"; }; }; @@ -647,25 +577,174 @@ Example: simple sound card }; ============================================= +Example: simple sound card for Asynchronous mode +============================================= + +sound { + compatible = "simple-scu-audio-card"; + ... + /* + * SRC Asynchronous mode setting + * Playback: + * All input data will be converted to 48kHz + * Capture: + * Inputed 48kHz data will be converted to + * system specified Hz + */ + simple-audio-card,convert-rate = <48000>; + ... + simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + }; + simple-audio-card,codec { + ... + }; +}; + +============================================= +Example: simple sound card for channel convert +============================================= + +sound { + compatible = "simple-scu-audio-card"; + ... + /* + * CTU setting + * All input data will be converted to 2ch + * as output data + */ + simple-audio-card,convert-channels = <2>; + ... + simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + }; + simple-audio-card,codec { + ... + }; +}; + +============================================= +Example: simple sound card for MIXer +============================================= + +sound { + compatible = "simple-scu-audio-card"; + ... + simple-audio-card,cpu@0 { + sound-dai = <&rcar_sound 0>; + }; + simple-audio-card,cpu@1 { + sound-dai = <&rcar_sound 1>; + }; + simple-audio-card,codec { + ... + }; +}; + +&rcar_sound { + ... + rcar_sound,dai { + dai0 { + playback = <&src1 &ctu02 &mix0 &dvc0 &ssi0>; + }; + dai1 { + playback = <&src2 &ctu03 &mix0 &dvc0 &ssi0>; + }; + }; +}; + +============================================= Example: simple sound card for TDM ============================================= - rsnd_tdm: sound { - compatible = "simple-audio-card"; +rsnd_tdm: sound { + compatible = "simple-audio-card"; - simple-audio-card,format = "left_j"; - simple-audio-card,bitclock-master = <&sndcodec>; - simple-audio-card,frame-master = <&sndcodec>; + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&sndcodec>; + simple-audio-card,frame-master = <&sndcodec>; - sndcpu: simple-audio-card,cpu { - sound-dai = <&rcar_sound>; - dai-tdm-slot-num = <6>; + sndcpu: simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + dai-tdm-slot-num = <6>; + }; + + sndcodec: simple-audio-card,codec { + sound-dai = <&xxx>; + }; +}; + +============================================= +Example: simple sound card for TDM Split +============================================= + +sound_card: sound { + compatible = "audio-graph-scu-card"; + prefix = "xxxx"; + routing = "xxxx Playback", "DAI0 Playback", + "xxxx Playback", "DAI1 Playback", + "xxxx Playback", "DAI2 Playback", + "xxxx Playback", "DAI3 Playback"; + convert-channels = <8>; /* TDM Split */ + + dais = <&rsnd_port0 /* playback ch1/ch2 */ + &rsnd_port1 /* playback ch3/ch4 */ + &rsnd_port2 /* playback ch5/ch6 */ + &rsnd_port3 /* playback ch7/ch8 */ + >; +}; + +audio-codec { + ... + port { + codec_0: endpoint@1 { + remote-endpoint = <&rsnd_ep0>; + }; + codec_1: endpoint@2 { + remote-endpoint = <&rsnd_ep1>; + }; + codec_2: endpoint@3 { + remote-endpoint = <&rsnd_ep2>; + }; + codec_3: endpoint@4 { + remote-endpoint = <&rsnd_ep3>; }; + }; +}; - sndcodec: simple-audio-card,codec { - sound-dai = <&xxx>; +&rcar_sound { + ... + ports { + rsnd_port0: port@0 { + rsnd_ep0: endpoint { + remote-endpoint = <&codec_0>; + ... + playback = <&ssiu30 &ssi3>; + }; + }; + rsnd_port1: port@1 { + rsnd_ep1: endpoint { + remote-endpoint = <&codec_1>; + ... + playback = <&ssiu31 &ssi3>; + }; + }; + rsnd_port2: port@2 { + rsnd_ep2: endpoint { + remote-endpoint = <&codec_2>; + ... + playback = <&ssiu32 &ssi3>; + }; + }; + rsnd_port3: port@3 { + rsnd_ep3: endpoint { + remote-endpoint = <&codec_3>; + ... + playback = <&ssiu33 &ssi3>; + }; }; }; +}; ============================================= Example: simple sound card for Multi channel diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt new file mode 100644 index 000000000000..2469588c7ccb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.txt @@ -0,0 +1,23 @@ +* Rockchip Rk3328 internal codec + +Required properties: + +- compatible: "rockchip,rk3328-codec" +- reg: physical base address of the controller and length of memory mapped + region. +- rockchip,grf: the phandle of the syscon node for GRF register. +- clocks: a list of phandle + clock-specifer pairs, one for each entry in clock-names. +- clock-names: should be "pclk". +- spk-depop-time-ms: speak depop time msec. + +Example for rk3328 internal codec: + +codec: codec@ff410000 { + compatible = "rockchip,rk3328-codec"; + reg = <0x0 0xff410000 0x0 0x1000>; + rockchip,grf = <&grf>; + clocks = <&cru PCLK_ACODEC>; + clock-names = "pclk"; + spk-depop-time-ms = 100; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/sound/rt5631.txt b/Documentation/devicetree/bindings/sound/rt5631.txt index 92b986ca337b..56bc85232c49 100644 --- a/Documentation/devicetree/bindings/sound/rt5631.txt +++ b/Documentation/devicetree/bindings/sound/rt5631.txt @@ -35,14 +35,14 @@ Pins on the device (for linking into audio routes): Example: -alc5631: alc5631@1a { +alc5631: audio-codec@1a { compatible = "realtek,alc5631"; reg = <0x1a>; }; or -rt5631: rt5631@1a { +rt5631: audio-codec@1a { compatible = "realtek,rt5631"; reg = <0x1a>; }; diff --git a/Documentation/devicetree/bindings/sound/rt5663.txt b/Documentation/devicetree/bindings/sound/rt5663.txt index 23386446c63d..2a55e9133408 100644 --- a/Documentation/devicetree/bindings/sound/rt5663.txt +++ b/Documentation/devicetree/bindings/sound/rt5663.txt @@ -10,6 +10,10 @@ Required properties: - interrupts : The CODEC's interrupt output. +- avdd-supply: Power supply for AVDD, providing 1.8V. + +- cpvdd-supply: Power supply for CPVDD, providing 3.5V. + Optional properties: - "realtek,dc_offset_l_manual" @@ -51,4 +55,6 @@ rt5663: codec@12 { compatible = "realtek,rt5663"; reg = <0x12>; interrupts = <7 IRQ_TYPE_EDGE_FALLING>; + avdd-supply = <&pp1800_a_alc5662>; + cpvdd-supply = <&pp3500_a_alc5662>; }; diff --git a/Documentation/devicetree/bindings/sound/sgtl5000.txt b/Documentation/devicetree/bindings/sound/sgtl5000.txt index 9c58f724396a..9d9ff5184939 100644 --- a/Documentation/devicetree/bindings/sound/sgtl5000.txt +++ b/Documentation/devicetree/bindings/sound/sgtl5000.txt @@ -37,6 +37,15 @@ VDDIO 1.8V 2.5V 3.3V 2 = 3.33 mA 5.74 mA 8.03 mA 3 = 4.99 mA 8.61 mA 12.05 mA +- sclk-strength: the SCLK pad strength. Possible values are: +0, 1, 2 and 3 as per the table below: + +VDDIO 1.8V 2.5V 3.3V +0 = Disable +1 = 1.66 mA 2.87 mA 4.02 mA +2 = 3.33 mA 5.74 mA 8.03 mA +3 = 4.99 mA 8.61 mA 12.05 mA + Example: sgtl5000: codec@a { diff --git a/Documentation/devicetree/bindings/sound/simple-amplifier.txt b/Documentation/devicetree/bindings/sound/simple-amplifier.txt index 8647edae7af0..7182ac4f1e65 100644 --- a/Documentation/devicetree/bindings/sound/simple-amplifier.txt +++ b/Documentation/devicetree/bindings/sound/simple-amplifier.txt @@ -4,9 +4,14 @@ Required properties: - compatible : "dioo,dio2125" or "simple-audio-amplifier" - enable-gpios : the gpio connected to the enable pin of the simple amplifier +Optional properties: +- VCC-supply : power supply for the device, as covered + in Documentation/devicetree/bindings/regulator/regulator.txt + Example: amp: analog-amplifier { compatible = "simple-audio-amplifier"; + VCC-supply = <®ulator>; enable-gpios = <&gpio GPIOH_3 0>; }; diff --git a/Documentation/devicetree/bindings/sound/simple-card.txt b/Documentation/devicetree/bindings/sound/simple-card.txt index a4c72d09cd45..4629c8f8a6b6 100644 --- a/Documentation/devicetree/bindings/sound/simple-card.txt +++ b/Documentation/devicetree/bindings/sound/simple-card.txt @@ -95,7 +95,9 @@ Optional CPU/CODEC subnodes properties: initialization. It is useful for some aCPUs with fixed clocks. +------------------------------------------- Example 1 - single DAI link: +------------------------------------------- sound { compatible = "simple-audio-card"; @@ -138,7 +140,9 @@ sh_fsi2: sh_fsi2@ec230000 { interrupts = <0 146 0x4>; }; +------------------------------------------- Example 2 - many DAI links: +------------------------------------------- sound { compatible = "simple-audio-card"; @@ -176,8 +180,10 @@ sound { }; }; +------------------------------------------- Example 3 - route audio from IMX6 SSI2 through TLV320DAC3100 codec through TPA6130A2 amplifier to headphones: +------------------------------------------- &i2c0 { codec: tlv320dac3100@18 { @@ -210,3 +216,134 @@ sound { clocks = ... }; }; + +------------------------------------------- +Example 4. Sampling Rate Conversion +------------------------------------------- + +sound { + compatible = "simple-audio-card"; + + simple-audio-card,name = "rsnd-ak4643"; + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&sndcodec>; + simple-audio-card,frame-master = <&sndcodec>; + + simple-audio-card,convert-rate = <48000>; + + simple-audio-card,prefix = "ak4642"; + simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", + "DAI0 Capture", "ak4642 Capture"; + + sndcpu: simple-audio-card,cpu { + sound-dai = <&rcar_sound>; + }; + + sndcodec: simple-audio-card,codec { + sound-dai = <&ak4643>; + system-clock-frequency = <11289600>; + }; +}; + +------------------------------------------- +Example 5. 2 CPU 1 Codec (Mixing) +------------------------------------------- +sound { + compatible = "simple-audio-card"; + + simple-audio-card,name = "rsnd-ak4643"; + simple-audio-card,format = "left_j"; + simple-audio-card,bitclock-master = <&dpcmcpu>; + simple-audio-card,frame-master = <&dpcmcpu>; + + simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", + "ak4642 Playback", "DAI1 Playback"; + + dpcmcpu: cpu@0 { + sound-dai = <&rcar_sound 0>; + }; + + cpu@1 { + sound-dai = <&rcar_sound 1>; + }; + + codec { + prefix = "ak4642"; + sound-dai = <&ak4643>; + clocks = <&audio_clock>; + }; +}; + +------------------------------------------- +Example 6 - many DAI links with DPCM: +------------------------------------------- + +CPU0 ------ ak4613 +CPU1 ------ PCM3168A-p /* DPCM 1ch/2ch */ +CPU2 --/ /* DPCM 3ch/4ch */ +CPU3 --/ /* DPCM 5ch/6ch */ +CPU4 --/ /* DPCM 7ch/8ch */ +CPU5 ------ PCM3168A-c + +sound { + compatible = "simple-audio-card"; + + simple-audio-card,routing = + "pcm3168a Playback", "DAI1 Playback", + "pcm3168a Playback", "DAI2 Playback", + "pcm3168a Playback", "DAI3 Playback", + "pcm3168a Playback", "DAI4 Playback"; + + simple-audio-card,dai-link@0 { + format = "left_j"; + bitclock-master = <&sndcpu0>; + frame-master = <&sndcpu0>; + + sndcpu0: cpu { + sound-dai = <&rcar_sound 0>; + }; + codec { + sound-dai = <&ak4613>; + }; + }; + simple-audio-card,dai-link@1 { + format = "i2s"; + bitclock-master = <&sndcpu1>; + frame-master = <&sndcpu1>; + + convert-channels = <8>; /* TDM Split */ + + sndcpu1: cpu@0 { + sound-dai = <&rcar_sound 1>; + }; + cpu@1 { + sound-dai = <&rcar_sound 2>; + }; + cpu@2 { + sound-dai = <&rcar_sound 3>; + }; + cpu@3 { + sound-dai = <&rcar_sound 4>; + }; + codec { + mclk-fs = <512>; + prefix = "pcm3168a"; + dai-tdm-slot-num = <8>; + sound-dai = <&pcm3168a 0>; + }; + }; + simple-audio-card,dai-link@2 { + format = "i2s"; + bitclock-master = <&sndcpu2>; + frame-master = <&sndcpu2>; + + sndcpu2: cpu { + sound-dai = <&rcar_sound 5>; + }; + codec { + mclk-fs = <512>; + prefix = "pcm3168a"; + sound-dai = <&pcm3168a 1>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/sound/simple-scu-card.txt b/Documentation/devicetree/bindings/sound/simple-scu-card.txt deleted file mode 100644 index 32f8dbce5241..000000000000 --- a/Documentation/devicetree/bindings/sound/simple-scu-card.txt +++ /dev/null @@ -1,94 +0,0 @@ -ASoC Simple SCU Sound Card - -Simple SCU Sound Card is "Simple Sound Card" + "ALSA DPCM". -For example, you can use this driver if you want to exchange sampling rate convert, -Mixing, etc... - -Required properties: - -- compatible : "simple-scu-audio-card" - "renesas,rsrc-card" -Optional properties: - -- simple-audio-card,name : see simple-audio-card.txt -- simple-audio-card,cpu : see simple-audio-card.txt -- simple-audio-card,codec : see simple-audio-card.txt - -Optional subnode properties: - -- simple-audio-card,format : see simple-audio-card.txt -- simple-audio-card,frame-master : see simple-audio-card.txt -- simple-audio-card,bitclock-master : see simple-audio-card.txt -- simple-audio-card,bitclock-inversion : see simple-audio-card.txt -- simple-audio-card,frame-inversion : see simple-audio-card.txt -- simple-audio-card,convert-rate : platform specified sampling rate convert -- simple-audio-card,convert-channels : platform specified converted channel size (2 - 8 ch) -- simple-audio-card,prefix : see routing -- simple-audio-card,widgets : Please refer to widgets.txt. -- simple-audio-card,routing : A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources. - use audio-prefix if some components is using same sink/sources naming. - it can be used if compatible was "renesas,rsrc-card"; - -Required CPU/CODEC subnodes properties: - -- sound-dai : see simple-audio-card.txt - -Optional CPU/CODEC subnodes properties: - -- clocks / system-clock-frequency : see simple-audio-card.txt - -Example 1. Sampling Rate Conversion - -sound { - compatible = "simple-scu-audio-card"; - - simple-audio-card,name = "rsnd-ak4643"; - simple-audio-card,format = "left_j"; - simple-audio-card,bitclock-master = <&sndcodec>; - simple-audio-card,frame-master = <&sndcodec>; - - simple-audio-card,convert-rate = <48000>; - - simple-audio-card,prefix = "ak4642"; - simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", - "DAI0 Capture", "ak4642 Capture"; - - sndcpu: simple-audio-card,cpu { - sound-dai = <&rcar_sound>; - }; - - sndcodec: simple-audio-card,codec { - sound-dai = <&ak4643>; - system-clock-frequency = <11289600>; - }; -}; - -Example 2. 2 CPU 1 Codec (Mixing) - -sound { - compatible = "simple-scu-audio-card"; - - simple-audio-card,name = "rsnd-ak4643"; - simple-audio-card,format = "left_j"; - simple-audio-card,bitclock-master = <&dpcmcpu>; - simple-audio-card,frame-master = <&dpcmcpu>; - - simple-audio-card,prefix = "ak4642"; - simple-audio-card,routing = "ak4642 Playback", "DAI0 Playback", - "ak4642 Playback", "DAI1 Playback"; - - dpcmcpu: cpu@0 { - sound-dai = <&rcar_sound 0>; - }; - - cpu@1 { - sound-dai = <&rcar_sound 1>; - }; - - codec { - sound-dai = <&ak4643>; - clocks = <&audio_clock>; - }; -}; diff --git a/Documentation/devicetree/bindings/sound/sprd-pcm.txt b/Documentation/devicetree/bindings/sound/sprd-pcm.txt new file mode 100644 index 000000000000..4b23e84b2e57 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/sprd-pcm.txt @@ -0,0 +1,23 @@ +* Spreadtrum DMA platfrom bindings + +Required properties: +- compatible: Should be "sprd,pcm-platform". +- dmas: Specify the list of DMA controller phandle and DMA request line ordered pairs. +- dma-names: Identifier string for each DMA request line in the dmas property. + These strings correspond 1:1 with the ordered pairs in dmas. + +Example: + + audio_platform:platform@0 { + compatible = "sprd,pcm-platform"; + dmas = <&agcp_dma 1 1>, <&agcp_dma 2 2>, + <&agcp_dma 3 3>, <&agcp_dma 4 4>, + <&agcp_dma 5 5>, <&agcp_dma 6 6>, + <&agcp_dma 7 7>, <&agcp_dma 8 8>, + <&agcp_dma 9 9>, <&agcp_dma 10 10>; + dma-names = "normal_p_l", "normal_p_r", + "normal_c_l", "normal_c_r", + "voice_c", "fast_p", + "loop_c", "loop_p", + "voip_c", "voip_p"; + }; diff --git a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt b/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt index 4f8ad0e04d20..056a098495cc 100644 --- a/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt +++ b/Documentation/devicetree/bindings/sound/sun50i-codec-analog.txt @@ -4,9 +4,11 @@ Required properties: - compatible: must be one of the following compatibles: - "allwinner,sun50i-a64-codec-analog" - reg: must contain the registers location and length +- cpvdd-supply: Regulator supply for the headphone amplifier Example: codec_analog: codec-analog@1f015c0 { compatible = "allwinner,sun50i-a64-codec-analog"; reg = <0x01f015c0 0x4>; + cpvdd-supply = <®_eldo1>; }; diff --git a/Documentation/devicetree/bindings/sound/xlnx,audio-formatter.txt b/Documentation/devicetree/bindings/sound/xlnx,audio-formatter.txt new file mode 100644 index 000000000000..cbc93c8f4963 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/xlnx,audio-formatter.txt @@ -0,0 +1,29 @@ +Device-Tree bindings for Xilinx PL audio formatter + +The IP core supports DMA, data formatting(AES<->PCM conversion) +of audio samples. + +Required properties: + - compatible: "xlnx,audio-formatter-1.0" + - interrupt-names: Names specified to list of interrupts in same + order mentioned under "interrupts". + List of supported interrupt names are: + "irq_mm2s" : interrupt from MM2S block + "irq_s2mm" : interrupt from S2MM block + - interrupts-parent: Phandle for interrupt controller. + - interrupts: List of Interrupt numbers. + - reg: Base address and size of the IP core instance. + - clock-names: List of input clocks. + Required elements: "s_axi_lite_aclk", "aud_mclk" + - clocks: Input clock specifier. Refer to common clock bindings. + +Example: + audio_ss_0_audio_formatter_0: audio_formatter@80010000 { + compatible = "xlnx,audio-formatter-1.0"; + interrupt-names = "irq_mm2s", "irq_s2mm"; + interrupt-parent = <&gic>; + interrupts = <0 104 4>, <0 105 4>; + reg = <0x0 0x80010000 0x0 0x1000>; + clock-names = "s_axi_lite_aclk", "aud_mclk"; + clocks = <&clk 71>, <&clk_wiz_1 0>; + }; diff --git a/Documentation/devicetree/bindings/sound/xlnx,i2s.txt b/Documentation/devicetree/bindings/sound/xlnx,i2s.txt new file mode 100644 index 000000000000..5e7c7d5bb60a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/xlnx,i2s.txt @@ -0,0 +1,28 @@ +Device-Tree bindings for Xilinx I2S PL block + +The IP supports I2S based playback/capture audio + +Required property: + - compatible: "xlnx,i2s-transmitter-1.0" for playback and + "xlnx,i2s-receiver-1.0" for capture + +Required property common to both I2S playback and capture: + - reg: Base address and size of the IP core instance. + - xlnx,dwidth: sample data width. Can be any of 16, 24. + - xlnx,num-channels: Number of I2S streams. Can be any of 1, 2, 3, 4. + supported channels = 2 * xlnx,num-channels + +Example: + + i2s_receiver@a0080000 { + compatible = "xlnx,i2s-receiver-1.0"; + reg = <0x0 0xa0080000 0x0 0x10000>; + xlnx,dwidth = <0x18>; + xlnx,num-channels = <1>; + }; + i2s_transmitter@a0090000 { + compatible = "xlnx,i2s-transmitter-1.0"; + reg = <0x0 0xa0090000 0x0 0x10000>; + xlnx,dwidth = <0x18>; + xlnx,num-channels = <1>; + }; diff --git a/Documentation/devicetree/bindings/sound/xlnx,spdif.txt b/Documentation/devicetree/bindings/sound/xlnx,spdif.txt new file mode 100644 index 000000000000..15c2d64d247c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/xlnx,spdif.txt @@ -0,0 +1,28 @@ +Device-Tree bindings for Xilinx SPDIF IP + +The IP supports playback and capture of SPDIF audio + +Required properties: + - compatible: "xlnx,spdif-2.0" + - clock-names: List of input clocks. + Required elements: "s_axi_aclk", "aud_clk_i" + - clocks: Input clock specifier. Refer to common clock bindings. + - reg: Base address and address length of the IP core instance. + - interrupts-parent: Phandle for interrupt controller. + - interrupts: List of Interrupt numbers. + - xlnx,spdif-mode: 0 :- receiver mode + 1 :- transmitter mode + - xlnx,aud_clk_i: input audio clock value. + +Example: + spdif_0: spdif@80010000 { + clock-names = "aud_clk_i", "s_axi_aclk"; + clocks = <&misc_clk_0>, <&clk 71>; + compatible = "xlnx,spdif-2.0"; + interrupt-names = "spdif_interrupt"; + interrupt-parent = <&gic>; + interrupts = <0 91 4>; + reg = <0x0 0x80010000 0x0 0x10000>; + xlnx,spdif-mode = <1>; + xlnx,aud_clk_i = <49152913>; + }; diff --git a/Documentation/devicetree/bindings/mtd/atmel-quadspi.txt b/Documentation/devicetree/bindings/spi/atmel-quadspi.txt index b93c1e2f25dd..7c40ea694352 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-quadspi.txt +++ b/Documentation/devicetree/bindings/spi/atmel-quadspi.txt @@ -1,14 +1,19 @@ * Atmel Quad Serial Peripheral Interface (QSPI) Required properties: -- compatible: Should be "atmel,sama5d2-qspi". +- compatible: Should be one of the following: + - "atmel,sama5d2-qspi" + - "microchip,sam9x60-qspi" - reg: Should contain the locations and lengths of the base registers and the mapped memory. - reg-names: Should contain the resource reg names: - qspi_base: configuration register address space - qspi_mmap: memory mapped address space - interrupts: Should contain the interrupt for the device. -- clocks: The phandle of the clock needed by the QSPI controller. +- clocks: Should reference the peripheral clock and the QSPI system + clock if available. +- clock-names: Should contain "pclk" for the peripheral clock and "qspick" + for the system clock when available. - #address-cells: Should be <1>. - #size-cells: Should be <0>. @@ -19,7 +24,8 @@ spi@f0020000 { reg = <0xf0020000 0x100>, <0xd0000000 0x8000000>; reg-names = "qspi_base", "qspi_mmap"; interrupts = <52 IRQ_TYPE_LEVEL_HIGH 7>; - clocks = <&spi0_clk>; + clocks = <&pmc PMC_TYPE_PERIPHERAL 52>; + clock-names = "pclk"; #address-cells = <1>; #size-cells = <0>; pinctrl-names = "default"; diff --git a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt index e3c48b20b1a6..2d3264140cc5 100644 --- a/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt +++ b/Documentation/devicetree/bindings/spi/fsl-imx-cspi.txt @@ -10,6 +10,7 @@ Required properties: - "fsl,imx35-cspi" for SPI compatible with the one integrated on i.MX35 - "fsl,imx51-ecspi" for SPI compatible with the one integrated on i.MX51 - "fsl,imx53-ecspi" for SPI compatible with the one integrated on i.MX53 and later Soc + - "fsl,imx8mq-ecspi" for SPI compatible with the one integrated on i.MX8M - reg : Offset and length of the register set for the device - interrupts : Should contain CSPI/eCSPI interrupt - clocks : Clock specifiers for both ipg and per clocks. diff --git a/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt new file mode 100644 index 000000000000..1fd9a4406a1d --- /dev/null +++ b/Documentation/devicetree/bindings/spi/nuvoton,npcm-pspi.txt @@ -0,0 +1,43 @@ +Nuvoton NPCM Peripheral Serial Peripheral Interface(PSPI) controller driver + +Nuvoton NPCM7xx SOC support two PSPI channels. + +Required properties: + - compatible : "nuvoton,npcm750-pspi" for NPCM7XX BMC + - #address-cells : should be 1. see spi-bus.txt + - #size-cells : should be 0. see spi-bus.txt + - specifies physical base address and size of the register. + - interrupts : contain PSPI interrupt. + - clocks : phandle of PSPI reference clock. + - clock-names: Should be "clk_apb5". + - pinctrl-names : a pinctrl state named "default" must be defined. + - pinctrl-0 : phandle referencing pin configuration of the device. + - cs-gpios: Specifies the gpio pins to be used for chipselects. + See: Documentation/devicetree/bindings/spi/spi-bus.txt + +Optional properties: +- clock-frequency : Input clock frequency to the PSPI block in Hz. + Default is 25000000 Hz. + +Aliases: +- All the SPI controller nodes should be represented in the aliases node using + the following format 'spi{n}' withe the correct numbered in "aliases" node. + +Example: + +aliases { + spi0 = &spi0; +}; + +spi0: spi@f0200000 { + compatible = "nuvoton,npcm750-pspi"; + reg = <0xf0200000 0x1000>; + pinctrl-names = "default"; + pinctrl-0 = <&pspi1_pins>; + #address-cells = <1>; + #size-cells = <0>; + interrupts = <GIC_SPI 31 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk NPCM7XX_CLK_APB5>; + clock-names = "clk_apb5"; + cs-gpios = <&gpio6 11 GPIO_ACTIVE_LOW>; +}; diff --git a/Documentation/devicetree/bindings/spi/omap-spi.txt b/Documentation/devicetree/bindings/spi/omap-spi.txt index 2ba5f9c023ac..487208c256c0 100644 --- a/Documentation/devicetree/bindings/spi/omap-spi.txt +++ b/Documentation/devicetree/bindings/spi/omap-spi.txt @@ -2,6 +2,7 @@ OMAP2+ McSPI device Required properties: - compatible : + - "ti,am654-mcspi" for AM654. - "ti,omap2-mcspi" for OMAP2 & OMAP3. - "ti,omap4-mcspi" for OMAP4+. - ti,spi-num-cs : Number of chipselect supported by the instance. diff --git a/Documentation/devicetree/bindings/spi/sh-msiof.txt b/Documentation/devicetree/bindings/spi/sh-msiof.txt index 4b836ad17b19..37cf69586d10 100644 --- a/Documentation/devicetree/bindings/spi/sh-msiof.txt +++ b/Documentation/devicetree/bindings/spi/sh-msiof.txt @@ -5,6 +5,7 @@ Required properties: "renesas,msiof-r8a7744" (RZ/G1N) "renesas,msiof-r8a7745" (RZ/G1E) "renesas,msiof-r8a774a1" (RZ/G2M) + "renesas,msiof-r8a774c0" (RZ/G2E) "renesas,msiof-r8a7790" (R-Car H2) "renesas,msiof-r8a7791" (R-Car M2-W) "renesas,msiof-r8a7792" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt index 8d178a4503cf..6cc3c6fe25a3 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.txt @@ -5,8 +5,11 @@ Required properties: - "fsl,imx7ulp-spi" for LPSPI compatible with the one integrated on i.MX7ULP soc - "fsl,imx8qxp-spi" for LPSPI compatible with the one integrated on i.MX8QXP soc - reg : address and length of the lpspi master registers +- interrupt-parent : core interrupt controller - interrupts : lpspi interrupt - clocks : lpspi clock specifier +- spi-slave : spi slave mode support. In slave mode, add this attribute without + value. In master mode, remove it. Examples: @@ -16,4 +19,5 @@ lpspi2: lpspi@40290000 { interrupt-parent = <&intc>; interrupts = <GIC_SPI 28 IRQ_TYPE_LEVEL_HIGH>; clocks = <&clks IMX7ULP_CLK_LPSPI2>; + spi-slave; }; diff --git a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt index 483e9cfac1b1..e8f1d627d288 100644 --- a/Documentation/devicetree/bindings/mtd/fsl-quadspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-fsl-qspi.txt @@ -14,15 +14,13 @@ Required properties: - clocks : The clocks needed by the QuadSPI controller - clock-names : Should contain the name of the clocks: "qspi_en" and "qspi". -Optional properties: - - fsl,qspi-has-second-chip: The controller has two buses, bus A and bus B. - Each bus can be connected with two NOR flashes. - Most of the time, each bus only has one NOR flash - connected, this is the default case. - But if there are two NOR flashes connected to the - bus, you should enable this property. - (Please check the board's schematic.) - - big-endian : That means the IP register is big endian +Required SPI slave node properties: + - reg: There are two buses (A and B) with two chip selects each. + This encodes to which bus and CS the flash is connected: + <0>: Bus A, CS 0 + <1>: Bus A, CS 1 + <2>: Bus B, CS 0 + <3>: Bus B, CS 1 Example: @@ -40,7 +38,7 @@ qspi0: quadspi@40044000 { }; }; -Example showing the usage of two SPI NOR devices: +Example showing the usage of two SPI NOR devices on bus A: &qspi2 { pinctrl-names = "default"; diff --git a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt index 236dcb0faf37..69c356767cf8 100644 --- a/Documentation/devicetree/bindings/spi/spi-mt65xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-mt65xx.txt @@ -6,8 +6,10 @@ Required properties: - mediatek,mt2712-spi: for mt2712 platforms - mediatek,mt6589-spi: for mt6589 platforms - mediatek,mt7622-spi: for mt7622 platforms + - "mediatek,mt7629-spi", "mediatek,mt7622-spi": for mt7629 platforms - mediatek,mt8135-spi: for mt8135 platforms - mediatek,mt8173-spi: for mt8173 platforms + - mediatek,mt8183-spi: for mt8183 platforms - #address-cells: should be 1. diff --git a/Documentation/devicetree/bindings/spi/spi-mxic.txt b/Documentation/devicetree/bindings/spi/spi-mxic.txt new file mode 100644 index 000000000000..529f2dab2648 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-mxic.txt @@ -0,0 +1,34 @@ +Macronix SPI controller Device Tree Bindings +-------------------------------------------- + +Required properties: +- compatible: should be "mxicy,mx25f0a-spi" +- #address-cells: should be 1 +- #size-cells: should be 0 +- reg: should contain 2 entries, one for the registers and one for the direct + mapping area +- reg-names: should contain "regs" and "dirmap" +- interrupts: interrupt line connected to the SPI controller +- clock-names: should contain "ps_clk", "send_clk" and "send_dly_clk" +- clocks: should contain 3 entries for the "ps_clk", "send_clk" and + "send_dly_clk" clocks + +Example: + + spi@43c30000 { + compatible = "mxicy,mx25f0a-spi"; + reg = <0x43c30000 0x10000>, <0xa0000000 0x20000000>; + reg-names = "regs", "dirmap"; + clocks = <&clkwizard 0>, <&clkwizard 1>, <&clkc 18>; + clock-names = "send_clk", "send_dly_clk", "ps_clk"; + #address-cells = <1>; + #size-cells = <0>; + + flash@0 { + compatible = "jedec,spi-nor"; + reg = <0>; + spi-max-frequency = <25000000>; + spi-tx-bus-width = <4>; + spi-rx-bus-width = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt new file mode 100644 index 000000000000..2cd67eb727d4 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.txt @@ -0,0 +1,39 @@ +* NXP Flex Serial Peripheral Interface (FSPI) + +Required properties: + - compatible : Should be "nxp,lx2160a-fspi" + - reg : First contains the register location and length, + Second contains the memory mapping address and length + - reg-names : Should contain the resource reg names: + - fspi_base: configuration register address space + - fspi_mmap: memory mapped address space + - interrupts : Should contain the interrupt for the device + +Required SPI slave node properties: + - reg : There are two buses (A and B) with two chip selects each. + This encodes to which bus and CS the flash is connected: + - <0>: Bus A, CS 0 + - <1>: Bus A, CS 1 + - <2>: Bus B, CS 0 + - <3>: Bus B, CS 1 + +Example showing the usage of two SPI NOR slave devices on bus A: + +fspi0: spi@20c0000 { + compatible = "nxp,lx2160a-fspi"; + reg = <0x0 0x20c0000 0x0 0x10000>, <0x0 0x20000000 0x0 0x10000000>; + reg-names = "fspi_base", "fspi_mmap"; + interrupts = <0 25 0x4>; /* Level high type */ + clocks = <&clockgen 4 3>, <&clockgen 4 3>; + clock-names = "fspi_en", "fspi"; + + mt35xu512aba0: flash@0 { + reg = <0>; + .... + }; + + mt35xu512aba1: flash@1 { + reg = <1>; + .... + }; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-pxa2xx.txt b/Documentation/devicetree/bindings/spi/spi-pxa2xx.txt index 0335a9bd2e8a..e30e0c2a4bce 100644 --- a/Documentation/devicetree/bindings/spi/spi-pxa2xx.txt +++ b/Documentation/devicetree/bindings/spi/spi-pxa2xx.txt @@ -11,6 +11,9 @@ Required properties: Optional properties: - cs-gpios: list of GPIO chip selects. See the SPI bus bindings, Documentation/devicetree/bindings/spi/spi-bus.txt +- spi-slave: Empty property indicating the SPI controller is used in slave mode. +- ready-gpios: GPIO used to signal a SPI master that the FIFO is filled + and we're ready to service a transfer. Only useful in slave mode. Child nodes represent devices on the SPI bus See ../spi/spi-bus.txt diff --git a/Documentation/devicetree/bindings/spi/spi-rspi.txt b/Documentation/devicetree/bindings/spi/spi-rspi.txt index fc97ad64fbf2..421722b93992 100644 --- a/Documentation/devicetree/bindings/spi/spi-rspi.txt +++ b/Documentation/devicetree/bindings/spi/spi-rspi.txt @@ -15,6 +15,7 @@ Required properties: - "renesas,qspi-r8a7743" (RZ/G1M) - "renesas,qspi-r8a7744" (RZ/G1N) - "renesas,qspi-r8a7745" (RZ/G1E) + - "renesas,qspi-r8a77470" (RZ/G1C) - "renesas,qspi-r8a7790" (R-Car H2) - "renesas,qspi-r8a7791" (R-Car M2-W) - "renesas,qspi-r8a7792" (R-Car V2H) diff --git a/Documentation/devicetree/bindings/spi/spi-sifive.txt b/Documentation/devicetree/bindings/spi/spi-sifive.txt new file mode 100644 index 000000000000..3f5c6e438972 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-sifive.txt @@ -0,0 +1,37 @@ +SiFive SPI controller Device Tree Bindings +------------------------------------------ + +Required properties: +- compatible : Should be "sifive,<chip>-spi" and "sifive,spi<version>". + Supported compatible strings are: + "sifive,fu540-c000-spi" for the SiFive SPI v0 as integrated + onto the SiFive FU540 chip, and "sifive,spi0" for the SiFive + SPI v0 IP block with no chip integration tweaks. + Please refer to sifive-blocks-ip-versioning.txt for details +- reg : Physical base address and size of SPI registers map + A second (optional) range can indicate memory mapped flash +- interrupts : Must contain one entry +- interrupt-parent : Must be core interrupt controller +- clocks : Must reference the frequency given to the controller +- #address-cells : Must be '1', indicating which CS to use +- #size-cells : Must be '0' + +Optional properties: +- sifive,fifo-depth : Depth of hardware queues; defaults to 8 +- sifive,max-bits-per-word : Maximum bits per word; defaults to 8 + +SPI RTL that corresponds to the IP block version numbers can be found here: +https://github.com/sifive/sifive-blocks/tree/master/src/main/scala/devices/spi + +Example: + spi: spi@10040000 { + compatible = "sifive,fu540-c000-spi", "sifive,spi0"; + reg = <0x0 0x10040000 0x0 0x1000 0x0 0x20000000 0x0 0x10000000>; + interrupt-parent = <&plic>; + interrupts = <51>; + clocks = <&tlclk>; + #address-cells = <1>; + #size-cells = <0>; + sifive,fifo-depth = <8>; + sifive,max-bits-per-word = <8>; + }; diff --git a/Documentation/devicetree/bindings/spi/spi-sprd.txt b/Documentation/devicetree/bindings/spi/spi-sprd.txt index bad211a19da4..3c7eacce0ee3 100644 --- a/Documentation/devicetree/bindings/spi/spi-sprd.txt +++ b/Documentation/devicetree/bindings/spi/spi-sprd.txt @@ -14,6 +14,11 @@ Required properties: address on the SPI bus. Should be set to 1. - #size-cells: Should be set to 0. +Optional properties: +dma-names: Should contain names of the SPI used DMA channel. +dmas: Should contain DMA channels and DMA slave ids which the SPI used + sorted in the same order as the dma-names property. + Example: spi0: spi@70a00000{ compatible = "sprd,sc9860-spi"; @@ -21,6 +26,8 @@ spi0: spi@70a00000{ interrupts = <GIC_SPI 7 IRQ_TYPE_LEVEL_HIGH>; clock-names = "spi", "source","enable"; clocks = <&clk_spi0>, <&ext_26m>, <&clk_ap_apb_gates 5>; + dma-names = "rx_chn", "tx_chn"; + dmas = <&apdma 11 11>, <&apdma 12 12>; #address-cells = <1>; #size-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/spi/spi-stm32.txt b/Documentation/devicetree/bindings/spi/spi-stm32.txt index 1b3fa2c119d5..d82755c63eaf 100644 --- a/Documentation/devicetree/bindings/spi/spi-stm32.txt +++ b/Documentation/devicetree/bindings/spi/spi-stm32.txt @@ -7,7 +7,9 @@ from 4 to 32-bit data size. Although it can be configured as master or slave, only master is supported by the driver. Required properties: -- compatible: Must be "st,stm32h7-spi". +- compatible: Should be one of: + "st,stm32h7-spi" + "st,stm32f4-spi" - reg: Offset and length of the device's register set. - interrupts: Must contain the interrupt id. - clocks: Must contain an entry for spiclk (which feeds the internal clock @@ -30,8 +32,9 @@ Child nodes represent devices on the SPI bus See ../spi/spi-bus.txt Optional properties: -- st,spi-midi-ns: (Master Inter-Data Idleness) minimum time delay in - nanoseconds inserted between two consecutive data frames. +- st,spi-midi-ns: Only for STM32H7, (Master Inter-Data Idleness) minimum time + delay in nanoseconds inserted between two consecutive data + frames. Example: diff --git a/Documentation/devicetree/bindings/spi/spi-uniphier.txt b/Documentation/devicetree/bindings/spi/spi-uniphier.txt index 504a4ecfc7b1..e1201573a29a 100644 --- a/Documentation/devicetree/bindings/spi/spi-uniphier.txt +++ b/Documentation/devicetree/bindings/spi/spi-uniphier.txt @@ -7,8 +7,11 @@ Required properties: - reg: address and length of the spi master registers - #address-cells: must be <1>, see spi-bus.txt - #size-cells: must be <0>, see spi-bus.txt - - clocks: A phandle to the clock for the device. - - resets: A phandle to the reset control for the device. + - interrupts: a single interrupt specifier + - pinctrl-names: should be "default" + - pinctrl-0: pin control state for the default mode + - clocks: a phandle to the clock for the device + - resets: a phandle to the reset control for the device Example: @@ -17,6 +20,9 @@ spi0: spi@54006000 { reg = <0x54006000 0x100>; #address-cells = <1>; #size-cells = <0>; + interrupts = <0 39 4>; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_spi0>; clocks = <&peri_clk 11>; resets = <&peri_rst 11>; }; diff --git a/Documentation/devicetree/bindings/sram/milbeaut-smp-sram.txt b/Documentation/devicetree/bindings/sram/milbeaut-smp-sram.txt new file mode 100644 index 000000000000..194f6a3c1c1e --- /dev/null +++ b/Documentation/devicetree/bindings/sram/milbeaut-smp-sram.txt @@ -0,0 +1,24 @@ +Milbeaut SRAM for smp bringup + +Milbeaut SoCs use a part of the sram for the bringup of the secondary cores. +Once they get powered up in the bootloader, they stay at the specific part +of the sram. +Therefore the part needs to be added as the sub-node of mmio-sram. + +Required sub-node properties: +- compatible : should be "socionext,milbeaut-smp-sram" + +Example: + + sram: sram@0 { + compatible = "mmio-sram"; + reg = <0x0 0x10000>; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0 0x0 0x10000>; + + smp-sram@f100 { + compatible = "socionext,milbeaut-smp-sram"; + reg = <0xf100 0x20>; + }; + }; diff --git a/Documentation/devicetree/bindings/sram/sunxi-sram.txt b/Documentation/devicetree/bindings/sram/sunxi-sram.txt index c51ade86578c..380246a805f2 100644 --- a/Documentation/devicetree/bindings/sram/sunxi-sram.txt +++ b/Documentation/devicetree/bindings/sram/sunxi-sram.txt @@ -18,6 +18,9 @@ Required properties: - "allwinner,sun8i-h3-system-control" - "allwinner,sun50i-a64-sram-controller" (deprecated) - "allwinner,sun50i-a64-system-control" + - "allwinner,sun50i-h5-system-control" + - "allwinner,sun50i-h6-system-control", "allwinner,sun50i-a64-system-control" + - "allwinner,suniv-f1c100s-system-control", "allwinner,sun4i-a10-system-control" - reg : sram controller register offset + length SRAM nodes @@ -53,6 +56,17 @@ The valid sections compatible for H3 are: The valid sections compatible for A64 are: - allwinner,sun50i-a64-sram-c + - allwinner,sun50i-a64-sram-c1, allwinner,sun4i-a10-sram-c1 + +The valid sections compatible for H5 are: + - allwinner,sun50i-h5-sram-c1, allwinner,sun4i-a10-sram-c1 + +The valid sections compatible for H6 are: + - allwinner,sun50i-h6-sram-c, allwinner,sun50i-a64-sram-c + - allwinner,sun50i-h6-sram-c1, allwinner,sun4i-a10-sram-c1 + +The valid sections compatible for F1C100s are: + - allwinner,suniv-f1c100s-sram-d, allwinner,sun4i-a10-sram-d Devices using SRAM sections --------------------------- diff --git a/Documentation/devicetree/bindings/thermal/brcm,sr-thermal.txt b/Documentation/devicetree/bindings/thermal/brcm,sr-thermal.txt new file mode 100644 index 000000000000..3ab330219d45 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/brcm,sr-thermal.txt @@ -0,0 +1,105 @@ +* Broadcom Stingray Thermal + +This binding describes thermal sensors that is part of Stingray SoCs. + +Required properties: +- compatible : Must be "brcm,sr-thermal" +- reg : Memory where tmon data will be available. +- brcm,tmon-mask: A one cell bit mask of valid TMON sources. + Each bit represents single TMON source. +- #thermal-sensor-cells : Thermal sensor phandler +- polling-delay: Max number of milliseconds to wait between polls. +- thermal-sensors: A list of thermal sensor phandles and specifier. + specifier value is tmon ID and it should be + in correspond with brcm,tmon-mask. +- temperature: trip temperature threshold in millicelsius. + +Example: + tmons { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x0 0x0 0x8f100000 0x100>; + + tmon: tmon@0 { + compatible = "brcm,sr-thermal"; + reg = <0x0 0x40>; + brcm,tmon-mask = <0x3f>; + #thermal-sensor-cells = <1>; + }; + }; + + thermal-zones { + ihost0_thermal: ihost0-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 0>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + ihost1_thermal: ihost1-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 1>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + ihost2_thermal: ihost2-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 2>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + ihost3_thermal: ihost3-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 3>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + crmu_thermal: crmu-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 4>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + nitro_thermal: nitro-thermal { + polling-delay-passive = <0>; + polling-delay = <1000>; + thermal-sensors = <&tmon 5>; + trips { + cpu-crit { + temperature = <105000>; + hysteresis = <0>; + type = "critical"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt index 41d6a443ad66..f8d7831f3974 100644 --- a/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/mediatek-thermal.txt @@ -13,6 +13,7 @@ Required properties: - "mediatek,mt2701-thermal" : For MT2701 family of SoCs - "mediatek,mt2712-thermal" : For MT2712 family of SoCs - "mediatek,mt7622-thermal" : For MT7622 SoC + - "mediatek,mt8183-thermal" : For MT8183 family of SoCs - reg: Address range of the thermal controller - interrupts: IRQ for the thermal controller - clocks, clock-names: Clocks needed for the thermal controller. required diff --git a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt index 276387dd6815..e17c07be270b 100644 --- a/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/nvidia,tegra186-bpmp-thermal.txt @@ -15,7 +15,8 @@ Required properties: - compatible: Array of strings. One of: - - "nvidia,tegra186-bpmp-thermal". + - "nvidia,tegra186-bpmp-thermal" + - "nvidia,tegra194-bpmp-thermal" - #thermal-sensor-cells: Cell for sensor index. Single-cell integer. Must be <1>. diff --git a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt index 290ec06fa33a..0273a92a2a84 100644 --- a/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt +++ b/Documentation/devicetree/bindings/thermal/qcom-spmi-temp-alarm.txt @@ -6,8 +6,7 @@ interrupt signal and status register to identify high PMIC die temperature. Required properties: - compatible: Should contain "qcom,spmi-temp-alarm". -- reg: Specifies the SPMI address and length of the controller's - registers. +- reg: Specifies the SPMI address. - interrupts: PMIC temperature alarm interrupt. - #thermal-sensor-cells: Should be 0. See thermal.txt for a description. @@ -20,7 +19,7 @@ Example: pm8941_temp: thermal-alarm@2400 { compatible = "qcom,spmi-temp-alarm"; - reg = <0x2400 0x100>; + reg = <0x2400>; interrupts = <0 0x24 0 IRQ_TYPE_EDGE_RISING>; #thermal-sensor-cells = <0>; @@ -36,19 +35,14 @@ Example: thermal-sensors = <&pm8941_temp>; trips { - passive { - temperature = <1050000>; + stage1 { + temperature = <105000>; hysteresis = <2000>; type = "passive"; }; - alert { + stage2 { temperature = <125000>; hysteresis = <2000>; - type = "hot"; - }; - crit { - temperature = <145000>; - hysteresis = <2000>; type = "critical"; }; }; diff --git a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt index 20ca4ef9d776..04cbb90a5d3e 100644 --- a/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/qoriq-thermal.txt @@ -1,9 +1,9 @@ * Thermal Monitoring Unit (TMU) on Freescale QorIQ SoCs Required properties: -- compatible : Must include "fsl,qoriq-tmu". The version of the device is - determined by the TMU IP Block Revision Register (IPBRR0) at - offset 0x0BF8. +- compatible : Must include "fsl,qoriq-tmu" or "fsl,imx8mq-tmu". The + version of the device is determined by the TMU IP Block Revision + Register (IPBRR0) at offset 0x0BF8. Table of correspondences between IPBRR0 values and example chips: Value Device ---------- ----- diff --git a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt index cfa154bb0fa7..b6ab60f6abbf 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-gen3-thermal.txt @@ -7,9 +7,11 @@ inside the LSI. Required properties: - compatible : "renesas,<soctype>-thermal", Examples with soctypes are: + - "renesas,r8a774a1-thermal" (RZ/G2M) - "renesas,r8a7795-thermal" (R-Car H3) - "renesas,r8a7796-thermal" (R-Car M3-W) - "renesas,r8a77965-thermal" (R-Car M3-N) + - "renesas,r8a77980-thermal" (R-Car V3H) - 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. @@ -19,7 +21,7 @@ Required properties: Optional properties: -- interrupts : interrupts routed to the TSC (3 for H3, M3-W and M3-N) +- interrupts : interrupts routed to the TSC (must be 3). - 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. diff --git a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt index 67c563f1b4c4..196112d23b1e 100644 --- a/Documentation/devicetree/bindings/thermal/rcar-thermal.txt +++ b/Documentation/devicetree/bindings/thermal/rcar-thermal.txt @@ -4,15 +4,19 @@ Required properties: - compatible : "renesas,thermal-<soctype>", "renesas,rcar-gen2-thermal" (with thermal-zone) or "renesas,rcar-thermal" (without thermal-zone) as - fallback except R-Car D3. + fallback except R-Car V3M/E3/D3 and RZ/G2E. Examples with soctypes are: - "renesas,thermal-r8a73a4" (R-Mobile APE6) - "renesas,thermal-r8a7743" (RZ/G1M) + - "renesas,thermal-r8a7744" (RZ/G1N) + - "renesas,thermal-r8a774c0" (RZ/G2E) - "renesas,thermal-r8a7779" (R-Car H1) - "renesas,thermal-r8a7790" (R-Car H2) - "renesas,thermal-r8a7791" (R-Car M2-W) - "renesas,thermal-r8a7792" (R-Car V2H) - "renesas,thermal-r8a7793" (R-Car M2-N) + - "renesas,thermal-r8a77970" (R-Car V3M) + - "renesas,thermal-r8a77990" (R-Car E3) - "renesas,thermal-r8a77995" (R-Car D3) - reg : Address range of the thermal registers. The 1st reg will be recognized as common register @@ -21,7 +25,7 @@ Required properties: Option properties: - interrupts : If present should contain 3 interrupts for - R-Car D3 or 1 interrupt otherwise. + R-Car V3M/E3/D3 and RZ/G2E or 1 interrupt otherwise. Example (non interrupt support): diff --git a/Documentation/devicetree/bindings/thermal/stm32-thermal.txt b/Documentation/devicetree/bindings/thermal/stm32-thermal.txt new file mode 100644 index 000000000000..8c0d5a4d8031 --- /dev/null +++ b/Documentation/devicetree/bindings/thermal/stm32-thermal.txt @@ -0,0 +1,61 @@ +Binding for Thermal Sensor for STMicroelectronics STM32 series of SoCs. + +On STM32 SoCs, the Digital Temperature Sensor (DTS) is in charge of managing an +analog block which delivers a frequency depending on the internal SoC's +temperature. By using a reference frequency, DTS is able to provide a sample +number which can be translated into a temperature by the user. + +DTS provides interrupt notification mechanism by threshold. This mechanism +offers two temperature trip points: passive and critical. The first is intended +for passive cooling notification while the second is used for over-temperature +reset. + +Required parameters: +------------------- + +compatible: Should be "st,stm32-thermal" +reg: This should be the physical base address and length of the + sensor's registers. +clocks: Phandle of the clock used by the thermal sensor. + See: Documentation/devicetree/bindings/clock/clock-bindings.txt +clock-names: Should be "pclk" for register access clock and reference clock. + See: Documentation/devicetree/bindings/resource-names.txt +#thermal-sensor-cells: Should be 0. See ./thermal.txt for a description. +interrupts: Standard way to define interrupt number. + +Example: + + thermal-zones { + cpu_thermal: cpu-thermal { + polling-delay-passive = <0>; + polling-delay = <0>; + + thermal-sensors = <&thermal>; + + trips { + cpu_alert1: cpu-alert1 { + temperature = <85000>; + hysteresis = <0>; + type = "passive"; + }; + + cpu-crit: cpu-crit { + temperature = <120000>; + hysteresis = <0>; + type = "critical"; + }; + }; + + cooling-maps { + }; + }; + }; + + thermal: thermal@50028000 { + compatible = "st,stm32-thermal"; + reg = <0x50028000 0x100>; + clocks = <&rcc TMPSENS>; + clock-names = "pclk"; + #thermal-sensor-cells = <0>; + interrupts = <GIC_SPI 147 IRQ_TYPE_LEVEL_HIGH>; + }; diff --git a/Documentation/devicetree/bindings/thermal/thermal.txt b/Documentation/devicetree/bindings/thermal/thermal.txt index eb7ee91556a5..ca14ba959e0d 100644 --- a/Documentation/devicetree/bindings/thermal/thermal.txt +++ b/Documentation/devicetree/bindings/thermal/thermal.txt @@ -152,7 +152,7 @@ Optional property: Elem size: one cell the sensors listed in the thermal-sensors property. Elem type: signed Coefficients defaults to 1, in case this property is not specified. A simple linear polynomial is used: - Z = c0 * x0 + c1 + x1 + ... + c(n-1) * x(n-1) + cn. + Z = c0 * x0 + c1 * x1 + ... + c(n-1) * x(n-1) + cn. The coefficients are ordered and they match with sensors by means of sensor ID. Additional coefficients are diff --git a/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt b/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt index a092053f7902..a9da22bda912 100644 --- a/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt +++ b/Documentation/devicetree/bindings/timer/amlogic,meson6-timer.txt @@ -4,12 +4,19 @@ Required properties: - compatible : should be "amlogic,meson6-timer" - reg : Specifies base physical address and size of the registers. -- interrupts : The interrupt of the first timer +- interrupts : The four interrupts, one for each timer event +- clocks : phandles to the pclk (system clock) and XTAL clocks +- clock-names : must contain "pclk" and "xtal" Example: timer@c1109940 { compatible = "amlogic,meson6-timer"; reg = <0xc1109940 0x14>; - interrupts = <0 10 1>; + interrupts = <GIC_SPI 10 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 11 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 6 IRQ_TYPE_EDGE_RISING>, + <GIC_SPI 29 IRQ_TYPE_EDGE_RISING>; + clocks = <&xtal>, <&clk81>; + clock-names = "xtal", "pclk"; }; diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer.txt b/Documentation/devicetree/bindings/timer/arm,arch_timer.txt deleted file mode 100644 index 68301b77e854..000000000000 --- a/Documentation/devicetree/bindings/timer/arm,arch_timer.txt +++ /dev/null @@ -1,112 +0,0 @@ -* ARM architected timer - -ARM cores may have a per-core architected timer, which provides per-cpu timers, -or a memory mapped architected timer, which provides up to 8 frames with a -physical and optional virtual timer per frame. - -The per-core architected timer is attached to a GIC to deliver its -per-processor interrupts via PPIs. The memory mapped timer is attached to a GIC -to deliver its interrupts via SPIs. - -** CP15 Timer node properties: - -- compatible : Should at least contain one of - "arm,armv7-timer" - "arm,armv8-timer" - -- interrupts : Interrupt list for secure, non-secure, virtual and - hypervisor timers, in that order. - -- clock-frequency : The frequency of the main counter, in Hz. Should be present - only where necessary to work around broken firmware which does not configure - CNTFRQ on all CPUs to a uniform correct value. Use of this property is - strongly discouraged; fix your firmware unless absolutely impossible. - -- always-on : a boolean property. If present, the timer is powered through an - always-on power domain, therefore it never loses context. - -- fsl,erratum-a008585 : A boolean property. Indicates the presence of - QorIQ erratum A-008585, which says that reading the counter is - unreliable unless the same value is returned by back-to-back reads. - This also affects writes to the tval register, due to the implicit - counter read. - -- hisilicon,erratum-161010101 : A boolean property. Indicates the - presence of Hisilicon erratum 161010101, which says that reading the - counters is unreliable in some cases, and reads may return a value 32 - beyond the correct value. This also affects writes to the tval - registers, due to the implicit counter read. - -** Optional properties: - -- arm,cpu-registers-not-fw-configured : Firmware does not initialize - any of the generic timer CPU registers, which contain their - architecturally-defined reset values. Only supported for 32-bit - systems which follow the ARMv7 architected reset values. - -- arm,no-tick-in-suspend : The main counter does not tick when the system is in - low-power system suspend on some SoCs. This behavior does not match the - Architecture Reference Manual's specification that the system counter "must - be implemented in an always-on power domain." - - -Example: - - timer { - compatible = "arm,cortex-a15-timer", - "arm,armv7-timer"; - interrupts = <1 13 0xf08>, - <1 14 0xf08>, - <1 11 0xf08>, - <1 10 0xf08>; - clock-frequency = <100000000>; - }; - -** Memory mapped timer node properties: - -- compatible : Should at least contain "arm,armv7-timer-mem". - -- clock-frequency : The frequency of the main counter, in Hz. Should be present - only when firmware has not configured the MMIO CNTFRQ registers. - -- reg : The control frame base address. - -Note that #address-cells, #size-cells, and ranges shall be present to ensure -the CPU can address a frame's registers. - -A timer node has up to 8 frame sub-nodes, each with the following properties: - -- frame-number: 0 to 7. - -- interrupts : Interrupt list for physical and virtual timers in that order. - The virtual timer interrupt is optional. - -- reg : The first and second view base addresses in that order. The second view - base address is optional. - -- status : "disabled" indicates the frame is not available for use. Optional. - -Example: - - timer@f0000000 { - compatible = "arm,armv7-timer-mem"; - #address-cells = <1>; - #size-cells = <1>; - ranges; - reg = <0xf0000000 0x1000>; - clock-frequency = <50000000>; - - frame@f0001000 { - frame-number = <0> - interrupts = <0 13 0x8>, - <0 14 0x8>; - reg = <0xf0001000 0x1000>, - <0xf0002000 0x1000>; - }; - - frame@f0003000 { - frame-number = <1> - interrupts = <0 15 0x8>; - reg = <0xf0003000 0x1000>; - }; - }; diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml new file mode 100644 index 000000000000..6deead07728e --- /dev/null +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml @@ -0,0 +1,103 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/arm,arch_timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM architected timer + +maintainers: + - Marc Zyngier <marc.zyngier@arm.com> + - Mark Rutland <mark.rutland@arm.com> +description: |+ + ARM cores may have a per-core architected timer, which provides per-cpu timers, + or a memory mapped architected timer, which provides up to 8 frames with a + physical and optional virtual timer per frame. + + The per-core architected timer is attached to a GIC to deliver its + per-processor interrupts via PPIs. The memory mapped timer is attached to a GIC + to deliver its interrupts via SPIs. + +properties: + compatible: + oneOf: + - items: + - enum: + - arm,cortex-a15-timer + - enum: + - arm,armv7-timer + - items: + - enum: + - arm,armv7-timer + - items: + - enum: + - arm,armv8-timer + + interrupts: + items: + - description: secure timer irq + - description: non-secure timer irq + - description: virtual timer irq + - description: hypervisor timer irq + + clock-frequency: + description: The frequency of the main counter, in Hz. Should be present + only where necessary to work around broken firmware which does not configure + CNTFRQ on all CPUs to a uniform correct value. Use of this property is + strongly discouraged; fix your firmware unless absolutely impossible. + + always-on: + type: boolean + description: If present, the timer is powered through an always-on power + domain, therefore it never loses context. + + fsl,erratum-a008585: + type: boolean + description: Indicates the presence of QorIQ erratum A-008585, which says + that reading the counter is unreliable unless the same value is returned + by back-to-back reads. This also affects writes to the tval register, due + to the implicit counter read. + + hisilicon,erratum-161010101: + type: boolean + description: Indicates the presence of Hisilicon erratum 161010101, which + says that reading the counters is unreliable in some cases, and reads may + return a value 32 beyond the correct value. This also affects writes to + the tval registers, due to the implicit counter read. + + arm,cpu-registers-not-fw-configured: + type: boolean + description: Firmware does not initialize any of the generic timer CPU + registers, which contain their architecturally-defined reset values. Only + supported for 32-bit systems which follow the ARMv7 architected reset + values. + + arm,no-tick-in-suspend: + type: boolean + description: The main counter does not tick when the system is in + low-power system suspend on some SoCs. This behavior does not match the + Architecture Reference Manual's specification that the system counter "must + be implemented in an always-on power domain." + +required: + - compatible + +oneOf: + - required: + - interrupts + - required: + - interrupts-extended + +examples: + - | + timer { + compatible = "arm,cortex-a15-timer", + "arm,armv7-timer"; + interrupts = <1 13 0xf08>, + <1 14 0xf08>, + <1 11 0xf08>, + <1 10 0xf08>; + clock-frequency = <100000000>; + }; + +... diff --git a/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml new file mode 100644 index 000000000000..c4ab59550fc2 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/arm,arch_timer_mmio.yaml @@ -0,0 +1,120 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/arm,arch_timer_mmio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM memory mapped architected timer + +maintainers: + - Marc Zyngier <marc.zyngier@arm.com> + - Mark Rutland <mark.rutland@arm.com> + +description: |+ + ARM cores may have a memory mapped architected timer, which provides up to 8 + frames with a physical and optional virtual timer per frame. + + The memory mapped timer is attached to a GIC to deliver its interrupts via SPIs. + +properties: + compatible: + items: + - enum: + - arm,armv7-timer-mem + + reg: + maxItems: 1 + description: The control frame base address + + '#address-cells': + enum: [1, 2] + + '#size-cells': + const: 1 + + clock-frequency: + description: The frequency of the main counter, in Hz. Should be present + only where necessary to work around broken firmware which does not configure + CNTFRQ on all CPUs to a uniform correct value. Use of this property is + strongly discouraged; fix your firmware unless absolutely impossible. + + always-on: + type: boolean + description: If present, the timer is powered through an always-on power + domain, therefore it never loses context. + + arm,cpu-registers-not-fw-configured: + type: boolean + description: Firmware does not initialize any of the generic timer CPU + registers, which contain their architecturally-defined reset values. Only + supported for 32-bit systems which follow the ARMv7 architected reset + values. + + arm,no-tick-in-suspend: + type: boolean + description: The main counter does not tick when the system is in + low-power system suspend on some SoCs. This behavior does not match the + Architecture Reference Manual's specification that the system counter "must + be implemented in an always-on power domain." + +patternProperties: + '^frame@[0-9a-z]*$': + description: A timer node has up to 8 frame sub-nodes, each with the following properties. + properties: + frame-number: + allOf: + - $ref: "/schemas/types.yaml#/definitions/uint32" + - minimum: 0 + maximum: 7 + + interrupts: + minItems: 1 + maxItems: 2 + items: + - description: physical timer irq + - description: virtual timer irq + + reg : + minItems: 1 + maxItems: 2 + items: + - description: 1st view base address + - description: 2nd optional view base address + + required: + - frame-number + - interrupts + - reg + +required: + - compatible + - reg + - '#address-cells' + - '#size-cells' + +examples: + - | + timer@f0000000 { + compatible = "arm,armv7-timer-mem"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + reg = <0xf0000000 0x1000>; + clock-frequency = <50000000>; + + frame@f0001000 { + frame-number = <0>; + interrupts = <0 13 0x8>, + <0 14 0x8>; + reg = <0xf0001000 0x1000>, + <0xf0002000 0x1000>; + }; + + frame@f0003000 { + frame-number = <1>; + interrupts = <0 15 0x8>; + reg = <0xf0003000 0x1000>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/timer/arm,global_timer.txt b/Documentation/devicetree/bindings/timer/arm,global_timer.txt deleted file mode 100644 index bdae3a818793..000000000000 --- a/Documentation/devicetree/bindings/timer/arm,global_timer.txt +++ /dev/null @@ -1,27 +0,0 @@ - -* ARM Global Timer - Cortex-A9 are often associated with a per-core Global timer. - -** Timer node required properties: - -- compatible : should contain - * "arm,cortex-a5-global-timer" for Cortex-A5 global timers. - * "arm,cortex-a9-global-timer" for Cortex-A9 global - timers or any compatible implementation. Note: driver - supports versions r2p0 and above. - -- interrupts : One interrupt to each core - -- reg : Specify the base address and the size of the GT timer - register window. - -- clocks : Should be phandle to a clock. - -Example: - - timer@2c000600 { - compatible = "arm,cortex-a9-global-timer"; - reg = <0x2c000600 0x20>; - interrupts = <1 13 0xf01>; - clocks = <&arm_periph_clk>; - }; diff --git a/Documentation/devicetree/bindings/timer/arm,global_timer.yaml b/Documentation/devicetree/bindings/timer/arm,global_timer.yaml new file mode 100644 index 000000000000..21c24a8e28fd --- /dev/null +++ b/Documentation/devicetree/bindings/timer/arm,global_timer.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/timer/arm,global_timer.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ARM Global Timer + +maintainers: + - Stuart Menefy <stuart.menefy@st.com> + +description: + Cortex-A9 are often associated with a per-core Global timer. + +properties: + compatible: + items: + - enum: + - arm,cortex-a5-global-timer + - arm,cortex-a9-global-timer + + description: driver supports versions r2p0 and above. + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - clocks + +examples: + - | + timer@2c000600 { + compatible = "arm,cortex-a9-global-timer"; + reg = <0x2c000600 0x20>; + interrupts = <1 13 0xf01>; + clocks = <&arm_periph_clk>; + }; +... diff --git a/Documentation/devicetree/bindings/timer/csky,gx6605s-timer.txt b/Documentation/devicetree/bindings/timer/csky,gx6605s-timer.txt new file mode 100644 index 000000000000..6b04344f4bea --- /dev/null +++ b/Documentation/devicetree/bindings/timer/csky,gx6605s-timer.txt @@ -0,0 +1,42 @@ +================= +gx6605s SOC Timer +================= + +The timer is used in gx6605s soc as system timer and the driver +contain clk event and clk source. + +============================== +timer node bindings definition +============================== + + Description: Describes gx6605s SOC timer + + PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: must be "csky,gx6605s-timer" + - reg + Usage: required + Value type: <u32 u32> + Definition: <phyaddr size> in soc from cpu view + - clocks + Usage: required + Value type: phandle + clock specifier cells + Definition: must be input clk node + - interrupt + Usage: required + Value type: <u32> + Definition: must be timer irq num defined by soc + +Examples: +--------- + + timer0: timer@20a000 { + compatible = "csky,gx6605s-timer"; + reg = <0x0020a000 0x400>; + clocks = <&dummy_apb_clk>; + interrupts = <10>; + interrupt-parent = <&intc>; + }; diff --git a/Documentation/devicetree/bindings/timer/csky,mptimer.txt b/Documentation/devicetree/bindings/timer/csky,mptimer.txt new file mode 100644 index 000000000000..15cfec08fbb8 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/csky,mptimer.txt @@ -0,0 +1,42 @@ +============================ +C-SKY Multi-processors Timer +============================ + +C-SKY multi-processors timer is designed for C-SKY SMP system and the +regs is accessed by cpu co-processor 4 registers with mtcr/mfcr. + + - PTIM_CTLR "cr<0, 14>" Control reg to start reset timer. + - PTIM_TSR "cr<1, 14>" Interrupt cleanup status reg. + - PTIM_CCVR "cr<3, 14>" Current counter value reg. + - PTIM_LVR "cr<6, 14>" Window value reg to triger next event. + +============================== +timer node bindings definition +============================== + + Description: Describes SMP timer + + PROPERTIES + + - compatible + Usage: required + Value type: <string> + Definition: must be "csky,mptimer" + - clocks + Usage: required + Value type: <node> + Definition: must be input clk node + - interrupts + Usage: required + Value type: <u32> + Definition: must be timer irq num defined by soc + +Examples: +--------- + + timer: timer { + compatible = "csky,mptimer"; + clocks = <&dummy_apb_clk>; + interrupts = <16>; + interrupt-parent = <&intc>; + }; diff --git a/Documentation/devicetree/bindings/timer/fsl,imxgpt.txt b/Documentation/devicetree/bindings/timer/fsl,imxgpt.txt index 9809b11f7180..5d8fd5b52598 100644 --- a/Documentation/devicetree/bindings/timer/fsl,imxgpt.txt +++ b/Documentation/devicetree/bindings/timer/fsl,imxgpt.txt @@ -2,17 +2,44 @@ Freescale i.MX General Purpose Timer (GPT) Required properties: -- compatible : should be "fsl,<soc>-gpt" -- reg : Specifies base physical address and size of the registers. -- interrupts : A list of 4 interrupts; one per timer channel. -- clocks : The clocks provided by the SoC to drive the timer. +- compatible : should be one of following: + for i.MX1: + - "fsl,imx1-gpt"; + for i.MX21: + - "fsl,imx21-gpt"; + for i.MX27: + - "fsl,imx27-gpt", "fsl,imx21-gpt"; + for i.MX31: + - "fsl,imx31-gpt"; + for i.MX25: + - "fsl,imx25-gpt", "fsl,imx31-gpt"; + for i.MX50: + - "fsl,imx50-gpt", "fsl,imx31-gpt"; + for i.MX51: + - "fsl,imx51-gpt", "fsl,imx31-gpt"; + for i.MX53: + - "fsl,imx53-gpt", "fsl,imx31-gpt"; + for i.MX6Q: + - "fsl,imx6q-gpt", "fsl,imx31-gpt"; + for i.MX6DL: + - "fsl,imx6dl-gpt"; + for i.MX6SL: + - "fsl,imx6sl-gpt", "fsl,imx6dl-gpt"; + for i.MX6SX: + - "fsl,imx6sx-gpt", "fsl,imx6dl-gpt"; +- reg : specifies base physical address and size of the registers. +- interrupts : should be the gpt interrupt. +- clocks : the clocks provided by the SoC to drive the timer, must contain + an entry for each entry in clock-names. +- clock-names : must include "ipg" entry first, then "per" entry. Example: gpt1: timer@10003000 { - compatible = "fsl,imx27-gpt", "fsl,imx1-gpt"; + compatible = "fsl,imx27-gpt", "fsl,imx21-gpt"; reg = <0x10003000 0x1000>; interrupts = <26>; - clocks = <&clks 46>, <&clks 61>; + clocks = <&clks IMX27_CLK_GPT1_IPG_GATE>, + <&clks IMX27_CLK_PER1_GATE>; clock-names = "ipg", "per"; }; diff --git a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt index 18d4d0166c76..ff7c567a7972 100644 --- a/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt +++ b/Documentation/devicetree/bindings/timer/mediatek,mtk-timer.txt @@ -1,7 +1,7 @@ -Mediatek Timers +MediaTek Timers --------------- -Mediatek SoCs have two different timers on different platforms, +MediaTek SoCs have two different timers on different platforms, - GPT (General Purpose Timer) - SYST (System Timer) @@ -9,6 +9,7 @@ The proper timer will be selected automatically by driver. Required properties: - compatible should contain: + For those SoCs that use GPT * "mediatek,mt2701-timer" for MT2701 compatible timers (GPT) * "mediatek,mt6580-timer" for MT6580 compatible timers (GPT) * "mediatek,mt6589-timer" for MT6589 compatible timers (GPT) @@ -17,7 +18,11 @@ Required properties: * "mediatek,mt8135-timer" for MT8135 compatible timers (GPT) * "mediatek,mt8173-timer" for MT8173 compatible timers (GPT) * "mediatek,mt6577-timer" for MT6577 and all above compatible timers (GPT) - * "mediatek,mt6765-timer" for MT6765 compatible timers (SYST) + + For those SoCs that use SYST + * "mediatek,mt7629-timer" for MT7629 compatible timers (SYST) + * "mediatek,mt6765-timer" for MT6765 and all above compatible timers (SYST) + - reg: Should contain location and length for timer register. - clocks: Should contain system clock. diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt index 9a6e251462e7..b8f02c663521 100644 --- a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt +++ b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.txt @@ -5,9 +5,13 @@ Required properties: - reg : Address and length of the register set of timer controller. - interrupts : Should be the interrupt number. +Optional properties: +- clocks : Should contain a single entry describing the clock input. + Example: timer0: timer@d4014000 { compatible = "mrvl,mmp-timer"; reg = <0xd4014000 0x100>; interrupts = <13>; + clocks = <&coreclk 2>; }; diff --git a/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt b/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt new file mode 100644 index 000000000000..032cda96fe0d --- /dev/null +++ b/Documentation/devicetree/bindings/timer/nvidia,tegra210-timer.txt @@ -0,0 +1,36 @@ +NVIDIA Tegra210 timer + +The Tegra210 timer provides fourteen 29-bit timer counters and one 32-bit +timestamp counter. The TMRs run at either a fixed 1 MHz clock rate derived +from the oscillator clock (TMR0-TMR9) or directly at the oscillator clock +(TMR10-TMR13). Each TMR can be programmed to generate one-shot, periodic, +or watchdog interrupts. + +Required properties: +- compatible : "nvidia,tegra210-timer". +- reg : Specifies base physical address and size of the registers. +- interrupts : A list of 14 interrupts; one per each timer channels 0 through + 13. +- clocks : Must contain one entry, for the module clock. + See ../clocks/clock-bindings.txt for details. + +timer@60005000 { + compatible = "nvidia,tegra210-timer"; + reg = <0x0 0x60005000 0x0 0x400>; + interrupts = <GIC_SPI 156 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 0 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 1 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 121 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 152 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 153 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 154 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 155 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 176 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 177 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 178 IRQ_TYPE_LEVEL_HIGH>, + <GIC_SPI 179 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&tegra_car TEGRA210_CLK_TIMER>; + clock-names = "timer"; +}; diff --git a/Documentation/devicetree/bindings/timer/rda,8810pl-timer.txt b/Documentation/devicetree/bindings/timer/rda,8810pl-timer.txt new file mode 100644 index 000000000000..4db542c9a0fd --- /dev/null +++ b/Documentation/devicetree/bindings/timer/rda,8810pl-timer.txt @@ -0,0 +1,20 @@ +RDA Micro RDA8810PL Timer + +Required properties: +- compatible : "rda,8810pl-timer" +- reg : Offset and length of the register set for the device. +- interrupts : Should contain two interrupts. +- interrupt-names : Should be "hwtimer", "ostimer". + +Example: + + apb@20900000 { + compatible = "simple-bus"; + ... + timer@10000 { + compatible = "rda,8810pl-timer"; + reg = <0x10000 0x1000>; + interrupts = <16 IRQ_TYPE_LEVEL_HIGH>, + <17 IRQ_TYPE_LEVEL_HIGH>; + interrupt-names = "hwtimer", "ostimer"; + }; diff --git a/Documentation/devicetree/bindings/timer/renesas,cmt.txt b/Documentation/devicetree/bindings/timer/renesas,cmt.txt index 49948fcc0631..c0594450e9ef 100644 --- a/Documentation/devicetree/bindings/timer/renesas,cmt.txt +++ b/Documentation/devicetree/bindings/timer/renesas,cmt.txt @@ -24,8 +24,16 @@ Required Properties: - "renesas,r8a73a4-cmt1" for the 48-bit CMT1 device included in r8a73a4. - "renesas,r8a7743-cmt0" for the 32-bit CMT0 device included in r8a7743. - "renesas,r8a7743-cmt1" for the 48-bit CMT1 device included in r8a7743. + - "renesas,r8a7744-cmt0" for the 32-bit CMT0 device included in r8a7744. + - "renesas,r8a7744-cmt1" for the 48-bit CMT1 device included in r8a7744. - "renesas,r8a7745-cmt0" for the 32-bit CMT0 device included in r8a7745. - "renesas,r8a7745-cmt1" for the 48-bit CMT1 device included in r8a7745. + - "renesas,r8a77470-cmt0" for the 32-bit CMT0 device included in r8a77470. + - "renesas,r8a77470-cmt1" for the 48-bit CMT1 device included in r8a77470. + - "renesas,r8a774a1-cmt0" for the 32-bit CMT0 device included in r8a774a1. + - "renesas,r8a774a1-cmt1" for the 48-bit CMT1 device included in r8a774a1. + - "renesas,r8a774c0-cmt0" for the 32-bit CMT0 device included in r8a774c0. + - "renesas,r8a774c0-cmt1" for the 48-bit CMT1 device included in r8a774c0. - "renesas,r8a7790-cmt0" for the 32-bit CMT0 device included in r8a7790. - "renesas,r8a7790-cmt1" for the 48-bit CMT1 device included in r8a7790. - "renesas,r8a7791-cmt0" for the 32-bit CMT0 device included in r8a7791. @@ -34,6 +42,8 @@ Required Properties: - "renesas,r8a7793-cmt1" for the 48-bit CMT1 device included in r8a7793. - "renesas,r8a7794-cmt0" for the 32-bit CMT0 device included in r8a7794. - "renesas,r8a7794-cmt1" for the 48-bit CMT1 device included in r8a7794. + - "renesas,r8a7796-cmt0" for the 32-bit CMT0 device included in r8a7796. + - "renesas,r8a7796-cmt1" for the 48-bit CMT1 device included in r8a7796. - "renesas,r8a77970-cmt0" for the 32-bit CMT0 device included in r8a77970. - "renesas,r8a77970-cmt1" for the 48-bit CMT1 device included in r8a77970. - "renesas,r8a77980-cmt0" for the 32-bit CMT0 device included in r8a77980. @@ -45,9 +55,12 @@ Required Properties: and RZ/G1. These are fallbacks for r8a73a4, R-Car Gen2 and RZ/G1 entries listed above. - - "renesas,rcar-gen3-cmt0" for 32-bit CMT0 devices included in R-Car Gen3. - - "renesas,rcar-gen3-cmt1" for 48-bit CMT1 devices included in R-Car Gen3. - These are fallbacks for R-Car Gen3 entries listed above. + - "renesas,rcar-gen3-cmt0" for 32-bit CMT0 devices included in R-Car Gen3 + and RZ/G2. + - "renesas,rcar-gen3-cmt1" for 48-bit CMT1 devices included in R-Car Gen3 + and RZ/G2. + These are fallbacks for R-Car Gen3 and RZ/G2 entries listed + above. - reg: base address and length of the registers block for the timer module. - interrupts: interrupt-specifier for the timer, one per channel. diff --git a/Documentation/devicetree/bindings/timer/renesas,ostm.txt b/Documentation/devicetree/bindings/timer/renesas,ostm.txt index be3ae0fdf775..81a78f8bcf17 100644 --- a/Documentation/devicetree/bindings/timer/renesas,ostm.txt +++ b/Documentation/devicetree/bindings/timer/renesas,ostm.txt @@ -9,7 +9,8 @@ Channels are independent from each other. Required Properties: - compatible: must be one or more of the following: - - "renesas,r7s72100-ostm" for the r7s72100 OSTM + - "renesas,r7s72100-ostm" for the R7S72100 (RZ/A1) OSTM + - "renesas,r7s9210-ostm" for the R7S9210 (RZ/A2) OSTM - "renesas,ostm" for any OSTM This is a fallback for the above renesas,*-ostm entries diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.txt b/Documentation/devicetree/bindings/timer/renesas,tmu.txt index cd5f20bf2582..13ad07416bdd 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.txt +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.txt @@ -10,8 +10,11 @@ Required Properties: - compatible: must contain one or more of the following: - "renesas,tmu-r8a7740" for the r8a7740 TMU + - "renesas,tmu-r8a774c0" for the r8a774C0 TMU - "renesas,tmu-r8a7778" for the r8a7778 TMU - "renesas,tmu-r8a7779" for the r8a7779 TMU + - "renesas,tmu-r8a77970" for the r8a77970 TMU + - "renesas,tmu-r8a77980" for the r8a77980 TMU - "renesas,tmu" for any TMU. This is a fallback for the above renesas,tmu-* entries diff --git a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt index 16a5f4577a61..d65fdce7c7f0 100644 --- a/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt +++ b/Documentation/devicetree/bindings/timer/rockchip,rk-timer.txt @@ -2,6 +2,7 @@ Rockchip rk timer Required properties: - compatible: should be: + "rockchip,rv1108-timer", "rockchip,rk3288-timer": for Rockchip RV1108 "rockchip,rk3036-timer", "rockchip,rk3288-timer": for Rockchip RK3036 "rockchip,rk3066-timer", "rockchip,rk3288-timer": for Rockchip RK3066 "rockchip,rk3188-timer", "rockchip,rk3288-timer": for Rockchip RK3188 diff --git a/Documentation/devicetree/bindings/timer/socionext,milbeaut-timer.txt b/Documentation/devicetree/bindings/timer/socionext,milbeaut-timer.txt new file mode 100644 index 000000000000..ac44c4b67530 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/socionext,milbeaut-timer.txt @@ -0,0 +1,17 @@ +Milbeaut SoCs Timer Controller + +Required properties: + +- compatible : should be "socionext,milbeaut-timer". +- reg : Specifies base physical address and size of the registers. +- interrupts : The interrupt of the first timer. +- clocks: phandle to the input clk. + +Example: + +timer { + compatible = "socionext,milbeaut-timer"; + reg = <0x1e000050 0x20> + interrupts = <0 91 4>; + clocks = <&clk 4>; +}; diff --git a/Documentation/devicetree/bindings/trivial-devices.txt b/Documentation/devicetree/bindings/trivial-devices.txt deleted file mode 100644 index 69c934aec13b..000000000000 --- a/Documentation/devicetree/bindings/trivial-devices.txt +++ /dev/null @@ -1,200 +0,0 @@ -This is a list of trivial i2c devices that have simple device tree -bindings, consisting only of a compatible field, an address and -possibly an interrupt line. - -If a device needs more specific bindings, such as properties to -describe some aspect of it, there needs to be a specific binding -document for it just like any other devices. - - -Compatible Vendor / Chip -========== ============= -abracon,abb5zes3 AB-RTCMC-32.768kHz-B5ZE-S3: Real Time Clock/Calendar Module with I2C Interface -ad,ad7414 SMBus/I2C Digital Temperature Sensor in 6-Pin SOT with SMBus Alert and Over Temperature Pin -ad,adm9240 ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems -adi,adt7461 +/-1C TDM Extended Temp Range I.C -adt7461 +/-1C TDM Extended Temp Range I.C -adi,adt7473 +/-1C TDM Extended Temp Range I.C -adi,adt7475 +/-1C TDM Extended Temp Range I.C -adi,adt7476 +/-1C TDM Extended Temp Range I.C -adi,adt7490 +/-1C TDM Extended Temp Range I.C -adi,adxl345 Three-Axis Digital Accelerometer -adi,adxl346 Three-Axis Digital Accelerometer (backward-compatibility value "adi,adxl345" must be listed too) -ams,iaq-core AMS iAQ-Core VOC Sensor -amstaos,tsl2571 AMS/TAOS ALS and proximity sensor -amstaos,tsl2671 AMS/TAOS ALS and proximity sensor -amstaos,tmd2671 AMS/TAOS ALS and proximity sensor -amstaos,tsl2771 AMS/TAOS ALS and proximity sensor -amstaos,tmd2771 AMS/TAOS ALS and proximity sensor -amstaos,tsl2572 AMS/TAOS ALS and proximity sensor -amstaos,tsl2672 AMS/TAOS ALS and proximity sensor -amstaos,tmd2672 AMS/TAOS ALS and proximity sensor -amstaos,tsl2772 AMS/TAOS ALS and proximity sensor -amstaos,tmd2772 AMS/TAOS ALS and proximity sensor -at,24c08 i2c serial eeprom (24cxx) -atmel,at97sc3204t i2c trusted platform module (TPM) -capella,cm32181 CM32181: Ambient Light Sensor -capella,cm3232 CM3232: Ambient Light Sensor -dallas,ds1374 I2C, 32-Bit Binary Counter Watchdog RTC with Trickle Charger and Reset Input/Output -dallas,ds1631 High-Precision Digital Thermometer -dallas,ds1672 Dallas DS1672 Real-time Clock -dallas,ds1682 Total-Elapsed-Time Recorder with Alarm -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,srf02 Devantech SRF02 ultrasonic ranger in I2C mode -devantech,srf08 Devantech SRF08 ultrasonic ranger -devantech,srf10 Devantech SRF10 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 -domintech,dmard10 DMARD10: 3-axis Accelerometer -epson,rx8010 I2C-BUS INTERFACE REAL TIME CLOCK MODULE -epson,rx8581 I2C-BUS INTERFACE REAL TIME CLOCK MODULE -emmicro,em3027 EM Microelectronic EM3027 Real-time Clock -fsl,mag3110 MAG3110: Xtrinsic High Accuracy, 3D Magnetometer -fsl,mma7660 MMA7660FC: 3-Axis Orientation/Motion Detection Sensor -fsl,mma8450 MMA8450Q: Xtrinsic Low-power, 3-axis Xtrinsic Accelerometer -fsl,mpl3115 MPL3115: Absolute Digital Pressure Sensor -fsl,mpr121 MPR121: Proximity Capacitive Touch Sensor Controller -fsl,sgtl5000 SGTL5000: Ultra Low-Power Audio Codec -gmt,g751 G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface -infineon,slb9635tt Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) -infineon,slb9645tt Infineon SLB9645 I2C TPM (new protocol, max 400khz) -infineon,tlv493d-a1b6 Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor -isil,isl1208 Intersil ISL1208 Low Power RTC with Battery Backed SRAM -isil,isl1218 Intersil ISL1218 Low Power RTC with Battery Backed SRAM -isil,isl12022 Intersil ISL12022 Real-time Clock -isil,isl29028 Intersil ISL29028 Ambient Light and Proximity Sensor -isil,isl29030 Intersil ISL29030 Ambient Light and Proximity Sensor -maxim,ds1050 5 Bit Programmable, Pulse-Width Modulator -maxim,max1237 Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs -maxim,max6621 PECI-to-I2C translator for PECI-to-SMBus/I2C protocol conversion -maxim,max6625 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface -mcube,mc3230 mCube 3-axis 8-bit digital accelerometer -memsic,mxc6225 MEMSIC 2-axis 8-bit digital accelerometer -microchip,mcp4017-502 Microchip 7-bit Single I2C Digital POT (5k) -microchip,mcp4017-103 Microchip 7-bit Single I2C Digital POT (10k) -microchip,mcp4017-503 Microchip 7-bit Single I2C Digital POT (50k) -microchip,mcp4017-104 Microchip 7-bit Single I2C Digital POT (100k) -microchip,mcp4018-502 Microchip 7-bit Single I2C Digital POT (5k) -microchip,mcp4018-103 Microchip 7-bit Single I2C Digital POT (10k) -microchip,mcp4018-503 Microchip 7-bit Single I2C Digital POT (50k) -microchip,mcp4018-104 Microchip 7-bit Single I2C Digital POT (100k) -microchip,mcp4019-502 Microchip 7-bit Single I2C Digital POT (5k) -microchip,mcp4019-103 Microchip 7-bit Single I2C Digital POT (10k) -microchip,mcp4019-503 Microchip 7-bit Single I2C Digital POT (50k) -microchip,mcp4019-104 Microchip 7-bit Single I2C Digital POT (100k) -microchip,mcp4531-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) -microchip,mcp4531-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) -microchip,mcp4531-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) -microchip,mcp4531-104 Microchip 7-bit Single I2C Digital Potentiometer (100k) -microchip,mcp4532-502 Microchip 7-bit Single I2C Digital Potentiometer (5k) -microchip,mcp4532-103 Microchip 7-bit Single I2C Digital Potentiometer (10k) -microchip,mcp4532-503 Microchip 7-bit Single I2C Digital Potentiometer (50k) -microchip,mcp4532-104 Microchip 7-bit Single I2C Digital Potentiometer (100k) -microchip,mcp4541-502 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4541-103 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4541-503 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4541-104 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4542-502 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4542-103 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4542-503 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4542-104 Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4551-502 Microchip 8-bit Single I2C Digital Potentiometer (5k) -microchip,mcp4551-103 Microchip 8-bit Single I2C Digital Potentiometer (10k) -microchip,mcp4551-503 Microchip 8-bit Single I2C Digital Potentiometer (50k) -microchip,mcp4551-104 Microchip 8-bit Single I2C Digital Potentiometer (100k) -microchip,mcp4552-502 Microchip 8-bit Single I2C Digital Potentiometer (5k) -microchip,mcp4552-103 Microchip 8-bit Single I2C Digital Potentiometer (10k) -microchip,mcp4552-503 Microchip 8-bit Single I2C Digital Potentiometer (50k) -microchip,mcp4552-104 Microchip 8-bit Single I2C Digital Potentiometer (100k) -microchip,mcp4561-502 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4561-103 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4561-503 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4561-104 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4562-502 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4562-103 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4562-503 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4562-104 Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4631-502 Microchip 7-bit Dual I2C Digital Potentiometer (5k) -microchip,mcp4631-103 Microchip 7-bit Dual I2C Digital Potentiometer (10k) -microchip,mcp4631-503 Microchip 7-bit Dual I2C Digital Potentiometer (50k) -microchip,mcp4631-104 Microchip 7-bit Dual I2C Digital Potentiometer (100k) -microchip,mcp4632-502 Microchip 7-bit Dual I2C Digital Potentiometer (5k) -microchip,mcp4632-103 Microchip 7-bit Dual I2C Digital Potentiometer (10k) -microchip,mcp4632-503 Microchip 7-bit Dual I2C Digital Potentiometer (50k) -microchip,mcp4632-104 Microchip 7-bit Dual I2C Digital Potentiometer (100k) -microchip,mcp4641-502 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4641-103 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4641-503 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4641-104 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4642-502 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4642-103 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4642-503 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4642-104 Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4651-502 Microchip 8-bit Dual I2C Digital Potentiometer (5k) -microchip,mcp4651-103 Microchip 8-bit Dual I2C Digital Potentiometer (10k) -microchip,mcp4651-503 Microchip 8-bit Dual I2C Digital Potentiometer (50k) -microchip,mcp4651-104 Microchip 8-bit Dual I2C Digital Potentiometer (100k) -microchip,mcp4652-502 Microchip 8-bit Dual I2C Digital Potentiometer (5k) -microchip,mcp4652-103 Microchip 8-bit Dual I2C Digital Potentiometer (10k) -microchip,mcp4652-503 Microchip 8-bit Dual I2C Digital Potentiometer (50k) -microchip,mcp4652-104 Microchip 8-bit Dual I2C Digital Potentiometer (100k) -microchip,mcp4661-502 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4661-103 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4661-503 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4661-104 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) -microchip,mcp4662-502 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) -microchip,mcp4662-103 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) -microchip,mcp4662-503 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) -microchip,mcp4662-104 Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) -microchip,tc654 PWM Fan Speed Controller With Fan Fault Detection -microchip,tc655 PWM Fan Speed Controller With Fan Fault Detection -microcrystal,rv3029 Real Time Clock Module with I2C-Bus -miramems,da226 MiraMEMS DA226 2-axis 14-bit digital accelerometer -miramems,da280 MiraMEMS DA280 3-axis 14-bit digital accelerometer -miramems,da311 MiraMEMS DA311 3-axis 12-bit digital accelerometer -national,lm63 Temperature sensor with integrated fan control -national,lm75 I2C TEMP SENSOR -national,lm80 Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor -national,lm85 Temperature sensor with integrated fan control -national,lm92 ±0.33°C Accurate, 12-Bit + Sign Temperature Sensor and Thermal Window Comparator with Two-Wire Interface -nuvoton,npct501 i2c trusted platform module (TPM) -nuvoton,npct601 i2c trusted platform module (TPM2) -nuvoton,w83773g Nuvoton Temperature Sensor -nxp,pca9556 Octal SMBus and I2C registered interface -nxp,pca9557 8-bit I2C-bus and SMBus I/O port with reset -nxp,pcf2127 Real-time clock -nxp,pcf2129 Real-time clock -nxp,pcf8523 Real-time Clock -nxp,pcf8563 Real-time clock/calendar -nxp,pcf85063 Tiny Real-Time Clock -oki,ml86v7667 OKI ML86V7667 video decoder -ovti,ov5642 OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI and Embedded TrueFocus -pericom,pt7c4338 Real-time Clock Module -plx,pex8648 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch -pulsedlight,lidar-lite-v2 Pulsedlight LIDAR range-finding sensor -ricoh,r2025sd I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -ricoh,r2221tl I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -ricoh,rs5c372a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -ricoh,rs5c372b I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -ricoh,rv5c386 I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -ricoh,rv5c387a I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC -samsung,24ad0xd1 S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) -sgx,vz89x SGX Sensortech VZ89X Sensors -sii,s35390a 2-wire CMOS real-time clock -silabs,si7020 Relative Humidity and Temperature Sensors -skyworks,sky81452 Skyworks SKY81452: Six-Channel White LED Driver with Touch Panel Bias Supply -st,24c256 i2c serial eeprom (24cxx) -taos,tsl2550 Ambient Light Sensor with SMBUS/Two Wire Serial Interface -ti,ads7828 8-Channels, 12-bit ADC -ti,ads7830 8-Channels, 8-bit ADC -ti,amc6821 Temperature Monitoring and Fan Control -ti,tsc2003 I2C Touch-Screen Controller -ti,tmp102 Low Power Digital Temperature Sensor with SMBUS/Two Wire Serial Interface -ti,tmp103 Low Power Digital Temperature Sensor with SMBUS/Two Wire Serial Interface -ti,tmp275 Digital Temperature Sensor -winbond,w83793 Winbond/Nuvoton H/W Monitor -winbond,wpct301 i2c trusted platform module (TPM) diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml new file mode 100644 index 000000000000..d79fb22bde39 --- /dev/null +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -0,0 +1,344 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/trivial-devices.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Trivial I2C and SPI devices that have simple device tree bindings + +maintainers: + - Rob Herring <robh@kernel.org> + +description: | + This is a list of trivial I2C and SPI devices that have simple device tree + bindings, consisting only of a compatible field, an address and possibly an + interrupt line. + + If a device needs more specific bindings, such as properties to + describe some aspect of it, there needs to be a specific binding + document for it just like any other devices. + +properties: + reg: + maxItems: 1 + interrupts: + maxItems: 1 + compatible: + items: + - enum: + # SMBus/I2C Digital Temperature Sensor in 6-Pin SOT with SMBus Alert and Over Temperature Pin + - ad,ad7414 + # ADM9240: Complete System Hardware Monitor for uProcessor-Based Systems + - ad,adm9240 + # +/-1C TDM Extended Temp Range I.C + - adi,adt7461 + # +/-1C TDM Extended Temp Range I.C + - adt7461 + # +/-1C TDM Extended Temp Range I.C + - adi,adt7473 + # +/-1C TDM Extended Temp Range I.C + - adi,adt7475 + # +/-1C TDM Extended Temp Range I.C + - adi,adt7476 + # +/-1C TDM Extended Temp Range I.C + - adi,adt7490 + # Three-Axis Digital Accelerometer + - adi,adxl345 + # Three-Axis Digital Accelerometer (backward-compatibility value "adi,adxl345" must be listed too) + - adi,adxl346 + # AMS iAQ-Core VOC Sensor + - ams,iaq-core + # i2c serial eeprom (24cxx) + - at,24c08 + # i2c trusted platform module (TPM) + - atmel,at97sc3204t + # CM32181: Ambient Light Sensor + - capella,cm32181 + # CM3232: Ambient Light Sensor + - capella,cm3232 + # High-Precision Digital Thermometer + - dallas,ds1631 + # Total-Elapsed-Time Recorder with Alarm + - dallas,ds1682 + # Tiny Digital Thermometer and Thermostat + - dallas,ds1775 + # CPU Supervisor with Nonvolatile Memory and Programmable I/O + - dallas,ds4510 + # Digital Thermometer and Thermostat + - dallas,ds75 + # Devantech SRF02 ultrasonic ranger in I2C mode + - devantech,srf02 + # Devantech SRF08 ultrasonic ranger + - devantech,srf08 + # Devantech SRF10 ultrasonic ranger + - devantech,srf10 + # DA9053: flexible system level PMIC with multicore support + - dlg,da9053 + # DA9063: system PMIC for quad-core application processors + - dlg,da9063 + # DMARD09: 3-axis Accelerometer + - domintech,dmard09 + # DMARD10: 3-axis Accelerometer + - domintech,dmard10 + # MMA7660FC: 3-Axis Orientation/Motion Detection Sensor + - fsl,mma7660 + # MMA8450Q: Xtrinsic Low-power, 3-axis Xtrinsic Accelerometer + - fsl,mma8450 + # MPL3115: Absolute Digital Pressure Sensor + - fsl,mpl3115 + # MPR121: Proximity Capacitive Touch Sensor Controller + - fsl,mpr121 + # SGTL5000: Ultra Low-Power Audio Codec + - fsl,sgtl5000 + # G751: Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface + - gmt,g751 + # Infineon SLB9635 (Soft-) I2C TPM (old protocol, max 100khz) + - infineon,slb9635tt + # Infineon SLB9645 I2C TPM (new protocol, max 400khz) + - infineon,slb9645tt + # Infineon TLV493D-A1B6 I2C 3D Magnetic Sensor + - infineon,tlv493d-a1b6 + # Intersil ISL29028 Ambient Light and Proximity Sensor + - isil,isl29028 + # Intersil ISL29030 Ambient Light and Proximity Sensor + - isil,isl29030 + # 5 Bit Programmable, Pulse-Width Modulator + - maxim,ds1050 + # Low-Power, 4-/12-Channel, 2-Wire Serial, 12-Bit ADCs + - maxim,max1237 + # PECI-to-I2C translator for PECI-to-SMBus/I2C protocol conversion + - maxim,max6621 + # 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface + - maxim,max6625 + # mCube 3-axis 8-bit digital accelerometer + - mcube,mc3230 + # MEMSIC 2-axis 8-bit digital accelerometer + - memsic,mxc6225 + # Microchip 7-bit Single I2C Digital POT (5k) + - microchip,mcp4017-502 + # Microchip 7-bit Single I2C Digital POT (10k) + - microchip,mcp4017-103 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4017-503 + # Microchip 7-bit Single I2C Digital POT (100k) + - microchip,mcp4017-104 + # Microchip 7-bit Single I2C Digital POT (5k) + - microchip,mcp4018-502 + # Microchip 7-bit Single I2C Digital POT (10k) + - microchip,mcp4018-103 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4018-503 + # Microchip 7-bit Single I2C Digital POT (100k) + - microchip,mcp4018-104 + # Microchip 7-bit Single I2C Digital POT (5k) + - microchip,mcp4019-502 + # Microchip 7-bit Single I2C Digital POT (10k) + - microchip,mcp4019-103 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4019-503 + # Microchip 7-bit Single I2C Digital POT (100k) + - microchip,mcp4019-104 + # Microchip 7-bit Single I2C Digital Potentiometer (5k) + - microchip,mcp4531-502 + # Microchip 7-bit Single I2C Digital Potentiometer (10k) + - microchip,mcp4531-103 + # Microchip 7-bit Single I2C Digital Potentiometer (50k) + - microchip,mcp4531-503 + # Microchip 7-bit Single I2C Digital Potentiometer (100k) + - microchip,mcp4531-104 + # Microchip 7-bit Single I2C Digital Potentiometer (5k) + - microchip,mcp4532-502 + # Microchip 7-bit Single I2C Digital Potentiometer (10k) + - microchip,mcp4532-103 + # Microchip 7-bit Single I2C Digital Potentiometer (50k) + - microchip,mcp4532-503 + # Microchip 7-bit Single I2C Digital Potentiometer (100k) + - microchip,mcp4532-104 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4541-502 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4541-103 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4541-503 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4541-104 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4542-502 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4542-103 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4542-503 + # Microchip 7-bit Single I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4542-104 + # Microchip 8-bit Single I2C Digital Potentiometer (5k) + - microchip,mcp4551-502 + # Microchip 8-bit Single I2C Digital Potentiometer (10k) + - microchip,mcp4551-103 + # Microchip 8-bit Single I2C Digital Potentiometer (50k) + - microchip,mcp4551-503 + # Microchip 8-bit Single I2C Digital Potentiometer (100k) + - microchip,mcp4551-104 + # Microchip 8-bit Single I2C Digital Potentiometer (5k) + - microchip,mcp4552-502 + # Microchip 8-bit Single I2C Digital Potentiometer (10k) + - microchip,mcp4552-103 + # Microchip 8-bit Single I2C Digital Potentiometer (50k) + - microchip,mcp4552-503 + # Microchip 8-bit Single I2C Digital Potentiometer (100k) + - microchip,mcp4552-104 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4561-502 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4561-103 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4561-503 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4561-104 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4562-502 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4562-103 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4562-503 + # Microchip 8-bit Single I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4562-104 + # Microchip 7-bit Dual I2C Digital Potentiometer (5k) + - microchip,mcp4631-502 + # Microchip 7-bit Dual I2C Digital Potentiometer (10k) + - microchip,mcp4631-103 + # Microchip 7-bit Dual I2C Digital Potentiometer (50k) + - microchip,mcp4631-503 + # Microchip 7-bit Dual I2C Digital Potentiometer (100k) + - microchip,mcp4631-104 + # Microchip 7-bit Dual I2C Digital Potentiometer (5k) + - microchip,mcp4632-502 + # Microchip 7-bit Dual I2C Digital Potentiometer (10k) + - microchip,mcp4632-103 + # Microchip 7-bit Dual I2C Digital Potentiometer (50k) + - microchip,mcp4632-503 + # Microchip 7-bit Dual I2C Digital Potentiometer (100k) + - microchip,mcp4632-104 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4641-502 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4641-103 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4641-503 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4641-104 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4642-502 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4642-103 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4642-503 + # Microchip 7-bit Dual I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4642-104 + # Microchip 8-bit Dual I2C Digital Potentiometer (5k) + - microchip,mcp4651-502 + # Microchip 8-bit Dual I2C Digital Potentiometer (10k) + - microchip,mcp4651-103 + # Microchip 8-bit Dual I2C Digital Potentiometer (50k) + - microchip,mcp4651-503 + # Microchip 8-bit Dual I2C Digital Potentiometer (100k) + - microchip,mcp4651-104 + # Microchip 8-bit Dual I2C Digital Potentiometer (5k) + - microchip,mcp4652-502 + # Microchip 8-bit Dual I2C Digital Potentiometer (10k) + - microchip,mcp4652-103 + # Microchip 8-bit Dual I2C Digital Potentiometer (50k) + - microchip,mcp4652-503 + # Microchip 8-bit Dual I2C Digital Potentiometer (100k) + - microchip,mcp4652-104 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4661-502 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4661-103 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4661-503 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4661-104 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (5k) + - microchip,mcp4662-502 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (10k) + - microchip,mcp4662-103 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (50k) + - microchip,mcp4662-503 + # Microchip 8-bit Dual I2C Digital Potentiometer with NV Memory (100k) + - microchip,mcp4662-104 + # PWM Fan Speed Controller With Fan Fault Detection + - microchip,tc654 + # PWM Fan Speed Controller With Fan Fault Detection + - microchip,tc655 + # MiraMEMS DA226 2-axis 14-bit digital accelerometer + - miramems,da226 + # MiraMEMS DA280 3-axis 14-bit digital accelerometer + - miramems,da280 + # MiraMEMS DA311 3-axis 12-bit digital accelerometer + - miramems,da311 + # Temperature sensor with integrated fan control + - national,lm63 + # I2C TEMP SENSOR + - national,lm75 + # Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor + - national,lm80 + # Temperature sensor with integrated fan control + - national,lm85 + # ±0.33°C Accurate, 12-Bit + Sign Temperature Sensor and Thermal Window Comparator with Two-Wire Interface + - national,lm92 + # i2c trusted platform module (TPM) + - nuvoton,npct501 + # i2c trusted platform module (TPM2) + - nuvoton,npct601 + # Nuvoton Temperature Sensor + - nuvoton,w83773g + # Octal SMBus and I2C registered interface + - nxp,pca9556 + # 8-bit I2C-bus and SMBus I/O port with reset + - nxp,pca9557 + # OKI ML86V7667 video decoder + - oki,ml86v7667 + # OV5642: Color CMOS QSXGA (5-megapixel) Image Sensor with OmniBSI and Embedded TrueFocus + - ovti,ov5642 + # 48-Lane, 12-Port PCI Express Gen 2 (5.0 GT/s) Switch + - plx,pex8648 + # Pulsedlight LIDAR range-finding sensor + - pulsedlight,lidar-lite-v2 + # S524AD0XF1 (128K/256K-bit Serial EEPROM for Low Power) + - samsung,24ad0xd1 + # SGX Sensortech VZ89X Sensors + - sgx,vz89x + # Relative Humidity and Temperature Sensors + - silabs,si7020 + # Skyworks SKY81452: Six-Channel White LED Driver with Touch Panel Bias Supply + - skyworks,sky81452 + # i2c serial eeprom (24cxx) + - st,24c256 + # Ambient Light Sensor with SMBUS/Two Wire Serial Interface + - taos,tsl2550 + # 8-Channels, 12-bit ADC + - ti,ads7828 + # 8-Channels, 8-bit ADC + - ti,ads7830 + # Temperature Monitoring and Fan Control + - ti,amc6821 + # Temperature sensor with integrated fan control + - ti,lm96000 + # I2C Touch-Screen Controller + - ti,tsc2003 + # Low Power Digital Temperature Sensor with SMBUS/Two Wire Serial Interface + - ti,tmp102 + # Low Power Digital Temperature Sensor with SMBUS/Two Wire Serial Interface + - ti,tmp103 + # Digital Temperature Sensor + - ti,tmp275 + # Winbond/Nuvoton H/W Monitor + - winbond,w83793 + # i2c trusted platform module (TPM) + - winbond,wpct301 + +required: + - compatible + - reg + +... diff --git a/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt b/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt new file mode 100644 index 000000000000..a04a4989ec7f --- /dev/null +++ b/Documentation/devicetree/bindings/ufs/cdns,ufshc.txt @@ -0,0 +1,31 @@ +* Cadence Universal Flash Storage (UFS) Controller + +UFS nodes are defined to describe on-chip UFS host controllers. +Each UFS controller instance should have its own node. +Please see the ufshcd-pltfrm.txt for a list of all available properties. + +Required properties: +- compatible : Compatible list, contains the following controller: + "cdns,ufshc" + complemented with the JEDEC version: + "jedec,ufs-2.0" + +- reg : Address and length of the UFS register set. +- interrupts : One interrupt mapping. +- freq-table-hz : Clock frequency table. + See the ufshcd-pltfrm.txt for details. +- clocks : List of phandle and clock specifier pairs. +- clock-names : List of clock input name strings sorted in the same + order as the clocks property. "core_clk" is mandatory. + Depending on a type of a PHY, + the "phy_clk" clock can also be added, if needed. + +Example: + ufs@fd030000 { + compatible = "cdns,ufshc", "jedec,ufs-2.0"; + reg = <0xfd030000 0x10000>; + interrupts = <0 1 IRQ_TYPE_LEVEL_HIGH>; + freq-table-hz = <0 0>, <0 0>; + clocks = <&ufs_core_clk>, <&ufs_phy_clk>; + clock-names = "core_clk", "phy_clk"; + }; diff --git a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt index 2df00524bd21..8cf59452c675 100644 --- a/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt +++ b/Documentation/devicetree/bindings/ufs/ufshcd-pltfrm.txt @@ -33,6 +33,12 @@ Optional properties: - clocks : List of phandle and clock specifier pairs - clock-names : List of clock input name strings sorted in the same order as the clocks property. + "ref_clk" indicates reference clock frequency. + UFS host supplies reference clock to UFS device and UFS device + specification allows host to provide one of the 4 frequencies (19.2 MHz, + 26 MHz, 38.4 MHz, 52MHz) for reference clock. This "ref_clk" entry is + parsed and used to update the reference clock setting in device. + Defaults to 26 MHz(as per specification) if not specified by host. - freq-table-hz : Array of <min max> operating frequencies stored in the same order as the clocks property. If this property is not defined or a value in the array is "0" then it is assumed diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt index 2e9318151df7..a254386a91ad 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt @@ -80,13 +80,20 @@ Optional properties: controller. It's expected that a mux state of 0 indicates device mode and a mux state of 1 indicates host mode. - mux-control-names: Shall be "usb_switch" if mux-controls is specified. +- pinctrl-names: Names for optional pin modes in "default", "host", "device". + In case of HSIC-mode, "idle" and "active" pin modes are mandatory. In this + case, the "idle" state needs to pull down the data and strobe pin + and the "active" state needs to pull up the strobe pin. +- pinctrl-n: alternate pin modes i.mx specific properties - fsl,usbmisc: phandler of non-core register device, with one argument that indicate usb controller index - disable-over-current: disable over current detect -- over-current-active-high: over current signal polarity is high active, - typically over current signal polarity is low active. +- over-current-active-low: over current signal polarity is active low. +- over-current-active-high: over current signal polarity is active high. + It's recommended to specify the over current polarity. +- power-active-high: power signal polarity is active high - external-vbus-divider: enables off-chip resistor divider for Vbus Example: @@ -109,3 +116,29 @@ Example: mux-controls = <&usb_switch>; mux-control-names = "usb_switch"; }; + +Example for HSIC: + + usb@2184400 { + compatible = "fsl,imx6q-usb", "fsl,imx27-usb"; + reg = <0x02184400 0x200>; + interrupts = <0 41 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6QDL_CLK_USBOH3>; + fsl,usbphy = <&usbphynop1>; + fsl,usbmisc = <&usbmisc 2>; + phy_type = "hsic"; + dr_mode = "host"; + ahb-burst-config = <0x0>; + tx-burst-size-dword = <0x10>; + rx-burst-size-dword = <0x10>; + pinctrl-names = "idle", "active"; + pinctrl-0 = <&pinctrl_usbh2_idle>; + pinctrl-1 = <&pinctrl_usbh2_active>; + #address-cells = <1>; + #size-cells = <0>; + + usbnet: smsc@1 { + compatible = "usb424,9730"; + reg = <1>; + }; + }; diff --git a/Documentation/devicetree/bindings/usb/dwc2.txt b/Documentation/devicetree/bindings/usb/dwc2.txt index 46da5f184460..6dc3c4a34483 100644 --- a/Documentation/devicetree/bindings/usb/dwc2.txt +++ b/Documentation/devicetree/bindings/usb/dwc2.txt @@ -6,6 +6,7 @@ Required properties: - brcm,bcm2835-usb: The DWC2 USB controller instance in the BCM2835 SoC. - hisilicon,hi6220-usb: The DWC2 USB controller instance in the hi6220 SoC. - rockchip,rk3066-usb: The DWC2 USB controller instance in the rk3066 Soc; + - "rockchip,px30-usb", "rockchip,rk3066-usb", "snps,dwc2": for px30 Soc; - "rockchip,rk3188-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3188 Soc; - "rockchip,rk3288-usb", "rockchip,rk3066-usb", "snps,dwc2": for rk3288 Soc; - "lantiq,arx100-usb": The DWC2 USB controller instance in Lantiq ARX SoCs; diff --git a/Documentation/devicetree/bindings/usb/dwc3.txt b/Documentation/devicetree/bindings/usb/dwc3.txt index 3e4c38b806ac..8e5265e9f658 100644 --- a/Documentation/devicetree/bindings/usb/dwc3.txt +++ b/Documentation/devicetree/bindings/usb/dwc3.txt @@ -19,6 +19,7 @@ Exception for clocks: "cavium,octeon-7130-usb-uctl" "qcom,dwc3" "samsung,exynos5250-dwusb3" + "samsung,exynos5433-dwusb3" "samsung,exynos7-dwusb3" "sprd,sc9860-dwc3" "st,stih407-dwc3" @@ -36,7 +37,11 @@ Optional properties: - phy-names: from the *Generic PHY* bindings; supported names are "usb2-phy" or "usb3-phy". - resets: a single pair of phandle and reset specifier + - snps,usb2-lpm-disable: indicate if we don't want to enable USB2 HW LPM - snps,usb3_lpm_capable: determines if platform is USB3 LPM capable + - snps,dis-start-transfer-quirk: when set, disable isoc START TRANSFER command + failure SW work-around for DWC_usb31 version 1.70a-ea06 + and prior. - snps,disable_scramble_quirk: true when SW should disable data scrambling. Only really useful for FPGA builds. - snps,has-lpm-erratum: true when DWC3 was configured with LPM Erratum enabled diff --git a/Documentation/devicetree/bindings/usb/ehci-mv.txt b/Documentation/devicetree/bindings/usb/ehci-mv.txt new file mode 100644 index 000000000000..335589895763 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ehci-mv.txt @@ -0,0 +1,23 @@ +* Marvell PXA/MMP EHCI controller. + +Required properties: + +- compatible: must be "marvell,pxau2o-ehci" +- reg: physical base addresses of the controller and length of memory mapped region +- interrupts: one EHCI controller interrupt should be described here +- clocks: phandle list of usb clocks +- clock-names: should be "USBCLK" +- phys: phandle for the PHY device +- phy-names: should be "usb" + +Example: + + ehci0: usb-ehci@d4208000 { + compatible = "marvell,pxau2o-ehci"; + reg = <0xd4208000 0x200>; + interrupts = <44>; + clocks = <&soc_clocks MMP2_CLK_USB>; + clock-names = "USBCLK"; + phys = <&usb_otg_phy>; + phy-names = "usb"; + }; diff --git a/Documentation/devicetree/bindings/usb/exynos-usb.txt b/Documentation/devicetree/bindings/usb/exynos-usb.txt index c97374315049..b7111f43fa59 100644 --- a/Documentation/devicetree/bindings/usb/exynos-usb.txt +++ b/Documentation/devicetree/bindings/usb/exynos-usb.txt @@ -83,6 +83,8 @@ Required properties: - compatible: should be one of the following - "samsung,exynos5250-dwusb3": for USB 3.0 DWC3 controller on Exynos5250/5420. + "samsung,exynos5433-dwusb3": for USB 3.0 DWC3 controller on + Exynos5433. "samsung,exynos7-dwusb3": for USB 3.0 DWC3 controller on Exynos7. - #address-cells, #size-cells : should be '1' if the device has sub-nodes with 'reg' property. diff --git a/Documentation/devicetree/bindings/usb/faraday,fotg210.txt b/Documentation/devicetree/bindings/usb/faraday,fotg210.txt new file mode 100644 index 000000000000..06a2286e2054 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/faraday,fotg210.txt @@ -0,0 +1,35 @@ +Faraday FOTG Host controller + +This OTG-capable USB host controller is found in Cortina Systems +Gemini and other SoC products. + +Required properties: +- compatible: should be one of: + "faraday,fotg210" + "cortina,gemini-usb", "faraday,fotg210" +- reg: should contain one register range i.e. start and length +- interrupts: description of the interrupt line + +Optional properties: +- clocks: should contain the IP block clock +- clock-names: should be "PCLK" for the IP block clock + +Required properties for "cortina,gemini-usb" compatible: +- syscon: a phandle to the system controller to access PHY registers + +Optional properties for "cortina,gemini-usb" compatible: +- cortina,gemini-mini-b: boolean property that indicates that a Mini-B + OTG connector is in use +- wakeup-source: see power/wakeup-source.txt + +Example for Gemini: + +usb@68000000 { + compatible = "cortina,gemini-usb", "faraday,fotg210"; + reg = <0x68000000 0x1000>; + interrupts = <10 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&cc 12>; + clock-names = "PCLK"; + syscon = <&syscon>; + wakeup-source; +}; diff --git a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt index 6087dc7f209e..a5d011d2efc8 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fusb302.txt +++ b/Documentation/devicetree/bindings/usb/fcs,fusb302.txt @@ -5,10 +5,19 @@ Required properties : - reg : I2C slave address - interrupts : Interrupt specifier -Optional properties : -- fcs,operating-sink-microwatt : - Minimum amount of power accepted from a sink - when negotiating +Required sub-node: +- connector : The "usb-c-connector" attached to the FUSB302 IC. The bindings + of the connector node are specified in: + + Documentation/devicetree/bindings/connector/usb-connector.txt + +Deprecated properties : +- fcs,max-sink-microvolt : Maximum sink voltage accepted by port controller +- fcs,max-sink-microamp : Maximum sink current accepted by port controller +- fcs,max-sink-microwatt : Maximum sink power accepted by port controller +- fcs,operating-sink-microwatt : Minimum amount of power accepted from a sink + when negotiating + Example: @@ -17,7 +26,16 @@ fusb302: typec-portc@54 { reg = <0x54>; interrupt-parent = <&nmi_intc>; interrupts = <0 IRQ_TYPE_LEVEL_LOW>; - fcs,max-sink-microvolt = <12000000>; - fcs,max-sink-microamp = <3000000>; - fcs,max-sink-microwatt = <36000000>; + + usb_con: connector { + compatible = "usb-c-connector"; + label = "USB-C"; + power-role = "dual"; + try-power-role = "sink"; + source-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM)>; + sink-pdos = <PDO_FIXED(5000, 3000, PDO_FIXED_USB_COMM) + PDO_VAR(3000, 12000, 3000) + PDO_PPS_APDO(3000, 11000, 3000)>; + op-sink-microwatt = <10000000>; + }; }; diff --git a/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt b/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt new file mode 100644 index 000000000000..620355cee63f --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ingenic,jz4740-musb.txt @@ -0,0 +1,24 @@ +Ingenic JZ4740 MUSB driver + +Required properties: + +- compatible: Must be "ingenic,jz4740-musb" +- reg: Address range of the UDC register set +- interrupts: IRQ number related to the UDC hardware +- interrupt-names: must be "mc" +- clocks: phandle to the "udc" clock +- clock-names: must be "udc" + +Example: + +udc: usb@13040000 { + compatible = "ingenic,jz4740-musb"; + reg = <0x13040000 0x10000>; + + interrupt-parent = <&intc>; + interrupts = <24>; + interrupt-names = "mc"; + + clocks = <&cgu JZ4740_CLK_UDC>; + clock-names = "udc"; +}; diff --git a/Documentation/devicetree/bindings/usb/keystone-usb.txt b/Documentation/devicetree/bindings/usb/keystone-usb.txt index f96e09f784cc..77df82e36138 100644 --- a/Documentation/devicetree/bindings/usb/keystone-usb.txt +++ b/Documentation/devicetree/bindings/usb/keystone-usb.txt @@ -3,7 +3,9 @@ TI Keystone Soc USB Controller DWC3 GLUE Required properties: - - compatible: should be "ti,keystone-dwc3". + - compatible: should be + "ti,keystone-dwc3" for Keystone 2 SoCs + "ti,am654-dwc3" for AM654 SoC - #address-cells, #size-cells : should be '1' if the device has sub-nodes with 'reg' property. - reg : Address and length of the register set for the USB subsystem on @@ -21,7 +23,7 @@ SoCs only: - clock-names: Must be "usb". -The following are mandatory properties for Keystone 2 66AK2G SoCs only: +The following are mandatory properties for 66AK2G and AM654: - power-domains: Should contain a phandle to a PM domain provider node and an args specifier containing the USB device id diff --git a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt index 3eee9e505400..4156c3e181c5 100644 --- a/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt +++ b/Documentation/devicetree/bindings/usb/nvidia,tegra124-xusb.txt @@ -59,6 +59,14 @@ For Tegra210: - avdd-pll-uerefe-supply: PLLE reference PLL power supply. Must supply 1.05 V. - dvdd-pex-pll-supply: PCIe/USB3 PLL power supply. Must supply 1.05 V. - hvdd-pex-pll-e-supply: High-voltage PLLE power supply. Must supply 1.8 V. +- power-domains: A list of PM domain specifiers that reference each power-domain + used by the xHCI controller. This list must comprise of a specifier for the + XUSBA and XUSBC power-domains. See ../power/power_domain.txt and + ../arm/tegra/nvidia,tegra20-pmc.txt for details. +- power-domain-names: A list of names that represent each of the specifiers in + the 'power-domains' property. Must include 'xusb_ss' and 'xusb_host' which + represent the power-domains XUSBA and XUSBC, respectively. See + ../power/power_domain.txt for details. Optional properties: -------------------- diff --git a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt index 95afdcf3c337..cb695aa3fba4 100644 --- a/Documentation/devicetree/bindings/usb/qcom,dwc3.txt +++ b/Documentation/devicetree/bindings/usb/qcom,dwc3.txt @@ -4,6 +4,7 @@ Required properties: - compatible: Compatible list, contains "qcom,dwc3" "qcom,msm8996-dwc3" for msm8996 SOC. + "qcom,msm8998-dwc3" for msm8998 SOC. "qcom,sdm845-dwc3" for sdm845 SOC. - reg: Offset and length of register set for QSCRATCH wrapper - power-domains: specifies a phandle to PM domain provider node diff --git a/Documentation/devicetree/bindings/usb/renesas_usb3.txt b/Documentation/devicetree/bindings/usb/renesas_usb3.txt index 2c071bb5801e..35039e720515 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usb3.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usb3.txt @@ -2,11 +2,14 @@ Renesas Electronics USB3.0 Peripheral driver Required properties: - compatible: Must contain one of the following: + - "renesas,r8a774a1-usb3-peri" + - "renesas,r8a774c0-usb3-peri" - "renesas,r8a7795-usb3-peri" - "renesas,r8a7796-usb3-peri" - "renesas,r8a77965-usb3-peri" - - "renesas,rcar-gen3-usb3-peri" for a generic R-Car Gen3 compatible - device + - "renesas,r8a77990-usb3-peri" + - "renesas,rcar-gen3-usb3-peri" for a generic R-Car Gen3 or RZ/G2 + compatible device When compatible with the generic version, nodes must list the SoC-specific version corresponding to the platform first diff --git a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt index 43960faf5a88..d93b6a1504f2 100644 --- a/Documentation/devicetree/bindings/usb/renesas_usbhs.txt +++ b/Documentation/devicetree/bindings/usb/renesas_usbhs.txt @@ -4,7 +4,10 @@ Required properties: - compatible: Must contain one or more of the following: - "renesas,usbhs-r8a7743" for r8a7743 (RZ/G1M) compatible device + - "renesas,usbhs-r8a7744" for r8a7744 (RZ/G1N) compatible device - "renesas,usbhs-r8a7745" for r8a7745 (RZ/G1E) compatible device + - "renesas,usbhs-r8a774a1" for r8a774a1 (RZ/G2M) compatible device + - "renesas,usbhs-r8a774c0" for r8a774c0 (RZ/G2E) compatible device - "renesas,usbhs-r8a7790" for r8a7790 (R-Car H2) compatible device - "renesas,usbhs-r8a7791" for r8a7791 (R-Car M2-W) compatible device - "renesas,usbhs-r8a7792" for r8a7792 (R-Car V2H) compatible device @@ -13,10 +16,11 @@ Required properties: - "renesas,usbhs-r8a7795" for r8a7795 (R-Car H3) compatible device - "renesas,usbhs-r8a7796" for r8a7796 (R-Car M3-W) compatible device - "renesas,usbhs-r8a77965" for r8a77965 (R-Car M3-N) compatible device + - "renesas,usbhs-r8a77990" for r8a77990 (R-Car E3) compatible device - "renesas,usbhs-r8a77995" for r8a77995 (R-Car D3) compatible device - "renesas,usbhs-r7s72100" for r7s72100 (RZ/A1) compatible device - "renesas,rcar-gen2-usbhs" for R-Car Gen2 or RZ/G1 compatible devices - - "renesas,rcar-gen3-usbhs" for R-Car Gen3 compatible device + - "renesas,rcar-gen3-usbhs" for R-Car Gen3 or RZ/G2 compatible devices - "renesas,rza1-usbhs" for RZ/A1 compatible device When compatible with the generic version, nodes must list the @@ -25,7 +29,11 @@ Required properties: - reg: Base address and length of the register for the USBHS - interrupts: Interrupt specifier for the USBHS - - clocks: A list of phandle + clock specifier pairs + - clocks: A list of phandle + clock specifier pairs. + - In case of "renesas,rcar-gen3-usbhs", two clocks are required. + First clock should be peripheral and second one should be host. + - In case of except above, one clock is required. First clock + should be peripheral. Optional properties: - renesas,buswait: Integer to use BUSWAIT register diff --git a/Documentation/devicetree/bindings/usb/usb-ehci.txt b/Documentation/devicetree/bindings/usb/usb-ehci.txt index 0f1b75386207..406252d14c6b 100644 --- a/Documentation/devicetree/bindings/usb/usb-ehci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ehci.txt @@ -15,7 +15,11 @@ Optional properties: - needs-reset-on-resume : boolean, set this to force EHCI reset after resume - has-transaction-translator : boolean, set this if EHCI have a Transaction Translator built into the root hub. - - clocks : a list of phandle + clock specifier pairs + - clocks : a list of phandle + clock specifier pairs. In case of Renesas + R-Car Gen3 SoCs: + - if a host only channel: first clock should be host. + - if a USB DRD channel: first clock should be host and second one + should be peripheral. - phys : see usb-hcd.txt in the current directory - resets : phandle + reset specifier pair diff --git a/Documentation/devicetree/bindings/usb/usb-ohci.txt b/Documentation/devicetree/bindings/usb/usb-ohci.txt index a8d2103d1f3d..aaaa5255c972 100644 --- a/Documentation/devicetree/bindings/usb/usb-ohci.txt +++ b/Documentation/devicetree/bindings/usb/usb-ohci.txt @@ -12,7 +12,11 @@ Optional properties: - no-big-frame-no : boolean, set if frame_no lives in bits [15:0] of HCCA - remote-wakeup-connected: remote wakeup is wired on the platform - num-ports : u32, to override the detected port count -- clocks : a list of phandle + clock specifier pairs +- clocks : a list of phandle + clock specifier pairs. In case of Renesas + R-Car Gen3 SoCs: + - if a host only channel: first clock should be host. + - if a USB DRD channel: first clock should be host and second one + should be peripheral. - phys : see usb-hcd.txt in the current directory - resets : a list of phandle + reset specifier pairs diff --git a/Documentation/devicetree/bindings/usb/usb-xhci.txt b/Documentation/devicetree/bindings/usb/usb-xhci.txt index ac4cd0d6195a..fea8b1545751 100644 --- a/Documentation/devicetree/bindings/usb/usb-xhci.txt +++ b/Documentation/devicetree/bindings/usb/usb-xhci.txt @@ -8,6 +8,8 @@ Required properties: - "marvell,armada-375-xhci" for Armada 375 SoCs - "marvell,armada-380-xhci" for Armada 38x SoCs - "renesas,xhci-r8a7743" for r8a7743 SoC + - "renesas,xhci-r8a7744" for r8a7744 SoC + - "renesas,xhci-r8a774a1" for r8a774a1 SoC - "renesas,xhci-r8a7790" for r8a7790 SoC - "renesas,xhci-r8a7791" for r8a7791 SoC - "renesas,xhci-r8a7793" for r8a7793 SoC @@ -17,7 +19,8 @@ Required properties: - "renesas,xhci-r8a77990" for r8a77990 SoC - "renesas,rcar-gen2-xhci" for a generic R-Car Gen2 or RZ/G1 compatible device - - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 compatible device + - "renesas,rcar-gen3-xhci" for a generic R-Car Gen3 or RZ/G2 compatible + device - "xhci-platform" (deprecated) When compatible with the generic version, nodes must list the diff --git a/Documentation/devicetree/bindings/usb/usb251xb.txt b/Documentation/devicetree/bindings/usb/usb251xb.txt index 168ff819e827..17915f64b8ee 100644 --- a/Documentation/devicetree/bindings/usb/usb251xb.txt +++ b/Documentation/devicetree/bindings/usb/usb251xb.txt @@ -64,6 +64,8 @@ Optional properties : - 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). + - swap-dx-lanes : Specifies the ports which will swap the differential-pair + (D+/D-), default is not-swapped. Examples: usb2512b@2c { @@ -81,4 +83,6 @@ Examples: manufacturer = "Foo"; product = "Foo-Bar"; serial = "1234567890A"; + /* correct misplaced usb connectors on port 1,2 */ + swap-dx-lanes = <1 2>; }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index f26bf667e530..385d22460b1d 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -24,6 +24,7 @@ amarula Amarula Solutions amazon Amazon.com, Inc. amcc Applied Micro Circuits Corporation (APM, formally AMCC) amd Advanced Micro Devices (AMD), Inc. +amediatech Shenzhen Amediatech Technology Co., Ltd amlogic Amlogic, Inc. ampire Ampire Co., Ltd. ams AMS AG @@ -65,8 +66,10 @@ bticino Bticino International calxeda Calxeda capella Capella Microsystems, Inc cascoda Cascoda, Ltd. +catalyst Catalyst Semiconductor, Inc. cavium Cavium, Inc. cdns Cadence Design Systems Inc. +cdtech CDTech(H.K.) Electronics Limited ceva Ceva, Inc. chipidea Chipidea, Inc chipone ChipOne @@ -84,6 +87,7 @@ cosmic Cosmic Circuits crane Crane Connectivity Solutions creative Creative Technology Ltd crystalfontz Crystalfontz America, Inc. +csky Hangzhou C-SKY Microsystems Co., Ltd cubietech Cubietech, Ltd. cypress Cypress Semiconductor Corporation cznic CZ.NIC, z.s.p.o. @@ -106,14 +110,18 @@ dongwoon Dongwoon Anatech dptechnics DPTechnics dragino Dragino Technology Co., Limited ea Embedded Artists AB +ebs-systart EBS-SYSTART GmbH ebv EBV Elektronik eckelmann Eckelmann AG edt Emerging Display Technologies eeti eGalax_eMPIA Technology Inc elan Elan Microelectronic Corp. +elgin Elgin S/A. embest Shenzhen Embest Technology Co., Ltd. +emlid Emlid, Ltd. emmicro EM Microelectronic emtrion emtrion GmbH +endless Endless Mobile, Inc. energymicro Silicon Laboratories (formerly Energy Micro AS) engicam Engicam S.r.l. epcos EPCOS AG @@ -127,6 +135,7 @@ everspin Everspin Technologies, Inc. exar Exar Corporation excito Excito ezchip EZchip Semiconductor +facebook Facebook fairphone Fairphone B.V. faraday Faraday Technology Corporation fastrax Fastrax Oy @@ -136,6 +145,7 @@ focaltech FocalTech Systems Co.,Ltd friendlyarm Guangzhou FriendlyARM Computer Tech Co., Ltd fsl Freescale Semiconductor fujitsu Fujitsu Ltd. +gateworks Gateworks Corporation gcw Game Consoles Worldwide ge General Electric Company geekbuying GeekBuying @@ -145,6 +155,7 @@ geniatech Geniatech, Inc. giantec Giantec Semiconductor, Inc. giantplus Giantplus Technology Co., Ltd. globalscale Globalscale Technologies, Inc. +globaltop GlobalTop Technology, Inc. gmt Global Mixed-mode Technology, Inc. goodix Shenzhen Huiding Technology Co., Ltd. google Google, Inc. @@ -167,6 +178,7 @@ holtek Holtek Semiconductor, Inc. hwacom HwaCom Systems Inc. i2se I2SE GmbH ibm International Business Machines (IBM) +icplus IC Plus Corp. idt Integrated Device Technologies, Inc. ifi Ingenieurburo Fur Ic-Technologie (I/F/I) ilitek ILI Technology Corporation (ILITEK) @@ -205,6 +217,7 @@ laird Laird PLC lantiq Lantiq Semiconductor lattice Lattice Semiconductor lego LEGO Systems A/S +lemaker Shenzhen LeMaker Technology Co., Ltd. lenovo Lenovo Group Ltd. lg LG Corporation libretech Shenzhen Libre Technology Co., Ltd @@ -267,6 +280,7 @@ nintendo Nintendo nlt NLT Technologies, Ltd. nokia Nokia nordic Nordic Semiconductor +novtech NovTech, Inc. nutsboard NutsBoard nuvoton Nuvoton Technology Corporation nvd New Vision Display @@ -275,6 +289,7 @@ nxp NXP Semiconductors okaya Okaya Electric America, Inc. oki Oki Electric Industry Co., Ltd. olimex OLIMEX Ltd. +olpc One Laptop Per Child onion Onion Corporation onnn ON Semiconductor Corp. ontat On Tat Industrial Company @@ -290,14 +305,19 @@ ovti OmniVision Technologies oxsemi Oxford Semiconductor, Ltd. panasonic Panasonic Corporation parade Parade Technologies Inc. +pda Precision Design Associates, Inc. pericom Pericom Technology Inc. pervasive Pervasive Displays, Inc. +phicomm PHICOMM Co., Ltd. phytec PHYTEC Messtechnik GmbH picochip Picochip Ltd pine64 Pine64 pixcir PIXCIR MICROELECTRONICS Co., Ltd +plantower Plantower Co., Ltd plathome Plat'Home Co., Ltd. plda PLDA +plx Broadcom Corporation (formerly PLX Technology) +pni PNI Sensor Corporation portwell Portwell Inc. poslab Poslab Technology Co., Ltd. powervr PowerVR (deprecated, use img) @@ -315,6 +335,7 @@ ralink Mediatek/Ralink Technology Corp. ramtron Ramtron International raspberrypi Raspberry Pi Foundation raydium Raydium Semiconductor Corp. +rda Unisoc Communications, Inc. realtek Realtek Semiconductor Corp. renesas Renesas Electronics Corporation richtek Richtek Technology Corporation @@ -410,6 +431,7 @@ vamrs Vamrs Ltd. variscite Variscite Ltd. via VIA Technologies, Inc. virtio Virtual I/O Device Specification, developed by the OASIS consortium +vishay Vishay Intertechnology, Inc vitesse Vitesse Semiconductor Corporation vivante Vivante Corporation vocore VoCore Studio @@ -418,6 +440,7 @@ vot Vision Optical Technology Co., Ltd. wd Western Digital Corp. wetek WeTek Electronics, limited. wexler Wexler +whwave Shenzhen whwave Electronics, Inc. wi2wi Wi2Wi, Inc. winbond Winbond Electronics corp. winstar Winstar Display Corp. diff --git a/Documentation/devicetree/bindings/watchdog/armada-37xx-wdt.txt b/Documentation/devicetree/bindings/watchdog/armada-37xx-wdt.txt new file mode 100644 index 000000000000..a8d00c31a1d8 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/armada-37xx-wdt.txt @@ -0,0 +1,23 @@ +* Armada 37xx CPU Watchdog Timer Controller + +Required properties: +- compatible : must be "marvell,armada-3700-wdt" +- reg : base physical address of the controller and length of memory mapped + region. +- clocks : the clock feeding the watchdog timer. See clock-bindings.txt +- marvell,system-controller : reference to syscon node for the CPU Miscellaneous + Registers + +Example: + + cpu_misc: system-controller@d000 { + compatible = "marvell,armada-3700-cpu-misc", "syscon"; + reg = <0xd000 0x1000>; + }; + + wdt: watchdog@8300 { + compatible = "marvell,armada-3700-wdt"; + reg = <0x8300 0x40>; + marvell,system-controller = <&cpu_misc>; + clocks = <&xtalclk>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/mpc8xxx-wdt.txt b/Documentation/devicetree/bindings/watchdog/mpc8xxx-wdt.txt new file mode 100644 index 000000000000..a384ff5b3ce8 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/mpc8xxx-wdt.txt @@ -0,0 +1,25 @@ +* Freescale mpc8xxx watchdog driver (For 83xx, 86xx and 8xx) + +Required properties: +- compatible: Shall contain one of the following: + "mpc83xx_wdt" for an mpc83xx + "fsl,mpc8610-wdt" for an mpc86xx + "fsl,mpc823-wdt" for an mpc8xx +- reg: base physical address and length of the area hosting the + watchdog registers. + On the 83xx, "Watchdog Timer Registers" area: <0x200 0x100> + On the 86xx, "Watchdog Timer Registers" area: <0xe4000 0x100> + On the 8xx, "General System Interface Unit" area: <0x0 0x10> + +Optional properties: +- reg: additional physical address and length (4) of location of the + Reset Status Register (called RSTRSCR on the mpc86xx) + On the 83xx, it is located at offset 0x910 + On the 86xx, it is located at offset 0xe0094 + On the 8xx, it is located at offset 0x288 + +Example: + WDT: watchdog@0 { + compatible = "fsl,mpc823-wdt"; + reg = <0x0 0x10 0x288 0x4>; + }; diff --git a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt index 859dee167b91..8682d6a93e5b 100644 --- a/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/mtk-wdt.txt @@ -8,6 +8,7 @@ Required properties: "mediatek,mt6797-wdt", "mediatek,mt6589-wdt": for MT6797 "mediatek,mt7622-wdt", "mediatek,mt6589-wdt": for MT7622 "mediatek,mt7623-wdt", "mediatek,mt6589-wdt": for MT7623 + "mediatek,mt7629-wdt", "mediatek,mt6589-wdt": for MT7629 - reg : Specifies base physical address and size of the registers. diff --git a/Documentation/devicetree/bindings/watchdog/qcom,pm8916-wdt.txt b/Documentation/devicetree/bindings/watchdog/qcom,pm8916-wdt.txt new file mode 100644 index 000000000000..6fb984f31982 --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/qcom,pm8916-wdt.txt @@ -0,0 +1,28 @@ +QCOM PM8916 watchdog timer controller + +This pm8916 watchdog timer controller must be under pm8916-pon node. + +Required properties: +- compatible: should be "qcom,pm8916-wdt" + +Optional properties : +- interrupts : Watchdog pre-timeout (bark) interrupt. +- timeout-sec : Watchdog timeout value in seconds. + +Example: + + pm8916_0: pm8916@0 { + compatible = "qcom,pm8916", "qcom,spmi-pmic"; + reg = <0x0 SPMI_USID>; + + pon@800 { + compatible = "qcom,pm8916-pon"; + reg = <0x800>; + + watchdog { + compatible = "qcom,pm8916-wdt"; + interrupts = <0x0 0x8 6 IRQ_TYPE_EDGE_RISING>; + timeout-sec = <10>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt index 9407212a85a8..ef2b97b72e08 100644 --- a/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/renesas-wdt.txt @@ -6,8 +6,10 @@ Required properties: version. Examples with soctypes are: - "renesas,r8a7743-wdt" (RZ/G1M) + - "renesas,r8a7744-wdt" (RZ/G1N) - "renesas,r8a7745-wdt" (RZ/G1E) - "renesas,r8a774a1-wdt" (RZ/G2M) + - "renesas,r8a774c0-wdt" (RZ/G2E) - "renesas,r8a7790-wdt" (R-Car H2) - "renesas,r8a7791-wdt" (R-Car M2-W) - "renesas,r8a7792-wdt" (R-Car V2H) @@ -20,6 +22,7 @@ Required properties: - "renesas,r8a77990-wdt" (R-Car E3) - "renesas,r8a77995-wdt" (R-Car D3) - "renesas,r7s72100-wdt" (RZ/A1) + - "renesas,r7s9210-wdt" (RZ/A2) The generic compatible string must be: - "renesas,rza-wdt" for RZ/A - "renesas,rcar-gen2-wdt" for R-Car Gen2 and RZ/G1 diff --git a/Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt b/Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt new file mode 100644 index 000000000000..7cc1407f15cb --- /dev/null +++ b/Documentation/devicetree/bindings/watchdog/st,stpmic1-wdt.txt @@ -0,0 +1,11 @@ +STMicroelectronics STPMIC1 Watchdog + +Required properties: + +- compatible : should be "st,stpmic1-wdt" + +Example: + +watchdog { + compatible = "st,stpmic1-wdt"; +}; diff --git a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt index ed11ce0ac836..46055254e8dd 100644 --- a/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt +++ b/Documentation/devicetree/bindings/watchdog/sunxi-wdt.txt @@ -6,6 +6,7 @@ Required properties: "allwinner,sun4i-a10-wdt" "allwinner,sun6i-a31-wdt" "allwinner,sun50i-a64-wdt","allwinner,sun6i-a31-wdt" + "allwinner,suniv-f1c100s-wdt", "allwinner,sun4i-a10-wdt" - reg : Specifies base physical address and size of the registers. Optional properties: diff --git a/Documentation/devicetree/todo.txt b/Documentation/devicetree/todo.txt deleted file mode 100644 index b5139d1de811..000000000000 --- a/Documentation/devicetree/todo.txt +++ /dev/null @@ -1,10 +0,0 @@ -Todo list for devicetree: - -=== General structure === -- Switch from custom lists to (h)list_head for nodes and properties structure - -=== CONFIG_OF_DYNAMIC === -- Switch to RCU for tree updates and get rid of global spinlock -- Document node lifecycle for CONFIG_OF_DYNAMIC -- Always set ->full_name at of_attach_node() time -- pseries: Get rid of open-coded tree modification from arch/powerpc/platforms/pseries/dlpar.c diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md new file mode 100644 index 000000000000..a3652d33a48f --- /dev/null +++ b/Documentation/devicetree/writing-schema.md @@ -0,0 +1,130 @@ +# Writing DeviceTree Bindings in json-schema + +Devicetree bindings are written using json-schema vocabulary. Schema files are +written in a JSON compatible subset of YAML. YAML is used instead of JSON as it +considered more human readable and has some advantages such as allowing +comments (Prefixed with '#'). + +## Schema Contents + +Each schema doc is a structured json-schema which is defined by a set of +top-level properties. Generally, there is one binding defined per file. The +top-level json-schema properties used are: + +- __$id__ - A json-schema unique identifier string. The string must be a valid +URI typically containing the binding's filename and path. For DT schema, it must +begin with "http://devicetree.org/schemas/". The URL is used in constructing +references to other files specified in schema "$ref" properties. A $ref values +with a leading '/' will have the hostname prepended. A $ref value a relative +path or filename only will be prepended with the hostname and path components +of the current schema file's '$id' value. A URL is used even for local files, +but there may not actually be files present at those locations. + +- __$schema__ - Indicates the meta-schema the schema file adheres to. + +- __title__ - A one line description on the contents of the binding schema. + +- __maintainers__ - A DT specific property. Contains a list of email address(es) +for maintainers of this binding. + +- __description__ - Optional. A multi-line text block containing any detailed +information about this binding. It should contain things such as what the block +or device does, standards the device conforms to, and links to datasheets for +more information. + +- __select__ - Optional. A json-schema used to match nodes for applying the +schema. By default without 'select', nodes are matched against their possible +compatible string values or node name. Most bindings should not need select. + +- __allOf__ - Optional. A list of other schemas to include. This is used to +include other schemas the binding conforms to. This may be schemas for a +particular class of devices such as I2C or SPI controllers. + +- __properties__ - A set of sub-schema defining all the DT properties for the +binding. The exact schema syntax depends on whether properties are known, +common properties (e.g. 'interrupts') or are binding/vendor specific properties. + + A property can also define a child DT node with child properties defined +under it. + + For more details on properties sections, see 'Property Schema' section. + +- __patternProperties__ - Optional. Similar to 'properties', but names are regex. + +- __required__ - A list of DT properties from the 'properties' section that +must always be present. + +- __examples__ - Optional. A list of one or more DTS hunks implementing the +binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. + +Unless noted otherwise, all properties are required. + +## Property Schema + +The 'properties' section of the schema contains all the DT properties for a +binding. Each property contains a set of constraints using json-schema +vocabulary for that property. The properties schemas are what is used for +validation of DT files. + +For common properties, only additional constraints not covered by the common +binding schema need to be defined such as how many values are valid or what +possible values are valid. + +Vendor specific properties will typically need more detailed schema. With the +exception of boolean properties, they should have a reference to a type in +schemas/types.yaml. A "description" property is always required. + +The Devicetree schemas don't exactly match the YAML encoded DT data produced by +dtc. They are simplified to make them more compact and avoid a bunch of +boilerplate. The tools process the schema files to produce the final schema for +validation. There are currently 2 transformations the tools perform. + +The default for arrays in json-schema is they are variable sized and allow more +entries than explicitly defined. This can be restricted by defining 'minItems', +'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed +size is desired in most cases, so these properties are added based on the +number of entries in an 'items' list. + +The YAML Devicetree format also makes all string values an array and scalar +values a matrix (in order to define groupings) even when only a single value +is present. Single entries in schemas are fixed up to match this encoding. + +## Testing + +### Dependencies + +The DT schema project must be installed in order to validate the DT schema +binding documents and validate DTS files using the DT schema. The DT schema +project can be installed with pip: + +`pip3 install git+https://github.com/robherring/yaml-bindings.git@master` + +dtc must also be built with YAML output support enabled. This requires that +libyaml and its headers be installed on the host system. + +### Running checks + +The DT schema binding documents must be validated using the meta-schema (the +schema for the schema) to ensure they are both valid json-schema and valid +binding schema. All of the DT binding documents can be validated using the +`dt_binding_check` target: + +`make dt_binding_check` + +In order to perform validation of DT source files, use the `dtbs_check` target: + +`make dtbs_check` + +This will first run the `dt_binding_check` which generates the processed schema. + +It is also possible to run checks with a single schema file by setting the +'DT_SCHEMA_FILES' variable to a specific schema file. + +`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml` + + +## json-schema Resources + +[JSON-Schema Specifications](http://json-schema.org/) + +[Using JSON Schema Book](http://usingjsonschema.com/) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 8db53cdc225f..51be62aa4385 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -77,7 +77,7 @@ The general format of a function and function-like macro kernel-doc comment is:: * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. - * Return: Describe the return value of foobar. + * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index f0796daa95b4..02605ee1d876 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -1,3 +1,5 @@ +.. _sphinxdoc: + Introduction ============ diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 2228fcc8e29f..ef25a066d952 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -106,7 +106,6 @@ compile.h* conf config config-* -config_data.h* config.mak config.mak.autogen conmakehash diff --git a/Documentation/driver-api/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst index 85a8335e80b6..eab40bcf3987 100644 --- a/Documentation/driver-api/80211/mac80211.rst +++ b/Documentation/driver-api/80211/mac80211.rst @@ -126,6 +126,9 @@ functions/definitions :functions: ieee80211_rx_status .. kernel-doc:: include/net/mac80211.h + :functions: mac80211_rx_encoding_flags + +.. kernel-doc:: include/net/mac80211.h :functions: mac80211_rx_flags .. kernel-doc:: include/net/mac80211.h diff --git a/Documentation/driver-api/component.rst b/Documentation/driver-api/component.rst new file mode 100644 index 000000000000..2da4a8f20607 --- /dev/null +++ b/Documentation/driver-api/component.rst @@ -0,0 +1,17 @@ +====================================== +Component Helper for Aggregate Drivers +====================================== + +.. kernel-doc:: drivers/base/component.c + :doc: overview + + +API +=== + +.. kernel-doc:: include/linux/component.h + :internal: + +.. kernel-doc:: drivers/base/component.c + :export: + diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst index d6763272e747..ae1e3d0394b0 100644 --- a/Documentation/driver-api/device_link.rst +++ b/Documentation/driver-api/device_link.rst @@ -1,6 +1,9 @@ .. |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_link: + ============ Device links ============ @@ -25,8 +28,8 @@ suspend/resume and shutdown ordering. Device links allow representation of such dependencies in the driver core. -In its standard form, a device link combines *both* dependency types: -It guarantees correct suspend/resume and shutdown ordering between a +In its standard or *managed* form, a device link combines *both* dependency +types: It guarantees correct suspend/resume and shutdown ordering between a "supplier" device and its "consumer" devices, and it guarantees driver presence on the supplier. The consumer devices are not probed before the supplier is bound to a driver, and they're unbound before the supplier @@ -59,18 +62,24 @@ device ``->probe`` callback or a boot-time PCI quirk. Another example for an inconsistent state would be a device link that represents a driver presence dependency, yet is added from the consumer's -``->probe`` callback while the supplier hasn't probed yet: Had the driver -core known about the device link earlier, it wouldn't have probed the +``->probe`` callback while the supplier hasn't started to probe yet: Had the +driver core known about the device link earlier, it wouldn't have probed the consumer in the first place. The onus is thus on the consumer to check presence of the supplier after adding the link, and defer probing on -non-presence. - -If a device link is added in the ``->probe`` callback of the supplier or -consumer driver, it is typically deleted in its ``->remove`` callback for -symmetry. That way, if the driver is compiled as a module, the device -link is added on module load and orderly deleted on unload. The same -restrictions that apply to device link addition (e.g. exclusion of a -parallel suspend/resume transition) apply equally to deletion. +non-presence. [Note that it is valid to create a link from the consumer's +``->probe`` callback while the supplier is still probing, but the consumer must +know that the supplier is functional already at the link creation time (that is +the case, for instance, if the consumer has just acquired some resources that +would not have been available had the supplier not been functional then).] + +If a device link with ``DL_FLAG_STATELESS`` set (i.e. a stateless device link) +is added in the ``->probe`` callback of the supplier or consumer driver, it is +typically deleted in its ``->remove`` callback for symmetry. That way, if the +driver is compiled as a module, the device link is added on module load and +orderly deleted on unload. The same restrictions that apply to device link +addition (e.g. exclusion of a parallel suspend/resume transition) apply equally +to deletion. Device links with ``DL_FLAG_STATELESS`` unset (i.e. managed +device links) are deleted automatically by the driver core. Several flags may be specified on device link addition, two of which have already been mentioned above: ``DL_FLAG_STATELESS`` to express that no @@ -80,25 +89,55 @@ integration is desired. Two other flags are specifically targeted at use cases where the device link is added from the consumer's ``->probe`` callback: ``DL_FLAG_RPM_ACTIVE`` -can be specified to runtime resume the supplier upon addition of the -device link. ``DL_FLAG_AUTOREMOVE_CONSUMER`` causes the device link to be -automatically purged when the consumer fails to probe or later unbinds. -This obviates the need to explicitly delete the link in the ``->remove`` -callback or in the error path of the ``->probe`` callback. +can be specified to runtime resume the supplier and prevent it from suspending +before the consumer is runtime suspended. ``DL_FLAG_AUTOREMOVE_CONSUMER`` +causes the device link to be automatically purged when the consumer fails to +probe or later unbinds. Similarly, when the device link is added from supplier's ``->probe`` callback, ``DL_FLAG_AUTOREMOVE_SUPPLIER`` causes the device link to be automatically purged when the supplier fails to probe or later unbinds. +If neither ``DL_FLAG_AUTOREMOVE_CONSUMER`` nor ``DL_FLAG_AUTOREMOVE_SUPPLIER`` +is set, ``DL_FLAG_AUTOPROBE_CONSUMER`` can be used to request the driver core +to probe for a driver for the consumer driver on the link automatically after +a driver has been bound to the supplier device. + +Note, however, that any combinations of ``DL_FLAG_AUTOREMOVE_CONSUMER``, +``DL_FLAG_AUTOREMOVE_SUPPLIER`` or ``DL_FLAG_AUTOPROBE_CONSUMER`` with +``DL_FLAG_STATELESS`` are invalid and cannot be used. + Limitations =========== -Driver authors should be aware that a driver presence dependency (i.e. when -``DL_FLAG_STATELESS`` is not specified on link addition) may cause probing of -the consumer to be deferred indefinitely. This can become a problem if the -consumer is required to probe before a certain initcall level is reached. -Worse, if the supplier driver is blacklisted or missing, the consumer will -never be probed. +Driver authors should be aware that a driver presence dependency for managed +device links (i.e. when ``DL_FLAG_STATELESS`` is not specified on link addition) +may cause probing of the consumer to be deferred indefinitely. This can become +a problem if the consumer is required to probe before a certain initcall level +is reached. Worse, if the supplier driver is blacklisted or missing, the +consumer will never be probed. + +Moreover, managed device links cannot be deleted directly. They are deleted +by the driver core when they are not necessary any more in accordance with the +``DL_FLAG_AUTOREMOVE_CONSUMER`` and ``DL_FLAG_AUTOREMOVE_SUPPLIER`` flags. +However, stateless device links (i.e. device links with ``DL_FLAG_STATELESS`` +set) are expected to be removed by whoever called :c:func:`device_link_add()` +to add them with the help of either :c:func:`device_link_del()` or +:c:func:`device_link_remove()`. + +Passing ``DL_FLAG_RPM_ACTIVE`` along with ``DL_FLAG_STATELESS`` to +:c:func:`device_link_add()` may cause the PM-runtime usage counter of the +supplier device to remain nonzero after a subsequent invocation of either +:c:func:`device_link_del()` or :c:func:`device_link_remove()` to remove the +device link returned by it. This happens if :c:func:`device_link_add()` is +called twice in a row for the same consumer-supplier pair without removing the +link between these calls, in which case allowing the PM-runtime usage counter +of the supplier to drop on an attempt to remove the link may cause it to be +suspended while the consumer is still PM-runtime-active and that has to be +avoided. [To work around this limitation it is sufficient to let the consumer +runtime suspend at least once, or call :c:func:`pm_runtime_set_suspended()` for +it with PM-runtime disabled, between the :c:func:`device_link_add()` and +:c:func:`device_link_del()` or :c:func:`device_link_remove()` calls.] Sometimes drivers depend on optional resources. They are able to operate in a degraded mode (reduced feature set or performance) when those resources @@ -282,4 +321,4 @@ API === .. kernel-doc:: drivers/base/core.c - :functions: device_link_add device_link_del + :functions: device_link_add device_link_del device_link_remove diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst index 7ce5e71c353e..8d81f1a7169b 100644 --- a/Documentation/driver-api/dmaengine/dmatest.rst +++ b/Documentation/driver-api/dmaengine/dmatest.rst @@ -11,6 +11,10 @@ This small document introduces how to test DMA drivers using dmatest module. capability of the following: DMA_MEMCPY (memory-to-memory), DMA_MEMSET (const-to-memory or memory-to-memory, when emulated), DMA_XOR, DMA_PQ. +.. note:: + In case of any related questions use the official mailing list + dmaengine@vger.kernel.org. + Part 1 - How to build the test module ===================================== @@ -26,28 +30,43 @@ Part 2 - When dmatest is built as a module Example of usage:: - % modprobe dmatest channel=dma0chan0 timeout=2000 iterations=1 run=1 + % modprobe dmatest timeout=2000 iterations=1 channel=dma0chan0 run=1 ...or:: % modprobe dmatest - % echo dma0chan0 > /sys/module/dmatest/parameters/channel % echo 2000 > /sys/module/dmatest/parameters/timeout % echo 1 > /sys/module/dmatest/parameters/iterations + % echo dma0chan0 > /sys/module/dmatest/parameters/channel % echo 1 > /sys/module/dmatest/parameters/run ...or on the kernel command line:: - dmatest.channel=dma0chan0 dmatest.timeout=2000 dmatest.iterations=1 dmatest.run=1 + dmatest.timeout=2000 dmatest.iterations=1 dmatest.channel=dma0chan0 dmatest.run=1 + +Example of multi-channel test usage: + % modprobe dmatest + % echo 2000 > /sys/module/dmatest/parameters/timeout + % echo 1 > /sys/module/dmatest/parameters/iterations + % echo dma0chan0 > /sys/module/dmatest/parameters/channel + % echo dma0chan1 > /sys/module/dmatest/parameters/channel + % echo dma0chan2 > /sys/module/dmatest/parameters/channel + % echo 1 > /sys/module/dmatest/parameters/run +Note: the channel parameter should always be the last parameter set prior to +running the test (setting run=1), this is because upon setting the channel +parameter, that specific channel is requested using the dmaengine and a thread +is created with the existing parameters. This thread is set as pending +and will be executed once run is set to 1. Any parameters set after the thread +is created are not applied. .. hint:: available channel list could be extracted by running the following command:: % ls -1 /sys/class/dma/ -Once started a message like "dmatest: Started 1 threads using dma0chan0" is -emitted. After that only test failure messages are reported until the test -stops. +Once started a message like " dmatest: Added 1 threads using dma0chan0" is +emitted. A thread for that specific channel is created and is now pending, the +pending thread is started once run is to 1. Note that running a new test will not stop any in progress test. @@ -112,3 +131,85 @@ Example:: The details of a data miscompare error are also emitted, but do not follow the above format. + +Part 5 - Handling channel allocation +==================================== + +Allocating Channels +------------------- + +Channels are required to be configured prior to starting the test run. +Attempting to run the test without configuring the channels will fail. + +Example:: + + % echo 1 > /sys/module/dmatest/parameters/run + dmatest: Could not start test, no channels configured + +Channels are registered using the "channel" parameter. Channels can be requested by their +name, once requested, the channel is registered and a pending thread is added to the test list. + +Example:: + + % echo dma0chan2 > /sys/module/dmatest/parameters/channel + dmatest: Added 1 threads using dma0chan2 + +More channels can be added by repeating the example above. +Reading back the channel parameter will return the name of last channel that was added successfully. + +Example:: + + % echo dma0chan1 > /sys/module/dmatest/parameters/channel + dmatest: Added 1 threads using dma0chan1 + % echo dma0chan2 > /sys/module/dmatest/parameters/channel + dmatest: Added 1 threads using dma0chan2 + % cat /sys/module/dmatest/parameters/channel + dma0chan2 + +Another method of requesting channels is to request a channel with an empty string, Doing so +will request all channels available to be tested: + +Example:: + + % echo "" > /sys/module/dmatest/parameters/channel + dmatest: Added 1 threads using dma0chan0 + dmatest: Added 1 threads using dma0chan3 + dmatest: Added 1 threads using dma0chan4 + dmatest: Added 1 threads using dma0chan5 + dmatest: Added 1 threads using dma0chan6 + dmatest: Added 1 threads using dma0chan7 + dmatest: Added 1 threads using dma0chan8 + +At any point during the test configuration, reading the "test_list" parameter will +print the list of currently pending tests. + +Example:: + + % cat /sys/module/dmatest/parameters/test_list + dmatest: 1 threads using dma0chan0 + dmatest: 1 threads using dma0chan3 + dmatest: 1 threads using dma0chan4 + dmatest: 1 threads using dma0chan5 + dmatest: 1 threads using dma0chan6 + dmatest: 1 threads using dma0chan7 + dmatest: 1 threads using dma0chan8 + +Note: Channels will have to be configured for each test run as channel configurations do not +carry across to the next test run. + +Releasing Channels +------------------- + +Channels can be freed by setting run to 0. + +Example:: + % echo dma0chan1 > /sys/module/dmatest/parameters/channel + dmatest: Added 1 threads using dma0chan1 + % cat /sys/class/dma/dma0chan1/in_use + 1 + % echo 0 > /sys/module/dmatest/parameters/run + % cat /sys/class/dma/dma0chan1/in_use + 0 + +Channels allocated by previous test runs are automatically freed when a new +channel is requested after completing a successful test run. diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst index 36c47b1e9824..a4ac54b5fd79 100644 --- a/Documentation/driver-api/firmware/other_interfaces.rst +++ b/Documentation/driver-api/firmware/other_interfaces.rst @@ -13,3 +13,33 @@ EDD Interfaces .. kernel-doc:: drivers/firmware/edd.c :internal: +Intel Stratix10 SoC Service Layer +--------------------------------- +Some features of the Intel Stratix10 SoC require a level of privilege +higher than the kernel is granted. Such secure features include +FPGA programming. In terms of the ARMv8 architecture, the kernel runs +at Exception Level 1 (EL1), access to the features requires +Exception Level 3 (EL3). + +The Intel Stratix10 SoC service layer provides an in kernel API for +drivers to request access to the secure features. The requests are queued +and processed one by one. ARM’s SMCCC is used to pass the execution +of the requests on to a secure monitor (EL3). + +.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h + :functions: stratix10_svc_command_code + +.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h + :functions: stratix10_svc_client_msg + +.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h + :functions: stratix10_svc_command_reconfig_payload + +.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h + :functions: stratix10_svc_cb_data + +.. kernel-doc:: include/linux/firmware/intel/stratix10-svc-client.h + :functions: stratix10_svc_client + +.. kernel-doc:: drivers/firmware/stratix10-svc.c + :export: diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst index 2c2aaca894bf..71c5a40da320 100644 --- a/Documentation/driver-api/fpga/fpga-bridge.rst +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -4,6 +4,12 @@ FPGA Bridge API to implement a new FPGA bridge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* struct :c:type:`fpga_bridge` — The FPGA Bridge structure +* struct :c:type:`fpga_bridge_ops` — Low level Bridge driver ops +* :c:func:`devm_fpga_bridge_create()` — Allocate and init a bridge struct +* :c:func:`fpga_bridge_register()` — Register a bridge +* :c:func:`fpga_bridge_unregister()` — Unregister a bridge + .. kernel-doc:: include/linux/fpga/fpga-bridge.h :functions: fpga_bridge @@ -11,39 +17,10 @@ API to implement a new FPGA bridge :functions: fpga_bridge_ops .. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_create - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_free + :functions: devm_fpga_bridge_create .. kernel-doc:: drivers/fpga/fpga-bridge.c :functions: fpga_bridge_register .. kernel-doc:: drivers/fpga/fpga-bridge.c :functions: fpga_bridge_unregister - -API to control an FPGA bridge -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You probably won't need these directly. FPGA regions should handle this. - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: of_fpga_bridge_get - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_get - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_put - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_get_to_list - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: of_fpga_bridge_get_to_list - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_enable - -.. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_disable diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index 82b6dbbd31cd..576f1945eacd 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -49,18 +49,14 @@ probe function calls fpga_mgr_register(), such as:: * them in priv */ - mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager", - &socfpga_fpga_ops, priv); + mgr = devm_fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); if (!mgr) return -ENOMEM; platform_set_drvdata(pdev, mgr); - ret = fpga_mgr_register(mgr); - if (ret) - fpga_mgr_free(mgr); - - return ret; + return fpga_mgr_register(mgr); } static int socfpga_fpga_remove(struct platform_device *pdev) @@ -102,67 +98,19 @@ The ops include a .state function which will determine the state the FPGA is in and return a code of type enum fpga_mgr_states. It doesn't result in a change in state. -How to write an image buffer to a supported FPGA ------------------------------------------------- - -Some sample code:: - - #include <linux/fpga/fpga-mgr.h> - - struct fpga_manager *mgr; - struct fpga_image_info *info; - int ret; - - /* - * Get a reference to FPGA manager. The manager is not locked, so you can - * hold onto this reference without it preventing programming. - * - * This example uses the device node of the manager. Alternatively, use - * fpga_mgr_get(dev) instead if you have the device. - */ - mgr = of_fpga_mgr_get(mgr_node); - - /* struct with information about the FPGA image to program. */ - info = fpga_image_info_alloc(dev); - - /* flags indicates whether to do full or partial reconfiguration */ - info->flags = FPGA_MGR_PARTIAL_RECONFIG; - - /* - * At this point, indicate where the image is. This is pseudo-code; you're - * going to use one of these three. - */ - if (image is in a scatter gather table) { - - info->sgt = [your scatter gather table] - - } else if (image is in a buffer) { - - info->buf = [your image buffer] - info->count = [image buffer size] - - } else if (image is in a firmware file) { - - info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL); - - } - - /* Get exclusive control of FPGA manager */ - ret = fpga_mgr_lock(mgr); - - /* Load the buffer to the FPGA */ - ret = fpga_mgr_buf_load(mgr, &info, buf, count); - - /* Release the FPGA manager */ - fpga_mgr_unlock(mgr); - fpga_mgr_put(mgr); - - /* Deallocate the image info if you're done with it */ - fpga_image_info_free(info); - API for implementing a new FPGA Manager driver ---------------------------------------------- +* ``fpga_mgr_states`` — Values for :c:member:`fpga_manager->state`. +* struct :c:type:`fpga_manager` — the FPGA manager struct +* struct :c:type:`fpga_manager_ops` — Low level FPGA manager driver ops +* :c:func:`devm_fpga_mgr_create` — Allocate and init a manager struct +* :c:func:`fpga_mgr_register` — Register an FPGA manager +* :c:func:`fpga_mgr_unregister` — Unregister an FPGA manager + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_mgr_states + .. kernel-doc:: include/linux/fpga/fpga-mgr.h :functions: fpga_manager @@ -170,56 +118,10 @@ API for implementing a new FPGA Manager driver :functions: fpga_manager_ops .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_create - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_free + :functions: devm_fpga_mgr_create .. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_unregister - -API for programming an FPGA ---------------------------- - -FPGA Manager flags - -.. kernel-doc:: include/linux/fpga/fpga-mgr.h - :doc: FPGA Manager flags - -.. kernel-doc:: include/linux/fpga/fpga-mgr.h - :functions: fpga_image_info - -.. kernel-doc:: include/linux/fpga/fpga-mgr.h - :functions: fpga_mgr_states - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_image_info_alloc - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_image_info_free - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: of_fpga_mgr_get - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_get - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_put - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_lock - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_unlock - -.. kernel-doc:: include/linux/fpga/fpga-mgr.h - :functions: fpga_mgr_states - -Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()` - -.. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_load diff --git a/Documentation/driver-api/fpga/fpga-programming.rst b/Documentation/driver-api/fpga/fpga-programming.rst new file mode 100644 index 000000000000..b5484df6ff0f --- /dev/null +++ b/Documentation/driver-api/fpga/fpga-programming.rst @@ -0,0 +1,107 @@ +In-kernel API for FPGA Programming +================================== + +Overview +-------- + +The in-kernel API for FPGA programming is a combination of APIs from +FPGA manager, bridge, and regions. The actual function used to +trigger FPGA programming is :c:func:`fpga_region_program_fpga()`. + +:c:func:`fpga_region_program_fpga()` uses functionality supplied by +the FPGA manager and bridges. It will: + + * lock the region's mutex + * lock the mutex of the region's FPGA manager + * build a list of FPGA bridges if a method has been specified to do so + * disable the bridges + * program the FPGA using info passed in :c:member:`fpga_region->info`. + * re-enable the bridges + * release the locks + +The struct fpga_image_info specifies what FPGA image to program. It is +allocated/freed by :c:func:`fpga_image_info_alloc()` and freed with +:c:func:`fpga_image_info_free()` + +How to program an FPGA using a region +------------------------------------- + +When the FPGA region driver probed, it was given a pointer to an FPGA manager +driver so it knows which manager to use. The region also either has a list of +bridges to control during programming or it has a pointer to a function that +will generate that list. Here's some sample code of what to do next:: + + #include <linux/fpga/fpga-mgr.h> + #include <linux/fpga/fpga-region.h> + + struct fpga_image_info *info; + int ret; + + /* + * First, alloc the struct with information about the FPGA image to + * program. + */ + info = fpga_image_info_alloc(dev); + if (!info) + return -ENOMEM; + + /* Set flags as needed, such as: */ + info->flags = FPGA_MGR_PARTIAL_RECONFIG; + + /* + * Indicate where the FPGA image is. This is pseudo-code; you're + * going to use one of these three. + */ + if (image is in a scatter gather table) { + + info->sgt = [your scatter gather table] + + } else if (image is in a buffer) { + + info->buf = [your image buffer] + info->count = [image buffer size] + + } else if (image is in a firmware file) { + + info->firmware_name = devm_kstrdup(dev, firmware_name, + GFP_KERNEL); + + } + + /* Add info to region and do the programming */ + region->info = info; + ret = fpga_region_program_fpga(region); + + /* Deallocate the image info if you're done with it */ + region->info = NULL; + fpga_image_info_free(info); + + if (ret) + return ret; + + /* Now enumerate whatever hardware has appeared in the FPGA. */ + +API for programming an FPGA +--------------------------- + +* :c:func:`fpga_region_program_fpga` — Program an FPGA +* :c:type:`fpga_image_info` — Specifies what FPGA image to program +* :c:func:`fpga_image_info_alloc()` — Allocate an FPGA image info struct +* :c:func:`fpga_image_info_free()` — Free an FPGA image info struct + +.. kernel-doc:: drivers/fpga/fpga-region.c + :functions: fpga_region_program_fpga + +FPGA Manager flags + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :doc: FPGA Manager flags + +.. kernel-doc:: include/linux/fpga/fpga-mgr.h + :functions: fpga_image_info + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_image_info_alloc + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_image_info_free diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst index f30333ce828e..0529b2d2231a 100644 --- a/Documentation/driver-api/fpga/fpga-region.rst +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -34,41 +34,6 @@ fpga_image_info including: * flags indicating specifics such as whether the image is for partial reconfiguration. -How to program an FPGA using a region -------------------------------------- - -First, allocate the info struct:: - - info = fpga_image_info_alloc(dev); - if (!info) - return -ENOMEM; - -Set flags as needed, i.e.:: - - info->flags |= FPGA_MGR_PARTIAL_RECONFIG; - -Point to your FPGA image, such as:: - - info->sgt = &sgt; - -Add info to region and do the programming:: - - region->info = info; - ret = fpga_region_program_fpga(region); - -:c:func:`fpga_region_program_fpga()` operates on info passed in the -fpga_image_info (region->info). This function will attempt to: - - * lock the region's mutex - * lock the region's FPGA manager - * build a list of FPGA bridges if a method has been specified to do so - * disable the bridges - * program the FPGA - * re-enable the bridges - * release the locks - -Then you will want to enumerate whatever hardware has appeared in the FPGA. - How to add a new FPGA region ---------------------------- @@ -77,26 +42,62 @@ An example of usage can be seen in the probe function of [#f2]_. .. [#f1] ../devicetree/bindings/fpga/fpga-region.txt .. [#f2] ../../drivers/fpga/of-fpga-region.c -API to program an FPGA ----------------------- - -.. kernel-doc:: drivers/fpga/fpga-region.c - :functions: fpga_region_program_fpga - API to add a new FPGA region ---------------------------- +* struct :c:type:`fpga_region` — The FPGA region struct +* :c:func:`devm_fpga_region_create` — Allocate and init a region struct +* :c:func:`fpga_region_register` — Register an FPGA region +* :c:func:`fpga_region_unregister` — Unregister an FPGA region + +The FPGA region's probe function will need to get a reference to the FPGA +Manager it will be using to do the programming. This usually would happen +during the region's probe function. + +* :c:func:`fpga_mgr_get` — Get a reference to an FPGA manager, raise ref count +* :c:func:`of_fpga_mgr_get` — Get a reference to an FPGA manager, raise ref count, + given a device node. +* :c:func:`fpga_mgr_put` — Put an FPGA manager + +The FPGA region will need to specify which bridges to control while programming +the FPGA. The region driver can build a list of bridges during probe time +(:c:member:`fpga_region->bridge_list`) or it can have a function that creates +the list of bridges to program just before programming +(:c:member:`fpga_region->get_bridges`). The FPGA bridge framework supplies the +following APIs to handle building or tearing down that list. + +* :c:func:`fpga_bridge_get_to_list` — Get a ref of an FPGA bridge, add it to a + list +* :c:func:`of_fpga_bridge_get_to_list` — Get a ref of an FPGA bridge, add it to a + list, given a device node +* :c:func:`fpga_bridges_put` — Given a list of bridges, put them + .. kernel-doc:: include/linux/fpga/fpga-region.h :functions: fpga_region .. kernel-doc:: drivers/fpga/fpga-region.c - :functions: fpga_region_create - -.. kernel-doc:: drivers/fpga/fpga-region.c - :functions: fpga_region_free + :functions: devm_fpga_region_create .. kernel-doc:: drivers/fpga/fpga-region.c :functions: fpga_region_register .. kernel-doc:: drivers/fpga/fpga-region.c :functions: fpga_region_unregister + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_get + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: of_fpga_mgr_get + +.. kernel-doc:: drivers/fpga/fpga-mgr.c + :functions: fpga_mgr_put + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridge_get_to_list + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: of_fpga_bridge_get_to_list + +.. kernel-doc:: drivers/fpga/fpga-bridge.c + :functions: fpga_bridges_put diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst index c51e5ebd544a..31a4773bd2e6 100644 --- a/Documentation/driver-api/fpga/index.rst +++ b/Documentation/driver-api/fpga/index.rst @@ -11,3 +11,5 @@ FPGA Subsystem fpga-mgr fpga-bridge fpga-region + fpga-programming + diff --git a/Documentation/driver-api/fpga/intro.rst b/Documentation/driver-api/fpga/intro.rst index 50d1cab84950..f54c7dabcc7d 100644 --- a/Documentation/driver-api/fpga/intro.rst +++ b/Documentation/driver-api/fpga/intro.rst @@ -44,7 +44,7 @@ FPGA Region ----------- If you are adding a new interface to the FPGA framework, add it on top -of an FPGA region to allow the most reuse of your interface. +of an FPGA region. The FPGA Region framework (fpga-region.c) associates managers and bridges as reconfigurable regions. A region may refer to the whole diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index a0f294e2e250..b37f3f7b8926 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -204,6 +204,7 @@ between a caller and a respective .get/set_multiple() callback of a GPIO chip. In order to qualify for fast bitmap processing, the array must meet the following requirements: + - pin hardware number of array member 0 must also be 0, - pin hardware numbers of consecutive array members which belong to the same chip as member 0 does must also match their array indexes. diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index a6c14ff0c54f..3043167fc557 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -135,7 +135,7 @@ This configuration is normally used as a way to achieve one of two things: - inverse wire-OR on an I/O line, for example a GPIO line, making it possible for any driving stage on the line to drive it low even if any other output to the same line is simultaneously driving it high. A special case of this - is driving the SCL and SCA lines of an I2C bus, which is by definition a + is driving the SCL and SDA lines of an I2C bus, which is by definition a wire-OR bus. Both usecases require that the line be equipped with a pull-up resistor. This @@ -434,7 +434,9 @@ try_module_get()). A GPIO driver can use the following functions instead to request and free descriptors without being pinned to the kernel forever:: struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, - const char *label) + u16 hwnum, + const char *label, + enum gpiod_flags flags) void gpiochip_free_own_desc(struct gpio_desc *desc) diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst index 5e9421e05f1d..9bc34ba697d9 100644 --- a/Documentation/driver-api/gpio/legacy.rst +++ b/Documentation/driver-api/gpio/legacy.rst @@ -690,11 +690,10 @@ and have the following read/write attributes: and if it has been configured to generate interrupts (see the description of "edge"), you can poll(2) on that file and poll(2) will return whenever the interrupt was triggered. If - you use poll(2), set the events POLLPRI and POLLERR. If you - use select(2), set the file descriptor in exceptfds. After - poll(2) returns, either lseek(2) to the beginning of the sysfs - file and read the new value or close the file and re-open it - to read the value. + you use poll(2), set the events POLLPRI. If you use select(2), + set the file descriptor in exceptfds. After poll(2) returns, + either lseek(2) to the beginning of the sysfs file and read the + new value or close the file and re-open it to read the value. "edge" ... reads as either "none", "rising", "falling", or "both". Write these strings to select the signal edge(s) diff --git a/Documentation/driver-api/i3c/device-driver-api.rst b/Documentation/driver-api/i3c/device-driver-api.rst new file mode 100644 index 000000000000..85bc3381cd3e --- /dev/null +++ b/Documentation/driver-api/i3c/device-driver-api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +I3C device driver API +===================== + +.. kernel-doc:: include/linux/i3c/device.h + +.. kernel-doc:: drivers/i3c/device.c diff --git a/Documentation/driver-api/i3c/index.rst b/Documentation/driver-api/i3c/index.rst new file mode 100644 index 000000000000..783d6dad054b --- /dev/null +++ b/Documentation/driver-api/i3c/index.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +I3C subsystem +============= + +.. toctree:: + + protocol + device-driver-api + master-driver-api diff --git a/Documentation/driver-api/i3c/master-driver-api.rst b/Documentation/driver-api/i3c/master-driver-api.rst new file mode 100644 index 000000000000..332552b28358 --- /dev/null +++ b/Documentation/driver-api/i3c/master-driver-api.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +I3C master controller driver API +================================ + +.. kernel-doc:: drivers/i3c/master.c + +.. kernel-doc:: include/linux/i3c/master.h diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst new file mode 100644 index 000000000000..dae3b6d32c6b --- /dev/null +++ b/Documentation/driver-api/i3c/protocol.rst @@ -0,0 +1,203 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +I3C protocol +============ + +Disclaimer +========== + +This chapter will focus on aspects that matter to software developers. For +everything hardware related (like how things are transmitted on the bus, how +collisions are prevented, ...) please have a look at the I3C specification. + +This document is just a brief introduction to the I3C protocol and the concepts +it brings to the table. If you need more information, please refer to the MIPI +I3C specification (can be downloaded here +http://resources.mipi.org/mipi-i3c-v1-download). + +Introduction +============ + +The I3C (pronounced 'eye-three-see') is a MIPI standardized protocol designed +to overcome I2C limitations (limited speed, external signals needed for +interrupts, no automatic detection of the devices connected to the bus, ...) +while remaining power-efficient. + +I3C Bus +======= + +An I3C bus is made of several I3C devices and possibly some I2C devices as +well, but let's focus on I3C devices for now. + +An I3C device on the I3C bus can have one of the following roles: + +* Master: the device is driving the bus. It's the one in charge of initiating + transactions or deciding who is allowed to talk on the bus (slave generated + events are possible in I3C, see below). +* Slave: the device acts as a slave, and is not able to send frames to another + slave on the bus. The device can still send events to the master on + its own initiative if the master allowed it. + +I3C is a multi-master protocol, so there might be several masters on a bus, +though only one device can act as a master at a given time. In order to gain +bus ownership, a master has to follow a specific procedure. + +Each device on the I3C bus has to be assigned a dynamic address to be able to +communicate. Until this is done, the device should only respond to a limited +set of commands. If it has a static address (also called legacy I2C address), +the device can reply to I2C transfers. + +In addition to these per-device addresses, the protocol defines a broadcast +address in order to address all devices on the bus. + +Once a dynamic address has been assigned to a device, this address will be used +for any direct communication with the device. Note that even after being +assigned a dynamic address, the device should still process broadcast messages. + +I3C Device discovery +==================== + +The I3C protocol defines a mechanism to automatically discover devices present +on the bus, their capabilities and the functionalities they provide. In this +regard I3C is closer to a discoverable bus like USB than it is to I2C or SPI. + +The discovery mechanism is called DAA (Dynamic Address Assignment), because it +not only discovers devices but also assigns them a dynamic address. + +During DAA, each I3C device reports 3 important things: + +* BCR: Bus Characteristic Register. This 8-bit register describes the device bus + related capabilities +* DCR: Device Characteristic Register. This 8-bit register describes the + functionalities provided by the device +* Provisional ID: A 48-bit unique identifier. On a given bus there should be no + Provisional ID collision, otherwise the discovery mechanism may fail. + +I3C slave events +================ + +The I3C protocol allows slaves to generate events on their own, and thus allows +them to take temporary control of the bus. + +This mechanism is called IBI for In Band Interrupts, and as stated in the name, +it allows devices to generate interrupts without requiring an external signal. + +During DAA, each device on the bus has been assigned an address, and this +address will serve as a priority identifier to determine who wins if 2 different +devices are generating an interrupt at the same moment on the bus (the lower the +dynamic address the higher the priority). + +Masters are allowed to inhibit interrupts if they want to. This inhibition +request can be broadcast (applies to all devices) or sent to a specific +device. + +I3C Hot-Join +============ + +The Hot-Join mechanism is similar to USB hotplug. This mechanism allows +slaves to join the bus after it has been initialized by the master. + +This covers the following use cases: + +* the device is not powered when the bus is probed +* the device is hotplugged on the bus through an extension board + +This mechanism is relying on slave events to inform the master that a new +device joined the bus and is waiting for a dynamic address. + +The master is then free to address the request as it wishes: ignore it or +assign a dynamic address to the slave. + +I3C transfer types +================== + +If you omit SMBus (which is just a standardization on how to access registers +exposed by I2C devices), I2C has only one transfer type. + +I3C defines 3 different classes of transfer in addition to I2C transfers which +are here for backward compatibility with I2C devices. + +I3C CCC commands +---------------- + +CCC (Common Command Code) commands are meant to be used for anything that is +related to bus management and all features that are common to a set of devices. + +CCC commands contain an 8-bit CCC ID describing the command that is executed. +The MSB of this ID specifies whether this is a broadcast command (bit7 = 0) or a +unicast one (bit7 = 1). + +The command ID can be followed by a payload. Depending on the command, this +payload is either sent by the master sending the command (write CCC command), +or sent by the slave receiving the command (read CCC command). Of course, read +accesses only apply to unicast commands. +Note that, when sending a CCC command to a specific device, the device address +is passed in the first byte of the payload. + +The payload length is not explicitly passed on the bus, and should be extracted +from the CCC ID. + +Note that vendors can use a dedicated range of CCC IDs for their own commands +(0x61-0x7f and 0xe0-0xef). + +I3C Private SDR transfers +------------------------- + +Private SDR (Single Data Rate) transfers should be used for anything that is +device specific and does not require high transfer speed. + +It is the equivalent of I2C transfers but in the I3C world. Each transfer is +passed the device address (dynamic address assigned during DAA), a payload +and a direction. + +The only difference with I2C is that the transfer is much faster (typical clock +frequency is 12.5MHz). + +I3C HDR commands +---------------- + +HDR commands should be used for anything that is device specific and requires +high transfer speed. + +The first thing attached to an HDR command is the HDR mode. There are currently +3 different modes defined by the I3C specification (refer to the specification +for more details): + +* HDR-DDR: Double Data Rate mode +* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices +* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices + +When sending an HDR command, the whole bus has to enter HDR mode, which is done +using a broadcast CCC command. +Once the bus has entered a specific HDR mode, the master sends the HDR command. +An HDR command is made of: + +* one 16-bits command word in big endian +* N 16-bits data words in big endian + +Those words may be wrapped with specific preambles/post-ambles which depend on +the chosen HDR mode and are detailed here (see the specification for more +details). + +The 16-bits command word is made of: + +* bit[15]: direction bit, read is 1, write is 0 +* bit[14:8]: command code. Identifies the command being executed, the amount of + data words and their meaning +* bit[7:1]: I3C address of the device this command is addressed to +* bit[0]: reserved/parity-bit + +Backward compatibility with I2C devices +======================================= + +The I3C protocol has been designed to be backward compatible with I2C devices. +This backward compatibility allows one to connect a mix of I2C and I3C devices +on the same bus, though, in order to be really efficient, I2C devices should +be equipped with 50 ns spike filters. + +I2C devices can't be discovered like I3C ones and have to be statically +declared. In order to let the master know what these devices are capable of +(both in terms of bus related limitations and functionalities), the software +has to provide some information, which is done through the LVR (Legacy I2C +Virtual Register). diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 909f991b4c0d..c0b600ed9961 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -22,6 +22,7 @@ available subsections can be seen below. device_connection dma-buf device_link + component message-based sound frame-buffer @@ -33,6 +34,7 @@ available subsections can be seen below. pci/index spi i2c + i3c/index hsi edac scsi diff --git a/Documentation/driver-api/pci/p2pdma.rst b/Documentation/driver-api/pci/p2pdma.rst index 4c577fa7bef9..6d85b5a2598d 100644 --- a/Documentation/driver-api/pci/p2pdma.rst +++ b/Documentation/driver-api/pci/p2pdma.rst @@ -49,7 +49,7 @@ For example, in the NVMe Target Copy Offload implementation: in that it exposes any CMB (Controller Memory Buffer) as a P2P memory resource (provider), it accepts P2P memory pages as buffers in requests to be used directly (client) and it can also make use of the CMB as - submission queue entries (orchastrator). + submission queue entries (orchestrator). * The RDMA driver is a client in this arrangement so that an RNIC can DMA directly to the memory exposed by the NVMe device. * The NVMe Target driver (nvmet) can orchestrate the data from the RNIC @@ -111,7 +111,7 @@ that's compatible with all clients using :c:func:`pci_p2pmem_find()`. If more than one provider is supported, the one nearest to all the clients will be chosen first. If more than one provider is an equal distance away, the one returned will be chosen at random (it is not an arbitrary but -truely random). This function returns the PCI device to use for the provider +truly random). This function returns the PCI device to use for the provider with a reference taken and therefore when it's no longer needed it should be returned with pci_dev_put(). diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst new file mode 100644 index 000000000000..5842ab621a58 --- /dev/null +++ b/Documentation/driver-api/pm/cpuidle.rst @@ -0,0 +1,282 @@ +.. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` +.. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>` +.. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>` +.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` + +======================== +CPU Idle Time Management +======================== + +:: + + Copyright (c) 2019 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> + + +CPU Idle Time Management Subsystem +================================== + +Every time one of the logical CPUs in the system (the entities that appear to +fetch and execute instructions: hardware threads, if present, or processor +cores) is idle after an interrupt or equivalent wakeup event, which means that +there are no tasks to run on it except for the special "idle" task associated +with it, there is an opportunity to save energy for the processor that it +belongs to. That can be done by making the idle logical CPU stop fetching +instructions from memory and putting some of the processor's functional units +depended on by it into an idle state in which they will draw less power. + +However, there may be multiple different idle states that can be used in such a +situation in principle, so it may be necessary to find the most suitable one +(from the kernel perspective) and ask the processor to use (or "enter") that +particular idle state. That is the role of the CPU idle time management +subsystem in the kernel, called ``CPUIdle``. + +The design of ``CPUIdle`` is modular and based on the code duplication avoidance +principle, so the generic code that in principle need not depend on the hardware +or platform design details in it is separate from the code that interacts with +the hardware. It generally is divided into three categories of functional +units: *governors* responsible for selecting idle states to ask the processor +to enter, *drivers* that pass the governors' decisions on to the hardware and +the *core* providing a common framework for them. + + +CPU Idle Time Governors +======================= + +A CPU idle time (``CPUIdle``) governor is a bundle of policy code invoked when +one of the logical CPUs in the system turns out to be idle. Its role is to +select an idle state to ask the processor to enter in order to save some energy. + +``CPUIdle`` governors are generic and each of them can be used on any hardware +platform that the Linux kernel can run on. For this reason, data structures +operated on by them cannot depend on any hardware architecture or platform +design details as well. + +The governor itself is represented by a |struct cpuidle_governor| object +containing four callback pointers, :c:member:`enable`, :c:member:`disable`, +:c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described +below, and a name (string) used for identifying it. + +For the governor to be available at all, that object needs to be registered +with the ``CPUIdle`` core by calling :c:func:`cpuidle_register_governor()` with +a pointer to it passed as the argument. If successful, that causes the core to +add the governor to the global list of available governors and, if it is the +only one in the list (that is, the list was empty before) or the value of its +:c:member:`rating` field is greater than the value of that field for the +governor currently in use, or the name of the new governor was passed to the +kernel as the value of the ``cpuidle.governor=`` command line parameter, the new +governor will be used from that point on (there can be only one ``CPUIdle`` +governor in use at a time). Also, if ``cpuidle_sysfs_switch`` is passed to the +kernel in the command line, user space can choose the ``CPUIdle`` governor to +use at run time via ``sysfs``. + +Once registered, ``CPUIdle`` governors cannot be unregistered, so it is not +practical to put them into loadable kernel modules. + +The interface between ``CPUIdle`` governors and the core consists of four +callbacks: + +:c:member:`enable` + :: + + int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); + + The role of this callback is to prepare the governor for handling the + (logical) CPU represented by the |struct cpuidle_device| object pointed + to by the ``dev`` argument. The |struct cpuidle_driver| object pointed + to by the ``drv`` argument represents the ``CPUIdle`` driver to be used + with that CPU (among other things, it should contain the list of + |struct cpuidle_state| objects representing idle states that the + processor holding the given CPU can be asked to enter). + + It may fail, in which case it is expected to return a negative error + code, and that causes the kernel to run the architecture-specific + default code for idle CPUs on the CPU in question instead of ``CPUIdle`` + until the ``->enable()`` governor callback is invoked for that CPU + again. + +:c:member:`disable` + :: + + void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); + + Called to make the governor stop handling the (logical) CPU represented + by the |struct cpuidle_device| object pointed to by the ``dev`` + argument. + + It is expected to reverse any changes made by the ``->enable()`` + callback when it was last invoked for the target CPU, free all memory + allocated by that callback and so on. + +:c:member:`select` + :: + + int (*select) (struct cpuidle_driver *drv, struct cpuidle_device *dev, + bool *stop_tick); + + Called to select an idle state for the processor holding the (logical) + CPU represented by the |struct cpuidle_device| object pointed to by the + ``dev`` argument. + + The list of idle states to take into consideration is represented by the + :c:member:`states` array of |struct cpuidle_state| objects held by the + |struct cpuidle_driver| object pointed to by the ``drv`` argument (which + represents the ``CPUIdle`` driver to be used with the CPU at hand). The + value returned by this callback is interpreted as an index into that + array (unless it is a negative error code). + + The ``stop_tick`` argument is used to indicate whether or not to stop + the scheduler tick before asking the processor to enter the selected + idle state. When the ``bool`` variable pointed to by it (which is set + to ``true`` before invoking this callback) is cleared to ``false``, the + processor will be asked to enter the selected idle state without + stopping the scheduler tick on the given CPU (if the tick has been + stopped on that CPU already, however, it will not be restarted before + asking the processor to enter the idle state). + + This callback is mandatory (i.e. the :c:member:`select` callback pointer + in |struct cpuidle_governor| must not be ``NULL`` for the registration + of the governor to succeed). + +:c:member:`reflect` + :: + + void (*reflect) (struct cpuidle_device *dev, int index); + + Called to allow the governor to evaluate the accuracy of the idle state + selection made by the ``->select()`` callback (when it was invoked last + time) and possibly use the result of that to improve the accuracy of + idle state selections in the future. + +In addition, ``CPUIdle`` governors are required to take power management +quality of service (PM QoS) constraints on the processor wakeup latency into +account when selecting idle states. In order to obtain the current effective +PM QoS wakeup latency constraint for a given CPU, a ``CPUIdle`` governor is +expected to pass the number of the CPU to +:c:func:`cpuidle_governor_latency_req()`. Then, the governor's ``->select()`` +callback must not return the index of an indle state whose +:c:member:`exit_latency` value is greater than the number returned by that +function. + + +CPU Idle Time Management Drivers +================================ + +CPU idle time management (``CPUIdle``) drivers provide an interface between the +other parts of ``CPUIdle`` and the hardware. + +First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array +of |struct cpuidle_state| objects included in the |struct cpuidle_driver| object +representing it. Going forward this array will represent the list of available +idle states that the processor hardware can be asked to enter shared by all of +the logical CPUs handled by the given driver. + +The entries in the :c:member:`states` array are expected to be sorted by the +value of the :c:member:`target_residency` field in |struct cpuidle_state| in +the ascending order (that is, index 0 should correspond to the idle state with +the minimum value of :c:member:`target_residency`). [Since the +:c:member:`target_residency` value is expected to reflect the "depth" of the +idle state represented by the |struct cpuidle_state| object holding it, this +sorting order should be the same as the ascending sorting order by the idle +state "depth".] + +Three fields in |struct cpuidle_state| are used by the existing ``CPUIdle`` +governors for computations related to idle state selection: + +:c:member:`target_residency` + Minimum time to spend in this idle state including the time needed to + enter it (which may be substantial) to save more energy than could + be saved by staying in a shallower idle state for the same amount of + time, in microseconds. + +:c:member:`exit_latency` + Maximum time it will take a CPU asking the processor to enter this idle + state to start executing the first instruction after a wakeup from it, + in microseconds. + +:c:member:`flags` + Flags representing idle state properties. Currently, governors only use + the ``CPUIDLE_FLAG_POLLING`` flag which is set if the given object + does not represent a real idle state, but an interface to a software + "loop" that can be used in order to avoid asking the processor to enter + any idle state at all. [There are other flags used by the ``CPUIdle`` + core in special situations.] + +The :c:member:`enter` callback pointer in |struct cpuidle_state|, which must not +be ``NULL``, points to the routine to execute in order to ask the processor to +enter this particular idle state: + +:: + + void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv, + int index); + +The first two arguments of it point to the |struct cpuidle_device| object +representing the logical CPU running this callback and the +|struct cpuidle_driver| object representing the driver itself, respectively, +and the last one is an index of the |struct cpuidle_state| entry in the driver's +:c:member:`states` array representing the idle state to ask the processor to +enter. + +The analogous ``->enter_s2idle()`` callback in |struct cpuidle_state| is used +only for implementing the suspend-to-idle system-wide power management feature. +The difference between in and ``->enter()`` is that it must not re-enable +interrupts at any point (even temporarily) or attempt to change the states of +clock event devices, which the ``->enter()`` callback may do sometimes. + +Once the :c:member:`states` array has been populated, the number of valid +entries in it has to be stored in the :c:member:`state_count` field of the +|struct cpuidle_driver| object representing the driver. Moreover, if any +entries in the :c:member:`states` array represent "coupled" idle states (that +is, idle states that can only be asked for if multiple related logical CPUs are +idle), the :c:member:`safe_state_index` field in |struct cpuidle_driver| needs +to be the index of an idle state that is not "coupled" (that is, one that can be +asked for if only one logical CPU is idle). + +In addition to that, if the given ``CPUIdle`` driver is only going to handle a +subset of logical CPUs in the system, the :c:member:`cpumask` field in its +|struct cpuidle_driver| object must point to the set (mask) of CPUs that will be +handled by it. + +A ``CPUIdle`` driver can only be used after it has been registered. If there +are no "coupled" idle state entries in the driver's :c:member:`states` array, +that can be accomplished by passing the driver's |struct cpuidle_driver| object +to :c:func:`cpuidle_register_driver()`. Otherwise, :c:func:`cpuidle_register()` +should be used for this purpose. + +However, it also is necessary to register |struct cpuidle_device| objects for +all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the +help of :c:func:`cpuidle_register_device()` after the driver has been registered +and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`, +does not do that automatically. For this reason, the drivers that use +:c:func:`cpuidle_register_driver()` to register themselves must also take care +of registering the |struct cpuidle_device| objects as needed, so it is generally +recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver +registration in all cases. + +The registration of a |struct cpuidle_device| object causes the ``CPUIdle`` +``sysfs`` interface to be created and the governor's ``->enable()`` callback to +be invoked for the logical CPU represented by it, so it must take place after +registering the driver that will handle the CPU in question. + +``CPUIdle`` drivers and |struct cpuidle_device| objects can be unregistered +when they are not necessary any more which allows some resources associated with +them to be released. Due to dependencies between them, all of the +|struct cpuidle_device| objects representing CPUs handled by the given +``CPUIdle`` driver must be unregistered, with the help of +:c:func:`cpuidle_unregister_device()`, before calling +:c:func:`cpuidle_unregister_driver()` to unregister the driver. Alternatively, +:c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver +along with all of the |struct cpuidle_device| objects representing CPUs handled +by it. + +``CPUIdle`` drivers can respond to runtime system configuration changes that +lead to modifications of the list of available processor idle states (which can +happen, for example, when the system's power source is switched from AC to +battery or the other way around). Upon a notification of such a change, +a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to +turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for +all of the |struct cpuidle_device| objects representing CPUs affected by that +change. Next, it can update its :c:member:`states` array in accordance with +the new configuration of the system, call :c:func:`cpuidle_enable_device()` for +all of the relevant |struct cpuidle_device| objects and invoke +:c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 1128705a5731..090c151aa86b 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -6,6 +6,8 @@ .. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>` .. |struct device| replace:: :c:type:`struct device <device>` +.. _driverapi_pm_devices: + ============================== Device Power Management Basics ============================== diff --git a/Documentation/driver-api/pm/index.rst b/Documentation/driver-api/pm/index.rst index 2f6d0e9cf6b7..56975c6bc789 100644 --- a/Documentation/driver-api/pm/index.rst +++ b/Documentation/driver-api/pm/index.rst @@ -1,9 +1,10 @@ -======================= -Device Power Management -======================= +=============================== +CPU and Device Power Management +=============================== .. toctree:: + cpuidle devices notifiers types diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst index 29121aa55fb9..26a6064503fd 100644 --- a/Documentation/driver-api/soundwire/stream.rst +++ b/Documentation/driver-api/soundwire/stream.rst @@ -101,6 +101,34 @@ interface. :: +--------------------+ | | +----------------+ +Example 5: Stereo Stream with L and R channel is rendered by 2 Masters, each +rendering one channel, and is received by two different Slaves, each +receiving one channel. Both Masters and both Slaves are using single port. :: + + +---------------+ Clock Signal +---------------+ + | Master +----------------------------------+ Slave | + | Interface | | Interface | + | 1 | | 1 | + | | Data Signal | | + | L +----------------------------------+ L | + | (Data) | Data Direction | (Data) | + +---------------+ +-----------------------> +---------------+ + + +---------------+ Clock Signal +---------------+ + | Master +----------------------------------+ Slave | + | Interface | | Interface | + | 2 | | 2 | + | | Data Signal | | + | R +----------------------------------+ R | + | (Data) | Data Direction | (Data) | + +---------------+ +-----------------------> +---------------+ + +Note: In multi-link cases like above, to lock, one would acquire a global +lock and then go on locking bus instances. But, in this case the caller +framework(ASoC DPCM) guarantees that stream operations on a card are +always serialized. So, there is no race condition and hence no need for +global lock. + SoundWire Stream Management flow ================================ @@ -174,6 +202,7 @@ per stream. From ASoC DPCM framework, this stream state maybe linked to .startup() operation. .. code-block:: c + int sdw_alloc_stream(char * stream_name); @@ -200,6 +229,7 @@ only be invoked once by respective Master(s) and Slave(s). From ASoC DPCM framework, this stream state is linked to .hw_params() operation. .. code-block:: c + int sdw_stream_add_master(struct sdw_bus * bus, struct sdw_stream_config * stream_config, struct sdw_ports_config * ports_config, @@ -245,6 +275,7 @@ stream. From ASoC DPCM framework, this stream state is linked to .prepare() operation. .. code-block:: c + int sdw_prepare_stream(struct sdw_stream_runtime * stream); @@ -274,6 +305,7 @@ stream. From ASoC DPCM framework, this stream state is linked to .trigger() start operation. .. code-block:: c + int sdw_enable_stream(struct sdw_stream_runtime * stream); SDW_STREAM_DISABLED @@ -301,6 +333,7 @@ per stream. From ASoC DPCM framework, this stream state is linked to .trigger() stop operation. .. code-block:: c + int sdw_disable_stream(struct sdw_stream_runtime * stream); @@ -325,6 +358,7 @@ per stream. From ASoC DPCM framework, this stream state is linked to .trigger() stop operation. .. code-block:: c + int sdw_deprepare_stream(struct sdw_stream_runtime * stream); @@ -349,6 +383,7 @@ all the Master(s) and Slave(s) associated with stream. From ASoC DPCM framework, this stream state is linked to .hw_free() operation. .. code-block:: c + int sdw_stream_remove_master(struct sdw_bus * bus, struct sdw_stream_runtime * stream); int sdw_stream_remove_slave(struct sdw_slave * slave, @@ -361,6 +396,7 @@ stream assigned as part of ALLOCATED state. In .shutdown() the data structure maintaining stream state are freed up. .. code-block:: c + void sdw_release_stream(struct sdw_stream_runtime * stream); Not Supported diff --git a/Documentation/driver-api/uio-howto.rst b/Documentation/driver-api/uio-howto.rst index fb2eb73be4a3..25f50eace28b 100644 --- a/Documentation/driver-api/uio-howto.rst +++ b/Documentation/driver-api/uio-howto.rst @@ -463,8 +463,8 @@ 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. +sure you're 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. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 8fe995a1ec94..cfa8797ea614 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -19,6 +19,7 @@ Linux USB API dwc3 writing_musb_glue_layer typec + typec_bus usb3-debug-port .. only:: subproject and html diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst index 48ff58095f11..201163d8c13e 100644 --- a/Documentation/driver-api/usb/typec.rst +++ b/Documentation/driver-api/usb/typec.rst @@ -1,3 +1,4 @@ +.. _typec: USB Type-C connector class ========================== diff --git a/Documentation/driver-api/usb/typec_bus.rst b/Documentation/driver-api/usb/typec_bus.rst index d5eec1715b5b..f47a69bff498 100644 --- a/Documentation/driver-api/usb/typec_bus.rst +++ b/Documentation/driver-api/usb/typec_bus.rst @@ -13,10 +13,10 @@ every alternate mode, so every alternate mode will need a custom driver. USB Type-C bus allows binding a driver to the discovered partner alternate modes by using the SVID and the mode number. -USB Type-C Connector Class provides a device for every alternate mode a port -supports, and separate device for every alternate mode the partner supports. -The drivers for the alternate modes are bound to the partner alternate mode -devices, and the port alternate mode devices must be handled by the port +:ref:`USB Type-C Connector Class <typec>` provides a device for every alternate +mode a port supports, and separate device for every alternate mode the partner +supports. The drivers for the alternate modes are bound to the partner alternate +mode devices, and the port alternate mode devices must be handled by the port drivers. When a new partner alternate mode device is registered, it is linked to the @@ -46,7 +46,7 @@ enter any modes on their own. ``->vdm`` is the most important callback in the operation callbacks vector. It will be used to deliver all the SVID specific commands from the partner to the alternate mode driver, and vice versa in case of port drivers. The drivers send -the SVID specific commands to each other using :c:func:`typec_altmode_vmd()`. +the SVID specific commands to each other using :c:func:`typec_altmode_vdm()`. If the communication with the partner using the SVID specific commands results in need to reconfigure the pins on the connector, the alternate mode driver @@ -67,15 +67,15 @@ Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB`` after the mode has been exited. An example of working definitions for SVID specific pin configurations would -look like this: +look like this:: -enum { - ALTMODEX_CONF_A = TYPEC_STATE_MODAL, - ALTMODEX_CONF_B, - ... -}; + enum { + ALTMODEX_CONF_A = TYPEC_STATE_MODAL, + ALTMODEX_CONF_B, + ... + }; -Helper macro ``TYPEC_MODAL_STATE()`` can also be used: +Helper macro ``TYPEC_MODAL_STATE()`` can also be used:: #define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0); #define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1); diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt index b577a45b93ea..c247b488a567 100644 --- a/Documentation/driver-model/bus.txt +++ b/Documentation/driver-model/bus.txt @@ -124,11 +124,11 @@ struct bus_attribute { ssize_t (*store)(struct bus_type *, const char * buf, size_t count); }; -Bus drivers can export attributes using the BUS_ATTR macro that works -similarly to the DEVICE_ATTR macro for devices. For example, a definition -like this: +Bus drivers can export attributes using the BUS_ATTR_RW macro that works +similarly to the DEVICE_ATTR_RW macro for devices. For example, a +definition like this: -static BUS_ATTR(debug,0644,show_debug,store_debug); +static BUS_ATTR_RW(debug); is equivalent to declaring: diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt index 43681ca0837f..b277cafce71e 100644 --- a/Documentation/driver-model/devres.txt +++ b/Documentation/driver-model/devres.txt @@ -132,6 +132,13 @@ devres. Complexity is shifted from less maintained low level drivers to better maintained higher layer. Also, as init failure path is shared with exit path, both can get more testing. +Note though that when converting current calls or assignments to +managed devm_* versions it is up to you to check if internal operations +like allocating memory, have failed. Managed resources pertains to the +freeing of these resources *only* - all other checks needed are still +on you. In some cases this may mean introducing checks that were not +necessary before moving to the managed devm_* calls. + 3. Devres group --------------- @@ -243,7 +250,6 @@ DMA dmaenginem_async_device_register() dmam_alloc_coherent() dmam_alloc_attrs() - dmam_declare_coherent_memory() dmam_free_coherent() dmam_pool_create() dmam_pool_destroy() @@ -254,8 +260,8 @@ GPIO devm_gpiod_get_index_optional() devm_gpiod_get_optional() devm_gpiod_put() + devm_gpiod_unhinge() devm_gpiochip_add_data() - devm_gpiochip_remove() devm_gpio_request() devm_gpio_request_one() devm_gpio_free() diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/README index 1e1057958dd3..955d667dc87e 100644 --- a/Documentation/early-userspace/README +++ b/Documentation/early-userspace/README @@ -52,7 +52,7 @@ user root (0). INITRAMFS_ROOT_GID can be set to a group ID that needs to be mapped to group root (0). A source file must be directives in the format required by the -usr/gen_init_cpio utility (run 'usr/gen_init_cpio --help' to get the +usr/gen_init_cpio utility (run 'usr/gen_init_cpio -h' to get the file format). The directives in the file will be passed directly to usr/gen_init_cpio. diff --git a/Documentation/fb/fbcon.txt b/Documentation/fb/fbcon.txt index 62af30511a95..60a5ec04e8f0 100644 --- a/Documentation/fb/fbcon.txt +++ b/Documentation/fb/fbcon.txt @@ -163,6 +163,14 @@ C. Boot options be preserved until there actually is some text is output to the console. This option causes fbcon to bind immediately to the fbdev device. +7. fbcon=logo-pos:<location> + + The only possible 'location' is 'center' (without quotes), and when + given, the bootup logo is moved from the default top-left corner + location to the center of the framebuffer. If more than one logo is + displayed due to multiple CPUs, the collected line of logos is moved + as a whole. + C. Attaching, Detaching and Unloading Before going on to how to attach, detach and unload the framebuffer console, an diff --git a/Documentation/features/core/cBPF-JIT/arch-support.txt b/Documentation/features/core/cBPF-JIT/arch-support.txt index 90459cdde314..8620c38d4db0 100644 --- a/Documentation/features/core/cBPF-JIT/arch-support.txt +++ b/Documentation/features/core/cBPF-JIT/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/core/eBPF-JIT/arch-support.txt b/Documentation/features/core/eBPF-JIT/arch-support.txt index c90a0382fe66..9ae6e8d0d10d 100644 --- a/Documentation/features/core/eBPF-JIT/arch-support.txt +++ b/Documentation/features/core/eBPF-JIT/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/core/generic-idle-thread/arch-support.txt b/Documentation/features/core/generic-idle-thread/arch-support.txt index 0ef6acdb991c..365df2c2ff0b 100644 --- a/Documentation/features/core/generic-idle-thread/arch-support.txt +++ b/Documentation/features/core/generic-idle-thread/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | ok | | h8300: | TODO | | hexagon: | ok | | ia64: | ok | diff --git a/Documentation/features/core/jump-labels/arch-support.txt b/Documentation/features/core/jump-labels/arch-support.txt index 27cbd63abfd2..7fc2e243dee9 100644 --- a/Documentation/features/core/jump-labels/arch-support.txt +++ b/Documentation/features/core/jump-labels/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | @@ -29,5 +30,5 @@ | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/core/tracehook/arch-support.txt b/Documentation/features/core/tracehook/arch-support.txt index f44c274e40ed..d344b99aae1e 100644 --- a/Documentation/features/core/tracehook/arch-support.txt +++ b/Documentation/features/core/tracehook/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | ok | + | csky: | ok | | h8300: | TODO | | hexagon: | ok | | ia64: | ok | diff --git a/Documentation/features/debug/KASAN/arch-support.txt b/Documentation/features/debug/KASAN/arch-support.txt index 282ecc8ea1da..304dcd461795 100644 --- a/Documentation/features/debug/KASAN/arch-support.txt +++ b/Documentation/features/debug/KASAN/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/gcov-profile-all/arch-support.txt b/Documentation/features/debug/gcov-profile-all/arch-support.txt index 01b2b3004e0a..059d58a549c7 100644 --- a/Documentation/features/debug/gcov-profile-all/arch-support.txt +++ b/Documentation/features/debug/gcov-profile-all/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/kgdb/arch-support.txt b/Documentation/features/debug/kgdb/arch-support.txt index 3b4dff22329f..3e6b8f07d5d0 100644 --- a/Documentation/features/debug/kgdb/arch-support.txt +++ b/Documentation/features/debug/kgdb/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | ok | | hexagon: | ok | | ia64: | TODO | diff --git a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt index 7e963d0ae646..68f266944d5f 100644 --- a/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt +++ b/Documentation/features/debug/kprobes-on-ftrace/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/kprobes/arch-support.txt b/Documentation/features/debug/kprobes/arch-support.txt index 4ada027faf16..f4e45bd58fea 100644 --- a/Documentation/features/debug/kprobes/arch-support.txt +++ b/Documentation/features/debug/kprobes/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | diff --git a/Documentation/features/debug/kretprobes/arch-support.txt b/Documentation/features/debug/kretprobes/arch-support.txt index 044e13fcca5d..1d5651ef11f8 100644 --- a/Documentation/features/debug/kretprobes/arch-support.txt +++ b/Documentation/features/debug/kretprobes/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | diff --git a/Documentation/features/debug/optprobes/arch-support.txt b/Documentation/features/debug/optprobes/arch-support.txt index dce7669c918f..fb297a88f62c 100644 --- a/Documentation/features/debug/optprobes/arch-support.txt +++ b/Documentation/features/debug/optprobes/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/stackprotector/arch-support.txt b/Documentation/features/debug/stackprotector/arch-support.txt index 954ac1c95553..9999ea521f3e 100644 --- a/Documentation/features/debug/stackprotector/arch-support.txt +++ b/Documentation/features/debug/stackprotector/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/uprobes/arch-support.txt b/Documentation/features/debug/uprobes/arch-support.txt index 1a3f9d3229bf..1c577d0cfc7f 100644 --- a/Documentation/features/debug/uprobes/arch-support.txt +++ b/Documentation/features/debug/uprobes/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/debug/user-ret-profiler/arch-support.txt b/Documentation/features/debug/user-ret-profiler/arch-support.txt index 1d78d1069a5f..6bfa36b0e017 100644 --- a/Documentation/features/debug/user-ret-profiler/arch-support.txt +++ b/Documentation/features/debug/user-ret-profiler/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/io/dma-contiguous/arch-support.txt b/Documentation/features/io/dma-contiguous/arch-support.txt index 30c072d2b67c..eb28b5c97ca6 100644 --- a/Documentation/features/io/dma-contiguous/arch-support.txt +++ b/Documentation/features/io/dma-contiguous/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | ok | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/io/sg-chain/arch-support.txt b/Documentation/features/io/sg-chain/arch-support.txt deleted file mode 100644 index 6554f0372c3f..000000000000 --- a/Documentation/features/io/sg-chain/arch-support.txt +++ /dev/null @@ -1,33 +0,0 @@ -# -# Feature name: sg-chain -# Kconfig: ARCH_HAS_SG_CHAIN -# description: arch supports chained scatter-gather lists -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | TODO | - | arc: | ok | - | arm: | ok | - | arm64: | ok | - | c6x: | TODO | - | h8300: | TODO | - | hexagon: | TODO | - | ia64: | ok | - | m68k: | TODO | - | microblaze: | TODO | - | mips: | TODO | - | nds32: | TODO | - | nios2: | TODO | - | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | ok | - | riscv: | TODO | - | s390: | ok | - | sh: | TODO | - | sparc: | ok | - | um: | TODO | - | unicore32: | TODO | - | x86: | ok | - | xtensa: | TODO | - ----------------------- diff --git a/Documentation/features/locking/cmpxchg-local/arch-support.txt b/Documentation/features/locking/cmpxchg-local/arch-support.txt index 51704a2dc8d1..242ff5a6586e 100644 --- a/Documentation/features/locking/cmpxchg-local/arch-support.txt +++ b/Documentation/features/locking/cmpxchg-local/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/locking/lockdep/arch-support.txt b/Documentation/features/locking/lockdep/arch-support.txt index bd39c5edd460..941fd5b1094d 100644 --- a/Documentation/features/locking/lockdep/arch-support.txt +++ b/Documentation/features/locking/lockdep/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | TODO | diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index da7aff3bee0b..c683da198f31 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | ok | | c6x: | TODO | + | csky: | ok | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index 478e9101322c..e3080b82aefd 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt index e54b1f1a8091..7521d7500fbe 100644 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ b/Documentation/features/locking/rwsem-optimized/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | diff --git a/Documentation/features/perf/kprobes-event/arch-support.txt b/Documentation/features/perf/kprobes-event/arch-support.txt index 7331402d1887..d8278bf62b85 100644 --- a/Documentation/features/perf/kprobes-event/arch-support.txt +++ b/Documentation/features/perf/kprobes-event/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | ok | | ia64: | TODO | diff --git a/Documentation/features/perf/perf-regs/arch-support.txt b/Documentation/features/perf/perf-regs/arch-support.txt index 53feeee6cdad..687d049d9cee 100644 --- a/Documentation/features/perf/perf-regs/arch-support.txt +++ b/Documentation/features/perf/perf-regs/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/perf/perf-stackdump/arch-support.txt b/Documentation/features/perf/perf-stackdump/arch-support.txt index 16164348e0ea..90996e3d18a8 100644 --- a/Documentation/features/perf/perf-stackdump/arch-support.txt +++ b/Documentation/features/perf/perf-stackdump/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/sched/membarrier-sync-core/arch-support.txt b/Documentation/features/sched/membarrier-sync-core/arch-support.txt index c7858dd1ea8f..8a521a622966 100644 --- a/Documentation/features/sched/membarrier-sync-core/arch-support.txt +++ b/Documentation/features/sched/membarrier-sync-core/arch-support.txt @@ -34,6 +34,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/sched/numa-balancing/arch-support.txt b/Documentation/features/sched/numa-balancing/arch-support.txt index c68bb2c2cb62..350823692f28 100644 --- a/Documentation/features/sched/numa-balancing/arch-support.txt +++ b/Documentation/features/sched/numa-balancing/arch-support.txt @@ -11,6 +11,7 @@ | arm: | .. | | arm64: | ok | | c6x: | .. | + | csky: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | diff --git a/Documentation/features/seccomp/seccomp-filter/arch-support.txt b/Documentation/features/seccomp/seccomp-filter/arch-support.txt index d4271b493b41..4fe6c3c3be5c 100644 --- a/Documentation/features/seccomp/seccomp-filter/arch-support.txt +++ b/Documentation/features/seccomp/seccomp-filter/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/time/arch-tick-broadcast/arch-support.txt b/Documentation/features/time/arch-tick-broadcast/arch-support.txt index 83d9e68462bb..593536f7925b 100644 --- a/Documentation/features/time/arch-tick-broadcast/arch-support.txt +++ b/Documentation/features/time/arch-tick-broadcast/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/time/clockevents/arch-support.txt b/Documentation/features/time/clockevents/arch-support.txt index 3d4908fce6da..7a27157da408 100644 --- a/Documentation/features/time/clockevents/arch-support.txt +++ b/Documentation/features/time/clockevents/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | ok | + | csky: | ok | | h8300: | ok | | hexagon: | ok | | ia64: | TODO | diff --git a/Documentation/features/time/context-tracking/arch-support.txt b/Documentation/features/time/context-tracking/arch-support.txt index c29974afffaa..048bfb6d3872 100644 --- a/Documentation/features/time/context-tracking/arch-support.txt +++ b/Documentation/features/time/context-tracking/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/time/irq-time-acct/arch-support.txt b/Documentation/features/time/irq-time-acct/arch-support.txt index 8d73c463ec27..a14bbad8e948 100644 --- a/Documentation/features/time/irq-time-acct/arch-support.txt +++ b/Documentation/features/time/irq-time-acct/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | .. | diff --git a/Documentation/features/time/modern-timekeeping/arch-support.txt b/Documentation/features/time/modern-timekeeping/arch-support.txt index e7c6ea6b8fb3..2855dfe2464d 100644 --- a/Documentation/features/time/modern-timekeeping/arch-support.txt +++ b/Documentation/features/time/modern-timekeeping/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | ok | | c6x: | ok | + | csky: | ok | | h8300: | ok | | hexagon: | ok | | ia64: | ok | diff --git a/Documentation/features/time/virt-cpuacct/arch-support.txt b/Documentation/features/time/virt-cpuacct/arch-support.txt index 4646457461cf..fb0d0cab9cab 100644 --- a/Documentation/features/time/virt-cpuacct/arch-support.txt +++ b/Documentation/features/time/virt-cpuacct/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | diff --git a/Documentation/features/vm/ELF-ASLR/arch-support.txt b/Documentation/features/vm/ELF-ASLR/arch-support.txt index 1f71d090ff2c..adc25878d217 100644 --- a/Documentation/features/vm/ELF-ASLR/arch-support.txt +++ b/Documentation/features/vm/ELF-ASLR/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/vm/PG_uncached/arch-support.txt b/Documentation/features/vm/PG_uncached/arch-support.txt index fbd5aa463b0a..f05588f9e4b4 100644 --- a/Documentation/features/vm/PG_uncached/arch-support.txt +++ b/Documentation/features/vm/PG_uncached/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | ok | diff --git a/Documentation/features/vm/THP/arch-support.txt b/Documentation/features/vm/THP/arch-support.txt index 5d7ecc378f29..cdfe8925f881 100644 --- a/Documentation/features/vm/THP/arch-support.txt +++ b/Documentation/features/vm/THP/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | .. | + | csky: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | TODO | diff --git a/Documentation/features/vm/TLB/arch-support.txt b/Documentation/features/vm/TLB/arch-support.txt index f7af9678eb66..2bdd3b6cee3c 100644 --- a/Documentation/features/vm/TLB/arch-support.txt +++ b/Documentation/features/vm/TLB/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | TODO | | c6x: | .. | + | csky: | TODO | | h8300: | .. | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/vm/huge-vmap/arch-support.txt b/Documentation/features/vm/huge-vmap/arch-support.txt index d0713ccc7117..019131c5acce 100644 --- a/Documentation/features/vm/huge-vmap/arch-support.txt +++ b/Documentation/features/vm/huge-vmap/arch-support.txt @@ -11,6 +11,7 @@ | arm: | TODO | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/features/vm/ioremap_prot/arch-support.txt b/Documentation/features/vm/ioremap_prot/arch-support.txt index 8527601a3739..3a6b87de6a19 100644 --- a/Documentation/features/vm/ioremap_prot/arch-support.txt +++ b/Documentation/features/vm/ioremap_prot/arch-support.txt @@ -11,12 +11,13 @@ | arm: | TODO | | arm64: | TODO | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | | m68k: | TODO | | microblaze: | TODO | - | mips: | TODO | + | mips: | ok | | nds32: | TODO | | nios2: | TODO | | openrisc: | TODO | diff --git a/Documentation/features/vm/numa-memblock/arch-support.txt b/Documentation/features/vm/numa-memblock/arch-support.txt index 1a988052cd24..3004beb0fd71 100644 --- a/Documentation/features/vm/numa-memblock/arch-support.txt +++ b/Documentation/features/vm/numa-memblock/arch-support.txt @@ -11,6 +11,7 @@ | arm: | .. | | arm64: | ok | | c6x: | .. | + | csky: | .. | | h8300: | .. | | hexagon: | .. | | ia64: | ok | diff --git a/Documentation/features/vm/pte_special/arch-support.txt b/Documentation/features/vm/pte_special/arch-support.txt index a8378424bc98..2dc5df6a1cf5 100644 --- a/Documentation/features/vm/pte_special/arch-support.txt +++ b/Documentation/features/vm/pte_special/arch-support.txt @@ -11,6 +11,7 @@ | arm: | ok | | arm64: | ok | | c6x: | TODO | + | csky: | TODO | | h8300: | TODO | | hexagon: | TODO | | ia64: | TODO | diff --git a/Documentation/filesystems/caching/backend-api.txt b/Documentation/filesystems/caching/backend-api.txt index c0bd5677271b..c418280c915f 100644 --- a/Documentation/filesystems/caching/backend-api.txt +++ b/Documentation/filesystems/caching/backend-api.txt @@ -704,7 +704,7 @@ FS-Cache provides some utilities that a cache backend may make use of: void fscache_get_retrieval(struct fscache_retrieval *op); void fscache_put_retrieval(struct fscache_retrieval *op); - These two functions are used to retain a retrieval record whilst doing + These two functions are used to retain a retrieval record while doing asynchronous data retrieval and block allocation. diff --git a/Documentation/filesystems/caching/cachefiles.txt b/Documentation/filesystems/caching/cachefiles.txt index 748a1ae49e12..28aefcbb1442 100644 --- a/Documentation/filesystems/caching/cachefiles.txt +++ b/Documentation/filesystems/caching/cachefiles.txt @@ -45,7 +45,7 @@ filesystems are very specific in nature. CacheFiles creates a misc character device - "/dev/cachefiles" - that is used to communication with the daemon. Only one thing may have this open at once, -and whilst it is open, a cache is at least partially in existence. The daemon +and while it is open, a cache is at least partially in existence. The daemon opens this and sends commands down it to control the cache. CacheFiles is currently limited to a single cache. @@ -163,7 +163,7 @@ Do not mount other things within the cache as this will cause problems. The kernel module contains its own very cut-down path walking facility that ignores mountpoints, but the daemon can't avoid them. -Do not create, rename or unlink files and directories in the cache whilst the +Do not create, rename or unlink files and directories in the cache while the cache is active, as this may cause the state to become uncertain. Renaming files in the cache might make objects appear to be other objects (the diff --git a/Documentation/filesystems/caching/netfs-api.txt b/Documentation/filesystems/caching/netfs-api.txt index 2a6f7399c1f3..ba968e8f5704 100644 --- a/Documentation/filesystems/caching/netfs-api.txt +++ b/Documentation/filesystems/caching/netfs-api.txt @@ -382,7 +382,7 @@ MISCELLANEOUS OBJECT REGISTRATION An optional step is to request an object of miscellaneous type be created in the cache. This is almost identical to index cookie acquisition. The only difference is that the type in the object definition should be something other -than index type. Whilst the parent object could be an index, it's more likely +than index type. While the parent object could be an index, it's more likely it would be some other type of object such as a data file. xattr->cache = diff --git a/Documentation/filesystems/caching/operations.txt b/Documentation/filesystems/caching/operations.txt index a1c052cbba35..d8976c434718 100644 --- a/Documentation/filesystems/caching/operations.txt +++ b/Documentation/filesystems/caching/operations.txt @@ -171,7 +171,7 @@ Operations are used through the following procedure: (3) If the submitting thread wants to do the work itself, and has marked the operation with FSCACHE_OP_MYTHREAD, then it should monitor FSCACHE_OP_WAITING as described above and check the state of the object if - necessary (the object might have died whilst the thread was waiting). + necessary (the object might have died while the thread was waiting). When it has finished doing its processing, it should call fscache_op_complete() and fscache_put_operation() on it. diff --git a/Documentation/filesystems/ceph.txt b/Documentation/filesystems/ceph.txt index 8bf62240e10d..1177052701e1 100644 --- a/Documentation/filesystems/ceph.txt +++ b/Documentation/filesystems/ceph.txt @@ -151,6 +151,11 @@ Mount Options Report overall filesystem usage in statfs instead of using the root directory quota. + nocopyfrom + Don't use the RADOS 'copy-from' operation to perform remote object + copies. Currently, it's only used in copy_file_range, which will revert + to the default VFS implementation if this option is used. + More Information ================ diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/filesystems/cifs/TODO index 852499aed64b..66b3f54aa6dc 100644 --- a/Documentation/filesystems/cifs/TODO +++ b/Documentation/filesystems/cifs/TODO @@ -1,4 +1,4 @@ -Version 2.11 September 13, 2017 +Version 2.14 December 21, 2018 A Partial List of Missing Features ================================== @@ -7,7 +7,7 @@ Contributions are welcome. There are plenty of opportunities for visible, important contributions to this module. Here is a partial list of the known problems and missing features: -a) SMB3 (and SMB3.02) missing optional features: +a) SMB3 (and SMB3.1.1) missing optional features: - multichannel (started), integration with RDMA - directory leases (improved metadata caching), started (root dir only) - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl @@ -21,8 +21,9 @@ using Directory Leases, currently only the root file handle is cached longer d) quota support (needs minor kernel change since quota calls to make it to network filesystems or deviceless filesystems) -e) Compounding (in progress) to reduce number of roundtrips, and also -better optimize open to reduce redundant opens (using reference counts more). +e) Additional use cases where we use "compoounding" (e.g. open/query/close +and open/setinfo/close) to reduce the number of roundtrips, and also +open to reduce redundant opens (using deferred close and reference counts more). f) Finish inotify support so kde and gnome file list windows will autorefresh (partially complete by Asser). Needs minor kernel @@ -43,11 +44,13 @@ exists. Also better integration with winbind for resolving SID owners k) Add tools to take advantage of more smb3 specific ioctls and features (passthrough ioctl/fsctl for sending various SMB3 fsctls to the server -is in progress) +is in progress, and a passthrough query_info call is already implemented +in cifs.ko to allow smb3 info levels queries to be sent from userspace) l) encrypted file support -m) improved stats gathering, tools (perhaps integration with nfsometer?) +m) improved stats gathering tools (perhaps integration with nfsometer?) +to extend and make easier to use what is currently in /proc/fs/cifs/Stats n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed file attribute via chflags) and improve user space tools for managing and @@ -76,6 +79,9 @@ and simplify the code. v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added so far). +w) Add support for additional strong encryption types, and additional spnego +authentication mechanisms (see MS-SMB2) + KNOWN BUGS ==================================== See http://bugzilla.samba.org - search on product "CifsVFS" for @@ -102,3 +108,11 @@ and when signing is disabled to request larger read sizes (larger than negotiated size) and send larger write sizes to modern servers. 4) More exhaustively test against less common servers + +5) Continue to extend the smb3 "buildbot" which does automated xfstesting +against Windows, Samba and Azure currently - to add additional tests and +to allow the buildbot to execute the tests faster. + +6) Address various coverity warnings (most are not bugs per-se, but +the more warnings are addressed, the easier it is to spot real +problems that static analyzers will point out in the future). diff --git a/Documentation/filesystems/configfs/configfs.txt b/Documentation/filesystems/configfs/configfs.txt index 3828e85345ae..16e606c11f40 100644 --- a/Documentation/filesystems/configfs/configfs.txt +++ b/Documentation/filesystems/configfs/configfs.txt @@ -216,7 +216,7 @@ be called whenever userspace asks for a write(2) on the attribute. [struct configfs_bin_attribute] - struct configfs_attribute { + struct configfs_bin_attribute { struct configfs_attribute cb_attr; void *cb_private; size_t cb_max_size; diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt index bc393e0a22b8..6d2c0d340dea 100644 --- a/Documentation/filesystems/dax.txt +++ b/Documentation/filesystems/dax.txt @@ -75,7 +75,7 @@ exposure of uninitialized data through mmap. These filesystems may be used for inspiration: - ext2: see Documentation/filesystems/ext2.txt -- ext4: see Documentation/filesystems/ext4/ext4.rst +- ext4: see Documentation/filesystems/ext4/ - xfs: see Documentation/filesystems/xfs.txt diff --git a/Documentation/filesystems/ext2.txt b/Documentation/filesystems/ext2.txt index a45c9fc0747b..a19973a4dd1e 100644 --- a/Documentation/filesystems/ext2.txt +++ b/Documentation/filesystems/ext2.txt @@ -358,7 +358,7 @@ and are copied into the filesystem. If a transaction is incomplete at the time of the crash, then there is no guarantee of consistency for the blocks in that transaction so they are discarded (which means any filesystem changes they represent are also lost). -Check Documentation/filesystems/ext4/ext4.rst if you want to read more about +Check Documentation/filesystems/ext4/ if you want to read more about ext4 and journaling. References diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index cfbc18f0d9c9..3a7b60521b94 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -132,47 +132,28 @@ designed for this purpose be used, such as scrypt, PBKDF2, or Argon2. Per-file keys ------------- -Master keys are not used to encrypt file contents or names directly. -Instead, a unique key is derived for each encrypted file, including -each regular file, directory, and symbolic link. This has several -advantages: - -- In cryptosystems, the same key material should never be used for - different purposes. Using the master key as both an XTS key for - contents encryption and as a CTS-CBC key for filenames encryption - would violate this rule. -- Per-file keys simplify the choice of IVs (Initialization Vectors) - for contents encryption. Without per-file keys, to ensure IV - uniqueness both the inode and logical block number would need to be - encoded in the IVs. This would make it impossible to renumber - inodes, which e.g. ``resize2fs`` can do when resizing an ext4 - filesystem. With per-file keys, it is sufficient to encode just the - logical block number in the IVs. -- Per-file keys strengthen the encryption of filenames, where IVs are - reused out of necessity. With a unique key per directory, IV reuse - is limited to within a single directory. -- Per-file keys allow individual files to be securely erased simply by - securely erasing their keys. (Not yet implemented.) - -A KDF (Key Derivation Function) is used to derive per-file keys from -the master key. This is done instead of wrapping a randomly-generated -key for each file because it reduces the size of the encryption xattr, -which for some filesystems makes the xattr more likely to fit in-line -in the filesystem's inode table. With a KDF, only a 16-byte nonce is -required --- long enough to make key reuse extremely unlikely. A -wrapped key, on the other hand, would need to be up to 64 bytes --- -the length of an AES-256-XTS key. Furthermore, currently there is no -requirement to support unlocking a file with multiple alternative -master keys or to support rotating master keys. Instead, the master -keys may be wrapped in userspace, e.g. as done by the `fscrypt -<https://github.com/google/fscrypt>`_ tool. - -The current KDF encrypts the master key using the 16-byte nonce as an -AES-128-ECB key. The output is used as the derived key. If the -output is longer than needed, then it is truncated to the needed -length. Truncation is the norm for directories and symlinks, since -those use the CTS-CBC encryption mode which requires a key half as -long as that required by the XTS encryption mode. +Since each master key can protect many files, it is necessary to +"tweak" the encryption of each file so that the same plaintext in two +files doesn't map to the same ciphertext, or vice versa. In most +cases, fscrypt does this by deriving per-file keys. When a new +encrypted inode (regular file, directory, or symlink) is created, +fscrypt randomly generates a 16-byte nonce and stores it in the +inode's encryption xattr. Then, it uses a KDF (Key Derivation +Function) to derive the file's key from the master key and nonce. + +The Adiantum encryption mode (see `Encryption modes and usage`_) is +special, since it accepts longer IVs and is suitable for both contents +and filenames encryption. For it, a "direct key" option is offered +where the file's nonce is included in the IVs and the master key is +used for encryption directly. This improves performance; however, +users must not use the same master key for any other encryption mode. + +Below, the KDF and design considerations are described in more detail. + +The current KDF works by encrypting the master key with AES-128-ECB, +using the file's nonce as the AES key. The output is used as the +derived key. If the output is longer than needed, then it is +truncated to the needed length. Note: this KDF meets the primary security requirement, which is to produce unique derived keys that preserve the entropy of the master @@ -181,6 +162,20 @@ However, it is nonstandard and has some problems such as being reversible, so it is generally considered to be a mistake! It may be replaced with HKDF or another more standard KDF in the future. +Key derivation was chosen over key wrapping because wrapped keys would +require larger xattrs which would be less likely to fit in-line in the +filesystem's inode table, and there didn't appear to be any +significant advantages to key wrapping. In particular, currently +there is no requirement to support unlocking a file with multiple +alternative master keys or to support rotating master keys. Instead, +the master keys may be wrapped in userspace, e.g. as is done by the +`fscrypt <https://github.com/google/fscrypt>`_ tool. + +Including the inode number in the IVs was considered. However, it was +rejected as it would have prevented ext4 filesystems from being +resized, and by itself still wouldn't have been sufficient to prevent +the same key from being directly reused for both XTS and CTS-CBC. + Encryption modes and usage ========================== @@ -191,54 +186,80 @@ Currently, the following pairs of encryption modes are supported: - AES-256-XTS for contents and AES-256-CTS-CBC for filenames - AES-128-CBC for contents and AES-128-CTS-CBC for filenames +- Adiantum for both contents and filenames + +If unsure, you should use the (AES-256-XTS, AES-256-CTS-CBC) pair. -It is strongly recommended to use AES-256-XTS for contents encryption. AES-128-CBC was added only for low-powered embedded devices with crypto accelerators such as CAAM or CESA that do not support XTS. +Adiantum is a (primarily) stream cipher-based mode that is fast even +on CPUs without dedicated crypto instructions. It's also a true +wide-block mode, unlike XTS. It can also eliminate the need to derive +per-file keys. However, it depends on the security of two primitives, +XChaCha12 and AES-256, rather than just one. See the paper +"Adiantum: length-preserving encryption for entry-level processors" +(https://eprint.iacr.org/2018/720.pdf) for more details. To use +Adiantum, CONFIG_CRYPTO_ADIANTUM must be enabled. Also, fast +implementations of ChaCha and NHPoly1305 should be enabled, e.g. +CONFIG_CRYPTO_CHACHA20_NEON and CONFIG_CRYPTO_NHPOLY1305_NEON for ARM. + New encryption modes can be added relatively easily, without changes to individual filesystems. However, authenticated encryption (AE) modes are not currently supported because of the difficulty of dealing with ciphertext expansion. +Contents encryption +------------------- + For file contents, each filesystem block is encrypted independently. Currently, only the case where the filesystem block size is equal to -the system's page size (usually 4096 bytes) is supported. With the -XTS mode of operation (recommended), the logical block number within -the file is used as the IV. With the CBC mode of operation (not -recommended), ESSIV is used; specifically, the IV for CBC is the -logical block number encrypted with AES-256, where the AES-256 key is -the SHA-256 hash of the inode's data encryption key. - -For filenames, the full filename is encrypted at once. Because of the -requirements to retain support for efficient directory lookups and -filenames of up to 255 bytes, a constant initialization vector (IV) is -used. However, each encrypted directory uses a unique key, which -limits IV reuse to within a single directory. Note that IV reuse in -the context of CTS-CBC encryption means that when the original -filenames share a common prefix at least as long as the cipher block -size (16 bytes for AES), the corresponding encrypted filenames will -also share a common prefix. This is undesirable; it may be fixed in -the future by switching to an encryption mode that is a strong -pseudorandom permutation on arbitrary-length messages, e.g. the HEH -(Hash-Encrypt-Hash) mode. - -Since filenames are encrypted with the CTS-CBC mode of operation, the -plaintext and ciphertext filenames need not be multiples of the AES -block size, i.e. 16 bytes. However, the minimum size that can be -encrypted is 16 bytes, so shorter filenames are NUL-padded to 16 bytes -before being encrypted. In addition, to reduce leakage of filename -lengths via their ciphertexts, all filenames are NUL-padded to the -next 4, 8, 16, or 32-byte boundary (configurable). 32 is recommended -since this provides the best confidentiality, at the cost of making -directory entries consume slightly more space. Note that since NUL -(``\0``) is not otherwise a valid character in filenames, the padding -will never produce duplicate plaintexts. +the system's page size (usually 4096 bytes) is supported. + +Each block's IV is set to the logical block number within the file as +a little endian number, except that: + +- With CBC mode encryption, ESSIV is also used. Specifically, each IV + is encrypted with AES-256 where the AES-256 key is the SHA-256 hash + of the file's data encryption key. + +- In the "direct key" configuration (FS_POLICY_FLAG_DIRECT_KEY set in + the fscrypt_policy), the file's nonce is also appended to the IV. + Currently this is only allowed with the Adiantum encryption mode. + +Filenames encryption +-------------------- + +For filenames, each full filename is encrypted at once. Because of +the requirements to retain support for efficient directory lookups and +filenames of up to 255 bytes, the same IV is used for every filename +in a directory. + +However, each encrypted directory still uses a unique key; or +alternatively (for the "direct key" configuration) has the file's +nonce included in the IVs. Thus, IV reuse is limited to within a +single directory. + +With CTS-CBC, the IV reuse means that when the plaintext filenames +share a common prefix at least as long as the cipher block size (16 +bytes for AES), the corresponding encrypted filenames will also share +a common prefix. This is undesirable. Adiantum does not have this +weakness, as it is a wide-block encryption mode. + +All supported filenames encryption modes accept any plaintext length +>= 16 bytes; cipher block alignment is not required. However, +filenames shorter than 16 bytes are NUL-padded to 16 bytes before +being encrypted. In addition, to reduce leakage of filename lengths +via their ciphertexts, all filenames are NUL-padded to the next 4, 8, +16, or 32-byte boundary (configurable). 32 is recommended since this +provides the best confidentiality, at the cost of making directory +entries consume slightly more space. Note that since NUL (``\0``) is +not otherwise a valid character in filenames, the padding will never +produce duplicate plaintexts. Symbolic link targets are considered a type of filename and are -encrypted in the same way as filenames in directory entries. Each -symlink also uses a unique key; hence, the hardcoded IV is not a -problem for symlinks. +encrypted in the same way as filenames in directory entries, except +that IV reuse is not a problem as each symlink has its own inode. User API ======== @@ -272,9 +293,13 @@ This structure must be initialized as follows: and FS_ENCRYPTION_MODE_AES_256_CTS (4) for ``filenames_encryption_mode``. -- ``flags`` must be set to a value from ``<linux/fs.h>`` which +- ``flags`` must contain a value from ``<linux/fs.h>`` which identifies the amount of NUL-padding to use when encrypting filenames. If unsure, use FS_POLICY_FLAGS_PAD_32 (0x3). + In addition, if the chosen encryption modes are both + FS_ENCRYPTION_MODE_ADIANTUM, this can contain + FS_POLICY_FLAG_DIRECT_KEY to specify that the master key should be + used directly, without key derivation. - ``master_key_descriptor`` specifies how to find the master key in the keyring; see `Adding keys`_. It is up to userspace to choose a diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 46d1b1be3a51..605befab300b 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -359,3 +359,24 @@ encryption of files and directories. :maxdepth: 2 fscrypt + +Pathname lookup +=============== + + +This write-up is based on three articles published at lwn.net: + +- <https://lwn.net/Articles/649115/> Pathname lookup in Linux +- <https://lwn.net/Articles/649729/> RCU-walk: faster pathname lookup in Linux +- <https://lwn.net/Articles/650786/> A walk among the symlinks + +Written by Neil Brown with help from Al Viro and Jon Corbet. +It has subsequently been updated to reflect changes in the kernel +including: + +- per-directory parallel name lookup. + +.. toctree:: + :maxdepth: 2 + + path-lookup.rst diff --git a/Documentation/filesystems/nfs/rpc-cache.txt b/Documentation/filesystems/nfs/rpc-cache.txt index ebcaaee21616..c4dac829db0f 100644 --- a/Documentation/filesystems/nfs/rpc-cache.txt +++ b/Documentation/filesystems/nfs/rpc-cache.txt @@ -84,7 +84,7 @@ Creating a Cache A message from user space has arrived to fill out a cache entry. It is in 'buf' of length 'len'. cache_parse should parse this, find the item in the - cache with sunrpc_cache_lookup, and update the item + cache with sunrpc_cache_lookup_rcu, and update the item with sunrpc_cache_update. @@ -95,7 +95,7 @@ Creating a Cache Using a cache ------------- -To find a value in a cache, call sunrpc_cache_lookup passing a pointer +To find a value in a cache, call sunrpc_cache_lookup_rcu passing a pointer to the cache_head in a sample item with the 'key' fields filled in. This will be passed to ->match to identify the target entry. If no entry is found, a new entry will be create, added to the cache, and @@ -116,7 +116,7 @@ item does become valid, the deferred copy of the request will be revisited (->revisit). It is expected that this method will reschedule the request for processing. -The value returned by sunrpc_cache_lookup can also be passed to +The value returned by sunrpc_cache_lookup_rcu can also be passed to sunrpc_cache_update to set the content for the item. A second item is passed which should hold the content. If the item found by _lookup has valid data, then it is discarded and a new item is created. This diff --git a/Documentation/filesystems/overlayfs.txt b/Documentation/filesystems/overlayfs.txt index 51c136c821bf..eef7d9d259e8 100644 --- a/Documentation/filesystems/overlayfs.txt +++ b/Documentation/filesystems/overlayfs.txt @@ -286,6 +286,12 @@ pointed by REDIRECT. This should not be possible on local system as setting "trusted." xattrs will require CAP_SYS_ADMIN. But it should be possible for untrusted layers like from a pen drive. +Note: redirect_dir={off|nofollow|follow(*)} conflicts with metacopy=on, and +results in an error. + +(*) redirect_dir=follow only conflicts with metacopy=on if upperdir=... is +given. + Sharing and copying layers -------------------------- diff --git a/Documentation/filesystems/path-lookup.md b/Documentation/filesystems/path-lookup.rst index e2edd45c4bc0..9d6b68853f5b 100644 --- a/Documentation/filesystems/path-lookup.md +++ b/Documentation/filesystems/path-lookup.rst @@ -1,20 +1,6 @@ -<head> -<style> p { max-width:50em} ol, ul {max-width: 40em}</style> -</head> -Pathname lookup in Linux. -========================= - -This write-up is based on three articles published at lwn.net: - -- <https://lwn.net/Articles/649115/> Pathname lookup in Linux -- <https://lwn.net/Articles/649729/> RCU-walk: faster pathname lookup in Linux -- <https://lwn.net/Articles/650786/> A walk among the symlinks - -Written by Neil Brown with help from Al Viro and Jon Corbet. - -Introduction ------------- +Introduction to pathname lookup +=============================== The most obvious aspect of pathname lookup, which very little exploration is needed to discover, is that it is complex. There are @@ -32,58 +18,58 @@ distinctions we need to clarify first. There are two sorts of ... -------------------------- -[`openat()`]: http://man7.org/linux/man-pages/man2/openat.2.html +.. _openat: http://man7.org/linux/man-pages/man2/openat.2.html Pathnames (sometimes "file names"), used to identify objects in the filesystem, will be familiar to most readers. They contain two sorts -of elements: "slashes" that are sequences of one or more "`/`" +of elements: "slashes" that are sequences of one or more "``/``" characters, and "components" that are sequences of one or more -non-"`/`" characters. These form two kinds of paths. Those that +non-"``/``" characters. These form two kinds of paths. Those that start with slashes are "absolute" and start from the filesystem root. The others are "relative" and start from the current directory, or from some other location specified by a file descriptor given to a -"xxx`at`" system call such as "[`openat()`]". +"``XXXat``" system call such as `openat() <openat_>`_. -[`execveat()`]: http://man7.org/linux/man-pages/man2/execveat.2.html +.. _execveat: http://man7.org/linux/man-pages/man2/execveat.2.html It is tempting to describe the second kind as starting with a component, but that isn't always accurate: a pathname can lack both slashes and components, it can be empty, in other words. This is -generally forbidden in POSIX, but some of those "xxx`at`" system calls -in Linux permit it when the `AT_EMPTY_PATH` flag is given. For +generally forbidden in POSIX, but some of those "xxx``at``" system calls +in Linux permit it when the ``AT_EMPTY_PATH`` flag is given. For example, if you have an open file descriptor on an executable file you -can execute it by calling [`execveat()`] passing the file descriptor, -an empty path, and the `AT_EMPTY_PATH` flag. +can execute it by calling `execveat() <execveat_>`_ passing +the file descriptor, an empty path, and the ``AT_EMPTY_PATH`` flag. These paths can be divided into two sections: the final component and everything else. The "everything else" is the easy bit. In all cases it must identify a directory that already exists, otherwise an error -such as `ENOENT` or `ENOTDIR` will be reported. +such as ``ENOENT`` or ``ENOTDIR`` will be reported. The final component is not so simple. Not only do different system calls interpret it quite differently (e.g. some create it, some do not), but it might not even exist: neither the empty pathname nor the pathname that is just slashes have a final component. If it does -exist, it could be "`.`" or "`..`" which are handled quite differently +exist, it could be "``.``" or "``..``" which are handled quite differently from other components. -[POSIX]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 +.. _POSIX: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_12 -If a pathname ends with a slash, such as "`/tmp/foo/`" it might be +If a pathname ends with a slash, such as "``/tmp/foo/``" it might be tempting to consider that to have an empty final component. In many ways that would lead to correct results, but not always. In -particular, `mkdir()` and `rmdir()` each create or remove a directory named +particular, ``mkdir()`` and ``rmdir()`` each create or remove a directory named by the final component, and they are required to work with pathnames -ending in "`/`". According to [POSIX] +ending in "``/``". According to POSIX_ -> A pathname that contains at least one non- <slash> character and -> that ends with one or more trailing <slash> characters shall not -> be resolved successfully unless the last pathname component before -> the trailing <slash> characters names an existing directory or a -> directory entry that is to be created for a directory immediately -> after the pathname is resolved. + A pathname that contains at least one non- <slash> character and + that ends with one or more trailing <slash> characters shall not + be resolved successfully unless the last pathname component before + the trailing <slash> characters names an existing directory or a + directory entry that is to be created for a directory immediately + after the pathname is resolved. -The Linux pathname walking code (mostly in `fs/namei.c`) deals with +The Linux pathname walking code (mostly in ``fs/namei.c``) deals with all of these issues: breaking the path into components, handling the "everything else" quite separately from the final component, and checking that the trailing slash is not used where it isn't @@ -100,15 +86,15 @@ of the possible races are seen most clearly in the context of the "dcache" and an understanding of that is central to understanding pathname lookup. -More than just a cache. ------------------------ +More than just a cache +---------------------- The "dcache" caches information about names in each filesystem to make them quickly available for lookup. Each entry (known as a "dentry") contains three significant fields: a component name, a pointer to a parent dentry, and a pointer to the "inode" which contains further information about the object in that parent with -the given name. The inode pointer can be `NULL` indicating that the +the given name. The inode pointer can be ``NULL`` indicating that the name doesn't exist in the parent. While there can be linkage in the dentry of a directory to the dentries of the children, that linkage is not used for pathname lookup, and so will not be considered here. @@ -135,7 +121,7 @@ whether remote filesystems like NFS and 9P, or cluster filesystems like ocfs2 or cephfs. These filesystems allow the VFS to revalidate cached information, and must provide their own protection against awkward races. The VFS can detect these filesystems by the -`DCACHE_OP_REVALIDATE` flag being set in the dentry. +``DCACHE_OP_REVALIDATE`` flag being set in the dentry. REF-walk: simple concurrency management with refcounts and spinlocks -------------------------------------------------------------------- @@ -144,22 +130,23 @@ With all of those divisions carefully classified, we can now start looking at the actual process of walking along a path. In particular we will start with the handling of the "everything else" part of a pathname, and focus on the "REF-walk" approach to concurrency -management. This code is found in the `link_path_walk()` function, if -you ignore all the places that only run when "`LOOKUP_RCU`" +management. This code is found in the ``link_path_walk()`` function, if +you ignore all the places that only run when "``LOOKUP_RCU``" (indicating the use of RCU-walk) is set. -[Meet the Lockers]: https://lwn.net/Articles/453685/ +.. _Meet the Lockers: https://lwn.net/Articles/453685/ REF-walk is fairly heavy-handed with locks and reference counts. Not as heavy-handed as in the old "big kernel lock" days, but certainly not afraid of taking a lock when one is needed. It uses a variety of different concurrency controls. A background understanding of the various primitives is assumed, or can be gleaned from elsewhere such -as in [Meet the Lockers]. +as in `Meet the Lockers`_. The locking mechanisms used by REF-walk include: -### dentry->d_lockref ### +dentry->d_lockref +~~~~~~~~~~~~~~~~~ This uses the lockref primitive to provide both a spinlock and a reference count. The special-sauce of this primitive is that the @@ -168,49 +155,51 @@ with a single atomic memory operation. Holding a reference on a dentry ensures that the dentry won't suddenly be freed and used for something else, so the values in various fields -will behave as expected. It also protects the `->d_inode` reference +will behave as expected. It also protects the ``->d_inode`` reference to the inode to some extent. The association between a dentry and its inode is fairly permanent. For example, when a file is renamed, the dentry and inode move together to the new location. When a file is created the dentry will -initially be negative (i.e. `d_inode` is `NULL`), and will be assigned +initially be negative (i.e. ``d_inode`` is ``NULL``), and will be assigned to the new inode as part of the act of creation. When a file is deleted, this can be reflected in the cache either by -setting `d_inode` to `NULL`, or by removing it from the hash table +setting ``d_inode`` to ``NULL``, or by removing it from the hash table (described shortly) used to look up the name in the parent directory. If the dentry is still in use the second option is used as it is perfectly legal to keep using an open file after it has been deleted and having the dentry around helps. If the dentry is not otherwise in -use (i.e. if the refcount in `d_lockref` is one), only then will -`d_inode` be set to `NULL`. Doing it this way is more efficient for a +use (i.e. if the refcount in ``d_lockref`` is one), only then will +``d_inode`` be set to ``NULL``. Doing it this way is more efficient for a very common case. -So as long as a counted reference is held to a dentry, a non-`NULL` `->d_inode` +So as long as a counted reference is held to a dentry, a non-``NULL`` ``->d_inode`` value will never be changed. -### dentry->d_lock ### +dentry->d_lock +~~~~~~~~~~~~~~ -`d_lock` is a synonym for the spinlock that is part of `d_lockref` above. +``d_lock`` is a synonym for the spinlock that is part of ``d_lockref`` above. For our purposes, holding this lock protects against the dentry being -renamed or unlinked. In particular, its parent (`d_parent`), and its -name (`d_name`) cannot be changed, and it cannot be removed from the +renamed or unlinked. In particular, its parent (``d_parent``), and its +name (``d_name``) cannot be changed, and it cannot be removed from the dentry hash table. -When looking for a name in a directory, REF-walk takes `d_lock` on +When looking for a name in a directory, REF-walk takes ``d_lock`` on each candidate dentry that it finds in the hash table and then checks that the parent and name are correct. So it doesn't lock the parent while searching in the cache; it only locks children. -When looking for the parent for a given name (to handle "`..`"), -REF-walk can take `d_lock` to get a stable reference to `d_parent`, +When looking for the parent for a given name (to handle "``..``"), +REF-walk can take ``d_lock`` to get a stable reference to ``d_parent``, but it first tries a more lightweight approach. As seen in -`dget_parent()`, if a reference can be claimed on the parent, and if -subsequently `d_parent` can be seen to have not changed, then there is +``dget_parent()``, if a reference can be claimed on the parent, and if +subsequently ``d_parent`` can be seen to have not changed, then there is no need to actually take the lock on the child. -### rename_lock ### +rename_lock +~~~~~~~~~~~ Looking up a given name in a given directory involves computing a hash from the two values (the name and the dentry of the directory), @@ -224,71 +213,117 @@ happened to be looking at a dentry that was moved in this way, it might end up continuing the search down the wrong chain, and so miss out on part of the correct chain. -The name-lookup process (`d_lookup()`) does _not_ try to prevent this +The name-lookup process (``d_lookup()``) does _not_ try to prevent this from happening, but only to detect when it happens. -`rename_lock` is a seqlock that is updated whenever any dentry is -renamed. If `d_lookup` finds that a rename happened while it +``rename_lock`` is a seqlock that is updated whenever any dentry is +renamed. If ``d_lookup`` finds that a rename happened while it unsuccessfully scanned a chain in the hash table, it simply tries again. -### inode->i_mutex ### +inode->i_rwsem +~~~~~~~~~~~~~~ -`i_mutex` is a mutex that serializes all changes to a particular -directory. This ensures that, for example, an `unlink()` and a `rename()` +``i_rwsem`` is a read/write semaphore that serializes all changes to a particular +directory. This ensures that, for example, an ``unlink()`` and a ``rename()`` cannot both happen at the same time. It also keeps the directory stable while the filesystem is asked to look up a name that is not -currently in the dcache. +currently in the dcache or, optionally, when the list of entries in a +directory is being retrieved with ``readdir()``. -This has a complementary role to that of `d_lock`: `i_mutex` on a -directory protects all of the names in that directory, while `d_lock` +This has a complementary role to that of ``d_lock``: ``i_rwsem`` on a +directory protects all of the names in that directory, while ``d_lock`` on a name protects just one name in a directory. Most changes to the -dcache hold `i_mutex` on the relevant directory inode and briefly take -`d_lock` on one or more the dentries while the change happens. One +dcache hold ``i_rwsem`` on the relevant directory inode and briefly take +``d_lock`` on one or more the dentries while the change happens. One exception is when idle dentries are removed from the dcache due to -memory pressure. This uses `d_lock`, but `i_mutex` plays no role. +memory pressure. This uses ``d_lock``, but ``i_rwsem`` plays no role. -The mutex affects pathname lookup in two distinct ways. Firstly it -serializes lookup of a name in a directory. `walk_component()` uses -`lookup_fast()` first which, in turn, checks to see if the name is in the cache, -using only `d_lock` locking. If the name isn't found, then `walk_component()` -falls back to `lookup_slow()` which takes `i_mutex`, checks again that +The semaphore affects pathname lookup in two distinct ways. Firstly it +prevents changes during lookup of a name in a directory. ``walk_component()`` uses +``lookup_fast()`` first which, in turn, checks to see if the name is in the cache, +using only ``d_lock`` locking. If the name isn't found, then ``walk_component()`` +falls back to ``lookup_slow()`` which takes a shared lock on ``i_rwsem``, checks again that the name isn't in the cache, and then calls in to the filesystem to get a definitive answer. A new dentry will be added to the cache regardless of the result. Secondly, when pathname lookup reaches the final component, it will -sometimes need to take `i_mutex` before performing the last lookup so +sometimes need to take an exclusive lock on ``i_rwsem`` before performing the last lookup so that the required exclusion can be achieved. How path lookup chooses -to take, or not take, `i_mutex` is one of the +to take, or not take, ``i_rwsem`` is one of the issues addressed in a subsequent section. -### mnt->mnt_count ### - -`mnt_count` is a per-CPU reference counter on "`mount`" structures. +If two threads attempt to look up the same name at the same time - a +name that is not yet in the dcache - the shared lock on ``i_rwsem`` will +not prevent them both adding new dentries with the same name. As this +would result in confusion an extra level of interlocking is used, +based around a secondary hash table (``in_lookup_hashtable``) and a +per-dentry flag bit (``DCACHE_PAR_LOOKUP``). + +To add a new dentry to the cache while only holding a shared lock on +``i_rwsem``, a thread must call ``d_alloc_parallel()``. This allocates a +dentry, stores the required name and parent in it, checks if there +is already a matching dentry in the primary or secondary hash +tables, and if not, stores the newly allocated dentry in the secondary +hash table, with ``DCACHE_PAR_LOOKUP`` set. + +If a matching dentry was found in the primary hash table then that is +returned and the caller can know that it lost a race with some other +thread adding the entry. If no matching dentry is found in either +cache, the newly allocated dentry is returned and the caller can +detect this from the presence of ``DCACHE_PAR_LOOKUP``. In this case it +knows that it has won any race and now is responsible for asking the +filesystem to perform the lookup and find the matching inode. When +the lookup is complete, it must call ``d_lookup_done()`` which clears +the flag and does some other house keeping, including removing the +dentry from the secondary hash table - it will normally have been +added to the primary hash table already. Note that a ``struct +waitqueue_head`` is passed to ``d_alloc_parallel()``, and +``d_lookup_done()`` must be called while this ``waitqueue_head`` is still +in scope. + +If a matching dentry is found in the secondary hash table, +``d_alloc_parallel()`` has a little more work to do. It first waits for +``DCACHE_PAR_LOOKUP`` to be cleared, using a wait_queue that was passed +to the instance of ``d_alloc_parallel()`` that won the race and that +will be woken by the call to ``d_lookup_done()``. It then checks to see +if the dentry has now been added to the primary hash table. If it +has, the dentry is returned and the caller just sees that it lost any +race. If it hasn't been added to the primary hash table, the most +likely explanation is that some other dentry was added instead using +``d_splice_alias()``. In any case, ``d_alloc_parallel()`` repeats all the +look ups from the start and will normally return something from the +primary hash table. + +mnt->mnt_count +~~~~~~~~~~~~~~ + +``mnt_count`` is a per-CPU reference counter on "``mount``" structures. Per-CPU here means that incrementing the count is cheap as it only uses CPU-local memory, but checking if the count is zero is expensive as -it needs to check with every CPU. Taking a `mnt_count` reference +it needs to check with every CPU. Taking a ``mnt_count`` reference prevents the mount structure from disappearing as the result of regular unmount operations, but does not prevent a "lazy" unmount. So holding -`mnt_count` doesn't ensure that the mount remains in the namespace and, +``mnt_count`` doesn't ensure that the mount remains in the namespace and, in particular, doesn't stabilize the link to the mounted-on dentry. It -does, however, ensure that the `mount` data structure remains coherent, +does, however, ensure that the ``mount`` data structure remains coherent, and it provides a reference to the root dentry of the mounted -filesystem. So a reference through `->mnt_count` provides a stable +filesystem. So a reference through ``->mnt_count`` provides a stable reference to the mounted dentry, but not the mounted-on dentry. -### mount_lock ### +mount_lock +~~~~~~~~~~ -`mount_lock` is a global seqlock, a bit like `rename_lock`. It can be used to +``mount_lock`` is a global seqlock, a bit like ``rename_lock``. It can be used to check if any change has been made to any mount points. While walking down the tree (away from the root) this lock is used when crossing a mount point to check that the crossing was safe. That is, the value in the seqlock is read, then the code finds the mount that is mounted on the current directory, if there is one, and increments -the `mnt_count`. Finally the value in `mount_lock` is checked against +the ``mnt_count``. Finally the value in ``mount_lock`` is checked against the old value. If there is no change, then the crossing was safe. If there -was a change, the `mnt_count` is decremented and the whole process is +was a change, the ``mnt_count`` is decremented and the whole process is retried. When walking up the tree (towards the root) by following a ".." link, @@ -298,7 +333,8 @@ any changes to any mount points while stepping up. This locking is needed to stabilize the link to the mounted-on dentry, which the refcount on the mount itself doesn't ensure. -### RCU ### +RCU +~~~ Finally the global (but extremely lightweight) RCU read lock is held from time to time to ensure certain data structures don't get freed @@ -307,137 +343,141 @@ unexpectedly. In particular it is held while scanning chains in the dcache hash table, and the mount point hash table. -Bringing it together with `struct nameidata` +Bringing it together with ``struct nameidata`` -------------------------------------------- -[First edition Unix]: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s +.. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s Throughout the process of walking a path, the current status is stored -in a `struct nameidata`, "namei" being the traditional name - dating -all the way back to [First Edition Unix] - of the function that -converts a "name" to an "inode". `struct nameidata` contains (among +in a ``struct nameidata``, "namei" being the traditional name - dating +all the way back to `First Edition Unix`_ - of the function that +converts a "name" to an "inode". ``struct nameidata`` contains (among other fields): -### `struct path path` ### +``struct path path`` +~~~~~~~~~~~~~~~~~~ -A `path` contains a `struct vfsmount` (which is -embedded in a `struct mount`) and a `struct dentry`. Together these +A ``path`` contains a ``struct vfsmount`` (which is +embedded in a ``struct mount``) and a ``struct dentry``. Together these record the current status of the walk. They start out referring to the starting point (the current working directory, the root directory, or some other directory identified by a file descriptor), and are updated on each -step. A reference through `d_lockref` and `mnt_count` is always +step. A reference through ``d_lockref`` and ``mnt_count`` is always held. -### `struct qstr last` ### +``struct qstr last`` +~~~~~~~~~~~~~~~~~~ -This is a string together with a length (i.e. _not_ `nul` terminated) +This is a string together with a length (i.e. _not_ ``nul`` terminated) that is the "next" component in the pathname. -### `int last_type` ### +``int last_type`` +~~~~~~~~~~~~~~~ -This is one of `LAST_NORM`, `LAST_ROOT`, `LAST_DOT`, `LAST_DOTDOT`, or -`LAST_BIND`. The `last` field is only valid if the type is -`LAST_NORM`. `LAST_BIND` is used when following a symlink and no +This is one of ``LAST_NORM``, ``LAST_ROOT``, ``LAST_DOT``, ``LAST_DOTDOT``, or +``LAST_BIND``. The ``last`` field is only valid if the type is +``LAST_NORM``. ``LAST_BIND`` is used when following a symlink and no components of the symlink have been processed yet. Others should be fairly self-explanatory. -### `struct path root` ### +``struct path root`` +~~~~~~~~~~~~~~~~~~ This is used to hold a reference to the effective root of the filesystem. Often that reference won't be needed, so this field is only assigned the first time it is used, or when a non-standard root -is requested. Keeping a reference in the `nameidata` ensures that +is requested. Keeping a reference in the ``nameidata`` ensures that only one root is in effect for the entire path walk, even if it races -with a `chroot()` system call. +with a ``chroot()`` system call. The root is needed when either of two conditions holds: (1) either the -pathname or a symbolic link starts with a "'/'", or (2) a "`..`" -component is being handled, since "`..`" from the root must always stay +pathname or a symbolic link starts with a "'/'", or (2) a "``..``" +component is being handled, since "``..``" from the root must always stay at the root. The value used is usually the current root directory of the calling process. An alternate root can be provided as when -`sysctl()` calls `file_open_root()`, and when NFSv4 or Btrfs call -`mount_subtree()`. In each case a pathname is being looked up in a very +``sysctl()`` calls ``file_open_root()``, and when NFSv4 or Btrfs call +``mount_subtree()``. In each case a pathname is being looked up in a very specific part of the filesystem, and the lookup must not be allowed to -escape that subtree. It works a bit like a local `chroot()`. +escape that subtree. It works a bit like a local ``chroot()``. Ignoring the handling of symbolic links, we can now describe the -"`link_path_walk()`" function, which handles the lookup of everything +"``link_path_walk()``" function, which handles the lookup of everything except the final component as: -> Given a path (`name`) and a nameidata structure (`nd`), check that the -> current directory has execute permission and then advance `name` -> over one component while updating `last_type` and `last`. If that -> was the final component, then return, otherwise call -> `walk_component()` and repeat from the top. + Given a path (``name``) and a nameidata structure (``nd``), check that the + current directory has execute permission and then advance ``name`` + over one component while updating ``last_type`` and ``last``. If that + was the final component, then return, otherwise call + ``walk_component()`` and repeat from the top. -`walk_component()` is even easier. If the component is `LAST_DOTS`, -it calls `handle_dots()` which does the necessary locking as already -described. If it finds a `LAST_NORM` component it first calls -"`lookup_fast()`" which only looks in the dcache, but will ask the +``walk_component()`` is even easier. If the component is ``LAST_DOTS``, +it calls ``handle_dots()`` which does the necessary locking as already +described. If it finds a ``LAST_NORM`` component it first calls +"``lookup_fast()``" which only looks in the dcache, but will ask the filesystem to revalidate the result if it is that sort of filesystem. -If that doesn't get a good result, it calls "`lookup_slow()`" which -takes the `i_mutex`, rechecks the cache, and then asks the filesystem +If that doesn't get a good result, it calls "``lookup_slow()``" which +takes ``i_rwsem``, rechecks the cache, and then asks the filesystem to find a definitive answer. Each of these will call -`follow_managed()` (as described below) to handle any mount points. +``follow_managed()`` (as described below) to handle any mount points. -In the absence of symbolic links, `walk_component()` creates a new -`struct path` containing a counted reference to the new dentry and a -reference to the new `vfsmount` which is only counted if it is -different from the previous `vfsmount`. It then calls -`path_to_nameidata()` to install the new `struct path` in the -`struct nameidata` and drop the unneeded references. +In the absence of symbolic links, ``walk_component()`` creates a new +``struct path`` containing a counted reference to the new dentry and a +reference to the new ``vfsmount`` which is only counted if it is +different from the previous ``vfsmount``. It then calls +``path_to_nameidata()`` to install the new ``struct path`` in the +``struct nameidata`` and drop the unneeded references. This "hand-over-hand" sequencing of getting a reference to the new dentry before dropping the reference to the previous dentry may seem obvious, but is worth pointing out so that we will recognize its analogue in the "RCU-walk" version. -Handling the final component. ------------------------------ +Handling the final component +---------------------------- -`link_path_walk()` only walks as far as setting `nd->last` and -`nd->last_type` to refer to the final component of the path. It does -not call `walk_component()` that last time. Handling that final +``link_path_walk()`` only walks as far as setting ``nd->last`` and +``nd->last_type`` to refer to the final component of the path. It does +not call ``walk_component()`` that last time. Handling that final component remains for the caller to sort out. Those callers are -`path_lookupat()`, `path_parentat()`, `path_mountpoint()` and -`path_openat()` each of which handles the differing requirements of +``path_lookupat()``, ``path_parentat()``, ``path_mountpoint()`` and +``path_openat()`` each of which handles the differing requirements of different system calls. -`path_parentat()` is clearly the simplest - it just wraps a little bit -of housekeeping around `link_path_walk()` and returns the parent +``path_parentat()`` is clearly the simplest - it just wraps a little bit +of housekeeping around ``link_path_walk()`` and returns the parent directory and final component to the caller. The caller will be either -aiming to create a name (via `filename_create()`) or remove or rename -a name (in which case `user_path_parent()` is used). They will use -`i_mutex` to exclude other changes while they validate and then +aiming to create a name (via ``filename_create()``) or remove or rename +a name (in which case ``user_path_parent()`` is used). They will use +``i_rwsem`` to exclude other changes while they validate and then perform their operation. -`path_lookupat()` is nearly as simple - it is used when an existing -object is wanted such as by `stat()` or `chmod()`. It essentially just -calls `walk_component()` on the final component through a call to -`lookup_last()`. `path_lookupat()` returns just the final dentry. +``path_lookupat()`` is nearly as simple - it is used when an existing +object is wanted such as by ``stat()`` or ``chmod()``. It essentially just +calls ``walk_component()`` on the final component through a call to +``lookup_last()``. ``path_lookupat()`` returns just the final dentry. -`path_mountpoint()` handles the special case of unmounting which must +``path_mountpoint()`` handles the special case of unmounting which must not try to revalidate the mounted filesystem. It effectively -contains, through a call to `mountpoint_last()`, an alternate -implementation of `lookup_slow()` which skips that step. This is +contains, through a call to ``mountpoint_last()``, an alternate +implementation of ``lookup_slow()`` which skips that step. This is important when unmounting a filesystem that is inaccessible, such as one provided by a dead NFS server. -Finally `path_openat()` is used for the `open()` system call; it -contains, in support functions starting with "`do_last()`", all the +Finally ``path_openat()`` is used for the ``open()`` system call; it +contains, in support functions starting with "``do_last()``", all the complexity needed to handle the different subtleties of O_CREAT (with -or without O_EXCL), final "`/`" characters, and trailing symbolic +or without O_EXCL), final "``/``" characters, and trailing symbolic links. We will revisit this in the final part of this series, which -focuses on those symbolic links. "`do_last()`" will sometimes, but -not always, take `i_mutex`, depending on what it finds. +focuses on those symbolic links. "``do_last()``" will sometimes, but +not always, take ``i_rwsem``, depending on what it finds. Each of these, or the functions which call them, need to be alert to -the possibility that the final component is not `LAST_NORM`. If the +the possibility that the final component is not ``LAST_NORM``. If the goal of the lookup is to create something, then any value for -`last_type` other than `LAST_NORM` will result in an error. For -example if `path_parentat()` reports `LAST_DOTDOT`, then the caller +``last_type`` other than ``LAST_NORM`` will result in an error. For +example if ``path_parentat()`` reports ``LAST_DOTDOT``, then the caller won't try to create that name. They also check for trailing slashes -by testing `last.name[last.len]`. If there is any character beyond +by testing ``last.name[last.len]``. If there is any character beyond the final component, it must be a trailing slash. Revalidation and automounts @@ -448,12 +488,12 @@ process not yet covered. One is the handling of stale cache entries and the other is automounts. On filesystems that require it, the lookup routines will call the -`->d_revalidate()` dentry method to ensure that the cached information +``->d_revalidate()`` dentry method to ensure that the cached information is current. This will often confirm validity or update a few details from a server. In some cases it may find that there has been change further up the path and that something that was thought to be valid previously isn't really. When this happens the lookup of the whole -path is aborted and retried with the "`LOOKUP_REVAL`" flag set. This +path is aborted and retried with the "``LOOKUP_REVAL``" flag set. This forces revalidation to be more thorough. We will see more details of this retry process in the next article. @@ -465,52 +505,55 @@ tree, but a few notes specifically related to path lookup are in order here. The Linux VFS has a concept of "managed" dentries which is reflected -in function names such as "`follow_managed()`". There are three +in function names such as "``follow_managed()``". There are three potentially interesting things about these dentries corresponding -to three different flags that might be set in `dentry->d_flags`: +to three different flags that might be set in ``dentry->d_flags``: -### `DCACHE_MANAGE_TRANSIT` ### +``DCACHE_MANAGE_TRANSIT`` +~~~~~~~~~~~~~~~~~~~~~~~ If this flag has been set, then the filesystem has requested that the -`d_manage()` dentry operation be called before handling any possible +``d_manage()`` dentry operation be called before handling any possible mount point. This can perform two particular services: It can block to avoid races. If an automount point is being -unmounted, the `d_manage()` function will usually wait for that +unmounted, the ``d_manage()`` function will usually wait for that process to complete before letting the new lookup proceed and possibly trigger a new automount. It can selectively allow only some processes to transit through a mount point. When a server process is managing automounts, it may need to access a directory without triggering normal automount -processing. That server process can identify itself to the `autofs` +processing. That server process can identify itself to the ``autofs`` filesystem, which will then give it a special pass through -`d_manage()` by returning `-EISDIR`. +``d_manage()`` by returning ``-EISDIR``. -### `DCACHE_MOUNTED` ### +``DCACHE_MOUNTED`` +~~~~~~~~~~~~~~~~ This flag is set on every dentry that is mounted on. As Linux supports multiple filesystem namespaces, it is possible that the dentry may not be mounted on in *this* namespace, just in some other. So this flag is seen as a hint, not a promise. -If this flag is set, and `d_manage()` didn't return `-EISDIR`, -`lookup_mnt()` is called to examine the mount hash table (honoring the -`mount_lock` described earlier) and possibly return a new `vfsmount` -and a new `dentry` (both with counted references). +If this flag is set, and ``d_manage()`` didn't return ``-EISDIR``, +``lookup_mnt()`` is called to examine the mount hash table (honoring the +``mount_lock`` described earlier) and possibly return a new ``vfsmount`` +and a new ``dentry`` (both with counted references). -### `DCACHE_NEED_AUTOMOUNT` ### +``DCACHE_NEED_AUTOMOUNT`` +~~~~~~~~~~~~~~~~~~~~~~~ -If `d_manage()` allowed us to get this far, and `lookup_mnt()` didn't -find a mount point, then this flag causes the `d_automount()` dentry +If ``d_manage()`` allowed us to get this far, and ``lookup_mnt()`` didn't +find a mount point, then this flag causes the ``d_automount()`` dentry operation to be called. -The `d_automount()` operation can be arbitrarily complex and may +The ``d_automount()`` operation can be arbitrarily complex and may communicate with server processes etc. but it should ultimately either report that there was an error, that there was nothing to mount, or -should provide an updated `struct path` with new `dentry` and `vfsmount`. +should provide an updated ``struct path`` with new ``dentry`` and ``vfsmount``. -In the latter case, `finish_automount()` will be called to safely +In the latter case, ``finish_automount()`` will be called to safely install the new mount point into the mount table. There is no new locking of import here and it is important that no @@ -567,7 +610,7 @@ isn't in the cache, then it tries to stop gracefully and switch to REF-walk. This stopping requires getting a counted reference on the current -`vfsmount` and `dentry`, and ensuring that these are still valid - +``vfsmount`` and ``dentry``, and ensuring that these are still valid - that a path walk with REF-walk would have found the same entries. This is an invariant that RCU-walk must guarantee. It can only make decisions, such as selecting the next step, that are decisions which @@ -578,21 +621,21 @@ RCU-walk finds it cannot stop gracefully, it simply gives up and restarts from the top with REF-walk. This pattern of "try RCU-walk, if that fails try REF-walk" can be -clearly seen in functions like `filename_lookup()`, -`filename_parentat()`, `filename_mountpoint()`, -`do_filp_open()`, and `do_file_open_root()`. These five -correspond roughly to the four `path_`* functions we met earlier, -each of which calls `link_path_walk()`. The `path_*` functions are +clearly seen in functions like ``filename_lookup()``, +``filename_parentat()``, ``filename_mountpoint()``, +``do_filp_open()``, and ``do_file_open_root()``. These five +correspond roughly to the four ``path_``* functions we met earlier, +each of which calls ``link_path_walk()``. The ``path_*`` functions are called using different mode flags until a mode is found which works. -They are first called with `LOOKUP_RCU` set to request "RCU-walk". If -that fails with the error `ECHILD` they are called again with no +They are first called with ``LOOKUP_RCU`` set to request "RCU-walk". If +that fails with the error ``ECHILD`` they are called again with no special flag to request "REF-walk". If either of those report the -error `ESTALE` a final attempt is made with `LOOKUP_REVAL` set (and no -`LOOKUP_RCU`) to ensure that entries found in the cache are forcibly +error ``ESTALE`` a final attempt is made with ``LOOKUP_REVAL`` set (and no +``LOOKUP_RCU``) to ensure that entries found in the cache are forcibly revalidated - normally entries are only revalidated if the filesystem determines that they are too old to trust. -The `LOOKUP_RCU` attempt may drop that flag internally and switch to +The ``LOOKUP_RCU`` attempt may drop that flag internally and switch to REF-walk, but will never then try to switch back to RCU-walk. Places that trip up RCU-walk are much more likely to be near the leaves and so it is very unlikely that there will be much, if any, benefit from @@ -602,7 +645,7 @@ RCU and seqlocks: fast and light -------------------------------- RCU is, unsurprisingly, critical to RCU-walk mode. The -`rcu_read_lock()` is held for the entire time that RCU-walk is walking +``rcu_read_lock()`` is held for the entire time that RCU-walk is walking down a path. The particular guarantee it provides is that the key data structures - dentries, inodes, super_blocks, and mounts - will not be freed while the lock is held. They might be unlinked or @@ -614,7 +657,7 @@ seqlocks. As we saw above, REF-walk holds a counted reference to the current dentry and the current vfsmount, and does not release those references before taking references to the "next" dentry or vfsmount. It also -sometimes takes the `d_lock` spinlock. These references and locks are +sometimes takes the ``d_lock`` spinlock. These references and locks are taken to prevent certain changes from happening. RCU-walk must not take those references or locks and so cannot prevent such changes. Instead, it checks to see if a change has been made, and aborts or @@ -624,123 +667,126 @@ To preserve the invariant mentioned above (that RCU-walk may only make decisions that REF-walk could have made), it must make the checks at or near the same places that REF-walk holds the references. So, when REF-walk increments a reference count or takes a spinlock, RCU-walk -samples the status of a seqlock using `read_seqcount_begin()` or a +samples the status of a seqlock using ``read_seqcount_begin()`` or a similar function. When REF-walk decrements the count or drops the lock, RCU-walk checks if the sampled status is still valid using -`read_seqcount_retry()` or similar. +``read_seqcount_retry()`` or similar. However, there is a little bit more to seqlocks than that. If RCU-walk accesses two different fields in a seqlock-protected structure, or accesses the same field twice, there is no a priori guarantee of any consistency between those accesses. When consistency is needed - which it usually is - RCU-walk must take a copy and then -use `read_seqcount_retry()` to validate that copy. +use ``read_seqcount_retry()`` to validate that copy. -`read_seqcount_retry()` not only checks the sequence number, but also +``read_seqcount_retry()`` not only checks the sequence number, but also imposes a memory barrier so that no memory-read instruction from *before* the call can be delayed until *after* the call, either by the CPU or by the compiler. A simple example of this can be seen in -`slow_dentry_cmp()` which, for filesystems which do not use simple +``slow_dentry_cmp()`` which, for filesystems which do not use simple byte-wise name equality, calls into the filesystem to compare a name against a dentry. The length and name pointer are copied into local -variables, then `read_seqcount_retry()` is called to confirm the two -are consistent, and only then is `->d_compare()` called. When -standard filename comparison is used, `dentry_cmp()` is called -instead. Notably it does _not_ use `read_seqcount_retry()`, but +variables, then ``read_seqcount_retry()`` is called to confirm the two +are consistent, and only then is ``->d_compare()`` called. When +standard filename comparison is used, ``dentry_cmp()`` is called +instead. Notably it does _not_ use ``read_seqcount_retry()``, but instead has a large comment explaining why the consistency guarantee -isn't necessary. A subsequent `read_seqcount_retry()` will be +isn't necessary. A subsequent ``read_seqcount_retry()`` will be sufficient to catch any problem that could occur at this point. With that little refresher on seqlocks out of the way we can look at the bigger picture of how RCU-walk uses seqlocks. -### `mount_lock` and `nd->m_seq` ### +``mount_lock`` and ``nd->m_seq`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We already met the `mount_lock` seqlock when REF-walk used it to +We already met the ``mount_lock`` seqlock when REF-walk used it to ensure that crossing a mount point is performed safely. RCU-walk uses it for that too, but for quite a bit more. -Instead of taking a counted reference to each `vfsmount` as it -descends the tree, RCU-walk samples the state of `mount_lock` at the +Instead of taking a counted reference to each ``vfsmount`` as it +descends the tree, RCU-walk samples the state of ``mount_lock`` at the start of the walk and stores this initial sequence number in the -`struct nameidata` in the `m_seq` field. This one lock and one -sequence number are used to validate all accesses to all `vfsmounts`, +``struct nameidata`` in the ``m_seq`` field. This one lock and one +sequence number are used to validate all accesses to all ``vfsmounts``, and all mount point crossings. As changes to the mount table are relatively rare, it is reasonable to fall back on REF-walk any time that any "mount" or "unmount" happens. -`m_seq` is checked (using `read_seqretry()`) at the end of an RCU-walk +``m_seq`` is checked (using ``read_seqretry()``) at the end of an RCU-walk sequence, whether switching to REF-walk for the rest of the path or when the end of the path is reached. It is also checked when stepping -down over a mount point (in `__follow_mount_rcu()`) or up (in -`follow_dotdot_rcu()`). If it is ever found to have changed, the +down over a mount point (in ``__follow_mount_rcu()``) or up (in +``follow_dotdot_rcu()``). If it is ever found to have changed, the whole RCU-walk sequence is aborted and the path is processed again by REF-walk. -If RCU-walk finds that `mount_lock` hasn't changed then it can be sure +If RCU-walk finds that ``mount_lock`` hasn't changed then it can be sure that, had REF-walk taken counted references on each vfsmount, the results would have been the same. This ensures the invariant holds, at least for vfsmount structures. -### `dentry->d_seq` and `nd->seq`. ### +``dentry->d_seq`` and ``nd->seq`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In place of taking a count or lock on `d_reflock`, RCU-walk samples -the per-dentry `d_seq` seqlock, and stores the sequence number in the -`seq` field of the nameidata structure, so `nd->seq` should always be -the current sequence number of `nd->dentry`. This number needs to be +In place of taking a count or lock on ``d_reflock``, RCU-walk samples +the per-dentry ``d_seq`` seqlock, and stores the sequence number in the +``seq`` field of the nameidata structure, so ``nd->seq`` should always be +the current sequence number of ``nd->dentry``. This number needs to be revalidated after copying, and before using, the name, parent, or inode of the dentry. The handling of the name we have already looked at, and the parent is -only accessed in `follow_dotdot_rcu()` which fairly trivially follows +only accessed in ``follow_dotdot_rcu()`` which fairly trivially follows the required pattern, though it does so for three different cases. -When not at a mount point, `d_parent` is followed and its `d_seq` is +When not at a mount point, ``d_parent`` is followed and its ``d_seq`` is collected. When we are at a mount point, we instead follow the -`mnt->mnt_mountpoint` link to get a new dentry and collect its -`d_seq`. Then, after finally finding a `d_parent` to follow, we must +``mnt->mnt_mountpoint`` link to get a new dentry and collect its +``d_seq``. Then, after finally finding a ``d_parent`` to follow, we must check if we have landed on a mount point and, if so, must find that -mount point and follow the `mnt->mnt_root` link. This would imply a +mount point and follow the ``mnt->mnt_root`` link. This would imply a somewhat unusual, but certainly possible, circumstance where the starting point of the path lookup was in part of the filesystem that was mounted on, and so not visible from the root. -The inode pointer, stored in `->d_inode`, is a little more +The inode pointer, stored in ``->d_inode``, is a little more interesting. The inode will always need to be accessed at least twice, once to determine if it is NULL and once to verify access permissions. Symlink handling requires a validated inode pointer too. Rather than revalidating on each access, a copy is made on the first -access and it is stored in the `inode` field of `nameidata` from where +access and it is stored in the ``inode`` field of ``nameidata`` from where it can be safely accessed without further validation. -`lookup_fast()` is the only lookup routine that is used in RCU-mode, -`lookup_slow()` being too slow and requiring locks. It is in -`lookup_fast()` that we find the important "hand over hand" tracking +``lookup_fast()`` is the only lookup routine that is used in RCU-mode, +``lookup_slow()`` being too slow and requiring locks. It is in +``lookup_fast()`` that we find the important "hand over hand" tracking of the current dentry. -The current `dentry` and current `seq` number are passed to -`__d_lookup_rcu()` which, on success, returns a new `dentry` and a -new `seq` number. `lookup_fast()` then copies the inode pointer and -revalidates the new `seq` number. It then validates the old `dentry` -with the old `seq` number one last time and only then continues. This -process of getting the `seq` number of the new dentry and then -checking the `seq` number of the old exactly mirrors the process of +The current ``dentry`` and current ``seq`` number are passed to +``__d_lookup_rcu()`` which, on success, returns a new ``dentry`` and a +new ``seq`` number. ``lookup_fast()`` then copies the inode pointer and +revalidates the new ``seq`` number. It then validates the old ``dentry`` +with the old ``seq`` number one last time and only then continues. This +process of getting the ``seq`` number of the new dentry and then +checking the ``seq`` number of the old exactly mirrors the process of getting a counted reference to the new dentry before dropping that for the old dentry which we saw in REF-walk. -### No `inode->i_mutex` or even `rename_lock` ### +No ``inode->i_rwsem`` or even ``rename_lock`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A mutex is a fairly heavyweight lock that can only be taken when it is -permissible to sleep. As `rcu_read_lock()` forbids sleeping, -`inode->i_mutex` plays no role in RCU-walk. If some other thread does -take `i_mutex` and modifies the directory in a way that RCU-walk needs +A semaphore is a fairly heavyweight lock that can only be taken when it is +permissible to sleep. As ``rcu_read_lock()`` forbids sleeping, +``inode->i_rwsem`` plays no role in RCU-walk. If some other thread does +take ``i_rwsem`` and modifies the directory in a way that RCU-walk needs to notice, the result will be either that RCU-walk fails to find the dentry that it is looking for, or it will find a dentry which -`read_seqretry()` won't validate. In either case it will drop down to +``read_seqretry()`` won't validate. In either case it will drop down to REF-walk mode which can take whatever locks are needed. -Though `rename_lock` could be used by RCU-walk as it doesn't require -any sleeping, RCU-walk doesn't bother. REF-walk uses `rename_lock` to +Though ``rename_lock`` could be used by RCU-walk as it doesn't require +any sleeping, RCU-walk doesn't bother. REF-walk uses ``rename_lock`` to protect against the possibility of hash chains in the dcache changing while they are being searched. This can result in failing to find something that actually is there. When RCU-walk fails to find @@ -749,57 +795,57 @@ already drops down to REF-walk and tries again with appropriate locking. This neatly handles all cases, so adding extra checks on rename_lock would bring no significant value. -`unlazy walk()` and `complete_walk()` +``unlazy walk()`` and ``complete_walk()`` ------------------------------------- That "dropping down to REF-walk" typically involves a call to -`unlazy_walk()`, so named because "RCU-walk" is also sometimes -referred to as "lazy walk". `unlazy_walk()` is called when +``unlazy_walk()``, so named because "RCU-walk" is also sometimes +referred to as "lazy walk". ``unlazy_walk()`` is called when following the path down to the current vfsmount/dentry pair seems to have proceeded successfully, but the next step is problematic. This can happen if the next name cannot be found in the dcache, if permission checking or name revalidation couldn't be achieved while -the `rcu_read_lock()` is held (which forbids sleeping), if an +the ``rcu_read_lock()`` is held (which forbids sleeping), if an automount point is found, or in a couple of cases involving symlinks. -It is also called from `complete_walk()` when the lookup has reached +It is also called from ``complete_walk()`` when the lookup has reached the final component, or the very end of the path, depending on which particular flavor of lookup is used. Other reasons for dropping out of RCU-walk that do not trigger a call -to `unlazy_walk()` are when some inconsistency is found that cannot be -handled immediately, such as `mount_lock` or one of the `d_seq` +to ``unlazy_walk()`` are when some inconsistency is found that cannot be +handled immediately, such as ``mount_lock`` or one of the ``d_seq`` seqlocks reporting a change. In these cases the relevant function -will return `-ECHILD` which will percolate up until it triggers a new +will return ``-ECHILD`` which will percolate up until it triggers a new attempt from the top using REF-walk. -For those cases where `unlazy_walk()` is an option, it essentially +For those cases where ``unlazy_walk()`` is an option, it essentially takes a reference on each of the pointers that it holds (vfsmount, dentry, and possibly some symbolic links) and then verifies that the relevant seqlocks have not been changed. If there have been changes, -it, too, aborts with `-ECHILD`, otherwise the transition to REF-walk +it, too, aborts with ``-ECHILD``, otherwise the transition to REF-walk has been a success and the lookup process continues. Taking a reference on those pointers is not quite as simple as just incrementing a counter. That works to take a second reference if you already have one (often indirectly through another object), but it isn't sufficient if you don't actually have a counted reference at -all. For `dentry->d_lockref`, it is safe to increment the reference +all. For ``dentry->d_lockref``, it is safe to increment the reference counter to get a reference unless it has been explicitly marked as -"dead" which involves setting the counter to `-128`. -`lockref_get_not_dead()` achieves this. +"dead" which involves setting the counter to ``-128``. +``lockref_get_not_dead()`` achieves this. -For `mnt->mnt_count` it is safe to take a reference as long as -`mount_lock` is then used to validate the reference. If that +For ``mnt->mnt_count`` it is safe to take a reference as long as +``mount_lock`` is then used to validate the reference. If that validation fails, it may *not* be safe to just drop that reference in -the standard way of calling `mnt_put()` - an unmount may have -progressed too far. So the code in `legitimize_mnt()`, when it +the standard way of calling ``mnt_put()`` - an unmount may have +progressed too far. So the code in ``legitimize_mnt()``, when it finds that the reference it got might not be safe, checks the -`MNT_SYNC_UMOUNT` flag to determine if a simple `mnt_put()` is +``MNT_SYNC_UMOUNT`` flag to determine if a simple ``mnt_put()`` is correct, or if it should just decrement the count and pretend none of this ever happened. Taking care in filesystems ---------------------------- +-------------------------- RCU-walk depends almost entirely on cached information and often will not call into the filesystem at all. However there are two places, @@ -809,26 +855,26 @@ careful. If the filesystem has non-standard permission-checking requirements - such as a networked filesystem which may need to check with the server -- the `i_op->permission` interface might be called during RCU-walk. -In this case an extra "`MAY_NOT_BLOCK`" flag is passed so that it -knows not to sleep, but to return `-ECHILD` if it cannot complete -promptly. `i_op->permission` is given the inode pointer, not the +- the ``i_op->permission`` interface might be called during RCU-walk. +In this case an extra "``MAY_NOT_BLOCK``" flag is passed so that it +knows not to sleep, but to return ``-ECHILD`` if it cannot complete +promptly. ``i_op->permission`` is given the inode pointer, not the dentry, so it doesn't need to worry about further consistency checks. However if it accesses any other filesystem data structures, it must -ensure they are safe to be accessed with only the `rcu_read_lock()` -held. This typically means they must be freed using `kfree_rcu()` or +ensure they are safe to be accessed with only the ``rcu_read_lock()`` +held. This typically means they must be freed using ``kfree_rcu()`` or similar. -[`READ_ONCE()`]: https://lwn.net/Articles/624126/ +.. _READ_ONCE: https://lwn.net/Articles/624126/ If the filesystem may need to revalidate dcache entries, then -`d_op->d_revalidate` may be called in RCU-walk too. This interface -*is* passed the dentry but does not have access to the `inode` or the -`seq` number from the `nameidata`, so it needs to be extra careful +``d_op->d_revalidate`` may be called in RCU-walk too. This interface +*is* passed the dentry but does not have access to the ``inode`` or the +``seq`` number from the ``nameidata``, so it needs to be extra careful when accessing fields in the dentry. This "extra care" typically -involves using [`READ_ONCE()`] to access fields, and verifying the +involves using `READ_ONCE() <READ_ONCE_>`_ to access fields, and verifying the result is not NULL before using it. This pattern can be seen in -`nfs_lookup_revalidate()`. +``nfs_lookup_revalidate()``. A pair of patterns ------------------ @@ -839,14 +885,14 @@ being aware of. The first is "try quickly and check, if that fails try slowly". We can see that in the high-level approach of first trying RCU-walk and -then trying REF-walk, and in places where `unlazy_walk()` is used to +then trying REF-walk, and in places where ``unlazy_walk()`` is used to switch to REF-walk for the rest of the path. We also saw it earlier -in `dget_parent()` when following a "`..`" link. It tries a quick way +in ``dget_parent()`` when following a "``..``" link. It tries a quick way to get a reference, then falls back to taking locks if needed. The second pattern is "try quickly and check, if that fails try -again - repeatedly". This is seen with the use of `rename_lock` and -`mount_lock` in REF-walk. RCU-walk doesn't make use of this pattern - +again - repeatedly". This is seen with the use of ``rename_lock`` and +``mount_lock`` in REF-walk. RCU-walk doesn't make use of this pattern - if anything goes wrong it is much safer to just abort and try a more sedate approach. @@ -882,8 +928,8 @@ Conceptually, symbolic links could be handled by editing the path. If a component name refers to a symbolic link, then that component is replaced by the body of the link and, if that body starts with a '/', then all preceding parts of the path are discarded. This is what the -"`readlink -f`" command does, though it also edits out "`.`" and -"`..`" components. +"``readlink -f``" command does, though it also edits out "``.``" and +"``..``" components. Directly editing the path string is not really necessary when looking up a path, and discarding early components is pointless as they aren't @@ -899,19 +945,19 @@ There are two reasons for placing limits on how many symlinks can occur in a single path lookup. The most obvious is to avoid loops. If a symlink referred to itself either directly or through intermediaries, then following the symlink can never complete -successfully - the error `ELOOP` must be returned. Loops can be +successfully - the error ``ELOOP`` must be returned. Loops can be detected without imposing limits, but limits are the simplest solution and, given the second reason for restriction, quite sufficient. -[outlined recently]: http://thread.gmane.org/gmane.linux.kernel/1934390/focus=1934550 +.. _outlined recently: http://thread.gmane.org/gmane.linux.kernel/1934390/focus=1934550 -The second reason was [outlined recently] by Linus: +The second reason was `outlined recently`_ by Linus: -> Because it's a latency and DoS issue too. We need to react well to -> true loops, but also to "very deep" non-loops. It's not about memory -> use, it's about users triggering unreasonable CPU resources. + Because it's a latency and DoS issue too. We need to react well to + true loops, but also to "very deep" non-loops. It's not about memory + use, it's about users triggering unreasonable CPU resources. -Linux imposes a limit on the length of any pathname: `PATH_MAX`, which +Linux imposes a limit on the length of any pathname: ``PATH_MAX``, which is 4096. There are a number of reasons for this limit; not letting the kernel spend too much time on just one path is one of them. With symbolic links you can effectively generate much longer paths so some @@ -921,7 +967,7 @@ further limit of eight on the maximum depth of recursion, but that was raised to 40 when a separate stack was implemented, so there is now just the one limit. -The `nameidata` structure that we met in an earlier article contains a +The ``nameidata`` structure that we met in an earlier article contains a small stack that can be used to store the remaining part of up to two symlinks. In many cases this will be sufficient. If it isn't, a separate stack is allocated with room for 40 symlinks. Pathname @@ -941,13 +987,13 @@ to external storage. It is particularly important for RCU-walk to be able to find and temporarily hold onto these cached entries, so that it doesn't need to drop down into REF-walk. -[object-oriented design pattern]: https://lwn.net/Articles/446317/ +.. _object-oriented design pattern: https://lwn.net/Articles/446317/ While each filesystem is free to make its own choice, symlinks are typically stored in one of two places. Short symlinks are often -stored directly in the inode. When a filesystem allocates a `struct -inode` it typically allocates extra space to store private data (a -common [object-oriented design pattern] in the kernel). This will +stored directly in the inode. When a filesystem allocates a ``struct +inode`` it typically allocates extra space to store private data (a +common `object-oriented design pattern`_ in the kernel). This will sometimes include space for a symlink. The other common location is in the page cache, which normally stores the content of files. The pathname in a symlink can be seen as the content of that symlink and @@ -962,13 +1008,13 @@ the inode which, itself, is protected by RCU or by a counted reference on the dentry. This means that the mechanisms that pathname lookup uses to access the dcache and icache (inode cache) safely are quite sufficient for accessing some cached symlinks safely. In these cases, -the `i_link` pointer in the inode is set to point to wherever the +the ``i_link`` pointer in the inode is set to point to wherever the symlink is stored and it can be accessed directly whenever needed. When the symlink is stored in the page cache or elsewhere, the situation is not so straightforward. A reference on a dentry or even on an inode does not imply any reference on cached pages of that -inode, and even an `rcu_read_lock()` is not sufficient to ensure that +inode, and even an ``rcu_read_lock()`` is not sufficient to ensure that a page will not disappear. So for these symlinks the pathname lookup code needs to ask the filesystem to provide a stable reference and, significantly, needs to release that reference when it is finished @@ -978,48 +1024,48 @@ Taking a reference to a cache page is often possible even in RCU-walk mode. It does require making changes to memory, which is best avoided, but that isn't necessarily a big cost and it is better than dropping out of RCU-walk mode completely. Even filesystems that allocate -space to copy the symlink into can use `GFP_ATOMIC` to often successfully +space to copy the symlink into can use ``GFP_ATOMIC`` to often successfully allocate memory without the need to drop out of RCU-walk. If a filesystem cannot successfully get a reference in RCU-walk mode, it -must return `-ECHILD` and `unlazy_walk()` will be called to return to +must return ``-ECHILD`` and ``unlazy_walk()`` will be called to return to REF-walk mode in which the filesystem is allowed to sleep. -The place for all this to happen is the `i_op->follow_link()` inode +The place for all this to happen is the ``i_op->follow_link()`` inode method. In the present mainline code this is never actually called in RCU-walk mode as the rewrite is not quite complete. It is likely that -in a future release this method will be passed an `inode` pointer when +in a future release this method will be passed an ``inode`` pointer when called in RCU-walk mode so it both (1) knows to be careful, and (2) has the -validated pointer. Much like the `i_op->permission()` method we -looked at previously, `->follow_link()` would need to be careful that +validated pointer. Much like the ``i_op->permission()`` method we +looked at previously, ``->follow_link()`` would need to be careful that all the data structures it references are safe to be accessed while holding no counted reference, only the RCU lock. Though getting a -reference with `->follow_link()` is not yet done in RCU-walk mode, the +reference with ``->follow_link()`` is not yet done in RCU-walk mode, the code is ready to release the reference when that does happen. This need to drop the reference to a symlink adds significant complexity. It requires a reference to the inode so that the -`i_op->put_link()` inode operation can be called. In REF-walk, that +``i_op->put_link()`` inode operation can be called. In REF-walk, that reference is kept implicitly through a reference to the dentry, so -keeping the `struct path` of the symlink is easiest. For RCU-walk, +keeping the ``struct path`` of the symlink is easiest. For RCU-walk, the pointer to the inode is kept separately. To allow switching from RCU-walk back to REF-walk in the middle of processing nested symlinks we also need the seq number for the dentry so we can confirm that switching back was safe. Finally, when providing a reference to a symlink, the filesystem also -provides an opaque "cookie" that must be passed to `->put_link()` so that it +provides an opaque "cookie" that must be passed to ``->put_link()`` so that it knows what to free. This might be the allocated memory area, or a -pointer to the `struct page` in the page cache, or something else +pointer to the ``struct page`` in the page cache, or something else completely. Only the filesystem knows what it is. In order for the reference to each symlink to be dropped when the walk completes, whether in RCU-walk or REF-walk, the symlink stack needs to contain, along with the path remnants: -- the `struct path` to provide a reference to the inode in REF-walk -- the `struct inode *` to provide a reference to the inode in RCU-walk -- the `seq` to allow the path to be safely switched from RCU-walk to REF-walk -- the `cookie` that tells `->put_path()` what to put. +- the ``struct path`` to provide a reference to the inode in REF-walk +- the ``struct inode *`` to provide a reference to the inode in RCU-walk +- the ``seq`` to allow the path to be safely switched from RCU-walk to REF-walk +- the ``cookie`` that tells ``->put_path()`` what to put. This means that each entry in the symlink stack needs to hold five pointers and an integer instead of just one pointer (the path @@ -1028,28 +1074,28 @@ with 40 entries it adds up to 1600 bytes total, which is less than half a page. So it might seem like a lot, but is by no means excessive. -Note that, in a given stack frame, the path remnant (`name`) is not +Note that, in a given stack frame, the path remnant (``name``) is not part of the symlink that the other fields refer to. It is the remnant to be followed once that symlink has been fully parsed. Following the symlink --------------------- -The main loop in `link_path_walk()` iterates seamlessly over all +The main loop in ``link_path_walk()`` iterates seamlessly over all components in the path and all of the non-final symlinks. As symlinks -are processed, the `name` pointer is adjusted to point to a new +are processed, the ``name`` pointer is adjusted to point to a new symlink, or is restored from the stack, so that much of the loop -doesn't need to notice. Getting this `name` variable on and off the +doesn't need to notice. Getting this ``name`` variable on and off the stack is very straightforward; pushing and popping the references is a little more complex. -When a symlink is found, `walk_component()` returns the value `1` -(`0` is returned for any other sort of success, and a negative number -is, as usual, an error indicator). This causes `get_link()` to be +When a symlink is found, ``walk_component()`` returns the value ``1`` +(``0`` is returned for any other sort of success, and a negative number +is, as usual, an error indicator). This causes ``get_link()`` to be called; it then gets the link from the filesystem. Providing that -operation is successful, the old path `name` is placed on the stack, -and the new value is used as the `name` for a while. When the end of -the path is found (i.e. `*name` is `'\0'`) the old `name` is restored +operation is successful, the old path ``name`` is placed on the stack, +and the new value is used as the ``name`` for a while. When the end of +the path is found (i.e. ``*name`` is ``'\0'``) the old ``name`` is restored off the stack and path walking continues. Pushing and popping the reference pointers (inode, cookie, etc.) is more @@ -1060,113 +1106,114 @@ the symlink-just-found to avoid leaving empty path remnants that would just get in the way. It is most convenient to push the new symlink references onto the -stack in `walk_component()` immediately when the symlink is found; -`walk_component()` is also the last piece of code that needs to look at the +stack in ``walk_component()`` immediately when the symlink is found; +``walk_component()`` is also the last piece of code that needs to look at the old symlink as it walks that last component. So it is quite -convenient for `walk_component()` to release the old symlink and pop +convenient for ``walk_component()`` to release the old symlink and pop the references just before pushing the reference information for the -new symlink. It is guided in this by two flags; `WALK_GET`, which +new symlink. It is guided in this by two flags; ``WALK_GET``, which gives it permission to follow a symlink if it finds one, and -`WALK_PUT`, which tells it to release the current symlink after it has been -followed. `WALK_PUT` is tested first, leading to a call to -`put_link()`. `WALK_GET` is tested subsequently (by -`should_follow_link()`) leading to a call to `pick_link()` which sets +``WALK_PUT``, which tells it to release the current symlink after it has been +followed. ``WALK_PUT`` is tested first, leading to a call to +``put_link()``. ``WALK_GET`` is tested subsequently (by +``should_follow_link()``) leading to a call to ``pick_link()`` which sets up the stack frame. -### Symlinks with no final component ### +Symlinks with no final component +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A pair of special-case symlinks deserve a little further explanation. -Both result in a new `struct path` (with mount and dentry) being set -up in the `nameidata`, and result in `get_link()` returning `NULL`. +Both result in a new ``struct path`` (with mount and dentry) being set +up in the ``nameidata``, and result in ``get_link()`` returning ``NULL``. -The more obvious case is a symlink to "`/`". All symlinks starting -with "`/`" are detected in `get_link()` which resets the `nameidata` +The more obvious case is a symlink to "``/``". All symlinks starting +with "``/``" are detected in ``get_link()`` which resets the ``nameidata`` to point to the effective filesystem root. If the symlink only -contains "`/`" then there is nothing more to do, no components at all, -so `NULL` is returned to indicate that the symlink can be released and +contains "``/``" then there is nothing more to do, no components at all, +so ``NULL`` is returned to indicate that the symlink can be released and the stack frame discarded. -The other case involves things in `/proc` that look like symlinks but -aren't really. +The other case involves things in ``/proc`` that look like symlinks but +aren't really:: -> $ ls -l /proc/self/fd/1 -> lrwx------ 1 neilb neilb 64 Jun 13 10:19 /proc/self/fd/1 -> /dev/pts/4 + $ ls -l /proc/self/fd/1 + lrwx------ 1 neilb neilb 64 Jun 13 10:19 /proc/self/fd/1 -> /dev/pts/4 -Every open file descriptor in any process is represented in `/proc` by +Every open file descriptor in any process is represented in ``/proc`` by something that looks like a symlink. It is really a reference to the -target file, not just the name of it. When you `readlink` these +target file, not just the name of it. When you ``readlink`` these objects you get a name that might refer to the same file - unless it -has been unlinked or mounted over. When `walk_component()` follows -one of these, the `->follow_link()` method in "procfs" doesn't return -a string name, but instead calls `nd_jump_link()` which updates the -`nameidata` in place to point to that target. `->follow_link()` then -returns `NULL`. Again there is no final component and `get_link()` -reports this by leaving the `last_type` field of `nameidata` as -`LAST_BIND`. +has been unlinked or mounted over. When ``walk_component()`` follows +one of these, the ``->follow_link()`` method in "procfs" doesn't return +a string name, but instead calls ``nd_jump_link()`` which updates the +``nameidata`` in place to point to that target. ``->follow_link()`` then +returns ``NULL``. Again there is no final component and ``get_link()`` +reports this by leaving the ``last_type`` field of ``nameidata`` as +``LAST_BIND``. Following the symlink in the final component -------------------------------------------- -All this leads to `link_path_walk()` walking down every component, and +All this leads to ``link_path_walk()`` walking down every component, and following all symbolic links it finds, until it reaches the final -component. This is just returned in the `last` field of `nameidata`. +component. This is just returned in the ``last`` field of ``nameidata``. For some callers, this is all they need; they want to create that -`last` name if it doesn't exist or give an error if it does. Other +``last`` name if it doesn't exist or give an error if it does. Other callers will want to follow a symlink if one is found, and possibly apply special handling to the last component of that symlink, rather than just the last component of the original file name. These callers -potentially need to call `link_path_walk()` again and again on +potentially need to call ``link_path_walk()`` again and again on successive symlinks until one is found that doesn't point to another symlink. -This case is handled by the relevant caller of `link_path_walk()`, such as -`path_lookupat()` using a loop that calls `link_path_walk()`, and then +This case is handled by the relevant caller of ``link_path_walk()``, such as +``path_lookupat()`` using a loop that calls ``link_path_walk()``, and then handles the final component. If the final component is a symlink -that needs to be followed, then `trailing_symlink()` is called to set -things up properly and the loop repeats, calling `link_path_walk()` +that needs to be followed, then ``trailing_symlink()`` is called to set +things up properly and the loop repeats, calling ``link_path_walk()`` again. This could loop as many as 40 times if the last component of each symlink is another symlink. The various functions that examine the final component and possibly -report that it is a symlink are `lookup_last()`, `mountpoint_last()` -and `do_last()`, each of which use the same convention as -`walk_component()` of returning `1` if a symlink was found that needs +report that it is a symlink are ``lookup_last()``, ``mountpoint_last()`` +and ``do_last()``, each of which use the same convention as +``walk_component()`` of returning ``1`` if a symlink was found that needs to be followed. -Of these, `do_last()` is the most interesting as it is used for -opening a file. Part of `do_last()` runs with `i_mutex` held and this -part is in a separate function: `lookup_open()`. +Of these, ``do_last()`` is the most interesting as it is used for +opening a file. Part of ``do_last()`` runs with ``i_rwsem`` held and this +part is in a separate function: ``lookup_open()``. -Explaining `do_last()` completely is beyond the scope of this article, +Explaining ``do_last()`` completely is beyond the scope of this article, but a few highlights should help those interested in exploring the code. -1. Rather than just finding the target file, `do_last()` needs to open - it. If the file was found in the dcache, then `vfs_open()` is used for - this. If not, then `lookup_open()` will either call `atomic_open()` (if - the filesystem provides it) to combine the final lookup with the open, or - will perform the separate `lookup_real()` and `vfs_create()` steps - directly. In the later case the actual "open" of this newly found or - created file will be performed by `vfs_open()`, just as if the name - were found in the dcache. - -2. `vfs_open()` can fail with `-EOPENSTALE` if the cached information - wasn't quite current enough. Rather than restarting the lookup from - the top with `LOOKUP_REVAL` set, `lookup_open()` is called instead, - giving the filesystem a chance to resolve small inconsistencies. - If that doesn't work, only then is the lookup restarted from the top. +1. Rather than just finding the target file, ``do_last()`` needs to open + it. If the file was found in the dcache, then ``vfs_open()`` is used for + this. If not, then ``lookup_open()`` will either call ``atomic_open()`` (if + the filesystem provides it) to combine the final lookup with the open, or + will perform the separate ``lookup_real()`` and ``vfs_create()`` steps + directly. In the later case the actual "open" of this newly found or + created file will be performed by ``vfs_open()``, just as if the name + were found in the dcache. + +2. ``vfs_open()`` can fail with ``-EOPENSTALE`` if the cached information + wasn't quite current enough. Rather than restarting the lookup from + the top with ``LOOKUP_REVAL`` set, ``lookup_open()`` is called instead, + giving the filesystem a chance to resolve small inconsistencies. + If that doesn't work, only then is the lookup restarted from the top. 3. An open with O_CREAT **does** follow a symlink in the final component, - unlike other creation system calls (like `mkdir`). So the sequence: + unlike other creation system calls (like ``mkdir``). So the sequence:: - > ln -s bar /tmp/foo - > echo hello > /tmp/foo + ln -s bar /tmp/foo + echo hello > /tmp/foo - will create a file called `/tmp/bar`. This is not permitted if - `O_EXCL` is set but otherwise is handled for an O_CREAT open much - like for a non-creating open: `should_follow_link()` returns `1`, and - so does `do_last()` so that `trailing_symlink()` gets called and the - open process continues on the symlink that was found. + will create a file called ``/tmp/bar``. This is not permitted if + ``O_EXCL`` is set but otherwise is handled for an O_CREAT open much + like for a non-creating open: ``should_follow_link()`` returns ``1``, and + so does ``do_last()`` so that ``trailing_symlink()`` gets called and the + open process continues on the symlink that was found. Updating the access time ------------------------ @@ -1180,110 +1227,112 @@ footprints are best kept to a minimum. One other place where walking down a symlink can involve leaving footprints in a way that doesn't affect directories is in updating access times. In Unix (and Linux) every filesystem object has a "last accessed -time", or "`atime`". Passing through a directory to access a file +time", or "``atime``". Passing through a directory to access a file within is not considered to be an access for the purposes of -`atime`; only listing the contents of a directory can update its `atime`. -Symlinks are different it seems. Both reading a symlink (with `readlink()`) +``atime``; only listing the contents of a directory can update its ``atime``. +Symlinks are different it seems. Both reading a symlink (with ``readlink()``) and looking up a symlink on the way to some other destination can update the atime on that symlink. -[clearest statement]: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 +.. _clearest statement: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_08 It is not clear why this is the case; POSIX has little to say on the -subject. The [clearest statement] is that, if a particular implementation +subject. The `clearest statement`_ is that, if a particular implementation updates a timestamp in a place not specified by POSIX, this must be documented "except that any changes caused by pathname resolution need not be documented". This seems to imply that POSIX doesn't really care about access-time updates during pathname lookup. -[Linux 1.3.87]: https://git.kernel.org/cgit/linux/kernel/git/history/history.git/diff/fs/ext2/symlink.c?id=f806c6db77b8eaa6e00dcfb6b567706feae8dbb8 +.. _Linux 1.3.87: https://git.kernel.org/cgit/linux/kernel/git/history/history.git/diff/fs/ext2/symlink.c?id=f806c6db77b8eaa6e00dcfb6b567706feae8dbb8 -An examination of history shows that prior to [Linux 1.3.87], the ext2 +An examination of history shows that prior to `Linux 1.3.87`_, the ext2 filesystem, at least, didn't update atime when following a link. Unfortunately we have no record of why that behavior was changed. In any case, access time must now be updated and that operation can be quite complex. Trying to stay in RCU-walk while doing it is best -avoided. Fortunately it is often permitted to skip the `atime` -update. Because `atime` updates cause performance problems in various -areas, Linux supports the `relatime` mount option, which generally -limits the updates of `atime` to once per day on files that aren't +avoided. Fortunately it is often permitted to skip the ``atime`` +update. Because ``atime`` updates cause performance problems in various +areas, Linux supports the ``relatime`` mount option, which generally +limits the updates of ``atime`` to once per day on files that aren't being changed (and symlinks never change once created). Even without -`relatime`, many filesystems record `atime` with a one-second +``relatime``, many filesystems record ``atime`` with a one-second granularity, so only one update per second is required. -It is easy to test if an `atime` update is needed while in RCU-walk +It is easy to test if an ``atime`` update is needed while in RCU-walk mode and, if it isn't, the update can be skipped and RCU-walk mode -continues. Only when an `atime` update is actually required does the +continues. Only when an ``atime`` update is actually required does the path walk drop down to REF-walk. All of this is handled in the -`get_link()` function. +``get_link()`` function. A few flags ----------- A suitable way to wrap up this tour of pathname walking is to list -the various flags that can be stored in the `nameidata` to guide the +the various flags that can be stored in the ``nameidata`` to guide the lookup process. Many of these are only meaningful on the final component, others reflect the current state of the pathname lookup. -And then there is `LOOKUP_EMPTY`, which doesn't fit conceptually with +And then there is ``LOOKUP_EMPTY``, which doesn't fit conceptually with the others. If this is not set, an empty pathname causes an error very early on. If it is set, empty pathnames are not considered to be an error. -### Global state flags ### +Global state flags +~~~~~~~~~~~~~~~~~~ -We have already met two global state flags: `LOOKUP_RCU` and -`LOOKUP_REVAL`. These select between one of three overall approaches +We have already met two global state flags: ``LOOKUP_RCU`` and +``LOOKUP_REVAL``. These select between one of three overall approaches to lookup: RCU-walk, REF-walk, and REF-walk with forced revalidation. -`LOOKUP_PARENT` indicates that the final component hasn't been reached +``LOOKUP_PARENT`` indicates that the final component hasn't been reached yet. This is primarily used to tell the audit subsystem the full context of a particular access being audited. -`LOOKUP_ROOT` indicates that the `root` field in the `nameidata` was +``LOOKUP_ROOT`` indicates that the ``root`` field in the ``nameidata`` was provided by the caller, so it shouldn't be released when it is no longer needed. -`LOOKUP_JUMPED` means that the current dentry was chosen not because +``LOOKUP_JUMPED`` means that the current dentry was chosen not because it had the right name but for some other reason. This happens when -following "`..`", following a symlink to `/`, crossing a mount point -or accessing a "`/proc/$PID/fd/$FD`" symlink. In this case the +following "``..``", following a symlink to ``/``, crossing a mount point +or accessing a "``/proc/$PID/fd/$FD``" symlink. In this case the filesystem has not been asked to revalidate the name (with -`d_revalidate()`). In such cases the inode may still need to be -revalidated, so `d_op->d_weak_revalidate()` is called if -`LOOKUP_JUMPED` is set when the look completes - which may be at the +``d_revalidate()``). In such cases the inode may still need to be +revalidated, so ``d_op->d_weak_revalidate()`` is called if +``LOOKUP_JUMPED`` is set when the look completes - which may be at the final component or, when creating, unlinking, or renaming, at the penultimate component. -### Final-component flags ### +Final-component flags +~~~~~~~~~~~~~~~~~~~~~ Some of these flags are only set when the final component is being considered. Others are only checked for when considering that final component. -`LOOKUP_AUTOMOUNT` ensures that, if the final component is an automount +``LOOKUP_AUTOMOUNT`` ensures that, if the final component is an automount point, then the mount is triggered. Some operations would trigger it -anyway, but operations like `stat()` deliberately don't. `statfs()` -needs to trigger the mount but otherwise behaves a lot like `stat()`, so -it sets `LOOKUP_AUTOMOUNT`, as does "`quotactl()`" and the handling of -"`mount --bind`". +anyway, but operations like ``stat()`` deliberately don't. ``statfs()`` +needs to trigger the mount but otherwise behaves a lot like ``stat()``, so +it sets ``LOOKUP_AUTOMOUNT``, as does "``quotactl()``" and the handling of +"``mount --bind``". -`LOOKUP_FOLLOW` has a similar function to `LOOKUP_AUTOMOUNT` but for +``LOOKUP_FOLLOW`` has a similar function to ``LOOKUP_AUTOMOUNT`` but for symlinks. Some system calls set or clear it implicitly, while -others have API flags such as `AT_SYMLINK_FOLLOW` and -`UMOUNT_NOFOLLOW` to control it. Its effect is similar to -`WALK_GET` that we already met, but it is used in a different way. +others have API flags such as ``AT_SYMLINK_FOLLOW`` and +``UMOUNT_NOFOLLOW`` to control it. Its effect is similar to +``WALK_GET`` that we already met, but it is used in a different way. -`LOOKUP_DIRECTORY` insists that the final component is a directory. +``LOOKUP_DIRECTORY`` insists that the final component is a directory. Various callers set this and it is also set when the final component is found to be followed by a slash. -Finally `LOOKUP_OPEN`, `LOOKUP_CREATE`, `LOOKUP_EXCL`, and -`LOOKUP_RENAME_TARGET` are not used directly by the VFS but are made -available to the filesystem and particularly the `->d_revalidate()` +Finally ``LOOKUP_OPEN``, ``LOOKUP_CREATE``, ``LOOKUP_EXCL``, and +``LOOKUP_RENAME_TARGET`` are not used directly by the VFS but are made +available to the filesystem and particularly the ``->d_revalidate()`` method. A filesystem can choose not to bother revalidating too hard if it knows that it will be asked to open or create the file soon. -These flags were previously useful for `->lookup()` too but with the -introduction of `->atomic_open()` they are less relevant there. +These flags were previously useful for ``->lookup()`` too but with the +introduction of ``->atomic_open()`` they are less relevant there. End of the road --------------- diff --git a/Documentation/filesystems/pohmelfs/design_notes.txt b/Documentation/filesystems/pohmelfs/design_notes.txt deleted file mode 100644 index 106d17fbb05f..000000000000 --- a/Documentation/filesystems/pohmelfs/design_notes.txt +++ /dev/null @@ -1,72 +0,0 @@ -POHMELFS: Parallel Optimized Host Message Exchange Layered File System. - - Evgeniy Polyakov <zbr@ioremap.net> - -Homepage: http://www.ioremap.net/projects/pohmelfs - -POHMELFS first began as a network filesystem with coherent local data and -metadata caches but is now evolving into a parallel distributed filesystem. - -Main features of this FS include: - * Locally coherent cache for data and metadata with (potentially) byte-range locks. - Since all Linux filesystems lock the whole inode during writing, algorithm - is very simple and does not use byte-ranges, although they are sent in - locking messages. - * Completely async processing of all events except creation of hard and symbolic - links, and rename events. - Object creation and data reading and writing are processed asynchronously. - * Flexible object architecture optimized for network processing. - Ability to create long paths to objects and remove arbitrarily huge - directories with a single network command. - (like removing the whole kernel tree via a single network command). - * Very high performance. - * Fast and scalable multithreaded userspace server. Being in userspace it works - with any underlying filesystem and still is much faster than async in-kernel NFS one. - * Client is able to switch between different servers (if one goes down, client - automatically reconnects to second and so on). - * Transactions support. Full failover for all operations. - Resending transactions to different servers on timeout or error. - * Read request (data read, directory listing, lookup requests) balancing between multiple servers. - * Write requests are replicated to multiple servers and completed only when all of them are acked. - * Ability to add and/or remove servers from the working set at run-time. - * Strong authentication and possible data encryption in network channel. - * Extended attributes support. - -POHMELFS is based on transactions, which are potentially long-standing objects that live -in the client's memory. Each transaction contains all the information needed to process a given -command (or set of commands, which is frequently used during data writing: single transactions -can contain creation and data writing commands). Transactions are committed by all the servers -to which they are sent and, in case of failures, are eventually resent or dropped with an error. -For example, reading will return an error if no servers are available. - -POHMELFS uses a asynchronous approach to data processing. Courtesy of transactions, it is -possible to detach replies from requests and, if the command requires data to be received, the -caller sleeps waiting for it. Thus, it is possible to issue multiple read commands to different -servers and async threads will pick up replies in parallel, find appropriate transactions in the -system and put the data where it belongs (like the page or inode cache). - -The main feature of POHMELFS is writeback data and the metadata cache. -Only a few non-performance critical operations use the write-through cache and -are synchronous: hard and symbolic link creation, and object rename. Creation, -removal of objects and data writing are asynchronous and are sent to -the server during system writeback. Only one writer at a time is allowed for any -given inode, which is guarded by an appropriate locking protocol. -Because of this feature, POHMELFS is extremely fast at metadata intensive -workloads and can fully utilize the bandwidth to the servers when doing bulk -data transfers. - -POHMELFS clients operate with a working set of servers and are capable of balancing read-only -operations (like lookups or directory listings) between them according to IO priorities. -Administrators can add or remove servers from the set at run-time via special commands (described -in Documentation/filesystems/pohmelfs/info.txt file). Writes are replicated to all servers, which -are connected with write permission turned on. IO priority and permissions can be changed in -run-time. - -POHMELFS is capable of full data channel encryption and/or strong crypto hashing. -One can select any kernel supported cipher, encryption mode, hash type and operation mode -(hmac or digest). It is also possible to use both or neither (default). Crypto configuration -is checked during mount time and, if the server does not support it, appropriate capabilities -will be disabled or mount will fail (if 'crypto_fail_unsupported' mount option is specified). -Crypto performance heavily depends on the number of crypto threads, which asynchronously perform -crypto operations and send the resulting data to server or submit it up the stack. This number -can be controlled via a mount option. diff --git a/Documentation/filesystems/pohmelfs/info.txt b/Documentation/filesystems/pohmelfs/info.txt deleted file mode 100644 index db2e41393626..000000000000 --- a/Documentation/filesystems/pohmelfs/info.txt +++ /dev/null @@ -1,99 +0,0 @@ -POHMELFS usage information. - -Mount options. -All but index, number of crypto threads and maximum IO size can changed via remount. - -idx=%u - Each mountpoint is associated with a special index via this option. - Administrator can add or remove servers from the given index, so all mounts, - which were attached to it, are updated. - Default it is 0. - -trans_scan_timeout=%u - This timeout, expressed in milliseconds, specifies time to scan transaction - trees looking for stale requests, which have to be resent, or if number of - retries exceed specified limit, dropped with error. - Default is 5 seconds. - -drop_scan_timeout=%u - Internal timeout, expressed in milliseconds, which specifies how frequently - inodes marked to be dropped are freed. It also specifies how frequently - the system checks that servers have to be added or removed from current working set. - Default is 1 second. - -wait_on_page_timeout=%u - Number of milliseconds to wait for reply from remote server for data reading command. - If this timeout is exceeded, reading returns an error. - Default is 5 seconds. - -trans_retries=%u - This is the number of times that a transaction will be resent to a server that did - not answer for the last @trans_scan_timeout milliseconds. - When the number of resends exceeds this limit, the transaction is completed with error. - Default is 5 resends. - -crypto_thread_num=%u - Number of crypto processing threads. Threads are used both for RX and TX traffic. - Default is 2, or no threads if crypto operations are not supported. - -trans_max_pages=%u - Maximum number of pages in a single transaction. This parameter also controls - the number of pages, allocated for crypto processing (each crypto thread has - pool of pages, the number of which is equal to 'trans_max_pages'. - Default is 100 pages. - -crypto_fail_unsupported - If specified, mount will fail if the server does not support requested crypto operations. - By default mount will disable non-matching crypto operations. - -mcache_timeout=%u - Maximum number of milliseconds to wait for the mcache objects to be processed. - Mcache includes locks (given lock should be granted by server), attributes (they should be - fully received in the given timeframe). - Default is 5 seconds. - -Usage examples. - -Add server server1.net:1025 into the working set with index $idx -with appropriate hash algorithm and key file and cipher algorithm, mode and key file: -$cfg A add -a server1.net -p 1025 -i $idx -K $hash_key -k $cipher_key - -Mount filesystem with given index $idx to /mnt mountpoint. -Client will connect to all servers specified in the working set via previous command: -mount -t pohmel -o idx=$idx q /mnt - -Change permissions to read-only (-I 1 option, '-I 2' - write-only, 3 - rw): -$cfg A modify -a server1.net -p 1025 -i $idx -I 1 - -Change IO priority to 123 (node with the highest priority gets read requests). -$cfg A modify -a server1.net -p 1025 -i $idx -P 123 - -One can check currect status of all connections in the mountstats file: -# cat /proc/$PID/mountstats -... -device none mounted on /mnt with fstype pohmel -idx addr(:port) socket_type protocol active priority permissions -0 server1.net:1026 1 6 1 250 1 -0 server2.net:1025 1 6 1 123 3 - -Server installation. - -Creating a server, which listens at port 1025 and 0.0.0.0 address. -Working root directory (note, that server chroots there, so you have to have appropriate permissions) -is set to /mnt, server will negotiate hash/cipher with client, in case client requested it, there -are appropriate key files. -Number of working threads is set to 10. - -# ./fserver -a 0.0.0.0 -p 1025 -r /mnt -w 10 -K hash_key -k cipher_key - - -A 6 - listen on ipv6 address. Default: Disabled. - -r root - path to root directory. Default: /tmp. - -a addr - listen address. Default: 0.0.0.0. - -p port - listen port. Default: 1025. - -w workers - number of workers per connected client. Default: 1. - -K file - hash key size. Default: none. - -k file - cipher key size. Default: none. - -h - this help. - -Number of worker threads specifies how many workers will be created for each client. -Bulk single-client transafers usually are better handled with smaller number (like 1-3). diff --git a/Documentation/filesystems/pohmelfs/network_protocol.txt b/Documentation/filesystems/pohmelfs/network_protocol.txt deleted file mode 100644 index c680b4b5353d..000000000000 --- a/Documentation/filesystems/pohmelfs/network_protocol.txt +++ /dev/null @@ -1,227 +0,0 @@ -POHMELFS network protocol. - -Basic structure used in network communication is following command: - -struct netfs_cmd -{ - __u16 cmd; /* Command number */ - __u16 csize; /* Attached crypto information size */ - __u16 cpad; /* Attached padding size */ - __u16 ext; /* External flags */ - __u32 size; /* Size of the attached data */ - __u32 trans; /* Transaction id */ - __u64 id; /* Object ID to operate on. Used for feedback.*/ - __u64 start; /* Start of the object. */ - __u64 iv; /* IV sequence */ - __u8 data[0]; -}; - -Commands can be embedded into transaction command (which in turn has own command), -so one can extend protocol as needed without breaking backward compatibility as long -as old commands are supported. All string lengths include tail 0 byte. - -All commands are transferred over the network in big-endian. CPU endianness is used at the end peers. - -@cmd - command number, which specifies command to be processed. Following - commands are used currently: - - NETFS_READDIR = 1, /* Read directory for given inode number */ - NETFS_READ_PAGE, /* Read data page from the server */ - NETFS_WRITE_PAGE, /* Write data page to the server */ - NETFS_CREATE, /* Create directory entry */ - NETFS_REMOVE, /* Remove directory entry */ - NETFS_LOOKUP, /* Lookup single object */ - NETFS_LINK, /* Create a link */ - NETFS_TRANS, /* Transaction */ - NETFS_OPEN, /* Open intent */ - NETFS_INODE_INFO, /* Metadata cache coherency synchronization message */ - NETFS_PAGE_CACHE, /* Page cache invalidation message */ - NETFS_READ_PAGES, /* Read multiple contiguous pages in one go */ - NETFS_RENAME, /* Rename object */ - NETFS_CAPABILITIES, /* Capabilities of the client, for example supported crypto */ - NETFS_LOCK, /* Distributed lock message */ - NETFS_XATTR_SET, /* Set extended attribute */ - NETFS_XATTR_GET, /* Get extended attribute */ - -@ext - external flags. Used by different commands to specify some extra arguments - like partial size of the embedded objects or creation flags. - -@size - size of the attached data. For NETFS_READ_PAGE and NETFS_READ_PAGES no data is attached, - but size of the requested data is incorporated here. It does not include size of the command - header (struct netfs_cmd) itself. - -@id - id of the object this command operates on. Each command can use it for own purpose. - -@start - start of the object this command operates on. Each command can use it for own purpose. - -@csize, @cpad - size and padding size of the (attached if needed) crypto information. - -Command specifications. - -@NETFS_READDIR -This command is used to sync content of the remote dir to the client. - -@ext - length of the path to object. -@size - the same. -@id - local inode number of the directory to read. -@start - zero. - - -@NETFS_READ_PAGE -This command is used to read data from remote server. -Data size does not exceed local page cache size. - -@id - inode number. -@start - first byte offset. -@size - number of bytes to read plus length of the path to object. -@ext - object path length. - - -@NETFS_CREATE -Used to create object. -It does not require that all directories on top of the object were -already created, it will create them automatically. Each object has -associated @netfs_path_entry data structure, which contains creation -mode (permissions and type) and length of the name as long as name itself. - -@start - 0 -@size - size of the all data structures needed to create a path -@id - local inode number -@ext - 0 - - -@NETFS_REMOVE -Used to remove object. - -@ext - length of the path to object. -@size - the same. -@id - local inode number. -@start - zero. - - -@NETFS_LOOKUP -Lookup information about object on server. - -@ext - length of the path to object. -@size - the same. -@id - local inode number of the directory to look object in. -@start - local inode number of the object to look at. - - -@NETFS_LINK -Create hard of symlink. -Command is sent as "object_path|target_path". - -@size - size of the above string. -@id - parent local inode number. -@start - 1 for symlink, 0 for hardlink. -@ext - size of the "object_path" above. - - -@NETFS_TRANS -Transaction header. - -@size - incorporates all embedded command sizes including theirs header sizes. -@start - transaction generation number - unique id used to find transaction. -@ext - transaction flags. Unused at the moment. -@id - 0. - - -@NETFS_OPEN -Open intent for given transaction. - -@id - local inode number. -@start - 0. -@size - path length to the object. -@ext - open flags (O_RDWR and so on). - - -@NETFS_INODE_INFO -Metadata update command. -It is sent to servers when attributes of the object are changed and received -when data or metadata were updated. It operates with the following structure: - -struct netfs_inode_info -{ - unsigned int mode; - unsigned int nlink; - unsigned int uid; - unsigned int gid; - unsigned int blocksize; - unsigned int padding; - __u64 ino; - __u64 blocks; - __u64 rdev; - __u64 size; - __u64 version; -}; - -It effectively mirrors stat(2) returned data. - - -@ext - path length to the object. -@size - the same plus size of the netfs_inode_info structure. -@id - local inode number. -@start - 0. - - -@NETFS_PAGE_CACHE -Command is only received by clients. It contains information about -page to be marked as not up-to-date. - -@id - client's inode number. -@start - last byte of the page to be invalidated. If it is not equal to - current inode size, it will be vmtruncated(). -@size - 0 -@ext - 0 - - -@NETFS_READ_PAGES -Used to read multiple contiguous pages in one go. - -@start - first byte of the contiguous region to read. -@size - contains of two fields: lower 8 bits are used to represent page cache shift - used by client, another 3 bytes are used to get number of pages. -@id - local inode number. -@ext - path length to the object. - - -@NETFS_RENAME -Used to rename object. -Attached data is formed into following string: "old_path|new_path". - -@id - local inode number. -@start - parent inode number. -@size - length of the above string. -@ext - length of the old path part. - - -@NETFS_CAPABILITIES -Used to exchange crypto capabilities with server. -If crypto capabilities are not supported by server, then client will disable it -or fail (if 'crypto_fail_unsupported' mount options was specified). - -@id - superblock index. Used to specify crypto information for group of servers. -@size - size of the attached capabilities structure. -@start - 0. -@size - 0. -@scsize - 0. - -@NETFS_LOCK -Used to send lock request/release messages. Although it sends byte range request -and is capable of flushing pages based on that, it is not used, since all Linux -filesystems lock the whole inode. - -@id - lock generation number. -@start - start of the locked range. -@size - size of the locked range. -@ext - lock type: read/write. Not used actually. 15'th bit is used to determine, - if it is lock request (1) or release (0). - -@NETFS_XATTR_SET -@NETFS_XATTR_GET -Used to set/get extended attributes for given inode. -@id - attribute generation number or xattr setting type -@start - size of the attribute (request or attached) -@size - name length, path len and data size for given attribute -@ext - path length for given object diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index 321d74b73937..cf43bc4dbf31 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -623,6 +623,11 @@ in your dentry operations instead. On success you get a new struct file sharing the mount/dentry with the original, on failure - ERR_PTR(). -- +[mandatory] + ->clone_file_range() and ->dedupe_file_range have been replaced with + ->remap_file_range(). See Documentation/filesystems/vfs.txt for more + information. +-- [recommended] ->lookup() instances doing an equivalent of if (IS_ERR(inode)) diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index 22b4b00dee31..66cad5c86171 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -125,6 +125,13 @@ process running on the system, which is named after the process ID (PID). The link self points to the process reading the file system. Each process subdirectory has the entries listed in Table 1-1. +Note that an open a file descriptor to /proc/<pid> or to any of its +contained files or subdirectories does not prevent <pid> being reused +for some other process in the event that <pid> exits. Operations on +open /proc/<pid> file descriptors corresponding to dead processes +never act on any new process that the kernel may, through chance, have +also assigned the process ID <pid>. Instead, operations on these FDs +usually fail with ESRCH. Table 1-1: Process specific entries in /proc .............................................................................. @@ -182,6 +189,7 @@ read the file /proc/PID/status: VmSwap: 0 kB HugetlbPages: 0 kB CoreDumping: 0 + THP_enabled: 1 Threads: 1 SigQ: 0/28578 SigPnd: 0000000000000000 @@ -193,8 +201,10 @@ read the file /proc/PID/status: CapPrm: 0000000000000000 CapEff: 0000000000000000 CapBnd: ffffffffffffffff + CapAmb: 0000000000000000 NoNewPrivs: 0 Seccomp: 0 + Speculation_Store_Bypass: thread vulnerable voluntary_ctxt_switches: 0 nonvoluntary_ctxt_switches: 1 @@ -214,7 +224,7 @@ asynchronous manner and the value may not be very precise. To see a precise snapshot of a moment, you can see /proc/<pid>/smaps file and scan page table. It's slow but very precise. -Table 1-2: Contents of the status files (as of 4.8) +Table 1-2: Contents of the status files (as of 4.19) .............................................................................. Field Content Name filename of the executable @@ -256,6 +266,8 @@ Table 1-2: Contents of the status files (as of 4.8) HugetlbPages size of hugetlb memory portions CoreDumping process's memory is currently being dumped (killing the process may lead to a corrupted core) + THP_enabled process is allowed to use THP (returns 0 when + PR_SET_THP_DISABLE is set on the process Threads number of threads SigQ number of signals queued/max. number for queue SigPnd bitmap of pending signals for the thread @@ -267,8 +279,10 @@ Table 1-2: Contents of the status files (as of 4.8) CapPrm bitmap of permitted capabilities CapEff bitmap of effective capabilities CapBnd bitmap of capabilities bounding set + CapAmb bitmap of ambient capabilities NoNewPrivs no_new_privs, like prctl(PR_GET_NO_NEW_PRIV, ...) Seccomp seccomp mode, like prctl(PR_GET_SECCOMP, ...) + Speculation_Store_Bypass speculative store bypass mitigation status Cpus_allowed mask of CPUs on which this process may run Cpus_allowed_list Same as previous, but in "list format" Mems_allowed mask of memory nodes allowed to this process @@ -425,6 +439,7 @@ SwapPss: 0 kB KernelPageSize: 4 kB MMUPageSize: 4 kB Locked: 0 kB +THPeligible: 0 VmFlags: rd ex mr mw me dw the first of these lines shows the same information as is displayed for the @@ -462,6 +477,8 @@ replaced by copy-on-write) part of the underlying shmem object out on swap. "SwapPss" shows proportional swap share of this mapping. Unlike "Swap", this does not take into account swapped out page of underlying shmem objects. "Locked" indicates whether the mapping is locked in memory or not. +"THPeligible" indicates whether the mapping is eligible for THP pages - 1 if +true, 0 otherwise. "VmFlags" field deserves a separate description. This member represents the kernel flags associated with the particular virtual memory area in two letter encoded @@ -496,7 +513,9 @@ manner. The codes are the following: Note that there is no guarantee that every flag and associated mnemonic will be present in all further kernel releases. Things get changed, the flags may -be vanished or the reverse -- new added. +be vanished or the reverse -- new added. Interpretation of their meaning +might change in future as well. So each consumer of these flags has to +follow each specific kernel version for the exact semantic. This file is only present if the CONFIG_MMU kernel configuration option is enabled. @@ -858,6 +877,7 @@ Writeback: 0 kB AnonPages: 861800 kB Mapped: 280372 kB Shmem: 644 kB +KReclaimable: 168048 kB Slab: 284364 kB SReclaimable: 159856 kB SUnreclaim: 124508 kB @@ -925,6 +945,9 @@ AnonHugePages: Non-file backed huge pages mapped into userspace page tables ShmemHugePages: Memory used by shared memory (shmem) and tmpfs allocated with huge pages ShmemPmdMapped: Shared memory mapped into userspace with huge pages +KReclaimable: Kernel allocations that the kernel will attempt to reclaim + under memory pressure. Includes SReclaimable (below), and other + direct allocations with a shrinker. Slab: in-kernel data structures cache SReclaimable: Part of Slab, that might be reclaimed, such as caches SUnreclaim: Part of Slab, that cannot be reclaimed on memory pressure diff --git a/Documentation/filesystems/qnx6.txt b/Documentation/filesystems/qnx6.txt index 4f3d6a882bdc..48ea68f15845 100644 --- a/Documentation/filesystems/qnx6.txt +++ b/Documentation/filesystems/qnx6.txt @@ -87,7 +87,7 @@ addressed with 16 direct blocks. For more than 16 blocks an indirect addressing in form of another tree is used. (scheme is the same as the one used for the superblock root nodes) -The filesize is stored 64bit. Inode counting starts with 1. (whilst long +The filesize is stored 64bit. Inode counting starts with 1. (while long filename inodes start with 0) Directories @@ -155,7 +155,7 @@ Then userspace. The requirement for a static, fixed preallocated system area comes from how qnx6fs deals with writes. Each superblock got it's own half of the system area. So superblock #1 -always uses blocks from the lower half whilst superblock #2 just writes to +always uses blocks from the lower half while superblock #2 just writes to blocks represented by the upper half bitmap system area bits. Bitmap blocks, Inode blocks and indirect addressing blocks for those two diff --git a/Documentation/filesystems/spufs.txt b/Documentation/filesystems/spufs.txt index 1343d118a9b2..eb9e3aa63026 100644 --- a/Documentation/filesystems/spufs.txt +++ b/Documentation/filesystems/spufs.txt @@ -452,7 +452,7 @@ RETURN VALUE ERRORS - EACCESS + EACCES The current user does not have write access on the spufs mount point. diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index a1426cabcef1..41411b0c60a3 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -344,7 +344,9 @@ struct bus_attribute { Declaring: -BUS_ATTR(_name, _mode, _show, _store) +static BUS_ATTR_RW(name); +static BUS_ATTR_RO(name); +static BUS_ATTR_WO(name); Creation/Removal: diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.md new file mode 100644 index 000000000000..028b3e2e25f9 --- /dev/null +++ b/Documentation/filesystems/ubifs-authentication.md @@ -0,0 +1,426 @@ +% UBIFS Authentication +% sigma star gmbh +% 2018 + +# Introduction + +UBIFS utilizes the fscrypt framework to provide confidentiality for file +contents and file names. This prevents attacks where an attacker is able to +read contents of the filesystem on a single point in time. A classic example +is a lost smartphone where the attacker is unable to read personal data stored +on the device without the filesystem decryption key. + +At the current state, UBIFS encryption however does not prevent attacks where +the attacker is able to modify the filesystem contents and the user uses the +device afterwards. In such a scenario an attacker can modify filesystem +contents arbitrarily without the user noticing. One example is to modify a +binary to perform a malicious action when executed [DMC-CBC-ATTACK]. Since +most of the filesystem metadata of UBIFS is stored in plain, this makes it +fairly easy to swap files and replace their contents. + +Other full disk encryption systems like dm-crypt cover all filesystem metadata, +which makes such kinds of attacks more complicated, but not impossible. +Especially, if the attacker is given access to the device multiple points in +time. For dm-crypt and other filesystems that build upon the Linux block IO +layer, the dm-integrity or dm-verity subsystems [DM-INTEGRITY, DM-VERITY] +can be used to get full data authentication at the block layer. +These can also be combined with dm-crypt [CRYPTSETUP2]. + +This document describes an approach to get file contents _and_ full metadata +authentication for UBIFS. Since UBIFS uses fscrypt for file contents and file +name encryption, the authentication system could be tied into fscrypt such that +existing features like key derivation can be utilized. It should however also +be possible to use UBIFS authentication without using encryption. + + +## MTD, UBI & UBIFS + +On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform +interface to access raw flash devices. One of the more prominent subsystems that +work on top of MTD is UBI (Unsorted Block Images). It provides volume management +for flash devices and is thus somewhat similar to LVM for block devices. In +addition, it deals with flash-specific wear-leveling and transparent I/O error +handling. UBI offers logical erase blocks (LEBs) to the layers on top of it +and maps them transparently to physical erase blocks (PEBs) on the flash. + +UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear +leveling and some flash specifics are left to UBI, while UBIFS focuses on +scalability, performance and recoverability. + + + + +------------+ +*******+ +-----------+ +-----+ + | | * UBIFS * | UBI-BLOCK | | ... | + | JFFS/JFFS2 | +*******+ +-----------+ +-----+ + | | +-----------------------------+ +-----------+ +-----+ + | | | UBI | | MTD-BLOCK | | ... | + +------------+ +-----------------------------+ +-----------+ +-----+ + +------------------------------------------------------------------+ + | MEMORY TECHNOLOGY DEVICES (MTD) | + +------------------------------------------------------------------+ + +-----------------------------+ +--------------------------+ +-----+ + | NAND DRIVERS | | NOR DRIVERS | | ... | + +-----------------------------+ +--------------------------+ +-----+ + + Figure 1: Linux kernel subsystems for dealing with raw flash + + + +Internally, UBIFS maintains multiple data structures which are persisted on +the flash: + +- *Index*: an on-flash B+ tree where the leaf nodes contain filesystem data +- *Journal*: an additional data structure to collect FS changes before updating + the on-flash index and reduce flash wear. +- *Tree Node Cache (TNC)*: an in-memory B+ tree that reflects the current FS + state to avoid frequent flash reads. It is basically the in-memory + representation of the index, but contains additional attributes. +- *LEB property tree (LPT)*: an on-flash B+ tree for free space accounting per + UBI LEB. + +In the remainder of this section we will cover the on-flash UBIFS data +structures in more detail. The TNC is of less importance here since it is never +persisted onto the flash directly. More details on UBIFS can also be found in +[UBIFS-WP]. + + +### UBIFS Index & Tree Node Cache + +Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types +of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file +contents or inode nodes (`struct ubifs_ino_node`) which represent VFS inodes. +Almost all types of nodes share a common header (`ubifs_ch`) containing basic +information like node type, node length, a sequence number, etc. (see +`fs/ubifs/ubifs-media.h`in kernel source). Exceptions are entries of the LPT +and some less important node types like padding nodes which are used to pad +unusable content at the end of LEBs. + +To avoid re-writing the whole B+ tree on every single change, it is implemented +as *wandering tree*, where only the changed nodes are re-written and previous +versions of them are obsoleted without erasing them right away. As a result, +the index is not stored in a single place on the flash, but *wanders* around +and there are obsolete parts on the flash as long as the LEB containing them is +not reused by UBIFS. To find the most recent version of the index, UBIFS stores +a special node called *master node* into UBI LEB 1 which always points to the +most recent root node of the UBIFS index. For recoverability, the master node +is additionally duplicated to LEB 2. Mounting UBIFS is thus a simple read of +LEB 1 and 2 to get the current master node and from there get the location of +the most recent on-flash index. + +The TNC is the in-memory representation of the on-flash index. It contains some +additional runtime attributes per node which are not persisted. One of these is +a dirty-flag which marks nodes that have to be persisted the next time the +index is written onto the flash. The TNC acts as a write-back cache and all +modifications of the on-flash index are done through the TNC. Like other caches, +the TNC does not have to mirror the full index into memory, but reads parts of +it from flash whenever needed. A *commit* is the UBIFS operation of updating the +on-flash filesystem structures like the index. On every commit, the TNC nodes +marked as dirty are written to the flash to update the persisted index. + + +### Journal + +To avoid wearing out the flash, the index is only persisted (*commited*) when +certain conditions are met (eg. `fsync(2)`). The journal is used to record +any changes (in form of inode nodes, data nodes etc.) between commits +of the index. During mount, the journal is read from the flash and replayed +onto the TNC (which will be created on-demand from the on-flash index). + +UBIFS reserves a bunch of LEBs just for the journal called *log area*. The +amount of log area LEBs is configured on filesystem creation (using +`mkfs.ubifs`) and stored in the superblock node. The log area contains only +two types of nodes: *reference nodes* and *commit start nodes*. A commit start +node is written whenever an index commit is performed. Reference nodes are +written on every journal update. Each reference node points to the position of +other nodes (inode nodes, data nodes etc.) on the flash that are part of this +journal entry. These nodes are called *buds* and describe the actual filesystem +changes including their data. + +The log area is maintained as a ring. Whenever the journal is almost full, +a commit is initiated. This also writes a commit start node so that during +mount, UBIFS will seek for the most recent commit start node and just replay +every reference node after that. Every reference node before the commit start +node will be ignored as they are already part of the on-flash index. + +When writing a journal entry, UBIFS first ensures that enough space is +available to write the reference node and buds part of this entry. Then, the +reference node is written and afterwards the buds describing the file changes. +On replay, UBIFS will record every reference node and inspect the location of +the referenced LEBs to discover the buds. If these are corrupt or missing, +UBIFS will attempt to recover them by re-reading the LEB. This is however only +done for the last referenced LEB of the journal. Only this can become corrupt +because of a power cut. If the recovery fails, UBIFS will not mount. An error +for every other LEB will directly cause UBIFS to fail the mount operation. + + + | ---- LOG AREA ---- | ---------- MAIN AREA ------------ | + + -----+------+-----+--------+---- ------+-----+-----+--------------- + \ | | | | / / | | | \ + / CS | REF | REF | | \ \ DENT | INO | INO | / + \ | | | | / / | | | \ + ----+------+-----+--------+--- -------+-----+-----+---------------- + | | ^ ^ + | | | | + +------------------------+ | + | | + +-------------------------------+ + + + Figure 2: UBIFS flash layout of log area with commit start nodes + (CS) and reference nodes (REF) pointing to main area + containing their buds + + +### LEB Property Tree/Table + +The LEB property tree is used to store per-LEB information. This includes the +LEB type and amount of free and *dirty* (old, obsolete content) space [1] on +the LEB. The type is important, because UBIFS never mixes index nodes with data +nodes on a single LEB and thus each LEB has a specific purpose. This again is +useful for free space calculations. See [UBIFS-WP] for more details. + +The LEB property tree again is a B+ tree, but it is much smaller than the +index. Due to its smaller size it is always written as one chunk on every +commit. Thus, saving the LPT is an atomic operation. + + +[1] Since LEBs can only be appended and never overwritten, there is a +difference between free space ie. the remaining space left on the LEB to be +written to without erasing it and previously written content that is obsolete +but can't be overwritten without erasing the full LEB. + + +# UBIFS Authentication + +This chapter introduces UBIFS authentication which enables UBIFS to verify +the authenticity and integrity of metadata and file contents stored on flash. + + +## Threat Model + +UBIFS authentication enables detection of offline data modification. While it +does not prevent it, it enables (trusted) code to check the integrity and +authenticity of on-flash file contents and filesystem metadata. This covers +attacks where file contents are swapped. + +UBIFS authentication will not protect against rollback of full flash contents. +Ie. an attacker can still dump the flash and restore it at a later time without +detection. It will also not protect against partial rollback of individual +index commits. That means that an attacker is able to partially undo changes. +This is possible because UBIFS does not immediately overwrites obsolete +versions of the index tree or the journal, but instead marks them as obsolete +and garbage collection erases them at a later time. An attacker can use this by +erasing parts of the current tree and restoring old versions that are still on +the flash and have not yet been erased. This is possible, because every commit +will always write a new version of the index root node and the master node +without overwriting the previous version. This is further helped by the +wear-leveling operations of UBI which copies contents from one physical +eraseblock to another and does not atomically erase the first eraseblock. + +UBIFS authentication does not cover attacks where an attacker is able to +execute code on the device after the authentication key was provided. +Additional measures like secure boot and trusted boot have to be taken to +ensure that only trusted code is executed on a device. + + +## Authentication + +To be able to fully trust data read from flash, all UBIFS data structures +stored on flash are authenticated. That is: + +- The index which includes file contents, file metadata like extended + attributes, file length etc. +- The journal which also contains file contents and metadata by recording changes + to the filesystem +- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting + + +### Index Authentication + +Through UBIFS' concept of a wandering tree, it already takes care of only +updating and persisting changed parts from leaf node up to the root node +of the full B+ tree. This enables us to augment the index nodes of the tree +with a hash over each node's child nodes. As a result, the index basically also +a Merkle tree. Since the leaf nodes of the index contain the actual filesystem +data, the hashes of their parent index nodes thus cover all the file contents +and file metadata. When a file changes, the UBIFS index is updated accordingly +from the leaf nodes up to the root node including the master node. This process +can be hooked to recompute the hash only for each changed node at the same time. +Whenever a file is read, UBIFS can verify the hashes from each leaf node up to +the root node to ensure the node's integrity. + +To ensure the authenticity of the whole index, the UBIFS master node stores a +keyed hash (HMAC) over its own contents and a hash of the root node of the index +tree. As mentioned above, the master node is always written to the flash whenever +the index is persisted (ie. on index commit). + +Using this approach only UBIFS index nodes and the master node are changed to +include a hash. All other types of nodes will remain unchanged. This reduces +the storage overhead which is precious for users of UBIFS (ie. embedded +devices). + + + +---------------+ + | Master Node | + | (hash) | + +---------------+ + | + v + +-------------------+ + | Index Node #1 | + | | + | branch0 branchn | + | (hash) (hash) | + +-------------------+ + | ... | (fanout: 8) + | | + +-------+ +------+ + | | + v v + +-------------------+ +-------------------+ + | Index Node #2 | | Index Node #3 | + | | | | + | branch0 branchn | | branch0 branchn | + | (hash) (hash) | | (hash) (hash) | + +-------------------+ +-------------------+ + | ... | ... | + v v v + +-----------+ +----------+ +-----------+ + | Data Node | | INO Node | | DENT Node | + +-----------+ +----------+ +-----------+ + + + Figure 3: Coverage areas of index node hash and master node HMAC + + + +The most important part for robustness and power-cut safety is to atomically +persist the hash and file contents. Here the existing UBIFS logic for how +changed nodes are persisted is already designed for this purpose such that +UBIFS can safely recover if a power-cut occurs while persisting. Adding +hashes to index nodes does not change this since each hash will be persisted +atomically together with its respective node. + + +### Journal Authentication + +The journal is authenticated too. Since the journal is continuously written +it is necessary to also add authentication information frequently to the +journal so that in case of a powercut not too much data can't be authenticated. +This is done by creating a continuous hash beginning from the commit start node +over the previous reference nodes, the current reference node, and the bud +nodes. From time to time whenever it is suitable authentication nodes are added +between the bud nodes. This new node type contains a HMAC over the current state +of the hash chain. That way a journal can be authenticated up to the last +authentication node. The tail of the journal which may not have a authentication +node cannot be authenticated and is skipped during journal replay. + +We get this picture for journal authentication: + + ,,,,,,,, + ,......,........................................... + ,. CS , hash1.----. hash2.----. + ,. | , . |hmac . |hmac + ,. v , . v . v + ,.REF#0,-> bud -> bud -> bud.-> auth -> bud -> bud.-> auth ... + ,..|...,........................................... + , | , + , | ,,,,,,,,,,,,,,, + . | hash3,----. + , | , |hmac + , v , v + , REF#1 -> bud -> bud,-> auth ... + ,,,|,,,,,,,,,,,,,,,,,, + v + REF#2 -> ... + | + V + ... + +Since the hash also includes the reference nodes an attacker cannot reorder or +skip any journal heads for replay. An attacker can only remove bud nodes or +reference nodes from the end of the journal, effectively rewinding the +filesystem at maximum back to the last commit. + +The location of the log area is stored in the master node. Since the master +node is authenticated with a HMAC as described above, it is not possible to +tamper with that without detection. The size of the log area is specified when +the filesystem is created using `mkfs.ubifs` and stored in the superblock node. +To avoid tampering with this and other values stored there, a HMAC is added to +the superblock struct. The superblock node is stored in LEB 0 and is only +modified on feature flag or similar changes, but never on file changes. + + +### LPT Authentication + +The location of the LPT root node on the flash is stored in the UBIFS master +node. Since the LPT is written and read atomically on every commit, there is +no need to authenticate individual nodes of the tree. It suffices to +protect the integrity of the full LPT by a simple hash stored in the master +node. Since the master node itself is authenticated, the LPTs authenticity can +be verified by verifying the authenticity of the master node and comparing the +LTP hash stored there with the hash computed from the read on-flash LPT. + + +## Key Management + +For simplicity, UBIFS authentication uses a single key to compute the HMACs +of superblock, master, commit start and reference nodes. This key has to be +available on creation of the filesystem (`mkfs.ubifs`) to authenticate the +superblock node. Further, it has to be available on mount of the filesystem +to verify authenticated nodes and generate new HMACs for changes. + +UBIFS authentication is intended to operate side-by-side with UBIFS encryption +(fscrypt) to provide confidentiality and authenticity. Since UBIFS encryption +has a different approach of encryption policies per directory, there can be +multiple fscrypt master keys and there might be folders without encryption. +UBIFS authentication on the other hand has an all-or-nothing approach in the +sense that it either authenticates everything of the filesystem or nothing. +Because of this and because UBIFS authentication should also be usable without +encryption, it does not share the same master key with fscrypt, but manages +a dedicated authentication key. + +The API for providing the authentication key has yet to be defined, but the +key can eg. be provided by userspace through a keyring similar to the way it +is currently done in fscrypt. It should however be noted that the current +fscrypt approach has shown its flaws and the userspace API will eventually +change [FSCRYPT-POLICY2]. + +Nevertheless, it will be possible for a user to provide a single passphrase +or key in userspace that covers UBIFS authentication and encryption. This can +be solved by the corresponding userspace tools which derive a second key for +authentication in addition to the derived fscrypt master key used for +encryption. + +To be able to check if the proper key is available on mount, the UBIFS +superblock node will additionally store a hash of the authentication key. This +approach is similar to the approach proposed for fscrypt encryption policy v2 +[FSCRYPT-POLICY2]. + + +# Future Extensions + +In certain cases where a vendor wants to provide an authenticated filesystem +image to customers, it should be possible to do so without sharing the secret +UBIFS authentication key. Instead, in addition the each HMAC a digital +signature could be stored where the vendor shares the public key alongside the +filesystem image. In case this filesystem has to be modified afterwards, +UBIFS can exchange all digital signatures with HMACs on first mount similar +to the way the IMA/EVM subsystem deals with such situations. The HMAC key +will then have to be provided beforehand in the normal way. + + +# References + +[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html + +[DMC-CBC-ATTACK] http://www.jakoblell.com/blog/2013/12/22/practical-malleability-attack-against-cbc-encrypted-luks-partitions/ + +[DM-INTEGRITY] https://www.kernel.org/doc/Documentation/device-mapper/dm-integrity.txt + +[DM-VERITY] https://www.kernel.org/doc/Documentation/device-mapper/verity.txt + +[FSCRYPT-POLICY2] https://www.spinics.net/lists/linux-ext4/msg58710.html + +[UBIFS-WP] http://www.linux-mtd.infradead.org/doc/ubifs_whitepaper.pdf diff --git a/Documentation/filesystems/ubifs.txt b/Documentation/filesystems/ubifs.txt index a0a61d2f389f..acc80442a3bb 100644 --- a/Documentation/filesystems/ubifs.txt +++ b/Documentation/filesystems/ubifs.txt @@ -91,6 +91,13 @@ chk_data_crc do not skip checking CRCs on data nodes compr=none override default compressor and set it to "none" compr=lzo override default compressor and set it to "lzo" compr=zlib override default compressor and set it to "zlib" +auth_key= specify the key used for authenticating the filesystem. + Passing this option makes authentication mandatory. + The passed key must be present in the kernel keyring + and must be of type 'logon' +auth_hash_name= The hash algorithm used for authentication. Used for + both hashing and for creating HMACs. Typical values + include "sha256" or "sha512" Quick usage instructions diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index a6c6a8af48a2..761c6fd24a53 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -857,6 +857,7 @@ struct file_operations { ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); + int (*iopoll)(struct kiocb *kiocb, bool spin); int (*iterate) (struct file *, struct dir_context *); int (*iterate_shared) (struct file *, struct dir_context *); __poll_t (*poll) (struct file *, struct poll_table_struct *); @@ -883,8 +884,9 @@ struct file_operations { unsigned (*mmap_capabilities)(struct file *); #endif ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t, size_t, unsigned int); - int (*clone_file_range)(struct file *, loff_t, struct file *, loff_t, u64); - int (*dedupe_file_range)(struct file *, loff_t, struct file *, loff_t, u64); + loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in, + struct file *file_out, loff_t pos_out, + loff_t len, unsigned int remap_flags); int (*fadvise)(struct file *, loff_t, loff_t, int); }; @@ -901,6 +903,8 @@ otherwise noted. write_iter: possibly asynchronous write with iov_iter as source + iopoll: called when aio wants to poll for completions on HIPRI iocbs + iterate: called when the VFS needs to read the directory contents iterate_shared: called when the VFS needs to read the directory contents @@ -960,11 +964,18 @@ otherwise noted. copy_file_range: called by the copy_file_range(2) system call. - clone_file_range: called by the ioctl(2) system call for FICLONERANGE and - FICLONE commands. - - dedupe_file_range: called by the ioctl(2) system call for FIDEDUPERANGE - command. + remap_file_range: called by the ioctl(2) system call for FICLONERANGE and + FICLONE and FIDEDUPERANGE commands to remap file ranges. An + implementation should remap len bytes at pos_in of the source file into + the dest file at pos_out. Implementations must handle callers passing + in len == 0; this means "remap to the end of the source file". The + return value should the number of bytes remapped, or the usual + negative error code if errors occurred before any bytes were remapped. + The remap_flags parameter accepts REMAP_FILE_* flags. If + REMAP_FILE_DEDUP is set then the implementation must only remap if the + requested file ranges have identical contents. If REMAP_CAN_SHORTEN is + set, the caller is ok with the implementation shortening the request + length to satisfy alignment or EOF requirements (or any other reason). fadvise: possibly called by the fadvise64() system call. @@ -1123,7 +1134,7 @@ struct dentry_operations { d_manage: called to allow the filesystem to manage the transition from a dentry (optional). This allows autofs, for example, to hold up clients - waiting to explore behind a 'mountpoint' whilst letting the daemon go + waiting to explore behind a 'mountpoint' while letting the daemon go past and construct the subtree there. 0 should be returned to let the calling process continue. -EISDIR can be returned to tell pathwalk to use this directory as an ordinary directory and to ignore anything diff --git a/Documentation/filesystems/xfs-self-describing-metadata.txt b/Documentation/filesystems/xfs-self-describing-metadata.txt index 05aa455163e3..68604e67a495 100644 --- a/Documentation/filesystems/xfs-self-describing-metadata.txt +++ b/Documentation/filesystems/xfs-self-describing-metadata.txt @@ -110,7 +110,7 @@ owner field in the metadata object, we can immediately do top down validation to determine the scope of the problem. Different types of metadata have different owner identifiers. For example, -directory, attribute and extent tree blocks are all owned by an inode, whilst +directory, attribute and extent tree blocks are all owned by an inode, while freespace btree blocks are owned by an allocation group. Hence the size and contents of the owner field are determined by the type of metadata object we are looking at. The owner information can also identify misplaced writes (e.g. diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt index a9ae82fb9d13..a5cbb5e0e3db 100644 --- a/Documentation/filesystems/xfs.txt +++ b/Documentation/filesystems/xfs.txt @@ -272,7 +272,7 @@ The following sysctls are available for the XFS filesystem: XFS_ERRLEVEL_LOW: 1 XFS_ERRLEVEL_HIGH: 5 - fs.xfs.panic_mask (Min: 0 Default: 0 Max: 255) + fs.xfs.panic_mask (Min: 0 Default: 0 Max: 256) Causes certain error conditions to call BUG(). Value is a bitmask; OR together the tags which represent errors which should cause panics: @@ -285,6 +285,7 @@ The following sysctls are available for the XFS filesystem: XFS_PTAG_SHUTDOWN_IOERROR 0x00000020 XFS_PTAG_SHUTDOWN_LOGERROR 0x00000040 XFS_PTAG_FSBLOCK_ZERO 0x00000080 + XFS_PTAG_VERIFIER_ERROR 0x00000100 This option is intended for debugging only. @@ -417,7 +418,7 @@ level directory: filesystem from ever unmounting fully in the case of "retry forever" handler configurations. - Note: there is no guarantee that fail_at_unmount can be set whilst an + Note: there is no guarantee that fail_at_unmount can be set while an unmount is in progress. It is possible that the sysfs entries are removed by the unmounting filesystem before a "retry forever" error handler configuration causes unmount to hang, and hence the filesystem diff --git a/Documentation/gpu/afbc.rst b/Documentation/gpu/afbc.rst new file mode 100644 index 000000000000..4d38dc49d105 --- /dev/null +++ b/Documentation/gpu/afbc.rst @@ -0,0 +1,235 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=================================== + Arm Framebuffer Compression (AFBC) +=================================== + +AFBC is a proprietary lossless image compression protocol and format. +It provides fine-grained random access and minimizes the amount of +data transferred between IP blocks. + +AFBC can be enabled on drivers which support it via use of the AFBC +format modifiers defined in drm_fourcc.h. See DRM_FORMAT_MOD_ARM_AFBC(*). + +All users of the AFBC modifiers must follow the usage guidelines laid +out in this document, to ensure compatibility across different AFBC +producers and consumers. + +Components and Ordering +======================= + +AFBC streams can contain several components - where a component +corresponds to a color channel (i.e. R, G, B, X, A, Y, Cb, Cr). +The assignment of input/output color channels must be consistent +between the encoder and the decoder for correct operation, otherwise +the consumer will interpret the decoded data incorrectly. + +Furthermore, when the lossless colorspace transform is used +(AFBC_FORMAT_MOD_YTR, which should be enabled for RGB buffers for +maximum compression efficiency), the component order must be: + + * Component 0: R + * Component 1: G + * Component 2: B + +The component ordering is communicated via the fourcc code in the +fourcc:modifier pair. In general, component '0' is considered to +reside in the least-significant bits of the corresponding linear +format. For example, COMP(bits): + + * DRM_FORMAT_ABGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * DRM_FORMAT_BGR888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * DRM_FORMAT_YUYV + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + +In AFBC, 'X' components are not treated any differently from any other +component. Therefore, an AFBC buffer with fourcc DRM_FORMAT_XBGR8888 +encodes with 4 components, like so: + + * DRM_FORMAT_XBGR8888 + + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: X(8) + +Please note, however, that the inclusion of a "wasted" 'X' channel is +bad for compression efficiency, and so it's recommended to avoid +formats containing 'X' bits. If a fourth component is +required/expected by the encoder/decoder, then it is recommended to +instead use an equivalent format with alpha, setting all alpha bits to +'1'. If there is no requirement for a fourth component, then a format +which doesn't include alpha can be used, e.g. DRM_FORMAT_BGR888. + +Number of Planes +================ + +Formats which are typically multi-planar in linear layouts (e.g. YUV +420), can be encoded into one, or multiple, AFBC planes. As with +component order, the encoder and decoder must agree about the number +of planes in order to correctly decode the buffer. The fourcc code is +used to determine the number of encoded planes in an AFBC buffer, +matching the number of planes for the linear (unmodified) format. +Within each plane, the component ordering also follows the fourcc +code: + +For example: + + * DRM_FORMAT_YUYV: nplanes = 1 + + * Plane 0: + + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * DRM_FORMAT_NV12: nplanes = 2 + + * Plane 0: + + * Component 0: Y(8) + + * Plane 1: + + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + +Cross-device interoperability +============================= + +For maximum compatibility across devices, the table below defines +canonical formats for use between AFBC-enabled devices. Formats which +are listed here must be used exactly as specified when using the AFBC +modifiers. Formats which are not listed should be avoided. + +.. flat-table:: AFBC formats + + * - Fourcc code + - Description + - Planes/Components + + * - DRM_FORMAT_ABGR2101010 + - 10-bit per component RGB, with 2-bit alpha + - Plane 0: 4 components + * Component 0: R(10) + * Component 1: G(10) + * Component 2: B(10) + * Component 3: A(2) + + * - DRM_FORMAT_ABGR8888 + - 8-bit per component RGB, with 8-bit alpha + - Plane 0: 4 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + * Component 3: A(8) + + * - DRM_FORMAT_BGR888 + - 8-bit per component RGB + - Plane 0: 3 components + * Component 0: R(8) + * Component 1: G(8) + * Component 2: B(8) + + * - DRM_FORMAT_BGR565 + - 5/6-bit per component RGB + - Plane 0: 3 components + * Component 0: R(5) + * Component 1: G(6) + * Component 2: B(5) + + * - DRM_FORMAT_ABGR1555 + - 5-bit per component RGB, with 1-bit alpha + - Plane 0: 4 components + * Component 0: R(5) + * Component 1: G(5) + * Component 2: B(5) + * Component 3: A(1) + + * - DRM_FORMAT_VUY888 + - 8-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8) + * Component 2: Cr(8) + + * - DRM_FORMAT_VUY101010 + - 10-bit per component YCbCr 444, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10) + * Component 2: Cr(10) + + * - DRM_FORMAT_YUYV + - 8-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x1 subsampled) + * Component 2: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_NV16 + - 8-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x1 subsampled) + * Component 1: Cr(8, 2x1 subsampled) + + * - DRM_FORMAT_Y210 + - 10-bit per component YCbCr 422, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x1 subsampled) + * Component 2: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_P210 + - 10-bit per component YCbCr 422, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x1 subsampled) + * Component 1: Cr(10, 2x1 subsampled) + + * - DRM_FORMAT_YUV420_8BIT + - 8-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(8) + * Component 1: Cb(8, 2x2 subsampled) + * Component 2: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_YUV420_10BIT + - 10-bit per component YCbCr 420, single plane + - Plane 0: 3 components + * Component 0: Y(10) + * Component 1: Cb(10, 2x2 subsampled) + * Component 2: Cr(10, 2x2 subsampled) + + * - DRM_FORMAT_NV12 + - 8-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(8) + Plane 1: 2 components + * Component 0: Cb(8, 2x2 subsampled) + * Component 1: Cr(8, 2x2 subsampled) + + * - DRM_FORMAT_P010 + - 10-bit per component YCbCr 420, two plane + - Plane 0: 1 component + * Component 0: Y(10) + Plane 1: 2 components + * Component 0: Cb(10, 2x2 subsampled) + * Component 1: Cr(10, 2x2 subsampled) diff --git a/Documentation/gpu/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc.rst new file mode 100644 index 000000000000..cc89b0fc11df --- /dev/null +++ b/Documentation/gpu/amdgpu-dc.rst @@ -0,0 +1,68 @@ +=================================== +drm/amd/display - Display Core (DC) +=================================== + +*placeholder - general description of supported platforms, what dc is, etc.* + +Because it is partially shared with other operating systems, the Display Core +Driver is divided in two pieces. + +1. **Display Core (DC)** contains the OS-agnostic components. Things like + hardware programming and resource management are handled here. +2. **Display Manager (DM)** contains the OS-dependent components. Hooks to the + amdgpu base driver and DRM are implemented here. + +It doesn't help that the entire package is frequently referred to as DC. But +with the context in mind, it should be clear. + +When CONFIG_DRM_AMD_DC is enabled, DC will be initialized by default for +supported ASICs. To force disable, set `amdgpu.dc=0` on kernel command line. +Likewise, to force enable on unsupported ASICs, set `amdgpu.dc=1`. + +To determine if DC is loaded, search dmesg for the following entry: + +``Display Core initialized with <version number here>`` + +AMDgpu Display Manager +====================== + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h + :internal: + +Lifecycle +--------- + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: DM Lifecycle + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: dm_hw_init dm_hw_fini + +Interrupts +---------- + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm_irq.c + :internal: + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: register_hpd_handlers dm_crtc_high_irq dm_pflip_high_irq + +Atomic Implementation +--------------------- + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :doc: atomic + +.. kernel-doc:: drivers/gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c + :functions: amdgpu_dm_atomic_check amdgpu_dm_atomic_commit_tail + +Display Core +============ + +**WIP** diff --git a/Documentation/gpu/dp-mst/topology-figure-1.dot b/Documentation/gpu/dp-mst/topology-figure-1.dot new file mode 100644 index 000000000000..157e17c7e0b0 --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-1.dot @@ -0,0 +1,52 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + driver -> {payload1, payload2} [dir=none]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4; + + payload1:s -> port1:e; + payload2:s -> port3:e; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + } + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue]; + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen;shape=oval]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen;shape=oval]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen;shape=oval]; + mstb4 [label="MSTB #4";style=filled;fillcolor=palegreen;shape=oval]; + + port1 [label="Port #1";shape=oval]; + port2 [label="Port #2";shape=oval]; + port3 [label="Port #3";shape=oval]; + port4 [label="Port #4";shape=oval]; +} diff --git a/Documentation/gpu/dp-mst/topology-figure-2.dot b/Documentation/gpu/dp-mst/topology-figure-2.dot new file mode 100644 index 000000000000..4243dd1737cb --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-2.dot @@ -0,0 +1,56 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + driver -> {payload1, payload2} [dir=none]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4 [color=red]; + + payload1:s -> port1:e; + payload2:s -> port3:e; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + edge [color=red]; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + edge [color=""]; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 -> port3; + edge [color=red]; + mstb3 -> port4; + port3 -> mstb4; + } + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen]; + mstb4 [label="MSTB #4";style=filled;fillcolor=grey]; + + port1 [label="Port #1"]; + port2 [label="Port #2"]; + port3 [label="Port #3"]; + port4 [label="Port #4";style=filled;fillcolor=grey]; + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue]; +} diff --git a/Documentation/gpu/dp-mst/topology-figure-3.dot b/Documentation/gpu/dp-mst/topology-figure-3.dot new file mode 100644 index 000000000000..6cd78d06778b --- /dev/null +++ b/Documentation/gpu/dp-mst/topology-figure-3.dot @@ -0,0 +1,59 @@ +digraph T { + /* Make sure our payloads are always drawn below the driver node */ + subgraph cluster_driver { + fillcolor = grey; + style = filled; + edge [dir=none]; + driver -> payload1; + driver -> payload2 [penwidth=3]; + edge [dir=""]; + } + + /* Driver malloc references */ + edge [style=dashed]; + driver -> port1; + driver -> port2; + driver -> port3:e; + driver -> port4 [color=grey]; + payload1:s -> port1:e; + payload2:s -> port3:e [penwidth=3]; + edge [style=""]; + + subgraph cluster_topology { + label="Topology Manager"; + labelloc=bottom; + + /* Topology references */ + mstb1 -> {port1, port2}; + port1 -> mstb2; + edge [color=grey]; + port2 -> mstb3 -> {port3, port4}; + port3 -> mstb4; + edge [color=""]; + + /* Malloc references */ + edge [style=dashed;dir=back]; + mstb1 -> {port1, port2}; + port1 -> mstb2; + port2 -> mstb3 [penwidth=3]; + mstb3 -> port3 [penwidth=3]; + edge [color=grey]; + mstb3 -> port4; + port3 -> mstb4; + } + + mstb1 [label="MSTB #1";style=filled;fillcolor=palegreen]; + mstb2 [label="MSTB #2";style=filled;fillcolor=palegreen]; + mstb3 [label="MSTB #3";style=filled;fillcolor=palegreen;penwidth=3]; + mstb4 [label="MSTB #4";style=filled;fillcolor=grey]; + + port1 [label="Port #1"]; + port2 [label="Port #2";penwidth=5]; + port3 [label="Port #3";penwidth=3]; + port4 [label="Port #4";style=filled;fillcolor=grey]; + + driver [label="DRM driver";style=filled;shape=box;fillcolor=lightblue]; + + payload1 [label="Payload #1";style=filled;shape=box;fillcolor=lightblue]; + payload2 [label="Payload #2";style=filled;shape=box;fillcolor=lightblue;penwidth=3]; +} diff --git a/Documentation/gpu/drivers.rst b/Documentation/gpu/drivers.rst index 65be325bf282..044a7025477c 100644 --- a/Documentation/gpu/drivers.rst +++ b/Documentation/gpu/drivers.rst @@ -5,6 +5,7 @@ GPU Driver Documentation .. toctree:: amdgpu + amdgpu-dc i915 meson pl111 @@ -13,8 +14,11 @@ GPU Driver Documentation tve200 v3d vc4 + vkms bridge/dw-hdmi xen-front + afbc + komeda-kms .. only:: subproject and html diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 5ee9674fb9e9..3ae23a5454ac 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -39,68 +39,6 @@ sections. Driver Information ------------------ -Driver Features -~~~~~~~~~~~~~~~ - -Drivers inform the DRM core about their requirements and supported -features by setting appropriate flags in the driver_features field. -Since those flags influence the DRM core behaviour since registration -time, most of them must be set to registering the :c:type:`struct -drm_driver <drm_driver>` instance. - -u32 driver_features; - -DRIVER_USE_AGP - Driver uses AGP interface, the DRM core will manage AGP resources. - -DRIVER_LEGACY - Denote a legacy driver using shadow attach. Don't use. - -DRIVER_KMS_LEGACY_CONTEXT - Used only by nouveau for backwards compatibility with existing userspace. - Don't use. - -DRIVER_PCI_DMA - Driver is capable of PCI DMA, mapping of PCI DMA buffers to - userspace will be enabled. Deprecated. - -DRIVER_SG - Driver can perform scatter/gather DMA, allocation and mapping of - scatter/gather buffers will be enabled. Deprecated. - -DRIVER_HAVE_DMA - Driver supports DMA, the userspace DMA API will be supported. - Deprecated. - -DRIVER_HAVE_IRQ; DRIVER_IRQ_SHARED - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler - managed by the DRM Core. The core will support simple IRQ handler - installation when the flag is set. The installation process is - described in ?. - - DRIVER_IRQ_SHARED indicates whether the device & handler support - shared IRQs (note that this is required of PCI drivers). - -DRIVER_GEM - Driver use the GEM memory manager. - -DRIVER_MODESET - Driver supports mode setting interfaces (KMS). - -DRIVER_PRIME - Driver implements DRM PRIME buffer sharing. - -DRIVER_RENDER - Driver supports dedicated render nodes. - -DRIVER_ATOMIC - Driver supports atomic properties. In this case the driver must - implement appropriate obj->atomic_get_property() vfuncs for any - modeset objects with driver specific properties. - -DRIVER_SYNCOBJ - Driver support drm sync objects. - Major, Minor and Patchlevel ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -143,6 +81,9 @@ Device Instance and Driver Handling .. kernel-doc:: drivers/gpu/drm/drm_drv.c :doc: driver instance overview +.. kernel-doc:: include/drm/drm_device.h + :internal: + .. kernel-doc:: include/drm/drm_drv.h :internal: @@ -230,6 +171,15 @@ Printer .. kernel-doc:: drivers/gpu/drm/drm_print.c :export: +Utilities +--------- + +.. kernel-doc:: include/drm/drm_util.h + :doc: drm utils + +.. kernel-doc:: include/drm/drm_util.h + :internal: + Legacy Support Code =================== diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index f9cfcdcdf024..17ca7f8bf3d3 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -59,19 +59,28 @@ Implementing Asynchronous Atomic Commit .. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c :doc: implementing nonblocking commit +Helper Functions Reference +-------------------------- + +.. kernel-doc:: include/drm/drm_atomic_helper.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c + :export: + Atomic State Reset and Initialization ------------------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :doc: atomic state reset and initialization -Helper Functions Reference --------------------------- +Atomic State Helper Reference +----------------------------- -.. kernel-doc:: include/drm/drm_atomic_helper.h +.. kernel-doc:: include/drm/drm_atomic_state_helper.h :internal: -.. kernel-doc:: drivers/gpu/drm/drm_atomic_helper.c +.. kernel-doc:: drivers/gpu/drm/drm_atomic_state_helper.c :export: Simple KMS Helper Reference @@ -107,8 +116,6 @@ Framebuffer CMA Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_fb_cma_helper.c :export: -.. _drm_bridges: - Framebuffer GEM Helper Reference ================================ @@ -118,6 +125,8 @@ Framebuffer GEM Helper Reference .. kernel-doc:: drivers/gpu/drm/drm_gem_framebuffer_helper.c :export: +.. _drm_bridges: + Bridges ======= @@ -199,18 +208,40 @@ Display Port Dual Mode Adaptor Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_dp_dual_mode_helper.c :export: -Display Port MST Helper Functions Reference -=========================================== +Display Port MST Helpers +======================== + +Overview +-------- .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c :doc: dp mst helper +.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c + :doc: Branch device and port refcounting + +Functions Reference +------------------- + .. kernel-doc:: include/drm/drm_dp_mst_helper.h :internal: .. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c :export: +Topology Lifetime Internals +--------------------------- + +These functions aren't exported to drivers, but are documented here to help make +the MST topology helpers easier to understand + +.. kernel-doc:: drivers/gpu/drm/drm_dp_mst_topology.c + :functions: drm_dp_mst_topology_try_get_mstb drm_dp_mst_topology_get_mstb + drm_dp_mst_topology_put_mstb + drm_dp_mst_topology_try_get_port drm_dp_mst_topology_get_port + drm_dp_mst_topology_put_port + drm_dp_mst_get_mstb_malloc drm_dp_mst_put_mstb_malloc + MIPI DSI Helper Functions Reference =================================== @@ -223,6 +254,18 @@ MIPI DSI Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_mipi_dsi.c :export: +Display Stream Compression Helper Functions Reference +===================================================== + +.. kernel-doc:: drivers/gpu/drm/drm_dsc.c + :doc: dsc helpers + +.. kernel-doc:: include/drm/drm_dsc.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_dsc.c + :export: + Output Probing Helper Functions Reference ========================================= @@ -253,18 +296,6 @@ SCDC Helper Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_scdc_helper.c :export: -Rectangle Utilities Reference -============================= - -.. kernel-doc:: include/drm/drm_rect.h - :doc: rect utils - -.. kernel-doc:: include/drm/drm_rect.h - :internal: - -.. kernel-doc:: drivers/gpu/drm/drm_rect.c - :export: - HDMI Infoframes Helper Reference ================================ @@ -279,6 +310,18 @@ libraries and hence is also included here. .. kernel-doc:: drivers/video/hdmi.c :export: +Rectangle Utilities Reference +============================= + +.. kernel-doc:: include/drm/drm_rect.h + :doc: rect utils + +.. kernel-doc:: include/drm/drm_rect.h + :internal: + +.. kernel-doc:: drivers/gpu/drm/drm_rect.c + :export: + Flip-work Helper Reference ========================== diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 5dee6b8a4c12..23a3c986ef6d 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -287,8 +287,14 @@ Atomic Mode Setting Function Reference .. kernel-doc:: drivers/gpu/drm/drm_atomic.c :export: -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c - :internal: +Atomic Mode Setting IOCTL and UAPI Functions +-------------------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c + :export: CRTC Abstraction ================ @@ -323,6 +329,12 @@ Frame Buffer Functions Reference DRM Format Handling =================== +.. kernel-doc:: include/uapi/drm/drm_fourcc.h + :doc: overview + +Format Functions Reference +-------------------------- + .. kernel-doc:: include/drm/drm_fourcc.h :internal: @@ -398,102 +410,6 @@ Encoder Functions Reference .. kernel-doc:: drivers/gpu/drm/drm_encoder.c :export: -KMS Initialization and Cleanup -============================== - -A KMS device is abstracted and exposed as a set of planes, CRTCs, -encoders and connectors. KMS drivers must thus create and initialize all -those objects at load time after initializing mode setting. - -CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) --------------------------------------------- - -A CRTC is an abstraction representing a part of the chip that contains a -pointer to a scanout buffer. Therefore, the number of CRTCs available -determines how many independent scanout buffers can be active at any -given time. The CRTC structure contains several fields to support this: -a pointer to some video memory (abstracted as a frame buffer object), a -display mode, and an (x, y) offset into the video memory to support -panning or configurations where one piece of video memory spans multiple -CRTCs. - -CRTC Initialization -~~~~~~~~~~~~~~~~~~~ - -A KMS device must create and register at least one struct -:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is -allocated and zeroed by the driver, possibly as part of a larger -structure, and registered with a call to :c:func:`drm_crtc_init()` -with a pointer to CRTC functions. - - -Cleanup -------- - -The DRM core manages its objects' lifetime. When an object is not needed -anymore the core calls its destroy function, which must clean up and -free every resource allocated for the object. Every -:c:func:`drm_\*_init()` call must be matched with a corresponding -:c:func:`drm_\*_cleanup()` call to cleanup CRTCs -(:c:func:`drm_crtc_cleanup()`), planes -(:c:func:`drm_plane_cleanup()`), encoders -(:c:func:`drm_encoder_cleanup()`) and connectors -(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that -have been added to sysfs must be removed by a call to -:c:func:`drm_connector_unregister()` before calling -:c:func:`drm_connector_cleanup()`. - -Connectors state change detection must be cleanup up with a call to -:c:func:`drm_kms_helper_poll_fini()`. - -Output discovery and initialization example -------------------------------------------- - -.. code-block:: c - - void intel_crt_init(struct drm_device *dev) - { - struct drm_connector *connector; - struct intel_output *intel_output; - - intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); - if (!intel_output) - return; - - connector = &intel_output->base; - drm_connector_init(dev, &intel_output->base, - &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); - - drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, - DRM_MODE_ENCODER_DAC); - - drm_connector_attach_encoder(&intel_output->base, - &intel_output->enc); - - /* Set up the DDC bus. */ - intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); - if (!intel_output->ddc_bus) { - dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " - "failed.\n"); - return; - } - - intel_output->type = INTEL_OUTPUT_ANALOG; - connector->interlace_allowed = 0; - connector->doublescan_allowed = 0; - - drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); - drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); - - drm_connector_register(connector); - } - -In the example above (taken from the i915 driver), a CRTC, connector and -encoder combination is created. A device-specific i2c bus is also -created for fetching EDID data and performing monitor detection. Once -the process is complete, the new connector is registered with sysfs to -make its properties available to applications. - KMS Locking =========== @@ -542,6 +458,18 @@ Plane Composition Properties .. kernel-doc:: drivers/gpu/drm/drm_blend.c :export: +FB_DAMAGE_CLIPS +~~~~~~~~~~~~~~~ + +.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c + :export: + +.. kernel-doc:: include/drm/drm_damage_helper.h + :internal: + Color Management Properties --------------------------- @@ -560,9 +488,16 @@ Tile Group Property Explicit Fencing Properties --------------------------- -.. kernel-doc:: drivers/gpu/drm/drm_atomic.c +.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c :doc: explicit fencing properties + +Variable Refresh Properties +--------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_connector.c + :doc: Variable refresh properties + Existing KMS Properties ----------------------- diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index 21b6b72a9ba8..54a696d961a7 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -72,16 +72,13 @@ object TTM to provide a pool for buffer object allocation by clients and the kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, and its size should be sizeof(struct ttm_bo_global). Again, driver-specific init and release functions may -be provided, likely eventually calling ttm_bo_global_init() and -ttm_bo_global_release(), respectively. Also, like the previous +be provided, likely eventually calling ttm_bo_global_ref_init() and +ttm_bo_global_ref_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) ==================================== @@ -297,7 +294,7 @@ made up of several fields, the more interesting ones being: struct vm_operations_struct { void (*open)(struct vm_area_struct * area); void (*close)(struct vm_area_struct * area); - int (*fault)(struct vm_fault *vmf); + vm_fault_t (*fault)(struct vm_fault *vmf); }; @@ -505,7 +502,7 @@ GPU Scheduler Overview -------- -.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c +.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c :doc: Overview Scheduler Function References @@ -514,5 +511,5 @@ Scheduler Function References .. kernel-doc:: include/drm/gpu_scheduler.h :internal: -.. kernel-doc:: drivers/gpu/drm/scheduler/gpu_scheduler.c +.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c :export: diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst index a2214cc1f821..c9fd23efd957 100644 --- a/Documentation/gpu/drm-uapi.rst +++ b/Documentation/gpu/drm-uapi.rst @@ -190,13 +190,16 @@ ENOSPC: Simply running out of kernel/system memory is signalled through ENOMEM. -EPERM/EACCESS: +EPERM/EACCES: Returned for an operation that is valid, but needs more privileges. E.g. root-only or much more common, DRM master-only operations return this when when called by unpriviledged clients. There's no clear - difference between EACCESS and EPERM. + difference between EACCES and EPERM. ENODEV: + The device is not (yet) present or fully initialized. + +EOPNOTSUPP: Feature (like PRIME, modesetting, GEM) is not supported by the driver. ENXIO: @@ -235,6 +238,14 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of Testing and validation ====================== +Testing Requirements for userspace API +-------------------------------------- + +New cross-driver userspace interface extensions, like new IOCTL, new KMS +properties, new files in sysfs or anything else that constitutes an API change +should have driver-agnostic testcases in IGT for that feature, if such a test +can be reasonably made using IGT for the target hardware. + Validating changes with IGT --------------------------- diff --git a/Documentation/gpu/komeda-kms.rst b/Documentation/gpu/komeda-kms.rst new file mode 100644 index 000000000000..b08da1cffecc --- /dev/null +++ b/Documentation/gpu/komeda-kms.rst @@ -0,0 +1,488 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================== + drm/komeda Arm display driver +============================== + +The drm/komeda driver supports the Arm display processor D71 and later products, +this document gives a brief overview of driver design: how it works and why +design it like that. + +Overview of D71 like display IPs +================================ + +From D71, Arm display IP begins to adopt a flexible and modularized +architecture. A display pipeline is made up of multiple individual and +functional pipeline stages called components, and every component has some +specific capabilities that can give the flowed pipeline pixel data a +particular processing. + +Typical D71 components: + +Layer +----- +Layer is the first pipeline stage, which prepares the pixel data for the next +stage. It fetches the pixel from memory, decodes it if it's AFBC, rotates the +source image, unpacks or converts YUV pixels to the device internal RGB pixels, +then adjusts the color_space of pixels if needed. + +Scaler +------ +As its name suggests, scaler takes responsibility for scaling, and D71 also +supports image enhancements by scaler. +The usage of scaler is very flexible and can be connected to layer output +for layer scaling, or connected to compositor and scale the whole display +frame and then feed the output data into wb_layer which will then write it +into memory. + +Compositor (compiz) +------------------- +Compositor blends multiple layers or pixel data flows into one single display +frame. its output frame can be fed into post image processor for showing it on +the monitor or fed into wb_layer and written to memory at the same time. +user can also insert a scaler between compositor and wb_layer to down scale +the display frame first and and then write to memory. + +Writeback Layer (wb_layer) +-------------------------- +Writeback layer does the opposite things of Layer, which connects to compiz +and writes the composition result to memory. + +Post image processor (improc) +----------------------------- +Post image processor adjusts frame data like gamma and color space to fit the +requirements of the monitor. + +Timing controller (timing_ctrlr) +-------------------------------- +Final stage of display pipeline, Timing controller is not for the pixel +handling, but only for controlling the display timing. + +Merger +------ +D71 scaler mostly only has the half horizontal input/output capabilities +compared with Layer, like if Layer supports 4K input size, the scaler only can +support 2K input/output in the same time. To achieve the ful frame scaling, D71 +introduces Layer Split, which splits the whole image to two half parts and feeds +them to two Layers A and B, and does the scaling independently. After scaling +the result need to be fed to merger to merge two part images together, and then +output merged result to compiz. + +Splitter +-------- +Similar to Layer Split, but Splitter is used for writeback, which splits the +compiz result to two parts and then feed them to two scalers. + +Possible D71 Pipeline usage +=========================== + +Benefitting from the modularized architecture, D71 pipelines can be easily +adjusted to fit different usages. And D71 has two pipelines, which support two +types of working mode: + +- Dual display mode + Two pipelines work independently and separately to drive two display outputs. + +- Single display mode + Two pipelines work together to drive only one display output. + + On this mode, pipeline_B doesn't work indenpendently, but outputs its + composition result into pipeline_A, and its pixel timing also derived from + pipeline_A.timing_ctrlr. The pipeline_B works just like a "slave" of + pipeline_A(master) + +Single pipeline data flow +------------------------- + +.. kernel-render:: DOT + :alt: Single pipeline digraph + :caption: Single pipeline data flow + + digraph single_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + + subgraph cluster_pipeline { + style=dashed + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Dual pipeline with Slave enabled +-------------------------------- + +.. kernel-render:: DOT + :alt: Slave pipeline digraph + :caption: Slave pipeline enabled data flow + + digraph slave_ppl { + rankdir=LR; + + subgraph { + "Memory"; + "Monitor"; + } + node [shape=box] + subgraph cluster_pipeline_slave { + style=dashed + label="Slave Pipeline_B" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Slave.Scaler-0"; + "Slave.Scaler-1"; + } + + node [bgcolor=grey style=filled] + "Slave.Layer-0" -> "Slave.Scaler-0" + "Slave.Layer-1" -> "Slave.Scaler-0" + "Slave.Layer-2" -> "Slave.Scaler-1" + "Slave.Layer-3" -> "Slave.Scaler-1" + + "Slave.Layer-0" -> "Slave.Compiz" + "Slave.Layer-1" -> "Slave.Compiz" + "Slave.Layer-2" -> "Slave.Compiz" + "Slave.Layer-3" -> "Slave.Compiz" + "Slave.Scaler-0" -> "Slave.Compiz" + "Slave.Scaler-1" -> "Slave.Compiz" + } + + subgraph cluster_pipeline_master { + style=dashed + label="Master Pipeline_A" + node [shape=box] + { + node [bgcolor=grey style=dashed] + "Scaler-0"; + "Scaler-1"; + "Scaler-0/1" + } + + node [bgcolor=grey style=filled] + "Layer-0" -> "Scaler-0" + "Layer-1" -> "Scaler-0" + "Layer-2" -> "Scaler-1" + "Layer-3" -> "Scaler-1" + + "Slave.Compiz" -> "Compiz" + "Layer-0" -> "Compiz" + "Layer-1" -> "Compiz" + "Layer-2" -> "Compiz" + "Layer-3" -> "Compiz" + "Scaler-0" -> "Compiz" + "Scaler-1" -> "Compiz" + + "Compiz" -> "Scaler-0/1" -> "Wb_layer" + "Compiz" -> "Improc" -> "Timing Controller" + } + + "Wb_layer" -> "Memory" + "Timing Controller" -> "Monitor" + } + +Sub-pipelines for input and output +---------------------------------- + +A complete display pipeline can be easily divided into three sub-pipelines +according to the in/out usage. + +Layer(input) pipeline +~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-render:: DOT + :alt: Layer data digraph + :caption: Layer (input) data flow + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Layer-n" -> "Scaler-n" -> "Compiz" + } + +.. kernel-render:: DOT + :alt: Layer Split digraph + :caption: Layer Split pipeline + + digraph layer_data_flow { + rankdir=LR; + node [shape=box] + + "Layer-0/1" -> "Scaler-0" -> "Merger" + "Layer-2/3" -> "Scaler-1" -> "Merger" + "Merger" -> "Compiz" + } + +Writeback(output) pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: writeback digraph + :caption: Writeback(output) data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + { + node [bgcolor=grey style=dashed] + "Scaler-n"; + } + + "Compiz" -> "Scaler-n" -> "Wb_layer" + } + +.. kernel-render:: DOT + :alt: split writeback digraph + :caption: Writeback(output) Split data flow + + digraph writeback_data_flow { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Splitter" + "Splitter" -> "Scaler-0" -> "Merger" + "Splitter" -> "Scaler-1" -> "Merger" + "Merger" -> "Wb_layer" + } + +Display output pipeline +~~~~~~~~~~~~~~~~~~~~~~~ +.. kernel-render:: DOT + :alt: display digraph + :caption: display output data flow + + digraph single_ppl { + rankdir=LR; + node [shape=box] + + "Compiz" -> "Improc" -> "Timing Controller" + } + +In the following section we'll see these three sub-pipelines will be handled +by KMS-plane/wb_conn/crtc respectively. + +Komeda Resource abstraction +=========================== + +struct komeda_pipeline/component +-------------------------------- + +To fully utilize and easily access/configure the HW, the driver side also uses +a similar architecture: Pipeline/Component to describe the HW features and +capabilities, and a specific component includes two parts: + +- Data flow controlling. +- Specific component capabilities and features. + +So the driver defines a common header struct komeda_component to describe the +data flow control and all specific components are a subclass of this base +structure. + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h + :internal: + +Resource discovery and initialization +===================================== + +Pipeline and component are used to describe how to handle the pixel data. We +still need a @struct komeda_dev to describe the whole view of the device, and +the control-abilites of device. + +We have &komeda_dev, &komeda_pipeline, &komeda_component. Now fill devices with +pipelines. Since komeda is not for D71 only but also intended for later products, +of course we’d better share as much as possible between different products. To +achieve this, split the komeda device into two layers: CORE and CHIP. + +- CORE: for common features and capabilities handling. +- CHIP: for register programing and HW specific feature (limitation) handling. + +CORE can access CHIP by three chip function structures: + +- struct komeda_dev_funcs +- struct komeda_pipeline_funcs +- struct komeda_component_funcs + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_dev.h + :internal: + +Format handling +=============== + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_format_caps.h + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h + :internal: + +Attach komeda_dev to DRM-KMS +============================ + +Komeda abstracts resources by pipeline/component, but DRM-KMS uses +crtc/plane/connector. One KMS-obj cannot represent only one single component, +since the requirements of a single KMS object cannot simply be achieved by a +single component, usually that needs multiple components to fit the requirement. +Like set mode, gamma, ctm for KMS all target on CRTC-obj, but komeda needs +compiz, improc and timing_ctrlr to work together to fit these requirements. +And a KMS-Plane may require multiple komeda resources: layer/scaler/compiz. + +So, one KMS-Obj represents a sub-pipeline of komeda resources. + +- Plane: `Layer(input) pipeline`_ +- Wb_connector: `Writeback(output) pipeline`_ +- Crtc: `Display output pipeline`_ + +So, for komeda, we treat KMS crtc/plane/connector as users of pipeline and +component, and at any one time a pipeline/component only can be used by one +user. And pipeline/component will be treated as private object of DRM-KMS; the +state will be managed by drm_atomic_state as well. + +How to map plane to Layer(input) pipeline +----------------------------------------- + +Komeda has multiple Layer input pipelines, see: +- `Single pipeline data flow`_ +- `Dual pipeline with Slave enabled`_ + +The easiest way is binding a plane to a fixed Layer pipeline, but consider the +komeda capabilities: + +- Layer Split, See `Layer(input) pipeline`_ + + Layer_Split is quite complicated feature, which splits a big image into two + parts and handles it by two layers and two scalers individually. But it + imports an edge problem or effect in the middle of the image after the split. + To avoid such a problem, it needs a complicated Split calculation and some + special configurations to the layer and scaler. We'd better hide such HW + related complexity to user mode. + +- Slave pipeline, See `Dual pipeline with Slave enabled`_ + + Since the compiz component doesn't output alpha value, the slave pipeline + only can be used for bottom layers composition. The komeda driver wants to + hide this limitation to the user. The way to do this is to pick a suitable + Layer according to plane_state->zpos. + +So for komeda, the KMS-plane doesn't represent a fixed komeda layer pipeline, +but multiple Layers with same capabilities. Komeda will select one or more +Layers to fit the requirement of one KMS-plane. + +Make component/pipeline to be drm_private_obj +--------------------------------------------- + +Add :c:type:`drm_private_obj` to :c:type:`komeda_component`, :c:type:`komeda_pipeline` + +.. code-block:: c + + struct komeda_component { + struct drm_private_obj obj; + ... + } + + struct komeda_pipeline { + struct drm_private_obj obj; + ... + } + +Tracking component_state/pipeline_state by drm_atomic_state +----------------------------------------------------------- + +Add :c:type:`drm_private_state` and user to :c:type:`komeda_component_state`, +:c:type:`komeda_pipeline_state` + +.. code-block:: c + + struct komeda_component_state { + struct drm_private_state obj; + void *binding_user; + ... + } + + struct komeda_pipeline_state { + struct drm_private_state obj; + struct drm_crtc *crtc; + ... + } + +komeda component validation +--------------------------- + +Komeda has multiple types of components, but the process of validation are +similar, usually including the following steps: + +.. code-block:: c + + int komeda_xxxx_validate(struct komeda_component_xxx xxx_comp, + struct komeda_component_output *input_dflow, + struct drm_plane/crtc/connector *user, + struct drm_plane/crtc/connector_state, *user_state) + { + setup 1: check if component is needed, like the scaler is optional depending + on the user_state; if unneeded, just return, and the caller will + put the data flow into next stage. + Setup 2: check user_state with component features and capabilities to see + if requirements can be met; if not, return fail. + Setup 3: get component_state from drm_atomic_state, and try set to set + user to component; fail if component has been assigned to another + user already. + Setup 3: configure the component_state, like set its input component, + convert user_state to component specific state. + Setup 4: adjust the input_dflow and prepare it for the next stage. + } + +komeda_kms Abstraction +---------------------- + +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_kms.h + :internal: + +komde_kms Functions +------------------- +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_crtc.c + :internal: +.. kernel-doc:: drivers/gpu/drm/arm/display/komeda/komeda_plane.c + :internal: + +Build komeda to be a Linux module driver +======================================== + +Now we have two level devices: + +- komeda_dev: describes the real display hardware. +- komeda_kms_dev: attachs or connects komeda_dev to DRM-KMS. + +All komeda operations are supplied or operated by komeda_dev or komeda_kms_dev, +the module driver is only a simple wrapper to pass the Linux command +(probe/remove/pm) into komeda_dev or komeda_kms_dev. diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index a7c150d6b63f..159a4aba49e6 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -28,22 +28,16 @@ them, but also all the virtual ones used by KVM, so everyone qualifies). Contact: Daniel Vetter, Thierry Reding, respective driver maintainers -Switch from reference/unreference to get/put --------------------------------------------- - -For some reason DRM core uses ``reference``/``unreference`` suffixes for -refcounting functions, but kernel uses ``get``/``put`` (e.g. -``kref_get``/``put()``). It would be good to switch over for consistency, and -it's shorter. Needs to be done in 3 steps for each pair of functions: -* Create new ``get``/``put`` functions, define the old names as compatibility - wrappers -* Switch over each file/driver using a cocci-generated spatch. -* Once all users of the old names are gone, remove them. +Remove custom dumb_map_offset implementations +--------------------------------------------- -This way drivers/patches in the progress of getting merged won't break. +All GEM based drivers should be using drm_gem_create_mmap_offset() instead. +Audit each individual driver, make sure it'll work with the generic +implementation (there's lots of outdated locking leftovers in various +implementations), and then remove it. -Contact: Daniel Vetter +Contact: Daniel Vetter, respective driver maintainers Convert existing KMS drivers to atomic modesetting -------------------------------------------------- @@ -88,30 +82,6 @@ events for atomic commits correctly. But fixing these bugs is good anyway. Contact: Daniel Vetter, respective driver maintainers -Better manual-upload support for atomic ---------------------------------------- - -This would be especially useful for tinydrm: - -- Add a struct drm_rect dirty_clip to drm_crtc_state. When duplicating the - crtc state, clear that to the max values, x/y = 0 and w/h = MAX_INT, in - __drm_atomic_helper_crtc_duplicate_state(). - -- Move tinydrm_merge_clips into drm_framebuffer.c, dropping the tinydrm\_ - prefix ofc and using drm_fb\_. drm_framebuffer.c makes sense since this - is a function useful to implement the fb->dirty function. - -- Create a new drm_fb_dirty function which does essentially what e.g. - mipi_dbi_fb_dirty does. You can use e.g. drm_atomic_helper_update_plane as the - template. But instead of doing a simple full-screen plane update, this new - helper also sets crtc_state->dirty_clip to the right coordinates. And of - course it needs to check whether the fb is actually active (and maybe where), - so there's some book-keeping involved. There's also some good fun involved in - scaling things appropriately. For that case we might simply give up and - declare the entire area covered by the plane as dirty. - -Contact: Noralf Trønnes, Daniel Vetter - Fallout from atomic KMS ----------------------- @@ -127,7 +97,8 @@ interfaces to fix these issues: the acquire context explicitly on stack and then also pass it down into drivers explicitly so that the legacy-on-atomic functions can use them. - Except for some driver code this is done. + Except for some driver code this is done. This task should be finished by + adding WARN_ON(!drm_drv_uses_atomic_modeset) in drm_modeset_lock_all(). * A bunch of the vtable hooks are now in the wrong place: DRM has a split between core vfunc tables (named ``drm_foo_funcs``), which are used to @@ -137,13 +108,6 @@ interfaces to fix these issues: ``_helper_funcs`` since they are not part of the core ABI. There's a ``FIXME`` comment in the kerneldoc for each such case in ``drm_crtc.h``. -* There's a new helper ``drm_atomic_helper_best_encoder()`` which could be - used by all atomic drivers which don't select the encoder for a given - connector at runtime. That's almost all of them, and would allow us to get - rid of a lot of ``best_encoder`` boilerplate in drivers. - - This was almost done, but new drivers added a few more cases again. - Contact: Daniel Vetter Get rid of dev->struct_mutex from GEM drivers @@ -164,9 +128,8 @@ private lock. The tricky part is the BO free functions, since those can't reliably take that lock any more. Instead state needs to be protected with suitable subordinate locks or some cleanup work pushed to a worker thread. For performance-critical drivers it might also be better to go with a more -fine-grained per-buffer object and per-context lockings scheme. Currently the -following drivers still use ``struct_mutex``: ``msm``, ``omapdrm`` and -``udl``. +fine-grained per-buffer object and per-context lockings scheme. Currently only the +``msm`` driver still use ``struct_mutex``. Contact: Daniel Vetter, respective driver maintainers @@ -190,7 +153,8 @@ Convert drivers to use simple modeset suspend/resume Most drivers (except i915 and nouveau) that use drm_atomic_helper_suspend/resume() can probably be converted to use -drm_mode_config_helper_suspend/resume(). +drm_mode_config_helper_suspend/resume(). Also there's still open-coded version +of the atomic suspend/resume code in older atomic modeset drivers. Contact: Maintainer of the driver you plan to convert @@ -221,6 +185,36 @@ Would be great to refactor this all into a set of small common helpers. Contact: Daniel Vetter +Generic fbdev defio support +--------------------------- + +The defio support code in the fbdev core has some very specific requirements, +which means drivers need to have a special framebuffer for fbdev. Which prevents +us from using the generic fbdev emulation code everywhere. The main issue is +that it uses some fields in struct page itself, which breaks shmem gem objects +(and other things). + +Possible solution would be to write our own defio mmap code in the drm fbdev +emulation. It would need to fully wrap the existing mmap ops, forwarding +everything after it has done the write-protect/mkwrite trickery: + +- In the drm_fbdev_fb_mmap helper, if we need defio, change the + default page prots to write-protected with something like this:: + + vma->vm_page_prot = pgprot_wrprotect(vma->vm_page_prot); + +- Set the mkwrite and fsync callbacks with similar implementions to the core + fbdev defio stuff. These should all work on plain ptes, they don't actually + require a struct page. uff. These should all work on plain ptes, they don't + actually require a struct page. + +- Track the dirty pages in a separate structure (bitfield with one bit per page + should work) to avoid clobbering struct page. + +Might be good to also have some igt testcases for this. + +Contact: Daniel Vetter, Noralf Tronnes + Put a reservation_object into drm_gem_object -------------------------------------------- @@ -240,26 +234,82 @@ efficient. Contact: Daniel Vetter +Defaults for .gem_prime_import and export +----------------------------------------- + +Most drivers don't need to set drm_driver->gem_prime_import and +->gem_prime_export now that drm_gem_prime_import() and drm_gem_prime_export() +are the default. + +struct drm_gem_object_funcs +--------------------------- + +GEM objects can now have a function table instead of having the callbacks on the +DRM driver struct. This is now the preferred way and drivers can be moved over. + +Use DRM_MODESET_LOCK_ALL_* helpers instead of boilerplate +--------------------------------------------------------- + +For cases where drivers are attempting to grab the modeset locks with a local +acquire context. Replace the boilerplate code surrounding +drm_modeset_lock_all_ctx() with DRM_MODESET_LOCK_ALL_BEGIN() and +DRM_MODESET_LOCK_ALL_END() instead. + +This should also be done for all places where drm_modest_lock_all() is still +used. + +As a reference, take a look at the conversions already completed in drm core. + +Contact: Sean Paul, respective driver maintainers + +Rename CMA helpers to DMA helpers +--------------------------------- + +CMA (standing for contiguous memory allocator) is really a bit an accident of +what these were used for first, a much better name would be DMA helpers. In the +text these should even be called coherent DMA memory helpers (so maybe CDM, but +no one knows what that means) since underneath they just use dma_alloc_coherent. + +Contact: Laurent Pinchart, Daniel Vetter + +Convert direct mode.vrefresh accesses to use drm_mode_vrefresh() +---------------------------------------------------------------- + +drm_display_mode.vrefresh isn't guaranteed to be populated. As such, using it +is risky and has been known to cause div-by-zero bugs. Fortunately, drm core +has helper which will use mode.vrefresh if it's !0 and will calculate it from +the timings when it's 0. + +Use simple search/replace, or (more fun) cocci to replace instances of direct +vrefresh access with a call to the helper. Check out +https://lists.freedesktop.org/archives/dri-devel/2019-January/205186.html for +inspiration. + +Once all instances of vrefresh have been converted, remove vrefresh from +drm_display_mode to avoid future use. + +Contact: Sean Paul + +Remove drm_display_mode.hsync +----------------------------- + +We have drm_mode_hsync() to calculate this from hsync_start/end, since drivers +shouldn't/don't use this, remove this member to avoid any temptations to use it +in the future. If there is any debug code using drm_display_mode.hsync, convert +it to use drm_mode_hsync() instead. + +Contact: Sean Paul + Core refactorings ================= Clean up the DRM header mess ---------------------------- -Currently the DRM subsystem has only one global header, ``drmP.h``. This is -used both for functions exported to helper libraries and drivers and functions -only used internally in the ``drm.ko`` module. The goal would be to move all -header declarations not needed outside of ``drm.ko`` into -``drivers/gpu/drm/drm_*_internal.h`` header files. ``EXPORT_SYMBOL`` also -needs to be dropped for these functions. - -This would nicely tie in with the below task to create kerneldoc after the API -is cleaned up. Or with the "hide legacy cruft better" task. - -Note that this is well in progress, but ``drmP.h`` is still huge. The updated -plan is to switch to per-file driver API headers, which will also structure -the kerneldoc better. This should also allow more fine-grained ``#include`` -directives. +The DRM subsystem originally had only one huge global header, ``drmP.h``. This +is now split up, but many source files still include it. The remaining part of +the cleanup work here is to replace any ``#include <drm/drmP.h>`` by only the +headers needed (and fixing up any missing pre-declarations in the headers). In the end no .c file should need to include ``drmP.h`` anymore. @@ -278,26 +328,6 @@ See https://dri.freedesktop.org/docs/drm/ for what's there already. Contact: Daniel Vetter -Hide legacy cruft better ------------------------- - -Way back DRM supported only drivers which shadow-attached to PCI devices with -userspace or fbdev drivers setting up outputs. Modern DRM drivers take charge -of the entire device, you can spot them with the DRIVER_MODESET flag. - -Unfortunately there's still large piles of legacy code around which needs to -be hidden so that driver writers don't accidentally end up using it. And to -prevent security issues in those legacy IOCTLs from being exploited on modern -drivers. This has multiple possible subtasks: - -* Extract support code for legacy features into a ``drm-legacy.ko`` kernel - module and compile it only when one of the legacy drivers is enabled. - -This is mostly done, the only thing left is to split up ``drm_irq.c`` into -legacy cruft and the parts needed by modern KMS drivers. - -Contact: Daniel Vetter - Make panic handling work ------------------------ @@ -368,12 +398,15 @@ KMS cleanups Some of these date from the very introduction of KMS in 2008 ... -- drm_mode_config.crtc_idr is misnamed, since it contains all KMS object. Should - be renamed to drm_mode_config.object_idr. +- Make ->funcs and ->helper_private vtables optional. There's a bunch of empty + function tables in drivers, but before we can remove them we need to make sure + that all the users in helpers and drivers do correctly check for a NULL + vtable. -- drm_display_mode doesn't need to be derived from drm_mode_object. That's - leftovers from older (never merged into upstream) KMS designs where modes - where set using their ID, including support to add/remove modes. +- Cleanup up the various ->destroy callbacks. A lot of them just wrapt the + drm_*_cleanup implementations and can be removed. Some tack a kfree() at the + end, for which we could add drm_*_cleanup_kfree(). And then there's the (for + historical reasons) misnamed drm_primary_helper_destroy() function. Better Testing ============== @@ -396,17 +429,12 @@ converting things over. For modeset tests we also first need a bit of infrastructure to use dumb buffers for untiled buffers, to be able to run all the non-i915 specific modeset tests. -Contact: Daniel Vetter - -Create a virtual KMS driver for testing (vkms) ----------------------------------------------- - -With all the latest helpers it should be fairly simple to create a virtual KMS -driver useful for testing, or for running X or similar on headless machines -(to be able to still use the GPU). This would be similar to vgem, but aimed at -the modeset side. +Extend virtual test driver (VKMS) +--------------------------------- -Once the basics are there there's tons of possibilities to extend it. +See the documentation of :ref:`VKMS <vkms>` for more details. This is an ideal +internship task, since it only requires a virtual machine and can be sized to +fit the available time. Contact: Daniel Vetter @@ -441,21 +469,10 @@ those drivers as simple as possible, so lots of room for refactoring: one of the ideas for having a shared dsi/dbi helper, abstracting away the transport details more. -- tinydrm_gem_cma_prime_import_sg_table should probably go into the cma - helpers, as a _vmapped variant (since not every driver needs the vmap). - And tinydrm_gem_cma_free_object could the be merged into - drm_gem_cma_free_object(). - -- tinydrm_fb_create we could move into drm_simple_pipe, only need to add - the fb_create hook to drm_simple_pipe_funcs, which would again simplify a - bunch of things (since it gives you a one-stop vfunc for simple drivers). - - Quick aside: The unregister devm stuff is kinda getting the lifetimes of a drm_device wrong. Doesn't matter, since everyone else gets it wrong too :-) -- also rework the drm_framebuffer_funcs->dirty hook wire-up, see above. - Contact: Noralf Trønnes, Daniel Vetter AMD DC Display Driver diff --git a/Documentation/gpu/vkms.rst b/Documentation/gpu/vkms.rst new file mode 100644 index 000000000000..61586fc861bb --- /dev/null +++ b/Documentation/gpu/vkms.rst @@ -0,0 +1,110 @@ +.. _vkms: + +========================================== + drm/vkms Virtual Kernel Modesetting +========================================== + +.. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c + :doc: vkms (Virtual Kernel Modesetting) + +TODO +==== + +CRC API Improvements +-------------------- + +- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` + +- Use the alpha value to blend vaddr_src with vaddr_dst instead of + overwriting it in ``blend()``. + +- Add igt test to check cleared alpha value for XRGB plane format. + +- Add igt test to check extreme alpha values i.e. fully opaque and fully + transparent (intermediate values are affected by hw-specific rounding modes). + +Runtime Configuration +--------------------- + +We want to be able to reconfigure vkms instance without having to reload the +module. Use/Test-cases: + +- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling of + compositors). + +- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of + them first). + +- Change output configuration: Plug/unplug screens, change EDID, allow changing + the refresh rate. + +The currently proposed solution is to expose vkms configuration through +configfs. All existing module options should be supported through configfs too. + +Add Plane Features +------------------ + +There's lots of plane features we could add support for: + +- Real overlay planes, not just cursor. + +- Full alpha blending on all planes. + +- Rotation, scaling. + +- Additional buffer formats, especially YUV formats for video like NV12. + Low/high bpp RGB formats would also be interesting. + +- Async updates (currently only possible on cursor plane using the legacy cursor + api). + +For all of these, we also want to review the igt test coverage and make sure all +relevant igt testcases work on vkms. + +Writeback support +----------------- + +Currently vkms only computes a CRC for each frame. Once we have additional plane +features, we could write back the entire composited frame, and expose it as: + +- Writeback connector. This is useful for testing compositors if you don't have + hardware with writeback support. + +- As a v4l device. This is useful for debugging compositors on special vkms + configurations, so that developers see what's really going on. + +Prime Buffer Sharing +-------------------- + +We already have vgem, which is a gem driver for testing rendering, similar to +how vkms is for testing the modeset side. Adding buffer sharing support to vkms +allows us to test them together, to test synchronization and lots of other +features. Also, this allows compositors to test whether they work correctly on +SoC chips, where the display and rendering is very often split between 2 +drivers. + +Output Features +--------------- + +- Variable refresh rate/freesync support. This probably needs prime buffer + sharing support, so that we can use vgem fences to simulate rendering in + testing. Also needs support to specify the EDID. + +- Add support for link status, so that compositors can validate their runtime + fallbacks when e.g. a Display Port link goes bad. + +- All the hotplug handling describe under "Runtime Configuration". + +Atomic Check using eBPF +----------------------- + +Atomic drivers have lots of restrictions which are not exposed to userspace in +any explicit form through e.g. possible property values. Userspace can only +inquiry about these limits through the atomic IOCTL, possibly using the +TEST_ONLY flag. Trying to add configurable code for all these limits, to allow +compositors to be tested against them, would be rather futile exercise. Instead +we could add support for eBPF to validate any kind of atomic state, and +implement a library of different restrictions. + +This needs a bunch of features (plane compositing, multiple outputs, ...) +enabled already to make sense. diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.txt index c8656dd029a9..958fff945304 100644 --- a/Documentation/hid/uhid.txt +++ b/Documentation/hid/uhid.txt @@ -160,7 +160,7 @@ them but you should handle them according to your needs. UHID_OUTPUT: This is sent if the HID device driver wants to send raw data to the I/O device on the interrupt channel. You should read the payload and forward it to - the device. The payload is of type "struct uhid_data_req". + the device. The payload is of type "struct uhid_output_req". This may be received even though you haven't received UHID_OPEN, yet. UHID_GET_REPORT: diff --git a/Documentation/hwmon/adm1275 b/Documentation/hwmon/adm1275 index 39033538eb03..5e277b0d91ce 100644 --- a/Documentation/hwmon/adm1275 +++ b/Documentation/hwmon/adm1275 @@ -58,6 +58,9 @@ The ADM1075, unlike many other PMBus devices, does not support internal voltage or current scaling. Reported voltages, currents, and power are raw measurements, and will typically have to be scaled. +The shunt value in micro-ohms can be set via device tree at compile-time. Please +refer to the Documentation/devicetree/bindings/hwmon/adm1275.txt for bindings +if the device tree is used. Platform data support --------------------- diff --git a/Documentation/hwmon/adt7475 b/Documentation/hwmon/adt7475 index 09d73a10644c..01b46b290532 100644 --- a/Documentation/hwmon/adt7475 +++ b/Documentation/hwmon/adt7475 @@ -79,6 +79,18 @@ ADT7490: * 2 GPIO pins (not implemented) * system acoustics optimizations (not implemented) +Sysfs Mapping +------------- + + ADT7490 ADT7476 ADT7475 ADT7473 + ------- ------- ------- ------- +in0 2.5VIN (22) 2.5VIN (22) - - +in1 VCCP (23) VCCP (23) VCCP (14) VCCP (14) +in2 VCC (4) VCC (4) VCC (4) VCC (3) +in3 5VIN (20) 5VIN (20) +in4 12VIN (21) 12VIN (21) +in5 VTT (8) + Special Features ---------------- diff --git a/Documentation/hwmon/hwmon-kernel-api.txt b/Documentation/hwmon/hwmon-kernel-api.txt index eb7a78aebb38..8bdefb41be30 100644 --- a/Documentation/hwmon/hwmon-kernel-api.txt +++ b/Documentation/hwmon/hwmon-kernel-api.txt @@ -299,17 +299,25 @@ functions is used. The header file linux/hwmon-sysfs.h provides a number of useful macros to declare and use hardware monitoring sysfs attributes. -In many cases, you can use the exsting define DEVICE_ATTR to declare such -attributes. This is feasible if an attribute has no additional context. However, -in many cases there will be additional information such as a sensor index which -will need to be passed to the sysfs attribute handling function. +In many cases, you can use the exsting define DEVICE_ATTR or its variants +DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an +attribute has no additional context. However, in many cases there will be +additional information such as a sensor index which will need to be passed +to the sysfs attribute handling function. SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes which need such additional context information. SENSOR_DEVICE_ATTR requires one additional argument, SENSOR_DEVICE_ATTR_2 requires two. -SENSOR_DEVICE_ATTR defines a struct sensor_device_attribute variable. -This structure has the following fields. +Simplified variants of SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 are available +and should be used if standard attribute permissions and function names are +feasible. Standard permissions are 0644 for SENSOR_DEVICE_ATTR[_2]_RW, +0444 for SENSOR_DEVICE_ATTR[_2]_RO, and 0200 for SENSOR_DEVICE_ATTR[_2]_WO. +Standard functions, similar to DEVICE_ATTR_{RW,RO,WO}, have _show and _store +appended to the provided function name. + +SENSOR_DEVICE_ATTR and its variants define a struct sensor_device_attribute +variable. This structure has the following fields. struct sensor_device_attribute { struct device_attribute dev_attr; @@ -320,8 +328,8 @@ You can use to_sensor_dev_attr to get the pointer to this structure from the attribute read or write function. Its parameter is the device to which the attribute is attached. -SENSOR_DEVICE_ATTR_2 defines a struct sensor_device_attribute_2 variable, -which is defined as follows. +SENSOR_DEVICE_ATTR_2 and its variants define a struct sensor_device_attribute_2 +variable, which is defined as follows. struct sensor_device_attribute_2 { struct device_attribute dev_attr; diff --git a/Documentation/hwmon/ina2xx b/Documentation/hwmon/ina2xx index b8df81f6d6bc..0f36c021192d 100644 --- a/Documentation/hwmon/ina2xx +++ b/Documentation/hwmon/ina2xx @@ -62,3 +62,18 @@ bus and shunt voltage conversion times multiplied by the averaging rate. We don't touch the conversion times and only modify the number of averages. The lower limit of the update_interval is 2 ms, the upper limit is 2253 ms. The actual programmed interval may vary from the desired value. + +General sysfs entries +------------- + +in0_input Shunt voltage(mV) channel +in1_input Bus voltage(mV) channel +curr1_input Current(mA) measurement channel +power1_input Power(uW) measurement channel +shunt_resistor Shunt resistance(uOhm) channel + +Sysfs entries for ina226, ina230 and ina231 only +------------- + +update_interval data conversion time; affects number of samples used + to average results for shunt and bus voltages. diff --git a/Documentation/hwmon/lm75 b/Documentation/hwmon/lm75 index 2f1120f88c16..010583608f12 100644 --- a/Documentation/hwmon/lm75 +++ b/Documentation/hwmon/lm75 @@ -42,6 +42,11 @@ Supported chips: Addresses scanned: none Datasheet: Publicly available at the ST website http://www.st.com/internet/analog/product/121769.jsp + * ST Microelectronics STLM75 + Prefix: 'stlm75' + Addresses scanned: none + Datasheet: Publicly available at the ST website + https://www.st.com/resource/en/datasheet/stlm75.pdf * Texas Instruments TMP100, TMP101, TMP105, TMP112, TMP75, TMP75C, TMP175, TMP275 Prefixes: 'tmp100', 'tmp101', 'tmp105', 'tmp112', 'tmp175', 'tmp75', 'tmp75c', 'tmp275' Addresses scanned: none diff --git a/Documentation/hwmon/lm85 b/Documentation/hwmon/lm85 index 7c49feaa79d2..2329c383efe4 100644 --- a/Documentation/hwmon/lm85 +++ b/Documentation/hwmon/lm85 @@ -3,9 +3,13 @@ Kernel driver lm85 Supported chips: * National Semiconductor LM85 (B and C versions) - Prefix: 'lm85' + Prefix: 'lm85b' or 'lm85c' Addresses scanned: I2C 0x2c, 0x2d, 0x2e Datasheet: http://www.national.com/pf/LM/LM85.html + * Texas Instruments LM96000 + Prefix: 'lm9600' + Addresses scanned: I2C 0x2c, 0x2d, 0x2e + Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf * Analog Devices ADM1027 Prefix: 'adm1027' Addresses scanned: I2C 0x2c, 0x2d, 0x2e @@ -136,6 +140,9 @@ of voltage and temperature channels. SMSC EMC6D103S is similar to EMC6D103, but does not support pwm#_auto_pwm_minctl and temp#_auto_temp_off. +The LM96000 supports additional high frequency PWM modes (22.5 kHz, 24 kHz, +25.7 kHz, 27.7 kHz and 30 kHz), which can be configured on a per-PWM basis. + Hardware Configurations ----------------------- diff --git a/Documentation/hwmon/occ b/Documentation/hwmon/occ new file mode 100644 index 000000000000..e787596e03fe --- /dev/null +++ b/Documentation/hwmon/occ @@ -0,0 +1,112 @@ +Kernel driver occ-hwmon +======================= + +Supported chips: + * POWER8 + * POWER9 + +Author: Eddie James <eajames@linux.ibm.com> + +Description +----------- + +This driver supports hardware monitoring for the On-Chip Controller (OCC) +embedded on POWER processors. The OCC is a device that collects and aggregates +sensor data from the processor and the system. The OCC can provide the raw +sensor data as well as perform thermal and power management on the system. + +The P8 version of this driver is a client driver of I2C. It may be probed +manually if an "ibm,p8-occ-hwmon" compatible device is found under the +appropriate I2C bus node in the device-tree. + +The P9 version of this driver is a client driver of the FSI-based OCC driver. +It will be probed automatically by the FSI-based OCC driver. + +Sysfs entries +------------- + +The following attributes are supported. All attributes are read-only unless +specified. + +The OCC sensor ID is an integer that represents the unique identifier of the +sensor with respect to the OCC. For example, a temperature sensor for the third +DIMM slot in the system may have a sensor ID of 7. This mapping is unavailable +to the device driver, which must therefore export the sensor ID as-is. + +Some entries are only present with certain OCC sensor versions or only on +certain OCCs in the system. The version number is not exported to the user +but can be inferred. + +temp[1-n]_label OCC sensor ID. +[with temperature sensor version 1] + temp[1-n]_input Measured temperature of the component in millidegrees + Celsius. +[with temperature sensor version >= 2] + temp[1-n]_type The FRU (Field Replaceable Unit) type + (represented by an integer) for the component + that this sensor measures. + temp[1-n]_fault Temperature sensor fault boolean; 1 to indicate + that a fault is present or 0 to indicate that + no fault is present. + [with type == 3 (FRU type is VRM)] + temp[1-n]_alarm VRM temperature alarm boolean; 1 to indicate + alarm, 0 to indicate no alarm + [else] + temp[1-n]_input Measured temperature of the component in + millidegrees Celsius. + +freq[1-n]_label OCC sensor ID. +freq[1-n]_input Measured frequency of the component in MHz. + +power[1-n]_input Latest measured power reading of the component in + microwatts. +power[1-n]_average Average power of the component in microwatts. +power[1-n]_average_interval The amount of time over which the power average + was taken in microseconds. +[with power sensor version < 2] + power[1-n]_label OCC sensor ID. +[with power sensor version >= 2] + power[1-n]_label OCC sensor ID + function ID + channel in the form + of a string, delimited by underscores, i.e. "0_15_1". + Both the function ID and channel are integers that + further identify the power sensor. +[with power sensor version 0xa0] + power[1-n]_label OCC sensor ID + sensor type in the form of a string, + delimited by an underscore, i.e. "0_system". Sensor + type will be one of "system", "proc", "vdd" or "vdn". + For this sensor version, OCC sensor ID will be the same + for all power sensors. +[present only on "master" OCC; represents the whole system power; only one of + this type of power sensor will be present] + power[1-n]_label "system" + power[1-n]_input Latest system output power in microwatts. + power[1-n]_cap Current system power cap in microwatts. + power[1-n]_cap_not_redundant System power cap in microwatts when + there is not redundant power. + power[1-n]_cap_max Maximum power cap that the OCC can enforce in + microwatts. + power[1-n]_cap_min Minimum power cap that the OCC can enforce in + microwatts. + power[1-n]_cap_user The power cap set by the user, in microwatts. + This attribute will return 0 if no user power + cap has been set. This attribute is read-write, + but writing any precision below watts will be + ignored, i.e. requesting a power cap of + 500900000 microwatts will result in a power cap + request of 500 watts. + [with caps sensor version > 1] + power[1-n]_cap_user_source Indicates how the user power cap was + set. This is an integer that maps to + system or firmware components that can + set the user power cap. + +The following "extn" sensors are exported as a way for the OCC to provide data +that doesn't fit anywhere else. The meaning of these sensors is entirely +dependent on their data, and cannot be statically defined. + +extn[1-n]_label ASCII ID or OCC sensor ID. +extn[1-n]_flags This is one byte hexadecimal value. Bit 7 indicates the + type of the label attribute; 1 for sensor ID, 0 for + ASCII ID. Other bits are reserved. +extn[1-n]_input 6 bytes of hexadecimal data, with a meaning defined by + the sensor ID. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu new file mode 100644 index 000000000000..31884d2b2eb5 --- /dev/null +++ b/Documentation/i2c/busses/i2c-nvidia-gpu @@ -0,0 +1,18 @@ +Kernel driver i2c-nvidia-gpu + +Datasheet: not publicly available. + +Authors: + Ajay Gupta <ajayg@nvidia.com> + +Description +----------- + +i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing +and later GPUs and it is used to communicate with Type-C controller on GPUs. + +If your 'lspci -v' listing shows something like the following, + +01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) + +then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes index 47c25abb7d52..0cee0fc545b4 100644 --- a/Documentation/i2c/fault-codes +++ b/Documentation/i2c/fault-codes @@ -112,6 +112,10 @@ EPROTO case is when the length of an SMBus block data response (from the SMBus slave) is outside the range 1-32 bytes. +ESHUTDOWN + Returned when a transfer was requested using an adapter + which is already suspended. + ETIMEDOUT This is returned by drivers when an operation took too much time, and was aborted before it completed. diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection index a4ce62090fd5..c87f416d53dd 100644 --- a/Documentation/i2c/gpio-fault-injection +++ b/Documentation/i2c/gpio-fault-injection @@ -1,3 +1,4 @@ +========================= Linux I2C fault injection ========================= @@ -13,6 +14,9 @@ mounted at /sys/kernel/debug. There will be a separate subdirectory per GPIO driven I2C bus. Each subdirectory will contain files to trigger the fault injection. They will be described now along with their intended use-cases. +Wire states +=========== + "scl" ----- @@ -34,10 +38,10 @@ I2C specification version 4, section 3.1.16) using the helpers of the Linux I2C core (see 'struct bus_recovery_info'). However, the bus recovery will not succeed because SDA is still pinned low until you manually release it again with "echo 1 > sda". A test with an automatic release can be done with the -following class of fault injectors. +"incomplete transfers" class of fault injectors. -Introduction to incomplete transfers ------------------------------------- +Incomplete transfers +==================== The following fault injectors create situations where SDA will be held low by a device. Bus recovery should be able to fix these situations. But please note: @@ -79,3 +83,54 @@ This is why bus recovery (up to 9 clock pulses) must either check SDA or send additional STOP conditions to ensure the bus has been released. Otherwise random data will be written to a device! +Lost arbitration +================ + +Here, we want to simulate the condition where the master under test loses the +bus arbitration against another master in a multi-master setup. + +"lose_arbitration" +------------------ + +This file is write only and you need to write the duration of the arbitration +intereference (in µs, maximum is 100ms). The calling process will then sleep +and wait for the next bus clock. The process is interruptible, though. + +Arbitration lost is achieved by waiting for SCL going down by the master under +test and then pulling SDA low for some time. So, the I2C address sent out +should be corrupted and that should be detected properly. That means that the +address sent out should have a lot of '1' bits to be able to detect corruption. +There doesn't need to be a device at this address because arbitration lost +should be detected beforehand. Also note, that SCL going down is monitored +using interrupts, so the interrupt latency might cause the first bits to be not +corrupted. A good starting point for using this fault injector on an otherwise +idle bus is: + +# echo 200 > lose_arbitration & +# i2cget -y <bus_to_test> 0x3f + +Panic during transfer +===================== + +This fault injector will create a Kernel panic once the master under test +started a transfer. This usually means that the state machine of the bus master +driver will be ungracefully interrupted and the bus may end up in an unusual +state. Use this to check if your shutdown/reboot/boot code can handle this +scenario. + +"inject_panic" +-------------- + +This file is write only and you need to write the delay between the detected +start of a transmission and the induced Kernel panic (in µs, maximum is 100ms). +The calling process will then sleep and wait for the next bus clock. The +process is interruptible, though. + +Start of a transfer is detected by waiting for SCL going down by the master +under test. A good starting point for using this fault injector is: + +# echo 0 > inject_panic & +# i2cget -y <bus_to_test> <some_address> + +Note that there doesn't need to be a device listening to the address you are +using. Results may vary depending on that, though. diff --git a/Documentation/input/event-codes.rst b/Documentation/input/event-codes.rst index cef220c176a4..b24b5343f5eb 100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@ -190,16 +190,26 @@ A few EV_REL codes have special meanings: * REL_WHEEL, REL_HWHEEL: - These codes are used for vertical and horizontal scroll wheels, - respectively. The value is the number of "notches" moved on the wheel, the - physical size of which varies by device. For high-resolution wheels (which - report multiple events for each notch of movement, or do not have notches) - this may be an approximation based on the high-resolution scroll events. - -* REL_WHEEL_HI_RES: - - - If a vertical scroll wheel supports high-resolution scrolling, this code - will be emitted in addition to REL_WHEEL. The value is the (approximate) - distance travelled by the user's finger, in microns. + respectively. The value is the number of detents moved on the wheel, the + physical size of which varies by device. For high-resolution wheels + this may be an approximation based on the high-resolution scroll events, + see REL_WHEEL_HI_RES. These event codes are legacy codes and + REL_WHEEL_HI_RES and REL_HWHEEL_HI_RES should be preferred where + available. + +* REL_WHEEL_HI_RES, REL_HWHEEL_HI_RES: + + - High-resolution scroll wheel data. The accumulated value 120 represents + movement by one detent. For devices that do not provide high-resolution + scrolling, the value is always a multiple of 120. For devices with + high-resolution scrolling, the value may be a fraction of 120. + + If a vertical scroll wheel supports high-resolution scrolling, this code + will be emitted in addition to REL_WHEEL or REL_HWHEEL. The REL_WHEEL + and REL_HWHEEL may be an approximation based on the high-resolution + scroll events. There is no guarantee that the high-resolution data + is a multiple of 120 at the time of an emulated REL_WHEEL or REL_HWHEEL + event. EV_ABS ------ diff --git a/Documentation/interconnect/interconnect.rst b/Documentation/interconnect/interconnect.rst new file mode 100644 index 000000000000..b8107dcc4cd3 --- /dev/null +++ b/Documentation/interconnect/interconnect.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +GENERIC SYSTEM INTERCONNECT SUBSYSTEM +===================================== + +Introduction +------------ + +This framework is designed to provide a standard kernel interface to control +the settings of the interconnects on an SoC. These settings can be throughput, +latency and priority between multiple interconnected devices or functional +blocks. This can be controlled dynamically in order to save power or provide +maximum performance. + +The interconnect bus is hardware with configurable parameters, which can be +set on a data path according to the requests received from various drivers. +An example of interconnect buses are the interconnects between various +components or functional blocks in chipsets. There can be multiple interconnects +on an SoC that can be multi-tiered. + +Below is a simplified diagram of a real-world SoC interconnect bus topology. + +:: + + +----------------+ +----------------+ + | HW Accelerator |--->| M NoC |<---------------+ + +----------------+ +----------------+ | + | | +------------+ + +-----+ +-------------+ V +------+ | | + | DDR | | +--------+ | PCIe | | | + +-----+ | | Slaves | +------+ | | + ^ ^ | +--------+ | | C NoC | + | | V V | | + +------------------+ +------------------------+ | | +-----+ + | |-->| |-->| |-->| CPU | + | |-->| |<--| | +-----+ + | Mem NoC | | S NoC | +------------+ + | |<--| |---------+ | + | |<--| |<------+ | | +--------+ + +------------------+ +------------------------+ | | +-->| Slaves | + ^ ^ ^ ^ ^ | | +--------+ + | | | | | | V + +------+ | +-----+ +-----+ +---------+ +----------------+ +--------+ + | CPUs | | | GPU | | DSP | | Masters |-->| P NoC |-->| Slaves | + +------+ | +-----+ +-----+ +---------+ +----------------+ +--------+ + | + +-------+ + | Modem | + +-------+ + +Terminology +----------- + +Interconnect provider is the software definition of the interconnect hardware. +The interconnect providers on the above diagram are M NoC, S NoC, C NoC, P NoC +and Mem NoC. + +Interconnect node is the software definition of the interconnect hardware +port. Each interconnect provider consists of multiple interconnect nodes, +which are connected to other SoC components including other interconnect +providers. The point on the diagram where the CPUs connect to the memory is +called an interconnect node, which belongs to the Mem NoC interconnect provider. + +Interconnect endpoints are the first or the last element of the path. Every +endpoint is a node, but not every node is an endpoint. + +Interconnect path is everything between two endpoints including all the nodes +that have to be traversed to reach from a source to destination node. It may +include multiple master-slave pairs across several interconnect providers. + +Interconnect consumers are the entities which make use of the data paths exposed +by the providers. The consumers send requests to providers requesting various +throughput, latency and priority. Usually the consumers are device drivers, that +send request based on their needs. An example for a consumer is a video decoder +that supports various formats and image sizes. + +Interconnect providers +---------------------- + +Interconnect provider is an entity that implements methods to initialize and +configure interconnect bus hardware. The interconnect provider drivers should +be registered with the interconnect provider core. + +.. kernel-doc:: include/linux/interconnect-provider.h + +Interconnect consumers +---------------------- + +Interconnect consumers are the clients which use the interconnect APIs to +get paths between endpoints and set their bandwidth/latency/QoS requirements +for these interconnect paths. + +.. kernel-doc:: include/linux/interconnect.h diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 13a7c999c04a..c9558146ac58 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -79,6 +79,7 @@ Code Seq#(hex) Include File Comments 0x1b all InfiniBand Subsystem <http://infiniband.sourceforge.net/> 0x20 all drivers/cdrom/cm206.h 0x22 all scsi/sg.h +'!' 00-1F uapi/linux/seccomp.h '#' 00-3F IEEE 1394 Subsystem Block for the entire subsystem '$' 00-0F linux/perf_counter.h, linux/perf_event.h '%' 00-0F include/uapi/linux/stm.h @@ -201,7 +202,7 @@ Code Seq#(hex) Include File Comments 'X' 01 linux/pktcdvd.h conflict! 'Y' all linux/cyclades.h 'Z' 14-15 drivers/message/fusion/mptctl.h -'[' 00-07 linux/usb/tmc.h USB Test and Measurement Devices +'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices <mailto:gregkh@linuxfoundation.org> 'a' all linux/atm*.h, linux/sonet.h ATM on linux <http://lrcwww.epfl.ch/> @@ -272,6 +273,7 @@ Code Seq#(hex) Include File Comments 't' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM 'u' 00-1F linux/smb_fs.h gone 'u' 20-3F linux/uvcvideo.h USB video class host driver +'u' 40-4f linux/udmabuf.h userspace dma-buf misc device 'v' 00-1F linux/ext2_fs.h conflict! 'v' 00-1F linux/fs.h conflict! 'v' 00-0F linux/sonypi.h conflict! diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.txt index 8390c360d4b3..c9e3d93e7a89 100644 --- a/Documentation/kbuild/kbuild.txt +++ b/Documentation/kbuild/kbuild.txt @@ -81,12 +81,7 @@ KBUILD_EXTMOD -------------------------------------------------- Set the directory to look for the kernel source when building external modules. -The directory can be specified in several ways: -1) Use "M=..." on the command line -2) Environment variable KBUILD_EXTMOD -3) Environment variable SUBDIRS -The possibilities are listed in the order they take precedence. -Using "M=..." will always override the others. +Setting "M=..." takes precedence over KBUILD_EXTMOD. KBUILD_OUTPUT -------------------------------------------------- diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index 7b6a2b2bdc98..bf28c47bfd72 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -537,21 +537,6 @@ more details, with real examples. The third parameter may be a text as in this example, but it may also be an expanded variable or a macro. - cc-fullversion - cc-fullversion is useful when the exact version of gcc is needed. - One typical use-case is when a specific GCC version is broken. - cc-fullversion points out a more specific version than cc-version does. - - Example: - #arch/powerpc/Makefile - $(Q)if test "$(cc-fullversion)" = "040200" ; then \ - echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \ - false ; \ - fi - - In this example for a specific GCC version the build will error out - explaining to the user why it stops. - cc-cross-prefix cc-cross-prefix is used to check if there exists a $(CC) in path with one of the listed prefixes. The first prefix where there exist a @@ -1311,9 +1296,12 @@ See subsequent chapter for the syntax of the Kbuild file. --- 7.4 mandatory-y - mandatory-y is essentially used by include/uapi/asm-generic/Kbuild.asm - to define the minimum set of headers that must be exported in - include/asm. + mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild.asm + to define the minimum set of ASM headers that all architectures must have. + + This works like optional generic-y. If a mandatory header is missing + in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate + a wrapper of the asm-generic one. The convention is to list one subdir per line and preferably in alphabetic order. diff --git a/Documentation/kdump/vmcoreinfo.txt b/Documentation/kdump/vmcoreinfo.txt new file mode 100644 index 000000000000..bb94a4bd597a --- /dev/null +++ b/Documentation/kdump/vmcoreinfo.txt @@ -0,0 +1,495 @@ +================================================================ + VMCOREINFO +================================================================ + +=========== +What is it? +=========== + +VMCOREINFO is a special ELF note section. It contains various +information from the kernel like structure size, page size, symbol +values, field offsets, etc. These data are packed into an ELF note +section and used by user-space tools like crash and makedumpfile to +analyze a kernel's memory layout. + +================ +Common variables +================ + +init_uts_ns.name.release +------------------------ + +The version of the Linux kernel. Used to find the corresponding source +code from which the kernel has been built. For example, crash uses it to +find the corresponding vmlinux in order to process vmcore. + +PAGE_SIZE +--------- + +The size of a page. It is the smallest unit of data used by the memory +management facilities. It is usually 4096 bytes of size and a page is +aligned on 4096 bytes. Used for computing page addresses. + +init_uts_ns +----------- + +The UTS namespace which is used to isolate two specific elements of the +system that relate to the uname(2) system call. It is named after the +data structure used to store information returned by the uname(2) system +call. + +User-space tools can get the kernel name, host name, kernel release +number, kernel version, architecture name and OS type from it. + +node_online_map +--------------- + +An array node_states[N_ONLINE] which represents the set of online nodes +in a system, one bit position per node number. Used to keep track of +which nodes are in the system and online. + +swapper_pg_dir +------------- + +The global page directory pointer of the kernel. Used to translate +virtual to physical addresses. + +_stext +------ + +Defines the beginning of the text section. In general, _stext indicates +the kernel start address. Used to convert a virtual address from the +direct kernel map to a physical address. + +vmap_area_list +-------------- + +Stores the virtual area list. makedumpfile gets the vmalloc start value +from this variable and its value is necessary for vmalloc translation. + +mem_map +------- + +Physical addresses are translated to struct pages by treating them as +an index into the mem_map array. Right-shifting a physical address +PAGE_SHIFT bits converts it into a page frame number which is an index +into that mem_map array. + +Used to map an address to the corresponding struct page. + +contig_page_data +---------------- + +Makedumpfile gets the pglist_data structure from this symbol, which is +used to describe the memory layout. + +User-space tools use this to exclude free pages when dumping memory. + +mem_section|(mem_section, NR_SECTION_ROOTS)|(mem_section, section_mem_map) +-------------------------------------------------------------------------- + +The address of the mem_section array, its length, structure size, and +the section_mem_map offset. + +It exists in the sparse memory mapping model, and it is also somewhat +similar to the mem_map variable, both of them are used to translate an +address. + +page +---- + +The size of a page structure. struct page is an important data structure +and it is widely used to compute contiguous memory. + +pglist_data +----------- + +The size of a pglist_data structure. This value is used to check if the +pglist_data structure is valid. It is also used for checking the memory +type. + +zone +---- + +The size of a zone structure. This value is used to check if the zone +structure has been found. It is also used for excluding free pages. + +free_area +--------- + +The size of a free_area structure. It indicates whether the free_area +structure is valid or not. Useful when excluding free pages. + +list_head +--------- + +The size of a list_head structure. Used when iterating lists in a +post-mortem analysis session. + +nodemask_t +---------- + +The size of a nodemask_t type. Used to compute the number of online +nodes. + +(page, flags|_refcount|mapping|lru|_mapcount|private|compound_dtor| + compound_order|compound_head) +------------------------------------------------------------------- + +User-space tools compute their values based on the offset of these +variables. The variables are used when excluding unnecessary pages. + +(pglist_data, node_zones|nr_zones|node_mem_map|node_start_pfn|node_ + spanned_pages|node_id) +------------------------------------------------------------------- + +On NUMA machines, each NUMA node has a pg_data_t to describe its memory +layout. On UMA machines there is a single pglist_data which describes the +whole memory. + +These values are used to check the memory type and to compute the +virtual address for memory map. + +(zone, free_area|vm_stat|spanned_pages) +--------------------------------------- + +Each node is divided into a number of blocks called zones which +represent ranges within memory. A zone is described by a structure zone. + +User-space tools compute required values based on the offset of these +variables. + +(free_area, free_list) +---------------------- + +Offset of the free_list's member. This value is used to compute the number +of free pages. + +Each zone has a free_area structure array called free_area[MAX_ORDER]. +The free_list represents a linked list of free page blocks. + +(list_head, next|prev) +---------------------- + +Offsets of the list_head's members. list_head is used to define a +circular linked list. User-space tools need these in order to traverse +lists. + +(vmap_area, va_start|list) +-------------------------- + +Offsets of the vmap_area's members. They carry vmalloc-specific +information. Makedumpfile gets the start address of the vmalloc region +from this. + +(zone.free_area, MAX_ORDER) +--------------------------- + +Free areas descriptor. User-space tools use this value to iterate the +free_area ranges. MAX_ORDER is used by the zone buddy allocator. + +log_first_idx +------------- + +Index of the first record stored in the buffer log_buf. Used by +user-space tools to read the strings in the log_buf. + +log_buf +------- + +Console output is written to the ring buffer log_buf at index +log_first_idx. Used to get the kernel log. + +log_buf_len +----------- + +log_buf's length. + +clear_idx +--------- + +The index that the next printk() record to read after the last clear +command. It indicates the first record after the last SYSLOG_ACTION +_CLEAR, like issued by 'dmesg -c'. Used by user-space tools to dump +the dmesg log. + +log_next_idx +------------ + +The index of the next record to store in the buffer log_buf. Used to +compute the index of the current buffer position. + +printk_log +---------- + +The size of a structure printk_log. Used to compute the size of +messages, and extract dmesg log. It encapsulates header information for +log_buf, such as timestamp, syslog level, etc. + +(printk_log, ts_nsec|len|text_len|dict_len) +------------------------------------------- + +It represents field offsets in struct printk_log. User space tools +parse it and check whether the values of printk_log's members have been +changed. + +(free_area.free_list, MIGRATE_TYPES) +------------------------------------ + +The number of migrate types for pages. The free_list is described by the +array. Used by tools to compute the number of free pages. + +NR_FREE_PAGES +------------- + +On linux-2.6.21 or later, the number of free pages is in +vm_stat[NR_FREE_PAGES]. Used to get the number of free pages. + +PG_lru|PG_private|PG_swapcache|PG_swapbacked|PG_slab|PG_hwpoision +|PG_head_mask|PAGE_BUDDY_MAPCOUNT_VALUE(~PG_buddy) +|PAGE_OFFLINE_MAPCOUNT_VALUE(~PG_offline) +----------------------------------------------------------------- + +Page attributes. These flags are used to filter various unnecessary for +dumping pages. + +HUGETLB_PAGE_DTOR +----------------- + +The HUGETLB_PAGE_DTOR flag denotes hugetlbfs pages. Makedumpfile +excludes these pages. + +====== +x86_64 +====== + +phys_base +--------- + +Used to convert the virtual address of an exported kernel symbol to its +corresponding physical address. + +init_top_pgt +------------ + +Used to walk through the whole page table and convert virtual addresses +to physical addresses. The init_top_pgt is somewhat similar to +swapper_pg_dir, but it is only used in x86_64. + +pgtable_l5_enabled +------------------ + +User-space tools need to know whether the crash kernel was in 5-level +paging mode. + +node_data +--------- + +This is a struct pglist_data array and stores all NUMA nodes +information. Makedumpfile gets the pglist_data structure from it. + +(node_data, MAX_NUMNODES) +------------------------- + +The maximum number of nodes in system. + +KERNELOFFSET +------------ + +The kernel randomization offset. Used to compute the page offset. If +KASLR is disabled, this value is zero. + +KERNEL_IMAGE_SIZE +----------------- + +Currently unused by Makedumpfile. Used to compute the module virtual +address by Crash. + +sme_mask +-------- + +AMD-specific with SME support: it indicates the secure memory encryption +mask. Makedumpfile tools need to know whether the crash kernel was +encrypted. If SME is enabled in the first kernel, the crash kernel's +page table entries (pgd/pud/pmd/pte) contain the memory encryption +mask. This is used to remove the SME mask and obtain the true physical +address. + +Currently, sme_mask stores the value of the C-bit position. If needed, +additional SME-relevant info can be placed in that variable. + +For example: +[ misc ][ enc bit ][ other misc SME info ] +0000_0000_0000_0000_1000_0000_0000_0000_0000_0000_..._0000 +63 59 55 51 47 43 39 35 31 27 ... 3 + +====== +x86_32 +====== + +X86_PAE +------- + +Denotes whether physical address extensions are enabled. It has the cost +of a higher page table lookup overhead, and also consumes more page +table space per process. Used to check whether PAE was enabled in the +crash kernel when converting virtual addresses to physical addresses. + +==== +ia64 +==== + +pgdat_list|(pgdat_list, MAX_NUMNODES) +------------------------------------- + +pg_data_t array storing all NUMA nodes information. MAX_NUMNODES +indicates the number of the nodes. + +node_memblk|(node_memblk, NR_NODE_MEMBLKS) +------------------------------------------ + +List of node memory chunks. Filled when parsing the SRAT table to obtain +information about memory nodes. NR_NODE_MEMBLKS indicates the number of +node memory chunks. + +These values are used to compute the number of nodes the crashed kernel used. + +node_memblk_s|(node_memblk_s, start_paddr)|(node_memblk_s, size) +---------------------------------------------------------------- + +The size of a struct node_memblk_s and the offsets of the +node_memblk_s's members. Used to compute the number of nodes. + +PGTABLE_3|PGTABLE_4 +------------------- + +User-space tools need to know whether the crash kernel was in 3-level or +4-level paging mode. Used to distinguish the page table. + +===== +ARM64 +===== + +VA_BITS +------- + +The maximum number of bits for virtual addresses. Used to compute the +virtual memory ranges. + +kimage_voffset +-------------- + +The offset between the kernel virtual and physical mappings. Used to +translate virtual to physical addresses. + +PHYS_OFFSET +----------- + +Indicates the physical address of the start of memory. Similar to +kimage_voffset, which is used to translate virtual to physical +addresses. + +KERNELOFFSET +------------ + +The kernel randomization offset. Used to compute the page offset. If +KASLR is disabled, this value is zero. + +==== +arm +==== + +ARM_LPAE +-------- + +It indicates whether the crash kernel supports large physical address +extensions. Used to translate virtual to physical addresses. + +==== +s390 +==== + +lowcore_ptr +---------- + +An array with a pointer to the lowcore of every CPU. Used to print the +psw and all registers information. + +high_memory +----------- + +Used to get the vmalloc_start address from the high_memory symbol. + +(lowcore_ptr, NR_CPUS) +---------------------- + +The maximum number of CPUs. + +======= +powerpc +======= + + +node_data|(node_data, MAX_NUMNODES) +----------------------------------- + +See above. + +contig_page_data +---------------- + +See above. + +vmemmap_list +------------ + +The vmemmap_list maintains the entire vmemmap physical mapping. Used +to get vmemmap list count and populated vmemmap regions info. If the +vmemmap address translation information is stored in the crash kernel, +it is used to translate vmemmap kernel virtual addresses. + +mmu_vmemmap_psize +----------------- + +The size of a page. Used to translate virtual to physical addresses. + +mmu_psize_defs +-------------- + +Page size definitions, i.e. 4k, 64k, or 16M. + +Used to make vtop translations. + +vmemmap_backing|(vmemmap_backing, list)|(vmemmap_backing, phys)| +(vmemmap_backing, virt_addr) +---------------------------------------------------------------- + +The vmemmap virtual address space management does not have a traditional +page table to track which virtual struct pages are backed by a physical +mapping. The virtual to physical mappings are tracked in a simple linked +list format. + +User-space tools need to know the offset of list, phys and virt_addr +when computing the count of vmemmap regions. + +mmu_psize_def|(mmu_psize_def, shift) +------------------------------------ + +The size of a struct mmu_psize_def and the offset of mmu_psize_def's +member. + +Used in vtop translations. + +== +sh +== + +node_data|(node_data, MAX_NUMNODES) +----------------------------------- + +See above. + +X2TLB +----- + +Indicates whether the crashed kernel enabled SH extended mode. diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index fc9485d79061..ff4c25098119 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -279,10 +279,14 @@ such a method has a form like:: One important point cannot be overstated: every kobject must have a release() method, and the kobject must persist (in a consistent state) until that method is called. If these constraints are not met, the code is -flawed. Note that the kernel will warn you if you forget to provide a +flawed. Note that the kernel will warn you if you forget to provide a release() method. Do not try to get rid of this warning by providing an -"empty" release function; you will be mocked mercilessly by the kobject -maintainer if you attempt this. +"empty" release function. + +If all your cleanup function needs to do is call kfree(), then you must +create a wrapper function which uses container_of() to upcast to the correct +type (as shown in the example above) and then calls kfree() on the overall +structure. Note, the name of the kobject is available in the release function, but it must NOT be changed within this callback. Otherwise there will be a memory diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst new file mode 100644 index 000000000000..e486fe7ddc35 --- /dev/null +++ b/Documentation/laptops/lg-laptop.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0+ +LG Gram laptop extra features +============================= + +By Matan Ziv-Av <matan@svgalib.org> + + +Hotkeys +------- + +The following FN keys are ignored by the kernel without this driver: +- FN-F1 (LG control panel) - Generates F15 +- FN-F5 (Touchpad toggle) - Generates F13 +- FN-F6 (Airplane mode) - Generates RFKILL +- FN-F8 (Keyboard backlight) - Generates F16. + This key also changes keyboard backlight mode. +- FN-F9 (Reader mode) - Generates F14 + +The rest of the FN key work without a need for a special driver. + + +Reader mode +----------- + +Writing 0/1 to /sys/devices/platform/lg-laptop/reader_mode disables/enables +reader mode. In this mode the screen colors change (blue color reduced), +and the reader mode indicator LED (on F9 key) turns on. + + +FN Lock +------- + +Writing 0/1 to /sys/devices/platform/lg-laptop/fn_lock disables/enables +FN lock. + + +Battery care limit +------------------ + +Writing 80/100 to /sys/devices/platform/lg-laptop/battery_care_limit +sets the maximum capacity to charge the battery. Limiting the charge +reduces battery capacity loss over time. + +This value is reset to 100 when the kernel boots. + + +Fan mode +-------- + +Writing 1/0 to /sys/devices/platform/lg-laptop/fan_mode disables/enables +the fan silent mode. + + +USB charge +---------- + +Writing 0/1 to /sys/devices/platform/lg-laptop/usb_charge disables/enables +charging another device from the USB port while the device is turned off. + +This value is reset to 0 when the kernel boots. + + +LEDs +~~~~ + +The are two LED devices supported by the driver: + +Keyboard backlight +------------------ + +A led device named kbd_led controls the keyboard backlight. There are three +lighting level: off (0), low (127) and high (255). + +The keyboard backlight is also controlled by the key combination FN-F8 +which cycles through those levels. + + +Touchpad indicator LED +---------------------- + +On the F5 key. Controlled by led device names tpad_led. diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.txt index 836cb16d6f09..8b39cc6b03ee 100644 --- a/Documentation/leds/leds-class.txt +++ b/Documentation/leds/leds-class.txt @@ -15,7 +15,7 @@ existing subsystems with minimal additional code. Examples are the disk-activity nand-disk and sharpsl-charge triggers. With led triggers disabled, the code optimises away. -Complex triggers whilst available to all LEDs have LED specific +Complex triggers while available to all LEDs have LED specific parameters and work on a per LED basis. The timer trigger is an example. The timer trigger will periodically change the LED brightness between LED_OFF and the current brightness setting. The "on" and "off" time can diff --git a/Documentation/livepatch/callbacks.txt b/Documentation/livepatch/callbacks.txt index c9776f48e458..182e31d4abce 100644 --- a/Documentation/livepatch/callbacks.txt +++ b/Documentation/livepatch/callbacks.txt @@ -118,488 +118,9 @@ similar change to their hw_features value. (Client functions of the value may need to be updated accordingly.) -Test cases -========== - -What follows is not an exhaustive test suite of every possible livepatch -pre/post-(un)patch combination, but a selection that demonstrates a few -important concepts. Each test case uses the kernel modules located in -the samples/livepatch/ and assumes that no livepatches are loaded at the -beginning of the test. - - -Test 1 ------- - -Test a combination of loading a kernel module and a livepatch that -patches a function in the first module. (Un)load the target module -before the livepatch module: - -- load target module -- load livepatch -- disable livepatch -- unload target module -- unload livepatch - -First load a target module: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 34.475708] livepatch_callbacks_mod: livepatch_callbacks_mod_init - -On livepatch enable, before the livepatch transition starts, pre-patch -callbacks are executed for vmlinux and livepatch_callbacks_mod (those -klp_objects currently loaded). After klp_objects are patched according -to the klp_patch, their post-patch callbacks run and the transition -completes: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 36.503719] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 36.504213] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 36.504238] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 36.504721] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 36.505849] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 37.727133] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 37.727232] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 37.727860] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 37.728792] livepatch: 'livepatch_callbacks_demo': patching complete - -Similarly, on livepatch disable, pre-patch callbacks run before the -unpatching transition starts. klp_objects are reverted, post-patch -callbacks execute and the transition completes: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 38.510209] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 38.510234] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 38.510982] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 38.512209] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 39.711132] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 39.711210] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 39.711779] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 39.712735] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 42.534183] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - - -Test 2 ------- - -This test is similar to the previous test, but (un)load the livepatch -module before the target kernel module. This tests the livepatch core's -module_coming handler: - -- load livepatch -- load target module -- disable livepatch -- unload livepatch -- unload target module - - -On livepatch enable, only pre/post-patch callbacks are executed for -currently loaded klp_objects, in this case, vmlinux: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 44.553328] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 44.553997] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 44.554049] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 44.554845] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 45.727128] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 45.727212] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 45.727961] livepatch: 'livepatch_callbacks_demo': patching complete - -When a targeted module is subsequently loaded, only its pre/post-patch -callbacks are executed: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 46.560845] livepatch: applying patch 'livepatch_callbacks_demo' to loading module 'livepatch_callbacks_mod' - [ 46.561988] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 46.563452] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 46.565495] livepatch_callbacks_mod: livepatch_callbacks_mod_init - -On livepatch disable, all currently loaded klp_objects' (vmlinux and -livepatch_callbacks_mod) pre/post-unpatch callbacks are executed: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 48.568885] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 48.568910] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 48.569441] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 48.570502] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 49.759091] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 49.759171] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 49.759742] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 49.760690] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 52.592283] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - - -Test 3 ------- - -Test loading the livepatch after a targeted kernel module, then unload -the kernel module before disabling the livepatch. This tests the -livepatch core's module_going handler: - -- load target module -- load livepatch -- unload target module -- disable livepatch -- unload livepatch - -First load a target module, then the livepatch: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 54.607948] livepatch_callbacks_mod: livepatch_callbacks_mod_init - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 56.613919] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 56.614411] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 56.614436] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 56.614818] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 56.615656] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 57.759070] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 57.759147] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 57.759621] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_LIVE] Normal state - [ 57.760307] livepatch: 'livepatch_callbacks_demo': patching complete - -When a target module is unloaded, the livepatch is only reverted from -that klp_object (livepatch_callbacks_mod). As such, only its pre and -post-unpatch callbacks are executed when this occurs: - - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 58.623409] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - [ 58.623903] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - [ 58.624658] livepatch: reverting patch 'livepatch_callbacks_demo' on unloading module 'livepatch_callbacks_mod' - [ 58.625305] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - -When the livepatch is disabled, pre and post-unpatch callbacks are run -for the remaining klp_object, vmlinux: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 60.638420] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 60.638444] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 60.638996] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 61.727088] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 61.727165] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 61.727985] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - - -Test 4 ------- - -This test is similar to the previous test, however the livepatch is -loaded first. This tests the livepatch core's module_coming and -module_going handlers: - -- load livepatch -- load target module -- unload target module -- disable livepatch -- unload livepatch - -First load the livepatch: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 64.661552] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 64.662147] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 64.662175] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 64.662850] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 65.695056] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 65.695147] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 65.695561] livepatch: 'livepatch_callbacks_demo': patching complete - -When a targeted kernel module is subsequently loaded, only its -pre/post-patch callbacks are executed: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 66.669196] livepatch: applying patch 'livepatch_callbacks_demo' to loading module 'livepatch_callbacks_mod' - [ 66.669882] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 66.670744] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 66.672873] livepatch_callbacks_mod: livepatch_callbacks_mod_init - -When the target module is unloaded, the livepatch is only reverted from -the livepatch_callbacks_mod klp_object. As such, only pre and -post-unpatch callbacks are executed when this occurs: - - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 68.680065] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - [ 68.680688] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - [ 68.681452] livepatch: reverting patch 'livepatch_callbacks_demo' on unloading module 'livepatch_callbacks_mod' - [ 68.682094] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 70.689225] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 70.689256] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 70.689882] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 71.711080] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 71.711481] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 71.711988] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - - -Test 5 ------- - -A simple test of loading a livepatch without one of its patch target -klp_objects ever loaded (livepatch_callbacks_mod): - -- load livepatch -- disable livepatch -- unload livepatch - -Load the livepatch: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 74.711081] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 74.711595] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 74.711639] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 74.712272] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 75.743137] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 75.743219] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 75.743867] livepatch: 'livepatch_callbacks_demo': patching complete - -As expected, only pre/post-(un)patch handlers are executed for vmlinux: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 76.716254] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 76.716278] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 76.716666] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 77.727089] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 77.727194] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 77.727907] livepatch: 'livepatch_callbacks_demo': unpatching complete +Other Examples +============== - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - - -Test 6 ------- - -Test a scenario where a vmlinux pre-patch callback returns a non-zero -status (ie, failure): - -- load target module -- load livepatch -ENODEV -- unload target module - -First load a target module: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 80.740520] livepatch_callbacks_mod: livepatch_callbacks_mod_init - -Load the livepatch module, setting its 'pre_patch_ret' value to -19 -(-ENODEV). When its vmlinux pre-patch callback executed, this status -code will propagate back to the module-loading subsystem. The result is -that the insmod command refuses to load the livepatch module: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko pre_patch_ret=-19 - [ 82.747326] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 82.747743] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 82.747767] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 82.748237] livepatch: pre-patch callback failed for object 'vmlinux' - [ 82.748637] livepatch: failed to enable patch 'livepatch_callbacks_demo' - [ 82.749059] livepatch: 'livepatch_callbacks_demo': canceling transition, going to unpatch - [ 82.749060] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 82.749868] livepatch: 'livepatch_callbacks_demo': unpatching complete - [ 82.765809] insmod: ERROR: could not insert module samples/livepatch/livepatch-callbacks-demo.ko: No such device - - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 84.774238] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - - -Test 7 ------- - -Similar to the previous test, setup a livepatch such that its vmlinux -pre-patch callback returns success. However, when a targeted kernel -module is later loaded, have the livepatch return a failing status code: - -- load livepatch -- setup -ENODEV -- load target module -- disable livepatch -- unload livepatch - -Load the livepatch, notice vmlinux pre-patch callback succeeds: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 86.787845] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 86.788325] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 86.788427] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 86.788821] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 87.711069] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 87.711143] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 87.711886] livepatch: 'livepatch_callbacks_demo': patching complete - -Set a trap so subsequent pre-patch callbacks to this livepatch will -return -ENODEV: - - % echo -19 > /sys/module/livepatch_callbacks_demo/parameters/pre_patch_ret - -The livepatch pre-patch callback for subsequently loaded target modules -will return failure, so the module loader refuses to load the kernel -module. Notice that no post-patch or pre/post-unpatch callbacks are -executed for this klp_object: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 90.796976] livepatch: applying patch 'livepatch_callbacks_demo' to loading module 'livepatch_callbacks_mod' - [ 90.797834] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 90.798900] livepatch: pre-patch callback failed for object 'livepatch_callbacks_mod' - [ 90.799652] livepatch: patch 'livepatch_callbacks_demo' failed for module 'livepatch_callbacks_mod', refusing to load module 'livepatch_callbacks_mod' - [ 90.819737] insmod: ERROR: could not insert module samples/livepatch/livepatch-callbacks-mod.ko: No such device - -However, pre/post-unpatch callbacks run for the vmlinux klp_object: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 92.823547] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 92.823573] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 92.824331] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 93.727128] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 93.727327] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 93.727861] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - - -Test 8 ------- - -Test loading multiple targeted kernel modules. This test-case is -mainly for comparing with the next test-case. - -- load busy target module (0s sleep), -- load livepatch -- load target module -- unload target module -- disable livepatch -- unload livepatch -- unload busy target module - - -Load a target "busy" kernel module which kicks off a worker function -that immediately exits: - - % insmod samples/livepatch/livepatch-callbacks-busymod.ko sleep_secs=0 - [ 96.910107] livepatch_callbacks_busymod: livepatch_callbacks_mod_init - [ 96.910600] livepatch_callbacks_busymod: busymod_work_func, sleeping 0 seconds ... - [ 96.913024] livepatch_callbacks_busymod: busymod_work_func exit - -Proceed with loading the livepatch and another ordinary target module, -notice that the post-patch callbacks are executed and the transition -completes quickly: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 98.917892] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 98.918426] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 98.918453] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 98.918955] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 98.923835] livepatch: 'livepatch_callbacks_demo': starting patching transition - [ 99.743104] livepatch: 'livepatch_callbacks_demo': completing patching transition - [ 99.743156] livepatch_callbacks_demo: post_patch_callback: vmlinux - [ 99.743679] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 99.744616] livepatch: 'livepatch_callbacks_demo': patching complete - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 100.930955] livepatch: applying patch 'livepatch_callbacks_demo' to loading module 'livepatch_callbacks_mod' - [ 100.931668] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 100.932645] livepatch_callbacks_demo: post_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 100.934125] livepatch_callbacks_mod: livepatch_callbacks_mod_init - - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 102.942805] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - [ 102.943640] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - [ 102.944585] livepatch: reverting patch 'livepatch_callbacks_demo' on unloading module 'livepatch_callbacks_mod' - [ 102.945455] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 104.953815] livepatch: 'livepatch_callbacks_demo': initializing unpatching transition - [ 104.953838] livepatch_callbacks_demo: pre_unpatch_callback: vmlinux - [ 104.954431] livepatch_callbacks_demo: pre_unpatch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 104.955426] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 106.719073] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 106.722633] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 106.723282] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 106.724279] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - % rmmod samples/livepatch/livepatch-callbacks-busymod.ko - [ 108.975660] livepatch_callbacks_busymod: livepatch_callbacks_mod_exit - - -Test 9 ------- - -A similar test as the previous one, but force the "busy" kernel module -to do longer work. - -The livepatching core will refuse to patch a task that is currently -executing a to-be-patched function -- the consistency model stalls the -current patch transition until this safety-check is met. Test a -scenario where one of a livepatch's target klp_objects sits on such a -function for a long time. Meanwhile, load and unload other target -kernel modules while the livepatch transition is in progress. - -- load busy target module (30s sleep) -- load livepatch -- load target module -- unload target module -- disable livepatch -- unload livepatch -- unload busy target module - - -Load the "busy" kernel module, this time make it do 30 seconds worth of -work: - - % insmod samples/livepatch/livepatch-callbacks-busymod.ko sleep_secs=30 - [ 110.993362] livepatch_callbacks_busymod: livepatch_callbacks_mod_init - [ 110.994059] livepatch_callbacks_busymod: busymod_work_func, sleeping 30 seconds ... - -Meanwhile, the livepatch is loaded. Notice that the patch transition -does not complete as the targeted "busy" module is sitting on a -to-be-patched function: - - % insmod samples/livepatch/livepatch-callbacks-demo.ko - [ 113.000309] livepatch: enabling patch 'livepatch_callbacks_demo' - [ 113.000764] livepatch: 'livepatch_callbacks_demo': initializing patching transition - [ 113.000791] livepatch_callbacks_demo: pre_patch_callback: vmlinux - [ 113.001289] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 113.005208] livepatch: 'livepatch_callbacks_demo': starting patching transition - -Load a second target module (this one is an ordinary idle kernel -module). Note that *no* post-patch callbacks will be executed while the -livepatch is still in transition: - - % insmod samples/livepatch/livepatch-callbacks-mod.ko - [ 115.012740] livepatch: applying patch 'livepatch_callbacks_demo' to loading module 'livepatch_callbacks_mod' - [ 115.013406] livepatch_callbacks_demo: pre_patch_callback: livepatch_callbacks_mod -> [MODULE_STATE_COMING] Full formed, running module_init - [ 115.015315] livepatch_callbacks_mod: livepatch_callbacks_mod_init - -Request an unload of the simple kernel module. The patch is still -transitioning, so its pre-unpatch callbacks are skipped: - - % rmmod samples/livepatch/livepatch-callbacks-mod.ko - [ 117.022626] livepatch_callbacks_mod: livepatch_callbacks_mod_exit - [ 117.023376] livepatch: reverting patch 'livepatch_callbacks_demo' on unloading module 'livepatch_callbacks_mod' - [ 117.024533] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_mod -> [MODULE_STATE_GOING] Going away - -Finally the livepatch is disabled. Since none of the patch's -klp_object's post-patch callbacks executed, the remaining klp_object's -pre-unpatch callbacks are skipped: - - % echo 0 > /sys/kernel/livepatch/livepatch_callbacks_demo/enabled - [ 119.035408] livepatch: 'livepatch_callbacks_demo': reversing transition from patching to unpatching - [ 119.035485] livepatch: 'livepatch_callbacks_demo': starting unpatching transition - [ 119.711166] livepatch: 'livepatch_callbacks_demo': completing unpatching transition - [ 119.714179] livepatch_callbacks_demo: post_unpatch_callback: vmlinux - [ 119.714653] livepatch_callbacks_demo: post_unpatch_callback: livepatch_callbacks_busymod -> [MODULE_STATE_LIVE] Normal state - [ 119.715437] livepatch: 'livepatch_callbacks_demo': unpatching complete - - % rmmod samples/livepatch/livepatch-callbacks-demo.ko - % rmmod samples/livepatch/livepatch-callbacks-busymod.ko - [ 141.279111] livepatch_callbacks_busymod: busymod_work_func exit - [ 141.279760] livepatch_callbacks_busymod: livepatch_callbacks_mod_exit +Sample livepatch modules demonstrating the callback API can be found in +samples/livepatch/ directory. These samples were modified for use in +kselftests and can be found in the lib/livepatch directory. diff --git a/Documentation/livepatch/cumulative-patches.txt b/Documentation/livepatch/cumulative-patches.txt new file mode 100644 index 000000000000..0012808e8d44 --- /dev/null +++ b/Documentation/livepatch/cumulative-patches.txt @@ -0,0 +1,102 @@ +=================================== +Atomic Replace & Cumulative Patches +=================================== + +There might be dependencies between livepatches. If multiple patches need +to do different changes to the same function(s) then we need to define +an order in which the patches will be installed. And function implementations +from any newer livepatch must be done on top of the older ones. + +This might become a maintenance nightmare. Especially when more patches +modified the same function in different ways. + +An elegant solution comes with the feature called "Atomic Replace". It allows +creation of so called "Cumulative Patches". They include all wanted changes +from all older livepatches and completely replace them in one transition. + +Usage +----- + +The atomic replace can be enabled by setting "replace" flag in struct klp_patch, +for example: + + static struct klp_patch patch = { + .mod = THIS_MODULE, + .objs = objs, + .replace = true, + }; + +All processes are then migrated to use the code only from the new patch. +Once the transition is finished, all older patches are automatically +disabled. + +Ftrace handlers are transparently removed from functions that are no +longer modified by the new cumulative patch. + +As a result, the livepatch authors might maintain sources only for one +cumulative patch. It helps to keep the patch consistent while adding or +removing various fixes or features. + +Users could keep only the last patch installed on the system after +the transition to has finished. It helps to clearly see what code is +actually in use. Also the livepatch might then be seen as a "normal" +module that modifies the kernel behavior. The only difference is that +it can be updated at runtime without breaking its functionality. + + +Features +-------- + +The atomic replace allows: + + + Atomically revert some functions in a previous patch while + upgrading other functions. + + + Remove eventual performance impact caused by core redirection + for functions that are no longer patched. + + + Decrease user confusion about dependencies between livepatches. + + +Limitations: +------------ + + + Once the operation finishes, there is no straightforward way + to reverse it and restore the replaced patches atomically. + + A good practice is to set .replace flag in any released livepatch. + Then re-adding an older livepatch is equivalent to downgrading + to that patch. This is safe as long as the livepatches do _not_ do + extra modifications in (un)patching callbacks or in the module_init() + or module_exit() functions, see below. + + Also note that the replaced patch can be removed and loaded again + only when the transition was not forced. + + + + Only the (un)patching callbacks from the _new_ cumulative livepatch are + executed. Any callbacks from the replaced patches are ignored. + + In other words, the cumulative patch is responsible for doing any actions + that are necessary to properly replace any older patch. + + As a result, it might be dangerous to replace newer cumulative patches by + older ones. The old livepatches might not provide the necessary callbacks. + + This might be seen as a limitation in some scenarios. But it makes life + easier in many others. Only the new cumulative livepatch knows what + fixes/features are added/removed and what special actions are necessary + for a smooth transition. + + In any case, it would be a nightmare to think about the order of + the various callbacks and their interactions if the callbacks from all + enabled patches were called. + + + + There is no special handling of shadow variables. Livepatch authors + must create their own rules how to pass them from one cumulative + patch to the other. Especially that they should not blindly remove + them in module_exit() functions. + + A good practice might be to remove shadow variables in the post-unpatch + callback. It is called only when the livepatch is properly disabled. diff --git a/Documentation/livepatch/livepatch.txt b/Documentation/livepatch/livepatch.txt index 2d7ed09dbd59..4627b41ff02e 100644 --- a/Documentation/livepatch/livepatch.txt +++ b/Documentation/livepatch/livepatch.txt @@ -12,12 +12,12 @@ Table of Contents: 4. Livepatch module 4.1. New functions 4.2. Metadata - 4.3. Livepatch module handling 5. Livepatch life-cycle - 5.1. Registration + 5.1. Loading 5.2. Enabling - 5.3. Disabling - 5.4. Unregistration + 5.3. Replacing + 5.4. Disabling + 5.5. Removing 6. Sysfs 7. Limitations @@ -143,9 +143,9 @@ without HAVE_RELIABLE_STACKTRACE are not considered fully supported by the kernel livepatching. The /sys/kernel/livepatch/<patch>/transition file shows whether a patch -is in transition. Only a single patch (the topmost patch on the stack) -can be in transition at a given time. A patch can remain in transition -indefinitely, if any of the tasks are stuck in the initial patch state. +is in transition. Only a single patch can be in transition at a given +time. A patch can remain in transition indefinitely, if any of the tasks +are stuck in the initial patch state. A transition can be reversed and effectively canceled by writing the opposite value to the /sys/kernel/livepatch/<patch>/enabled file while @@ -158,12 +158,11 @@ If a patch is in transition, this file shows 0 to indicate the task is unpatched and 1 to indicate it's patched. Otherwise, if no patch is in transition, it shows -1. Any tasks which are blocking the transition can be signaled with SIGSTOP and SIGCONT to force them to change their -patched state. This may be harmful to the system though. -/sys/kernel/livepatch/<patch>/signal attribute provides a better alternative. -Writing 1 to the attribute sends a fake signal to all remaining blocking -tasks. No proper signal is actually delivered (there is no data in signal -pending structures). Tasks are interrupted or woken up, and forced to change -their patched state. +patched state. This may be harmful to the system though. Sending a fake signal +to all remaining blocking tasks is a better alternative. No proper signal is +actually delivered (there is no data in signal pending structures). Tasks are +interrupted or woken up, and forced to change their patched state. The fake +signal is automatically sent every 15 seconds. Administrator can also affect a transition through /sys/kernel/livepatch/<patch>/force attribute. Writing 1 there clears @@ -298,117 +297,110 @@ into three levels: see the "Consistency model" section. -4.3. Livepatch module handling ------------------------------- - -The usual behavior is that the new functions will get used when -the livepatch module is loaded. For this, the module init() function -has to register the patch (struct klp_patch) and enable it. See the -section "Livepatch life-cycle" below for more details about these -two operations. - -Module removal is only safe when there are no users of the underlying -functions. This is the reason why the force feature permanently disables -the removal. The forced tasks entered the functions but we cannot say -that they returned back. Therefore it cannot be decided when the -livepatch module can be safely removed. When the system is successfully -transitioned to a new patch state (patched/unpatched) without being -forced it is guaranteed that no task sleeps or runs in the old code. - - 5. Livepatch life-cycle ======================= -Livepatching defines four basic operations that define the life cycle of each -live patch: registration, enabling, disabling and unregistration. There are -several reasons why it is done this way. +Livepatching can be described by five basic operations: +loading, enabling, replacing, disabling, removing. -First, the patch is applied only when all patched symbols for already -loaded objects are found. The error handling is much easier if this -check is done before particular functions get redirected. +Where the replacing and the disabling operations are mutually +exclusive. They have the same result for the given patch but +not for the system. -Second, it might take some time until the entire system is migrated with -the hybrid consistency model being used. The patch revert might block -the livepatch module removal for too long. Therefore it is useful to -revert the patch using a separate operation that might be called -explicitly. But it does not make sense to remove all information until -the livepatch module is really removed. +5.1. Loading +------------ -5.1. Registration ------------------ +The only reasonable way is to enable the patch when the livepatch kernel +module is being loaded. For this, klp_enable_patch() has to be called +in the module_init() callback. There are two main reasons: -Each patch first has to be registered using klp_register_patch(). This makes -the patch known to the livepatch framework. Also it does some preliminary -computing and checks. +First, only the module has an easy access to the related struct klp_patch. -In particular, the patch is added into the list of known patches. The -addresses of the patched functions are found according to their names. -The special relocations, mentioned in the section "New functions", are -applied. The relevant entries are created under -/sys/kernel/livepatch/<name>. The patch is rejected when any operation -fails. +Second, the error code might be used to refuse loading the module when +the patch cannot get enabled. 5.2. Enabling ------------- -Registered patches might be enabled either by calling klp_enable_patch() or -by writing '1' to /sys/kernel/livepatch/<name>/enabled. The system will -start using the new implementation of the patched functions at this stage. +The livepatch gets enabled by calling klp_enable_patch() from +the module_init() callback. The system will start using the new +implementation of the patched functions at this stage. -When a patch is enabled, livepatch enters into a transition state where -tasks are converging to the patched state. This is indicated by a value -of '1' in /sys/kernel/livepatch/<name>/transition. Once all tasks have -been patched, the 'transition' value changes to '0'. For more -information about this process, see the "Consistency model" section. +First, the addresses of the patched functions are found according to their +names. The special relocations, mentioned in the section "New functions", +are applied. The relevant entries are created under +/sys/kernel/livepatch/<name>. The patch is rejected when any above +operation fails. -If an original function is patched for the first time, a function -specific struct klp_ops is created and an universal ftrace handler is -registered. +Second, livepatch enters into a transition state where tasks are converging +to the patched state. If an original function is patched for the first +time, a function specific struct klp_ops is created and an universal +ftrace handler is registered[*]. This stage is indicated by a value of '1' +in /sys/kernel/livepatch/<name>/transition. For more information about +this process, see the "Consistency model" section. -Functions might be patched multiple times. The ftrace handler is registered -only once for the given function. Further patches just add an entry to the -list (see field `func_stack`) of the struct klp_ops. The last added -entry is chosen by the ftrace handler and becomes the active function -replacement. +Finally, once all tasks have been patched, the 'transition' value changes +to '0'. -Note that the patches might be enabled in a different order than they were -registered. +[*] Note that functions might be patched multiple times. The ftrace handler + is registered only once for a given function. Further patches just add + an entry to the list (see field `func_stack`) of the struct klp_ops. + The right implementation is selected by the ftrace handler, see + the "Consistency model" section. + That said, it is highly recommended to use cumulative livepatches + because they help keeping the consistency of all changes. In this case, + functions might be patched two times only during the transition period. -5.3. Disabling + +5.3. Replacing -------------- -Enabled patches might get disabled either by calling klp_disable_patch() or -by writing '0' to /sys/kernel/livepatch/<name>/enabled. At this stage -either the code from the previously enabled patch or even the original -code gets used. +All enabled patches might get replaced by a cumulative patch that +has the .replace flag set. + +Once the new patch is enabled and the 'transition' finishes then +all the functions (struct klp_func) associated with the replaced +patches are removed from the corresponding struct klp_ops. Also +the ftrace handler is unregistered and the struct klp_ops is +freed when the related function is not modified by the new patch +and func_stack list becomes empty. + +See Documentation/livepatch/cumulative-patches.txt for more details. -When a patch is disabled, livepatch enters into a transition state where -tasks are converging to the unpatched state. This is indicated by a -value of '1' in /sys/kernel/livepatch/<name>/transition. Once all tasks -have been unpatched, the 'transition' value changes to '0'. For more -information about this process, see the "Consistency model" section. -Here all the functions (struct klp_func) associated with the to-be-disabled +5.4. Disabling +-------------- + +Enabled patches might get disabled by writing '0' to +/sys/kernel/livepatch/<name>/enabled. + +First, livepatch enters into a transition state where tasks are converging +to the unpatched state. The system starts using either the code from +the previously enabled patch or even the original one. This stage is +indicated by a value of '1' in /sys/kernel/livepatch/<name>/transition. +For more information about this process, see the "Consistency model" +section. + +Second, once all tasks have been unpatched, the 'transition' value changes +to '0'. All the functions (struct klp_func) associated with the to-be-disabled patch are removed from the corresponding struct klp_ops. The ftrace handler is unregistered and the struct klp_ops is freed when the func_stack list becomes empty. -Patches must be disabled in exactly the reverse order in which they were -enabled. It makes the problem and the implementation much easier. - +Third, the sysfs interface is destroyed. -5.4. Unregistration -------------------- -Disabled patches might be unregistered by calling klp_unregister_patch(). -This can be done only when the patch is disabled and the code is no longer -used. It must be called before the livepatch module gets unloaded. +5.5. Removing +------------- -At this stage, all the relevant sys-fs entries are removed and the patch -is removed from the list of known patches. +Module removal is only safe when there are no users of functions provided +by the module. This is the reason why the force feature permanently +disables the removal. Only when the system is successfully transitioned +to a new patch state (patched/unpatched) without being forced it is +guaranteed that no task sleeps or runs in the old code. 6. Sysfs @@ -418,8 +410,8 @@ Information about the registered patches can be found under /sys/kernel/livepatch. The patches could be enabled and disabled by writing there. -/sys/kernel/livepatch/<patch>/signal and /sys/kernel/livepatch/<patch>/force -attributes allow administrator to affect a patching operation. +/sys/kernel/livepatch/<patch>/force attributes allow administrator to affect a +patching operation. See Documentation/ABI/testing/sysfs-kernel-livepatch for more details. diff --git a/Documentation/lzo.txt b/Documentation/lzo.txt index 6fa6a93d0949..f79934225d8d 100644 --- a/Documentation/lzo.txt +++ b/Documentation/lzo.txt @@ -78,16 +78,34 @@ Description is an implementation design choice independent on the algorithm or encoding. +Versions + +0: Original version +1: LZO-RLE + +Version 1 of LZO implements an extension to encode runs of zeros using run +length encoding. This improves speed for data with many zeros, which is a +common case for zram. This modifies the bitstream in a backwards compatible way +(v1 can correctly decompress v0 compressed data, but v0 cannot read v1 data). + +For maximum compatibility, both versions are available under different names +(lzo and lzo-rle). Differences in the encoding are noted in this document with +e.g.: version 1 only. + Byte sequences ============== First byte encoding:: - 0..17 : follow regular instruction encoding, see below. It is worth - noting that codes 16 and 17 will represent a block copy from - the dictionary which is empty, and that they will always be + 0..16 : follow regular instruction encoding, see below. It is worth + noting that code 16 will represent a block copy from the + dictionary which is empty, and that it will always be invalid at this place. + 17 : bitstream version. If the first byte is 17, the next byte + gives the bitstream version (version 1 only). If the first byte + is not 17, the bitstream version is 0. + 18..21 : copy 0..3 literals state = (byte - 17) = 0..3 [ copy <state> literals ] skip byte @@ -140,6 +158,11 @@ Byte sequences state = S (copy S literals after this block) End of stream is reached if distance == 16384 + In version 1 only, this instruction is also used to encode a run of + zeros if distance = 0xbfff, i.e. H = 1 and the D bits are all 1. + In this case, it is followed by a fourth byte, X. + run length = ((X << 3) | (0 0 0 0 0 L L L)) + 4. + 0 0 1 L L L L L (32..63) Copy of small block within 16kB distance (preferably less than 34B) length = 2 + (L ?: 31 + (zero_bytes * 255) + non_zero_byte) @@ -165,7 +188,9 @@ Authors ======= This document was written by Willy Tarreau <w@1wt.eu> on 2014/07/19 during an - analysis of the decompression code available in Linux 3.16-rc5. The code is - tricky, it is possible that this document contains mistakes or that a few - corner cases were overlooked. In any case, please report any doubt, fix, or - proposed updates to the author(s) so that the document can be updated. + analysis of the decompression code available in Linux 3.16-rc5, and updated + by Dave Rodgman <dave.rodgman@arm.com> on 2018/10/30 to introduce run-length + encoding. The code is tricky, it is possible that this document contains + mistakes or that a few corner cases were overlooked. In any case, please + report any doubt, fix, or proposed updates to the author(s) so that the + document can be updated. diff --git a/Documentation/media/.gitignore b/Documentation/media/.gitignore index 08b21de3ef94..53adc029061f 100644 --- a/Documentation/media/.gitignore +++ b/Documentation/media/.gitignore @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + *.pdf # Files generated from *.dot uapi/v4l/pipeline.svg diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile index 36166952d555..d75d70f191bc 100644 --- a/Documentation/media/Makefile +++ b/Documentation/media/Makefile @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Rules to convert a .h file to inline RST documentation SRC_DIR=$(srctree)/Documentation/media diff --git a/Documentation/media/audio.h.rst.exceptions b/Documentation/media/audio.h.rst.exceptions index 940458774cf6..cf6620477f73 100644 --- a/Documentation/media/audio.h.rst.exceptions +++ b/Documentation/media/audio.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _DVBAUDIO_H_ diff --git a/Documentation/media/ca.h.rst.exceptions b/Documentation/media/ca.h.rst.exceptions index 553559cc6ad7..f6828238eb48 100644 --- a/Documentation/media/ca.h.rst.exceptions +++ b/Documentation/media/ca.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _DVBCA_H_ diff --git a/Documentation/media/cec-drivers/index.rst b/Documentation/media/cec-drivers/index.rst index 7ef204823422..2b7fcaa4311b 100644 --- a/Documentation/media/cec-drivers/index.rst +++ b/Documentation/media/cec-drivers/index.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> diff --git a/Documentation/media/cec-drivers/pulse8-cec.rst b/Documentation/media/cec-drivers/pulse8-cec.rst index 99551c6a9bc5..356d08b519f3 100644 --- a/Documentation/media/cec-drivers/pulse8-cec.rst +++ b/Documentation/media/cec-drivers/pulse8-cec.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Pulse-Eight CEC Adapter driver ============================== diff --git a/Documentation/media/cec.h.rst.exceptions b/Documentation/media/cec.h.rst.exceptions index d9fd092de6f8..014816d04b9e 100644 --- a/Documentation/media/cec.h.rst.exceptions +++ b/Documentation/media/cec.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _CEC_UAPI_H diff --git a/Documentation/media/conf.py b/Documentation/media/conf.py index bef927bc4659..1f194fcd2cae 100644 --- a/Documentation/media/conf.py +++ b/Documentation/media/conf.py @@ -1,5 +1,7 @@ # -*- coding: utf-8; mode: python -*- +# SPDX-License-Identifier: GPL-2.0 + project = 'Linux Media Subsystem Documentation' tags.add("subproject") diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py index 480d548af670..d0c50d75f518 100644 --- a/Documentation/media/conf_nitpick.py +++ b/Documentation/media/conf_nitpick.py @@ -1,5 +1,7 @@ # -*- coding: utf-8; mode: python -*- +# SPDX-License-Identifier: GPL-2.0 + project = 'Linux Media Subsystem Documentation' # It is possible to run Sphinx in nickpick mode with: diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions index a8c4239ed95b..afc14d384b83 100644 --- a/Documentation/media/dmx.h.rst.exceptions +++ b/Documentation/media/dmx.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _UAPI_DVBDMX_H_ diff --git a/Documentation/media/dvb-drivers/avermedia.rst b/Documentation/media/dvb-drivers/avermedia.rst index 49cd9c935307..14f437ca38d3 100644 --- a/Documentation/media/dvb-drivers/avermedia.rst +++ b/Documentation/media/dvb-drivers/avermedia.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + HOWTO: Get An Avermedia DVB-T working under Linux ------------------------------------------------- diff --git a/Documentation/media/dvb-drivers/bt8xx.rst b/Documentation/media/dvb-drivers/bt8xx.rst index e3e387bdf498..7936cd96fc8f 100644 --- a/Documentation/media/dvb-drivers/bt8xx.rst +++ b/Documentation/media/dvb-drivers/bt8xx.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + How to get the bt8xx cards working ================================== diff --git a/Documentation/media/dvb-drivers/cards.rst b/Documentation/media/dvb-drivers/cards.rst index 177cbeb2b561..e2e30a56b450 100644 --- a/Documentation/media/dvb-drivers/cards.rst +++ b/Documentation/media/dvb-drivers/cards.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Hardware supported by the linuxtv.org DVB drivers ================================================= diff --git a/Documentation/media/dvb-drivers/ci.rst b/Documentation/media/dvb-drivers/ci.rst index 87f3748c49b9..35f33f1f9e2a 100644 --- a/Documentation/media/dvb-drivers/ci.rst +++ b/Documentation/media/dvb-drivers/ci.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Conditional Access Interface (CI API) ================================================ diff --git a/Documentation/media/dvb-drivers/contributors.rst b/Documentation/media/dvb-drivers/contributors.rst index 5949753008ae..f23b6e6faf46 100644 --- a/Documentation/media/dvb-drivers/contributors.rst +++ b/Documentation/media/dvb-drivers/contributors.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Contributors ============ diff --git a/Documentation/media/dvb-drivers/dvb-usb.rst b/Documentation/media/dvb-drivers/dvb-usb.rst index eec99cd07a30..6679191819aa 100644 --- a/Documentation/media/dvb-drivers/dvb-usb.rst +++ b/Documentation/media/dvb-drivers/dvb-usb.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Idea behind the dvb-usb-framework ================================= diff --git a/Documentation/media/dvb-drivers/faq.rst b/Documentation/media/dvb-drivers/faq.rst index a8593d3792fa..52f153d18278 100644 --- a/Documentation/media/dvb-drivers/faq.rst +++ b/Documentation/media/dvb-drivers/faq.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + FAQ === diff --git a/Documentation/media/dvb-drivers/frontends.rst b/Documentation/media/dvb-drivers/frontends.rst index 1f5f57989196..7b8336ece681 100644 --- a/Documentation/media/dvb-drivers/frontends.rst +++ b/Documentation/media/dvb-drivers/frontends.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + **************** Frontend drivers **************** diff --git a/Documentation/media/dvb-drivers/index.rst b/Documentation/media/dvb-drivers/index.rst index 314e127d82e3..9d3fce544f85 100644 --- a/Documentation/media/dvb-drivers/index.rst +++ b/Documentation/media/dvb-drivers/index.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> diff --git a/Documentation/media/dvb-drivers/intro.rst b/Documentation/media/dvb-drivers/intro.rst index d6eeb2708b9b..4e361bcc3ad4 100644 --- a/Documentation/media/dvb-drivers/intro.rst +++ b/Documentation/media/dvb-drivers/intro.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Introduction ============ diff --git a/Documentation/media/dvb-drivers/lmedm04.rst b/Documentation/media/dvb-drivers/lmedm04.rst index e8913d4481a0..a6ee33413748 100644 --- a/Documentation/media/dvb-drivers/lmedm04.rst +++ b/Documentation/media/dvb-drivers/lmedm04.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Firmware files for lmedm04 cards ================================ diff --git a/Documentation/media/dvb-drivers/opera-firmware.rst b/Documentation/media/dvb-drivers/opera-firmware.rst index 41236b43c124..fab3581551de 100644 --- a/Documentation/media/dvb-drivers/opera-firmware.rst +++ b/Documentation/media/dvb-drivers/opera-firmware.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Opera firmware ============== diff --git a/Documentation/media/dvb-drivers/technisat.rst b/Documentation/media/dvb-drivers/technisat.rst index f80f4ecc1560..9eaa12366bbf 100644 --- a/Documentation/media/dvb-drivers/technisat.rst +++ b/Documentation/media/dvb-drivers/technisat.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + How to set up the Technisat/B2C2 Flexcop devices ================================================ diff --git a/Documentation/media/dvb-drivers/ttusb-dec.rst b/Documentation/media/dvb-drivers/ttusb-dec.rst index 84fc2199dc29..516bbab8a872 100644 --- a/Documentation/media/dvb-drivers/ttusb-dec.rst +++ b/Documentation/media/dvb-drivers/ttusb-dec.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + TechnoTrend/Hauppauge DEC USB Driver ==================================== diff --git a/Documentation/media/dvb-drivers/udev.rst b/Documentation/media/dvb-drivers/udev.rst index 7d7d5d82108a..ca6c9c226902 100644 --- a/Documentation/media/dvb-drivers/udev.rst +++ b/Documentation/media/dvb-drivers/udev.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + UDEV rules for DVB ================== diff --git a/Documentation/media/frontend.h.rst.exceptions b/Documentation/media/frontend.h.rst.exceptions index f7c4df620a52..6283702c08c8 100644 --- a/Documentation/media/frontend.h.rst.exceptions +++ b/Documentation/media/frontend.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _DVBFRONTEND_H_ diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index 1cf5316c8ff8..0a222fc1d7ca 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Linux Media Subsystem Documentation =================================== diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst index 9ce2e23a0236..4a6bd665b884 100644 --- a/Documentation/media/intro.rst +++ b/Documentation/media/intro.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 ============ Introduction diff --git a/Documentation/media/kapi/cec-core.rst b/Documentation/media/kapi/cec-core.rst index 1d989c544370..3ce26b7c2b2b 100644 --- a/Documentation/media/kapi/cec-core.rst +++ b/Documentation/media/kapi/cec-core.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + CEC Kernel Support ================== @@ -268,6 +270,10 @@ to 1, if the hardware does support retry then either set these counters to 0 if the hardware provides no feedback of which errors occurred and how many times, or fill in the correct values as reported by the hardware. +Be aware that calling these functions can immediately start a new transmit +if there is one pending in the queue. So make sure that the hardware is in +a state where new transmits can be started *before* calling these functions. + The cec_transmit_attempt_done() function is a helper for cases where the hardware never retries, so the transmit is always for just a single attempt. It will call cec_transmit_done() in turn, filling in 1 for the diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst index 0560100efca2..a7e75e2eba85 100644 --- a/Documentation/media/kapi/csi2.rst +++ b/Documentation/media/kapi/csi2.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + MIPI CSI-2 ========== diff --git a/Documentation/media/kapi/dtv-ca.rst b/Documentation/media/kapi/dtv-ca.rst index fded096b937c..8a09862b428b 100644 --- a/Documentation/media/kapi/dtv-ca.rst +++ b/Documentation/media/kapi/dtv-ca.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Conditional Access kABI ---------------------------------- diff --git a/Documentation/media/kapi/dtv-common.rst b/Documentation/media/kapi/dtv-common.rst index 7a9574f03190..f8b2c4dc8170 100644 --- a/Documentation/media/kapi/dtv-common.rst +++ b/Documentation/media/kapi/dtv-common.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Common functions --------------------------- diff --git a/Documentation/media/kapi/dtv-core.rst b/Documentation/media/kapi/dtv-core.rst index bca743dc6b43..17454a2cf6b0 100644 --- a/Documentation/media/kapi/dtv-core.rst +++ b/Documentation/media/kapi/dtv-core.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV (DVB) devices ------------------------ diff --git a/Documentation/media/kapi/dtv-demux.rst b/Documentation/media/kapi/dtv-demux.rst index 24857133e4e8..c0ae5dec5328 100644 --- a/Documentation/media/kapi/dtv-demux.rst +++ b/Documentation/media/kapi/dtv-demux.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Demux kABI --------------------- diff --git a/Documentation/media/kapi/dtv-frontend.rst b/Documentation/media/kapi/dtv-frontend.rst index 472650cdb100..8ea64742c7ba 100644 --- a/Documentation/media/kapi/dtv-frontend.rst +++ b/Documentation/media/kapi/dtv-frontend.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Frontend kABI ------------------------ diff --git a/Documentation/media/kapi/dtv-net.rst b/Documentation/media/kapi/dtv-net.rst index 158c7cbd7600..deb6bffe96bb 100644 --- a/Documentation/media/kapi/dtv-net.rst +++ b/Documentation/media/kapi/dtv-net.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Digital TV Network kABI ----------------------- diff --git a/Documentation/media/kapi/mc-core.rst b/Documentation/media/kapi/mc-core.rst index 0c05503eaf1f..0bcfeadbc52d 100644 --- a/Documentation/media/kapi/mc-core.rst +++ b/Documentation/media/kapi/mc-core.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Media Controller devices ------------------------ @@ -262,3 +264,5 @@ in the end provide a way to use driver-specific callbacks. .. kernel-doc:: include/media/media-devnode.h .. kernel-doc:: include/media/media-entity.h + +.. kernel-doc:: include/media/media-request.h diff --git a/Documentation/media/kapi/rc-core.rst b/Documentation/media/kapi/rc-core.rst index 4759f020d6b2..53f5e643b6e9 100644 --- a/Documentation/media/kapi/rc-core.rst +++ b/Documentation/media/kapi/rc-core.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Remote Controller devices ------------------------- diff --git a/Documentation/media/kapi/v4l2-async.rst b/Documentation/media/kapi/v4l2-async.rst index 523ff9eb09a0..3422330b3b1f 100644 --- a/Documentation/media/kapi/v4l2-async.rst +++ b/Documentation/media/kapi/v4l2-async.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 async kAPI ^^^^^^^^^^^^^^^ .. kernel-doc:: include/media/v4l2-async.h diff --git a/Documentation/media/kapi/v4l2-clocks.rst b/Documentation/media/kapi/v4l2-clocks.rst index b8a895860a8a..5c22eecab7ba 100644 --- a/Documentation/media/kapi/v4l2-clocks.rst +++ b/Documentation/media/kapi/v4l2-clocks.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 clocks ----------- diff --git a/Documentation/media/kapi/v4l2-common.rst b/Documentation/media/kapi/v4l2-common.rst index 525d804871ff..b1e70eb56aa4 100644 --- a/Documentation/media/kapi/v4l2-common.rst +++ b/Documentation/media/kapi/v4l2-common.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 common functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-controls.rst b/Documentation/media/kapi/v4l2-controls.rst index 07a179eeb2fb..64ab99abf0b6 100644 --- a/Documentation/media/kapi/v4l2-controls.rst +++ b/Documentation/media/kapi/v4l2-controls.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 Controls ============= diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index 5cf292037a48..0dcad7a23141 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Video4Linux devices ------------------- diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst index eb03ccc41c41..b359f1804bbe 100644 --- a/Documentation/media/kapi/v4l2-dev.rst +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Video device' s internal representation ======================================= diff --git a/Documentation/media/kapi/v4l2-device.rst b/Documentation/media/kapi/v4l2-device.rst index 6c58bbbaa66f..c4311f0421be 100644 --- a/Documentation/media/kapi/v4l2-device.rst +++ b/Documentation/media/kapi/v4l2-device.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 device instance -------------------- diff --git a/Documentation/media/kapi/v4l2-dv-timings.rst b/Documentation/media/kapi/v4l2-dv-timings.rst index 55274329d229..b178f931518b 100644 --- a/Documentation/media/kapi/v4l2-dv-timings.rst +++ b/Documentation/media/kapi/v4l2-dv-timings.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 DV Timings functions ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-event.rst b/Documentation/media/kapi/v4l2-event.rst index 5c7e31224ddc..a4b7ae2b94d8 100644 --- a/Documentation/media/kapi/v4l2-event.rst +++ b/Documentation/media/kapi/v4l2-event.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: GPL-2.0 V4L2 events ----------- diff --git a/Documentation/media/kapi/v4l2-fh.rst b/Documentation/media/kapi/v4l2-fh.rst index 3ee64adf4635..4c62b19af744 100644 --- a/Documentation/media/kapi/v4l2-fh.rst +++ b/Documentation/media/kapi/v4l2-fh.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 File handlers ------------------ diff --git a/Documentation/media/kapi/v4l2-flash-led-class.rst b/Documentation/media/kapi/v4l2-flash-led-class.rst index 20798bdac387..2aa6bed9b8db 100644 --- a/Documentation/media/kapi/v4l2-flash-led-class.rst +++ b/Documentation/media/kapi/v4l2-flash-led-class.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 flash functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-fwnode.rst b/Documentation/media/kapi/v4l2-fwnode.rst index 6c8bccdfeb25..e313b6cddcd0 100644 --- a/Documentation/media/kapi/v4l2-fwnode.rst +++ b/Documentation/media/kapi/v4l2-fwnode.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 fwnode kAPI ^^^^^^^^^^^^^^^^ .. kernel-doc:: include/media/v4l2-fwnode.h diff --git a/Documentation/media/kapi/v4l2-intro.rst b/Documentation/media/kapi/v4l2-intro.rst index e614d8d4ca1c..cea3e263e48b 100644 --- a/Documentation/media/kapi/v4l2-intro.rst +++ b/Documentation/media/kapi/v4l2-intro.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Introduction ------------ diff --git a/Documentation/media/kapi/v4l2-mc.rst b/Documentation/media/kapi/v4l2-mc.rst index 8af347013490..0c352ac588b2 100644 --- a/Documentation/media/kapi/v4l2-mc.rst +++ b/Documentation/media/kapi/v4l2-mc.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 Media Controller functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-mediabus.rst b/Documentation/media/kapi/v4l2-mediabus.rst index e64131906d11..1f2254cba92d 100644 --- a/Documentation/media/kapi/v4l2-mediabus.rst +++ b/Documentation/media/kapi/v4l2-mediabus.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 Media Bus functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-mem2mem.rst b/Documentation/media/kapi/v4l2-mem2mem.rst index 5536b4a71e51..a43b31cc8261 100644 --- a/Documentation/media/kapi/v4l2-mem2mem.rst +++ b/Documentation/media/kapi/v4l2-mem2mem.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 Memory to Memory functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-rect.rst b/Documentation/media/kapi/v4l2-rect.rst index 8df5067ad57d..fc315cd84156 100644 --- a/Documentation/media/kapi/v4l2-rect.rst +++ b/Documentation/media/kapi/v4l2-rect.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 rect helper functions ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-subdev.rst b/Documentation/media/kapi/v4l2-subdev.rst index e1f0b726e438..be4970909f40 100644 --- a/Documentation/media/kapi/v4l2-subdev.rst +++ b/Documentation/media/kapi/v4l2-subdev.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + V4L2 sub-devices ---------------- @@ -247,20 +249,28 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices registered this way are stored in a global list of subdevices, ready to be picked up by bridge drivers. -Bridge drivers in turn have to register a notifier object with an array of -subdevice descriptors that the bridge device needs for its operation. This is +Bridge drivers in turn have to register a notifier object. This is performed using the :c:func:`v4l2_async_notifier_register` call. To unregister the notifier the driver has to call :c:func:`v4l2_async_notifier_unregister`. The former of the two functions -takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to -struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array -of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev` -type. The V4L2 core will then use these descriptors to match asynchronously -registered -subdevices to them. If a match is detected the ``.bound()`` notifier callback -is called. After all subdevices have been located the .complete() callback is -called. When a subdevice is removed from the system the .unbind() method is -called. All three callbacks are optional. +takes two arguments: a pointer to struct :c:type:`v4l2_device` and a +pointer to struct :c:type:`v4l2_async_notifier`. + +Before registering the notifier, bridge drivers must do two things: +first, the notifier must be initialized using the +:c:func:`v4l2_async_notifier_init`. Second, bridge drivers can then +begin to form a list of subdevice descriptors that the bridge device +needs for its operation. Subdevice descriptors are added to the notifier +using the :c:func:`v4l2_async_notifier_add_subdev` call. This function +takes two arguments: a pointer to struct :c:type:`v4l2_async_notifier`, +and a pointer to the subdevice descripter, which is of type struct +:c:type:`v4l2_async_subdev`. + +The V4L2 core will then use these descriptors to match asynchronously +registered subdevices to them. If a match is detected the ``.bound()`` +notifier callback is called. After all subdevices have been located the +.complete() callback is called. When a subdevice is removed from the +system the .unbind() method is called. All three callbacks are optional. V4L2 sub-device userspace API ----------------------------- diff --git a/Documentation/media/kapi/v4l2-tuner.rst b/Documentation/media/kapi/v4l2-tuner.rst index 86e894639651..e6caa3321566 100644 --- a/Documentation/media/kapi/v4l2-tuner.rst +++ b/Documentation/media/kapi/v4l2-tuner.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Tuner functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-tveeprom.rst b/Documentation/media/kapi/v4l2-tveeprom.rst index 33422cb26aa7..43fb391edaba 100644 --- a/Documentation/media/kapi/v4l2-tveeprom.rst +++ b/Documentation/media/kapi/v4l2-tveeprom.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Hauppauge TV EEPROM functions and data structures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/media/kapi/v4l2-videobuf.rst b/Documentation/media/kapi/v4l2-videobuf.rst index 54adfd772d28..1a7756397b1a 100644 --- a/Documentation/media/kapi/v4l2-videobuf.rst +++ b/Documentation/media/kapi/v4l2-videobuf.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _vb_framework: Videobuf Framework diff --git a/Documentation/media/kapi/v4l2-videobuf2.rst b/Documentation/media/kapi/v4l2-videobuf2.rst index 3c4cb1e7e05f..1044f64ff168 100644 --- a/Documentation/media/kapi/v4l2-videobuf2.rst +++ b/Documentation/media/kapi/v4l2-videobuf2.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _vb2_framework: V4L2 videobuf2 functions and data structures diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions index 984b61dc3f2e..379b9e7df5d0 100644 --- a/Documentation/media/lirc.h.rst.exceptions +++ b/Documentation/media/lirc.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _LINUX_LIRC_H diff --git a/Documentation/media/media.h.rst.exceptions b/Documentation/media/media.h.rst.exceptions index 684fe9c86dee..9b4c26502d95 100644 --- a/Documentation/media/media.h.rst.exceptions +++ b/Documentation/media/media.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define __LINUX_MEDIA_H diff --git a/Documentation/media/media_kapi.rst b/Documentation/media/media_kapi.rst index 83da736fad72..1389998c90f7 100644 --- a/Documentation/media/media_kapi.rst +++ b/Documentation/media/media_kapi.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst index 28eb35a1f965..0753005c7bb4 100644 --- a/Documentation/media/media_uapi.rst +++ b/Documentation/media/media_uapi.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> @@ -10,9 +10,9 @@ Linux Media Infrastructure userspace API Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation. A copy of -the license is included in the chapter entitled "GNU Free Documentation -License". +any later version published by the Free Software Foundation, with no +Invariant Sections. A copy of the license is included in the chapter +entitled "GNU Free Documentation License". .. only:: html diff --git a/Documentation/media/net.h.rst.exceptions b/Documentation/media/net.h.rst.exceptions index afe6bef91567..5159aa4bbbb9 100644 --- a/Documentation/media/net.h.rst.exceptions +++ b/Documentation/media/net.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _DVBNET_H_ diff --git a/Documentation/media/typical_media_device.svg b/Documentation/media/typical_media_device.svg index d6fad90ec199..bfd5c7db3b00 100644 --- a/Documentation/media/typical_media_device.svg +++ b/Documentation/media/typical_media_device.svg @@ -1,4 +1,14 @@ <?xml version="1.0" encoding="UTF-8"?> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg id="svg2" width="235mm" height="179mm" clip-path="url(#a)" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 22648.239 17899.829" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata1533"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><defs id="defs4"><clipPath id="a"><rect id="rect7" width="28000" height="21000"/></clipPath></defs><path id="path11" d="m10146 2636c-518.06 0-1035.1 515-1035.1 1031v4124c0 516 517.06 1032 1035.1 1032h8572.2c518.06 0 1036.1-516 1036.1-1032v-4124c0-516-518.06-1031-1036.1-1031h-8572.2z" fill="#fcf" style=""/><path id="path15" d="m1505.5 13443c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z" fill="#ffc" style=""/><path id="path19" d="m517.15 22.013c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z" fill="#e6e6e6" style=""/><path id="path23" d="m2371.5 6438h-2260v-1086h4520v1086h-2260z" fill="#ff8080" style=""/><path id="path25" d="m2371.5 6438h-2260v-1086h4520v1086h-2260z" fill="none" stroke="#3465af" style=""/><text id="text27" class="TextShape" x="-2089.4541" y="-2163.9871" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan29" class="TextParagraph" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan31" class="TextPosition" x="489.5459" y="6111.0132" font-family="Serif, serif" font-size="493.88px"><tspan id="tspan33" fill="#000000" font-family="Serif, serif" font-size="493.88px">Audio decoder</tspan></tspan></tspan></text> diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst index 1e2cf498ba30..b614bf81aa20 100644 --- a/Documentation/media/uapi/cec/cec-api.rst +++ b/Documentation/media/uapi/cec/cec-api.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. include:: <isonum.txt> diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst index 334358dfa72e..e10d675546f8 100644 --- a/Documentation/media/uapi/cec/cec-func-close.rst +++ b/Documentation/media/uapi/cec/cec-func-close.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _cec-func-close: diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst index e2b6260b0086..c18d4ba5eb37 100644 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ b/Documentation/media/uapi/cec/cec-func-ioctl.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _cec-func-ioctl: diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst index 5d6663a649bd..f235aa80155c 100644 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ b/Documentation/media/uapi/cec/cec-func-open.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _cec-func-open: diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst index d49f1ee0742d..3f6c5b0effa3 100644 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ b/Documentation/media/uapi/cec/cec-func-poll.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _cec-func-poll: @@ -74,4 +81,5 @@ is returned, and the ``errno`` variable is set appropriately: The call was interrupted by a signal. ``EINVAL`` - The ``nfds`` argument is greater than ``OPEN_MAX``. + The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use + ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/cec/cec-funcs.rst b/Documentation/media/uapi/cec/cec-funcs.rst index 6d696cead5cb..620590b168c9 100644 --- a/Documentation/media/uapi/cec/cec-funcs.rst +++ b/Documentation/media/uapi/cec/cec-funcs.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _cec-user-func: ****************** diff --git a/Documentation/media/uapi/cec/cec-header.rst b/Documentation/media/uapi/cec/cec-header.rst index d5a9a2828274..726f9766a130 100644 --- a/Documentation/media/uapi/cec/cec-header.rst +++ b/Documentation/media/uapi/cec/cec-header.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _cec_header: diff --git a/Documentation/media/uapi/cec/cec-intro.rst b/Documentation/media/uapi/cec/cec-intro.rst index 07ee2b8f89d6..05088fcefe81 100644 --- a/Documentation/media/uapi/cec/cec-intro.rst +++ b/Documentation/media/uapi/cec/cec-intro.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _cec-intro: Introduction diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst index 6c1f6efb822e..0c44f31a9b59 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_ADAP_G_CAPS: diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst index 84f431a022ad..26465094e3f1 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_ADAP_LOG_ADDRS: .. _CEC_ADAP_G_LOG_ADDRS: diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst index 9e49d4be35d5..693be2f9bf2e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +++ b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_ADAP_PHYS_ADDR: .. _CEC_ADAP_G_PHYS_ADDR: diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst index 8d5633e6ae04..46a1c99a595e 100644 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_DQEVENT: diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst index 508e2e325683..c53bb5f73f0d 100644 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_MODE: .. _CEC_G_MODE: diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst index e964074cd15b..c3a685ff05cb 100644 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ b/Documentation/media/uapi/cec/cec-ioc-receive.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CEC_TRANSMIT: .. _CEC_RECEIVE: @@ -16,10 +23,10 @@ CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message Synopsis ======== -.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg *argp ) +.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp ) :name: CEC_RECEIVE -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg *argp ) +.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) :name: CEC_TRANSMIT Arguments @@ -272,6 +279,19 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The transmit failed after one or more retries. This status bit is mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still be set to explain which failures were seen. + * .. _`CEC-TX-STATUS-ABORTED`: + + - ``CEC_TX_STATUS_ABORTED`` + - 0x40 + - The transmit was aborted due to an HDMI disconnect, or the adapter + was unconfigured, or a transmit was interrupted, or the driver + returned an error when attempting to start a transmit. + * .. _`CEC-TX-STATUS-TIMEOUT`: + + - ``CEC_TX_STATUS_TIMEOUT`` + - 0x80 + - The transmit timed out. This should not normally happen and this + indicates a driver problem. .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| @@ -300,6 +320,14 @@ View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - The message was received successfully but the reply was ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message was the reply to an earlier transmitted message. + * .. _`CEC-RX-STATUS-ABORTED`: + + - ``CEC_RX_STATUS_ABORTED`` + - 0x08 + - The wait for a reply to an earlier transmitted message was aborted + because the HDMI cable was disconnected, the adapter was unconfigured + or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a + reply was interrupted. diff --git a/Documentation/media/uapi/cec/cec-pin-error-inj.rst b/Documentation/media/uapi/cec/cec-pin-error-inj.rst index 464b006dbe0a..725f8b1c9965 100644 --- a/Documentation/media/uapi/cec/cec-pin-error-inj.rst +++ b/Documentation/media/uapi/cec/cec-pin-error-inj.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + CEC Pin Framework Error Injection ================================= diff --git a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst index 1279bd21dbd0..ee2ee74dafa3 100644 --- a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst +++ b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_BILINGUAL_CHANNEL_SELECT: diff --git a/Documentation/media/uapi/dvb/audio-channel-select.rst b/Documentation/media/uapi/dvb/audio-channel-select.rst index 8cab3d7abff5..ebb2f121c4c8 100644 --- a/Documentation/media/uapi/dvb/audio-channel-select.rst +++ b/Documentation/media/uapi/dvb/audio-channel-select.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_CHANNEL_SELECT: diff --git a/Documentation/media/uapi/dvb/audio-clear-buffer.rst b/Documentation/media/uapi/dvb/audio-clear-buffer.rst index f6bed67cb070..c5b62cde18c8 100644 --- a/Documentation/media/uapi/dvb/audio-clear-buffer.rst +++ b/Documentation/media/uapi/dvb/audio-clear-buffer.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_CLEAR_BUFFER: diff --git a/Documentation/media/uapi/dvb/audio-continue.rst b/Documentation/media/uapi/dvb/audio-continue.rst index ca587869306e..6bdc99e39e20 100644 --- a/Documentation/media/uapi/dvb/audio-continue.rst +++ b/Documentation/media/uapi/dvb/audio-continue.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_CONTINUE: diff --git a/Documentation/media/uapi/dvb/audio-fclose.rst b/Documentation/media/uapi/dvb/audio-fclose.rst index 58d351a3af4b..1e4ad7a0325d 100644 --- a/Documentation/media/uapi/dvb/audio-fclose.rst +++ b/Documentation/media/uapi/dvb/audio-fclose.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio_fclose: diff --git a/Documentation/media/uapi/dvb/audio-fopen.rst b/Documentation/media/uapi/dvb/audio-fopen.rst index 4a174640bf11..2cf4d83661f4 100644 --- a/Documentation/media/uapi/dvb/audio-fopen.rst +++ b/Documentation/media/uapi/dvb/audio-fopen.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio_fopen: diff --git a/Documentation/media/uapi/dvb/audio-fwrite.rst b/Documentation/media/uapi/dvb/audio-fwrite.rst index 4980ae7953ef..6dc6bf6cbbc7 100644 --- a/Documentation/media/uapi/dvb/audio-fwrite.rst +++ b/Documentation/media/uapi/dvb/audio-fwrite.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio_fwrite: diff --git a/Documentation/media/uapi/dvb/audio-get-capabilities.rst b/Documentation/media/uapi/dvb/audio-get-capabilities.rst index 0d867f189c22..4f1ec47e8ac2 100644 --- a/Documentation/media/uapi/dvb/audio-get-capabilities.rst +++ b/Documentation/media/uapi/dvb/audio-get-capabilities.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_GET_CAPABILITIES: diff --git a/Documentation/media/uapi/dvb/audio-get-status.rst b/Documentation/media/uapi/dvb/audio-get-status.rst index 857b058325f1..30e4dd7fce6d 100644 --- a/Documentation/media/uapi/dvb/audio-get-status.rst +++ b/Documentation/media/uapi/dvb/audio-get-status.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_GET_STATUS: diff --git a/Documentation/media/uapi/dvb/audio-pause.rst b/Documentation/media/uapi/dvb/audio-pause.rst index c7310dffbff2..4567ecd9e0a3 100644 --- a/Documentation/media/uapi/dvb/audio-pause.rst +++ b/Documentation/media/uapi/dvb/audio-pause.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_PAUSE: diff --git a/Documentation/media/uapi/dvb/audio-play.rst b/Documentation/media/uapi/dvb/audio-play.rst index 943b5eec9f28..17acd4c411b8 100644 --- a/Documentation/media/uapi/dvb/audio-play.rst +++ b/Documentation/media/uapi/dvb/audio-play.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_PLAY: diff --git a/Documentation/media/uapi/dvb/audio-select-source.rst b/Documentation/media/uapi/dvb/audio-select-source.rst index c0434a0bd324..c5ed6243b11c 100644 --- a/Documentation/media/uapi/dvb/audio-select-source.rst +++ b/Documentation/media/uapi/dvb/audio-select-source.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SELECT_SOURCE: diff --git a/Documentation/media/uapi/dvb/audio-set-av-sync.rst b/Documentation/media/uapi/dvb/audio-set-av-sync.rst index cf621f3a3037..c116d105fdea 100644 --- a/Documentation/media/uapi/dvb/audio-set-av-sync.rst +++ b/Documentation/media/uapi/dvb/audio-set-av-sync.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_AV_SYNC: diff --git a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst index f0db1fbdb066..d537da90acf5 100644 --- a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst +++ b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_BYPASS_MODE: diff --git a/Documentation/media/uapi/dvb/audio-set-id.rst b/Documentation/media/uapi/dvb/audio-set-id.rst index 8b1081d24473..aeb6ace6cd1e 100644 --- a/Documentation/media/uapi/dvb/audio-set-id.rst +++ b/Documentation/media/uapi/dvb/audio-set-id.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_ID: diff --git a/Documentation/media/uapi/dvb/audio-set-mixer.rst b/Documentation/media/uapi/dvb/audio-set-mixer.rst index 248aab8c8909..60781aa88202 100644 --- a/Documentation/media/uapi/dvb/audio-set-mixer.rst +++ b/Documentation/media/uapi/dvb/audio-set-mixer.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_MIXER: diff --git a/Documentation/media/uapi/dvb/audio-set-mute.rst b/Documentation/media/uapi/dvb/audio-set-mute.rst index 0af105a8ddcc..4449f225e48c 100644 --- a/Documentation/media/uapi/dvb/audio-set-mute.rst +++ b/Documentation/media/uapi/dvb/audio-set-mute.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_MUTE: diff --git a/Documentation/media/uapi/dvb/audio-set-streamtype.rst b/Documentation/media/uapi/dvb/audio-set-streamtype.rst index 46c0362ac71d..d20c34fc7128 100644 --- a/Documentation/media/uapi/dvb/audio-set-streamtype.rst +++ b/Documentation/media/uapi/dvb/audio-set-streamtype.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_SET_STREAMTYPE: diff --git a/Documentation/media/uapi/dvb/audio-stop.rst b/Documentation/media/uapi/dvb/audio-stop.rst index dd6c3b6826ec..1bba2e50c364 100644 --- a/Documentation/media/uapi/dvb/audio-stop.rst +++ b/Documentation/media/uapi/dvb/audio-stop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _AUDIO_STOP: diff --git a/Documentation/media/uapi/dvb/audio.rst b/Documentation/media/uapi/dvb/audio.rst index e9f9e589c486..ebc18fca76a4 100644 --- a/Documentation/media/uapi/dvb/audio.rst +++ b/Documentation/media/uapi/dvb/audio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_audio: diff --git a/Documentation/media/uapi/dvb/audio_data_types.rst b/Documentation/media/uapi/dvb/audio_data_types.rst index 5bffa2c98a24..5b032fe13b9d 100644 --- a/Documentation/media/uapi/dvb/audio_data_types.rst +++ b/Documentation/media/uapi/dvb/audio_data_types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio_data_types: diff --git a/Documentation/media/uapi/dvb/audio_function_calls.rst b/Documentation/media/uapi/dvb/audio_function_calls.rst index 7dba16285dab..5478e78b085e 100644 --- a/Documentation/media/uapi/dvb/audio_function_calls.rst +++ b/Documentation/media/uapi/dvb/audio_function_calls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio_function_calls: diff --git a/Documentation/media/uapi/dvb/ca-fclose.rst b/Documentation/media/uapi/dvb/ca-fclose.rst index e84bbfcfa184..e273444ccc67 100644 --- a/Documentation/media/uapi/dvb/ca-fclose.rst +++ b/Documentation/media/uapi/dvb/ca-fclose.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _ca_fclose: diff --git a/Documentation/media/uapi/dvb/ca-fopen.rst b/Documentation/media/uapi/dvb/ca-fopen.rst index 056c71b53a70..e11ebeae5693 100644 --- a/Documentation/media/uapi/dvb/ca-fopen.rst +++ b/Documentation/media/uapi/dvb/ca-fopen.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _ca_fopen: diff --git a/Documentation/media/uapi/dvb/ca-get-cap.rst b/Documentation/media/uapi/dvb/ca-get-cap.rst index d2d5c1355396..9e4fb5186373 100644 --- a/Documentation/media/uapi/dvb/ca-get-cap.rst +++ b/Documentation/media/uapi/dvb/ca-get-cap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_GET_CAP: diff --git a/Documentation/media/uapi/dvb/ca-get-descr-info.rst b/Documentation/media/uapi/dvb/ca-get-descr-info.rst index e564fbb8d524..80ef43a339df 100644 --- a/Documentation/media/uapi/dvb/ca-get-descr-info.rst +++ b/Documentation/media/uapi/dvb/ca-get-descr-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_GET_DESCR_INFO: diff --git a/Documentation/media/uapi/dvb/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst index ceeda623ce93..bcb7955a0ddc 100644 --- a/Documentation/media/uapi/dvb/ca-get-msg.rst +++ b/Documentation/media/uapi/dvb/ca-get-msg.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_GET_MSG: diff --git a/Documentation/media/uapi/dvb/ca-get-slot-info.rst b/Documentation/media/uapi/dvb/ca-get-slot-info.rst index 1a1d6f0c71b9..1ea5c497f2ea 100644 --- a/Documentation/media/uapi/dvb/ca-get-slot-info.rst +++ b/Documentation/media/uapi/dvb/ca-get-slot-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_GET_SLOT_INFO: diff --git a/Documentation/media/uapi/dvb/ca-reset.rst b/Documentation/media/uapi/dvb/ca-reset.rst index 29788325f90e..29fda19984be 100644 --- a/Documentation/media/uapi/dvb/ca-reset.rst +++ b/Documentation/media/uapi/dvb/ca-reset.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_RESET: diff --git a/Documentation/media/uapi/dvb/ca-send-msg.rst b/Documentation/media/uapi/dvb/ca-send-msg.rst index 9e91287b7bbc..5a3c4e8120c4 100644 --- a/Documentation/media/uapi/dvb/ca-send-msg.rst +++ b/Documentation/media/uapi/dvb/ca-send-msg.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_SEND_MSG: diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst index a6c47205ffd8..22c8b8f94c7e 100644 --- a/Documentation/media/uapi/dvb/ca-set-descr.rst +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _CA_SET_DESCR: diff --git a/Documentation/media/uapi/dvb/ca.rst b/Documentation/media/uapi/dvb/ca.rst index deac72d89e93..8796512c1378 100644 --- a/Documentation/media/uapi/dvb/ca.rst +++ b/Documentation/media/uapi/dvb/ca.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_ca: diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst index ac7cbd76ddd5..834c8ab4c300 100644 --- a/Documentation/media/uapi/dvb/ca_data_types.rst +++ b/Documentation/media/uapi/dvb/ca_data_types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _ca_data_types: diff --git a/Documentation/media/uapi/dvb/ca_function_calls.rst b/Documentation/media/uapi/dvb/ca_function_calls.rst index 87d697851e82..6985bebd0661 100644 --- a/Documentation/media/uapi/dvb/ca_function_calls.rst +++ b/Documentation/media/uapi/dvb/ca_function_calls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _ca_function_calls: diff --git a/Documentation/media/uapi/dvb/demux.rst b/Documentation/media/uapi/dvb/demux.rst index 45c3d6405c46..d8c0ff4015fe 100644 --- a/Documentation/media/uapi/dvb/demux.rst +++ b/Documentation/media/uapi/dvb/demux.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_demux: diff --git a/Documentation/media/uapi/dvb/dmx-add-pid.rst b/Documentation/media/uapi/dvb/dmx-add-pid.rst index 4d5632dfb43e..f483268e4ede 100644 --- a/Documentation/media/uapi/dvb/dmx-add-pid.rst +++ b/Documentation/media/uapi/dvb/dmx-add-pid.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_ADD_PID: diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst index 2d96cfe891df..d7f0658f3db3 100644 --- a/Documentation/media/uapi/dvb/dmx-expbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-expbuf.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _DMX_EXPBUF: **************** diff --git a/Documentation/media/uapi/dvb/dmx-fclose.rst b/Documentation/media/uapi/dvb/dmx-fclose.rst index 578e929f4bde..05ff32270274 100644 --- a/Documentation/media/uapi/dvb/dmx-fclose.rst +++ b/Documentation/media/uapi/dvb/dmx-fclose.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_fclose: diff --git a/Documentation/media/uapi/dvb/dmx-fopen.rst b/Documentation/media/uapi/dvb/dmx-fopen.rst index 55628a18ba67..2700a2fad68b 100644 --- a/Documentation/media/uapi/dvb/dmx-fopen.rst +++ b/Documentation/media/uapi/dvb/dmx-fopen.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_fopen: diff --git a/Documentation/media/uapi/dvb/dmx-fread.rst b/Documentation/media/uapi/dvb/dmx-fread.rst index 488bdc4ba178..292fa98f39ff 100644 --- a/Documentation/media/uapi/dvb/dmx-fread.rst +++ b/Documentation/media/uapi/dvb/dmx-fread.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_fread: diff --git a/Documentation/media/uapi/dvb/dmx-fwrite.rst b/Documentation/media/uapi/dvb/dmx-fwrite.rst index 519e5733e53b..bdd4d4743bd5 100644 --- a/Documentation/media/uapi/dvb/dmx-fwrite.rst +++ b/Documentation/media/uapi/dvb/dmx-fwrite.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_fwrite: diff --git a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst index fbdbc12869d1..fcd3dc06c095 100644 --- a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst +++ b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_GET_PES_PIDS: diff --git a/Documentation/media/uapi/dvb/dmx-get-stc.rst b/Documentation/media/uapi/dvb/dmx-get-stc.rst index 604031f7904b..2c81595f470a 100644 --- a/Documentation/media/uapi/dvb/dmx-get-stc.rst +++ b/Documentation/media/uapi/dvb/dmx-get-stc.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_GET_STC: diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst index 15d107348b9f..34bb7766718f 100644 --- a/Documentation/media/uapi/dvb/dmx-mmap.rst +++ b/Documentation/media/uapi/dvb/dmx-mmap.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _dmx-mmap: ***************** diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst b/Documentation/media/uapi/dvb/dmx-munmap.rst index d77218732bb6..ef26b6f2b12b 100644 --- a/Documentation/media/uapi/dvb/dmx-munmap.rst +++ b/Documentation/media/uapi/dvb/dmx-munmap.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _dmx-munmap: ************ diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst index be5a4c6f1904..9a1d85147c25 100644 --- a/Documentation/media/uapi/dvb/dmx-qbuf.rst +++ b/Documentation/media/uapi/dvb/dmx-qbuf.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _DMX_QBUF: ************************* diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst index 89481e24bb86..4cf36e821696 100644 --- a/Documentation/media/uapi/dvb/dmx-querybuf.rst +++ b/Documentation/media/uapi/dvb/dmx-querybuf.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _DMX_QUERYBUF: ****************** diff --git a/Documentation/media/uapi/dvb/dmx-remove-pid.rst b/Documentation/media/uapi/dvb/dmx-remove-pid.rst index 456cc2ded2c0..be992f44f306 100644 --- a/Documentation/media/uapi/dvb/dmx-remove-pid.rst +++ b/Documentation/media/uapi/dvb/dmx-remove-pid.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_REMOVE_PID: diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst index 14b80d60bf35..b302785bf678 100644 --- a/Documentation/media/uapi/dvb/dmx-reqbufs.rst +++ b/Documentation/media/uapi/dvb/dmx-reqbufs.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _DMX_REQBUFS: ***************** diff --git a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst index 74fd076a9b90..2dee0fb11f62 100644 --- a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst +++ b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_SET_BUFFER_SIZE: diff --git a/Documentation/media/uapi/dvb/dmx-set-filter.rst b/Documentation/media/uapi/dvb/dmx-set-filter.rst index 88594b8d3846..66afbb9f2fe4 100644 --- a/Documentation/media/uapi/dvb/dmx-set-filter.rst +++ b/Documentation/media/uapi/dvb/dmx-set-filter.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_SET_FILTER: diff --git a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst b/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst index d70e7bf96a41..dae5ab7878e5 100644 --- a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst +++ b/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_SET_PES_FILTER: diff --git a/Documentation/media/uapi/dvb/dmx-start.rst b/Documentation/media/uapi/dvb/dmx-start.rst index 36700e775296..488289d02504 100644 --- a/Documentation/media/uapi/dvb/dmx-start.rst +++ b/Documentation/media/uapi/dvb/dmx-start.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_START: diff --git a/Documentation/media/uapi/dvb/dmx-stop.rst b/Documentation/media/uapi/dvb/dmx-stop.rst index 6d9c927bcd5f..982384d12923 100644 --- a/Documentation/media/uapi/dvb/dmx-stop.rst +++ b/Documentation/media/uapi/dvb/dmx-stop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _DMX_STOP: diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst index 4c391cf2554f..67312ab65f94 100644 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_fcalls: diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst index 2a023a4f516c..b5cf704199e5 100644 --- a/Documentation/media/uapi/dvb/dmx_types.rst +++ b/Documentation/media/uapi/dvb/dmx_types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmx_types: diff --git a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst index 212f032cad8b..172783b75fb7 100644 --- a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst +++ b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb-fe-read-status: diff --git a/Documentation/media/uapi/dvb/dvb-frontend-event.rst b/Documentation/media/uapi/dvb/dvb-frontend-event.rst index 2088bc6cacd8..ad4af66040c7 100644 --- a/Documentation/media/uapi/dvb/dvb-frontend-event.rst +++ b/Documentation/media/uapi/dvb/dvb-frontend-event.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. c:type:: dvb_frontend_event diff --git a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst index b152166f8fa7..67c2a316019f 100644 --- a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst +++ b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. c:type:: dvb_frontend_parameters diff --git a/Documentation/media/uapi/dvb/dvbapi.rst b/Documentation/media/uapi/dvb/dvbapi.rst index 89ddca38626f..0fcc01f182f9 100644 --- a/Documentation/media/uapi/dvb/dvbapi.rst +++ b/Documentation/media/uapi/dvb/dvbapi.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. include:: <isonum.txt> diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst index 1a56c1724e59..371c72bb9419 100644 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ b/Documentation/media/uapi/dvb/dvbproperty.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend-properties: diff --git a/Documentation/media/uapi/dvb/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg index f6fe2f837373..c7672148d6ff 100644 --- a/Documentation/media/uapi/dvb/dvbstb.svg +++ b/Documentation/media/uapi/dvb/dvbstb.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg id="svg2" width="15.847cm" height="8.4187cm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 23770.123 12628.122" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><defs id="defs142"><marker id="Arrow1Lend" overflow="visible" orient="auto"><path id="path954" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker><marker id="marker1243" overflow="visible" orient="auto"><path id="path1241" transform="matrix(-.8 0 0 -.8 -10 0)" d="m0 0 5-5-17.5 5 17.5 5z" fill-rule="evenodd" stroke="#000" stroke-width="1pt"/></marker></defs><metadata id="metadata519"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><rect id="rect197" class="BoundingBox" x="5355.1" y="13.122" width="18403" height="9603" fill="none"/><path id="path199" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="#fff"/><path id="path201" d="m14556 9614.1h-9200v-9600h18400v9600z" fill="none" stroke="#000"/><rect id="rect206" class="BoundingBox" x="13.122" y="4013.1" width="4544" height="2403" fill="none"/><path id="path208" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="#fff"/><path id="path210" d="m2285.1 6414.1h-2271v-2400h4541v2400z" fill="none" stroke="#000"/><text id="text212" class="TextShape" x="-2443.8779" y="-4585.8779"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" x="1281.1219" y="5435.1221"><tspan id="tspan218" fill="#000000">Antena</tspan></tspan></tspan></text> diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst index 16dd90fa9e94..eaa41bc8d173 100644 --- a/Documentation/media/uapi/dvb/examples.rst +++ b/Documentation/media/uapi/dvb/examples.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_examples: diff --git a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst index 70256180e9b3..c3d7837b5f87 100644 --- a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst +++ b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ****************** Frontend bandwidth diff --git a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst index f220ee351e15..88fd2186ca4d 100644 --- a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst +++ b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_DISEQC_RECV_SLAVE_REPLY: diff --git a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst index 78476c1c7bf5..92929c2e75db 100644 --- a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst +++ b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_DISEQC_RESET_OVERLOAD: diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst index a7e05914efae..8af872d306aa 100644 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst +++ b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_DISEQC_SEND_BURST: diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst index 6bd3994edfc2..30a48114153c 100644 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst +++ b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_DISEQC_SEND_MASTER_CMD: diff --git a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst index dcf2d20d460f..13811289971b 100644 --- a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_DISHNETWORK_SEND_LEGACY_CMD: diff --git a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst index b20cb360fe37..32b7d140d80b 100644 --- a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst +++ b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_ENABLE_HIGH_LNB_VOLTAGE: diff --git a/Documentation/media/uapi/dvb/fe-get-event.rst b/Documentation/media/uapi/dvb/fe-get-event.rst index 505db94bf183..2573d5b9b636 100644 --- a/Documentation/media/uapi/dvb/fe-get-event.rst +++ b/Documentation/media/uapi/dvb/fe-get-event.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_GET_EVENT: diff --git a/Documentation/media/uapi/dvb/fe-get-frontend.rst b/Documentation/media/uapi/dvb/fe-get-frontend.rst index 5db552cedd70..6cd5250d1832 100644 --- a/Documentation/media/uapi/dvb/fe-get-frontend.rst +++ b/Documentation/media/uapi/dvb/fe-get-frontend.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_GET_FRONTEND: diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst index 49307c0abfee..551e68b11528 100644 --- a/Documentation/media/uapi/dvb/fe-get-info.rst +++ b/Documentation/media/uapi/dvb/fe-get-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_GET_INFO: diff --git a/Documentation/media/uapi/dvb/fe-get-property.rst b/Documentation/media/uapi/dvb/fe-get-property.rst index b69741d9cedf..99386c7461b3 100644 --- a/Documentation/media/uapi/dvb/fe-get-property.rst +++ b/Documentation/media/uapi/dvb/fe-get-property.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_GET_PROPERTY: diff --git a/Documentation/media/uapi/dvb/fe-read-ber.rst b/Documentation/media/uapi/dvb/fe-read-ber.rst index 1e6a79567a4c..e579d648687e 100644 --- a/Documentation/media/uapi/dvb/fe-read-ber.rst +++ b/Documentation/media/uapi/dvb/fe-read-ber.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_READ_BER: diff --git a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst index 198f6dfb53a1..0a0c0c2ff207 100644 --- a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst +++ b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_READ_SIGNAL_STRENGTH: diff --git a/Documentation/media/uapi/dvb/fe-read-snr.rst b/Documentation/media/uapi/dvb/fe-read-snr.rst index 6db22c043512..2a7a0d8f1fd5 100644 --- a/Documentation/media/uapi/dvb/fe-read-snr.rst +++ b/Documentation/media/uapi/dvb/fe-read-snr.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_READ_SNR: diff --git a/Documentation/media/uapi/dvb/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst index 4adb52f084ff..0dfc9fdf568f 100644 --- a/Documentation/media/uapi/dvb/fe-read-status.rst +++ b/Documentation/media/uapi/dvb/fe-read-status.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_READ_STATUS: diff --git a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst index f2c688bcacb3..19c532f750aa 100644 --- a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst +++ b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_READ_UNCORRECTED_BLOCKS: diff --git a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst index 3c4bc179b313..36e8913170e1 100644 --- a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst +++ b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_SET_FRONTEND_TUNE_MODE: diff --git a/Documentation/media/uapi/dvb/fe-set-frontend.rst b/Documentation/media/uapi/dvb/fe-set-frontend.rst index 4f3dcf338254..23caae2588d2 100644 --- a/Documentation/media/uapi/dvb/fe-set-frontend.rst +++ b/Documentation/media/uapi/dvb/fe-set-frontend.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_SET_FRONTEND: diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst index 758efa11014c..fb605e8c9fc4 100644 --- a/Documentation/media/uapi/dvb/fe-set-tone.rst +++ b/Documentation/media/uapi/dvb/fe-set-tone.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_SET_TONE: diff --git a/Documentation/media/uapi/dvb/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst index 38d4485290a0..c81a8e6a59aa 100644 --- a/Documentation/media/uapi/dvb/fe-set-voltage.rst +++ b/Documentation/media/uapi/dvb/fe-set-voltage.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _FE_SET_VOLTAGE: diff --git a/Documentation/media/uapi/dvb/fe-type-t.rst b/Documentation/media/uapi/dvb/fe-type-t.rst index dee32ae104d7..9720d2f7ba35 100644 --- a/Documentation/media/uapi/dvb/fe-type-t.rst +++ b/Documentation/media/uapi/dvb/fe-type-t.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ************* Frontend type diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst index 3524dcae4604..2fd2954d8dae 100644 --- a/Documentation/media/uapi/dvb/fe_property_parameters.rst +++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _fe_property_parameters: diff --git a/Documentation/media/uapi/dvb/frontend-header.rst b/Documentation/media/uapi/dvb/frontend-header.rst index 8d8433cf1e12..635fb4251214 100644 --- a/Documentation/media/uapi/dvb/frontend-header.rst +++ b/Documentation/media/uapi/dvb/frontend-header.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + Frontend uAPI data types ======================== diff --git a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst index bf2328627af5..97fbfc228c10 100644 --- a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst +++ b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend-property-cable-systems: diff --git a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst index 2929e6999a7a..2bc880a3c826 100644 --- a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst +++ b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend-property-satellite-systems: diff --git a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst b/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst index 0beb5cb3d729..c20af13297e5 100644 --- a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst +++ b/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend-property-terrestrial-systems: diff --git a/Documentation/media/uapi/dvb/frontend-stat-properties.rst b/Documentation/media/uapi/dvb/frontend-stat-properties.rst index e73754fd0631..546464db04b5 100644 --- a/Documentation/media/uapi/dvb/frontend-stat-properties.rst +++ b/Documentation/media/uapi/dvb/frontend-stat-properties.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend-stat-properties: diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst index 4967c48d46ce..7ff225dfe11c 100644 --- a/Documentation/media/uapi/dvb/frontend.rst +++ b/Documentation/media/uapi/dvb/frontend.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_frontend: diff --git a/Documentation/media/uapi/dvb/frontend_f_close.rst b/Documentation/media/uapi/dvb/frontend_f_close.rst index 67958d73cf34..af87c2a83719 100644 --- a/Documentation/media/uapi/dvb/frontend_f_close.rst +++ b/Documentation/media/uapi/dvb/frontend_f_close.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend_f_close: diff --git a/Documentation/media/uapi/dvb/frontend_f_open.rst b/Documentation/media/uapi/dvb/frontend_f_open.rst index 8e8cb466c24b..6a46ec5acf7b 100644 --- a/Documentation/media/uapi/dvb/frontend_f_open.rst +++ b/Documentation/media/uapi/dvb/frontend_f_open.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend_f_open: diff --git a/Documentation/media/uapi/dvb/frontend_fcalls.rst b/Documentation/media/uapi/dvb/frontend_fcalls.rst index b03f9cab6d5a..9b3586f538ea 100644 --- a/Documentation/media/uapi/dvb/frontend_fcalls.rst +++ b/Documentation/media/uapi/dvb/frontend_fcalls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend_fcalls: diff --git a/Documentation/media/uapi/dvb/frontend_legacy_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_api.rst index 759833d3eaa4..1ea749d09ca2 100644 --- a/Documentation/media/uapi/dvb/frontend_legacy_api.rst +++ b/Documentation/media/uapi/dvb/frontend_legacy_api.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend_legacy_types: diff --git a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst index a4d5319cb76b..1567bc73855a 100644 --- a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst +++ b/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _frontend_legacy_dvbv3_api: diff --git a/Documentation/media/uapi/dvb/headers.rst b/Documentation/media/uapi/dvb/headers.rst index c13fd537fbff..edeabd9e8e90 100644 --- a/Documentation/media/uapi/dvb/headers.rst +++ b/Documentation/media/uapi/dvb/headers.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + **************************** Digital TV uAPI header files **************************** diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst index 79b4d0e4e920..f1384616ac4e 100644 --- a/Documentation/media/uapi/dvb/intro.rst +++ b/Documentation/media/uapi/dvb/intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_introdution: diff --git a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst index e1b2c9c7b620..a43b4c36d935 100644 --- a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst +++ b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _legacy_dvb_apis: diff --git a/Documentation/media/uapi/dvb/net-add-if.rst b/Documentation/media/uapi/dvb/net-add-if.rst index 6749b70246c5..1188641b453e 100644 --- a/Documentation/media/uapi/dvb/net-add-if.rst +++ b/Documentation/media/uapi/dvb/net-add-if.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _NET_ADD_IF: diff --git a/Documentation/media/uapi/dvb/net-get-if.rst b/Documentation/media/uapi/dvb/net-get-if.rst index 3733b34da9db..7c4ef4b9d6cc 100644 --- a/Documentation/media/uapi/dvb/net-get-if.rst +++ b/Documentation/media/uapi/dvb/net-get-if.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _NET_GET_IF: diff --git a/Documentation/media/uapi/dvb/net-remove-if.rst b/Documentation/media/uapi/dvb/net-remove-if.rst index 4ebe07a6b79a..bf9a1602eeec 100644 --- a/Documentation/media/uapi/dvb/net-remove-if.rst +++ b/Documentation/media/uapi/dvb/net-remove-if.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _NET_REMOVE_IF: diff --git a/Documentation/media/uapi/dvb/net-types.rst b/Documentation/media/uapi/dvb/net-types.rst index 8fa3292eaa42..9e16462a1ef4 100644 --- a/Documentation/media/uapi/dvb/net-types.rst +++ b/Documentation/media/uapi/dvb/net-types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _net_types: diff --git a/Documentation/media/uapi/dvb/net.rst b/Documentation/media/uapi/dvb/net.rst index e0cd4e402627..833daa381968 100644 --- a/Documentation/media/uapi/dvb/net.rst +++ b/Documentation/media/uapi/dvb/net.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _net: diff --git a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst index 51ec0b04b496..9a6badc1d295 100644 --- a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst +++ b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _query-dvb-frontend-info: diff --git a/Documentation/media/uapi/dvb/video-clear-buffer.rst b/Documentation/media/uapi/dvb/video-clear-buffer.rst index 2e51a78a69f1..5eb5546e8ce4 100644 --- a/Documentation/media/uapi/dvb/video-clear-buffer.rst +++ b/Documentation/media/uapi/dvb/video-clear-buffer.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_CLEAR_BUFFER: diff --git a/Documentation/media/uapi/dvb/video-command.rst b/Documentation/media/uapi/dvb/video-command.rst index 536d0fdd8399..020b49645c6b 100644 --- a/Documentation/media/uapi/dvb/video-command.rst +++ b/Documentation/media/uapi/dvb/video-command.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_COMMAND: diff --git a/Documentation/media/uapi/dvb/video-continue.rst b/Documentation/media/uapi/dvb/video-continue.rst index e65e600be632..2ae2067dfba8 100644 --- a/Documentation/media/uapi/dvb/video-continue.rst +++ b/Documentation/media/uapi/dvb/video-continue.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_CONTINUE: diff --git a/Documentation/media/uapi/dvb/video-fast-forward.rst b/Documentation/media/uapi/dvb/video-fast-forward.rst index 70a53e110335..3f805f334ae1 100644 --- a/Documentation/media/uapi/dvb/video-fast-forward.rst +++ b/Documentation/media/uapi/dvb/video-fast-forward.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_FAST_FORWARD: diff --git a/Documentation/media/uapi/dvb/video-fclose.rst b/Documentation/media/uapi/dvb/video-fclose.rst index 8a997ae6f6a7..3b0285b96a3c 100644 --- a/Documentation/media/uapi/dvb/video-fclose.rst +++ b/Documentation/media/uapi/dvb/video-fclose.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video_fclose: diff --git a/Documentation/media/uapi/dvb/video-fopen.rst b/Documentation/media/uapi/dvb/video-fopen.rst index 203a2c56f10a..7b2a8c750e6a 100644 --- a/Documentation/media/uapi/dvb/video-fopen.rst +++ b/Documentation/media/uapi/dvb/video-fopen.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video_fopen: diff --git a/Documentation/media/uapi/dvb/video-freeze.rst b/Documentation/media/uapi/dvb/video-freeze.rst index 5a28bdc8badd..6b31a4755d2c 100644 --- a/Documentation/media/uapi/dvb/video-freeze.rst +++ b/Documentation/media/uapi/dvb/video-freeze.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_FREEZE: diff --git a/Documentation/media/uapi/dvb/video-fwrite.rst b/Documentation/media/uapi/dvb/video-fwrite.rst index cfe7c57dcfc7..eb35b79eb85c 100644 --- a/Documentation/media/uapi/dvb/video-fwrite.rst +++ b/Documentation/media/uapi/dvb/video-fwrite.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video_fwrite: diff --git a/Documentation/media/uapi/dvb/video-get-capabilities.rst b/Documentation/media/uapi/dvb/video-get-capabilities.rst index 6987f659a1ad..971fdab70e15 100644 --- a/Documentation/media/uapi/dvb/video-get-capabilities.rst +++ b/Documentation/media/uapi/dvb/video-get-capabilities.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_CAPABILITIES: diff --git a/Documentation/media/uapi/dvb/video-get-event.rst b/Documentation/media/uapi/dvb/video-get-event.rst index b4f53616db9a..def6c40db601 100644 --- a/Documentation/media/uapi/dvb/video-get-event.rst +++ b/Documentation/media/uapi/dvb/video-get-event.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_EVENT: diff --git a/Documentation/media/uapi/dvb/video-get-frame-count.rst b/Documentation/media/uapi/dvb/video-get-frame-count.rst index 0ffe22cd6108..ef35da7d4861 100644 --- a/Documentation/media/uapi/dvb/video-get-frame-count.rst +++ b/Documentation/media/uapi/dvb/video-get-frame-count.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_FRAME_COUNT: diff --git a/Documentation/media/uapi/dvb/video-get-pts.rst b/Documentation/media/uapi/dvb/video-get-pts.rst index c73f86f1d35b..86ceefff7834 100644 --- a/Documentation/media/uapi/dvb/video-get-pts.rst +++ b/Documentation/media/uapi/dvb/video-get-pts.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_PTS: diff --git a/Documentation/media/uapi/dvb/video-get-size.rst b/Documentation/media/uapi/dvb/video-get-size.rst index d077fe2305a0..cc92189d31fd 100644 --- a/Documentation/media/uapi/dvb/video-get-size.rst +++ b/Documentation/media/uapi/dvb/video-get-size.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_SIZE: diff --git a/Documentation/media/uapi/dvb/video-get-status.rst b/Documentation/media/uapi/dvb/video-get-status.rst index ed6ea19827a6..8bfcf8fc3e19 100644 --- a/Documentation/media/uapi/dvb/video-get-status.rst +++ b/Documentation/media/uapi/dvb/video-get-status.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_GET_STATUS: diff --git a/Documentation/media/uapi/dvb/video-play.rst b/Documentation/media/uapi/dvb/video-play.rst index 2124120aec22..fb3f4f168814 100644 --- a/Documentation/media/uapi/dvb/video-play.rst +++ b/Documentation/media/uapi/dvb/video-play.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_PLAY: diff --git a/Documentation/media/uapi/dvb/video-select-source.rst b/Documentation/media/uapi/dvb/video-select-source.rst index cde6542723ca..32cf025356dc 100644 --- a/Documentation/media/uapi/dvb/video-select-source.rst +++ b/Documentation/media/uapi/dvb/video-select-source.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SELECT_SOURCE: diff --git a/Documentation/media/uapi/dvb/video-set-blank.rst b/Documentation/media/uapi/dvb/video-set-blank.rst index 3858c69496a5..901c3c80f167 100644 --- a/Documentation/media/uapi/dvb/video-set-blank.rst +++ b/Documentation/media/uapi/dvb/video-set-blank.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SET_BLANK: diff --git a/Documentation/media/uapi/dvb/video-set-display-format.rst b/Documentation/media/uapi/dvb/video-set-display-format.rst index 2ef7401781be..ffdefa341207 100644 --- a/Documentation/media/uapi/dvb/video-set-display-format.rst +++ b/Documentation/media/uapi/dvb/video-set-display-format.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SET_DISPLAY_FORMAT: diff --git a/Documentation/media/uapi/dvb/video-set-format.rst b/Documentation/media/uapi/dvb/video-set-format.rst index 4239a4e365bb..63e60214ab37 100644 --- a/Documentation/media/uapi/dvb/video-set-format.rst +++ b/Documentation/media/uapi/dvb/video-set-format.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SET_FORMAT: diff --git a/Documentation/media/uapi/dvb/video-set-streamtype.rst b/Documentation/media/uapi/dvb/video-set-streamtype.rst index 02a3c2e4e67c..845486a6e049 100644 --- a/Documentation/media/uapi/dvb/video-set-streamtype.rst +++ b/Documentation/media/uapi/dvb/video-set-streamtype.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SET_STREAMTYPE: diff --git a/Documentation/media/uapi/dvb/video-slowmotion.rst b/Documentation/media/uapi/dvb/video-slowmotion.rst index bd3d1a4070d9..32c934aaf2ba 100644 --- a/Documentation/media/uapi/dvb/video-slowmotion.rst +++ b/Documentation/media/uapi/dvb/video-slowmotion.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_SLOWMOTION: diff --git a/Documentation/media/uapi/dvb/video-stillpicture.rst b/Documentation/media/uapi/dvb/video-stillpicture.rst index 6f943f5e27bd..58035a7630e6 100644 --- a/Documentation/media/uapi/dvb/video-stillpicture.rst +++ b/Documentation/media/uapi/dvb/video-stillpicture.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_STILLPICTURE: diff --git a/Documentation/media/uapi/dvb/video-stop.rst b/Documentation/media/uapi/dvb/video-stop.rst index 474309ad31c2..732ace05e34b 100644 --- a/Documentation/media/uapi/dvb/video-stop.rst +++ b/Documentation/media/uapi/dvb/video-stop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_STOP: diff --git a/Documentation/media/uapi/dvb/video-try-command.rst b/Documentation/media/uapi/dvb/video-try-command.rst index 008e6a9ab696..37ecf8e91eb8 100644 --- a/Documentation/media/uapi/dvb/video-try-command.rst +++ b/Documentation/media/uapi/dvb/video-try-command.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDEO_TRY_COMMAND: diff --git a/Documentation/media/uapi/dvb/video.rst b/Documentation/media/uapi/dvb/video.rst index e7d68cd0cf23..6d72ed0e2b2d 100644 --- a/Documentation/media/uapi/dvb/video.rst +++ b/Documentation/media/uapi/dvb/video.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dvb_video: diff --git a/Documentation/media/uapi/dvb/video_function_calls.rst b/Documentation/media/uapi/dvb/video_function_calls.rst index a4222b6cd2d3..9e8e49e52b19 100644 --- a/Documentation/media/uapi/dvb/video_function_calls.rst +++ b/Documentation/media/uapi/dvb/video_function_calls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video_function_calls: diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst index a0942171596c..2ed8aad84003 100644 --- a/Documentation/media/uapi/dvb/video_types.rst +++ b/Documentation/media/uapi/dvb/video_types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video_types: diff --git a/Documentation/media/uapi/fdl-appendix.rst b/Documentation/media/uapi/fdl-appendix.rst index fd475180fed8..f8dc85d3939c 100644 --- a/Documentation/media/uapi/fdl-appendix.rst +++ b/Documentation/media/uapi/fdl-appendix.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _fdl: diff --git a/Documentation/media/uapi/gen-errors.rst b/Documentation/media/uapi/gen-errors.rst index 689d3b101ede..043c312dc06d 100644 --- a/Documentation/media/uapi/gen-errors.rst +++ b/Documentation/media/uapi/gen-errors.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _gen_errors: diff --git a/Documentation/media/uapi/mediactl/media-controller-intro.rst b/Documentation/media/uapi/mediactl/media-controller-intro.rst index 3e776c0d8276..281c559c2f3c 100644 --- a/Documentation/media/uapi/mediactl/media-controller-intro.rst +++ b/Documentation/media/uapi/mediactl/media-controller-intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-controller-intro: diff --git a/Documentation/media/uapi/mediactl/media-controller-model.rst b/Documentation/media/uapi/mediactl/media-controller-model.rst index 558273cf9570..b6d5902b556d 100644 --- a/Documentation/media/uapi/mediactl/media-controller-model.rst +++ b/Documentation/media/uapi/mediactl/media-controller-model.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-controller-model: diff --git a/Documentation/media/uapi/mediactl/media-controller.rst b/Documentation/media/uapi/mediactl/media-controller.rst index 0eea4f9a07d5..6e624f690331 100644 --- a/Documentation/media/uapi/mediactl/media-controller.rst +++ b/Documentation/media/uapi/mediactl/media-controller.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. include:: <isonum.txt> @@ -21,6 +28,7 @@ Part IV - Media Controller API media-controller-intro media-controller-model media-types + request-api media-funcs media-header diff --git a/Documentation/media/uapi/mediactl/media-func-close.rst b/Documentation/media/uapi/mediactl/media-func-close.rst index a8f5203afe4b..369ccd4dee56 100644 --- a/Documentation/media/uapi/mediactl/media-func-close.rst +++ b/Documentation/media/uapi/mediactl/media-func-close.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-func-close: diff --git a/Documentation/media/uapi/mediactl/media-func-ioctl.rst b/Documentation/media/uapi/mediactl/media-func-ioctl.rst index fe072b7c8765..9a990d6480f5 100644 --- a/Documentation/media/uapi/mediactl/media-func-ioctl.rst +++ b/Documentation/media/uapi/mediactl/media-func-ioctl.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-func-ioctl: diff --git a/Documentation/media/uapi/mediactl/media-func-open.rst b/Documentation/media/uapi/mediactl/media-func-open.rst index 32f53016a9e5..cd2f840ddf73 100644 --- a/Documentation/media/uapi/mediactl/media-func-open.rst +++ b/Documentation/media/uapi/mediactl/media-func-open.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-func-open: diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst b/Documentation/media/uapi/mediactl/media-funcs.rst index 076856501cdb..87b65df8252a 100644 --- a/Documentation/media/uapi/mediactl/media-funcs.rst +++ b/Documentation/media/uapi/mediactl/media-funcs.rst @@ -1,3 +1,12 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _media-user-func: ****************** @@ -16,3 +25,9 @@ Function Reference media-ioc-enum-entities media-ioc-enum-links media-ioc-setup-link + media-ioc-request-alloc + request-func-close + request-func-ioctl + request-func-poll + media-request-ioc-queue + media-request-ioc-reinit diff --git a/Documentation/media/uapi/mediactl/media-header.rst b/Documentation/media/uapi/mediactl/media-header.rst index 96f7b0155e5a..1cb7c88aeff0 100644 --- a/Documentation/media/uapi/mediactl/media-header.rst +++ b/Documentation/media/uapi/mediactl/media-header.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_header: diff --git a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst index 649cb3d9e058..f8038cfb708c 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_ioc_device_info: @@ -26,6 +33,7 @@ Arguments File descriptor returned by :ref:`open() <media-func-open>`. ``argp`` + Pointer to struct :c:type:`media_device_info`. Description diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst index fc2e39c070c9..6218d9cbdd83 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_ioc_enum_entities: @@ -26,6 +33,7 @@ Arguments File descriptor returned by :ref:`open() <media-func-open>`. ``argp`` + Pointer to struct :c:type:`media_entity_desc`. Description diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst index f158c134e9b0..a982f16e55a4 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_ioc_enum_links: @@ -26,6 +33,7 @@ Arguments File descriptor returned by :ref:`open() <media-func-open>`. ``argp`` + Pointer to struct :c:type:`media_links_enum`. Description diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst index bac128c7eda9..0a7d76ac8ded 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_ioc_g_topology: @@ -26,6 +33,7 @@ Arguments File descriptor returned by :ref:`open() <media-func-open>`. ``argp`` + Pointer to struct :c:type:`media_v2_topology`. Description diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst new file mode 100644 index 000000000000..6d4ca4ada2e0 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst @@ -0,0 +1,90 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _media_ioc_request_alloc: + +***************************** +ioctl MEDIA_IOC_REQUEST_ALLOC +***************************** + +Name +==== + +MEDIA_IOC_REQUEST_ALLOC - Allocate a request + + +Synopsis +======== + +.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) + :name: MEDIA_IOC_REQUEST_ALLOC + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() <media-func-open>`. + +``argp`` + Pointer to an integer. + + +Description +=========== + +If the media device supports :ref:`requests <media-request-api>`, then +this ioctl can be used to allocate a request. If it is not supported, then +``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor +that is returned in ``*argp``. + +If the request was successfully allocated, then the request file descriptor +can be passed to the :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, +:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and +:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls. + +In addition, the request can be queued by calling +:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling +:ref:`MEDIA_REQUEST_IOC_REINIT`. + +Finally, the file descriptor can be :ref:`polled <request-func-poll>` to wait +for the request to complete. + +The request will remain allocated until all the file descriptors associated +with it are closed by :ref:`close() <request-func-close>` and the driver no +longer uses the request internally. See also +:ref:`here <media-request-life-time>` for more information. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +ENOTTY + The driver has no support for requests. diff --git a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst index ae5194940100..ae39dbbe48a0 100644 --- a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst +++ b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media_ioc_setup_link: @@ -26,6 +33,7 @@ Arguments File descriptor returned by :ref:`open() <media-func-open>`. ``argp`` + Pointer to struct :c:type:`media_link_desc`. Description diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst new file mode 100644 index 000000000000..fc8458746d51 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst @@ -0,0 +1,102 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _media_request_ioc_queue: + +***************************** +ioctl MEDIA_REQUEST_IOC_QUEUE +***************************** + +Name +==== + +MEDIA_REQUEST_IOC_QUEUE - Queue a request + + +Synopsis +======== + +.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) + :name: MEDIA_REQUEST_IOC_QUEUE + + +Arguments +========= + +``request_fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + + +Description +=========== + +If the media device supports :ref:`requests <media-request-api>`, then +this request ioctl can be used to queue a previously allocated request. + +If the request was successfully queued, then the file descriptor can be +:ref:`polled <request-func-poll>` to wait for the request to complete. + +If the request was already queued before, then ``EBUSY`` is returned. +Other errors can be returned if the contents of the request contained +invalid or inconsistent data, see the next section for a list of +common error codes. On error both the request and driver state are unchanged. + +Once a request is queued, then the driver is required to gracefully handle +errors that occur when the request is applied to the hardware. The +exception is the ``EIO`` error which signals a fatal error that requires +the application to stop streaming to reset the hardware state. + +It is not allowed to mix queuing requests with queuing buffers directly +(without a request). ``EBUSY`` will be returned if the first buffer was +queued directly and you next try to queue a request, or vice versa. + +A request must contain at least one buffer, otherwise this ioctl will +return an ``ENOENT`` error. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +EBUSY + The request was already queued or the application queued the first + buffer directly, but later attempted to use a request. It is not permitted + to mix the two APIs. +ENOENT + The request did not contain any buffers. All requests are required + to have at least one buffer. This can also be returned if some required + configuration is missing in the request. +ENOMEM + Out of memory when allocating internal data structures for this + request. +EINVAL + The request has invalid data. +EIO + The hardware is in a bad state. To recover, the application needs to + stop streaming to reset the hardware state and then try to restart + streaming. diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst b/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst new file mode 100644 index 000000000000..61381e87665a --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst @@ -0,0 +1,75 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _media_request_ioc_reinit: + +****************************** +ioctl MEDIA_REQUEST_IOC_REINIT +****************************** + +Name +==== + +MEDIA_REQUEST_IOC_REINIT - Re-initialize a request + + +Synopsis +======== + +.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) + :name: MEDIA_REQUEST_IOC_REINIT + + +Arguments +========= + +``request_fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +Description +=========== + +If the media device supports :ref:`requests <media-request-api>`, then +this request ioctl can be used to re-initialize a previously allocated +request. + +Re-initializing a request will clear any existing data from the request. +This avoids having to :ref:`close() <request-func-close>` a completed +request and allocate a new request. Instead the completed request can just +be re-initialized and it is ready to be used again. + +A request can only be re-initialized if it either has not been queued +yet, or if it was queued and completed. Otherwise it will set ``errno`` +to ``EBUSY``. No other error codes can be returned. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. + +EBUSY + The request is queued but not yet completed. diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst index e4c57c8f4553..8627587b7075 100644 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _media-controller-types: diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst new file mode 100644 index 000000000000..4b25ad03f45a --- /dev/null +++ b/Documentation/media/uapi/mediactl/request-api.rst @@ -0,0 +1,276 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _media-request-api: + +Request API +=========== + +The Request API has been designed to allow V4L2 to deal with requirements of +modern devices (stateless codecs, complex camera pipelines, ...) and APIs +(Android Codec v2). One such requirement is the ability for devices belonging to +the same pipeline to reconfigure and collaborate closely on a per-frame basis. +Another is support of stateless codecs, which require controls to be applied +to specific frames (aka 'per-frame controls') in order to be used efficiently. + +While the initial use-case was V4L2, it can be extended to other subsystems +as well, as long as they use the media controller. + +Supporting these features without the Request API is not always possible and if +it is, it is terribly inefficient: user-space would have to flush all activity +on the media pipeline, reconfigure it for the next frame, queue the buffers to +be processed with that configuration, and wait until they are all available for +dequeuing before considering the next frame. This defeats the purpose of having +buffer queues since in practice only one buffer would be queued at a time. + +The Request API allows a specific configuration of the pipeline (media +controller topology + configuration for each media entity) to be associated with +specific buffers. This allows user-space to schedule several tasks ("requests") +with different configurations in advance, knowing that the configuration will be +applied when needed to get the expected result. Configuration values at the time +of request completion are also available for reading. + +Usage +===== + +The Request API extends the Media Controller API and cooperates with +subsystem-specific APIs to support request usage. At the Media Controller +level, requests are allocated from the supporting Media Controller device +node. Their life cycle is then managed through the request file descriptors in +an opaque way. Configuration data, buffer handles and processing results +stored in requests are accessed through subsystem-specific APIs extended for +request support, such as V4L2 APIs that take an explicit ``request_fd`` +parameter. + +Request Allocation +------------------ + +User-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC` +for the media device node. This returns a file descriptor representing the +request. Typically, several such requests will be allocated. + +Request Preparation +------------------- + +Standard V4L2 ioctls can then receive a request file descriptor to express the +fact that the ioctl is part of said request, and is not to be applied +immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC` for a list of ioctls that +support this. Configurations set with a ``request_fd`` parameter are stored +instead of being immediately applied, and buffers queued to a request do not +enter the regular buffer queue until the request itself is queued. + +Request Submission +------------------ + +Once the configuration and buffers of the request are specified, it can be +queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor. +A request must contain at least one buffer, otherwise ``ENOENT`` is returned. +A queued request cannot be modified anymore. + +.. caution:: + For :ref:`memory-to-memory devices <codec>` you can use requests only for + output buffers, not for capture buffers. Attempting to add a capture buffer + to a request will result in an ``EACCES`` error. + +If the request contains configurations for multiple entities, individual drivers +may synchronize so the requested pipeline's topology is applied before the +buffers are processed. Media controller drivers do a best effort implementation +since perfect atomicity may not be possible due to hardware limitations. + +.. caution:: + + It is not allowed to mix queuing requests with directly queuing buffers: + whichever method is used first locks this in place until + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called or the device is + :ref:`closed <func-close>`. Attempts to directly queue a buffer when earlier + a buffer was queued via a request or vice versa will result in an ``EBUSY`` + error. + +Controls can still be set without a request and are applied immediately, +regardless of whether a request is in use or not. + +.. caution:: + + Setting the same control through a request and also directly can lead to + undefined behavior! + +User-space can :ref:`poll() <request-func-poll>` a request file descriptor in +order to wait until the request completes. A request is considered complete +once all its associated buffers are available for dequeuing and all the +associated controls have been updated with the values at the time of completion. +Note that user-space does not need to wait for the request to complete to +dequeue its buffers: buffers that are available halfway through a request can +be dequeued independently of the request's state. + +A completed request contains the state of the device after the request was +executed. User-space can query that state by calling +:ref:`ioctl VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with the request file +descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` for a +request that has been queued but not yet completed will return ``EBUSY`` +since the control values might be changed at any time by the driver while the +request is in flight. + +.. _media-request-life-time: + +Recycling and Destruction +------------------------- + +Finally, a completed request can either be discarded or be reused. Calling +:ref:`close() <request-func-close>` on a request file descriptor will make +that file descriptor unusable and the request will be freed once it is no +longer in use by the kernel. That is, if the request is queued and then the +file descriptor is closed, then it won't be freed until the driver completed +the request. + +The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it +available again. No state is retained by this operation: the request is as +if it had just been allocated. + +Example for a Codec Device +-------------------------- + +For use-cases such as :ref:`codecs <codec>`, the request API can be used +to associate specific controls to +be applied by the driver for the OUTPUT buffer, allowing user-space +to queue many such buffers in advance. It can also take advantage of requests' +ability to capture the state of controls when the request completes to read back +information that may be subject to change. + +Put into code, after obtaining a request, user-space can assign controls and one +OUTPUT buffer to it: + +.. code-block:: c + + struct v4l2_buffer buf; + struct v4l2_ext_controls ctrls; + int req_fd; + ... + if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) + return errno; + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) + return errno; + ... + buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; + buf.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) + return errno; + +Note that it is not allowed to use the Request API for CAPTURE buffers +since there are no per-frame settings to report there. + +Once the request is fully prepared, it can be queued to the driver: + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) + return errno; + +User-space can then either wait for the request to complete by calling poll() on +its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will +want to get CAPTURE buffers as soon as possible and this can be done using a +regular :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`: + +.. code-block:: c + + struct v4l2_buffer buf; + + memset(&buf, 0, sizeof(buf)); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) + return errno; + +Note that this example assumes for simplicity that for every OUTPUT buffer +there will be one CAPTURE buffer, but this does not have to be the case. + +We can then, after ensuring that the request is completed via polling the +request file descriptor, query control values at the time of its completion via +a call to :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. +This is particularly useful for volatile controls for which we want to +query values as soon as the capture buffer is produced. + +.. code-block:: c + + struct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; + poll(&pfd, 1, -1); + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) + return errno; + +Once we don't need the request anymore, we can either recycle it for reuse with +:ref:`MEDIA_REQUEST_IOC_REINIT`... + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) + return errno; + +... or close its file descriptor to completely dispose of it. + +.. code-block:: c + + close(req_fd); + +Example for a Simple Capture Device +----------------------------------- + +With a simple capture device, requests can be used to specify controls to apply +for a given CAPTURE buffer. + +.. code-block:: c + + struct v4l2_buffer buf; + struct v4l2_ext_controls ctrls; + int req_fd; + ... + if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) + return errno; + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) + return errno; + ... + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; + buf.request_fd = req_fd; + if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) + return errno; + +Once the request is fully prepared, it can be queued to the driver: + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) + return errno; + +User-space can then dequeue buffers, wait for the request completion, query +controls and recycle the request as in the M2M example above. diff --git a/Documentation/media/uapi/mediactl/request-func-close.rst b/Documentation/media/uapi/mediactl/request-func-close.rst new file mode 100644 index 000000000000..2cff7770558e --- /dev/null +++ b/Documentation/media/uapi/mediactl/request-func-close.rst @@ -0,0 +1,73 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _request-func-close: + +*************** +request close() +*************** + +Name +==== + +request-close - Close a request file descriptor + + +Synopsis +======== + +.. code-block:: c + + #include <unistd.h> + + +.. c:function:: int close( int fd ) + :name: req-close + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + + +Description +=========== + +Closes the request file descriptor. Resources associated with the request +are freed once all file descriptors associated with the request are closed +and the driver has completed the request. +See :ref:`here <media-request-life-time>` for more information. + + +Return Value +============ + +:ref:`close() <request-func-close>` returns 0 on success. On error, -1 is +returned, and ``errno`` is set appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/mediactl/request-func-ioctl.rst b/Documentation/media/uapi/mediactl/request-func-ioctl.rst new file mode 100644 index 000000000000..de0781c61873 --- /dev/null +++ b/Documentation/media/uapi/mediactl/request-func-ioctl.rst @@ -0,0 +1,91 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _request-func-ioctl: + +*************** +request ioctl() +*************** + +Name +==== + +request-ioctl - Control a request file descriptor + + +Synopsis +======== + +.. code-block:: c + + #include <sys/ioctl.h> + + +.. c:function:: int ioctl( int fd, int cmd, void *argp ) + :name: req-ioctl + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +``cmd`` + The request ioctl command code as defined in the media.h header file, for + example :ref:`MEDIA_REQUEST_IOC_QUEUE`. + +``argp`` + Pointer to a request-specific structure. + + +Description +=========== + +The :ref:`ioctl() <request-func-ioctl>` function manipulates request +parameters. The argument ``fd`` must be an open file descriptor. + +The ioctl ``cmd`` code specifies the request function to be called. It +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. + +Macros and structures definitions specifying request ioctl commands and +their parameters are located in the media.h header file. All request ioctl +commands, their respective function and parameters are specified in +:ref:`media-user-func`. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes <gen-errors>` chapter. + +Command-specific error codes are listed in the individual command +descriptions. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/media/uapi/mediactl/request-func-poll.rst b/Documentation/media/uapi/mediactl/request-func-poll.rst new file mode 100644 index 000000000000..ebaf33e21873 --- /dev/null +++ b/Documentation/media/uapi/mediactl/request-func-poll.rst @@ -0,0 +1,101 @@ +.. This file is dual-licensed: you can use it either under the terms +.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this +.. dual licensing only applies to this file, and not this project as a +.. whole. +.. +.. a) This file 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 version 2 of +.. the License. +.. +.. This file 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. +.. +.. Or, alternatively, +.. +.. b) Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections + +.. _request-func-poll: + +************** +request poll() +************** + +Name +==== + +request-poll - Wait for some event on a file descriptor + + +Synopsis +======== + +.. code-block:: c + + #include <sys/poll.h> + + +.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) + :name: request-poll + +Arguments +========= + +``ufds`` + List of file descriptor events to be watched + +``nfds`` + Number of file descriptor events at the \*ufds array + +``timeout`` + Timeout to wait for events + + +Description +=========== + +With the :c:func:`poll() <request-func-poll>` function applications can wait +for a request to complete. + +On success :c:func:`poll() <request-func-poll>` returns the number of file +descriptors that have been selected (that is, file descriptors for which the +``revents`` field of the respective struct :c:type:`pollfd` +is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` +when the request was completed. When the function times out it returns +a value of zero, on failure it returns -1 and the ``errno`` variable is +set appropriately. + +Attempting to poll for a request that is not yet queued will +set the ``POLLERR`` flag in ``revents``. + + +Return Value +============ + +On success, :c:func:`poll() <request-func-poll>` returns the number of +structures which have non-zero ``revents`` fields, or zero if the call +timed out. On error -1 is returned, and the ``errno`` variable is set +appropriately: + +``EBADF`` + One or more of the ``ufds`` members specify an invalid file + descriptor. + +``EFAULT`` + ``ufds`` references an inaccessible memory area. + +``EINTR`` + The call was interrupted by a signal. + +``EINVAL`` + The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use + ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/rc/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst index 217237f93b37..46f98569e999 100644 --- a/Documentation/media/uapi/rc/keytable.c.rst +++ b/Documentation/media/uapi/rc/keytable.c.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections file: uapi/v4l/keytable.c ========================= diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst index 11516c8bff62..1a901d8e1797 100644 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ b/Documentation/media/uapi/rc/lirc-dev-intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_dev_intro: diff --git a/Documentation/media/uapi/rc/lirc-dev.rst b/Documentation/media/uapi/rc/lirc-dev.rst index 03cde25f5859..7058e0b2296a 100644 --- a/Documentation/media/uapi/rc/lirc-dev.rst +++ b/Documentation/media/uapi/rc/lirc-dev.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_dev: diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst index ddb4620de294..25058369f724 100644 --- a/Documentation/media/uapi/rc/lirc-func.rst +++ b/Documentation/media/uapi/rc/lirc-func.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_func: diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst index 889a8807037b..1d590df8164a 100644 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ b/Documentation/media/uapi/rc/lirc-get-features.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_get_features: diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst index 2722118484fa..0a3e02aca80e 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_get_rec_mode: .. _lirc_set_rec_mode: diff --git a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst b/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst index 6e016edc2bc4..f560b694ccf2 100644 --- a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst +++ b/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_get_rec_resolution: diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst index c44e61a79ad1..4f440c697052 100644 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ b/Documentation/media/uapi/rc/lirc-get-send-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_get_send_mode: .. _lirc_set_send_mode: diff --git a/Documentation/media/uapi/rc/lirc-get-timeout.rst b/Documentation/media/uapi/rc/lirc-get-timeout.rst index c94bc5dcaa8e..1de214529f27 100644 --- a/Documentation/media/uapi/rc/lirc-get-timeout.rst +++ b/Documentation/media/uapi/rc/lirc-get-timeout.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_get_min_timeout: .. _lirc_get_max_timeout: diff --git a/Documentation/media/uapi/rc/lirc-header.rst b/Documentation/media/uapi/rc/lirc-header.rst index 487fe00e5517..c9b4f33e1031 100644 --- a/Documentation/media/uapi/rc/lirc-header.rst +++ b/Documentation/media/uapi/rc/lirc-header.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_header: diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst index c024aaffb8ad..a8fedfaaf0ab 100644 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ b/Documentation/media/uapi/rc/lirc-read.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc-read: diff --git a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst b/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst index 6307b5715595..c80acd85e369 100644 --- a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst +++ b/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_measure_carrier_mode: diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst index a89246806c4b..443681d5cc10 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_rec_carrier_range: diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst index a411c0330818..cbe1e48b2a4a 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_rec_carrier: diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst index 86353e602695..d06d69414c1e 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_rec_timeout_reports: diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst index a833a6a4c25a..163ac6065737 100644 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst +++ b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_rec_timeout: .. _lirc_get_rec_timeout: diff --git a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst b/Documentation/media/uapi/rc/lirc-set-send-carrier.rst index 42c8cfb42df5..cffc6c1e15cc 100644 --- a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst +++ b/Documentation/media/uapi/rc/lirc-set-send-carrier.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_send_carrier: diff --git a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst b/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst index 20d07c2a37a5..08ab3d1a96cd 100644 --- a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst +++ b/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_send_duty_cycle: diff --git a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst b/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst index 69b7ad8c2afb..889a739eaf0d 100644 --- a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst +++ b/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_transmitter_mask: diff --git a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst b/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst index 0415c6a54f23..592715452fce 100644 --- a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst +++ b/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc_set_wideband_receiver: diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst index d4566b0a2015..6adf5ddbac99 100644 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ b/Documentation/media/uapi/rc/lirc-write.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _lirc-write: diff --git a/Documentation/media/uapi/rc/rc-intro.rst b/Documentation/media/uapi/rc/rc-intro.rst index 3707c29d37ed..37c5f90c76e7 100644 --- a/Documentation/media/uapi/rc/rc-intro.rst +++ b/Documentation/media/uapi/rc/rc-intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _Remote_controllers_Intro: diff --git a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst b/Documentation/media/uapi/rc/rc-sysfs-nodes.rst index 2d01358d5504..b8e8319e3317 100644 --- a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst +++ b/Documentation/media/uapi/rc/rc-sysfs-nodes.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _remote_controllers_sysfs_nodes: diff --git a/Documentation/media/uapi/rc/rc-table-change.rst b/Documentation/media/uapi/rc/rc-table-change.rst index d604896bca87..4a2e601b89fb 100644 --- a/Documentation/media/uapi/rc/rc-table-change.rst +++ b/Documentation/media/uapi/rc/rc-table-change.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _Remote_controllers_table_change: diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst index c8ae9479f842..cb670d10998b 100644 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ b/Documentation/media/uapi/rc/rc-tables.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _Remote_controllers_tables: diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst index 46a8acb82125..3051f7abe11d 100644 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ b/Documentation/media/uapi/rc/remote_controllers.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. include:: <isonum.txt> diff --git a/Documentation/media/uapi/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst index a8c41a7ec396..c25c1271b4f6 100644 --- a/Documentation/media/uapi/v4l/app-pri.rst +++ b/Documentation/media/uapi/v4l/app-pri.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _app-pri: @@ -8,7 +15,7 @@ Application Priority When multiple applications share a device it may be desirable to assign them different priorities. Contrary to the traditional "rm -rf /" school -of thought a video recording application could for example block other +of thought, a video recording application could for example block other applications from changing video controls or switching the current TV channel. Another objective is to permit low priority applications working in background, which can be preempted by user controlled diff --git a/Documentation/media/uapi/v4l/async.rst b/Documentation/media/uapi/v4l/async.rst index 5affc0adb95b..be9539313f60 100644 --- a/Documentation/media/uapi/v4l/async.rst +++ b/Documentation/media/uapi/v4l/async.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _async: diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst index 5ec99a2809fe..4c7fdbc8a860 100644 --- a/Documentation/media/uapi/v4l/audio.rst +++ b/Documentation/media/uapi/v4l/audio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _audio: @@ -31,7 +38,7 @@ outputs applications can enumerate them with the :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively. The struct :c:type:`v4l2_audio` returned by the :ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal -:status information applicable when the current audio input is queried. +status information applicable when the current audio input is queried. The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current diff --git a/Documentation/media/uapi/v4l/bayer.svg b/Documentation/media/uapi/v4l/bayer.svg index c395113d1876..c5bf85103901 100644 --- a/Documentation/media/uapi/v4l/bayer.svg +++ b/Documentation/media/uapi/v4l/bayer.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg id="svg2" width="164.15mm" height="46.771mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 16415.333 4677.1107" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata652"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><g id="g186" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id6"><rect id="rect189" class="BoundingBox" x="3299" y="3199" width="1303" height="1203" fill="none"/><path id="path191" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="#00f"/><path id="path193" d="m3950 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text195" class="TextShape"><tspan id="tspan197" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan199" class="TextPosition" x="3739" y="4021"><tspan id="tspan201" fill="#ffffff">B</tspan></tspan></tspan></text> </g></g><g id="g203" class="com.sun.star.drawing.CustomShape" transform="translate(-3285.9 -3185.9)"><g id="id7"><rect id="rect206" class="BoundingBox" x="4599" y="3199" width="1303" height="1203" fill="none"/><path id="path208" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="#0c0"/><path id="path210" d="m5250 4400h-650v-1200h1300v1200h-650z" fill="none" stroke="#3465a4"/><text id="text212" class="TextShape"><tspan id="tspan214" class="TextParagraph" font-family="sans-serif" font-size="635px" font-weight="400"><tspan id="tspan216" class="TextPosition" x="5003" y="4021"><tspan id="tspan218" fill="#ffffff">G</tspan></tspan></tspan></text> diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst index 1cedcfc04327..ec33768c055e 100644 --- a/Documentation/media/uapi/v4l/biblio.rst +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ********** References @@ -226,16 +233,6 @@ xvYCC :author: International Electrotechnical Commission (http://www.iec.ch) -.. _adobergb: - -AdobeRGB -======== - - -:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05 - -:author: Adobe Systems Incorporated (http://www.adobe.com) - .. _oprgb: opRGB diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst index e2c85ddc990b..86878bb0087f 100644 --- a/Documentation/media/uapi/v4l/buffer.rst +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _buffer: @@ -306,10 +313,23 @@ struct v4l2_buffer - A place holder for future extensions. Drivers and applications must set this to 0. * - __u32 - - ``reserved`` + - ``request_fd`` - - - A place holder for future extensions. Drivers and applications - must set this to 0. + - The file descriptor of the request to queue the buffer to. If the flag + ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be + queued to this request. If the flag is not set, then this field will + be ignored. + + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by + :ref:`ioctl VIDIOC_QBUF <VIDIOC_QBUF>` and ignored by other ioctls that + take a :c:type:`v4l2_buffer` as argument. + + Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls + other than :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. + + If the device does not support requests, then ``EACCES`` will be returned. + If requests are supported but an invalid request file descriptor is + given, then ``EINVAL`` will be returned. @@ -452,6 +472,9 @@ enum v4l2_buf_type * - ``V4L2_BUF_TYPE_META_CAPTURE`` - 13 - Buffer for metadata capture, see :ref:`metadata`. + * - ``V4L2_BUF_TYPE_META_OUTPUT`` + - 14 + - Buffer for metadata output, see :ref:`metadata`. @@ -514,6 +537,11 @@ Buffer Flags streaming may continue as normal and the buffer may be reused normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is called. + * .. _`V4L2-BUF-FLAG-IN-REQUEST`: + + - ``V4L2_BUF_FLAG_IN_REQUEST`` + - 0x00000080 + - This buffer is part of a request that hasn't been queued yet. * .. _`V4L2-BUF-FLAG-KEYFRAME`: - ``V4L2_BUF_FLAG_KEYFRAME`` @@ -589,6 +617,11 @@ Buffer Flags the format. Any Any subsequent call to the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore, but return an ``EPIPE`` error code. + * .. _`V4L2-BUF-FLAG-REQUEST-FD`: + + - ``V4L2_BUF_FLAG_REQUEST_FD`` + - 0x00800000 + - The ``request_fd`` field contains a valid file descriptor. * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` diff --git a/Documentation/media/uapi/v4l/capture-example.rst b/Documentation/media/uapi/v4l/capture-example.rst index ac1cd057e25b..130ca47ef796 100644 --- a/Documentation/media/uapi/v4l/capture-example.rst +++ b/Documentation/media/uapi/v4l/capture-example.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _capture-example: diff --git a/Documentation/media/uapi/v4l/capture.c.rst b/Documentation/media/uapi/v4l/capture.c.rst index 56525a0fb2fa..b4652c2351f2 100644 --- a/Documentation/media/uapi/v4l/capture.c.rst +++ b/Documentation/media/uapi/v4l/capture.c.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections file: media/v4l/capture.c ========================= diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst index 410907fe9415..c4e8fc620379 100644 --- a/Documentation/media/uapi/v4l/colorspaces-defs.rst +++ b/Documentation/media/uapi/v4l/colorspaces-defs.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections **************************** Defining Colorspaces in V4L2 @@ -51,8 +58,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum - See :ref:`col-rec709`. * - ``V4L2_COLORSPACE_SRGB`` - See :ref:`col-srgb`. - * - ``V4L2_COLORSPACE_ADOBERGB`` - - See :ref:`col-adobergb`. + * - ``V4L2_COLORSPACE_OPRGB`` + - See :ref:`col-oprgb`. * - ``V4L2_COLORSPACE_BT2020`` - See :ref:`col-bt2020`. * - ``V4L2_COLORSPACE_DCI_P3`` @@ -90,8 +97,8 @@ whole range, 0-255, dividing the angular value by 1.41. The enum - Use the Rec. 709 transfer function. * - ``V4L2_XFER_FUNC_SRGB`` - Use the sRGB transfer function. - * - ``V4L2_XFER_FUNC_ADOBERGB`` - - Use the AdobeRGB transfer function. + * - ``V4L2_XFER_FUNC_OPRGB`` + - Use the opRGB transfer function. * - ``V4L2_XFER_FUNC_SMPTE240M`` - Use the SMPTE 240M transfer function. * - ``V4L2_XFER_FUNC_NONE`` diff --git a/Documentation/media/uapi/v4l/colorspaces-details.rst b/Documentation/media/uapi/v4l/colorspaces-details.rst index b5d551b9cc8f..8b0ba3668101 100644 --- a/Documentation/media/uapi/v4l/colorspaces-details.rst +++ b/Documentation/media/uapi/v4l/colorspaces-details.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ******************************** Detailed Colorspace Descriptions @@ -290,15 +297,14 @@ Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range 170M/BT.601. The Y'CbCr quantization is limited range. -.. _col-adobergb: +.. _col-oprgb: -Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB) +Colorspace opRGB (V4L2_COLORSPACE_OPRGB) =============================================== -The :ref:`adobergb` standard defines the colorspace used by computer -graphics that use the AdobeRGB colorspace. This is also known as the -:ref:`oprgb` standard. The default transfer function is -``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is +The :ref:`oprgb` standard defines the colorspace used by computer +graphics that use the opRGB colorspace. The default transfer function is +``V4L2_XFER_FUNC_OPRGB``. The default Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. @@ -312,7 +318,7 @@ The chromaticities of the primary colors and the white reference are: .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| -.. flat-table:: Adobe RGB Chromaticities +.. flat-table:: opRGB Chromaticities :header-rows: 1 :stub-columns: 0 :widths: 1 1 2 diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst index 322eb94c1d44..c5a560f0c13d 100644 --- a/Documentation/media/uapi/v4l/colorspaces.rst +++ b/Documentation/media/uapi/v4l/colorspaces.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _colorspaces: diff --git a/Documentation/media/uapi/v4l/common-defs.rst b/Documentation/media/uapi/v4l/common-defs.rst index 39058216b630..504c6c93c9b0 100644 --- a/Documentation/media/uapi/v4l/common-defs.rst +++ b/Documentation/media/uapi/v4l/common-defs.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _common-defs: diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst index 5f93e71122ef..889f2f2632a1 100644 --- a/Documentation/media/uapi/v4l/common.rst +++ b/Documentation/media/uapi/v4l/common.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _common: diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst index 8b5e1cebd8f4..f35575a300b4 100644 --- a/Documentation/media/uapi/v4l/compat.rst +++ b/Documentation/media/uapi/v4l/compat.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _compat: diff --git a/Documentation/media/uapi/v4l/constraints.svg b/Documentation/media/uapi/v4l/constraints.svg index 7e5d7185ca49..08f9f8b0985e 100644 --- a/Documentation/media/uapi/v4l/constraints.svg +++ b/Documentation/media/uapi/v4l/constraints.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg id="svg2" width="249.01mm" height="143.01mm" fill-rule="evenodd" stroke-linejoin="round" stroke-width="28.222" preserveAspectRatio="xMidYMid" version="1.2" viewBox="0 0 24900.998 14300.999" xml:space="preserve" xmlns="http://www.w3.org/2000/svg" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><metadata id="metadata325"><rdf:RDF><cc:Work rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/><dc:title/></cc:Work></rdf:RDF></metadata><defs id="defs4" class="ClipPathGroup"><marker id="marker6261" overflow="visible" orient="auto"><path id="path6263" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6125" overflow="visible" orient="auto"><path id="path6127" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker6001" overflow="visible" orient="auto"><path id="path6003" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5693" overflow="visible" orient="auto"><path id="path5695" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#f00" fill-rule="evenodd" stroke="#f00" stroke-width="1pt"/></marker><marker id="marker5575" overflow="visible" orient="auto"><path id="path5577" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5469" overflow="visible" orient="auto"><path id="path5471" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="marker5259" overflow="visible" orient="auto"><path id="path5261" transform="matrix(-.4 0 0 -.4 -4 0)" d="m0 0 5-5-17.5 5 17.5 5-5-5z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-width="1pt"/></marker><marker id="Arrow2Mend" overflow="visible" orient="auto"><path id="path4241" transform="scale(-.6)" d="m8.7186 4.0337-10.926-4.0177 10.926-4.0177c-1.7455 2.3721-1.7354 5.6175-6e-7 8.0354z" fill="#000080" fill-rule="evenodd" stroke="#000080" stroke-linejoin="round" stroke-width=".625"/></marker></defs><g id="g204" class="com.sun.star.drawing.CustomShape" transform="translate(-1350,-3250)"><g id="id6"><rect id="rect207" class="BoundingBox" x="1350" y="3250" width="24901" height="14301" diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index c1e6adbe83d7..0d46526b5935 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _control: diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index 45e8a895a320..ada7c22e6291 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _crop: diff --git a/Documentation/media/uapi/v4l/crop.svg b/Documentation/media/uapi/v4l/crop.svg index 3878fe4c49e9..32d72598d135 100644 --- a/Documentation/media/uapi/v4l/crop.svg +++ b/Documentation/media/uapi/v4l/crop.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst index d1641e9687a6..1bfd0b82cb85 100644 --- a/Documentation/media/uapi/v4l/depth-formats.rst +++ b/Documentation/media/uapi/v4l/depth-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _depth-formats: @@ -14,3 +21,4 @@ Depth data provides distance to points, mapped onto the image plane pixfmt-inzi pixfmt-z16 + pixfmt-cnf4 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst index 4218742ab5d9..134e22b32338 100644 --- a/Documentation/media/uapi/v4l/dev-capture.rst +++ b/Documentation/media/uapi/v4l/dev-capture.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _capture: @@ -99,6 +106,6 @@ requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_F Reading Images ============== -A video capture device may support the ::ref:`read() function <func-read>` +A video capture device may support the :ref:`read() function <func-read>` and/or streaming (:ref:`memory mapping <func-mmap>` or :ref:`user pointer <userp>`) I/O. See :ref:`io` for details. diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-codec.rst index c61e938bd8dc..b5e017c17834 100644 --- a/Documentation/media/uapi/v4l/dev-codec.rst +++ b/Documentation/media/uapi/v4l/dev-codec.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _codec: diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst index b946cc9e1064..b165e2c20910 100644 --- a/Documentation/media/uapi/v4l/dev-effect.rst +++ b/Documentation/media/uapi/v4l/dev-effect.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _effect: diff --git a/Documentation/media/uapi/v4l/dev-event.rst b/Documentation/media/uapi/v4l/dev-event.rst index a06ec4d65359..6029101fe1d7 100644 --- a/Documentation/media/uapi/v4l/dev-event.rst +++ b/Documentation/media/uapi/v4l/dev-event.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _event: diff --git a/Documentation/media/uapi/v4l/dev-meta.rst b/Documentation/media/uapi/v4l/dev-meta.rst index f7ac8d0d3af1..c5dbe882be65 100644 --- a/Documentation/media/uapi/v4l/dev-meta.rst +++ b/Documentation/media/uapi/v4l/dev-meta.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _metadata: @@ -7,21 +14,27 @@ Metadata Interface ****************** Metadata refers to any non-image data that supplements video frames with -additional information. This may include statistics computed over the image -or frame capture parameters supplied by the image source. This interface is -intended for transfer of metadata to userspace and control of that operation. +additional information. This may include statistics computed over the image, +frame capture parameters supplied by the image source or device specific +parameters for specifying how the device processes images. This interface is +intended for transfer of metadata between the userspace and the hardware and +control of that operation. -The metadata interface is implemented on video capture device nodes. The device -can be dedicated to metadata or can implement both video and metadata capture -as specified in its reported capabilities. +The metadata interface is implemented on video device nodes. The device can be +dedicated to metadata or can support both video and metadata as specified in its +reported capabilities. Querying Capabilities ===================== -Device nodes supporting the metadata interface set the ``V4L2_CAP_META_CAPTURE`` -flag in the ``device_caps`` field of the +Device nodes supporting the metadata capture interface set the +``V4L2_CAP_META_CAPTURE`` flag in the ``device_caps`` field of the :c:type:`v4l2_capability` structure returned by the :c:func:`VIDIOC_QUERYCAP` -ioctl. That flag means the device can capture metadata to memory. +ioctl. That flag means the device can capture metadata to memory. Similarly, +device nodes supporting metadata output interface set the +``V4L2_CAP_META_OUTPUT`` flag in the ``device_caps`` field of +:c:type:`v4l2_capability` structure. That flag means the device can read +metadata from memory. At least one of the read/write or streaming I/O methods must be supported. @@ -35,12 +48,13 @@ to the basic :ref:`format` ioctls, the :c:func:`VIDIOC_ENUM_FMT` ioctl must be supported as well. To use the :ref:`format` ioctls applications set the ``type`` field of the -:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` and use the -:c:type:`v4l2_meta_format` ``meta`` member of the ``fmt`` union as needed per -the desired operation. Both drivers and applications must set the remainder of -the :c:type:`v4l2_format` structure to 0. +:c:type:`v4l2_format` structure to ``V4L2_BUF_TYPE_META_CAPTURE`` or to +``V4L2_BUF_TYPE_META_OUTPUT`` and use the :c:type:`v4l2_meta_format` ``meta`` +member of the ``fmt`` union as needed per the desired operation. Both drivers +and applications must set the remainder of the :c:type:`v4l2_format` structure +to 0. -.. _v4l2-meta-format: +.. c:type:: v4l2_meta_format .. tabularcolumns:: |p{1.4cm}|p{2.2cm}|p{13.9cm}| diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst index 71da85ed7e4b..d3ad67da6386 100644 --- a/Documentation/media/uapi/v4l/dev-osd.rst +++ b/Documentation/media/uapi/v4l/dev-osd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _osd: diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst index 342eb4931f5c..3fe1b39696ed 100644 --- a/Documentation/media/uapi/v4l/dev-output.rst +++ b/Documentation/media/uapi/v4l/dev-output.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _output: diff --git a/Documentation/media/uapi/v4l/dev-overlay.rst b/Documentation/media/uapi/v4l/dev-overlay.rst index 9be14b55e305..b91b3837d4e7 100644 --- a/Documentation/media/uapi/v4l/dev-overlay.rst +++ b/Documentation/media/uapi/v4l/dev-overlay.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _overlay: diff --git a/Documentation/media/uapi/v4l/dev-radio.rst b/Documentation/media/uapi/v4l/dev-radio.rst index 2b5b836574eb..133eb0e788c2 100644 --- a/Documentation/media/uapi/v4l/dev-radio.rst +++ b/Documentation/media/uapi/v4l/dev-radio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _radio: diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst index 2e6878b624f6..d6a707f0b24f 100644 --- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _raw-vbi: diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst index 9c4e39dd66bd..624d6f95b842 100644 --- a/Documentation/media/uapi/v4l/dev-rds.rst +++ b/Documentation/media/uapi/v4l/dev-rds.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _rds: diff --git a/Documentation/media/uapi/v4l/dev-sdr.rst b/Documentation/media/uapi/v4l/dev-sdr.rst index b3e828d8cb1f..75595c58cb5b 100644 --- a/Documentation/media/uapi/v4l/dev-sdr.rst +++ b/Documentation/media/uapi/v4l/dev-sdr.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _sdr: diff --git a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst index d311a6866b3b..0aa6cb8a272b 100644 --- a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst +++ b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _sliced: diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst index d20d945803a7..2c2768c7343b 100644 --- a/Documentation/media/uapi/v4l/dev-subdev.rst +++ b/Documentation/media/uapi/v4l/dev-subdev.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _subdev: diff --git a/Documentation/media/uapi/v4l/dev-teletext.rst b/Documentation/media/uapi/v4l/dev-teletext.rst index 2648f6b37ea3..35e8c4b35458 100644 --- a/Documentation/media/uapi/v4l/dev-teletext.rst +++ b/Documentation/media/uapi/v4l/dev-teletext.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _ttx: @@ -10,7 +17,7 @@ This interface was aimed at devices receiving and demodulating Teletext data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext packages and storing formatted pages in cache memory. Such devices are usually implemented as microcontrollers with serial interface -(I:sup:`2`\ C) and could be found on old TV cards, dedicated Teletext +(I\ :sup:`2`\ C) and could be found on old TV cards, dedicated Teletext decoding cards and home-brew devices connected to the PC parallel port. The Teletext API was designed by Martin Buck. It was defined in the diff --git a/Documentation/media/uapi/v4l/dev-touch.rst b/Documentation/media/uapi/v4l/dev-touch.rst index 98797f255ce0..356f01385221 100644 --- a/Documentation/media/uapi/v4l/dev-touch.rst +++ b/Documentation/media/uapi/v4l/dev-touch.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _touch: diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst index fb7f8c26cf09..5dbe9d13b6e6 100644 --- a/Documentation/media/uapi/v4l/devices.rst +++ b/Documentation/media/uapi/v4l/devices.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _devices: diff --git a/Documentation/media/uapi/v4l/diff-v4l.rst b/Documentation/media/uapi/v4l/diff-v4l.rst index 8209eeb63dd2..dd6739e8a5b2 100644 --- a/Documentation/media/uapi/v4l/diff-v4l.rst +++ b/Documentation/media/uapi/v4l/diff-v4l.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _diff-v4l: diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst index 4e980a7e9c9c..bb8fd943b14e 100644 --- a/Documentation/media/uapi/v4l/dmabuf.rst +++ b/Documentation/media/uapi/v4l/dmabuf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dmabuf: diff --git a/Documentation/media/uapi/v4l/dv-timings.rst b/Documentation/media/uapi/v4l/dv-timings.rst index 415a0c4e2ccb..b3c69ca559e2 100644 --- a/Documentation/media/uapi/v4l/dv-timings.rst +++ b/Documentation/media/uapi/v4l/dv-timings.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _dv-timings: diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 9f7312bf3365..286a2dd7ec36 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _extended-controls: @@ -1110,10 +1117,16 @@ enum v4l2_mpeg_video_h264_loop_filter_mode - ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)`` Loop filter alpha coefficient, defined in the H264 standard. + This value corresponds to the slice_alpha_c0_offset_div2 slice header + field, and should be in the range of -6 to +6, inclusive. The actual alpha + offset FilterOffsetA is twice this value. Applicable to the H264 encoder. ``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)`` Loop filter beta coefficient, defined in the H264 standard. + This corresponds to the slice_beta_offset_div2 slice header field, and + should be in the range of -6 to +6, inclusive. The actual beta offset + FilterOffsetB is twice this value. Applicable to the H264 encoder. .. _v4l2-mpeg-video-h264-entropy-mode: @@ -1497,6 +1510,192 @@ enum v4l2_mpeg_video_h264_hierarchical_coding_type - +.. _v4l2-mpeg-mpeg2: + +``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS (struct)`` + Specifies the slice parameters (as extracted from the bitstream) for the + associated MPEG-2 slice data. This includes the necessary parameters for + configuring a stateless hardware decoding pipeline for MPEG-2. + The bitstream parameters are defined according to :ref:`mpeg2part2`. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_mpeg2_slice_params + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_mpeg2_slice_params + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bit_size`` + - Size (in bits) of the current slice data. + * - __u32 + - ``data_bit_offset`` + - Offset (in bits) to the video data in the current slice data. + * - struct :c:type:`v4l2_mpeg2_sequence` + - ``sequence`` + - Structure with MPEG-2 sequence metadata, merging relevant fields from + the sequence header and sequence extension parts of the bitstream. + * - struct :c:type:`v4l2_mpeg2_picture` + - ``picture`` + - Structure with MPEG-2 picture metadata, merging relevant fields from + the picture header and picture coding extension parts of the bitstream. + * - __u8 + - ``quantiser_scale_code`` + - Code used to determine the quantization scale to use for the IDCT. + * - __u8 + - ``backward_ref_index`` + - Index for the V4L2 buffer to use as backward reference, used with + B-coded and P-coded frames. + * - __u8 + - ``forward_ref_index`` + - Index for the V4L2 buffer to use as forward reference, used with + B-coded frames. + +.. c:type:: v4l2_mpeg2_sequence + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_mpeg2_sequence + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u16 + - ``horizontal_size`` + - The width of the displayable part of the frame's luminance component. + * - __u16 + - ``vertical_size`` + - The height of the displayable part of the frame's luminance component. + * - __u32 + - ``vbv_buffer_size`` + - Used to calculate the required size of the video buffering verifier, + defined (in bits) as: 16 * 1024 * vbv_buffer_size. + * - __u8 + - ``profile_and_level_indication`` + - The current profile and level indication as extracted from the + bitstream. + * - __u8 + - ``progressive_sequence`` + - Indication that all the frames for the sequence are progressive instead + of interlaced. + * - __u8 + - ``chroma_format`` + - The chrominance sub-sampling format (1: 4:2:0, 2: 4:2:2, 3: 4:4:4). + +.. c:type:: v4l2_mpeg2_picture + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_mpeg2_picture + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``picture_coding_type`` + - Picture coding type for the frame covered by the current slice + (V4L2_MPEG2_PICTURE_CODING_TYPE_I, V4L2_MPEG2_PICTURE_CODING_TYPE_P or + V4L2_MPEG2_PICTURE_CODING_TYPE_B). + * - __u8 + - ``f_code[2][2]`` + - Motion vector codes. + * - __u8 + - ``intra_dc_precision`` + - Precision of Discrete Cosine transform (0: 8 bits precision, + 1: 9 bits precision, 2: 10 bits precision, 3: 11 bits precision). + * - __u8 + - ``picture_structure`` + - Picture structure (1: interlaced top field, 2: interlaced bottom field, + 3: progressive frame). + * - __u8 + - ``top_field_first`` + - If set to 1 and interlaced stream, top field is output first. + * - __u8 + - ``frame_pred_frame_dct`` + - If set to 1, only frame-DCT and frame prediction are used. + * - __u8 + - ``concealment_motion_vectors`` + - If set to 1, motion vectors are coded for intra macroblocks. + * - __u8 + - ``q_scale_type`` + - This flag affects the inverse quantization process. + * - __u8 + - ``intra_vlc_format`` + - This flag affects the decoding of transform coefficient data. + * - __u8 + - ``alternate_scan`` + - This flag affects the decoding of transform coefficient data. + * - __u8 + - ``repeat_first_field`` + - This flag affects the decoding process of progressive frames. + * - __u8 + - ``progressive_frame`` + - Indicates whether the current frame is progressive. + +``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION (struct)`` + Specifies quantization matrices (as extracted from the bitstream) for the + associated MPEG-2 slice data. + + .. note:: + + This compound control is not yet part of the public kernel API and + it is expected to change. + +.. c:type:: v4l2_ctrl_mpeg2_quantization + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_ctrl_mpeg2_quantization + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u8 + - ``load_intra_quantiser_matrix`` + - One bit to indicate whether to load the ``intra_quantiser_matrix`` data. + * - __u8 + - ``load_non_intra_quantiser_matrix`` + - One bit to indicate whether to load the ``non_intra_quantiser_matrix`` + data. + * - __u8 + - ``load_chroma_intra_quantiser_matrix`` + - One bit to indicate whether to load the + ``chroma_intra_quantiser_matrix`` data, only relevant for non-4:2:0 YUV + formats. + * - __u8 + - ``load_chroma_non_intra_quantiser_matrix`` + - One bit to indicate whether to load the + ``chroma_non_intra_quantiser_matrix`` data, only relevant for non-4:2:0 + YUV formats. + * - __u8 + - ``intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for intra-coded frames, in zigzag + scanning order. It is relevant for both luma and chroma components, + although it can be superseded by the chroma-specific matrix for + non-4:2:0 YUV formats. + * - __u8 + - ``non_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for non-intra-coded frames, in + zigzag scanning order. It is relevant for both luma and chroma + components, although it can be superseded by the chroma-specific matrix + for non-4:2:0 YUV formats. + * - __u8 + - ``chroma_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for the chominance component of + intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. + * - __u8 + - ``chroma_non_intra_quantiser_matrix[64]`` + - The quantization matrix coefficients for the chrominance component of + non-intra-coded frames, in zigzag scanning order. Only relevant for + non-4:2:0 YUV formats. MFC 5.1 MPEG Controls --------------------- @@ -3804,7 +4003,7 @@ demodulator. It receives radio frequency (RF) from the antenna and converts that received signal to lower intermediate frequency (IF) or baseband frequency (BB). Tuners that could do baseband output are often called Zero-IF tuners. Older tuners were typically simple PLL tuners -inside a metal box, whilst newer ones are highly integrated chips +inside a metal box, while newer ones are highly integrated chips without a metal box "silicon tuners". These controls are mostly applicable for new feature rich silicon tuners, just because older tuners does not have much adjustable features. diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index 5f3f82cbfa34..8415268d439c 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _field-order: diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.svg b/Documentation/media/uapi/v4l/fieldseq_bt.svg index 909d758f8543..1dab1cd1b6de 100644 --- a/Documentation/media/uapi/v4l/fieldseq_bt.svg +++ b/Documentation/media/uapi/v4l/fieldseq_bt.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -2610,4 +2618,4 @@ sodipodi:role="line" y="-328.99481" x="10.054964 14.17972 18.766451 20.597849 25.18458 29.771311 34.358047 38.944778 41.238144 43.531509 48.118244 50.865334 53.158699 55.452068 57.283459 61.870193 63.701588 68.288322">v4l2_buffer.field:</tspan></text> -</g></svg>
\ No newline at end of file +</g></svg> diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.svg b/Documentation/media/uapi/v4l/fieldseq_tb.svg index 7c74344e770f..041071e43f9b 100644 --- a/Documentation/media/uapi/v4l/fieldseq_tb.svg +++ b/Documentation/media/uapi/v4l/fieldseq_tb.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -2607,4 +2615,4 @@ y="-311.9397" x="10.05469 15.55712 20.143852 24.730585 29.317318 33.904053 38.944508 41.237877 46.740307 51.327042 57.283192 61.869926 66.910378 73.328506 95.0867 100.58913 105.17586 109.7626 114.34933 118.93606 123.97652 126.26987 131.77232 136.35905 142.3152 146.90193 152.40436 158.82249 163.86295 168.9034 175.32153 197.12534 202.62778 207.21451 211.80124 216.38797 220.9747 226.01515 228.30853 233.81096 238.39769 244.35384 248.94058 253.98103 260.39917 282.15695 287.65936 292.24609 296.83282 301.41956 306.00629 311.04675 313.34012 318.84256 323.42929 329.38544 333.97217 339.47461 345.89273 350.9332 355.97363 362.39175 384.19559 389.698 394.28473 398.87149 403.45822 408.04495 413.08539 415.37875 420.8812 425.46793 431.42407 436.0108 441.05127 447.46939 469.2276 474.73001 479.31674 483.90347 488.49023 493.07697 498.1174 500.41077 505.91321 510.49994 516.45612 521.04285 526.54523 532.96338 538.00385 543.04431 549.4624">V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOM</tspan></text> -</g></svg>
\ No newline at end of file +</g></svg> diff --git a/Documentation/media/uapi/v4l/format.rst b/Documentation/media/uapi/v4l/format.rst index 3e3efb0e349e..9cdb296333b8 100644 --- a/Documentation/media/uapi/v4l/format.rst +++ b/Documentation/media/uapi/v4l/format.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _format: @@ -12,7 +19,7 @@ Data Format Negotiation Different devices exchange different kinds of data with applications, for example video images, raw or sliced VBI data, RDS datagrams. Even -within one kind many different formats are possible, in particular an +within one kind many different formats are possible, in particular there is an abundance of image formats. Although drivers must provide a default and the selection persists across closing and reopening a device, applications should always negotiate a data format before engaging in diff --git a/Documentation/media/uapi/v4l/func-close.rst b/Documentation/media/uapi/v4l/func-close.rst index e85a6744eb91..1a56811b827e 100644 --- a/Documentation/media/uapi/v4l/func-close.rst +++ b/Documentation/media/uapi/v4l/func-close.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-close: diff --git a/Documentation/media/uapi/v4l/func-ioctl.rst b/Documentation/media/uapi/v4l/func-ioctl.rst index ebfbe92f0478..e7a8cf62752e 100644 --- a/Documentation/media/uapi/v4l/func-ioctl.rst +++ b/Documentation/media/uapi/v4l/func-ioctl.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-ioctl: diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst index 6d2ce539bd72..75985d80788a 100644 --- a/Documentation/media/uapi/v4l/func-mmap.rst +++ b/Documentation/media/uapi/v4l/func-mmap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-mmap: diff --git a/Documentation/media/uapi/v4l/func-munmap.rst b/Documentation/media/uapi/v4l/func-munmap.rst index c2f4043d7d2b..0d472d86a036 100644 --- a/Documentation/media/uapi/v4l/func-munmap.rst +++ b/Documentation/media/uapi/v4l/func-munmap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-munmap: diff --git a/Documentation/media/uapi/v4l/func-open.rst b/Documentation/media/uapi/v4l/func-open.rst index deea34cc778b..a3d149ce6635 100644 --- a/Documentation/media/uapi/v4l/func-open.rst +++ b/Documentation/media/uapi/v4l/func-open.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-open: diff --git a/Documentation/media/uapi/v4l/func-poll.rst b/Documentation/media/uapi/v4l/func-poll.rst index 360bc6523ae2..4c579ed31358 100644 --- a/Documentation/media/uapi/v4l/func-poll.rst +++ b/Documentation/media/uapi/v4l/func-poll.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-poll: @@ -113,4 +120,5 @@ EINTR The call was interrupted by a signal. EINVAL - The ``nfds`` argument is greater than ``OPEN_MAX``. + The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use + ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/v4l/func-read.rst b/Documentation/media/uapi/v4l/func-read.rst index ae38c2d59d49..14aca4d5e8fd 100644 --- a/Documentation/media/uapi/v4l/func-read.rst +++ b/Documentation/media/uapi/v4l/func-read.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-read: diff --git a/Documentation/media/uapi/v4l/func-select.rst b/Documentation/media/uapi/v4l/func-select.rst index 002dedba2666..af5f1e31c0fb 100644 --- a/Documentation/media/uapi/v4l/func-select.rst +++ b/Documentation/media/uapi/v4l/func-select.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-select: diff --git a/Documentation/media/uapi/v4l/func-write.rst b/Documentation/media/uapi/v4l/func-write.rst index 938f33f85455..865129c726ad 100644 --- a/Documentation/media/uapi/v4l/func-write.rst +++ b/Documentation/media/uapi/v4l/func-write.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _func-write: diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst index 058b5db95c32..7d8e9efbeb1e 100644 --- a/Documentation/media/uapi/v4l/hist-v4l2.rst +++ b/Documentation/media/uapi/v4l/hist-v4l2.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _hist-v4l2: diff --git a/Documentation/media/uapi/v4l/hsv-formats.rst b/Documentation/media/uapi/v4l/hsv-formats.rst index f0f2615eaa95..f52f8ba131f0 100644 --- a/Documentation/media/uapi/v4l/hsv-formats.rst +++ b/Documentation/media/uapi/v4l/hsv-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _hsv-formats: diff --git a/Documentation/media/uapi/v4l/io.rst b/Documentation/media/uapi/v4l/io.rst index 94b38a10ee65..049a2530d3a2 100644 --- a/Documentation/media/uapi/v4l/io.rst +++ b/Documentation/media/uapi/v4l/io.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _io: diff --git a/Documentation/media/uapi/v4l/libv4l-introduction.rst b/Documentation/media/uapi/v4l/libv4l-introduction.rst index ccc3c4d2fc0f..1b206d380d4b 100644 --- a/Documentation/media/uapi/v4l/libv4l-introduction.rst +++ b/Documentation/media/uapi/v4l/libv4l-introduction.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _libv4l-introduction: diff --git a/Documentation/media/uapi/v4l/libv4l.rst b/Documentation/media/uapi/v4l/libv4l.rst index 332c1d42688b..d114fbf1ffa6 100644 --- a/Documentation/media/uapi/v4l/libv4l.rst +++ b/Documentation/media/uapi/v4l/libv4l.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _libv4l: diff --git a/Documentation/media/uapi/v4l/meta-formats.rst b/Documentation/media/uapi/v4l/meta-formats.rst index 0c4e1ecf5879..5f956fa784b7 100644 --- a/Documentation/media/uapi/v4l/meta-formats.rst +++ b/Documentation/media/uapi/v4l/meta-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _meta-formats: @@ -12,6 +19,8 @@ These formats are used for the :ref:`metadata` interface only. .. toctree:: :maxdepth: 1 + pixfmt-meta-intel-ipu3 + pixfmt-meta-d4xx pixfmt-meta-uvc pixfmt-meta-vsp1-hgo pixfmt-meta-vsp1-hgt diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst index 670596c1a4f7..c47708bf2c87 100644 --- a/Documentation/media/uapi/v4l/mmap.rst +++ b/Documentation/media/uapi/v4l/mmap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _mmap: @@ -231,17 +238,17 @@ up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`. In the write loop, when the application runs out of free buffers, it must wait until an empty buffer can be dequeued and reused. -To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF` -and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer -being mapped, enqueued, full or empty can be determined at any time -using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend -execution of the application until one or more buffers can be dequeued. -By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is -in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` -returns immediately with an ``EAGAIN`` error code when no buffer is -available. The :ref:`select() <func-select>` or :ref:`poll() -<func-poll>` functions are always available. +To enqueue and dequeue a buffer applications use the +:ref:`VIVIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +ioctl. The status of a buffer being mapped, enqueued, full or empty can +be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two +methods exist to suspend execution of the application until one or more +buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` +blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK`` +flag was given to the :ref:`open() <func-open>` function, +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN`` +error code when no buffer is available. The :ref:`select() <func-select>` +or :ref:`poll() <func-poll>` functions are always available. To start and stop capturing or output applications call the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF diff --git a/Documentation/media/uapi/v4l/nv12mt.svg b/Documentation/media/uapi/v4l/nv12mt.svg index 65d05606c04c..067d8fb34ba2 100644 --- a/Documentation/media/uapi/v4l/nv12mt.svg +++ b/Documentation/media/uapi/v4l/nv12mt.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/nv12mt_example.svg b/Documentation/media/uapi/v4l/nv12mt_example.svg index fc51fe8fda8b..70c3200fdb32 100644 --- a/Documentation/media/uapi/v4l/nv12mt_example.svg +++ b/Documentation/media/uapi/v4l/nv12mt_example.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst index afd116edb40d..42fad5001c5c 100644 --- a/Documentation/media/uapi/v4l/open.rst +++ b/Documentation/media/uapi/v4l/open.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _open: @@ -53,7 +60,7 @@ ranges. These ranges are listed in :ref:`devices`. The creation of character special files (with mknod) is a privileged operation and devices cannot be opened by major and minor number. That -means applications cannot *reliable* scan for loaded or installed +means applications cannot *reliably* scan for loaded or installed drivers. The user must enter a device name, or the application can try the conventional device names. diff --git a/Documentation/media/uapi/v4l/pipeline.dot b/Documentation/media/uapi/v4l/pipeline.dot index 02d7fcf12b26..8c53ce719a14 100644 --- a/Documentation/media/uapi/v4l/pipeline.dot +++ b/Documentation/media/uapi/v4l/pipeline.dot @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + digraph board { rankdir=TB colorscheme=x11 diff --git a/Documentation/media/uapi/v4l/pixfmt-cnf4.rst b/Documentation/media/uapi/v4l/pixfmt-cnf4.rst new file mode 100644 index 000000000000..8f469290c304 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-cnf4.rst @@ -0,0 +1,31 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _V4L2-PIX-FMT-CNF4: + +****************************** +V4L2_PIX_FMT_CNF4 ('CNF4') +****************************** + +Depth sensor confidence information as a 4 bits per pixel packed array + +Description +=========== + +Proprietary format used by Intel RealSense Depth cameras containing depth +confidence information in range 0-15 with 0 indicating that the sensor was +unable to resolve any signal and 15 indicating maximum level of confidence for +the specific sensor (actual error margins might change from sensor to sensor). + +Every two consecutive pixels are packed into a single byte. +Bits 0-3 of byte n refer to confidence value of depth pixel 2*n, +bits 4-7 to confidence value of depth pixel 2*n+1. + +**Bit-packed representation.** + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 64 64 + + * - Y'\ :sub:`01[3:0]`\ (bits 7--4) Y'\ :sub:`00[3:0]`\ (bits 3--0) + - Y'\ :sub:`03[3:0]`\ (bits 7--4) Y'\ :sub:`02[3:0]`\ (bits 3--0) diff --git a/Documentation/media/uapi/v4l/pixfmt-compressed.rst b/Documentation/media/uapi/v4l/pixfmt-compressed.rst index d382e7a5c38e..e4c5e456df59 100644 --- a/Documentation/media/uapi/v4l/pixfmt-compressed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-compressed.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ****************** Compressed Formats @@ -60,6 +67,22 @@ Compressed Formats - ``V4L2_PIX_FMT_MPEG2`` - 'MPG2' - MPEG2 video elementary stream. + * .. _V4L2-PIX-FMT-MPEG2-SLICE: + + - ``V4L2_PIX_FMT_MPEG2_SLICE`` + - 'MG2S' + - MPEG-2 parsed slice data, as extracted from the MPEG-2 bitstream. + This format is adapted for stateless video decoders that implement a + MPEG-2 pipeline (using the :ref:`codec` and :ref:`media-request-api`). + Metadata associated with the frame to decode is required to be passed + through the ``V4L2_CID_MPEG_VIDEO_MPEG2_SLICE_PARAMS`` control and + quantization matrices can optionally be specified through the + ``V4L2_CID_MPEG_VIDEO_MPEG2_QUANTIZATION`` control. + See the :ref:`associated Codec Control IDs <v4l2-mpeg-mpeg2>`. + Exactly one output and one capture buffer must be provided for use with + this pixel format. The output buffer must contain the appropriate number + of macroblocks to decode a full corresponding frame to the matching + capture buffer. * .. _V4L2-PIX-FMT-MPEG4: - ``V4L2_PIX_FMT_MPEG4`` @@ -101,4 +124,4 @@ Compressed Formats - 'FWHT' - Video elementary stream using a codec based on the Fast Walsh Hadamard Transform. This codec is implemented by the vicodec ('Virtual Codec') - driver. See the vicodec-codec.h header for more details. + driver. See the codec-fwht.h header for more details. diff --git a/Documentation/media/uapi/v4l/pixfmt-grey.rst b/Documentation/media/uapi/v4l/pixfmt-grey.rst index dad813819d3e..3a8156164d39 100644 --- a/Documentation/media/uapi/v4l/pixfmt-grey.rst +++ b/Documentation/media/uapi/v4l/pixfmt-grey.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-GREY: diff --git a/Documentation/media/uapi/v4l/pixfmt-indexed.rst b/Documentation/media/uapi/v4l/pixfmt-indexed.rst index 6edac54dad74..4538b425a046 100644 --- a/Documentation/media/uapi/v4l/pixfmt-indexed.rst +++ b/Documentation/media/uapi/v4l/pixfmt-indexed.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _pixfmt-indexed: diff --git a/Documentation/media/uapi/v4l/pixfmt-intro.rst b/Documentation/media/uapi/v4l/pixfmt-intro.rst index 4bc116aa8193..ca0a6e0d8959 100644 --- a/Documentation/media/uapi/v4l/pixfmt-intro.rst +++ b/Documentation/media/uapi/v4l/pixfmt-intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ********************** Standard Image Formats diff --git a/Documentation/media/uapi/v4l/pixfmt-inzi.rst b/Documentation/media/uapi/v4l/pixfmt-inzi.rst index 75272f80bc8a..af2940d844ff 100644 --- a/Documentation/media/uapi/v4l/pixfmt-inzi.rst +++ b/Documentation/media/uapi/v4l/pixfmt-inzi.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-INZI: diff --git a/Documentation/media/uapi/v4l/pixfmt-m420.rst b/Documentation/media/uapi/v4l/pixfmt-m420.rst index 6703f4079c3e..c2bae959bf51 100644 --- a/Documentation/media/uapi/v4l/pixfmt-m420.rst +++ b/Documentation/media/uapi/v4l/pixfmt-m420.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-M420: diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst new file mode 100644 index 000000000000..862e1f327150 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst @@ -0,0 +1,217 @@ +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + +.. _v4l2-meta-fmt-d4xx: + +******************************* +V4L2_META_FMT_D4XX ('D4XX') +******************************* + +Intel D4xx UVC Cameras Metadata + + +Description +=========== + +Intel D4xx (D435 and other) cameras include per-frame metadata in their UVC +payload headers, following the Microsoft(R) UVC extension proposal [1_]. That +means, that the private D4XX metadata, following the standard UVC header, is +organised in blocks. D4XX cameras implement several standard block types, +proposed by Microsoft, and several proprietary ones. Supported standard metadata +types are MetadataId_CaptureStats (ID 3), MetadataId_CameraExtrinsics (ID 4), +and MetadataId_CameraIntrinsics (ID 5). For their description see [1_]. This +document describes proprietary metadata types, used by D4xx cameras. + +V4L2_META_FMT_D4XX buffers follow the metadata buffer layout of +V4L2_META_FMT_UVC with the only difference, that it also includes proprietary +payload header data. D4xx cameras use bulk transfers and only send one payload +per frame, therefore their headers cannot be larger than 255 bytes. + +Below are proprietary Microsoft style metadata types, used by D4xx cameras, +where all fields are in little endian order: + +.. flat-table:: D4xx metadata + :widths: 1 4 + :header-rows: 1 + :stub-columns: 0 + + * - Field + - Description + * - :cspan:`1` *Depth Control* + * - __u32 ID + - 0x80000000 + * - __u32 Size + - Size in bytes (currently 56) + * - __u32 Version + - Version of this structure. The documentation herein corresponds to + version xxx. The version number will be incremented when new fields are + added. + * - __u32 Flags + - A bitmask of flags: see [2_] below + * - __u32 Gain + - Gain value in internal units, same as the V4L2_CID_GAIN control, used to + capture the frame + * - __u32 Exposure + - Exposure time (in microseconds) used to capture the frame + * - __u32 Laser power + - Power of the laser LED 0-360, used for depth measurement + * - __u32 AE mode + - 0: manual; 1: automatic exposure + * - __u32 Exposure priority + - Exposure priority value: 0 - constant frame rate + * - __u32 AE ROI left + - Left border of the AE Region of Interest (all ROI values are in pixels + and lie between 0 and maximum width or height respectively) + * - __u32 AE ROI right + - Right border of the AE Region of Interest + * - __u32 AE ROI top + - Top border of the AE Region of Interest + * - __u32 AE ROI bottom + - Bottom border of the AE Region of Interest + * - __u32 Preset + - Preset selector value, default: 0, unless changed by the user + * - __u32 Laser mode + - 0: off, 1: on + * - :cspan:`1` *Capture Timing* + * - __u32 ID + - 0x80000001 + * - __u32 Size + - Size in bytes (currently 40) + * - __u32 Version + - Version of this structure. The documentation herein corresponds to + version xxx. The version number will be incremented when new fields are + added. + * - __u32 Flags + - A bitmask of flags: see [3_] below + * - __u32 Frame counter + - Monotonically increasing counter + * - __u32 Optical time + - Time in microseconds from the beginning of a frame till its middle + * - __u32 Readout time + - Time, used to read out a frame in microseconds + * - __u32 Exposure time + - Frame exposure time in microseconds + * - __u32 Frame interval + - In microseconds = 1000000 / framerate + * - __u32 Pipe latency + - Time in microseconds from start of frame to data in USB buffer + * - :cspan:`1` *Configuration* + * - __u32 ID + - 0x80000002 + * - __u32 Size + - Size in bytes (currently 40) + * - __u32 Version + - Version of this structure. The documentation herein corresponds to + version xxx. The version number will be incremented when new fields are + added. + * - __u32 Flags + - A bitmask of flags: see [4_] below + * - __u8 Hardware type + - Camera hardware version [5_] + * - __u8 SKU ID + - Camera hardware configuration [6_] + * - __u32 Cookie + - Internal synchronisation + * - __u16 Format + - Image format code [7_] + * - __u16 Width + - Width in pixels + * - __u16 Height + - Height in pixels + * - __u16 Framerate + - Requested frame rate per second + * - __u16 Trigger + - Byte 0: bit 0: depth and RGB are synchronised, bit 1: external trigger + +.. _1: + +[1] https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5 + +.. _2: + +[2] Depth Control flags specify which fields are valid: :: + + 0x00000001 Gain + 0x00000002 Exposure + 0x00000004 Laser power + 0x00000008 AE mode + 0x00000010 Exposure priority + 0x00000020 AE ROI + 0x00000040 Preset + +.. _3: + +[3] Capture Timing flags specify which fields are valid: :: + + 0x00000001 Frame counter + 0x00000002 Optical time + 0x00000004 Readout time + 0x00000008 Exposure time + 0x00000010 Frame interval + 0x00000020 Pipe latency + +.. _4: + +[4] Configuration flags specify which fields are valid: :: + + 0x00000001 Hardware type + 0x00000002 SKU ID + 0x00000004 Cookie + 0x00000008 Format + 0x00000010 Width + 0x00000020 Height + 0x00000040 Framerate + 0x00000080 Trigger + 0x00000100 Cal count + +.. _5: + +[5] Camera model: :: + + 0 DS5 + 1 IVCAM2 + +.. _6: + +[6] 8-bit camera hardware configuration bitfield: :: + + [1:0] depthCamera + 00: no depth + 01: standard depth + 10: wide depth + 11: reserved + [2] depthIsActive - has a laser projector + [3] RGB presence + [4] Inertial Measurement Unit (IMU) presence + [5] projectorType + 0: HPTG + 1: Princeton + [6] 0: a projector, 1: an LED + [7] reserved + +.. _7: + +[7] Image format codes per video streaming interface: + +Depth: :: + + 1 Z16 + 2 Z + +Left sensor: :: + + 1 Y8 + 2 UYVY + 3 R8L8 + 4 Calibration + 5 W10 + +Fish Eye sensor: :: + + 1 RAW8 diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst new file mode 100644 index 000000000000..dc871006b41a --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst @@ -0,0 +1,178 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _v4l2-meta-fmt-params: +.. _v4l2-meta-fmt-stat-3a: + +****************************************************************** +V4L2_META_FMT_IPU3_PARAMS ('ip3p'), V4L2_META_FMT_IPU3_3A ('ip3s') +****************************************************************** + +.. c:type:: ipu3_uapi_stats_3a + +3A statistics +============= + +For IPU3 ImgU, the 3A statistics accelerators collect different statistics over +an input bayer frame. Those statistics, defined in data struct :c:type:`ipu3_uapi_stats_3a`, +are obtained from "ipu3-imgu 3a stat" metadata capture video node, which are then +passed to user space for statistics analysis using :c:type:`v4l2_meta_format` interface. + +The statistics collected are AWB (Auto-white balance) RGBS (Red, Green, Blue and +Saturation measure) cells, AWB filter response, AF (Auto-focus) filter response, +and AE (Auto-exposure) histogram. + +struct :c:type:`ipu3_uapi_4a_config` saves configurable parameters for all above. + +.. code-block:: c + + struct ipu3_uapi_stats_3a { + struct ipu3_uapi_awb_raw_buffer awb_raw_buffer; + struct ipu3_uapi_ae_raw_buffer_aligned ae_raw_buffer[IPU3_UAPI_MAX_STRIPES]; + struct ipu3_uapi_af_raw_buffer af_raw_buffer; + struct ipu3_uapi_awb_fr_raw_buffer awb_fr_raw_buffer; + struct ipu3_uapi_4a_config stats_4a_config; + __u32 ae_join_buffers; + __u8 padding[28]; + struct ipu3_uapi_stats_3a_bubble_info_per_stripe stats_3a_bubble_per_stripe; + struct ipu3_uapi_ff_status stats_3a_status; + }; + +.. c:type:: ipu3_uapi_params + +Pipeline parameters +=================== + +IPU3 pipeline has a number of image processing stages, each of which takes a +set of parameters as input. The major stages of pipelines are shown here: + +Raw pixels -> Bayer Downscaling -> Optical Black Correction -> + +Linearization -> Lens Shading Correction -> White Balance / Exposure / + +Focus Apply -> Bayer Noise Reduction -> ANR -> Demosaicing -> Color + +Correction Matrix -> Gamma correction -> Color Space Conversion -> + +Chroma Down Scaling -> Chromatic Noise Reduction -> Total Color + +Correction -> XNR3 -> TNR -> DDR + +The table below presents a description of the above algorithms. + +======================== ======================================================= +Name Description +======================== ======================================================= +Optical Black Correction Optical Black Correction block subtracts a pre-defined + value from the respective pixel values to obtain better + image quality. + Defined in :c:type:`ipu3_uapi_obgrid_param`. +Linearization This algo block uses linearization parameters to + address non-linearity sensor effects. The Lookup table + table is defined in + :c:type:`ipu3_uapi_isp_lin_vmem_params`. +SHD Lens shading correction is used to correct spatial + non-uniformity of the pixel response due to optical + lens shading. This is done by applying a different gain + for each pixel. The gain, black level etc are + configured in :c:type:`ipu3_uapi_shd_config_static`. +BNR Bayer noise reduction block removes image noise by + applying a bilateral filter. + See :c:type:`ipu3_uapi_bnr_static_config` for details. +ANR Advanced Noise Reduction is a block based algorithm + that performs noise reduction in the Bayer domain. The + convolution matrix etc can be found in + :c:type:`ipu3_uapi_anr_config`. +Demosaicing Demosaicing converts raw sensor data in Bayer format + into RGB (Red, Green, Blue) presentation. Then add + outputs of estimation of Y channel for following stream + processing by Firmware. The struct is defined as + :c:type:`ipu3_uapi_dm_config`. (TODO) +Color Correction Color Correction algo transforms sensor specific color + space to the standard "sRGB" color space. This is done + by applying 3x3 matrix defined in + :c:type:`ipu3_uapi_ccm_mat_config`. +Gamma correction Gamma correction :c:type:`ipu3_uapi_gamma_config` is a + basic non-linear tone mapping correction that is + applied per pixel for each pixel component. +CSC Color space conversion transforms each pixel from the + RGB primary presentation to YUV (Y: brightness, + UV: Luminance) presentation. This is done by applying + a 3x3 matrix defined in + :c:type:`ipu3_uapi_csc_mat_config` +CDS Chroma down sampling + After the CSC is performed, the Chroma Down Sampling + is applied for a UV plane down sampling by a factor + of 2 in each direction for YUV 4:2:0 using a 4x2 + configurable filter :c:type:`ipu3_uapi_cds_params`. +CHNR Chroma noise reduction + This block processes only the chrominance pixels and + performs noise reduction by cleaning the high + frequency noise. + See struct :c:type:`ipu3_uapi_yuvp1_chnr_config`. +TCC Total color correction as defined in struct + :c:type:`ipu3_uapi_yuvp2_tcc_static_config`. +XNR3 eXtreme Noise Reduction V3 is the third revision of + noise reduction algorithm used to improve image + quality. This removes the low frequency noise in the + captured image. Two related structs are being defined, + :c:type:`ipu3_uapi_isp_xnr3_params` for ISP data memory + and :c:type:`ipu3_uapi_isp_xnr3_vmem_params` for vector + memory. +TNR Temporal Noise Reduction block compares successive + frames in time to remove anomalies / noise in pixel + values. :c:type:`ipu3_uapi_isp_tnr3_vmem_params` and + :c:type:`ipu3_uapi_isp_tnr3_params` are defined for ISP + vector and data memory respectively. +======================== ======================================================= + +A few stages of the pipeline will be executed by firmware running on the ISP +processor, while many others will use a set of fixed hardware blocks also +called accelerator cluster (ACC) to crunch pixel data and produce statistics. + +ACC parameters of individual algorithms, as defined by +:c:type:`ipu3_uapi_acc_param`, can be chosen to be applied by the user +space through struct :c:type:`ipu3_uapi_flags` embedded in +:c:type:`ipu3_uapi_params` structure. For parameters that are configured as +not enabled by the user space, the corresponding structs are ignored by the +driver, in which case the existing configuration of the algorithm will be +preserved. + +Both 3A statistics and pipeline parameters described here are closely tied to +the underlying camera sub-system (CSS) APIs. They are usually consumed and +produced by dedicated user space libraries that comprise the important tuning +tools, thus freeing the developers from being bothered with the low level +hardware and algorithm details. + +It should be noted that IPU3 DMA operations require the addresses of all data +structures (that includes both input and output) to be aligned on 32 byte +boundaries. + +The meta data :c:type:`ipu3_uapi_params` will be sent to "ipu3-imgu parameters" +video node in ``V4L2_BUF_TYPE_META_CAPTURE`` format. + +.. code-block:: c + + struct ipu3_uapi_params { + /* Flags which of the settings below are to be applied */ + struct ipu3_uapi_flags use; + + /* Accelerator cluster parameters */ + struct ipu3_uapi_acc_param acc_param; + + /* ISP vector address space parameters */ + struct ipu3_uapi_isp_lin_vmem_params lin_vmem_params; + struct ipu3_uapi_isp_tnr3_vmem_params tnr3_vmem_params; + struct ipu3_uapi_isp_xnr3_vmem_params xnr3_vmem_params; + + /* ISP data memory (DMEM) parameters */ + struct ipu3_uapi_isp_tnr3_params tnr3_dmem_params; + struct ipu3_uapi_isp_xnr3_params xnr3_dmem_params; + + /* Optical black level compensation */ + struct ipu3_uapi_obgrid_param obgrid_param; + }; + +Intel IPU3 ImgU uAPI data types +=============================== + +.. kernel-doc:: drivers/staging/media/ipu3/include/intel-ipu3.h diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst index b5165dc090c2..481e4e0e6e1d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-meta-fmt-uvc: diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst index 67796594fd48..f7a861696281 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-meta-fmt-vsp1-hgo: diff --git a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst index fb9f79466319..2ebccdcca95d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-meta-fmt-vsp1-hgt: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12.rst b/Documentation/media/uapi/v4l/pixfmt-nv12.rst index 2776b41377d5..b8c021b07fd2 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv12.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv12.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV12: .. _V4L2-PIX-FMT-NV21: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12m.rst b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst index c1a2779f604c..9b2c5c21280a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv12m.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV12M: .. _v4l2-pix-fmt-nv12mt-16x16: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst index 172a3825604e..2092725de33c 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV12MT: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16.rst b/Documentation/media/uapi/v4l/pixfmt-nv16.rst index f0fdad3006cf..5ec4b7fa8f04 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV16: .. _V4L2-PIX-FMT-NV61: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16m.rst b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst index c45f036763e7..4a63bcf18b70 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv16m.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV16M: .. _v4l2-pix-fmt-nv61m: diff --git a/Documentation/media/uapi/v4l/pixfmt-nv24.rst b/Documentation/media/uapi/v4l/pixfmt-nv24.rst index bda973e86227..13fc6fe1a3d6 100644 --- a/Documentation/media/uapi/v4l/pixfmt-nv24.rst +++ b/Documentation/media/uapi/v4l/pixfmt-nv24.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-NV24: .. _V4L2-PIX-FMT-NV42: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst index 8edf65c80660..38b1895a509f 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _packed-hsv: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst index 4938d9655a41..6b3781c04dd5 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _packed-rgb: diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst index d7644b411ccc..f53e8f57a003 100644 --- a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _packed-yuv: diff --git a/Documentation/media/uapi/v4l/pixfmt-reserved.rst b/Documentation/media/uapi/v4l/pixfmt-reserved.rst index 38af1472a4b4..b2cd155e691b 100644 --- a/Documentation/media/uapi/v4l/pixfmt-reserved.rst +++ b/Documentation/media/uapi/v4l/pixfmt-reserved.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _pixfmt-reserved: @@ -243,7 +250,20 @@ please make a proposal on the linux-media mailing list. It is an opaque intermediate format and the MDP hardware must be used to convert ``V4L2_PIX_FMT_MT21C`` to ``V4L2_PIX_FMT_NV12M``, ``V4L2_PIX_FMT_YUV420M`` or ``V4L2_PIX_FMT_YVU420``. - + * .. _V4L2-PIX-FMT-SUNXI-TILED-NV12: + + - ``V4L2_PIX_FMT_SUNXI_TILED_NV12`` + - 'ST12' + - Two-planar NV12-based format used by the video engine found on Allwinner + (codenamed sunxi) platforms, with 32x32 tiles for the luminance plane + and 32x64 tiles for the chrominance plane. The data in each tile is + stored in linear order, within the tile bounds. Each tile follows the + previous one linearly in memory (from left to right, top to bottom). + + The associated buffer dimensions are aligned to match an integer number + of tiles, resulting in 32-aligned resolutions for the luminance plane + and 16-aligned resolutions for the chrominance plane (with 2x2 + subsampling). .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst index 1f9a7e3a07c9..48ab80024835 100644 --- a/Documentation/media/uapi/v4l/pixfmt-rgb.rst +++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _pixfmt-rgb: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst index 179894f6f8fb..e7a89fe7e117 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-sdr-fmt-cs8: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst index 5cf7d387447c..d10d56f0e63a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-SDR-FMT-CS14LE: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst index fd915b7629b7..f37df90f5a21 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-sdr-fmt-cu8: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst index 8922f5b35457..237998fb5f9f 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-SDR-FMT-CU16LE: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst index 2de1b1a0f517..df078dcfd18d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-SDR-FMT-PCU16BE: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst index da8b26bf6b95..a1ea63db9230 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-SDR-FMT-PCU18BE: diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst index 5499eed39477..11a05ea60e26 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst @@ -1,4 +1,12 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections + .. _V4L2-SDR-FMT-PCU20BE: ****************************** diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst index 5e383382802f..3c2c9f75fc5e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst +++ b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-SDR-FMT-RU12LE: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst index 99cde5077519..75279f0fdad8 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-pix-fmt-ipu3-sbggr10: .. _v4l2-pix-fmt-ipu3-sgbrg10: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst index af2538ce34e5..cab7fbb1f2fe 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB10: .. _v4l2-pix-fmt-sbggr10: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst index c44e093514de..5bb58764b532 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SBGGR10ALAW8: .. _v4l2-pix-fmt-sgbrg10alaw8: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst index 5e041d02eff0..cbc9c0a52ab4 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SBGGR10DPCM8: .. _v4l2-pix-fmt-sgbrg10dpcm8: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst index d9e07a4b8b31..cdb70ac26126 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB10P: .. _v4l2-pix-fmt-sbggr10p: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst index 15041e568a0a..6fb6a937e6ad 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb12.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB12: .. _v4l2-pix-fmt-sbggr12: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst index 59918a7913fe..01413be12916 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb12p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB12P: .. _v4l2-pix-fmt-sbggr12p: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst index 88d20c0e4282..b583531c2853 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb14p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB14P: .. _v4l2-pix-fmt-sbggr14p: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb16.rst b/Documentation/media/uapi/v4l/pixfmt-srggb16.rst index d407b2b2050f..36527c49eaf7 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB16: .. _v4l2-pix-fmt-sbggr16: diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst index 5ac25a634d30..f5233c1e2314 100644 --- a/Documentation/media/uapi/v4l/pixfmt-srggb8.rst +++ b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-SRGGB8: .. _v4l2-pix-fmt-sbggr8: diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst b/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst index 07834cd1249e..b7d3d6ccebc5 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-td08.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-TCH-FMT-DELTA-TD08: diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst index 29ebcf40a989..4031b175257c 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-td16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-TCH-FMT-DELTA-TD16: diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst b/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst index e7fb7ddd191b..2d447475aaa7 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-TCH-FMT-TU08: diff --git a/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst index 1588fcc3f1e7..8278543be99a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-TCH-FMT-TU16: diff --git a/Documentation/media/uapi/v4l/pixfmt-uv8.rst b/Documentation/media/uapi/v4l/pixfmt-uv8.rst index c449231b51bb..6008c898305d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-uv8.rst +++ b/Documentation/media/uapi/v4l/pixfmt-uv8.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-UV8: diff --git a/Documentation/media/uapi/v4l/pixfmt-uyvy.rst b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst index ecdc2d94c209..72da2639d37e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-uyvy.rst +++ b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-UYVY: diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst index ef52f637d8e9..7f82dad9013a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ****************************** Multi-planar format structures diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst index 826f2305da01..71eebfc6d853 100644 --- a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ****************************** Single-planar format structure diff --git a/Documentation/media/uapi/v4l/pixfmt-vyuy.rst b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst index 670c339c1714..39b99707cd99 100644 --- a/Documentation/media/uapi/v4l/pixfmt-vyuy.rst +++ b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-VYUY: diff --git a/Documentation/media/uapi/v4l/pixfmt-y10.rst b/Documentation/media/uapi/v4l/pixfmt-y10.rst index 89e22899cd81..63277686764a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y10.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y10.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y10: diff --git a/Documentation/media/uapi/v4l/pixfmt-y10b.rst b/Documentation/media/uapi/v4l/pixfmt-y10b.rst index 9feddf3ae07b..49c4dd432413 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y10b.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y10b.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y10BPACK: diff --git a/Documentation/media/uapi/v4l/pixfmt-y10p.rst b/Documentation/media/uapi/v4l/pixfmt-y10p.rst index 13b571306915..7893642faee3 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y10p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y10p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y10P: diff --git a/Documentation/media/uapi/v4l/pixfmt-y12.rst b/Documentation/media/uapi/v4l/pixfmt-y12.rst index 0f230713290b..33a943b4996a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y12.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y12.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y12: diff --git a/Documentation/media/uapi/v4l/pixfmt-y12i.rst b/Documentation/media/uapi/v4l/pixfmt-y12i.rst index bb39a2463564..1d4a14e1ec6e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y12i.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y12i.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y12I: diff --git a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst index 54ce35ef84b7..1e72bfe2d557 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y16-BE: diff --git a/Documentation/media/uapi/v4l/pixfmt-y16.rst b/Documentation/media/uapi/v4l/pixfmt-y16.rst index bcbd52de3aca..f77d900db131 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y16: diff --git a/Documentation/media/uapi/v4l/pixfmt-y41p.rst b/Documentation/media/uapi/v4l/pixfmt-y41p.rst index e1fe548807a4..829c68afd8d7 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y41p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y41p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y41P: diff --git a/Documentation/media/uapi/v4l/pixfmt-y8i.rst b/Documentation/media/uapi/v4l/pixfmt-y8i.rst index fd8ed23dd342..2c88ed90522d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-y8i.rst +++ b/Documentation/media/uapi/v4l/pixfmt-y8i.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Y8I: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv410.rst b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst index b51a0d1c6108..ebb72a5c7ceb 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv410.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YVU410: .. _v4l2-pix-fmt-yuv410: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst index 2582341972db..83ddaa3f8dfb 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUV411P: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst index a9b85c4b1dbc..f4f6f792a23e 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv420.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YVU420: .. _V4L2-PIX-FMT-YUV420: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst index 32c68c33f2b1..c29b30c6445a 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUV420M: .. _v4l2-pix-fmt-yvu420m: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst index 9e7028c4967c..737fd94a9ae9 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUV422M: .. _v4l2-pix-fmt-yvu422m: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst index a96f836c7fa5..7cebb6ebb621 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUV422P: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst index 8605bfaee112..8f14ca378816 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUV444M: .. _v4l2-pix-fmt-yvu444m: diff --git a/Documentation/media/uapi/v4l/pixfmt-yuyv.rst b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst index 53e876d053fb..d86d7f086c41 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yuyv.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YUYV: diff --git a/Documentation/media/uapi/v4l/pixfmt-yvyu.rst b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst index b9c31746e565..656a830fed02 100644 --- a/Documentation/media/uapi/v4l/pixfmt-yvyu.rst +++ b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-YVYU: diff --git a/Documentation/media/uapi/v4l/pixfmt-z16.rst b/Documentation/media/uapi/v4l/pixfmt-z16.rst index eb713a9bccae..eccf235bf02d 100644 --- a/Documentation/media/uapi/v4l/pixfmt-z16.rst +++ b/Documentation/media/uapi/v4l/pixfmt-z16.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _V4L2-PIX-FMT-Z16: diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst index 2aa449e2da67..29be001796db 100644 --- a/Documentation/media/uapi/v4l/pixfmt.rst +++ b/Documentation/media/uapi/v4l/pixfmt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _pixfmt: diff --git a/Documentation/media/uapi/v4l/planar-apis.rst b/Documentation/media/uapi/v4l/planar-apis.rst index 4e059fb44153..a422dc9d592c 100644 --- a/Documentation/media/uapi/v4l/planar-apis.rst +++ b/Documentation/media/uapi/v4l/planar-apis.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _planar-apis: diff --git a/Documentation/media/uapi/v4l/querycap.rst b/Documentation/media/uapi/v4l/querycap.rst index c19cce7a816f..8d01ef52f780 100644 --- a/Documentation/media/uapi/v4l/querycap.rst +++ b/Documentation/media/uapi/v4l/querycap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _querycap: diff --git a/Documentation/media/uapi/v4l/rw.rst b/Documentation/media/uapi/v4l/rw.rst index 91596c0cc2f3..6e498fcf32c4 100644 --- a/Documentation/media/uapi/v4l/rw.rst +++ b/Documentation/media/uapi/v4l/rw.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _rw: diff --git a/Documentation/media/uapi/v4l/sdr-formats.rst b/Documentation/media/uapi/v4l/sdr-formats.rst index 2037f5bad727..f452f5574ebb 100644 --- a/Documentation/media/uapi/v4l/sdr-formats.rst +++ b/Documentation/media/uapi/v4l/sdr-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _sdr-formats: diff --git a/Documentation/media/uapi/v4l/selection-api-configuration.rst b/Documentation/media/uapi/v4l/selection-api-configuration.rst index 0a4ddc2d71db..6e0c98c37067 100644 --- a/Documentation/media/uapi/v4l/selection-api-configuration.rst +++ b/Documentation/media/uapi/v4l/selection-api-configuration.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ************* Configuration diff --git a/Documentation/media/uapi/v4l/selection-api-examples.rst b/Documentation/media/uapi/v4l/selection-api-examples.rst index 67e0e9aed9e8..bb288b06cc17 100644 --- a/Documentation/media/uapi/v4l/selection-api-examples.rst +++ b/Documentation/media/uapi/v4l/selection-api-examples.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ******** Examples diff --git a/Documentation/media/uapi/v4l/selection-api-intro.rst b/Documentation/media/uapi/v4l/selection-api-intro.rst index 09ca93f91bf7..0faed02d0226 100644 --- a/Documentation/media/uapi/v4l/selection-api-intro.rst +++ b/Documentation/media/uapi/v4l/selection-api-intro.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ************ Introduction diff --git a/Documentation/media/uapi/v4l/selection-api-targets.rst b/Documentation/media/uapi/v4l/selection-api-targets.rst index bf7e76dfbdf9..83d633bcbd6f 100644 --- a/Documentation/media/uapi/v4l/selection-api-targets.rst +++ b/Documentation/media/uapi/v4l/selection-api-targets.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections ***************** Selection targets diff --git a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst index e7455fb1e572..79b3abca341a 100644 --- a/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst +++ b/Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _selection-vs-crop: diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst index 390233f704a3..5386004e87cf 100644 --- a/Documentation/media/uapi/v4l/selection-api.rst +++ b/Documentation/media/uapi/v4l/selection-api.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _selection-api: diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg index 911062bd2844..59d2bec9b278 100644 --- a/Documentation/media/uapi/v4l/selection.svg +++ b/Documentation/media/uapi/v4l/selection.svg @@ -1,4 +1,31 @@ <?xml version="1.0" encoding="UTF-8"?> +<!-- + This file is dual-licensed: you can use it either under the terms + of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this + dual licensing only applies to this file, and not this project as a + whole. + + a) This file 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 version 2 of + the License. + + This file 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. + + Or, alternatively, + + b) Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections +--> <svg enable-background="new" version="1" viewBox="0 0 4226.3 1686.8" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> <defs> <pattern id="ig" xlink:href="#ka" patternTransform="matrix(5.4432 0 0 10.1 1722.4 161.06)"/> diff --git a/Documentation/media/uapi/v4l/selections-common.rst b/Documentation/media/uapi/v4l/selections-common.rst index 69dbce4e6e47..28b32db280f2 100644 --- a/Documentation/media/uapi/v4l/selections-common.rst +++ b/Documentation/media/uapi/v4l/selections-common.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-selections-common: diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst index 75a14895aed7..bf8959b72988 100644 --- a/Documentation/media/uapi/v4l/standard.rst +++ b/Documentation/media/uapi/v4l/standard.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _standard: diff --git a/Documentation/media/uapi/v4l/streaming-par.rst b/Documentation/media/uapi/v4l/streaming-par.rst index f9b93c53f75c..425bd0ff1477 100644 --- a/Documentation/media/uapi/v4l/streaming-par.rst +++ b/Documentation/media/uapi/v4l/streaming-par.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _streaming-par: diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst index 8e73fcfc6900..ff4b2a972fd2 100644 --- a/Documentation/media/uapi/v4l/subdev-formats.rst +++ b/Documentation/media/uapi/v4l/subdev-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-mbus-format: diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg index ee1df49f83e8..59321e09929d 100644 --- a/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg +++ b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg @@ -1,4 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg index c10d222b9ea9..e739c54fbbfb 100644 --- a/Documentation/media/uapi/v4l/subdev-image-processing-full.svg +++ b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg @@ -1,4 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg index 3cb68bf9fc04..401d1456958c 100644 --- a/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg +++ b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg @@ -1,4 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" diff --git a/Documentation/media/uapi/v4l/tch-formats.rst b/Documentation/media/uapi/v4l/tch-formats.rst index dbaabf33a5b8..429c1010149d 100644 --- a/Documentation/media/uapi/v4l/tch-formats.rst +++ b/Documentation/media/uapi/v4l/tch-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _tch-formats: diff --git a/Documentation/media/uapi/v4l/tuner.rst b/Documentation/media/uapi/v4l/tuner.rst index ad117b068831..601dc535199c 100644 --- a/Documentation/media/uapi/v4l/tuner.rst +++ b/Documentation/media/uapi/v4l/tuner.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _tuner: @@ -31,7 +38,7 @@ current video or radio input is queried. .. note:: :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` does not switch the - current tuner, when there is more than one at all. The tuner is solely + current tuner, when there is more than one. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct :c:type:`v4l2_capability` returned by the :ref:`VIDIOC_QUERYCAP` ioctl when the @@ -41,7 +48,7 @@ current video or radio input is queried. Modulators ========== -Video output devices can have one or more modulators, uh, modulating a +Video output devices can have one or more modulators, that modulate a video signal for radiation or connection to the antenna input of a TV set or video recorder. Each modulator is associated with one or more video outputs, depending on the number of RF connectors on the diff --git a/Documentation/media/uapi/v4l/user-func.rst b/Documentation/media/uapi/v4l/user-func.rst index 3e0413b83a33..ca0ef21d77fe 100644 --- a/Documentation/media/uapi/v4l/user-func.rst +++ b/Documentation/media/uapi/v4l/user-func.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _user-func: diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst index dc2893a60d65..b19da8655452 100644 --- a/Documentation/media/uapi/v4l/userp.rst +++ b/Documentation/media/uapi/v4l/userp.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _userp: @@ -62,9 +69,9 @@ memory pages at any time between the completion of the DMA and this ioctl. The memory is also unlocked when :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called, :ref:`VIDIOC_REQBUFS`, or when the device is closed. -Applications must take care not to free buffers without dequeuing. For -once, the buffers remain locked until further, wasting physical memory. -Second the driver will not be notified when the memory is returned to +Applications must take care not to free buffers without dequeuing. +Firstly, the buffers remain locked for longer, wasting physical memory. +Secondly the driver will not be notified when the memory is returned to the application's free list and subsequently reused for other purposes, possibly completing the requested DMA and overwriting valuable data. @@ -90,7 +97,7 @@ To start and stop capturing or output applications call the .. note:: - ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both queues and unlocks all buffers as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine diff --git a/Documentation/media/uapi/v4l/v4l2-selection-flags.rst b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst index 1f9a03851d0f..cc8f2a2b7cba 100644 --- a/Documentation/media/uapi/v4l/v4l2-selection-flags.rst +++ b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-selection-flags: diff --git a/Documentation/media/uapi/v4l/v4l2-selection-targets.rst b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst index 87433ec76c6b..f74f239b0510 100644 --- a/Documentation/media/uapi/v4l/v4l2-selection-targets.rst +++ b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2-selection-targets: @@ -42,12 +49,7 @@ of the two interfaces they are used. * - ``V4L2_SEL_TGT_NATIVE_SIZE`` - 0x0003 - The native size of the device, e.g. a sensor's pixel array. - ``left`` and ``top`` fields are zero for this target. Setting the - native size will generally only make sense for memory to memory - devices where the software can create a canvas of a given size in - which for example a video frame can be composed. In that case - V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of - that canvas. + ``left`` and ``top`` fields are zero for this target. - Yes - Yes * - ``V4L2_SEL_TGT_COMPOSE`` diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst index b89e5621ae69..004ec00db6bd 100644 --- a/Documentation/media/uapi/v4l/v4l2.rst +++ b/Documentation/media/uapi/v4l/v4l2.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. include:: <isonum.txt> .. _v4l2spec: diff --git a/Documentation/media/uapi/v4l/v4l2grab-example.rst b/Documentation/media/uapi/v4l/v4l2grab-example.rst index c240f0513bee..2a0cfd4429c1 100644 --- a/Documentation/media/uapi/v4l/v4l2grab-example.rst +++ b/Documentation/media/uapi/v4l/v4l2grab-example.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _v4l2grab-example: diff --git a/Documentation/media/uapi/v4l/v4l2grab.c.rst b/Documentation/media/uapi/v4l/v4l2grab.c.rst index f0d0ab6abd41..e76c5fb7bd19 100644 --- a/Documentation/media/uapi/v4l/v4l2grab.c.rst +++ b/Documentation/media/uapi/v4l/v4l2grab.c.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections file: media/v4l/v4l2grab.c ========================== diff --git a/Documentation/media/uapi/v4l/vbi_525.svg b/Documentation/media/uapi/v4l/vbi_525.svg index 643aec8d0ba2..6cd5def22b1f 100644 --- a/Documentation/media/uapi/v4l/vbi_525.svg +++ b/Documentation/media/uapi/v4l/vbi_525.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -810,4 +818,4 @@ sodipodi:role="line" y="-3648.6809" x="3528.1047 3569.0876 3610.0703 3651.0532 3671.5447 3692.0361 3708.3999 3749.3826 3765.7463">2nd field</tspan></text> -</g></svg>
\ No newline at end of file +</g></svg> diff --git a/Documentation/media/uapi/v4l/vbi_625.svg b/Documentation/media/uapi/v4l/vbi_625.svg index 9b18243c0a06..7aaae5ec4878 100644 --- a/Documentation/media/uapi/v4l/vbi_625.svg +++ b/Documentation/media/uapi/v4l/vbi_625.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -859,4 +867,4 @@ y="-5054.106" sodipodi:role="line" id="tspan4129">24</tspan></text> -</g></svg>
\ No newline at end of file +</g></svg> diff --git a/Documentation/media/uapi/v4l/vbi_hsync.svg b/Documentation/media/uapi/v4l/vbi_hsync.svg index e17ff8314e7b..f8e979ada7e3 100644 --- a/Documentation/media/uapi/v4l/vbi_hsync.svg +++ b/Documentation/media/uapi/v4l/vbi_hsync.svg @@ -1,6 +1,14 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> +<!-- + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation, with no Invariant Sections, no Front-Cover Texts + and no Back-Cover Texts. A copy of the license is included at + Documentation/media/uapi/fdl-appendix.rst. + TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections +--> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" @@ -310,4 +318,4 @@ sodipodi:role="line" y="-395.66284" x="438.29504 457.96585 469.55164 474.17761 479.97049 491.55627 497.34915 508.93494 520.52069 530.93958 542.52533">White Level</tspan></text> -</g></svg>
\ No newline at end of file +</g></svg> diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst index d2bc06b064ad..69603b5efbb5 100644 --- a/Documentation/media/uapi/v4l/video.rst +++ b/Documentation/media/uapi/v4l/video.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _video: @@ -7,7 +14,7 @@ Video Inputs and Outputs ************************ Video inputs and outputs are physical connectors of a device. These can -be for example RF connectors (antenna/cable), CVBS a.k.a. Composite +be for example: RF connectors (antenna/cable), CVBS a.k.a. Composite Video, S-Video and RGB connectors. Camera sensors are also considered to be a video input. Video and VBI capture devices have inputs. Video and VBI output devices have outputs, at least one each. Radio devices have @@ -19,7 +26,7 @@ outputs applications can enumerate them with the :ref:`VIDIOC_ENUMOUTPUT` ioctl, respectively. The struct :c:type:`v4l2_input` returned by the :ref:`VIDIOC_ENUMINPUT` ioctl also contains signal -:status information applicable when the current video input is queried. +status information applicable when the current video input is queried. The :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and :ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctls return the index of diff --git a/Documentation/media/uapi/v4l/videodev.rst b/Documentation/media/uapi/v4l/videodev.rst index b9ee4672d639..fa3d3398930a 100644 --- a/Documentation/media/uapi/v4l/videodev.rst +++ b/Documentation/media/uapi/v4l/videodev.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _videodev: diff --git a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst index a39e18d69511..bd08e4f77ae4 100644 --- a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst +++ b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_CREATE_BUFS: @@ -102,7 +109,19 @@ than the number requested. - ``format`` - Filled in by the application, preserved by the driver. * - __u32 - - ``reserved``\ [8] + - ``capabilities`` + - Set by the driver. If 0, then the driver doesn't support + capabilities. In that case all you know is that the driver is + guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support + other :c:type:`v4l2_memory` types. It will not support any others + capabilities. See :ref:`here <v4l2-buf-capabilities>` for a list of the + capabilities. + + If you want to just query the capabilities without making any + other changes, then set ``count`` to 0, ``memory`` to + ``V4L2_MEMORY_MMAP`` and ``format.type`` to the buffer type. + * - __u32 + - ``reserved``\ [7] - A place holder for future extensions. Drivers and applications must set the array to zero. diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst index a65dbec6b20b..019d3d3a0e0d 100644 --- a/Documentation/media/uapi/v4l/vidioc-cropcap.rst +++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_CROPCAP: @@ -58,7 +65,7 @@ overlay devices. - Type of the data stream, set by the application. Only these types are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above. + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below. * - struct :ref:`v4l2_rect <v4l2-rect-crop>` - ``bounds`` - Defines the window within capturing or output is possible, this diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst index 7709852282c2..a1cf20181cf1 100644 --- a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_DBG_G_CHIP_INFO: diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst index f4e8dd5f7889..29e1d4fc4f52 100644 --- a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst +++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_DBG_G_REGISTER: diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst index 85c916b0ce07..ccf83b05afa7 100644 --- a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst +++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_DECODER_CMD: diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst index cb3565f36793..dea9c0cc00ab 100644 --- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst +++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_DQEVENT: @@ -379,7 +386,17 @@ call. - 0x0001 - This event gets triggered when a resolution change is detected at an input. This can come from an input connector or from a video - decoder. + decoder. Applications will have to query the new resolution (if + any, the signal may also have been lost). + + *Important*: even if the new video timings appear identical to the old + ones, receiving this event indicates that there was an issue with the + video signal and you must stop and restart streaming + (:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` + followed by :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`). The reason is + that many devices are not able to recover from a temporary loss of + signal and so restarting streaming I/O is required in order for the + hardware to synchronize to the video signal. Return Value diff --git a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst index 63ead6b7a115..e62d45d37072 100644 --- a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst +++ b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_DV_TIMINGS_CAP: diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst index 5ae8c933b1b9..c313ca8b8cb5 100644 --- a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst +++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENCODER_CMD: diff --git a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst index 63dca65f49e4..0b286e19b46b 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUM_DV_TIMINGS: diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst index 019c513df217..822d6730e7d2 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUM_FMT: @@ -64,8 +71,12 @@ one until ``EINVAL`` is returned. are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type`. + ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``, + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, + ``V4L2_BUF_TYPE_SDR_CAPTURE``, + ``V4L2_BUF_TYPE_SDR_OUTPUT`` and + ``V4L2_BUF_TYPE_META_CAPTURE``. + See :c:type:`v4l2_buf_type`. * - __u32 - ``flags`` - See :ref:`fmtdesc-flags` diff --git a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst index fea7dc3c879d..2c69f26b165d 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUM_FRAMEINTERVALS: diff --git a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst index 6de117f163e0..cf31f548826f 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUM_FRAMESIZES: diff --git a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst index 195cf45f3c32..0e97c09afe0e 100644 --- a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst +++ b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUM_FREQ_BANDS: diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudio.rst b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst index 8e5193e8696f..ee0c336c8721 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumaudio.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUMAUDIO: diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst index 6d2b4f6e78b0..3a8882214d62 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUMAUDOUT: diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst index 0350069a56c5..a0e4c4413121 100644 --- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUMINPUT: diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst index 697dcd186ae3..0fea81f60541 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUMOUTPUT: diff --git a/Documentation/media/uapi/v4l/vidioc-enumstd.rst b/Documentation/media/uapi/v4l/vidioc-enumstd.rst index 2644a62acd4b..1603b1b3b6e8 100644 --- a/Documentation/media/uapi/v4l/vidioc-enumstd.rst +++ b/Documentation/media/uapi/v4l/vidioc-enumstd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_ENUMSTD: diff --git a/Documentation/media/uapi/v4l/vidioc-expbuf.rst b/Documentation/media/uapi/v4l/vidioc-expbuf.rst index 226e83eb28a9..4bd8cd79754c 100644 --- a/Documentation/media/uapi/v4l/vidioc-expbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-expbuf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_EXPBUF: diff --git a/Documentation/media/uapi/v4l/vidioc-g-audio.rst b/Documentation/media/uapi/v4l/vidioc-g-audio.rst index 290851f99386..7af4fe478ba4 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-audio.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-audio.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_AUDIO: diff --git a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst index 1c98af33ee70..c6ea0396a96a 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_AUDOUT: diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst index a6ed43ba9ca3..1eff59dc5f35 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-crop.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_CROP: @@ -84,7 +91,7 @@ When cropping is not supported then no parameters are changed and - Type of the data stream, set by the application. Only these types are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``, ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note above. + ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :c:type:`v4l2_buf_type` and the note below. * - struct :c:type:`v4l2_rect` - ``c`` - Cropping rectangle. The same co-ordinate system as for struct diff --git a/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst index 299b9aabbac2..8493b52adbb2 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_CTRL: diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst index 1a034e825161..5712bd48e687 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_DV_TIMINGS: @@ -257,14 +264,19 @@ EBUSY will also be cleared. This is a read-only flag, applications must not set this. * - ``V4L2_DV_FL_REDUCED_FPS`` - - CEA-861 specific: only valid for video transmitters, the flag is - cleared by receivers. It is also only valid for formats with the - ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the - flag will be cleared by the driver. If the application sets this - flag, then the pixelclock used to set up the transmitter is - divided by 1.001 to make it compatible with NTSC framerates. If - the transmitter can't generate such frequencies, then the flag - will also be cleared. + - CEA-861 specific: only valid for video transmitters or video + receivers that have the ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS`` + set. This flag is cleared otherwise. It is also only valid for + formats with the ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other + formats the flag will be cleared by the driver. + + If the application sets this flag for a transmitter, then the + pixelclock used to set up the transmitter is divided by 1.001 to + make it compatible with NTSC framerates. If the transmitter can't + generate such frequencies, then the flag will be cleared. + + If a video receiver detects that the format uses a reduced framerate, + then it will set this flag to signal this to the application. * - ``V4L2_DV_FL_HALF_LINE`` - Specific to interlaced formats: if set, then the vertical backporch of field 1 (aka the odd field) is really one half-line @@ -294,3 +306,9 @@ EBUSY - If set, then the hdmi_vic field is valid and contains the Video Identification Code as per the HDMI standard (HDMI Vendor Specific InfoFrame). + * - ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS`` + - CEA-861 specific: only valid for video receivers, the flag is + cleared by transmitters. + If set, then the hardware can detect the difference between + regular framerates and framerates reduced by 1000/1001. E.g.: + 60 vs 59.94 Hz, 30 vs 29.97 Hz or 24 vs 23.976 Hz. diff --git a/Documentation/media/uapi/v4l/vidioc-g-edid.rst b/Documentation/media/uapi/v4l/vidioc-g-edid.rst index acab90f06e5a..e55b349a0c7e 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-edid.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-edid.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_EDID: diff --git a/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst index 9dfe64fc21a4..e285a1f14cdf 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_ENC_INDEX: diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst index 2011c2b2ee67..13dc1a986249 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_EXT_CTRLS: @@ -95,6 +102,25 @@ appropriate. In the first case the new value is set in struct is inappropriate (e.g. the given menu index is not supported by the menu control), then this will also result in an ``EINVAL`` error code error. +If ``request_fd`` is set to a not-yet-queued :ref:`request <media-request-api>` +file descriptor and ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``, +then the controls are not applied immediately when calling +:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, but instead are applied by +the driver for the buffer associated with the same request. +If the device does not support requests, then ``EACCES`` will be returned. +If requests are supported but an invalid request file descriptor is given, +then ``EINVAL`` will be returned. + +An attempt to call :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` for a +request that has already been queued will result in an ``EBUSY`` error. + +If ``request_fd`` is specified and ``which`` is set to +``V4L2_CTRL_WHICH_REQUEST_VAL`` during a call to +:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then it will return the +values of the controls at the time of request completion. +If the request is not yet completed, then this will result in an +``EACCES`` error. + The driver will only set/get these controls if all control values are correct. This prevents the situation where only some of the controls were set/get. Only low-level errors (e. g. a failed i2c command) can @@ -209,13 +235,17 @@ still cause this situation. - ``which`` - Which value of the control to get/set/try. ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the - control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default - value of the control. + control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default + value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that + these controls have to be retrieved from a request or tried/set for + a request. In the latter case the ``request_fd`` field contains the + file descriptor of the request that should be used. If the device + does not support requests, then ``EACCES`` will be returned. .. note:: - You can only get the default value of the control, - you cannot set or try it. + When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware that you can only + get the default value of the control, you cannot set or try it. For backwards compatibility you can also use a control class here (see :ref:`ctrl-class`). In that case all controls have to @@ -272,8 +302,15 @@ still cause this situation. then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the actual control that failed the validation step. Unfortunately, there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. + * - __s32 + - ``request_fd`` + - File descriptor of the request to be used by this operation. Only + valid if ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``. + If the device does not support requests, then ``EACCES`` will be returned. + If requests are supported but an invalid request file descriptor is + given, then ``EINVAL`` will be returned. * - __u32 - - ``reserved``\ [2] + - ``reserved``\ [1] - Reserved for future extensions. Drivers and applications must set the array to zero. @@ -347,11 +384,14 @@ appropriately. The generic error codes are described at the EINVAL The struct :c:type:`v4l2_ext_control` ``id`` is - invalid, the struct :c:type:`v4l2_ext_controls` + invalid, or the struct :c:type:`v4l2_ext_controls` ``which`` is invalid, or the struct :c:type:`v4l2_ext_control` ``value`` was inappropriate (e.g. the given menu index is not supported by the - driver). This error code is also returned by the + driver), or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` + but the given ``request_fd`` was invalid or ``V4L2_CTRL_WHICH_REQUEST_VAL`` + is not supported by the kernel. + This error code is also returned by the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or more control values are in conflict. @@ -362,7 +402,9 @@ ERANGE EBUSY The control is temporarily not changeable, possibly because another applications took over control of the device function this control - belongs to. + belongs to, or (if the ``which`` field was set to + ``V4L2_CTRL_WHICH_REQUEST_VAL``) the request was queued but not yet + completed. ENOSPC The space reserved for the control's payload is insufficient. The @@ -370,5 +412,9 @@ ENOSPC and this error code is returned. EACCES - Attempt to try or set a read-only control or to get a write-only - control. + Attempt to try or set a read-only control, or to get a write-only + control, or to get a control from a request that has not yet been + completed. + + Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the + device does not support requests. diff --git a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst index fc73bf0f6052..7b6179627803 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_FBUF: diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst index 3ead350e099f..e35a9caff652 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_FMT: @@ -133,6 +140,11 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical - Definition of a data format, see :ref:`pixfmt`, used by SDR capture and output devices. * - + - struct :c:type:`v4l2_meta_format` + - ``meta`` + - Definition of a metadata format, see :ref:`meta-formats`, used by + metadata capture devices. + * - - __u8 - ``raw_data``\ [200] - Place holder for future extensions. diff --git a/Documentation/media/uapi/v4l/vidioc-g-frequency.rst b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst index c1cccb144660..cc30bae3dd6e 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-frequency.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_FREQUENCY: diff --git a/Documentation/media/uapi/v4l/vidioc-g-input.rst b/Documentation/media/uapi/v4l/vidioc-g-input.rst index 1dcef44eef02..76b7d487466e 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-input.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-input.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_INPUT: diff --git a/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst index a1773ea9543e..5480277ab327 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_JPEGCOMP: diff --git a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst index a47b6a15cfbe..2c33a8bdcc47 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_MODULATOR: diff --git a/Documentation/media/uapi/v4l/vidioc-g-output.rst b/Documentation/media/uapi/v4l/vidioc-g-output.rst index 3e0093f66834..69542d78977b 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-output.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-output.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_OUTPUT: diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst index e831fa5512f0..0d2593176c90 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-parm.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_PARM: @@ -42,6 +49,9 @@ side. This is especially useful when using the :ref:`read() <func-read>` or :ref:`write() <func-write>`, which are not augmented by timestamps or sequence counters, and to avoid unnecessary data copying. +Changing the frame interval shall never change the format. Changing the +format, on the other hand, may change the frame interval. + Further these ioctls can be used to determine the number of buffers used internally by a driver in read/write mode. For implications see the section discussing the :ref:`read() <func-read>` function. diff --git a/Documentation/media/uapi/v4l/vidioc-g-priority.rst b/Documentation/media/uapi/v4l/vidioc-g-priority.rst index c28996b4a45c..244b4dbe9df3 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-priority.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-priority.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_PRIORITY: diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst index f1d9df029e0d..7d8ef7ac8e27 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_SELECTION: diff --git a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst index a9633cae76c5..388b826d44b3 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_SLICED_VBI_CAP: diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst index 8d94f0404df2..e633e42e3910 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-std.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_STD: diff --git a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst index acdd15901a51..82d23b8bd195 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_G_TUNER: diff --git a/Documentation/media/uapi/v4l/vidioc-log-status.rst b/Documentation/media/uapi/v4l/vidioc-log-status.rst index bbeb7b5f516b..16bb5509ad66 100644 --- a/Documentation/media/uapi/v4l/vidioc-log-status.rst +++ b/Documentation/media/uapi/v4l/vidioc-log-status.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_LOG_STATUS: diff --git a/Documentation/media/uapi/v4l/vidioc-overlay.rst b/Documentation/media/uapi/v4l/vidioc-overlay.rst index 1383e3db25fc..fc5a86e8c1f2 100644 --- a/Documentation/media/uapi/v4l/vidioc-overlay.rst +++ b/Documentation/media/uapi/v4l/vidioc-overlay.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_OVERLAY: diff --git a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst index 49f9f4c181de..60986710967b 100644 --- a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst +++ b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_PREPARE_BUF: diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst index 9e448a4aa3aa..3259168a7358 100644 --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QBUF: @@ -65,7 +72,7 @@ To enqueue a :ref:`memory mapped <mmap>` buffer applications set the with a pointer to this structure the driver sets the ``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an -EINVAL error code. +``EINVAL`` error code. To enqueue a :ref:`user pointer <userp>` buffer applications set the ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to @@ -98,6 +105,28 @@ dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or :ref:`VIDIOC_REQBUFS` ioctl is called, or until the device is closed. +The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to specify +the file descriptor of a :ref:`request <media-request-api>`, if requests are +in use. Setting it means that the buffer will not be passed to the driver +until the request itself is queued. Also, the driver will apply any +settings associated with the request for this buffer. This field will +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. +If the device does not support requests, then ``EACCES`` will be returned. +If requests are supported but an invalid request file descriptor is given, +then ``EINVAL`` will be returned. + +.. caution:: + It is not allowed to mix queuing requests with queuing buffers directly. + ``EBUSY`` will be returned if the first buffer was queued directly and + then the application tries to queue a request, or vice versa. After + closing the file descriptor, calling + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_REQBUFS` + the check for this will be reset. + + For :ref:`memory-to-memory devices <codec>` you can specify the + ``request_fd`` only for output buffers, not for capture buffers. Attempting + to specify this for a capture buffer will result in an ``EACCES`` error. + Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled (capturing) or displayed (output) buffer from the driver's outgoing queue. They just set the ``type``, ``memory`` and ``reserved`` fields of @@ -133,7 +162,9 @@ EAGAIN EINVAL The buffer ``type`` is not supported, or the ``index`` is out of bounds, or no buffers have been allocated yet, or the ``userptr`` or - ``length`` are invalid. + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was + set but the the given ``request_fd`` was invalid, or ``m.fd`` was + an invalid DMABUF file descriptor. EIO ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate @@ -153,3 +184,12 @@ EPIPE ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already dequeued and no new buffers are expected to become available. + +EACCES + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not + support requests for the given buffer type. + +EBUSY + The first buffer was queued via a request, but the application now tries + to queue it directly, or vice versa (it is not permitted to mix the two + APIs). diff --git a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst index 6c82eafd28bb..e9b055395382 100644 --- a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst +++ b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QUERY_DV_TIMINGS: diff --git a/Documentation/media/uapi/v4l/vidioc-querybuf.rst b/Documentation/media/uapi/v4l/vidioc-querybuf.rst index dd54747fabc9..7da60b24e8b6 100644 --- a/Documentation/media/uapi/v4l/vidioc-querybuf.rst +++ b/Documentation/media/uapi/v4l/vidioc-querybuf.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QUERYBUF: diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst index 66fb1b3d6e6e..5f9930195d62 100644 --- a/Documentation/media/uapi/v4l/vidioc-querycap.rst +++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QUERYCAP: @@ -251,6 +258,9 @@ specification the ioctl returns an ``EINVAL`` error code. * - ``V4L2_CAP_STREAMING`` - 0x04000000 - The device supports the :ref:`streaming <mmap>` I/O method. + * - ``V4L2_CAP_META_OUTPUT`` + - 0x08000000 + - The device supports the :ref:`metadata` output interface. * - ``V4L2_CAP_TOUCH`` - 0x10000000 - This is a touch device. diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index 5bd26e8c9a1a..f824162d0ea9 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QUERYCTRL: @@ -424,8 +431,18 @@ See also the examples in :ref:`control`. - any - An unsigned 32-bit valued control ranging from minimum to maximum inclusive. The step value indicates the increment between values. - - + * - ``V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_mpeg2_slice_params`, containing MPEG-2 + slice parameters for stateless video decoders. + * - ``V4L2_CTRL_TYPE_MPEG2_QUANTIZATION`` + - n/a + - n/a + - n/a + - A struct :c:type:`v4l2_ctrl_mpeg2_quantization`, containing MPEG-2 + quantization matrices for stateless video decoders. .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| diff --git a/Documentation/media/uapi/v4l/vidioc-querystd.rst b/Documentation/media/uapi/v4l/vidioc-querystd.rst index a8385cc74818..d8cf28274cfc 100644 --- a/Documentation/media/uapi/v4l/vidioc-querystd.rst +++ b/Documentation/media/uapi/v4l/vidioc-querystd.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_QUERYSTD: diff --git a/Documentation/media/uapi/v4l/vidioc-reqbufs.rst b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst index 316f52c8a310..d7faef10e39b 100644 --- a/Documentation/media/uapi/v4l/vidioc-reqbufs.rst +++ b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_REQBUFS: @@ -59,9 +66,14 @@ When the I/O method is not supported the ioctl returns an ``EINVAL`` error code. Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of -buffers, however this cannot succeed when any buffers are still mapped. -A ``count`` value of zero frees all buffers, after aborting or finishing -any DMA in progress, an implicit +buffers. Note that if any buffers are still mapped or exported via DMABUF, +then :ref:`VIDIOC_REQBUFS` can only succeed if the +``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` capability is set. Otherwise +:ref:`VIDIOC_REQBUFS` will return the ``EBUSY`` error code. +If ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` is set, then these buffers are +orphaned and will be freed when they are unmapped or when the exported DMABUF +fds are closed. A ``count`` value of zero frees or orphans all buffers, after +aborting or finishing any DMA in progress, an implicit :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`. @@ -88,10 +100,56 @@ any DMA in progress, an implicit ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See :c:type:`v4l2_memory`. * - __u32 - - ``reserved``\ [2] + - ``capabilities`` + - Set by the driver. If 0, then the driver doesn't support + capabilities. In that case all you know is that the driver is + guaranteed to support ``V4L2_MEMORY_MMAP`` and *might* support + other :c:type:`v4l2_memory` types. It will not support any others + capabilities. + + If you want to query the capabilities with a minimum of side-effects, + then this can be called with ``count`` set to 0, ``memory`` set to + ``V4L2_MEMORY_MMAP`` and ``type`` set to the buffer type. This will + free any previously allocated buffers, so this is typically something + that will be done at the start of the application. + * - __u32 + - ``reserved``\ [1] - A place holder for future extensions. Drivers and applications must set the array to zero. +.. tabularcolumns:: |p{6.1cm}|p{2.2cm}|p{8.7cm}| + +.. _v4l2-buf-capabilities: +.. _V4L2-BUF-CAP-SUPPORTS-MMAP: +.. _V4L2-BUF-CAP-SUPPORTS-USERPTR: +.. _V4L2-BUF-CAP-SUPPORTS-DMABUF: +.. _V4L2-BUF-CAP-SUPPORTS-REQUESTS: +.. _V4L2-BUF-CAP-SUPPORTS-ORPHANED-BUFS: + +.. cssclass:: longtable + +.. flat-table:: V4L2 Buffer Capabilities Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_BUF_CAP_SUPPORTS_MMAP`` + - 0x00000001 + - This buffer type supports the ``V4L2_MEMORY_MMAP`` streaming mode. + * - ``V4L2_BUF_CAP_SUPPORTS_USERPTR`` + - 0x00000002 + - This buffer type supports the ``V4L2_MEMORY_USERPTR`` streaming mode. + * - ``V4L2_BUF_CAP_SUPPORTS_DMABUF`` + - 0x00000004 + - This buffer type supports the ``V4L2_MEMORY_DMABUF`` streaming mode. + * - ``V4L2_BUF_CAP_SUPPORTS_REQUESTS`` + - 0x00000008 + - This buffer type supports :ref:`requests <media-request-api>`. + * - ``V4L2_BUF_CAP_SUPPORTS_ORPHANED_BUFS`` + - 0x00000010 + - The kernel allows calling :ref:`VIDIOC_REQBUFS` while buffers are still + mapped or exported via DMABUF. These orphaned buffers will be freed + when they are unmapped or when the exported DMABUF fds are closed. Return Value ============ diff --git a/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst index b318cb8e1df3..4daec97651f2 100644 --- a/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst +++ b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_S_HW_FREQ_SEEK: diff --git a/Documentation/media/uapi/v4l/vidioc-streamon.rst b/Documentation/media/uapi/v4l/vidioc-streamon.rst index e851a6961b78..2b5528ec9f89 100644 --- a/Documentation/media/uapi/v4l/vidioc-streamon.rst +++ b/Documentation/media/uapi/v4l/vidioc-streamon.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_STREAMON: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst index 1bfe3865dcc2..6b4bf9ef5606 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst index 33fdc3ac9316..253b128b194e 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst index 4e4291798e4b..fefe4d7349ee 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_ENUM_MBUS_CODE: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst index 69b2ae8e7c15..632ee053accc 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_G_CROP: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst index 81c5d331af9a..472577bd1745 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_G_FMT: diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst index 5af0a7179941..4b1b4bc78bfe 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_G_FRAME_INTERVAL: @@ -63,6 +70,9 @@ doesn't match the device capabilities. They must instead modify the interval to match what the hardware can provide. The modified interval should be as close as possible to the original request. +Changing the frame interval shall never change the format. Changing the +format, on the other hand, may change the frame interval. + Sub-devices that support the frame interval ioctls should implement them on a single pad only. Their behaviour when supported on multiple pads of the same sub-device is not defined. diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst index b1d3dbbef42a..fc73d27e6d74 100644 --- a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst +++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBDEV_G_SELECTION: diff --git a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst index b521efa53ceb..a2d3454555ba 100644 --- a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst +++ b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _VIDIOC_SUBSCRIBE_EVENT: .. _VIDIOC_UNSUBSCRIBE_EVENT: diff --git a/Documentation/media/uapi/v4l/yuv-formats.rst b/Documentation/media/uapi/v4l/yuv-formats.rst index 9ab0592d08da..867470e5f9e1 100644 --- a/Documentation/media/uapi/v4l/yuv-formats.rst +++ b/Documentation/media/uapi/v4l/yuv-formats.rst @@ -1,4 +1,11 @@ -.. -*- coding: utf-8; mode: rst -*- +.. Permission is granted to copy, distribute and/or modify this +.. document under the terms of the GNU Free Documentation License, +.. Version 1.1 or any later version published by the Free Software +.. Foundation, with no Invariant Sections, no Front-Cover Texts +.. and no Back-Cover Texts. A copy of the license is included at +.. Documentation/media/uapi/fdl-appendix.rst. +.. +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections .. _yuv-formats: diff --git a/Documentation/media/v4l-drivers/au0828-cardlist.rst b/Documentation/media/v4l-drivers/au0828-cardlist.rst index bb87b7b36a83..aaaadc934e7a 100644 --- a/Documentation/media/v4l-drivers/au0828-cardlist.rst +++ b/Documentation/media/v4l-drivers/au0828-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + AU0828 cards list ================= diff --git a/Documentation/media/v4l-drivers/bttv-cardlist.rst b/Documentation/media/v4l-drivers/bttv-cardlist.rst index 8da27b924e01..f5806856b5a1 100644 --- a/Documentation/media/v4l-drivers/bttv-cardlist.rst +++ b/Documentation/media/v4l-drivers/bttv-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + BTTV cards list =============== diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index 5f35e2fb5afa..d72a0f8fd267 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The bttv driver =============== diff --git a/Documentation/media/v4l-drivers/cafe_ccic.rst b/Documentation/media/v4l-drivers/cafe_ccic.rst index 94f0f58ebe37..ff7fbce1342a 100644 --- a/Documentation/media/v4l-drivers/cafe_ccic.rst +++ b/Documentation/media/v4l-drivers/cafe_ccic.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The cafe_ccic driver ==================== diff --git a/Documentation/media/v4l-drivers/cardlist.rst b/Documentation/media/v4l-drivers/cardlist.rst index 8a0728d20684..14249f47fbc2 100644 --- a/Documentation/media/v4l-drivers/cardlist.rst +++ b/Documentation/media/v4l-drivers/cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Cards List ========== diff --git a/Documentation/media/v4l-drivers/cpia2.rst b/Documentation/media/v4l-drivers/cpia2.rst index b5125016cfcb..a86baa1c83f1 100644 --- a/Documentation/media/v4l-drivers/cpia2.rst +++ b/Documentation/media/v4l-drivers/cpia2.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The cpia2 driver ================ diff --git a/Documentation/media/v4l-drivers/cx18.rst b/Documentation/media/v4l-drivers/cx18.rst index afa03f65b01c..16895a734bae 100644 --- a/Documentation/media/v4l-drivers/cx18.rst +++ b/Documentation/media/v4l-drivers/cx18.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The cx18 driver =============== diff --git a/Documentation/media/v4l-drivers/cx2341x.rst b/Documentation/media/v4l-drivers/cx2341x.rst index e06d07ebdecd..8ca37deb56b6 100644 --- a/Documentation/media/v4l-drivers/cx2341x.rst +++ b/Documentation/media/v4l-drivers/cx2341x.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The cx2341x driver ================== diff --git a/Documentation/media/v4l-drivers/cx23885-cardlist.rst b/Documentation/media/v4l-drivers/cx23885-cardlist.rst index 8c24df8e0423..ddff8da98eeb 100644 --- a/Documentation/media/v4l-drivers/cx23885-cardlist.rst +++ b/Documentation/media/v4l-drivers/cx23885-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + cx23885 cards list ================== diff --git a/Documentation/media/v4l-drivers/cx88-cardlist.rst b/Documentation/media/v4l-drivers/cx88-cardlist.rst index 21648b8c2e83..56ee08028106 100644 --- a/Documentation/media/v4l-drivers/cx88-cardlist.rst +++ b/Documentation/media/v4l-drivers/cx88-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + CX88 cards list =============== diff --git a/Documentation/media/v4l-drivers/cx88.rst b/Documentation/media/v4l-drivers/cx88.rst index d8f3a014726a..698c73ea2e36 100644 --- a/Documentation/media/v4l-drivers/cx88.rst +++ b/Documentation/media/v4l-drivers/cx88.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The cx88 driver =============== diff --git a/Documentation/media/v4l-drivers/davinci-vpbe.rst b/Documentation/media/v4l-drivers/davinci-vpbe.rst index b545fe001919..0fde433e5c71 100644 --- a/Documentation/media/v4l-drivers/davinci-vpbe.rst +++ b/Documentation/media/v4l-drivers/davinci-vpbe.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The VPBE V4L2 driver design =========================== diff --git a/Documentation/media/v4l-drivers/em28xx-cardlist.rst b/Documentation/media/v4l-drivers/em28xx-cardlist.rst index dfe882ca945f..2956cbdc28e0 100644 --- a/Documentation/media/v4l-drivers/em28xx-cardlist.rst +++ b/Documentation/media/v4l-drivers/em28xx-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + EM28xx cards list ================= @@ -233,7 +235,7 @@ EM28xx cards list - em2882 - eb1a:e323 * - 55 - - Terratec Cinnergy Hybrid T USB XS (em2882) + - Terratec Cinergy Hybrid T USB XS (em2882) - em2882 - 0ccd:005e, 0ccd:0042 * - 56 diff --git a/Documentation/media/v4l-drivers/fimc.rst b/Documentation/media/v4l-drivers/fimc.rst index 3adc19bcf039..74585ba48b7f 100644 --- a/Documentation/media/v4l-drivers/fimc.rst +++ b/Documentation/media/v4l-drivers/fimc.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> The Samsung S5P/EXYNOS4 FIMC driver diff --git a/Documentation/media/v4l-drivers/fourcc.rst b/Documentation/media/v4l-drivers/fourcc.rst index 9c82106e8a26..d3482c40da62 100644 --- a/Documentation/media/v4l-drivers/fourcc.rst +++ b/Documentation/media/v4l-drivers/fourcc.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Guidelines for Video4Linux pixel format 4CCs ============================================ diff --git a/Documentation/media/v4l-drivers/gspca-cardlist.rst b/Documentation/media/v4l-drivers/gspca-cardlist.rst index e18d87e80d78..adda933616f1 100644 --- a/Documentation/media/v4l-drivers/gspca-cardlist.rst +++ b/Documentation/media/v4l-drivers/gspca-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The gspca cards list ==================== diff --git a/Documentation/media/v4l-drivers/imx.rst b/Documentation/media/v4l-drivers/imx.rst index 65d3d15eb159..6922dde4a82b 100644 --- a/Documentation/media/v4l-drivers/imx.rst +++ b/Documentation/media/v4l-drivers/imx.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + i.MX Video Capture Driver ========================= diff --git a/Documentation/media/v4l-drivers/index.rst b/Documentation/media/v4l-drivers/index.rst index 679238e786a7..f28570ec9e42 100644 --- a/Documentation/media/v4l-drivers/index.rst +++ b/Documentation/media/v4l-drivers/index.rst @@ -1,4 +1,4 @@ -.. -*- coding: utf-8; mode: rst -*- +.. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> @@ -44,6 +44,7 @@ For more details see the file COPYING in the source distribution of Linux. davinci-vpbe fimc imx + ipu3 ivtv max2175 meye diff --git a/Documentation/media/v4l-drivers/ipu3.rst b/Documentation/media/v4l-drivers/ipu3.rst new file mode 100644 index 000000000000..f89b51dafadd --- /dev/null +++ b/Documentation/media/v4l-drivers/ipu3.rst @@ -0,0 +1,369 @@ +.. include:: <isonum.txt> + +=============================================================== +Intel Image Processing Unit 3 (IPU3) Imaging Unit (ImgU) driver +=============================================================== + +Copyright |copy| 2018 Intel Corporation + +Introduction +============ + +This file documents the Intel IPU3 (3rd generation Image Processing Unit) +Imaging Unit drivers located under drivers/media/pci/intel/ipu3 (CIO2) as well +as under drivers/staging/media/ipu3 (ImgU). + +The Intel IPU3 found in certain Kaby Lake (as well as certain Sky Lake) +platforms (U/Y processor lines) is made up of two parts namely the Imaging Unit +(ImgU) and the CIO2 device (MIPI CSI2 receiver). + +The CIO2 device receives the raw Bayer data from the sensors and outputs the +frames in a format that is specific to the IPU3 (for consumption by the IPU3 +ImgU). The CIO2 driver is available as drivers/media/pci/intel/ipu3/ipu3-cio2* +and is enabled through the CONFIG_VIDEO_IPU3_CIO2 config option. + +The Imaging Unit (ImgU) is responsible for processing images captured +by the IPU3 CIO2 device. The ImgU driver sources can be found under +drivers/staging/media/ipu3 directory. The driver is enabled through the +CONFIG_VIDEO_IPU3_IMGU config option. + +The two driver modules are named ipu3_csi2 and ipu3_imgu, respectively. + +The drivers has been tested on Kaby Lake platforms (U/Y processor lines). + +Both of the drivers implement V4L2, Media Controller and V4L2 sub-device +interfaces. The IPU3 CIO2 driver supports camera sensors connected to the CIO2 +MIPI CSI-2 interfaces through V4L2 sub-device sensor drivers. + +CIO2 +==== + +The CIO2 is represented as a single V4L2 subdev, which provides a V4L2 subdev +interface to the user space. There is a video node for each CSI-2 receiver, +with a single media controller interface for the entire device. + +The CIO2 contains four independent capture channel, each with its own MIPI CSI-2 +receiver and DMA engine. Each channel is modelled as a V4L2 sub-device exposed +to userspace as a V4L2 sub-device node and has two pads: + +.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}| + +.. flat-table:: + + * - pad + - direction + - purpose + + * - 0 + - sink + - MIPI CSI-2 input, connected to the sensor subdev + + * - 1 + - source + - Raw video capture, connected to the V4L2 video interface + +The V4L2 video interfaces model the DMA engines. They are exposed to userspace +as V4L2 video device nodes. + +Capturing frames in raw Bayer format +------------------------------------ + +CIO2 MIPI CSI2 receiver is used to capture frames (in packed raw Bayer format) +from the raw sensors connected to the CSI2 ports. The captured frames are used +as input to the ImgU driver. + +Image processing using IPU3 ImgU requires tools such as raw2pnm [#f1]_, and +yavta [#f2]_ due to the following unique requirements and / or features specific +to IPU3. + +-- The IPU3 CSI2 receiver outputs the captured frames from the sensor in packed +raw Bayer format that is specific to IPU3. + +-- Multiple video nodes have to be operated simultaneously. + +Let us take the example of ov5670 sensor connected to CSI2 port 0, for a +2592x1944 image capture. + +Using the media contorller APIs, the ov5670 sensor is configured to send +frames in packed raw Bayer format to IPU3 CSI2 receiver. + +# This example assumes /dev/media0 as the CIO2 media device + +export MDEV=/dev/media0 + +# and that ov5670 sensor is connected to i2c bus 10 with address 0x36 + +export SDEV=$(media-ctl -d $MDEV -e "ov5670 10-0036") + +# Establish the link for the media devices using media-ctl [#f3]_ +media-ctl -d $MDEV -l "ov5670:0 -> ipu3-csi2 0:0[1]" + +# Set the format for the media devices +media-ctl -d $MDEV -V "ov5670:0 [fmt:SGRBG10/2592x1944]" + +media-ctl -d $MDEV -V "ipu3-csi2 0:0 [fmt:SGRBG10/2592x1944]" + +media-ctl -d $MDEV -V "ipu3-csi2 0:1 [fmt:SGRBG10/2592x1944]" + +Once the media pipeline is configured, desired sensor specific settings +(such as exposure and gain settings) can be set, using the yavta tool. + +e.g + +yavta -w 0x009e0903 444 $SDEV + +yavta -w 0x009e0913 1024 $SDEV + +yavta -w 0x009e0911 2046 $SDEV + +Once the desired sensor settings are set, frame captures can be done as below. + +e.g + +yavta --data-prefix -u -c10 -n5 -I -s2592x1944 --file=/tmp/frame-#.bin \ + -f IPU3_SGRBG10 $(media-ctl -d $MDEV -e "ipu3-cio2 0") + +With the above command, 10 frames are captured at 2592x1944 resolution, with +sGRBG10 format and output as IPU3_SGRBG10 format. + +The captured frames are available as /tmp/frame-#.bin files. + +ImgU +==== + +The ImgU is represented as two V4L2 subdevs, each of which provides a V4L2 +subdev interface to the user space. + +Each V4L2 subdev represents a pipe, which can support a maximum of 2 streams. +This helps to support advanced camera features like Continuous View Finder (CVF) +and Snapshot During Video(SDV). + +The ImgU contains two independent pipes, each modelled as a V4L2 sub-device +exposed to userspace as a V4L2 sub-device node. + +Each pipe has two sink pads and three source pads for the following purpose: + +.. tabularcolumns:: |p{0.8cm}|p{4.0cm}|p{4.0cm}| + +.. flat-table:: + + * - pad + - direction + - purpose + + * - 0 + - sink + - Input raw video stream + + * - 1 + - sink + - Processing parameters + + * - 2 + - source + - Output processed video stream + + * - 3 + - source + - Output viewfinder video stream + + * - 4 + - source + - 3A statistics + +Each pad is connected to a corresponding V4L2 video interface, exposed to +userspace as a V4L2 video device node. + +Device operation +---------------- + +With ImgU, once the input video node ("ipu3-imgu 0/1":0, in +<entity>:<pad-number> format) is queued with buffer (in packed raw Bayer +format), ImgU starts processing the buffer and produces the video output in YUV +format and statistics output on respective output nodes. The driver is expected +to have buffers ready for all of parameter, output and statistics nodes, when +input video node is queued with buffer. + +At a minimum, all of input, main output, 3A statistics and viewfinder +video nodes should be enabled for IPU3 to start image processing. + +Each ImgU V4L2 subdev has the following set of video nodes. + +input, output and viewfinder video nodes +---------------------------------------- + +The frames (in packed raw Bayer format specific to the IPU3) received by the +input video node is processed by the IPU3 Imaging Unit and are output to 2 video +nodes, with each targeting a different purpose (main output and viewfinder +output). + +Details onand the Bayer format specific to the IPU3 can be found in +:ref:`v4l2-pix-fmt-ipu3-sbggr10`. + +The driver supports V4L2 Video Capture Interface as defined at :ref:`devices`. + +Only the multi-planar API is supported. More details can be found at +:ref:`planar-apis`. + +Parameters video node +--------------------- + +The parameters video node receives the ImgU algorithm parameters that are used +to configure how the ImgU algorithms process the image. + +Details on processing parameters specific to the IPU3 can be found in +:ref:`v4l2-meta-fmt-params`. + +3A statistics video node +------------------------ + +3A statistics video node is used by the ImgU driver to output the 3A (auto +focus, auto exposure and auto white balance) statistics for the frames that are +being processed by the ImgU to user space applications. User space applications +can use this statistics data to compute the desired algorithm parameters for +the ImgU. + +Configuring the Intel IPU3 +========================== + +The IPU3 ImgU pipelines can be configured using the Media Controller, defined at +:ref:`media_controller`. + +Firmware binary selection +------------------------- + +The firmware binary is selected using the V4L2_CID_INTEL_IPU3_MODE, currently +defined in drivers/staging/media/ipu3/include/intel-ipu3.h . "VIDEO" and "STILL" +modes are available. + +Processing the image in raw Bayer format +---------------------------------------- + +Configuring ImgU V4L2 subdev for image processing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ImgU V4L2 subdevs have to be configured with media controller APIs to have +all the video nodes setup correctly. + +Let us take "ipu3-imgu 0" subdev as an example. + +media-ctl -d $MDEV -r + +media-ctl -d $MDEV -l "ipu3-imgu 0 input":0 -> "ipu3-imgu 0":0[1] + +media-ctl -d $MDEV -l "ipu3-imgu 0":2 -> "ipu3-imgu 0 output":0[1] + +media-ctl -d $MDEV -l "ipu3-imgu 0":3 -> "ipu3-imgu 0 viewfinder":0[1] + +media-ctl -d $MDEV -l "ipu3-imgu 0":4 -> "ipu3-imgu 0 3a stat":0[1] + +Also the pipe mode of the corresponding V4L2 subdev should be set as desired +(e.g 0 for video mode or 1 for still mode) through the control id 0x009819a1 as +below. + +yavta -w "0x009819A1 1" /dev/v4l-subdev7 + +RAW Bayer frames go through the following ImgU pipeline HW blocks to have the +processed image output to the DDR memory. + +RAW Bayer frame -> Input Feeder -> Bayer Down Scaling (BDS) -> Geometric +Distortion Correction (GDC) -> DDR + +The ImgU V4L2 subdev has to be configured with the supported resolutions in all +the above HW blocks, for a given input resolution. + +For a given supported resolution for an input frame, the Input Feeder, Bayer +Down Scaling and GDC blocks should be configured with the supported resolutions. +This information can be obtained by looking at the following IPU3 ImgU +configuration table. + +https://chromium.googlesource.com/chromiumos/overlays/board-overlays/+/master + +Under baseboard-poppy/media-libs/cros-camera-hal-configs-poppy/files/gcss +directory, graph_settings_ov5670.xml can be used as an example. + +The following steps prepare the ImgU pipeline for the image processing. + +1. The ImgU V4L2 subdev data format should be set by using the +VIDIOC_SUBDEV_S_FMT on pad 0, using the GDC width and height obtained above. + +2. The ImgU V4L2 subdev cropping should be set by using the +VIDIOC_SUBDEV_S_SELECTION on pad 0, with V4L2_SEL_TGT_CROP as the target, +using the input feeder height and width. + +3. The ImgU V4L2 subdev composing should be set by using the +VIDIOC_SUBDEV_S_SELECTION on pad 0, with V4L2_SEL_TGT_COMPOSE as the target, +using the BDS height and width. + +For the ov5670 example, for an input frame with a resolution of 2592x1944 +(which is input to the ImgU subdev pad 0), the corresponding resolutions +for input feeder, BDS and GDC are 2592x1944, 2592x1944 and 2560x1920 +respectively. + +Once this is done, the received raw Bayer frames can be input to the ImgU +V4L2 subdev as below, using the open source application v4l2n [#f1]_. + +For an image captured with 2592x1944 [#f4]_ resolution, with desired output +resolution as 2560x1920 and viewfinder resolution as 2560x1920, the following +v4l2n command can be used. This helps process the raw Bayer frames and produces +the desired results for the main output image and the viewfinder output, in NV12 +format. + +v4l2n --pipe=4 --load=/tmp/frame-#.bin --open=/dev/video4 +--fmt=type:VIDEO_OUTPUT_MPLANE,width=2592,height=1944,pixelformat=0X47337069 +--reqbufs=type:VIDEO_OUTPUT_MPLANE,count:1 --pipe=1 --output=/tmp/frames.out +--open=/dev/video5 +--fmt=type:VIDEO_CAPTURE_MPLANE,width=2560,height=1920,pixelformat=NV12 +--reqbufs=type:VIDEO_CAPTURE_MPLANE,count:1 --pipe=2 --output=/tmp/frames.vf +--open=/dev/video6 +--fmt=type:VIDEO_CAPTURE_MPLANE,width=2560,height=1920,pixelformat=NV12 +--reqbufs=type:VIDEO_CAPTURE_MPLANE,count:1 --pipe=3 --open=/dev/video7 +--output=/tmp/frames.3A --fmt=type:META_CAPTURE,? +--reqbufs=count:1,type:META_CAPTURE --pipe=1,2,3,4 --stream=5 + +where /dev/video4, /dev/video5, /dev/video6 and /dev/video7 devices point to +input, output, viewfinder and 3A statistics video nodes respectively. + +Converting the raw Bayer image into YUV domain +---------------------------------------------- + +The processed images after the above step, can be converted to YUV domain +as below. + +Main output frames +~~~~~~~~~~~~~~~~~~ + +raw2pnm -x2560 -y1920 -fNV12 /tmp/frames.out /tmp/frames.out.ppm + +where 2560x1920 is output resolution, NV12 is the video format, followed +by input frame and output PNM file. + +Viewfinder output frames +~~~~~~~~~~~~~~~~~~~~~~~~ + +raw2pnm -x2560 -y1920 -fNV12 /tmp/frames.vf /tmp/frames.vf.ppm + +where 2560x1920 is output resolution, NV12 is the video format, followed +by input frame and output PNM file. + +Example user space code for IPU3 +================================ + +User space code that configures and uses IPU3 is available here. + +https://chromium.googlesource.com/chromiumos/platform/arc-camera/+/master/ + +The source can be located under hal/intel directory. + +References +========== + +.. [#f5] include/uapi/linux/intel-ipu3.h + +.. [#f1] https://github.com/intel/nvt + +.. [#f2] http://git.ideasonboard.org/yavta.git + +.. [#f3] http://git.ideasonboard.org/?p=media-ctl.git;a=summary + +.. [#f4] ImgU limitation requires an additional 16x16 for all input resolutions diff --git a/Documentation/media/v4l-drivers/ivtv-cardlist.rst b/Documentation/media/v4l-drivers/ivtv-cardlist.rst index 022dca80c2c8..c34a9ebc9ac2 100644 --- a/Documentation/media/v4l-drivers/ivtv-cardlist.rst +++ b/Documentation/media/v4l-drivers/ivtv-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + IVTV cards list =============== diff --git a/Documentation/media/v4l-drivers/ivtv.rst b/Documentation/media/v4l-drivers/ivtv.rst index 3ba464c4f9bf..7b8775d20214 100644 --- a/Documentation/media/v4l-drivers/ivtv.rst +++ b/Documentation/media/v4l-drivers/ivtv.rst @@ -1,3 +1,4 @@ +.. SPDX-License-Identifier: GPL-2.0 The ivtv driver =============== diff --git a/Documentation/media/v4l-drivers/max2175.rst b/Documentation/media/v4l-drivers/max2175.rst index b1a4c89fd869..a5e35059d98d 100644 --- a/Documentation/media/v4l-drivers/max2175.rst +++ b/Documentation/media/v4l-drivers/max2175.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Maxim Integrated MAX2175 RF to bits tuner driver ================================================ diff --git a/Documentation/media/v4l-drivers/meye.rst b/Documentation/media/v4l-drivers/meye.rst index cfaba6021850..a572996cdbf6 100644 --- a/Documentation/media/v4l-drivers/meye.rst +++ b/Documentation/media/v4l-drivers/meye.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> Vaio Picturebook Motion Eye Camera Driver diff --git a/Documentation/media/v4l-drivers/omap3isp.rst b/Documentation/media/v4l-drivers/omap3isp.rst index 336e58feaee2..8974c444e3a1 100644 --- a/Documentation/media/v4l-drivers/omap3isp.rst +++ b/Documentation/media/v4l-drivers/omap3isp.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> OMAP 3 Image Signal Processor (ISP) driver diff --git a/Documentation/media/v4l-drivers/omap4_camera.rst b/Documentation/media/v4l-drivers/omap4_camera.rst index 54b427b28e5f..24db4222d36d 100644 --- a/Documentation/media/v4l-drivers/omap4_camera.rst +++ b/Documentation/media/v4l-drivers/omap4_camera.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + OMAP4 ISS Driver ================ diff --git a/Documentation/media/v4l-drivers/philips.rst b/Documentation/media/v4l-drivers/philips.rst index 4f68947e6a13..e2840be10d08 100644 --- a/Documentation/media/v4l-drivers/philips.rst +++ b/Documentation/media/v4l-drivers/philips.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Philips webcams (pwc driver) ============================ diff --git a/Documentation/media/v4l-drivers/pvrusb2.rst b/Documentation/media/v4l-drivers/pvrusb2.rst index dc0e72d94b1a..83bfaa531ea8 100644 --- a/Documentation/media/v4l-drivers/pvrusb2.rst +++ b/Documentation/media/v4l-drivers/pvrusb2.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The pvrusb2 driver ================== diff --git a/Documentation/media/v4l-drivers/pxa_camera.rst b/Documentation/media/v4l-drivers/pxa_camera.rst index 554f91b04e70..e4fbca755e1a 100644 --- a/Documentation/media/v4l-drivers/pxa_camera.rst +++ b/Documentation/media/v4l-drivers/pxa_camera.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + PXA-Camera Host Driver ====================== diff --git a/Documentation/media/v4l-drivers/qcom_camss.rst b/Documentation/media/v4l-drivers/qcom_camss.rst index f27c8df20b2b..6b15385b12b3 100644 --- a/Documentation/media/v4l-drivers/qcom_camss.rst +++ b/Documentation/media/v4l-drivers/qcom_camss.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> Qualcomm Camera Subsystem driver diff --git a/Documentation/media/v4l-drivers/qcom_camss_8x96_graph.dot b/Documentation/media/v4l-drivers/qcom_camss_8x96_graph.dot index de34f0a7afdc..7ed243b41b67 100644 --- a/Documentation/media/v4l-drivers/qcom_camss_8x96_graph.dot +++ b/Documentation/media/v4l-drivers/qcom_camss_8x96_graph.dot @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + digraph board { rankdir=TB n00000001 [label="{{<port0> 0} | msm_csiphy0\n/dev/v4l-subdev0 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green] diff --git a/Documentation/media/v4l-drivers/qcom_camss_graph.dot b/Documentation/media/v4l-drivers/qcom_camss_graph.dot index 827fc7112c1e..ef7dca92fd0b 100644 --- a/Documentation/media/v4l-drivers/qcom_camss_graph.dot +++ b/Documentation/media/v4l-drivers/qcom_camss_graph.dot @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + digraph board { rankdir=TB n00000001 [label="{{<port0> 0} | msm_csiphy0\n/dev/v4l-subdev0 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green] diff --git a/Documentation/media/v4l-drivers/radiotrack.rst b/Documentation/media/v4l-drivers/radiotrack.rst index 2f6325ebfd16..a85cb6205db8 100644 --- a/Documentation/media/v4l-drivers/radiotrack.rst +++ b/Documentation/media/v4l-drivers/radiotrack.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The Radiotrack radio driver =========================== diff --git a/Documentation/media/v4l-drivers/rcar-fdp1.rst b/Documentation/media/v4l-drivers/rcar-fdp1.rst index a59b1e8e3e9c..88b0edcf9046 100644 --- a/Documentation/media/v4l-drivers/rcar-fdp1.rst +++ b/Documentation/media/v4l-drivers/rcar-fdp1.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Renesas R-Car Fine Display Processor (FDP1) Driver ================================================== diff --git a/Documentation/media/v4l-drivers/saa7134-cardlist.rst b/Documentation/media/v4l-drivers/saa7134-cardlist.rst index 6e4c35cbaabf..afb0e2fb52b0 100644 --- a/Documentation/media/v4l-drivers/saa7134-cardlist.rst +++ b/Documentation/media/v4l-drivers/saa7134-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + SAA7134 cards list ================== diff --git a/Documentation/media/v4l-drivers/saa7134.rst b/Documentation/media/v4l-drivers/saa7134.rst index 36b2ee9e0fdc..15d06facdbc1 100644 --- a/Documentation/media/v4l-drivers/saa7134.rst +++ b/Documentation/media/v4l-drivers/saa7134.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The saa7134 driver ================== diff --git a/Documentation/media/v4l-drivers/saa7164-cardlist.rst b/Documentation/media/v4l-drivers/saa7164-cardlist.rst index e28382ba82e6..e8f36e084537 100644 --- a/Documentation/media/v4l-drivers/saa7164-cardlist.rst +++ b/Documentation/media/v4l-drivers/saa7164-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + SAA7164 cards list ================== diff --git a/Documentation/media/v4l-drivers/sh_mobile_ceu_camera.rst b/Documentation/media/v4l-drivers/sh_mobile_ceu_camera.rst index e40ffea7708c..822fcb8368ae 100644 --- a/Documentation/media/v4l-drivers/sh_mobile_ceu_camera.rst +++ b/Documentation/media/v4l-drivers/sh_mobile_ceu_camera.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Cropping and Scaling algorithm, used in the sh_mobile_ceu_camera driver ======================================================================= @@ -114,7 +116,7 @@ window: S_CROP ------ -The API at http://v4l2spec.bytesex.org/spec/x1904.htm says: +The :ref:`V4L2 crop API <crop-scale>` says: "...specification does not define an origin or units. However by convention drivers should horizontally count unscaled samples relative to 0H." diff --git a/Documentation/media/v4l-drivers/si470x.rst b/Documentation/media/v4l-drivers/si470x.rst index 955d8ca159fe..d53bf5f95200 100644 --- a/Documentation/media/v4l-drivers/si470x.rst +++ b/Documentation/media/v4l-drivers/si470x.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> The Silicon Labs Si470x FM Radio Receivers driver diff --git a/Documentation/media/v4l-drivers/si4713.rst b/Documentation/media/v4l-drivers/si4713.rst index 3022e7cfe9a8..be8e6b49b7b4 100644 --- a/Documentation/media/v4l-drivers/si4713.rst +++ b/Documentation/media/v4l-drivers/si4713.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> The Silicon Labs Si4713 FM Radio Transmitter Driver diff --git a/Documentation/media/v4l-drivers/si476x.rst b/Documentation/media/v4l-drivers/si476x.rst index 677512566f15..87062301d6a1 100644 --- a/Documentation/media/v4l-drivers/si476x.rst +++ b/Documentation/media/v4l-drivers/si476x.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. include:: <isonum.txt> diff --git a/Documentation/media/v4l-drivers/soc-camera.rst b/Documentation/media/v4l-drivers/soc-camera.rst index 79d09e423700..7c39711aebf8 100644 --- a/Documentation/media/v4l-drivers/soc-camera.rst +++ b/Documentation/media/v4l-drivers/soc-camera.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The Soc-Camera Drivers ====================== diff --git a/Documentation/media/v4l-drivers/tm6000-cardlist.rst b/Documentation/media/v4l-drivers/tm6000-cardlist.rst index 6bd083544457..6d2769c0f4d8 100644 --- a/Documentation/media/v4l-drivers/tm6000-cardlist.rst +++ b/Documentation/media/v4l-drivers/tm6000-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + TM6000 cards list ================= diff --git a/Documentation/media/v4l-drivers/tuner-cardlist.rst b/Documentation/media/v4l-drivers/tuner-cardlist.rst index 276dd90e0c59..362617c59c5d 100644 --- a/Documentation/media/v4l-drivers/tuner-cardlist.rst +++ b/Documentation/media/v4l-drivers/tuner-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Tuner cards list ================ diff --git a/Documentation/media/v4l-drivers/tuners.rst b/Documentation/media/v4l-drivers/tuners.rst index c3e8a1cf64a6..7509be888909 100644 --- a/Documentation/media/v4l-drivers/tuners.rst +++ b/Documentation/media/v4l-drivers/tuners.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Tuner drivers ============= diff --git a/Documentation/media/v4l-drivers/usbvision-cardlist.rst b/Documentation/media/v4l-drivers/usbvision-cardlist.rst index 5a8ffbfc204e..6aee115ee6e2 100644 --- a/Documentation/media/v4l-drivers/usbvision-cardlist.rst +++ b/Documentation/media/v4l-drivers/usbvision-cardlist.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + USBvision cards list ==================== diff --git a/Documentation/media/v4l-drivers/uvcvideo.rst b/Documentation/media/v4l-drivers/uvcvideo.rst index d68b3d59a4b5..e5fd8fad333c 100644 --- a/Documentation/media/v4l-drivers/uvcvideo.rst +++ b/Documentation/media/v4l-drivers/uvcvideo.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The Linux USB Video Class (UVC) driver ====================================== diff --git a/Documentation/media/v4l-drivers/v4l-with-ir.rst b/Documentation/media/v4l-drivers/v4l-with-ir.rst index 613e1e79fc96..ce23c8a7bc93 100644 --- a/Documentation/media/v4l-drivers/v4l-with-ir.rst +++ b/Documentation/media/v4l-drivers/v4l-with-ir.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Infrared remote control support in video4linux drivers ====================================================== diff --git a/Documentation/media/v4l-drivers/vivid.rst b/Documentation/media/v4l-drivers/vivid.rst index 089595ce11c5..edb6f33e029c 100644 --- a/Documentation/media/v4l-drivers/vivid.rst +++ b/Documentation/media/v4l-drivers/vivid.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The Virtual Video Test Driver (vivid) ===================================== diff --git a/Documentation/media/v4l-drivers/zoran.rst b/Documentation/media/v4l-drivers/zoran.rst index c3a0f7bc2c7b..d2724a863d1d 100644 --- a/Documentation/media/v4l-drivers/zoran.rst +++ b/Documentation/media/v4l-drivers/zoran.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + The Zoran driver ================ diff --git a/Documentation/media/v4l-drivers/zr364xx.rst b/Documentation/media/v4l-drivers/zr364xx.rst index 3d193f01d8bb..ec8acb3e98fc 100644 --- a/Documentation/media/v4l-drivers/zr364xx.rst +++ b/Documentation/media/v4l-drivers/zr364xx.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + Zoran 364xx based USB webcam module =================================== diff --git a/Documentation/media/video.h.rst.exceptions b/Documentation/media/video.h.rst.exceptions index 371cdbd7d062..ea9de59ad8b7 100644 --- a/Documentation/media/video.h.rst.exceptions +++ b/Documentation/media/video.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _UAPI_DVBVIDEO_H_ diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index ca9f0edc579e..64d348e67df9 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -1,3 +1,5 @@ +# SPDX-License-Identifier: GPL-2.0 + # Ignore header name ignore define _UAPI__LINUX_VIDEODEV2_H @@ -28,6 +30,7 @@ replace symbol V4L2_FIELD_TOP :c:type:`v4l2_field` # Documented enum v4l2_buf_type replace symbol V4L2_BUF_TYPE_META_CAPTURE :c:type:`v4l2_buf_type` +replace symbol V4L2_BUF_TYPE_META_OUTPUT :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_CAPTURE :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SDR_OUTPUT :c:type:`v4l2_buf_type` replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE :c:type:`v4l2_buf_type` @@ -56,7 +59,8 @@ replace symbol V4L2_MEMORY_USERPTR :c:type:`v4l2_memory` # Documented enum v4l2_colorspace replace symbol V4L2_COLORSPACE_470_SYSTEM_BG :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_470_SYSTEM_M :c:type:`v4l2_colorspace` -replace symbol V4L2_COLORSPACE_ADOBERGB :c:type:`v4l2_colorspace` +replace symbol V4L2_COLORSPACE_OPRGB :c:type:`v4l2_colorspace` +replace define V4L2_COLORSPACE_ADOBERGB :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_BT2020 :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_DCI_P3 :c:type:`v4l2_colorspace` replace symbol V4L2_COLORSPACE_DEFAULT :c:type:`v4l2_colorspace` @@ -69,7 +73,8 @@ replace symbol V4L2_COLORSPACE_SRGB :c:type:`v4l2_colorspace` # Documented enum v4l2_xfer_func replace symbol V4L2_XFER_FUNC_709 :c:type:`v4l2_xfer_func` -replace symbol V4L2_XFER_FUNC_ADOBERGB :c:type:`v4l2_xfer_func` +replace symbol V4L2_XFER_FUNC_OPRGB :c:type:`v4l2_xfer_func` +replace define V4L2_XFER_FUNC_ADOBERGB :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_DCI_P3 :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_DEFAULT :c:type:`v4l2_xfer_func` replace symbol V4L2_XFER_FUNC_NONE :c:type:`v4l2_xfer_func` @@ -129,6 +134,8 @@ replace symbol V4L2_CTRL_TYPE_STRING :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U16 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U32 :c:type:`v4l2_ctrl_type` replace symbol V4L2_CTRL_TYPE_U8 :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_SLICE_PARAMS :c:type:`v4l2_ctrl_type` +replace symbol V4L2_CTRL_TYPE_MPEG2_QUANTIZATION :c:type:`v4l2_ctrl_type` # V4L2 capability defines replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities @@ -157,6 +164,7 @@ replace define V4L2_CAP_META_CAPTURE device-capabilities replace define V4L2_CAP_READWRITE device-capabilities replace define V4L2_CAP_ASYNCIO device-capabilities replace define V4L2_CAP_STREAMING device-capabilities +replace define V4L2_CAP_META_OUTPUT device-capabilities replace define V4L2_CAP_DEVICE_CAPS device-capabilities replace define V4L2_CAP_TOUCH device-capabilities @@ -278,6 +286,7 @@ replace define V4L2_DV_BT_STD_SDI dv-bt-standards replace define V4L2_DV_FL_REDUCED_BLANKING dv-bt-standards replace define V4L2_DV_FL_CAN_REDUCE_FPS dv-bt-standards +replace define V4L2_DV_FL_CAN_DETECT_REDUCED_FPS dv-bt-standards replace define V4L2_DV_FL_REDUCED_FPS dv-bt-standards replace define V4L2_DV_FL_HALF_LINE dv-bt-standards replace define V4L2_DV_FL_IS_CE_VIDEO dv-bt-standards @@ -514,6 +523,7 @@ ignore define V4L2_CTRL_DRIVER_PRIV ignore define V4L2_CTRL_MAX_DIMS ignore define V4L2_CTRL_WHICH_CUR_VAL ignore define V4L2_CTRL_WHICH_DEF_VAL +ignore define V4L2_CTRL_WHICH_REQUEST_VAL ignore define V4L2_OUT_CAP_CUSTOM_TIMINGS ignore define V4L2_CID_MAX_CTRLS diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index c1d913944ad8..1c22b21ae922 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -587,7 +587,7 @@ leading to the following situation: (Q == &B) and (D == 2) ???? -Whilst this may seem like a failure of coherency or causality maintenance, it +While this may seem like a failure of coherency or causality maintenance, it isn't, and this behaviour can be observed on certain real CPUs (such as the DEC Alpha). @@ -2008,7 +2008,7 @@ for each construct. These operations all imply certain barriers: Certain locking variants of the ACQUIRE operation may fail, either due to being unable to get the lock immediately, or due to receiving an unblocked - signal whilst asleep waiting for the lock to become available. Failed + signal while asleep waiting for the lock to become available. Failed locks do not imply any sort of barrier. [!] Note: one of the consequences of lock ACQUIREs and RELEASEs being only @@ -2508,7 +2508,7 @@ CPU, that CPU's dependency ordering logic will take care of everything else. ATOMIC OPERATIONS ----------------- -Whilst they are technically interprocessor interaction considerations, atomic +While they are technically interprocessor interaction considerations, atomic operations are noted specially as some of them imply full memory barriers and some don't, but they're very heavily relied on as a group throughout the kernel. @@ -2531,7 +2531,7 @@ the device to malfunction. Inside of the Linux kernel, I/O should be done through the appropriate accessor routines - such as inb() or writel() - which know how to make such accesses -appropriately sequential. Whilst this, for the most part, renders the explicit +appropriately sequential. While this, for the most part, renders the explicit use of memory barriers unnecessary, there are a couple of situations where they might be needed: @@ -2555,7 +2555,7 @@ access the device. This may be alleviated - at least in part - by disabling local interrupts (a form of locking), such that the critical operations are all contained within -the interrupt-disabled section in the driver. Whilst the driver's interrupt +the interrupt-disabled section in the driver. While the driver's interrupt routine is executing, the driver's core may not run on the same CPU, and its interrupt is not permitted to happen again until the current interrupt has been handled, thus the interrupt handler does not need to lock against that. @@ -2763,7 +2763,7 @@ CACHE COHERENCY Life isn't quite as simple as it may appear above, however: for while the caches are expected to be coherent, there's no guarantee that that coherency -will be ordered. This means that whilst changes made on one CPU will +will be ordered. This means that while changes made on one CPU will eventually become visible on all CPUs, there's no guarantee that they will become apparent in the same order on those other CPUs. @@ -2799,7 +2799,7 @@ Imagine the system has the following properties: (*) an even-numbered cache line may be in cache B, cache D or it may still be resident in memory; - (*) whilst the CPU core is interrogating one cache, the other cache may be + (*) while the CPU core is interrogating one cache, the other cache may be making use of the bus to access the rest of the system - perhaps to displace a dirty cacheline or to do a speculative load; @@ -2835,7 +2835,7 @@ now imagine that the second CPU wants to read those values: x = *q; The above pair of reads may then fail to happen in the expected order, as the -cacheline holding p may get updated in one of the second CPU's caches whilst +cacheline holding p may get updated in one of the second CPU's caches while the update to the cacheline holding v is delayed in the other of the second CPU's caches by some other cache event: @@ -2855,7 +2855,7 @@ CPU's caches by some other cache event: <C:unbusy> <C:commit v=2> -Basically, whilst both cachelines will be updated on CPU 2 eventually, there's +Basically, while both cachelines will be updated on CPU 2 eventually, there's no guarantee that, without intervention, the order of update will be the same as that committed on CPU 1. @@ -2885,7 +2885,7 @@ coherency queue before processing any further requests: This sort of problem can be encountered on DEC Alpha processors as they have a split cache that improves performance by making better use of the data bus. -Whilst most CPUs do imply a data dependency barrier on the read when a memory +While most CPUs do imply a data dependency barrier on the read when a memory access depends on a read, not all do, so it may not be relied on. Other CPUs may also have split caches, but must coordinate between the various @@ -2974,7 +2974,7 @@ assumption doesn't hold because: thus cutting down on transaction setup costs (memory and PCI devices may both be able to do this); and - (*) the CPU's data cache may affect the ordering, and whilst cache-coherency + (*) the CPU's data cache may affect the ordering, and while cache-coherency mechanisms may alleviate this - once the store has actually hit the cache - there's no guarantee that the coherency management will be propagated in order to other CPUs. diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index 4ae4f9d8f8fe..e14d7d40fc75 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -295,6 +295,41 @@ using:: For XDP_SKB mode, use the switch "-S" instead of "-N" and all options can be displayed with "-h", as usual. +FAQ +======= + +Q: I am not seeing any traffic on the socket. What am I doing wrong? + +A: When a netdev of a physical NIC is initialized, Linux usually + allocates one Rx and Tx queue pair per core. So on a 8 core system, + queue ids 0 to 7 will be allocated, one per core. In the AF_XDP + bind call or the xsk_socket__create libbpf function call, you + specify a specific queue id to bind to and it is only the traffic + towards that queue you are going to get on you socket. So in the + example above, if you bind to queue 0, you are NOT going to get any + traffic that is distributed to queues 1 through 7. If you are + lucky, you will see the traffic, but usually it will end up on one + of the queues you have not bound to. + + There are a number of ways to solve the problem of getting the + traffic you want to the queue id you bound to. If you want to see + all the traffic, you can force the netdev to only have 1 queue, queue + id 0, and then bind to queue 0. You can use ethtool to do this:: + + sudo ethtool -L <interface> combined 1 + + If you want to only see part of the traffic, you can program the + NIC through ethtool to filter out your traffic to a single queue id + that you can bind your XDP socket to. Here is one example in which + UDP traffic to and from port 4242 are sent to queue 2:: + + sudo ethtool -N <interface> rx-flow-hash udp4 fn + sudo ethtool -N <interface> flow-type udp4 src-port 4242 dst-port \ + 4242 action 2 + + A number of other ways are possible all up to the capabilitites of + the NIC you have. + Credits ======= @@ -309,4 +344,3 @@ Credits - Michael S. Tsirkin - Qi Z Zhang - Willem de Bruijn - diff --git a/Documentation/networking/3c509.txt b/Documentation/networking/device_drivers/3com/3c509.txt index fbf722e15ac3..fbf722e15ac3 100644 --- a/Documentation/networking/3c509.txt +++ b/Documentation/networking/device_drivers/3com/3c509.txt diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/device_drivers/3com/vortex.txt index ad3dead052a4..587f3fcfbcae 100644 --- a/Documentation/networking/vortex.txt +++ b/Documentation/networking/device_drivers/3com/vortex.txt @@ -1,4 +1,4 @@ -Documentation/networking/vortex.txt +Documentation/networking/device_drivers/3com/vortex.txt Andrew Morton 30 April 2000 diff --git a/Documentation/networking/ena.txt b/Documentation/networking/device_drivers/amazon/ena.txt index 2b4b6f57e549..2b4b6f57e549 100644 --- a/Documentation/networking/ena.txt +++ b/Documentation/networking/device_drivers/amazon/ena.txt diff --git a/Documentation/networking/cxgb.txt b/Documentation/networking/device_drivers/chelsio/cxgb.txt index 20a887615c4a..20a887615c4a 100644 --- a/Documentation/networking/cxgb.txt +++ b/Documentation/networking/device_drivers/chelsio/cxgb.txt diff --git a/Documentation/networking/cs89x0.txt b/Documentation/networking/device_drivers/cirrus/cs89x0.txt index 0e190180eec8..0e190180eec8 100644 --- a/Documentation/networking/cs89x0.txt +++ b/Documentation/networking/device_drivers/cirrus/cs89x0.txt diff --git a/Documentation/networking/dm9000.txt b/Documentation/networking/device_drivers/davicom/dm9000.txt index 5552e2e575c5..5552e2e575c5 100644 --- a/Documentation/networking/dm9000.txt +++ b/Documentation/networking/device_drivers/davicom/dm9000.txt diff --git a/Documentation/networking/de4x5.txt b/Documentation/networking/device_drivers/dec/de4x5.txt index c8e4ca9b2c3e..452aac58341d 100644 --- a/Documentation/networking/de4x5.txt +++ b/Documentation/networking/device_drivers/dec/de4x5.txt @@ -84,7 +84,7 @@ Automedia detection is included so that in principle you can disconnect from, e.g. TP, reconnect to BNC and things will still work (after a - pause whilst the driver figures out where its media went). My tests + pause while the driver figures out where its media went). My tests using ping showed that it appears to work.... By default, the driver will now autodetect any DECchip based card. diff --git a/Documentation/networking/dmfe.txt b/Documentation/networking/device_drivers/dec/dmfe.txt index 25320bf19c86..25320bf19c86 100644 --- a/Documentation/networking/dmfe.txt +++ b/Documentation/networking/device_drivers/dec/dmfe.txt diff --git a/Documentation/networking/dl2k.txt b/Documentation/networking/device_drivers/dlink/dl2k.txt index cba74f7a3abc..cba74f7a3abc 100644 --- a/Documentation/networking/dl2k.txt +++ b/Documentation/networking/device_drivers/dlink/dl2k.txt diff --git a/Documentation/networking/dpaa.txt b/Documentation/networking/device_drivers/freescale/dpaa.txt index f88194f71c54..f88194f71c54 100644 --- a/Documentation/networking/dpaa.txt +++ b/Documentation/networking/device_drivers/freescale/dpaa.txt diff --git a/Documentation/networking/dpaa2/dpio-driver.rst b/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst index 13588104161b..5045df990a4c 100644 --- a/Documentation/networking/dpaa2/dpio-driver.rst +++ b/Documentation/networking/device_drivers/freescale/dpaa2/dpio-driver.rst @@ -19,19 +19,20 @@ pool management for network interfaces. This document provides an overview the Linux DPIO driver, its subcomponents, and its APIs. -See Documentation/networking/dpaa2/overview.rst for a general overview of DPAA2 -and the general DPAA2 driver architecture in Linux. +See Documentation/networking/device_drivers/freescale/dpaa2/overview.rst for +a general overview of DPAA2 and the general DPAA2 driver architecture in Linux. Driver Overview --------------- The DPIO driver is bound to DPIO objects discovered on the fsl-mc bus and provides services that: - A) allow other drivers, such as the Ethernet driver, to enqueue and dequeue + + A. allow other drivers, such as the Ethernet driver, to enqueue and dequeue frames for their respective objects - B) allow drivers to register callbacks for data availability notifications + B. allow drivers to register callbacks for data availability notifications when data becomes available on a queue or channel - C) allow drivers to manage hardware buffer pools + C. allow drivers to manage hardware buffer pools The Linux DPIO driver consists of 3 primary components-- DPIO object driver-- fsl-mc driver that manages the DPIO object @@ -140,11 +141,10 @@ QBman portal interface (qbman-portal.c) The qbman-portal component provides APIs to do the low level hardware bit twiddling for operations such as: - -initializing Qman software portals - - -building and sending portal commands - -portal interrupt configuration and processing + - initializing Qman software portals + - building and sending portal commands + - portal interrupt configuration and processing The qbman-portal APIs are not public to other drivers, and are only used by dpio-service. diff --git a/Documentation/networking/dpaa2/ethernet-driver.rst b/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst index 90ec940749e8..cb4c9a0c5a17 100644 --- a/Documentation/networking/dpaa2/ethernet-driver.rst +++ b/Documentation/networking/device_drivers/freescale/dpaa2/ethernet-driver.rst @@ -33,7 +33,7 @@ hardware resources, like queues, do not have a corresponding MC object and are treated as internal resources of other objects. For a more detailed description of the DPAA2 architecture and its object -abstractions see *Documentation/networking/dpaa2/overview.rst*. +abstractions see *Documentation/networking/device_drivers/freescale/dpaa2/overview.rst*. Each Linux net device is built on top of a Datapath Network Interface (DPNI) object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators diff --git a/Documentation/networking/dpaa2/index.rst b/Documentation/networking/device_drivers/freescale/dpaa2/index.rst index 67bd87fe6c53..67bd87fe6c53 100644 --- a/Documentation/networking/dpaa2/index.rst +++ b/Documentation/networking/device_drivers/freescale/dpaa2/index.rst diff --git a/Documentation/networking/dpaa2/overview.rst b/Documentation/networking/device_drivers/freescale/dpaa2/overview.rst index d638b5a8aadd..d638b5a8aadd 100644 --- a/Documentation/networking/dpaa2/overview.rst +++ b/Documentation/networking/device_drivers/freescale/dpaa2/overview.rst diff --git a/Documentation/networking/gianfar.txt b/Documentation/networking/device_drivers/freescale/gianfar.txt index ba1daea7f2e4..ba1daea7f2e4 100644 --- a/Documentation/networking/gianfar.txt +++ b/Documentation/networking/device_drivers/freescale/gianfar.txt diff --git a/Documentation/networking/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst index 5e2839b4ec92..2b9f4887beda 100644 --- a/Documentation/networking/e100.rst +++ b/Documentation/networking/device_drivers/intel/e100.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +============================================================== Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters ============================================================== diff --git a/Documentation/networking/e1000.rst b/Documentation/networking/device_drivers/intel/e1000.rst index 6379d4d20771..956560b6e745 100644 --- a/Documentation/networking/e1000.rst +++ b/Documentation/networking/device_drivers/intel/e1000.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +=========================================================== Linux* Base Driver for Intel(R) Ethernet Network Connection =========================================================== diff --git a/Documentation/networking/e1000e.rst b/Documentation/networking/device_drivers/intel/e1000e.rst index 33554e5416c5..01999f05509c 100644 --- a/Documentation/networking/e1000e.rst +++ b/Documentation/networking/device_drivers/intel/e1000e.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +====================================================== Linux* Driver for Intel(R) Ethernet Network Connection ====================================================== diff --git a/Documentation/networking/fm10k.rst b/Documentation/networking/device_drivers/intel/fm10k.rst index bf5e5942f28d..ac3269e34f55 100644 --- a/Documentation/networking/fm10k.rst +++ b/Documentation/networking/device_drivers/intel/fm10k.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +============================================================== Linux* Base Driver for Intel(R) Ethernet Multi-host Controller ============================================================== diff --git a/Documentation/networking/i40e.rst b/Documentation/networking/device_drivers/intel/i40e.rst index 0cc16c525d10..848fd388fa6e 100644 --- a/Documentation/networking/i40e.rst +++ b/Documentation/networking/device_drivers/intel/i40e.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +================================================================== Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series ================================================================== diff --git a/Documentation/networking/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst index f8b42b64eb28..2d0c3baa1752 100644 --- a/Documentation/networking/iavf.rst +++ b/Documentation/networking/device_drivers/intel/iavf.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +================================================================== Linux* Base Driver for Intel(R) Ethernet Adaptive Virtual Function ================================================================== diff --git a/Documentation/networking/ice.rst b/Documentation/networking/device_drivers/intel/ice.rst index 1e4948c9e989..c220aa2711c6 100644 --- a/Documentation/networking/ice.rst +++ b/Documentation/networking/device_drivers/intel/ice.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +=================================================================== Linux* Base Driver for the Intel(R) Ethernet Connection E800 Series =================================================================== @@ -20,7 +21,7 @@ Enabling the driver The driver is enabled via the standard kernel configuration system, using the make command:: - make oldconfig/silentoldconfig/menuconfig/etc. + make oldconfig/menuconfig/etc. The driver is located in the menu structure at: diff --git a/Documentation/networking/igb.rst b/Documentation/networking/device_drivers/intel/igb.rst index ba16b86d5593..fc8cfaa5dcfa 100644 --- a/Documentation/networking/igb.rst +++ b/Documentation/networking/device_drivers/intel/igb.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +=========================================================== Linux* Base Driver for Intel(R) Ethernet Network Connection =========================================================== @@ -177,6 +178,25 @@ rate limit using the IProute2 tool. Download the latest version of the IProute2 tool from Sourceforge if your version does not have all the features you require. +Credit Based Shaper (Qav Mode) +------------------------------ +When enabling the CBS qdisc in the hardware offload mode, traffic shaping using +the CBS (described in the IEEE 802.1Q-2018 Section 8.6.8.2 and discussed in the +Annex L) algorithm will run in the i210 controller, so it's more accurate and +uses less CPU. + +When using offloaded CBS, and the traffic rate obeys the configured rate +(doesn't go above it), CBS should have little to no effect in the latency. + +The offloaded version of the algorithm has some limits, caused by how the idle +slope is expressed in the adapter's registers. It can only represent idle slopes +in 16.38431 kbps units, which means that if a idle slope of 2576kbps is +requested, the controller will be configured to use a idle slope of ~2589 kbps, +because the driver rounds the value up. For more details, see the comments on +:c:func:`igb_config_tx_modes()`. + +NOTE: This feature is exclusive to i210 models. + Support ======= diff --git a/Documentation/networking/igbvf.rst b/Documentation/networking/device_drivers/intel/igbvf.rst index a8a9ffa4f8d3..9cddabe8108e 100644 --- a/Documentation/networking/igbvf.rst +++ b/Documentation/networking/device_drivers/intel/igbvf.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +============================================================ Linux* Base Virtual Function Driver for Intel(R) 1G Ethernet ============================================================ diff --git a/Documentation/networking/README.ipw2100 b/Documentation/networking/device_drivers/intel/ipw2100.txt index 6f85e1d06031..6f85e1d06031 100644 --- a/Documentation/networking/README.ipw2100 +++ b/Documentation/networking/device_drivers/intel/ipw2100.txt diff --git a/Documentation/networking/README.ipw2200 b/Documentation/networking/device_drivers/intel/ipw2200.txt index b7658bed4906..b7658bed4906 100644 --- a/Documentation/networking/README.ipw2200 +++ b/Documentation/networking/device_drivers/intel/ipw2200.txt diff --git a/Documentation/networking/ixgb.rst b/Documentation/networking/device_drivers/intel/ixgb.rst index 8bd80e27843d..945018207a92 100644 --- a/Documentation/networking/ixgb.rst +++ b/Documentation/networking/device_drivers/intel/ixgb.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +===================================================================== Linux Base Driver for 10 Gigabit Intel(R) Ethernet Network Connection ===================================================================== diff --git a/Documentation/networking/ixgbe.rst b/Documentation/networking/device_drivers/intel/ixgbe.rst index 725fc697fd8f..c7d25483fedb 100644 --- a/Documentation/networking/ixgbe.rst +++ b/Documentation/networking/device_drivers/intel/ixgbe.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +============================================================================= Linux* Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters ============================================================================= @@ -501,6 +502,19 @@ NOTE: This feature can be disabled for a specific Virtual Function (VF):: ip link set <pf dev> vf <vf id> spoofchk {off|on} +IPsec Offload +------------- +The ixgbe driver supports IPsec Hardware Offload. When creating Security +Associations with "ip xfrm ..." the 'offload' tag option can be used to +register the IPsec SA with the driver in order to get higher throughput in +the secure communications. + +The offload is also supported for ixgbe's VFs, but the VF must be set as +'trusted' and the support must be enabled with:: + + ethtool --set-priv-flags eth<x> vf-ipsec on + ip link set eth<x> vf <y> trust on + Known Issues/Troubleshooting ============================ diff --git a/Documentation/networking/ixgbevf.rst b/Documentation/networking/device_drivers/intel/ixgbevf.rst index 56cde6366c2f..5d4977360157 100644 --- a/Documentation/networking/ixgbevf.rst +++ b/Documentation/networking/device_drivers/intel/ixgbevf.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0+ +============================================================= Linux* Base Virtual Function Driver for Intel(R) 10G Ethernet ============================================================= diff --git a/Documentation/networking/netvsc.txt b/Documentation/networking/device_drivers/microsoft/netvsc.txt index 3bfa635bbbd5..3bfa635bbbd5 100644 --- a/Documentation/networking/netvsc.txt +++ b/Documentation/networking/device_drivers/microsoft/netvsc.txt diff --git a/Documentation/networking/s2io.txt b/Documentation/networking/device_drivers/neterion/s2io.txt index 0362a42f7cf4..0362a42f7cf4 100644 --- a/Documentation/networking/s2io.txt +++ b/Documentation/networking/device_drivers/neterion/s2io.txt diff --git a/Documentation/networking/vxge.txt b/Documentation/networking/device_drivers/neterion/vxge.txt index abfec245f97c..abfec245f97c 100644 --- a/Documentation/networking/vxge.txt +++ b/Documentation/networking/device_drivers/neterion/vxge.txt diff --git a/Documentation/networking/LICENSE.qla3xxx b/Documentation/networking/device_drivers/qlogic/LICENSE.qla3xxx index 2f2077e34d81..2f2077e34d81 100644 --- a/Documentation/networking/LICENSE.qla3xxx +++ b/Documentation/networking/device_drivers/qlogic/LICENSE.qla3xxx diff --git a/Documentation/networking/LICENSE.qlcnic b/Documentation/networking/device_drivers/qlogic/LICENSE.qlcnic index 2ae3b64983ab..2ae3b64983ab 100644 --- a/Documentation/networking/LICENSE.qlcnic +++ b/Documentation/networking/device_drivers/qlogic/LICENSE.qlcnic diff --git a/Documentation/networking/LICENSE.qlge b/Documentation/networking/device_drivers/qlogic/LICENSE.qlge index ce64e4d15b21..ce64e4d15b21 100644 --- a/Documentation/networking/LICENSE.qlge +++ b/Documentation/networking/device_drivers/qlogic/LICENSE.qlge diff --git a/Documentation/networking/rmnet.txt b/Documentation/networking/device_drivers/qualcomm/rmnet.txt index 6b341eaf2062..6b341eaf2062 100644 --- a/Documentation/networking/rmnet.txt +++ b/Documentation/networking/device_drivers/qualcomm/rmnet.txt diff --git a/Documentation/networking/README.sb1000 b/Documentation/networking/device_drivers/sb1000.txt index f92c2aac56a9..f92c2aac56a9 100644 --- a/Documentation/networking/README.sb1000 +++ b/Documentation/networking/device_drivers/sb1000.txt diff --git a/Documentation/networking/smc9.txt b/Documentation/networking/device_drivers/smsc/smc9.txt index d1e15074e43d..d1e15074e43d 100644 --- a/Documentation/networking/smc9.txt +++ b/Documentation/networking/device_drivers/smsc/smc9.txt diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/device_drivers/stmicro/stmmac.txt index 2bb07078f535..1ae979fd90d2 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/device_drivers/stmicro/stmmac.txt @@ -267,7 +267,7 @@ static struct fixed_phy_status stmmac0_fixed_phy_status = { During the board's device_init we can configure the first MAC for fixed_link by calling: - fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status, -1); + fixed_phy_add(PHY_POLL, 1, &stmmac0_fixed_phy_status); and the second one, with a real PHY device attached to the bus, by using the stmmac_mdio_bus_data structure (to provide the id, the reset procedure etc). diff --git a/Documentation/networking/ti-cpsw.txt b/Documentation/networking/device_drivers/ti/cpsw.txt index d4d4c0751a09..d4d4c0751a09 100644 --- a/Documentation/networking/ti-cpsw.txt +++ b/Documentation/networking/device_drivers/ti/cpsw.txt diff --git a/Documentation/networking/tlan.txt b/Documentation/networking/device_drivers/ti/tlan.txt index 34550dfcef74..34550dfcef74 100644 --- a/Documentation/networking/tlan.txt +++ b/Documentation/networking/device_drivers/ti/tlan.txt diff --git a/Documentation/networking/spider_net.txt b/Documentation/networking/device_drivers/toshiba/spider_net.txt index b0b75f8463b3..b0b75f8463b3 100644 --- a/Documentation/networking/spider_net.txt +++ b/Documentation/networking/device_drivers/toshiba/spider_net.txt diff --git a/Documentation/networking/devlink-health.txt b/Documentation/networking/devlink-health.txt new file mode 100644 index 000000000000..1db3fbea0831 --- /dev/null +++ b/Documentation/networking/devlink-health.txt @@ -0,0 +1,86 @@ +The health mechanism is targeted for Real Time Alerting, in order to know when +something bad had happened to a PCI device +- Provide alert debug information +- Self healing +- If problem needs vendor support, provide a way to gather all needed debugging + information. + +The main idea is to unify and centralize driver health reports in the +generic devlink instance and allow the user to set different +attributes of the health reporting and recovery procedures. + +The devlink health reporter: +Device driver creates a "health reporter" per each error/health type. +Error/Health type can be a known/generic (eg pci error, fw error, rx/tx error) +or unknown (driver specific). +For each registered health reporter a driver can issue error/health reports +asynchronously. All health reports handling is done by devlink. +Device driver can provide specific callbacks for each "health reporter", e.g. + - Recovery procedures + - Diagnostics and object dump procedures + - OOB initial parameters +Different parts of the driver can register different types of health reporters +with different handlers. + +Once an error is reported, devlink health will do the following actions: + * A log is being send to the kernel trace events buffer + * Health status and statistics are being updated for the reporter instance + * Object dump is being taken and saved at the reporter instance (as long as + there is no other dump which is already stored) + * Auto recovery attempt is being done. Depends on: + - Auto-recovery configuration + - Grace period vs. time passed since last recover + +The user interface: +User can access/change each reporter's parameters and driver specific callbacks +via devlink, e.g per error type (per health reporter) + - Configure reporter's generic parameters (like: disable/enable auto recovery) + - Invoke recovery procedure + - Run diagnostics + - Object dump + +The devlink health interface (via netlink): +DEVLINK_CMD_HEALTH_REPORTER_GET + Retrieves status and configuration info per DEV and reporter. +DEVLINK_CMD_HEALTH_REPORTER_SET + Allows reporter-related configuration setting. +DEVLINK_CMD_HEALTH_REPORTER_RECOVER + Triggers a reporter's recovery procedure. +DEVLINK_CMD_HEALTH_REPORTER_DIAGNOSE + Retrieves diagnostics data from a reporter on a device. +DEVLINK_CMD_HEALTH_REPORTER_DUMP_GET + Retrieves the last stored dump. Devlink health + saves a single dump. If an dump is not already stored by the devlink + for this reporter, devlink generates a new dump. + dump output is defined by the reporter. +DEVLINK_CMD_HEALTH_REPORTER_DUMP_CLEAR + Clears the last saved dump file for the specified reporter. + + + netlink + +--------------------------+ + | | + | + | + | | | + +--------------------------+ + |request for ops + |(diagnose, + mlx5_core devlink |recover, + |dump) ++--------+ +--------------------------+ +| | | reporter| | +| | | +---------v----------+ | +| | ops execution | | | | +| <----------------------------------+ | | +| | | | | | +| | | + ^------------------+ | +| | | | request for ops | +| | | | (recover, dump) | +| | | | | +| | | +-+------------------+ | +| | health report | | health handler | | +| +-------------------------------> | | +| | | +--------------------+ | +| | health reporter create | | +| +----------------------------> | ++--------+ +--------------------------+ diff --git a/Documentation/networking/devlink-info-versions.rst b/Documentation/networking/devlink-info-versions.rst new file mode 100644 index 000000000000..c79ad8593383 --- /dev/null +++ b/Documentation/networking/devlink-info-versions.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) + +===================== +Devlink info versions +===================== + +board.id +======== + +Unique identifier of the board design. + +board.rev +========= + +Board design revision. + +board.manufacture +================= + +An identifier of the company or the facility which produced the part. + +fw.mgmt +======= + +Control unit firmware version. This firmware is responsible for house +keeping tasks, PHY control etc. but not the packet-by-packet data path +operation. + +fw.app +====== + +Data path microcode controlling high-speed packet processing. + +fw.undi +======= + +UNDI software, may include the UEFI driver, firmware or both. + +fw.ncsi +======= + +Version of the software responsible for supporting/handling the +Network Controller Sideband Interface. diff --git a/Documentation/networking/devlink-params-mlxsw.txt b/Documentation/networking/devlink-params-mlxsw.txt new file mode 100644 index 000000000000..c63ea9fc7009 --- /dev/null +++ b/Documentation/networking/devlink-params-mlxsw.txt @@ -0,0 +1,10 @@ +fw_load_policy [DEVICE, GENERIC] + Configuration mode: driverinit + +acl_region_rehash_interval [DEVICE, DRIVER-SPECIFIC] + Sets an interval for periodic ACL region rehashes. + The value is in milliseconds, minimal value is "3000". + Value "0" disables the periodic work. + The first rehash will be run right after value is set. + Type: u32 + Configuration mode: runtime diff --git a/Documentation/networking/devlink-params.txt b/Documentation/networking/devlink-params.txt index ae444ffe73ac..2d26434ddcf8 100644 --- a/Documentation/networking/devlink-params.txt +++ b/Documentation/networking/devlink-params.txt @@ -40,3 +40,12 @@ msix_vec_per_pf_min [DEVICE, GENERIC] for the device initialization. Value is same across all physical functions (PFs) in the device. Type: u32 + +fw_load_policy [DEVICE, GENERIC] + Controls the device's firmware loading policy. + Valid values: + * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_DRIVER (0) + Load firmware version preferred by the driver. + * DEVLINK_PARAM_FW_LOAD_POLICY_VALUE_FLASH (1) + Load firmware currently stored in flash. + Type: u8 diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index 25170ad7d25b..43ef767bc440 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -236,19 +236,6 @@ description. Design limitations ================== -DSA is a platform device driver -------------------------------- - -DSA is implemented as a DSA platform device driver which is convenient because -it will register the entire DSA switch tree attached to a master network device -in one-shot, facilitating the device creation and simplifying the device driver -model a bit, this comes however with a number of limitations: - -- building DSA and its switch drivers as modules is currently not working -- the device driver parenting does not necessarily reflect the original - bus/device the switch can be created from -- supporting non-MDIO and non-MMIO (platform) switches is not possible - Limits on the number of devices and ports ----------------------------------------- @@ -533,16 +520,12 @@ Bridge VLAN filtering function that the driver has to call for each VLAN the given port is a member of. A switchdev object is used to carry the VID and bridge flags. -- port_fdb_prepare: bridge layer function invoked when the bridge prepares the - installation of a Forwarding Database entry. If the operation is not - supported, this function should return -EOPNOTSUPP to inform the bridge code - to fallback to a software implementation. No hardware setup must be done in - this function. See port_fdb_add for this and details. - - port_fdb_add: bridge layer function invoked when the bridge wants to install a Forwarding Database entry, the switch hardware should be programmed with the specified address in the specified VLAN Id in the forwarding database - associated with this VLAN ID + associated with this VLAN ID. If the operation is not supported, this + function should return -EOPNOTSUPP to inform the bridge code to fallback to + a software implementation. Note: VLAN ID 0 corresponds to the port private database, which, in the context of DSA, would be the its port-based VLAN, used by the associated bridge device. diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt index 2196b824e96c..319e5e041f38 100644 --- a/Documentation/networking/filter.txt +++ b/Documentation/networking/filter.txt @@ -464,10 +464,11 @@ breakpoints: 0 1 JIT compiler ------------ -The Linux kernel has a built-in BPF JIT compiler for x86_64, SPARC, PowerPC, -ARM, ARM64, MIPS and s390 and can be enabled through CONFIG_BPF_JIT. The JIT -compiler is transparently invoked for each attached filter from user space -or for internal kernel users if it has been previously enabled by root: +The Linux kernel has a built-in BPF JIT compiler for x86_64, SPARC, +PowerPC, ARM, ARM64, MIPS, RISC-V and s390 and can be enabled through +CONFIG_BPF_JIT. The JIT compiler is transparently invoked for each +attached filter from user space or for internal kernel users if it has +been previously enabled by root: echo 1 > /proc/sys/net/core/bpf_jit_enable @@ -603,9 +604,10 @@ got from bpf_prog_create(), and 'ctx' the given context (e.g. skb pointer). All constraints and restrictions from bpf_check_classic() apply before a conversion to the new layout is being done behind the scenes! -Currently, the classic BPF format is being used for JITing on most 32-bit -architectures, whereas x86-64, aarch64, s390x, powerpc64, sparc64, arm32 perform -JIT compilation from eBPF instruction set. +Currently, the classic BPF format is being used for JITing on most +32-bit architectures, whereas x86-64, aarch64, s390x, powerpc64, +sparc64, arm32, riscv (RV64G) perform JIT compilation from eBPF +instruction set. Some core changes of the new internal format: @@ -827,7 +829,7 @@ tracing filters may do to maintain counters of events, for example. Register R9 is not used by socket filters either, but more complex filters may be running out of registers and would have to resort to spill/fill to stack. -Internal BPF can used as generic assembler for last step performance +Internal BPF can be used as a generic assembler for last step performance optimizations, socket filters and seccomp are using it as assembler. Tracing filters may use it as assembler to generate code from kernel. In kernel usage may not be bounded by security considerations, since generated internal BPF code @@ -865,7 +867,7 @@ Three LSB bits store instruction class which is one of: BPF_STX 0x03 BPF_STX 0x03 BPF_ALU 0x04 BPF_ALU 0x04 BPF_JMP 0x05 BPF_JMP 0x05 - BPF_RET 0x06 [ class 6 unused, for future if needed ] + BPF_RET 0x06 BPF_JMP32 0x06 BPF_MISC 0x07 BPF_ALU64 0x07 When BPF_CLASS(code) == BPF_ALU or BPF_JMP, 4th bit encodes source operand ... @@ -902,9 +904,9 @@ If BPF_CLASS(code) == BPF_ALU or BPF_ALU64 [ in eBPF ], BPF_OP(code) is one of: BPF_ARSH 0xc0 /* eBPF only: sign extending shift right */ BPF_END 0xd0 /* eBPF only: endianness conversion */ -If BPF_CLASS(code) == BPF_JMP, BPF_OP(code) is one of: +If BPF_CLASS(code) == BPF_JMP or BPF_JMP32 [ in eBPF ], BPF_OP(code) is one of: - BPF_JA 0x00 + BPF_JA 0x00 /* BPF_JMP only */ BPF_JEQ 0x10 BPF_JGT 0x20 BPF_JGE 0x30 @@ -912,8 +914,8 @@ If BPF_CLASS(code) == BPF_JMP, BPF_OP(code) is one of: BPF_JNE 0x50 /* eBPF only: jump != */ BPF_JSGT 0x60 /* eBPF only: signed '>' */ BPF_JSGE 0x70 /* eBPF only: signed '>=' */ - BPF_CALL 0x80 /* eBPF only: function call */ - BPF_EXIT 0x90 /* eBPF only: function return */ + BPF_CALL 0x80 /* eBPF BPF_JMP only: function call */ + BPF_EXIT 0x90 /* eBPF BPF_JMP only: function return */ BPF_JLT 0xa0 /* eBPF only: unsigned '<' */ BPF_JLE 0xb0 /* eBPF only: unsigned '<=' */ BPF_JSLT 0xc0 /* eBPF only: signed '<' */ @@ -936,8 +938,9 @@ Classic BPF wastes the whole BPF_RET class to represent a single 'ret' operation. Classic BPF_RET | BPF_K means copy imm32 into return register and perform function exit. eBPF is modeled to match CPU, so BPF_JMP | BPF_EXIT in eBPF means function exit only. The eBPF program needs to store return -value into register R0 before doing a BPF_EXIT. Class 6 in eBPF is currently -unused and reserved for future use. +value into register R0 before doing a BPF_EXIT. Class 6 in eBPF is used as +BPF_JMP32 to mean exactly the same operations as BPF_JMP, but with 32-bit wide +operands for the comparisons instead. For load and store instructions the 8-bit 'code' field is divided as: diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.rst index e74d8e1da0e2..36ca823a1122 100644 --- a/Documentation/networking/ieee802154.txt +++ b/Documentation/networking/ieee802154.rst @@ -1,54 +1,79 @@ - - Linux IEEE 802.15.4 implementation - +=============================== +IEEE 802.15.4 Developer's Guide +=============================== Introduction ============ The IEEE 802.15.4 working group focuses on standardization of the bottom two layers: Medium Access Control (MAC) and Physical access (PHY). And there are mainly two options available for upper layers: - - ZigBee - proprietary protocol from the ZigBee Alliance - - 6LoWPAN - IPv6 networking over low rate personal area networks + +- ZigBee - proprietary protocol from the ZigBee Alliance +- 6LoWPAN - IPv6 networking over low rate personal area networks The goal of the Linux-wpan is to provide a complete implementation of the IEEE 802.15.4 and 6LoWPAN protocols. IEEE 802.15.4 is a stack of protocols for organizing Low-Rate Wireless Personal Area Networks. The stack is composed of three main parts: - - IEEE 802.15.4 layer; We have chosen to use plain Berkeley socket API, - the generic Linux networking stack to transfer IEEE 802.15.4 data - messages and a special protocol over netlink for configuration/management - - MAC - provides access to shared channel and reliable data delivery - - PHY - represents device drivers +- IEEE 802.15.4 layer; We have chosen to use plain Berkeley socket API, + the generic Linux networking stack to transfer IEEE 802.15.4 data + messages and a special protocol over netlink for configuration/management +- MAC - provides access to shared channel and reliable data delivery +- PHY - represents device drivers Socket API ========== -int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); -..... +.. c:function:: int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0); The address family, socket addresses etc. are defined in the include/net/af_ieee802154.h header or in the special header in the userspace package (see either http://wpan.cakelab.org/ or the git tree at https://github.com/linux-wpan/wpan-tools). +6LoWPAN Linux implementation +============================ + +The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80 +octets of actual MAC payload once security is turned on, on a wireless link +with a link throughput of 250 kbps or less. The 6LoWPAN adaptation format +[RFC4944] was specified to carry IPv6 datagrams over such constrained links, +taking into account limited bandwidth, memory, or energy resources that are +expected in applications such as wireless Sensor Networks. [RFC4944] defines +a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header +to support the IPv6 minimum MTU requirement [RFC2460], and stateless header +compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the +relatively large IPv6 and UDP headers down to (in the best case) several bytes. + +In September 2011 the standard update was published - [RFC6282]. +It deprecates HC1 and HC2 compression and defines IPHC encoding format which is +used in this Linux implementation. + +All the code related to 6lowpan you may find in files: net/6lowpan/* +and net/ieee802154/6lowpan/* + +To setup a 6LoWPAN interface you need: +1. Add IEEE802.15.4 interface and set channel and PAN ID; +2. Add 6lowpan interface by command like: +# ip link add link wpan0 name lowpan0 type lowpan +3. Bring up 'lowpan0' interface -Kernel side -============= +Drivers +======= Like with WiFi, there are several types of devices implementing IEEE 802.15.4. 1) 'HardMAC'. The MAC layer is implemented in the device itself, the device - exports a management (e.g. MLME) and data API. +exports a management (e.g. MLME) and data API. 2) 'SoftMAC' or just radio. These types of devices are just radio transceivers - possibly with some kinds of acceleration like automatic CRC computation and - comparation, automagic ACK handling, address matching, etc. +possibly with some kinds of acceleration like automatic CRC computation and +comparation, automagic ACK handling, address matching, etc. Those types of devices require different approach to be hooked into Linux kernel. - HardMAC -======= +------- See the header include/net/ieee802154_netdev.h. You have to implement Linux net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family @@ -64,9 +89,8 @@ net_device with a pointer to struct ieee802154_mlme_ops instance. The fields assoc_req, assoc_resp, disassoc_req, start_req, and scan_req are optional. All other fields are required. - SoftMAC -======= +------- The MAC is the middle layer in the IEEE 802.15.4 Linux stack. This moment it provides interface for drivers registration and management of slave interfaces. @@ -79,99 +103,78 @@ This layer is going to be extended soon. See header include/net/mac802154.h and several drivers in drivers/net/ieee802154/. +Fake drivers +------------ + +In addition there is a driver available which simulates a real device with +SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option +provides a possibility to test and debug the stack without usage of real hardware. Device drivers API ================== The include/net/mac802154.h defines following functions: - - struct ieee802154_hw * - ieee802154_alloc_hw(size_t priv_data_len, const struct ieee802154_ops *ops): - allocation of IEEE 802.15.4 compatible hardware device - - void ieee802154_free_hw(struct ieee802154_hw *hw): - freeing allocated hardware device +.. c:function:: struct ieee802154_dev *ieee802154_alloc_device (size_t priv_size, struct ieee802154_ops *ops) - - int ieee802154_register_hw(struct ieee802154_hw *hw): - register PHY which is the allocated hardware device, in the system +Allocation of IEEE 802.15.4 compatible device. - - void ieee802154_unregister_hw(struct ieee802154_hw *hw): - freeing registered PHY +.. c:function:: void ieee802154_free_device(struct ieee802154_dev *dev) - - void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, - u8 lqi): - telling 802.15.4 module there is a new received frame in the skb with - the RF Link Quality Indicator (LQI) from the hardware device +Freeing allocated device. - - void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, - bool ifs_handling): - telling 802.15.4 module the frame in the skb is or going to be - transmitted through the hardware device +.. c:function:: int ieee802154_register_device(struct ieee802154_dev *dev) + +Register PHY in the system. + +.. c:function:: void ieee802154_unregister_device(struct ieee802154_dev *dev) + +Freeing registered PHY. + +.. c:function:: void ieee802154_rx_irqsafe(struct ieee802154_hw *hw, struct sk_buff *skb, u8 lqi): + +Telling 802.15.4 module there is a new received frame in the skb with +the RF Link Quality Indicator (LQI) from the hardware device. + +.. c:function:: void ieee802154_xmit_complete(struct ieee802154_hw *hw, struct sk_buff *skb, bool ifs_handling): + +Telling 802.15.4 module the frame in the skb is or going to be +transmitted through the hardware device The device driver must implement the following callbacks in the IEEE 802.15.4 -operations structure at least: -struct ieee802154_ops { - ... - int (*start)(struct ieee802154_hw *hw); - void (*stop)(struct ieee802154_hw *hw); - ... - int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); - int (*ed)(struct ieee802154_hw *hw, u8 *level); - int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); - ... -}; - - - int start(struct ieee802154_hw *hw): - handler that 802.15.4 module calls for the hardware device initialization. - - - void stop(struct ieee802154_hw *hw): - handler that 802.15.4 module calls for the hardware device cleanup. - - - int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): - handler that 802.15.4 module calls for each frame in the skb going to be - transmitted through the hardware device. - - - int ed(struct ieee802154_hw *hw, u8 *level): - handler that 802.15.4 module calls for Energy Detection from the hardware - device. - - - int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): - set radio for listening on specific channel of the hardware device. +operations structure at least:: -Moreover IEEE 802.15.4 device operations structure should be filled. + struct ieee802154_ops { + ... + int (*start)(struct ieee802154_hw *hw); + void (*stop)(struct ieee802154_hw *hw); + ... + int (*xmit_async)(struct ieee802154_hw *hw, struct sk_buff *skb); + int (*ed)(struct ieee802154_hw *hw, u8 *level); + int (*set_channel)(struct ieee802154_hw *hw, u8 page, u8 channel); + ... + }; -Fake drivers -============ +.. c:function:: int start(struct ieee802154_hw *hw): -In addition there is a driver available which simulates a real device with -SoftMAC (fakelb - IEEE 802.15.4 loopback driver) interface. This option -provides a possibility to test and debug the stack without usage of real hardware. +Handler that 802.15.4 module calls for the hardware device initialization. -See sources in drivers/net/ieee802154 folder for more details. +.. c:function:: void stop(struct ieee802154_hw *hw): +Handler that 802.15.4 module calls for the hardware device cleanup. -6LoWPAN Linux implementation -============================ +.. c:function:: int xmit_async(struct ieee802154_hw *hw, struct sk_buff *skb): -The IEEE 802.15.4 standard specifies an MTU of 127 bytes, yielding about 80 -octets of actual MAC payload once security is turned on, on a wireless link -with a link throughput of 250 kbps or less. The 6LoWPAN adaptation format -[RFC4944] was specified to carry IPv6 datagrams over such constrained links, -taking into account limited bandwidth, memory, or energy resources that are -expected in applications such as wireless Sensor Networks. [RFC4944] defines -a Mesh Addressing header to support sub-IP forwarding, a Fragmentation header -to support the IPv6 minimum MTU requirement [RFC2460], and stateless header -compression for IPv6 datagrams (LOWPAN_HC1 and LOWPAN_HC2) to reduce the -relatively large IPv6 and UDP headers down to (in the best case) several bytes. +Handler that 802.15.4 module calls for each frame in the skb going to be +transmitted through the hardware device. -In September 2011 the standard update was published - [RFC6282]. -It deprecates HC1 and HC2 compression and defines IPHC encoding format which is -used in this Linux implementation. +.. c:function:: int ed(struct ieee802154_hw *hw, u8 *level): -All the code related to 6lowpan you may find in files: net/6lowpan/* -and net/ieee802154/6lowpan/* +Handler that 802.15.4 module calls for Energy Detection from the hardware +device. -To setup a 6LoWPAN interface you need: -1. Add IEEE802.15.4 interface and set channel and PAN ID; -2. Add 6lowpan interface by command like: - # ip link add link wpan0 name lowpan0 type lowpan -3. Bring up 'lowpan0' interface +.. c:function:: int set_channel(struct ieee802154_hw *hw, u8 page, u8 channel): + +Set radio for listening on specific channel of the hardware device. + +Moreover IEEE 802.15.4 device operations structure should be filled. diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index bd89dae8d578..f0da1b001514 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -11,26 +11,31 @@ Contents: batman-adv can can_ucan_protocol - dpaa2/index - e100 - e1000 - e1000e - fm10k - igb - igbvf - ixgb - ixgbe - ixgbevf - i40e - iavf - ice + device_drivers/freescale/dpaa2/index + device_drivers/intel/e100 + device_drivers/intel/e1000 + device_drivers/intel/e1000e + device_drivers/intel/fm10k + device_drivers/intel/igb + device_drivers/intel/igbvf + device_drivers/intel/ixgb + device_drivers/intel/ixgbe + device_drivers/intel/ixgbevf + device_drivers/intel/i40e + device_drivers/intel/iavf + device_drivers/intel/ice + devlink-info-versions + ieee802154 kapi z8530book msg_zerocopy failover net_failover + phy + sfp-phylink alias bridge + snmp_counter .. only:: subproject diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index 163b5ff1073c..acdfb5d2bcaa 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -108,8 +108,8 @@ neigh/default/gc_thresh2 - INTEGER Default: 512 neigh/default/gc_thresh3 - INTEGER - Maximum number of neighbor entries allowed. Increase this - when using large numbers of interfaces and when communicating + Maximum number of non-PERMANENT neighbor entries allowed. Increase + this when using large numbers of interfaces and when communicating with large numbers of directly-connected peers. Default: 1024 @@ -316,6 +316,17 @@ tcp_frto - INTEGER By default it's enabled with a non-zero value. 0 disables F-RTO. +tcp_fwmark_accept - BOOLEAN + If set, incoming connections to listening sockets that do not have a + socket mark will set the mark of the accepting socket to the fwmark of + the incoming SYN packet. This will cause all packets on that connection + (starting from the first SYNACK) to be sent with that fwmark. The + listening socket's mark is unchanged. Listening sockets that already + have a fwmark set via setsockopt(SOL_SOCKET, SO_MARK, ...) are + unaffected. + + Default: 0 + tcp_invalid_ratelimit - INTEGER Limit the maximal rate for sending duplicate acknowledgments in response to incoming TCP packets that are for an existing @@ -359,6 +370,7 @@ tcp_l3mdev_accept - BOOLEAN derived from the listen socket to be bound to the L3 domain in which the packets originated. Only valid when the kernel was compiled with CONFIG_NET_L3_MASTER_DEV. + Default: 0 (disabled) tcp_low_latency - BOOLEAN This is a legacy option, it has no effect anymore. @@ -747,7 +759,7 @@ tcp_limit_output_bytes - INTEGER flows, for typical pfifo_fast qdiscs. tcp_limit_output_bytes limits the number of bytes on qdisc or device to reduce artificial RTT/cwnd and reduce bufferbloat. - Default: 262144 + Default: 1048576 (16 * 65536) tcp_challenge_ack_limit - INTEGER Limits number of Challenge ACK sent per second, as recommended @@ -762,6 +774,7 @@ udp_l3mdev_accept - BOOLEAN being received regardless of the L3 domain in which they originated. Only valid when the kernel was compiled with CONFIG_NET_L3_MASTER_DEV. + Default: 0 (disabled) udp_mem - vector of 3 INTEGERs: min, pressure, max Number of pages allowed for queueing by all UDP sockets. @@ -788,6 +801,16 @@ udp_wmem_min - INTEGER total pages of UDP sockets exceed udp_mem pressure. The unit is byte. Default: 4K +RAW variables: + +raw_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. + Default: 1 (enabled) + CIPSOv4 Variables: cipso_cache_enable - BOOLEAN diff --git a/Documentation/networking/msg_zerocopy.rst b/Documentation/networking/msg_zerocopy.rst index fe46d4867e2d..18c1415e7bfa 100644 --- a/Documentation/networking/msg_zerocopy.rst +++ b/Documentation/networking/msg_zerocopy.rst @@ -7,7 +7,7 @@ Intro ===== The MSG_ZEROCOPY flag enables copy avoidance for socket send calls. -The feature is currently implemented for TCP sockets. +The feature is currently implemented for TCP and UDP sockets. Opportunity and Caveats diff --git a/Documentation/networking/netdev-features.txt b/Documentation/networking/netdev-features.txt index c4a54c162547..58dd1c1e3c65 100644 --- a/Documentation/networking/netdev-features.txt +++ b/Documentation/networking/netdev-features.txt @@ -115,7 +115,7 @@ set, be it TCPv4 (when NETIF_F_TSO is enabled) or TCPv6 (NETIF_F_TSO6). * Transmit UDP segmentation offload -NETIF_F_GSO_UDP_GSO_L4 accepts a single UDP header with a payload that exceeds +NETIF_F_GSO_UDP_L4 accepts a single UDP header with a payload that exceeds gso_size. On segmentation, it segments the payload on gso_size boundaries and replicates the network and UDP headers (fixing up the last one if less than gso_size). diff --git a/Documentation/networking/nf_conntrack-sysctl.txt b/Documentation/networking/nf_conntrack-sysctl.txt index 1669dc2419fd..f75c2ce6e136 100644 --- a/Documentation/networking/nf_conntrack-sysctl.txt +++ b/Documentation/networking/nf_conntrack-sysctl.txt @@ -157,7 +157,16 @@ nf_conntrack_udp_timeout - INTEGER (seconds) default 30 nf_conntrack_udp_timeout_stream - INTEGER (seconds) - default 180 + default 120 This extended timeout will be used in case there is an UDP stream detected. + +nf_conntrack_gre_timeout - INTEGER (seconds) + default 30 + +nf_conntrack_gre_timeout_stream - INTEGER (seconds) + default 180 + + This extended timeout will be used in case there is an GRE stream + detected. diff --git a/Documentation/networking/operstates.txt b/Documentation/networking/operstates.txt index 355c6d8ef8ad..b203d1334822 100644 --- a/Documentation/networking/operstates.txt +++ b/Documentation/networking/operstates.txt @@ -22,8 +22,9 @@ and changeable from userspace under certain rules. 2. Querying from userspace Both admin and operational state can be queried via the netlink -operation RTM_GETLINK. It is also possible to subscribe to RTMGRP_LINK -to be notified of updates. This is important for setting from userspace. +operation RTM_GETLINK. It is also possible to subscribe to RTNLGRP_LINK +to be notified of updates while the interface is admin up. This is +important for setting from userspace. These values contain interface state: @@ -101,8 +102,9 @@ because some driver controlled protocol establishment has to complete. Corresponding functions are netif_dormant_on() to set the flag, netif_dormant_off() to clear it and netif_dormant() to query. -On device allocation, networking core sets the flags equivalent to -netif_carrier_ok() and !netif_dormant(). +On device allocation, both flags __LINK_STATE_NOCARRIER and +__LINK_STATE_DORMANT are cleared, so the effective state is equivalent +to netif_carrier_ok() and !netif_dormant(). Whenever the driver CHANGES one of these flags, a workqueue event is @@ -133,11 +135,11 @@ netif_carrier_ok() && !netif_dormant() is set by the driver. Afterwards, the userspace application can set IFLA_OPERSTATE to IF_OPER_DORMANT or IF_OPER_UP as long as the driver does not set netif_carrier_off() or netif_dormant_on(). Changes made by userspace -are multicasted on the netlink group RTMGRP_LINK. +are multicasted on the netlink group RTNLGRP_LINK. So basically a 802.1X supplicant interacts with the kernel like this: --subscribe to RTMGRP_LINK +-subscribe to RTNLGRP_LINK -set IFLA_LINKMODE to 1 via RTM_SETLINK -query RTM_GETLINK once to get initial state -if initial flags are not (IFF_LOWER_UP && !IFF_DORMANT), wait until diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst new file mode 100644 index 000000000000..0dd90d7df5ec --- /dev/null +++ b/Documentation/networking/phy.rst @@ -0,0 +1,447 @@ +===================== +PHY Abstraction Layer +===================== + +Purpose +======= + +Most network devices consist of set of registers which provide an interface +to a MAC layer, which communicates with the physical connection through a +PHY. The PHY concerns itself with negotiating link parameters with the link +partner on the other side of the network connection (typically, an ethernet +cable), and provides a register interface to allow drivers to determine what +settings were chosen, and to configure what settings are allowed. + +While these devices are distinct from the network devices, and conform to a +standard layout for the registers, it has been common practice to integrate +the PHY management code with the network driver. This has resulted in large +amounts of redundant code. Also, on embedded systems with multiple (and +sometimes quite different) ethernet controllers connected to the same +management bus, it is difficult to ensure safe use of the bus. + +Since the PHYs are devices, and the management busses through which they are +accessed are, in fact, busses, the PHY Abstraction Layer treats them as such. +In doing so, it has these goals: + +#. Increase code-reuse +#. Increase overall code-maintainability +#. Speed development time for new network drivers, and for new systems + +Basically, this layer is meant to provide an interface to PHY devices which +allows network driver writers to write as little code as possible, while +still providing a full feature set. + +The MDIO bus +============ + +Most network devices are connected to a PHY by means of a management bus. +Different devices use different busses (though some share common interfaces). +In order to take advantage of the PAL, each bus interface needs to be +registered as a distinct device. + +#. read and write functions must be implemented. Their prototypes are:: + + int write(struct mii_bus *bus, int mii_id, int regnum, u16 value); + int read(struct mii_bus *bus, int mii_id, int regnum); + + mii_id is the address on the bus for the PHY, and regnum is the register + number. These functions are guaranteed not to be called from interrupt + time, so it is safe for them to block, waiting for an interrupt to signal + the operation is complete + +#. A reset function is optional. This is used to return the bus to an + initialized state. + +#. A probe function is needed. This function should set up anything the bus + driver needs, setup the mii_bus structure, and register with the PAL using + mdiobus_register. Similarly, there's a remove function to undo all of + that (use mdiobus_unregister). + +#. Like any driver, the device_driver structure must be configured, and init + exit functions are used to register the driver. + +#. The bus must also be declared somewhere as a device, and registered. + +As an example for how one driver implemented an mdio bus driver, see +drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file +for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/") + +(RG)MII/electrical interface considerations +=========================================== + +The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin +electrical signal interface using a synchronous 125Mhz clock signal and several +data lines. Due to this design decision, a 1.5ns to 2ns delay must be added +between the clock line (RXC or TXC) and the data lines to let the PHY (clock +sink) have enough setup and hold times to sample the data lines correctly. The +PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let +the PHY driver and optionally the MAC driver, implement the required delay. The +values of phy_interface_t must be understood from the perspective of the PHY +device itself, leading to the following: + +* PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any + internal delay by itself, it assumes that either the Ethernet MAC (if capable + or the PCB traces) insert the correct 1.5-2ns delay + +* PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay + for the transmit data lines (TXD[3:0]) processed by the PHY device + +* PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay + for the receive data lines (RXD[3:0]) processed by the PHY device + +* PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for + both transmit AND receive data lines from/to the PHY device + +Whenever possible, use the PHY side RGMII delay for these reasons: + +* PHY devices may offer sub-nanosecond granularity in how they allow a + receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such + precision may be required to account for differences in PCB trace lengths + +* PHY devices are typically qualified for a large range of applications + (industrial, medical, automotive...), and they provide a constant and + reliable delay across temperature/pressure/voltage ranges + +* PHY device drivers in PHYLIB being reusable by nature, being able to + configure correctly a specified delay enables more designs with similar delay + requirements to be operate correctly + +For cases where the PHY is not capable of providing this delay, but the +Ethernet MAC driver is capable of doing so, the correct phy_interface_t value +should be PHY_INTERFACE_MODE_RGMII, and the Ethernet MAC driver should be +configured correctly in order to provide the required transmit and/or receive +side delay from the perspective of the PHY device. Conversely, if the Ethernet +MAC driver looks at the phy_interface_t value, for any other mode but +PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are +disabled. + +In case neither the Ethernet MAC, nor the PHY are capable of providing the +required delays, as defined per the RGMII standard, several options may be +available: + +* Some SoCs may offer a pin pad/mux/controller capable of configuring a given + set of pins'strength, delays, and voltage; and it may be a suitable + option to insert the expected 2ns RGMII delay. + +* Modifying the PCB design to include a fixed delay (e.g: using a specifically + designed serpentine), which may not require software configuration at all. + +Common problems with RGMII delay mismatch +----------------------------------------- + +When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this +will most likely result in the clock and data line signals to be unstable when +the PHY or MAC take a snapshot of these signals to translate them into logical +1 or 0 states and reconstruct the data being transmitted/received. Typical +symptoms include: + +* Transmission/reception partially works, and there is frequent or occasional + packet loss observed + +* Ethernet MAC may report some or all packets ingressing with a FCS/CRC error, + or just discard them all + +* Switching to lower speeds such as 10/100Mbits/sec makes the problem go away + (since there is enough setup/hold time in that case) + +Connecting to a PHY +=================== + +Sometime during startup, the network driver needs to establish a connection +between the PHY device, and the network device. At this time, the PHY's bus +and drivers need to all have been loaded, so it is ready for the connection. +At this point, there are several ways to connect to the PHY: + +#. The PAL handles everything, and only calls the network driver when + the link state changes, so it can react. + +#. The PAL handles everything except interrupts (usually because the + controller has the interrupt registers). + +#. The PAL handles everything, but checks in with the driver every second, + allowing the network driver to react first to any changes before the PAL + does. + +#. The PAL serves only as a library of functions, with the network device + manually calling functions to update status, and configure the PHY + + +Letting the PHY Abstraction Layer do Everything +=============================================== + +If you choose option 1 (The hope is that every driver can, but to still be +useful to drivers that can't), connecting to the PHY is simple: + +First, you need a function to react to changes in the link state. This +function follows this protocol:: + + static void adjust_link(struct net_device *dev); + +Next, you need to know the device name of the PHY connected to this device. +The name will look something like, "0:00", where the first number is the +bus id, and the second is the PHY's address on that bus. Typically, +the bus is responsible for making its ID unique. + +Now, to connect, just call this function:: + + phydev = phy_connect(dev, phy_name, &adjust_link, interface); + +*phydev* is a pointer to the phy_device structure which represents the PHY. +If phy_connect is successful, it will return the pointer. dev, here, is the +pointer to your net_device. Once done, this function will have started the +PHY's software state machine, and registered for the PHY's interrupt, if it +has one. The phydev structure will be populated with information about the +current state, though the PHY will not yet be truly operational at this +point. + +PHY-specific flags should be set in phydev->dev_flags prior to the call +to phy_connect() such that the underlying PHY driver can check for flags +and perform specific operations based on them. +This is useful if the system has put hardware restrictions on +the PHY/controller, of which the PHY needs to be aware. + +*interface* is a u32 which specifies the connection type used +between the controller and the PHY. Examples are GMII, MII, +RGMII, and SGMII. For a full list, see include/linux/phy.h + +Now just make sure that phydev->supported and phydev->advertising have any +values pruned from them which don't make sense for your controller (a 10/100 +controller may be connected to a gigabit capable PHY, so you would need to +mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions +for these bitfields. Note that you should not SET any bits, except the +SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get +put into an unsupported state. + +Lastly, once the controller is ready to handle network traffic, you call +phy_start(phydev). This tells the PAL that you are ready, and configures the +PHY to connect to the network. If the MAC interrupt of your network driver +also handles PHY status changes, just set phydev->irq to PHY_IGNORE_INTERRUPT +before you call phy_start and use phy_mac_interrupt() from the network +driver. If you don't want to use interrupts, set phydev->irq to PHY_POLL. +phy_start() enables the PHY interrupts (if applicable) and starts the +phylib state machine. + +When you want to disconnect from the network (even if just briefly), you call +phy_stop(phydev). This function also stops the phylib state machine and +disables PHY interrupts. + +Pause frames / flow control +=========================== + +The PHY does not participate directly in flow control/pause frames except by +making sure that the SUPPORTED_Pause and SUPPORTED_AsymPause bits are set in +MII_ADVERTISE to indicate towards the link partner that the Ethernet MAC +controller supports such a thing. Since flow control/pause frames generation +involves the Ethernet MAC driver, it is recommended that this driver takes care +of properly indicating advertisement and support for such features by setting +the SUPPORTED_Pause and SUPPORTED_AsymPause bits accordingly. This can be done +either before or after phy_connect() and/or as a result of implementing the +ethtool::set_pauseparam feature. + + +Keeping Close Tabs on the PAL +============================= + +It is possible that the PAL's built-in state machine needs a little help to +keep your network device and the PHY properly in sync. If so, you can +register a helper function when connecting to the PHY, which will be called +every second before the state machine reacts to any changes. To do this, you +need to manually call phy_attach() and phy_prepare_link(), and then call +phy_start_machine() with the second argument set to point to your special +handler. + +Currently there are no examples of how to use this functionality, and testing +on it has been limited because the author does not have any drivers which use +it (they all use option 1). So Caveat Emptor. + +Doing it all yourself +===================== + +There's a remote chance that the PAL's built-in state machine cannot track +the complex interactions between the PHY and your network device. If this is +so, you can simply call phy_attach(), and not call phy_start_machine or +phy_prepare_link(). This will mean that phydev->state is entirely yours to +handle (phy_start and phy_stop toggle between some of the states, so you +might need to avoid them). + +An effort has been made to make sure that useful functionality can be +accessed without the state-machine running, and most of these functions are +descended from functions which did not interact with a complex state-machine. +However, again, no effort has been made so far to test running without the +state machine, so tryer beware. + +Here is a brief rundown of the functions:: + + int phy_read(struct phy_device *phydev, u16 regnum); + int phy_write(struct phy_device *phydev, u16 regnum, u16 val); + +Simple read/write primitives. They invoke the bus's read/write function +pointers. +:: + + void phy_print_status(struct phy_device *phydev); + +A convenience function to print out the PHY status neatly. +:: + + void phy_request_interrupt(struct phy_device *phydev); + +Requests the IRQ for the PHY interrupts. +:: + + struct phy_device * phy_attach(struct net_device *dev, const char *phy_id, + phy_interface_t interface); + +Attaches a network device to a particular PHY, binding the PHY to a generic +driver if none was found during bus initialization. +:: + + int phy_start_aneg(struct phy_device *phydev); + +Using variables inside the phydev structure, either configures advertising +and resets autonegotiation, or disables autonegotiation, and configures +forced settings. +:: + + static inline int phy_read_status(struct phy_device *phydev); + +Fills the phydev structure with up-to-date information about the current +settings in the PHY. +:: + + int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd); + +Ethtool convenience functions. +:: + + int phy_mii_ioctl(struct phy_device *phydev, + struct mii_ioctl_data *mii_data, int cmd); + +The MII ioctl. Note that this function will completely screw up the state +machine if you write registers like BMCR, BMSR, ADVERTISE, etc. Best to +use this only to write registers which are not standard, and don't set off +a renegotiation. + +PHY Device Drivers +================== + +With the PHY Abstraction Layer, adding support for new PHYs is +quite easy. In some cases, no work is required at all! However, +many PHYs require a little hand-holding to get up-and-running. + +Generic PHY driver +------------------ + +If the desired PHY doesn't have any errata, quirks, or special +features you want to support, then it may be best to not add +support, and let the PHY Abstraction Layer's Generic PHY Driver +do all of the work. + +Writing a PHY driver +-------------------- + +If you do need to write a PHY driver, the first thing to do is +make sure it can be matched with an appropriate PHY device. +This is done during bus initialization by reading the device's +UID (stored in registers 2 and 3), then comparing it to each +driver's phy_id field by ANDing it with each driver's +phy_id_mask field. Also, it needs a name. Here's an example:: + + static struct phy_driver dm9161_driver = { + .phy_id = 0x0181b880, + .name = "Davicom DM9161E", + .phy_id_mask = 0x0ffffff0, + ... + } + +Next, you need to specify what features (speed, duplex, autoneg, +etc) your PHY device and driver support. Most PHYs support +PHY_BASIC_FEATURES, but you can look in include/mii.h for other +features. + +Each driver consists of a number of function pointers, documented +in include/linux/phy.h under the phy_driver structure. + +Of these, only config_aneg and read_status are required to be +assigned by the driver code. The rest are optional. Also, it is +preferred to use the generic phy driver's versions of these two +functions if at all possible: genphy_read_status and +genphy_config_aneg. If this is not possible, it is likely that +you only need to perform some actions before and after invoking +these functions, and so your functions will wrap the generic +ones. + +Feel free to look at the Marvell, Cicada, and Davicom drivers in +drivers/net/phy/ for examples (the lxt and qsemi drivers have +not been tested as of this writing). + +The PHY's MMD register accesses are handled by the PAL framework +by default, but can be overridden by a specific PHY driver if +required. This could be the case if a PHY was released for +manufacturing before the MMD PHY register definitions were +standardized by the IEEE. Most modern PHYs will be able to use +the generic PAL framework for accessing the PHY's MMD registers. +An example of such usage is for Energy Efficient Ethernet support, +implemented in the PAL. This support uses the PAL to access MMD +registers for EEE query and configuration if the PHY supports +the IEEE standard access mechanisms, or can use the PHY's specific +access interfaces if overridden by the specific PHY driver. See +the Micrel driver in drivers/net/phy/ for an example of how this +can be implemented. + +Board Fixups +============ + +Sometimes the specific interaction between the platform and the PHY requires +special handling. For instance, to change where the PHY's clock input is, +or to add a delay to account for latency issues in the data path. In order +to support such contingencies, the PHY Layer allows platform code to register +fixups to be run when the PHY is brought up (or subsequently reset). + +When the PHY Layer brings up a PHY it checks to see if there are any fixups +registered for it, matching based on UID (contained in the PHY device's phy_id +field) and the bus identifier (contained in phydev->dev.bus_id). Both must +match, however two constants, PHY_ANY_ID and PHY_ANY_UID, are provided as +wildcards for the bus ID and UID, respectively. + +When a match is found, the PHY layer will invoke the run function associated +with the fixup. This function is passed a pointer to the phy_device of +interest. It should therefore only operate on that PHY. + +The platform code can either register the fixup using phy_register_fixup():: + + int phy_register_fixup(const char *phy_id, + u32 phy_uid, u32 phy_uid_mask, + int (*run)(struct phy_device *)); + +Or using one of the two stubs, phy_register_fixup_for_uid() and +phy_register_fixup_for_id():: + + int phy_register_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask, + int (*run)(struct phy_device *)); + int phy_register_fixup_for_id(const char *phy_id, + int (*run)(struct phy_device *)); + +The stubs set one of the two matching criteria, and set the other one to +match anything. + +When phy_register_fixup() or \*_for_uid()/\*_for_id() is called at module, +unregister fixup and free allocate memory are required. + +Call one of following function before unloading module:: + + int phy_unregister_fixup(const char *phy_id, u32 phy_uid, u32 phy_uid_mask); + int phy_unregister_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask); + int phy_register_fixup_for_id(const char *phy_id); + +Standards +========= + +IEEE Standard 802.3: CSMA/CD Access Method and Physical Layer Specifications, Section Two: +http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf + +RGMII v1.3: +http://web.archive.org/web/20160303212629/http://www.hp.com/rnd/pdfs/RGMIIv1_3.pdf + +RGMII v2.0: +http://web.archive.org/web/20160303171328/http://www.hp.com/rnd/pdfs/RGMIIv2_0_final_hp.pdf diff --git a/Documentation/networking/phy.txt b/Documentation/networking/phy.txt deleted file mode 100644 index bdec0f700bc1..000000000000 --- a/Documentation/networking/phy.txt +++ /dev/null @@ -1,427 +0,0 @@ - -------- -PHY Abstraction Layer -(Updated 2008-04-08) - -Purpose - - Most network devices consist of set of registers which provide an interface - to a MAC layer, which communicates with the physical connection through a - PHY. The PHY concerns itself with negotiating link parameters with the link - partner on the other side of the network connection (typically, an ethernet - cable), and provides a register interface to allow drivers to determine what - settings were chosen, and to configure what settings are allowed. - - While these devices are distinct from the network devices, and conform to a - standard layout for the registers, it has been common practice to integrate - the PHY management code with the network driver. This has resulted in large - amounts of redundant code. Also, on embedded systems with multiple (and - sometimes quite different) ethernet controllers connected to the same - management bus, it is difficult to ensure safe use of the bus. - - Since the PHYs are devices, and the management busses through which they are - accessed are, in fact, busses, the PHY Abstraction Layer treats them as such. - In doing so, it has these goals: - - 1) Increase code-reuse - 2) Increase overall code-maintainability - 3) Speed development time for new network drivers, and for new systems - - Basically, this layer is meant to provide an interface to PHY devices which - allows network driver writers to write as little code as possible, while - still providing a full feature set. - -The MDIO bus - - Most network devices are connected to a PHY by means of a management bus. - Different devices use different busses (though some share common interfaces). - In order to take advantage of the PAL, each bus interface needs to be - registered as a distinct device. - - 1) read and write functions must be implemented. Their prototypes are: - - int write(struct mii_bus *bus, int mii_id, int regnum, u16 value); - int read(struct mii_bus *bus, int mii_id, int regnum); - - mii_id is the address on the bus for the PHY, and regnum is the register - number. These functions are guaranteed not to be called from interrupt - time, so it is safe for them to block, waiting for an interrupt to signal - the operation is complete - - 2) A reset function is optional. This is used to return the bus to an - initialized state. - - 3) A probe function is needed. This function should set up anything the bus - driver needs, setup the mii_bus structure, and register with the PAL using - mdiobus_register. Similarly, there's a remove function to undo all of - that (use mdiobus_unregister). - - 4) Like any driver, the device_driver structure must be configured, and init - exit functions are used to register the driver. - - 5) The bus must also be declared somewhere as a device, and registered. - - As an example for how one driver implemented an mdio bus driver, see - drivers/net/ethernet/freescale/fsl_pq_mdio.c and an associated DTS file - for one of the users. (e.g. "git grep fsl,.*-mdio arch/powerpc/boot/dts/") - -(RG)MII/electrical interface considerations - - The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin - electrical signal interface using a synchronous 125Mhz clock signal and several - data lines. Due to this design decision, a 1.5ns to 2ns delay must be added - between the clock line (RXC or TXC) and the data lines to let the PHY (clock - sink) have enough setup and hold times to sample the data lines correctly. The - PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let - the PHY driver and optionally the MAC driver, implement the required delay. The - values of phy_interface_t must be understood from the perspective of the PHY - device itself, leading to the following: - - * PHY_INTERFACE_MODE_RGMII: the PHY is not responsible for inserting any - internal delay by itself, it assumes that either the Ethernet MAC (if capable - or the PCB traces) insert the correct 1.5-2ns delay - - * PHY_INTERFACE_MODE_RGMII_TXID: the PHY should insert an internal delay - for the transmit data lines (TXD[3:0]) processed by the PHY device - - * PHY_INTERFACE_MODE_RGMII_RXID: the PHY should insert an internal delay - for the receive data lines (RXD[3:0]) processed by the PHY device - - * PHY_INTERFACE_MODE_RGMII_ID: the PHY should insert internal delays for - both transmit AND receive data lines from/to the PHY device - - Whenever possible, use the PHY side RGMII delay for these reasons: - - * PHY devices may offer sub-nanosecond granularity in how they allow a - receiver/transmitter side delay (e.g: 0.5, 1.0, 1.5ns) to be specified. Such - precision may be required to account for differences in PCB trace lengths - - * PHY devices are typically qualified for a large range of applications - (industrial, medical, automotive...), and they provide a constant and - reliable delay across temperature/pressure/voltage ranges - - * PHY device drivers in PHYLIB being reusable by nature, being able to - configure correctly a specified delay enables more designs with similar delay - requirements to be operate correctly - - For cases where the PHY is not capable of providing this delay, but the - Ethernet MAC driver is capable of doing so, the correct phy_interface_t value - should be PHY_INTERFACE_MODE_RGMII, and the Ethernet MAC driver should be - configured correctly in order to provide the required transmit and/or receive - side delay from the perspective of the PHY device. Conversely, if the Ethernet - MAC driver looks at the phy_interface_t value, for any other mode but - PHY_INTERFACE_MODE_RGMII, it should make sure that the MAC-level delays are - disabled. - - In case neither the Ethernet MAC, nor the PHY are capable of providing the - required delays, as defined per the RGMII standard, several options may be - available: - - * Some SoCs may offer a pin pad/mux/controller capable of configuring a given - set of pins'strength, delays, and voltage; and it may be a suitable - option to insert the expected 2ns RGMII delay. - - * Modifying the PCB design to include a fixed delay (e.g: using a specifically - designed serpentine), which may not require software configuration at all. - -Common problems with RGMII delay mismatch - - When there is a RGMII delay mismatch between the Ethernet MAC and the PHY, this - will most likely result in the clock and data line signals to be unstable when - the PHY or MAC take a snapshot of these signals to translate them into logical - 1 or 0 states and reconstruct the data being transmitted/received. Typical - symptoms include: - - * Transmission/reception partially works, and there is frequent or occasional - packet loss observed - - * Ethernet MAC may report some or all packets ingressing with a FCS/CRC error, - or just discard them all - - * Switching to lower speeds such as 10/100Mbits/sec makes the problem go away - (since there is enough setup/hold time in that case) - - -Connecting to a PHY - - Sometime during startup, the network driver needs to establish a connection - between the PHY device, and the network device. At this time, the PHY's bus - and drivers need to all have been loaded, so it is ready for the connection. - At this point, there are several ways to connect to the PHY: - - 1) The PAL handles everything, and only calls the network driver when - the link state changes, so it can react. - - 2) The PAL handles everything except interrupts (usually because the - controller has the interrupt registers). - - 3) The PAL handles everything, but checks in with the driver every second, - allowing the network driver to react first to any changes before the PAL - does. - - 4) The PAL serves only as a library of functions, with the network device - manually calling functions to update status, and configure the PHY - - -Letting the PHY Abstraction Layer do Everything - - If you choose option 1 (The hope is that every driver can, but to still be - useful to drivers that can't), connecting to the PHY is simple: - - First, you need a function to react to changes in the link state. This - function follows this protocol: - - static void adjust_link(struct net_device *dev); - - Next, you need to know the device name of the PHY connected to this device. - The name will look something like, "0:00", where the first number is the - bus id, and the second is the PHY's address on that bus. Typically, - the bus is responsible for making its ID unique. - - Now, to connect, just call this function: - - phydev = phy_connect(dev, phy_name, &adjust_link, interface); - - phydev is a pointer to the phy_device structure which represents the PHY. If - phy_connect is successful, it will return the pointer. dev, here, is the - pointer to your net_device. Once done, this function will have started the - PHY's software state machine, and registered for the PHY's interrupt, if it - has one. The phydev structure will be populated with information about the - current state, though the PHY will not yet be truly operational at this - point. - - PHY-specific flags should be set in phydev->dev_flags prior to the call - to phy_connect() such that the underlying PHY driver can check for flags - and perform specific operations based on them. - This is useful if the system has put hardware restrictions on - the PHY/controller, of which the PHY needs to be aware. - - interface is a u32 which specifies the connection type used - between the controller and the PHY. Examples are GMII, MII, - RGMII, and SGMII. For a full list, see include/linux/phy.h - - Now just make sure that phydev->supported and phydev->advertising have any - values pruned from them which don't make sense for your controller (a 10/100 - controller may be connected to a gigabit capable PHY, so you would need to - mask off SUPPORTED_1000baseT*). See include/linux/ethtool.h for definitions - for these bitfields. Note that you should not SET any bits, except the - SUPPORTED_Pause and SUPPORTED_AsymPause bits (see below), or the PHY may get - put into an unsupported state. - - Lastly, once the controller is ready to handle network traffic, you call - phy_start(phydev). This tells the PAL that you are ready, and configures the - PHY to connect to the network. If you want to handle your own interrupts, - just set phydev->irq to PHY_IGNORE_INTERRUPT before you call phy_start. - Similarly, if you don't want to use interrupts, set phydev->irq to PHY_POLL. - - When you want to disconnect from the network (even if just briefly), you call - phy_stop(phydev). - -Pause frames / flow control - - The PHY does not participate directly in flow control/pause frames except by - making sure that the SUPPORTED_Pause and SUPPORTED_AsymPause bits are set in - MII_ADVERTISE to indicate towards the link partner that the Ethernet MAC - controller supports such a thing. Since flow control/pause frames generation - involves the Ethernet MAC driver, it is recommended that this driver takes care - of properly indicating advertisement and support for such features by setting - the SUPPORTED_Pause and SUPPORTED_AsymPause bits accordingly. This can be done - either before or after phy_connect() and/or as a result of implementing the - ethtool::set_pauseparam feature. - - -Keeping Close Tabs on the PAL - - It is possible that the PAL's built-in state machine needs a little help to - keep your network device and the PHY properly in sync. If so, you can - register a helper function when connecting to the PHY, which will be called - every second before the state machine reacts to any changes. To do this, you - need to manually call phy_attach() and phy_prepare_link(), and then call - phy_start_machine() with the second argument set to point to your special - handler. - - Currently there are no examples of how to use this functionality, and testing - on it has been limited because the author does not have any drivers which use - it (they all use option 1). So Caveat Emptor. - -Doing it all yourself - - There's a remote chance that the PAL's built-in state machine cannot track - the complex interactions between the PHY and your network device. If this is - so, you can simply call phy_attach(), and not call phy_start_machine or - phy_prepare_link(). This will mean that phydev->state is entirely yours to - handle (phy_start and phy_stop toggle between some of the states, so you - might need to avoid them). - - An effort has been made to make sure that useful functionality can be - accessed without the state-machine running, and most of these functions are - descended from functions which did not interact with a complex state-machine. - However, again, no effort has been made so far to test running without the - state machine, so tryer beware. - - Here is a brief rundown of the functions: - - int phy_read(struct phy_device *phydev, u16 regnum); - int phy_write(struct phy_device *phydev, u16 regnum, u16 val); - - Simple read/write primitives. They invoke the bus's read/write function - pointers. - - void phy_print_status(struct phy_device *phydev); - - A convenience function to print out the PHY status neatly. - - int phy_start_interrupts(struct phy_device *phydev); - int phy_stop_interrupts(struct phy_device *phydev); - - Requests the IRQ for the PHY interrupts, then enables them for - start, or disables then frees them for stop. - - struct phy_device * phy_attach(struct net_device *dev, const char *phy_id, - phy_interface_t interface); - - Attaches a network device to a particular PHY, binding the PHY to a generic - driver if none was found during bus initialization. - - int phy_start_aneg(struct phy_device *phydev); - - Using variables inside the phydev structure, either configures advertising - and resets autonegotiation, or disables autonegotiation, and configures - forced settings. - - static inline int phy_read_status(struct phy_device *phydev); - - Fills the phydev structure with up-to-date information about the current - settings in the PHY. - - int phy_ethtool_sset(struct phy_device *phydev, struct ethtool_cmd *cmd); - - Ethtool convenience functions. - - int phy_mii_ioctl(struct phy_device *phydev, - struct mii_ioctl_data *mii_data, int cmd); - - The MII ioctl. Note that this function will completely screw up the state - machine if you write registers like BMCR, BMSR, ADVERTISE, etc. Best to - use this only to write registers which are not standard, and don't set off - a renegotiation. - - -PHY Device Drivers - - With the PHY Abstraction Layer, adding support for new PHYs is - quite easy. In some cases, no work is required at all! However, - many PHYs require a little hand-holding to get up-and-running. - -Generic PHY driver - - If the desired PHY doesn't have any errata, quirks, or special - features you want to support, then it may be best to not add - support, and let the PHY Abstraction Layer's Generic PHY Driver - do all of the work. - -Writing a PHY driver - - If you do need to write a PHY driver, the first thing to do is - make sure it can be matched with an appropriate PHY device. - This is done during bus initialization by reading the device's - UID (stored in registers 2 and 3), then comparing it to each - driver's phy_id field by ANDing it with each driver's - phy_id_mask field. Also, it needs a name. Here's an example: - - static struct phy_driver dm9161_driver = { - .phy_id = 0x0181b880, - .name = "Davicom DM9161E", - .phy_id_mask = 0x0ffffff0, - ... - } - - Next, you need to specify what features (speed, duplex, autoneg, - etc) your PHY device and driver support. Most PHYs support - PHY_BASIC_FEATURES, but you can look in include/mii.h for other - features. - - Each driver consists of a number of function pointers, documented - in include/linux/phy.h under the phy_driver structure. - - Of these, only config_aneg and read_status are required to be - assigned by the driver code. The rest are optional. Also, it is - preferred to use the generic phy driver's versions of these two - functions if at all possible: genphy_read_status and - genphy_config_aneg. If this is not possible, it is likely that - you only need to perform some actions before and after invoking - these functions, and so your functions will wrap the generic - ones. - - Feel free to look at the Marvell, Cicada, and Davicom drivers in - drivers/net/phy/ for examples (the lxt and qsemi drivers have - not been tested as of this writing). - - The PHY's MMD register accesses are handled by the PAL framework - by default, but can be overridden by a specific PHY driver if - required. This could be the case if a PHY was released for - manufacturing before the MMD PHY register definitions were - standardized by the IEEE. Most modern PHYs will be able to use - the generic PAL framework for accessing the PHY's MMD registers. - An example of such usage is for Energy Efficient Ethernet support, - implemented in the PAL. This support uses the PAL to access MMD - registers for EEE query and configuration if the PHY supports - the IEEE standard access mechanisms, or can use the PHY's specific - access interfaces if overridden by the specific PHY driver. See - the Micrel driver in drivers/net/phy/ for an example of how this - can be implemented. - -Board Fixups - - Sometimes the specific interaction between the platform and the PHY requires - special handling. For instance, to change where the PHY's clock input is, - or to add a delay to account for latency issues in the data path. In order - to support such contingencies, the PHY Layer allows platform code to register - fixups to be run when the PHY is brought up (or subsequently reset). - - When the PHY Layer brings up a PHY it checks to see if there are any fixups - registered for it, matching based on UID (contained in the PHY device's phy_id - field) and the bus identifier (contained in phydev->dev.bus_id). Both must - match, however two constants, PHY_ANY_ID and PHY_ANY_UID, are provided as - wildcards for the bus ID and UID, respectively. - - When a match is found, the PHY layer will invoke the run function associated - with the fixup. This function is passed a pointer to the phy_device of - interest. It should therefore only operate on that PHY. - - The platform code can either register the fixup using phy_register_fixup(): - - int phy_register_fixup(const char *phy_id, - u32 phy_uid, u32 phy_uid_mask, - int (*run)(struct phy_device *)); - - Or using one of the two stubs, phy_register_fixup_for_uid() and - phy_register_fixup_for_id(): - - int phy_register_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask, - int (*run)(struct phy_device *)); - int phy_register_fixup_for_id(const char *phy_id, - int (*run)(struct phy_device *)); - - The stubs set one of the two matching criteria, and set the other one to - match anything. - - When phy_register_fixup() or *_for_uid()/*_for_id() is called at module, - unregister fixup and free allocate memory are required. - - Call one of following function before unloading module. - - int phy_unregister_fixup(const char *phy_id, u32 phy_uid, u32 phy_uid_mask); - int phy_unregister_fixup_for_uid(u32 phy_uid, u32 phy_uid_mask); - int phy_register_fixup_for_id(const char *phy_id); - -Standards - - IEEE Standard 802.3: CSMA/CD Access Method and Physical Layer Specifications, Section Two: - http://standards.ieee.org/getieee802/download/802.3-2008_section2.pdf - - RGMII v1.3: - http://web.archive.org/web/20160303212629/http://www.hp.com/rnd/pdfs/RGMIIv1_3.pdf - - RGMII v2.0: - http://web.archive.org/web/20160303171328/http://www.hp.com/rnd/pdfs/RGMIIv2_0_final_hp.pdf diff --git a/Documentation/networking/rxrpc.txt b/Documentation/networking/rxrpc.txt index 605e00cdd6be..2df5894353d6 100644 --- a/Documentation/networking/rxrpc.txt +++ b/Documentation/networking/rxrpc.txt @@ -661,7 +661,7 @@ A server would be set up to accept operations in the following manner: setsockopt(server, SOL_RXRPC, RXRPC_SECURITY_KEYRING, "AFSkeys", 7); The keyring can be manipulated after it has been given to the socket. This - permits the server to add more keys, replace keys, etc. whilst it is live. + permits the server to add more keys, replace keys, etc. while it is live. (3) A local address must then be bound: @@ -1000,51 +1000,6 @@ The kernel interface functions are as follows: size should be set when the call is begun. tx_total_len may not be less than zero. - (*) Check to see the completion state of a call so that the caller can assess - whether it needs to be retried. - - enum rxrpc_call_completion { - RXRPC_CALL_SUCCEEDED, - RXRPC_CALL_REMOTELY_ABORTED, - RXRPC_CALL_LOCALLY_ABORTED, - RXRPC_CALL_LOCAL_ERROR, - RXRPC_CALL_NETWORK_ERROR, - }; - - int rxrpc_kernel_check_call(struct socket *sock, struct rxrpc_call *call, - enum rxrpc_call_completion *_compl, - u32 *_abort_code); - - On return, -EINPROGRESS will be returned if the call is still ongoing; if - it is finished, *_compl will be set to indicate the manner of completion, - *_abort_code will be set to any abort code that occurred. 0 will be - returned on a successful completion, -ECONNABORTED will be returned if the - client failed due to a remote abort and anything else will return an - appropriate error code. - - The caller should look at this information to decide if it's worth - retrying the call. - - (*) Retry a client call. - - int rxrpc_kernel_retry_call(struct socket *sock, - struct rxrpc_call *call, - struct sockaddr_rxrpc *srx, - struct key *key); - - This attempts to partially reinitialise a call and submit it again whilst - reusing the original call's Tx queue to avoid the need to repackage and - re-encrypt the data to be sent. call indicates the call to retry, srx the - new address to send it to and key the encryption key to use for signing or - encrypting the packets. - - For this to work, the first Tx data packet must still be in the transmit - queue, and currently this is only permitted for local and network errors - and the call must not have been aborted. Any partially constructed Tx - packet is left as is and can continue being filled afterwards. - - It returns 0 if the call was requeued and an error otherwise. - (*) Get call RTT. u64 rxrpc_kernel_get_rtt(struct socket *sock, struct rxrpc_call *call); @@ -1056,18 +1011,23 @@ The kernel interface functions are as follows: u32 rxrpc_kernel_check_life(struct socket *sock, struct rxrpc_call *call); + void rxrpc_kernel_probe_life(struct socket *sock, + struct rxrpc_call *call); - This returns a number that is updated when ACKs are received from the peer - (notably including PING RESPONSE ACKs which we can elicit by sending PING - ACKs to see if the call still exists on the server). The caller should - compare the numbers of two calls to see if the call is still alive after - waiting for a suitable interval. + The first function returns a number that is updated when ACKs are received + from the peer (notably including PING RESPONSE ACKs which we can elicit by + sending PING ACKs to see if the call still exists on the server). The + caller should compare the numbers of two calls to see if the call is still + alive after waiting for a suitable interval. This allows the caller to work out if the server is still contactable and - if the call is still alive on the server whilst waiting for the server to + if the call is still alive on the server while waiting for the server to process a client operation. - This function may transmit a PING ACK. + The second function causes a ping ACK to be transmitted to try to provoke + the peer into responding, which would then cause the value returned by the + first function to change. Note that this must be called in TASK_RUNNING + state. (*) Get reply timestamp. @@ -1144,14 +1104,14 @@ adjusted through sysctls in /proc/net/rxrpc/: (*) connection_expiry The amount of time in seconds after a connection was last used before we - remove it from the connection list. Whilst a connection is in existence, + remove it from the connection list. While a connection is in existence, it serves as a placeholder for negotiated security; when it is deleted, the security must be renegotiated. (*) transport_expiry The amount of time in seconds after a transport was last used before we - remove it from the transport list. Whilst a transport is in existence, it + remove it from the transport list. While a transport is in existence, it serves to anchor the peer data and keeps the connection ID counter. (*) rxrpc_rx_window_size diff --git a/Documentation/networking/sfp-phylink.rst b/Documentation/networking/sfp-phylink.rst new file mode 100644 index 000000000000..5bd26cb07244 --- /dev/null +++ b/Documentation/networking/sfp-phylink.rst @@ -0,0 +1,268 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +phylink +======= + +Overview +======== + +phylink is a mechanism to support hot-pluggable networking modules +without needing to re-initialise the adapter on hot-plug events. + +phylink supports conventional phylib-based setups, fixed link setups +and SFP (Small Formfactor Pluggable) modules at present. + +Modes of operation +================== + +phylink has several modes of operation, which depend on the firmware +settings. + +1. PHY mode + + In PHY mode, we use phylib to read the current link settings from + the PHY, and pass them to the MAC driver. We expect the MAC driver + to configure exactly the modes that are specified without any + negotiation being enabled on the link. + +2. Fixed mode + + Fixed mode is the same as PHY mode as far as the MAC driver is + concerned. + +3. In-band mode + + In-band mode is used with 802.3z, SGMII and similar interface modes, + and we are expecting to use and honor the in-band negotiation or + control word sent across the serdes channel. + +By example, what this means is that: + +.. code-block:: none + + ð { + phy = <&phy>; + phy-mode = "sgmii"; + }; + +does not use in-band SGMII signalling. The PHY is expected to follow +exactly the settings given to it in its :c:func:`mac_config` function. +The link should be forced up or down appropriately in the +:c:func:`mac_link_up` and :c:func:`mac_link_down` functions. + +.. code-block:: none + + ð { + managed = "in-band-status"; + phy = <&phy>; + phy-mode = "sgmii"; + }; + +uses in-band mode, where results from the PHY's negotiation are passed +to the MAC through the SGMII control word, and the MAC is expected to +acknowledge the control word. The :c:func:`mac_link_up` and +:c:func:`mac_link_down` functions must not force the MAC side link +up and down. + +Rough guide to converting a network driver to sfp/phylink +========================================================= + +This guide briefly describes how to convert a network driver from +phylib to the sfp/phylink support. Please send patches to improve +this documentation. + +1. Optionally split the network driver's phylib update function into + three parts dealing with link-down, link-up and reconfiguring the + MAC settings. This can be done as a separate preparation commit. + + An example of this preparation can be found in git commit fc548b991fb0. + +2. Replace:: + + select FIXED_PHY + select PHYLIB + + with:: + + select PHYLINK + + in the driver's Kconfig stanza. + +3. Add:: + + #include <linux/phylink.h> + + to the driver's list of header files. + +4. Add:: + + struct phylink *phylink; + + to the driver's private data structure. We shall refer to the + driver's private data pointer as ``priv`` below, and the driver's + private data structure as ``struct foo_priv``. + +5. Replace the following functions: + + .. flat-table:: + :header-rows: 1 + :widths: 1 1 + :stub-columns: 0 + + * - Original function + - Replacement function + * - phy_start(phydev) + - phylink_start(priv->phylink) + * - phy_stop(phydev) + - phylink_stop(priv->phylink) + * - phy_mii_ioctl(phydev, ifr, cmd) + - phylink_mii_ioctl(priv->phylink, ifr, cmd) + * - phy_ethtool_get_wol(phydev, wol) + - phylink_ethtool_get_wol(priv->phylink, wol) + * - phy_ethtool_set_wol(phydev, wol) + - phylink_ethtool_set_wol(priv->phylink, wol) + * - phy_disconnect(phydev) + - phylink_disconnect_phy(priv->phylink) + + Please note that some of these functions must be called under the + rtnl lock, and will warn if not. This will normally be the case, + except if these are called from the driver suspend/resume paths. + +6. Add/replace ksettings get/set methods with: + + .. code-block:: c + + static int foo_ethtool_set_link_ksettings(struct net_device *dev, + const struct ethtool_link_ksettings *cmd) + { + struct foo_priv *priv = netdev_priv(dev); + + return phylink_ethtool_ksettings_set(priv->phylink, cmd); + } + + static int foo_ethtool_get_link_ksettings(struct net_device *dev, + struct ethtool_link_ksettings *cmd) + { + struct foo_priv *priv = netdev_priv(dev); + + return phylink_ethtool_ksettings_get(priv->phylink, cmd); + } + +7. Replace the call to: + + phy_dev = of_phy_connect(dev, node, link_func, flags, phy_interface); + + and associated code with a call to: + + err = phylink_of_phy_connect(priv->phylink, node, flags); + + For the most part, ``flags`` can be zero; these flags are passed to + the of_phy_attach() inside this function call if a PHY is specified + in the DT node ``node``. + + ``node`` should be the DT node which contains the network phy property, + fixed link properties, and will also contain the sfp property. + + The setup of fixed links should also be removed; these are handled + internally by phylink. + + of_phy_connect() was also passed a function pointer for link updates. + This function is replaced by a different form of MAC updates + described below in (8). + + Manipulation of the PHY's supported/advertised happens within phylink + based on the validate callback, see below in (8). + + Note that the driver no longer needs to store the ``phy_interface``, + and also note that ``phy_interface`` becomes a dynamic property, + just like the speed, duplex etc. settings. + + Finally, note that the MAC driver has no direct access to the PHY + anymore; that is because in the phylink model, the PHY can be + dynamic. + +8. Add a :c:type:`struct phylink_mac_ops <phylink_mac_ops>` instance to + the driver, which is a table of function pointers, and implement + these functions. The old link update function for + :c:func:`of_phy_connect` becomes three methods: :c:func:`mac_link_up`, + :c:func:`mac_link_down`, and :c:func:`mac_config`. If step 1 was + performed, then the functionality will have been split there. + + It is important that if in-band negotiation is used, + :c:func:`mac_link_up` and :c:func:`mac_link_down` do not prevent the + in-band negotiation from completing, since these functions are called + when the in-band link state changes - otherwise the link will never + come up. + + The :c:func:`validate` method should mask the supplied supported mask, + and ``state->advertising`` with the supported ethtool link modes. + These are the new ethtool link modes, so bitmask operations must be + used. For an example, see drivers/net/ethernet/marvell/mvneta.c. + + The :c:func:`mac_link_state` method is used to read the link state + from the MAC, and report back the settings that the MAC is currently + using. This is particularly important for in-band negotiation + methods such as 1000base-X and SGMII. + + The :c:func:`mac_config` method is used to update the MAC with the + requested state, and must avoid unnecessarily taking the link down + when making changes to the MAC configuration. This means the + function should modify the state and only take the link down when + absolutely necessary to change the MAC configuration. An example + of how to do this can be found in :c:func:`mvneta_mac_config` in + drivers/net/ethernet/marvell/mvneta.c. + + For further information on these methods, please see the inline + documentation in :c:type:`struct phylink_mac_ops <phylink_mac_ops>`. + +9. Remove calls to of_parse_phandle() for the PHY, + of_phy_register_fixed_link() for fixed links etc. from the probe + function, and replace with: + + .. code-block:: c + + struct phylink *phylink; + + phylink = phylink_create(dev, node, phy_mode, &phylink_ops); + if (IS_ERR(phylink)) { + err = PTR_ERR(phylink); + fail probe; + } + + priv->phylink = phylink; + + and arrange to destroy the phylink in the probe failure path as + appropriate and the removal path too by calling: + + .. code-block:: c + + phylink_destroy(priv->phylink); + +10. Arrange for MAC link state interrupts to be forwarded into + phylink, via: + + .. code-block:: c + + phylink_mac_change(priv->phylink, link_is_up); + + where ``link_is_up`` is true if the link is currently up or false + otherwise. + +11. Verify that the driver does not call:: + + netif_carrier_on() + netif_carrier_off() + + as these will interfere with phylink's tracking of the link state, + and cause phylink to omit calls via the :c:func:`mac_link_up` and + :c:func:`mac_link_down` methods. + +Network drivers should call phylink_stop() and phylink_start() via their +suspend/resume paths, which ensures that the appropriate +:c:type:`struct phylink_mac_ops <phylink_mac_ops>` methods are called +as necessary. + +For information describing the SFP cage in DT, please see the binding +documentation in the kernel source tree +``Documentation/devicetree/bindings/net/sff,sfp.txt`` diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst new file mode 100644 index 000000000000..52b026be028f --- /dev/null +++ b/Documentation/networking/snmp_counter.rst @@ -0,0 +1,1787 @@ +============ +SNMP counter +============ + +This document explains the meaning of SNMP counters. + +General IPv4 counters +===================== +All layer 4 packets and ICMP packets will change these counters, but +these counters won't be changed by layer 2 packets (such as STP) or +ARP packets. + +* IpInReceives + +Defined in `RFC1213 ipInReceives`_ + +.. _RFC1213 ipInReceives: https://tools.ietf.org/html/rfc1213#page-26 + +The number of packets received by the IP layer. It gets increasing at the +beginning of ip_rcv function, always be updated together with +IpExtInOctets. It will be increased even if the packet is dropped +later (e.g. due to the IP header is invalid or the checksum is wrong +and so on). It indicates the number of aggregated segments after +GRO/LRO. + +* IpInDelivers + +Defined in `RFC1213 ipInDelivers`_ + +.. _RFC1213 ipInDelivers: https://tools.ietf.org/html/rfc1213#page-28 + +The number of packets delivers to the upper layer protocols. E.g. TCP, UDP, +ICMP and so on. If no one listens on a raw socket, only kernel +supported protocols will be delivered, if someone listens on the raw +socket, all valid IP packets will be delivered. + +* IpOutRequests + +Defined in `RFC1213 ipOutRequests`_ + +.. _RFC1213 ipOutRequests: https://tools.ietf.org/html/rfc1213#page-28 + +The number of packets sent via IP layer, for both single cast and +multicast packets, and would always be updated together with +IpExtOutOctets. + +* IpExtInOctets and IpExtOutOctets + +They are Linux kernel extensions, no RFC definitions. Please note, +RFC1213 indeed defines ifInOctets and ifOutOctets, but they +are different things. The ifInOctets and ifOutOctets include the MAC +layer header size but IpExtInOctets and IpExtOutOctets don't, they +only include the IP layer header and the IP layer data. + +* IpExtInNoECTPkts, IpExtInECT1Pkts, IpExtInECT0Pkts, IpExtInCEPkts + +They indicate the number of four kinds of ECN IP packets, please refer +`Explicit Congestion Notification`_ for more details. + +.. _Explicit Congestion Notification: https://tools.ietf.org/html/rfc3168#page-6 + +These 4 counters calculate how many packets received per ECN +status. They count the real frame number regardless the LRO/GRO. So +for the same packet, you might find that IpInReceives count 1, but +IpExtInNoECTPkts counts 2 or more. + +* IpInHdrErrors + +Defined in `RFC1213 ipInHdrErrors`_. It indicates the packet is +dropped due to the IP header error. It might happen in both IP input +and IP forward paths. + +.. _RFC1213 ipInHdrErrors: https://tools.ietf.org/html/rfc1213#page-27 + +* IpInAddrErrors + +Defined in `RFC1213 ipInAddrErrors`_. It will be increased in two +scenarios: (1) The IP address is invalid. (2) The destination IP +address is not a local address and IP forwarding is not enabled + +.. _RFC1213 ipInAddrErrors: https://tools.ietf.org/html/rfc1213#page-27 + +* IpExtInNoRoutes + +This counter means the packet is dropped when the IP stack receives a +packet and can't find a route for it from the route table. It might +happen when IP forwarding is enabled and the destination IP address is +not a local address and there is no route for the destination IP +address. + +* IpInUnknownProtos + +Defined in `RFC1213 ipInUnknownProtos`_. It will be increased if the +layer 4 protocol is unsupported by kernel. If an application is using +raw socket, kernel will always deliver the packet to the raw socket +and this counter won't be increased. + +.. _RFC1213 ipInUnknownProtos: https://tools.ietf.org/html/rfc1213#page-27 + +* IpExtInTruncatedPkts + +For IPv4 packet, it means the actual data size is smaller than the +"Total Length" field in the IPv4 header. + +* IpInDiscards + +Defined in `RFC1213 ipInDiscards`_. It indicates the packet is dropped +in the IP receiving path and due to kernel internal reasons (e.g. no +enough memory). + +.. _RFC1213 ipInDiscards: https://tools.ietf.org/html/rfc1213#page-28 + +* IpOutDiscards + +Defined in `RFC1213 ipOutDiscards`_. It indicates the packet is +dropped in the IP sending path and due to kernel internal reasons. + +.. _RFC1213 ipOutDiscards: https://tools.ietf.org/html/rfc1213#page-28 + +* IpOutNoRoutes + +Defined in `RFC1213 ipOutNoRoutes`_. It indicates the packet is +dropped in the IP sending path and no route is found for it. + +.. _RFC1213 ipOutNoRoutes: https://tools.ietf.org/html/rfc1213#page-29 + +ICMP counters +============= +* IcmpInMsgs and IcmpOutMsgs + +Defined by `RFC1213 icmpInMsgs`_ and `RFC1213 icmpOutMsgs`_ + +.. _RFC1213 icmpInMsgs: https://tools.ietf.org/html/rfc1213#page-41 +.. _RFC1213 icmpOutMsgs: https://tools.ietf.org/html/rfc1213#page-43 + +As mentioned in the RFC1213, these two counters include errors, they +would be increased even if the ICMP packet has an invalid type. The +ICMP output path will check the header of a raw socket, so the +IcmpOutMsgs would still be updated if the IP header is constructed by +a userspace program. + +* ICMP named types + +| These counters include most of common ICMP types, they are: +| IcmpInDestUnreachs: `RFC1213 icmpInDestUnreachs`_ +| IcmpInTimeExcds: `RFC1213 icmpInTimeExcds`_ +| IcmpInParmProbs: `RFC1213 icmpInParmProbs`_ +| IcmpInSrcQuenchs: `RFC1213 icmpInSrcQuenchs`_ +| IcmpInRedirects: `RFC1213 icmpInRedirects`_ +| IcmpInEchos: `RFC1213 icmpInEchos`_ +| IcmpInEchoReps: `RFC1213 icmpInEchoReps`_ +| IcmpInTimestamps: `RFC1213 icmpInTimestamps`_ +| IcmpInTimestampReps: `RFC1213 icmpInTimestampReps`_ +| IcmpInAddrMasks: `RFC1213 icmpInAddrMasks`_ +| IcmpInAddrMaskReps: `RFC1213 icmpInAddrMaskReps`_ +| IcmpOutDestUnreachs: `RFC1213 icmpOutDestUnreachs`_ +| IcmpOutTimeExcds: `RFC1213 icmpOutTimeExcds`_ +| IcmpOutParmProbs: `RFC1213 icmpOutParmProbs`_ +| IcmpOutSrcQuenchs: `RFC1213 icmpOutSrcQuenchs`_ +| IcmpOutRedirects: `RFC1213 icmpOutRedirects`_ +| IcmpOutEchos: `RFC1213 icmpOutEchos`_ +| IcmpOutEchoReps: `RFC1213 icmpOutEchoReps`_ +| IcmpOutTimestamps: `RFC1213 icmpOutTimestamps`_ +| IcmpOutTimestampReps: `RFC1213 icmpOutTimestampReps`_ +| IcmpOutAddrMasks: `RFC1213 icmpOutAddrMasks`_ +| IcmpOutAddrMaskReps: `RFC1213 icmpOutAddrMaskReps`_ + +.. _RFC1213 icmpInDestUnreachs: https://tools.ietf.org/html/rfc1213#page-41 +.. _RFC1213 icmpInTimeExcds: https://tools.ietf.org/html/rfc1213#page-41 +.. _RFC1213 icmpInParmProbs: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInSrcQuenchs: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInRedirects: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInEchos: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInEchoReps: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInTimestamps: https://tools.ietf.org/html/rfc1213#page-42 +.. _RFC1213 icmpInTimestampReps: https://tools.ietf.org/html/rfc1213#page-43 +.. _RFC1213 icmpInAddrMasks: https://tools.ietf.org/html/rfc1213#page-43 +.. _RFC1213 icmpInAddrMaskReps: https://tools.ietf.org/html/rfc1213#page-43 + +.. _RFC1213 icmpOutDestUnreachs: https://tools.ietf.org/html/rfc1213#page-44 +.. _RFC1213 icmpOutTimeExcds: https://tools.ietf.org/html/rfc1213#page-44 +.. _RFC1213 icmpOutParmProbs: https://tools.ietf.org/html/rfc1213#page-44 +.. _RFC1213 icmpOutSrcQuenchs: https://tools.ietf.org/html/rfc1213#page-44 +.. _RFC1213 icmpOutRedirects: https://tools.ietf.org/html/rfc1213#page-44 +.. _RFC1213 icmpOutEchos: https://tools.ietf.org/html/rfc1213#page-45 +.. _RFC1213 icmpOutEchoReps: https://tools.ietf.org/html/rfc1213#page-45 +.. _RFC1213 icmpOutTimestamps: https://tools.ietf.org/html/rfc1213#page-45 +.. _RFC1213 icmpOutTimestampReps: https://tools.ietf.org/html/rfc1213#page-45 +.. _RFC1213 icmpOutAddrMasks: https://tools.ietf.org/html/rfc1213#page-45 +.. _RFC1213 icmpOutAddrMaskReps: https://tools.ietf.org/html/rfc1213#page-46 + +Every ICMP type has two counters: 'In' and 'Out'. E.g., for the ICMP +Echo packet, they are IcmpInEchos and IcmpOutEchos. Their meanings are +straightforward. The 'In' counter means kernel receives such a packet +and the 'Out' counter means kernel sends such a packet. + +* ICMP numeric types + +They are IcmpMsgInType[N] and IcmpMsgOutType[N], the [N] indicates the +ICMP type number. These counters track all kinds of ICMP packets. The +ICMP type number definition could be found in the `ICMP parameters`_ +document. + +.. _ICMP parameters: https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml + +For example, if the Linux kernel sends an ICMP Echo packet, the +IcmpMsgOutType8 would increase 1. And if kernel gets an ICMP Echo Reply +packet, IcmpMsgInType0 would increase 1. + +* IcmpInCsumErrors + +This counter indicates the checksum of the ICMP packet is +wrong. Kernel verifies the checksum after updating the IcmpInMsgs and +before updating IcmpMsgInType[N]. If a packet has bad checksum, the +IcmpInMsgs would be updated but none of IcmpMsgInType[N] would be updated. + +* IcmpInErrors and IcmpOutErrors + +Defined by `RFC1213 icmpInErrors`_ and `RFC1213 icmpOutErrors`_ + +.. _RFC1213 icmpInErrors: https://tools.ietf.org/html/rfc1213#page-41 +.. _RFC1213 icmpOutErrors: https://tools.ietf.org/html/rfc1213#page-43 + +When an error occurs in the ICMP packet handler path, these two +counters would be updated. The receiving packet path use IcmpInErrors +and the sending packet path use IcmpOutErrors. When IcmpInCsumErrors +is increased, IcmpInErrors would always be increased too. + +relationship of the ICMP counters +--------------------------------- +The sum of IcmpMsgOutType[N] is always equal to IcmpOutMsgs, as they +are updated at the same time. The sum of IcmpMsgInType[N] plus +IcmpInErrors should be equal or larger than IcmpInMsgs. When kernel +receives an ICMP packet, kernel follows below logic: + +1. increase IcmpInMsgs +2. if has any error, update IcmpInErrors and finish the process +3. update IcmpMsgOutType[N] +4. handle the packet depending on the type, if has any error, update + IcmpInErrors and finish the process + +So if all errors occur in step (2), IcmpInMsgs should be equal to the +sum of IcmpMsgOutType[N] plus IcmpInErrors. If all errors occur in +step (4), IcmpInMsgs should be equal to the sum of +IcmpMsgOutType[N]. If the errors occur in both step (2) and step (4), +IcmpInMsgs should be less than the sum of IcmpMsgOutType[N] plus +IcmpInErrors. + +General TCP counters +==================== +* TcpInSegs + +Defined in `RFC1213 tcpInSegs`_ + +.. _RFC1213 tcpInSegs: https://tools.ietf.org/html/rfc1213#page-48 + +The number of packets received by the TCP layer. As mentioned in +RFC1213, it includes the packets received in error, such as checksum +error, invalid TCP header and so on. Only one error won't be included: +if the layer 2 destination address is not the NIC's layer 2 +address. It might happen if the packet is a multicast or broadcast +packet, or the NIC is in promiscuous mode. In these situations, the +packets would be delivered to the TCP layer, but the TCP layer will discard +these packets before increasing TcpInSegs. The TcpInSegs counter +isn't aware of GRO. So if two packets are merged by GRO, the TcpInSegs +counter would only increase 1. + +* TcpOutSegs + +Defined in `RFC1213 tcpOutSegs`_ + +.. _RFC1213 tcpOutSegs: https://tools.ietf.org/html/rfc1213#page-48 + +The number of packets sent by the TCP layer. As mentioned in RFC1213, +it excludes the retransmitted packets. But it includes the SYN, ACK +and RST packets. Doesn't like TcpInSegs, the TcpOutSegs is aware of +GSO, so if a packet would be split to 2 by GSO, TcpOutSegs will +increase 2. + +* TcpActiveOpens + +Defined in `RFC1213 tcpActiveOpens`_ + +.. _RFC1213 tcpActiveOpens: https://tools.ietf.org/html/rfc1213#page-47 + +It means the TCP layer sends a SYN, and come into the SYN-SENT +state. Every time TcpActiveOpens increases 1, TcpOutSegs should always +increase 1. + +* TcpPassiveOpens + +Defined in `RFC1213 tcpPassiveOpens`_ + +.. _RFC1213 tcpPassiveOpens: https://tools.ietf.org/html/rfc1213#page-47 + +It means the TCP layer receives a SYN, replies a SYN+ACK, come into +the SYN-RCVD state. + +* TcpExtTCPRcvCoalesce + +When packets are received by the TCP layer and are not be read by the +application, the TCP layer will try to merge them. This counter +indicate how many packets are merged in such situation. If GRO is +enabled, lots of packets would be merged by GRO, these packets +wouldn't be counted to TcpExtTCPRcvCoalesce. + +* TcpExtTCPAutoCorking + +When sending packets, the TCP layer will try to merge small packets to +a bigger one. This counter increase 1 for every packet merged in such +situation. Please refer to the LWN article for more details: +https://lwn.net/Articles/576263/ + +* TcpExtTCPOrigDataSent + +This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +explaination below:: + + TCPOrigDataSent: number of outgoing packets with original data (excluding + retransmission but including data-in-SYN). This counter is different from + TcpOutSegs because TcpOutSegs also tracks pure ACKs. TCPOrigDataSent is + more useful to track the TCP retransmission rate. + +* TCPSynRetrans + +This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +explaination below:: + + TCPSynRetrans: number of SYN and SYN/ACK retransmits to break down + retransmissions into SYN, fast-retransmits, timeout retransmits, etc. + +* TCPFastOpenActiveFail + +This counter is explained by `kernel commit f19c29e3e391`_, I pasted the +explaination below:: + + TCPFastOpenActiveFail: Fast Open attempts (SYN/data) failed because + the remote does not accept it or the attempts timed out. + +.. _kernel commit f19c29e3e391: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f19c29e3e391a66a273e9afebaf01917245148cd + +* TcpExtListenOverflows and TcpExtListenDrops + +When kernel receives a SYN from a client, and if the TCP accept queue +is full, kernel will drop the SYN and add 1 to TcpExtListenOverflows. +At the same time kernel will also add 1 to TcpExtListenDrops. When a +TCP socket is in LISTEN state, and kernel need to drop a packet, +kernel would always add 1 to TcpExtListenDrops. So increase +TcpExtListenOverflows would let TcpExtListenDrops increasing at the +same time, but TcpExtListenDrops would also increase without +TcpExtListenOverflows increasing, e.g. a memory allocation fail would +also let TcpExtListenDrops increase. + +Note: The above explanation is based on kernel 4.10 or above version, on +an old kernel, the TCP stack has different behavior when TCP accept +queue is full. On the old kernel, TCP stack won't drop the SYN, it +would complete the 3-way handshake. As the accept queue is full, TCP +stack will keep the socket in the TCP half-open queue. As it is in the +half open queue, TCP stack will send SYN+ACK on an exponential backoff +timer, after client replies ACK, TCP stack checks whether the accept +queue is still full, if it is not full, moves the socket to the accept +queue, if it is full, keeps the socket in the half-open queue, at next +time client replies ACK, this socket will get another chance to move +to the accept queue. + + +TCP Fast Open +============= +* TcpEstabResets + +Defined in `RFC1213 tcpEstabResets`_. + +.. _RFC1213 tcpEstabResets: https://tools.ietf.org/html/rfc1213#page-48 + +* TcpAttemptFails + +Defined in `RFC1213 tcpAttemptFails`_. + +.. _RFC1213 tcpAttemptFails: https://tools.ietf.org/html/rfc1213#page-48 + +* TcpOutRsts + +Defined in `RFC1213 tcpOutRsts`_. The RFC says this counter indicates +the 'segments sent containing the RST flag', but in linux kernel, this +couner indicates the segments kerenl tried to send. The sending +process might be failed due to some errors (e.g. memory alloc failed). + +.. _RFC1213 tcpOutRsts: https://tools.ietf.org/html/rfc1213#page-52 + +* TcpExtTCPSpuriousRtxHostQueues + +When the TCP stack wants to retransmit a packet, and finds that packet +is not lost in the network, but the packet is not sent yet, the TCP +stack would give up the retransmission and update this counter. It +might happen if a packet stays too long time in a qdisc or driver +queue. + +* TcpEstabResets + +The socket receives a RST packet in Establish or CloseWait state. + +* TcpExtTCPKeepAlive + +This counter indicates many keepalive packets were sent. The keepalive +won't be enabled by default. A userspace program could enable it by +setting the SO_KEEPALIVE socket option. + +* TcpExtTCPSpuriousRTOs + +The spurious retransmission timeout detected by the `F-RTO`_ +algorithm. + +.. _F-RTO: https://tools.ietf.org/html/rfc5682 + +TCP Fast Path +============ +When kernel receives a TCP packet, it has two paths to handler the +packet, one is fast path, another is slow path. The comment in kernel +code provides a good explanation of them, I pasted them below:: + + It is split into a fast path and a slow path. The fast path is + disabled when: + + - A zero window was announced from us + - zero window probing + is only handled properly on the slow path. + - Out of order segments arrived. + - Urgent data is expected. + - There is no buffer space left + - Unexpected TCP flags/window values/header lengths are received + (detected by checking the TCP header against pred_flags) + - Data is sent in both directions. The fast path only supports pure senders + or pure receivers (this means either the sequence number or the ack + value must stay constant) + - Unexpected TCP option. + +Kernel will try to use fast path unless any of the above conditions +are satisfied. If the packets are out of order, kernel will handle +them in slow path, which means the performance might be not very +good. Kernel would also come into slow path if the "Delayed ack" is +used, because when using "Delayed ack", the data is sent in both +directions. When the TCP window scale option is not used, kernel will +try to enable fast path immediately when the connection comes into the +established state, but if the TCP window scale option is used, kernel +will disable the fast path at first, and try to enable it after kernel +receives packets. + +* TcpExtTCPPureAcks and TcpExtTCPHPAcks + +If a packet set ACK flag and has no data, it is a pure ACK packet, if +kernel handles it in the fast path, TcpExtTCPHPAcks will increase 1, +if kernel handles it in the slow path, TcpExtTCPPureAcks will +increase 1. + +* TcpExtTCPHPHits + +If a TCP packet has data (which means it is not a pure ACK packet), +and this packet is handled in the fast path, TcpExtTCPHPHits will +increase 1. + + +TCP abort +========= +* TcpExtTCPAbortOnData + +It means TCP layer has data in flight, but need to close the +connection. So TCP layer sends a RST to the other side, indicate the +connection is not closed very graceful. An easy way to increase this +counter is using the SO_LINGER option. Please refer to the SO_LINGER +section of the `socket man page`_: + +.. _socket man page: http://man7.org/linux/man-pages/man7/socket.7.html + +By default, when an application closes a connection, the close function +will return immediately and kernel will try to send the in-flight data +async. If you use the SO_LINGER option, set l_onoff to 1, and l_linger +to a positive number, the close function won't return immediately, but +wait for the in-flight data are acked by the other side, the max wait +time is l_linger seconds. If set l_onoff to 1 and set l_linger to 0, +when the application closes a connection, kernel will send a RST +immediately and increase the TcpExtTCPAbortOnData counter. + +* TcpExtTCPAbortOnClose + +This counter means the application has unread data in the TCP layer when +the application wants to close the TCP connection. In such a situation, +kernel will send a RST to the other side of the TCP connection. + +* TcpExtTCPAbortOnMemory + +When an application closes a TCP connection, kernel still need to track +the connection, let it complete the TCP disconnect process. E.g. an +app calls the close method of a socket, kernel sends fin to the other +side of the connection, then the app has no relationship with the +socket any more, but kernel need to keep the socket, this socket +becomes an orphan socket, kernel waits for the reply of the other side, +and would come to the TIME_WAIT state finally. When kernel has no +enough memory to keep the orphan socket, kernel would send an RST to +the other side, and delete the socket, in such situation, kernel will +increase 1 to the TcpExtTCPAbortOnMemory. Two conditions would trigger +TcpExtTCPAbortOnMemory: + +1. the memory used by the TCP protocol is higher than the third value of +the tcp_mem. Please refer the tcp_mem section in the `TCP man page`_: + +.. _TCP man page: http://man7.org/linux/man-pages/man7/tcp.7.html + +2. the orphan socket count is higher than net.ipv4.tcp_max_orphans + + +* TcpExtTCPAbortOnTimeout + +This counter will increase when any of the TCP timers expire. In such +situation, kernel won't send RST, just give up the connection. + +* TcpExtTCPAbortOnLinger + +When a TCP connection comes into FIN_WAIT_2 state, instead of waiting +for the fin packet from the other side, kernel could send a RST and +delete the socket immediately. This is not the default behavior of +Linux kernel TCP stack. By configuring the TCP_LINGER2 socket option, +you could let kernel follow this behavior. + +* TcpExtTCPAbortFailed + +The kernel TCP layer will send RST if the `RFC2525 2.17 section`_ is +satisfied. If an internal error occurs during this process, +TcpExtTCPAbortFailed will be increased. + +.. _RFC2525 2.17 section: https://tools.ietf.org/html/rfc2525#page-50 + +TCP Hybrid Slow Start +===================== +The Hybrid Slow Start algorithm is an enhancement of the traditional +TCP congestion window Slow Start algorithm. It uses two pieces of +information to detect whether the max bandwidth of the TCP path is +approached. The two pieces of information are ACK train length and +increase in packet delay. For detail information, please refer the +`Hybrid Slow Start paper`_. Either ACK train length or packet delay +hits a specific threshold, the congestion control algorithm will come +into the Congestion Avoidance state. Until v4.20, two congestion +control algorithms are using Hybrid Slow Start, they are cubic (the +default congestion control algorithm) and cdg. Four snmp counters +relate with the Hybrid Slow Start algorithm. + +.. _Hybrid Slow Start paper: https://pdfs.semanticscholar.org/25e9/ef3f03315782c7f1cbcd31b587857adae7d1.pdf + +* TcpExtTCPHystartTrainDetect + +How many times the ACK train length threshold is detected + +* TcpExtTCPHystartTrainCwnd + +The sum of CWND detected by ACK train length. Dividing this value by +TcpExtTCPHystartTrainDetect is the average CWND which detected by the +ACK train length. + +* TcpExtTCPHystartDelayDetect + +How many times the packet delay threshold is detected. + +* TcpExtTCPHystartDelayCwnd + +The sum of CWND detected by packet delay. Dividing this value by +TcpExtTCPHystartDelayDetect is the average CWND which detected by the +packet delay. + +TCP retransmission and congestion control +========================================= +The TCP protocol has two retransmission mechanisms: SACK and fast +recovery. They are exclusive with each other. When SACK is enabled, +the kernel TCP stack would use SACK, or kernel would use fast +recovery. The SACK is a TCP option, which is defined in `RFC2018`_, +the fast recovery is defined in `RFC6582`_, which is also called +'Reno'. + +The TCP congestion control is a big and complex topic. To understand +the related snmp counter, we need to know the states of the congestion +control state machine. There are 5 states: Open, Disorder, CWR, +Recovery and Loss. For details about these states, please refer page 5 +and page 6 of this document: +https://pdfs.semanticscholar.org/0e9c/968d09ab2e53e24c4dca5b2d67c7f7140f8e.pdf + +.. _RFC2018: https://tools.ietf.org/html/rfc2018 +.. _RFC6582: https://tools.ietf.org/html/rfc6582 + +* TcpExtTCPRenoRecovery and TcpExtTCPSackRecovery + +When the congestion control comes into Recovery state, if sack is +used, TcpExtTCPSackRecovery increases 1, if sack is not used, +TcpExtTCPRenoRecovery increases 1. These two counters mean the TCP +stack begins to retransmit the lost packets. + +* TcpExtTCPSACKReneging + +A packet was acknowledged by SACK, but the receiver has dropped this +packet, so the sender needs to retransmit this packet. In this +situation, the sender adds 1 to TcpExtTCPSACKReneging. A receiver +could drop a packet which has been acknowledged by SACK, although it is +unusual, it is allowed by the TCP protocol. The sender doesn't really +know what happened on the receiver side. The sender just waits until +the RTO expires for this packet, then the sender assumes this packet +has been dropped by the receiver. + +* TcpExtTCPRenoReorder + +The reorder packet is detected by fast recovery. It would only be used +if SACK is disabled. The fast recovery algorithm detects recorder by +the duplicate ACK number. E.g., if retransmission is triggered, and +the original retransmitted packet is not lost, it is just out of +order, the receiver would acknowledge multiple times, one for the +retransmitted packet, another for the arriving of the original out of +order packet. Thus the sender would find more ACks than its +expectation, and the sender knows out of order occurs. + +* TcpExtTCPTSReorder + +The reorder packet is detected when a hole is filled. E.g., assume the +sender sends packet 1,2,3,4,5, and the receiving order is +1,2,4,5,3. When the sender receives the ACK of packet 3 (which will +fill the hole), two conditions will let TcpExtTCPTSReorder increase +1: (1) if the packet 3 is not re-retransmitted yet. (2) if the packet +3 is retransmitted but the timestamp of the packet 3's ACK is earlier +than the retransmission timestamp. + +* TcpExtTCPSACKReorder + +The reorder packet detected by SACK. The SACK has two methods to +detect reorder: (1) DSACK is received by the sender. It means the +sender sends the same packet more than one times. And the only reason +is the sender believes an out of order packet is lost so it sends the +packet again. (2) Assume packet 1,2,3,4,5 are sent by the sender, and +the sender has received SACKs for packet 2 and 5, now the sender +receives SACK for packet 4 and the sender doesn't retransmit the +packet yet, the sender would know packet 4 is out of order. The TCP +stack of kernel will increase TcpExtTCPSACKReorder for both of the +above scenarios. + +* TcpExtTCPSlowStartRetrans + +The TCP stack wants to retransmit a packet and the congestion control +state is 'Loss'. + +* TcpExtTCPFastRetrans + +The TCP stack wants to retransmit a packet and the congestion control +state is not 'Loss'. + +* TcpExtTCPLostRetransmit + +A SACK points out that a retransmission packet is lost again. + +* TcpExtTCPRetransFail + +The TCP stack tries to deliver a retransmission packet to lower layers +but the lower layers return an error. + +* TcpExtTCPSynRetrans + +The TCP stack retransmits a SYN packet. + +DSACK +===== +The DSACK is defined in `RFC2883`_. The receiver uses DSACK to report +duplicate packets to the sender. There are two kinds of +duplications: (1) a packet which has been acknowledged is +duplicate. (2) an out of order packet is duplicate. The TCP stack +counts these two kinds of duplications on both receiver side and +sender side. + +.. _RFC2883 : https://tools.ietf.org/html/rfc2883 + +* TcpExtTCPDSACKOldSent + +The TCP stack receives a duplicate packet which has been acked, so it +sends a DSACK to the sender. + +* TcpExtTCPDSACKOfoSent + +The TCP stack receives an out of order duplicate packet, so it sends a +DSACK to the sender. + +* TcpExtTCPDSACKRecv +The TCP stack receives a DSACK, which indicates an acknowledged +duplicate packet is received. + +* TcpExtTCPDSACKOfoRecv + +The TCP stack receives a DSACK, which indicate an out of order +duplicate packet is received. + +invalid SACK and DSACK +==================== +When a SACK (or DSACK) block is invalid, a corresponding counter would +be updated. The validation method is base on the start/end sequence +number of the SACK block. For more details, please refer the comment +of the function tcp_is_sackblock_valid in the kernel source code. A +SACK option could have up to 4 blocks, they are checked +individually. E.g., if 3 blocks of a SACk is invalid, the +corresponding counter would be updated 3 times. The comment of the +`Add counters for discarded SACK blocks`_ patch has additional +explaination: + +.. _Add counters for discarded SACK blocks: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=18f02545a9a16c9a89778b91a162ad16d510bb32 + +* TcpExtTCPSACKDiscard +This counter indicates how many SACK blocks are invalid. If the invalid +SACK block is caused by ACK recording, the TCP stack will only ignore +it and won't update this counter. + +* TcpExtTCPDSACKIgnoredOld and TcpExtTCPDSACKIgnoredNoUndo +When a DSACK block is invalid, one of these two counters would be +updated. Which counter will be updated depends on the undo_marker flag +of the TCP socket. If the undo_marker is not set, the TCP stack isn't +likely to re-transmit any packets, and we still receive an invalid +DSACK block, the reason might be that the packet is duplicated in the +middle of the network. In such scenario, TcpExtTCPDSACKIgnoredNoUndo +will be updated. If the undo_marker is set, TcpExtTCPDSACKIgnoredOld +will be updated. As implied in its name, it might be an old packet. + +SACK shift +========= +The linux networking stack stores data in sk_buff struct (skb for +short). If a SACK block acrosses multiple skb, the TCP stack will try +to re-arrange data in these skb. E.g. if a SACK block acknowledges seq +10 to 15, skb1 has seq 10 to 13, skb2 has seq 14 to 20. The seq 14 and +15 in skb2 would be moved to skb1. This operation is 'shift'. If a +SACK block acknowledges seq 10 to 20, skb1 has seq 10 to 13, skb2 has +seq 14 to 20. All data in skb2 will be moved to skb1, and skb2 will be +discard, this operation is 'merge'. + +* TcpExtTCPSackShifted +A skb is shifted + +* TcpExtTCPSackMerged +A skb is merged + +* TcpExtTCPSackShiftFallback +A skb should be shifted or merged, but the TCP stack doesn't do it for +some reasons. + +TCP out of order +================ +* TcpExtTCPOFOQueue + +The TCP layer receives an out of order packet and has enough memory +to queue it. + +* TcpExtTCPOFODrop + +The TCP layer receives an out of order packet but doesn't have enough +memory, so drops it. Such packets won't be counted into +TcpExtTCPOFOQueue. + +* TcpExtTCPOFOMerge + +The received out of order packet has an overlay with the previous +packet. the overlay part will be dropped. All of TcpExtTCPOFOMerge +packets will also be counted into TcpExtTCPOFOQueue. + +TCP PAWS +======== +PAWS (Protection Against Wrapped Sequence numbers) is an algorithm +which is used to drop old packets. It depends on the TCP +timestamps. For detail information, please refer the `timestamp wiki`_ +and the `RFC of PAWS`_. + +.. _RFC of PAWS: https://tools.ietf.org/html/rfc1323#page-17 +.. _timestamp wiki: https://en.wikipedia.org/wiki/Transmission_Control_Protocol#TCP_timestamps + +* TcpExtPAWSActive + +Packets are dropped by PAWS in Syn-Sent status. + +* TcpExtPAWSEstab + +Packets are dropped by PAWS in any status other than Syn-Sent. + +TCP ACK skip +============ +In some scenarios, kernel would avoid sending duplicate ACKs too +frequently. Please find more details in the tcp_invalid_ratelimit +section of the `sysctl document`_. When kernel decides to skip an ACK +due to tcp_invalid_ratelimit, kernel would update one of below +counters to indicate the ACK is skipped in which scenario. The ACK +would only be skipped if the received packet is either a SYN packet or +it has no data. + +.. _sysctl document: https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt + +* TcpExtTCPACKSkippedSynRecv + +The ACK is skipped in Syn-Recv status. The Syn-Recv status means the +TCP stack receives a SYN and replies SYN+ACK. Now the TCP stack is +waiting for an ACK. Generally, the TCP stack doesn't need to send ACK +in the Syn-Recv status. But in several scenarios, the TCP stack need +to send an ACK. E.g., the TCP stack receives the same SYN packet +repeately, the received packet does not pass the PAWS check, or the +received packet sequence number is out of window. In these scenarios, +the TCP stack needs to send ACK. If the ACk sending frequency is higher than +tcp_invalid_ratelimit allows, the TCP stack will skip sending ACK and +increase TcpExtTCPACKSkippedSynRecv. + + +* TcpExtTCPACKSkippedPAWS + +The ACK is skipped due to PAWS (Protect Against Wrapped Sequence +numbers) check fails. If the PAWS check fails in Syn-Recv, Fin-Wait-2 +or Time-Wait statuses, the skipped ACK would be counted to +TcpExtTCPACKSkippedSynRecv, TcpExtTCPACKSkippedFinWait2 or +TcpExtTCPACKSkippedTimeWait. In all other statuses, the skipped ACK +would be counted to TcpExtTCPACKSkippedPAWS. + +* TcpExtTCPACKSkippedSeq + +The sequence number is out of window and the timestamp passes the PAWS +check and the TCP status is not Syn-Recv, Fin-Wait-2, and Time-Wait. + +* TcpExtTCPACKSkippedFinWait2 + +The ACK is skipped in Fin-Wait-2 status, the reason would be either +PAWS check fails or the received sequence number is out of window. + +* TcpExtTCPACKSkippedTimeWait + +Tha ACK is skipped in Time-Wait status, the reason would be either +PAWS check failed or the received sequence number is out of window. + +* TcpExtTCPACKSkippedChallenge + +The ACK is skipped if the ACK is a challenge ACK. The RFC 5961 defines +3 kind of challenge ACK, please refer `RFC 5961 section 3.2`_, +`RFC 5961 section 4.2`_ and `RFC 5961 section 5.2`_. Besides these +three scenarios, In some TCP status, the linux TCP stack would also +send challenge ACKs if the ACK number is before the first +unacknowledged number (more strict than `RFC 5961 section 5.2`_). + +.. _RFC 5961 section 3.2: https://tools.ietf.org/html/rfc5961#page-7 +.. _RFC 5961 section 4.2: https://tools.ietf.org/html/rfc5961#page-9 +.. _RFC 5961 section 5.2: https://tools.ietf.org/html/rfc5961#page-11 + +TCP receive window +================== +* TcpExtTCPWantZeroWindowAdv + +Depending on current memory usage, the TCP stack tries to set receive +window to zero. But the receive window might still be a no-zero +value. For example, if the previous window size is 10, and the TCP +stack receives 3 bytes, the current window size would be 7 even if the +window size calculated by the memory usage is zero. + +* TcpExtTCPToZeroWindowAdv + +The TCP receive window is set to zero from a no-zero value. + +* TcpExtTCPFromZeroWindowAdv + +The TCP receive window is set to no-zero value from zero. + + +Delayed ACK +=========== +The TCP Delayed ACK is a technique which is used for reducing the +packet count in the network. For more details, please refer the +`Delayed ACK wiki`_ + +.. _Delayed ACK wiki: https://en.wikipedia.org/wiki/TCP_delayed_acknowledgment + +* TcpExtDelayedACKs + +A delayed ACK timer expires. The TCP stack will send a pure ACK packet +and exit the delayed ACK mode. + +* TcpExtDelayedACKLocked + +A delayed ACK timer expires, but the TCP stack can't send an ACK +immediately due to the socket is locked by a userspace program. The +TCP stack will send a pure ACK later (after the userspace program +unlock the socket). When the TCP stack sends the pure ACK later, the +TCP stack will also update TcpExtDelayedACKs and exit the delayed ACK +mode. + +* TcpExtDelayedACKLost + +It will be updated when the TCP stack receives a packet which has been +ACKed. A Delayed ACK loss might cause this issue, but it would also be +triggered by other reasons, such as a packet is duplicated in the +network. + +Tail Loss Probe (TLP) +===================== +TLP is an algorithm which is used to detect TCP packet loss. For more +details, please refer the `TLP paper`_. + +.. _TLP paper: https://tools.ietf.org/html/draft-dukkipati-tcpm-tcp-loss-probe-01 + +* TcpExtTCPLossProbes + +A TLP probe packet is sent. + +* TcpExtTCPLossProbeRecovery + +A packet loss is detected and recovered by TLP. + +TCP Fast Open +============= +TCP Fast Open is a technology which allows data transfer before the +3-way handshake complete. Please refer the `TCP Fast Open wiki`_ for a +general description. + +.. _TCP Fast Open wiki: https://en.wikipedia.org/wiki/TCP_Fast_Open + +* TcpExtTCPFastOpenActive + +When the TCP stack receives an ACK packet in the SYN-SENT status, and +the ACK packet acknowledges the data in the SYN packet, the TCP stack +understand the TFO cookie is accepted by the other side, then it +updates this counter. + +* TcpExtTCPFastOpenActiveFail + +This counter indicates that the TCP stack initiated a TCP Fast Open, +but it failed. This counter would be updated in three scenarios: (1) +the other side doesn't acknowledge the data in the SYN packet. (2) The +SYN packet which has the TFO cookie is timeout at least once. (3) +after the 3-way handshake, the retransmission timeout happens +net.ipv4.tcp_retries1 times, because some middle-boxes may black-hole +fast open after the handshake. + +* TcpExtTCPFastOpenPassive + +This counter indicates how many times the TCP stack accepts the fast +open request. + +* TcpExtTCPFastOpenPassiveFail + +This counter indicates how many times the TCP stack rejects the fast +open request. It is caused by either the TFO cookie is invalid or the +TCP stack finds an error during the socket creating process. + +* TcpExtTCPFastOpenListenOverflow + +When the pending fast open request number is larger than +fastopenq->max_qlen, the TCP stack will reject the fast open request +and update this counter. When this counter is updated, the TCP stack +won't update TcpExtTCPFastOpenPassive or +TcpExtTCPFastOpenPassiveFail. The fastopenq->max_qlen is set by the +TCP_FASTOPEN socket operation and it could not be larger than +net.core.somaxconn. For example: + +setsockopt(sfd, SOL_TCP, TCP_FASTOPEN, &qlen, sizeof(qlen)); + +* TcpExtTCPFastOpenCookieReqd + +This counter indicates how many times a client wants to request a TFO +cookie. + +SYN cookies +=========== +SYN cookies are used to mitigate SYN flood, for details, please refer +the `SYN cookies wiki`_. + +.. _SYN cookies wiki: https://en.wikipedia.org/wiki/SYN_cookies + +* TcpExtSyncookiesSent + +It indicates how many SYN cookies are sent. + +* TcpExtSyncookiesRecv + +How many reply packets of the SYN cookies the TCP stack receives. + +* TcpExtSyncookiesFailed + +The MSS decoded from the SYN cookie is invalid. When this counter is +updated, the received packet won't be treated as a SYN cookie and the +TcpExtSyncookiesRecv counter wont be updated. + +Challenge ACK +============= +For details of challenge ACK, please refer the explaination of +TcpExtTCPACKSkippedChallenge. + +* TcpExtTCPChallengeACK + +The number of challenge acks sent. + +* TcpExtTCPSYNChallenge + +The number of challenge acks sent in response to SYN packets. After +updates this counter, the TCP stack might send a challenge ACK and +update the TcpExtTCPChallengeACK counter, or it might also skip to +send the challenge and update the TcpExtTCPACKSkippedChallenge. + +prune +===== +When a socket is under memory pressure, the TCP stack will try to +reclaim memory from the receiving queue and out of order queue. One of +the reclaiming method is 'collapse', which means allocate a big sbk, +copy the contiguous skbs to the single big skb, and free these +contiguous skbs. + +* TcpExtPruneCalled + +The TCP stack tries to reclaim memory for a socket. After updates this +counter, the TCP stack will try to collapse the out of order queue and +the receiving queue. If the memory is still not enough, the TCP stack +will try to discard packets from the out of order queue (and update the +TcpExtOfoPruned counter) + +* TcpExtOfoPruned + +The TCP stack tries to discard packet on the out of order queue. + +* TcpExtRcvPruned + +After 'collapse' and discard packets from the out of order queue, if +the actually used memory is still larger than the max allowed memory, +this counter will be updated. It means the 'prune' fails. + +* TcpExtTCPRcvCollapsed + +This counter indicates how many skbs are freed during 'collapse'. + +examples +======== + +ping test +--------- +Run the ping command against the public dns server 8.8.8.8:: + + nstatuser@nstat-a:~$ ping 8.8.8.8 -c 1 + PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data. + 64 bytes from 8.8.8.8: icmp_seq=1 ttl=119 time=17.8 ms + + --- 8.8.8.8 ping statistics --- + 1 packets transmitted, 1 received, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 17.875/17.875/17.875/0.000 ms + +The nstayt result:: + + nstatuser@nstat-a:~$ nstat + #kernel + IpInReceives 1 0.0 + IpInDelivers 1 0.0 + IpOutRequests 1 0.0 + IcmpInMsgs 1 0.0 + IcmpInEchoReps 1 0.0 + IcmpOutMsgs 1 0.0 + IcmpOutEchos 1 0.0 + IcmpMsgInType0 1 0.0 + IcmpMsgOutType8 1 0.0 + IpExtInOctets 84 0.0 + IpExtOutOctets 84 0.0 + IpExtInNoECTPkts 1 0.0 + +The Linux server sent an ICMP Echo packet, so IpOutRequests, +IcmpOutMsgs, IcmpOutEchos and IcmpMsgOutType8 were increased 1. The +server got ICMP Echo Reply from 8.8.8.8, so IpInReceives, IcmpInMsgs, +IcmpInEchoReps and IcmpMsgInType0 were increased 1. The ICMP Echo Reply +was passed to the ICMP layer via IP layer, so IpInDelivers was +increased 1. The default ping data size is 48, so an ICMP Echo packet +and its corresponding Echo Reply packet are constructed by: + +* 14 bytes MAC header +* 20 bytes IP header +* 16 bytes ICMP header +* 48 bytes data (default value of the ping command) + +So the IpExtInOctets and IpExtOutOctets are 20+16+48=84. + +tcp 3-way handshake +------------------- +On server side, we run:: + + nstatuser@nstat-b:~$ nc -lknv 0.0.0.0 9000 + Listening on [0.0.0.0] (family 0, port 9000) + +On client side, we run:: + + nstatuser@nstat-a:~$ nc -nv 192.168.122.251 9000 + Connection to 192.168.122.251 9000 port [tcp/*] succeeded! + +The server listened on tcp 9000 port, the client connected to it, they +completed the 3-way handshake. + +On server side, we can find below nstat output:: + + nstatuser@nstat-b:~$ nstat | grep -i tcp + TcpPassiveOpens 1 0.0 + TcpInSegs 2 0.0 + TcpOutSegs 1 0.0 + TcpExtTCPPureAcks 1 0.0 + +On client side, we can find below nstat output:: + + nstatuser@nstat-a:~$ nstat | grep -i tcp + TcpActiveOpens 1 0.0 + TcpInSegs 1 0.0 + TcpOutSegs 2 0.0 + +When the server received the first SYN, it replied a SYN+ACK, and came into +SYN-RCVD state, so TcpPassiveOpens increased 1. The server received +SYN, sent SYN+ACK, received ACK, so server sent 1 packet, received 2 +packets, TcpInSegs increased 2, TcpOutSegs increased 1. The last ACK +of the 3-way handshake is a pure ACK without data, so +TcpExtTCPPureAcks increased 1. + +When the client sent SYN, the client came into the SYN-SENT state, so +TcpActiveOpens increased 1, the client sent SYN, received SYN+ACK, sent +ACK, so client sent 2 packets, received 1 packet, TcpInSegs increased +1, TcpOutSegs increased 2. + +TCP normal traffic +------------------ +Run nc on server:: + + nstatuser@nstat-b:~$ nc -lkv 0.0.0.0 9000 + Listening on [0.0.0.0] (family 0, port 9000) + +Run nc on client:: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + +Input a string in the nc client ('hello' in our example):: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + hello + +The client side nstat output:: + + nstatuser@nstat-a:~$ nstat + #kernel + IpInReceives 1 0.0 + IpInDelivers 1 0.0 + IpOutRequests 1 0.0 + TcpInSegs 1 0.0 + TcpOutSegs 1 0.0 + TcpExtTCPPureAcks 1 0.0 + TcpExtTCPOrigDataSent 1 0.0 + IpExtInOctets 52 0.0 + IpExtOutOctets 58 0.0 + IpExtInNoECTPkts 1 0.0 + +The server side nstat output:: + + nstatuser@nstat-b:~$ nstat + #kernel + IpInReceives 1 0.0 + IpInDelivers 1 0.0 + IpOutRequests 1 0.0 + TcpInSegs 1 0.0 + TcpOutSegs 1 0.0 + IpExtInOctets 58 0.0 + IpExtOutOctets 52 0.0 + IpExtInNoECTPkts 1 0.0 + +Input a string in nc client side again ('world' in our exmaple):: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + hello + world + +Client side nstat output:: + + nstatuser@nstat-a:~$ nstat + #kernel + IpInReceives 1 0.0 + IpInDelivers 1 0.0 + IpOutRequests 1 0.0 + TcpInSegs 1 0.0 + TcpOutSegs 1 0.0 + TcpExtTCPHPAcks 1 0.0 + TcpExtTCPOrigDataSent 1 0.0 + IpExtInOctets 52 0.0 + IpExtOutOctets 58 0.0 + IpExtInNoECTPkts 1 0.0 + + +Server side nstat output:: + + nstatuser@nstat-b:~$ nstat + #kernel + IpInReceives 1 0.0 + IpInDelivers 1 0.0 + IpOutRequests 1 0.0 + TcpInSegs 1 0.0 + TcpOutSegs 1 0.0 + TcpExtTCPHPHits 1 0.0 + IpExtInOctets 58 0.0 + IpExtOutOctets 52 0.0 + IpExtInNoECTPkts 1 0.0 + +Compare the first client-side nstat and the second client-side nstat, +we could find one difference: the first one had a 'TcpExtTCPPureAcks', +but the second one had a 'TcpExtTCPHPAcks'. The first server-side +nstat and the second server-side nstat had a difference too: the +second server-side nstat had a TcpExtTCPHPHits, but the first +server-side nstat didn't have it. The network traffic patterns were +exactly the same: the client sent a packet to the server, the server +replied an ACK. But kernel handled them in different ways. When the +TCP window scale option is not used, kernel will try to enable fast +path immediately when the connection comes into the established state, +but if the TCP window scale option is used, kernel will disable the +fast path at first, and try to enable it after kerenl receives +packets. We could use the 'ss' command to verify whether the window +scale option is used. e.g. run below command on either server or +client:: + + nstatuser@nstat-a:~$ ss -o state established -i '( dport = :9000 or sport = :9000 ) + Netid Recv-Q Send-Q Local Address:Port Peer Address:Port + tcp 0 0 192.168.122.250:40654 192.168.122.251:9000 + ts sack cubic wscale:7,7 rto:204 rtt:0.98/0.49 mss:1448 pmtu:1500 rcvmss:536 advmss:1448 cwnd:10 bytes_acked:1 segs_out:2 segs_in:1 send 118.2Mbps lastsnd:46572 lastrcv:46572 lastack:46572 pacing_rate 236.4Mbps rcv_space:29200 rcv_ssthresh:29200 minrtt:0.98 + +The 'wscale:7,7' means both server and client set the window scale +option to 7. Now we could explain the nstat output in our test: + +In the first nstat output of client side, the client sent a packet, server +reply an ACK, when kernel handled this ACK, the fast path was not +enabled, so the ACK was counted into 'TcpExtTCPPureAcks'. + +In the second nstat output of client side, the client sent a packet again, +and received another ACK from the server, in this time, the fast path is +enabled, and the ACK was qualified for fast path, so it was handled by +the fast path, so this ACK was counted into TcpExtTCPHPAcks. + +In the first nstat output of server side, fast path was not enabled, +so there was no 'TcpExtTCPHPHits'. + +In the second nstat output of server side, the fast path was enabled, +and the packet received from client qualified for fast path, so it +was counted into 'TcpExtTCPHPHits'. + +TcpExtTCPAbortOnClose +--------------------- +On the server side, we run below python script:: + + import socket + import time + + port = 9000 + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.bind(('0.0.0.0', port)) + s.listen(1) + sock, addr = s.accept() + while True: + time.sleep(9999999) + +This python script listen on 9000 port, but doesn't read anything from +the connection. + +On the client side, we send the string "hello" by nc:: + + nstatuser@nstat-a:~$ echo "hello" | nc nstat-b 9000 + +Then, we come back to the server side, the server has received the "hello" +packet, and the TCP layer has acked this packet, but the application didn't +read it yet. We type Ctrl-C to terminate the server script. Then we +could find TcpExtTCPAbortOnClose increased 1 on the server side:: + + nstatuser@nstat-b:~$ nstat | grep -i abort + TcpExtTCPAbortOnClose 1 0.0 + +If we run tcpdump on the server side, we could find the server sent a +RST after we type Ctrl-C. + +TcpExtTCPAbortOnMemory and TcpExtTCPAbortOnTimeout +--------------------------------------------------- +Below is an example which let the orphan socket count be higher than +net.ipv4.tcp_max_orphans. +Change tcp_max_orphans to a smaller value on client:: + + sudo bash -c "echo 10 > /proc/sys/net/ipv4/tcp_max_orphans" + +Client code (create 64 connection to server):: + + nstatuser@nstat-a:~$ cat client_orphan.py + import socket + import time + + server = 'nstat-b' # server address + port = 9000 + + count = 64 + + connection_list = [] + + for i in range(64): + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.connect((server, port)) + connection_list.append(s) + print("connection_count: %d" % len(connection_list)) + + while True: + time.sleep(99999) + +Server code (accept 64 connection from client):: + + nstatuser@nstat-b:~$ cat server_orphan.py + import socket + import time + + port = 9000 + count = 64 + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.bind(('0.0.0.0', port)) + s.listen(count) + connection_list = [] + while True: + sock, addr = s.accept() + connection_list.append((sock, addr)) + print("connection_count: %d" % len(connection_list)) + +Run the python scripts on server and client. + +On server:: + + python3 server_orphan.py + +On client:: + + python3 client_orphan.py + +Run iptables on server:: + + sudo iptables -A INPUT -i ens3 -p tcp --destination-port 9000 -j DROP + +Type Ctrl-C on client, stop client_orphan.py. + +Check TcpExtTCPAbortOnMemory on client:: + + nstatuser@nstat-a:~$ nstat | grep -i abort + TcpExtTCPAbortOnMemory 54 0.0 + +Check orphane socket count on client:: + + nstatuser@nstat-a:~$ ss -s + Total: 131 (kernel 0) + TCP: 14 (estab 1, closed 0, orphaned 10, synrecv 0, timewait 0/0), ports 0 + + Transport Total IP IPv6 + * 0 - - + RAW 1 0 1 + UDP 1 1 0 + TCP 14 13 1 + INET 16 14 2 + FRAG 0 0 0 + +The explanation of the test: after run server_orphan.py and +client_orphan.py, we set up 64 connections between server and +client. Run the iptables command, the server will drop all packets from +the client, type Ctrl-C on client_orphan.py, the system of the client +would try to close these connections, and before they are closed +gracefully, these connections became orphan sockets. As the iptables +of the server blocked packets from the client, the server won't receive fin +from the client, so all connection on clients would be stuck on FIN_WAIT_1 +stage, so they will keep as orphan sockets until timeout. We have echo +10 to /proc/sys/net/ipv4/tcp_max_orphans, so the client system would +only keep 10 orphan sockets, for all other orphan sockets, the client +system sent RST for them and delete them. We have 64 connections, so +the 'ss -s' command shows the system has 10 orphan sockets, and the +value of TcpExtTCPAbortOnMemory was 54. + +An additional explanation about orphan socket count: You could find the +exactly orphan socket count by the 'ss -s' command, but when kernel +decide whither increases TcpExtTCPAbortOnMemory and sends RST, kernel +doesn't always check the exactly orphan socket count. For increasing +performance, kernel checks an approximate count firstly, if the +approximate count is more than tcp_max_orphans, kernel checks the +exact count again. So if the approximate count is less than +tcp_max_orphans, but exactly count is more than tcp_max_orphans, you +would find TcpExtTCPAbortOnMemory is not increased at all. If +tcp_max_orphans is large enough, it won't occur, but if you decrease +tcp_max_orphans to a small value like our test, you might find this +issue. So in our test, the client set up 64 connections although the +tcp_max_orphans is 10. If the client only set up 11 connections, we +can't find the change of TcpExtTCPAbortOnMemory. + +Continue the previous test, we wait for several minutes. Because of the +iptables on the server blocked the traffic, the server wouldn't receive +fin, and all the client's orphan sockets would timeout on the +FIN_WAIT_1 state finally. So we wait for a few minutes, we could find +10 timeout on the client:: + + nstatuser@nstat-a:~$ nstat | grep -i abort + TcpExtTCPAbortOnTimeout 10 0.0 + +TcpExtTCPAbortOnLinger +---------------------- +The server side code:: + + nstatuser@nstat-b:~$ cat server_linger.py + import socket + import time + + port = 9000 + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.bind(('0.0.0.0', port)) + s.listen(1) + sock, addr = s.accept() + while True: + time.sleep(9999999) + +The client side code:: + + nstatuser@nstat-a:~$ cat client_linger.py + import socket + import struct + + server = 'nstat-b' # server address + port = 9000 + + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack('ii', 1, 10)) + s.setsockopt(socket.SOL_TCP, socket.TCP_LINGER2, struct.pack('i', -1)) + s.connect((server, port)) + s.close() + +Run server_linger.py on server:: + + nstatuser@nstat-b:~$ python3 server_linger.py + +Run client_linger.py on client:: + + nstatuser@nstat-a:~$ python3 client_linger.py + +After run client_linger.py, check the output of nstat:: + + nstatuser@nstat-a:~$ nstat | grep -i abort + TcpExtTCPAbortOnLinger 1 0.0 + +TcpExtTCPRcvCoalesce +-------------------- +On the server, we run a program which listen on TCP port 9000, but +doesn't read any data:: + + import socket + import time + port = 9000 + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.bind(('0.0.0.0', port)) + s.listen(1) + sock, addr = s.accept() + while True: + time.sleep(9999999) + +Save the above code as server_coalesce.py, and run:: + + python3 server_coalesce.py + +On the client, save below code as client_coalesce.py:: + + import socket + server = 'nstat-b' + port = 9000 + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + s.connect((server, port)) + +Run:: + + nstatuser@nstat-a:~$ python3 -i client_coalesce.py + +We use '-i' to come into the interactive mode, then a packet:: + + >>> s.send(b'foo') + 3 + +Send a packet again:: + + >>> s.send(b'bar') + 3 + +On the server, run nstat:: + + ubuntu@nstat-b:~$ nstat + #kernel + IpInReceives 2 0.0 + IpInDelivers 2 0.0 + IpOutRequests 2 0.0 + TcpInSegs 2 0.0 + TcpOutSegs 2 0.0 + TcpExtTCPRcvCoalesce 1 0.0 + IpExtInOctets 110 0.0 + IpExtOutOctets 104 0.0 + IpExtInNoECTPkts 2 0.0 + +The client sent two packets, server didn't read any data. When +the second packet arrived at server, the first packet was still in +the receiving queue. So the TCP layer merged the two packets, and we +could find the TcpExtTCPRcvCoalesce increased 1. + +TcpExtListenOverflows and TcpExtListenDrops +------------------------------------------- +On server, run the nc command, listen on port 9000:: + + nstatuser@nstat-b:~$ nc -lkv 0.0.0.0 9000 + Listening on [0.0.0.0] (family 0, port 9000) + +On client, run 3 nc commands in different terminals:: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + +The nc command only accepts 1 connection, and the accept queue length +is 1. On current linux implementation, set queue length to n means the +actual queue length is n+1. Now we create 3 connections, 1 is accepted +by nc, 2 in accepted queue, so the accept queue is full. + +Before running the 4th nc, we clean the nstat history on the server:: + + nstatuser@nstat-b:~$ nstat -n + +Run the 4th nc on the client:: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + +If the nc server is running on kernel 4.10 or higher version, you +won't see the "Connection to ... succeeded!" string, because kernel +will drop the SYN if the accept queue is full. If the nc client is running +on an old kernel, you would see that the connection is succeeded, +because kernel would complete the 3 way handshake and keep the socket +on half open queue. I did the test on kernel 4.15. Below is the nstat +on the server:: + + nstatuser@nstat-b:~$ nstat + #kernel + IpInReceives 4 0.0 + IpInDelivers 4 0.0 + TcpInSegs 4 0.0 + TcpExtListenOverflows 4 0.0 + TcpExtListenDrops 4 0.0 + IpExtInOctets 240 0.0 + IpExtInNoECTPkts 4 0.0 + +Both TcpExtListenOverflows and TcpExtListenDrops were 4. If the time +between the 4th nc and the nstat was longer, the value of +TcpExtListenOverflows and TcpExtListenDrops would be larger, because +the SYN of the 4th nc was dropped, the client was retrying. + +IpInAddrErrors, IpExtInNoRoutes and IpOutNoRoutes +------------------------------------------------- +server A IP address: 192.168.122.250 +server B IP address: 192.168.122.251 +Prepare on server A, add a route to server B:: + + $ sudo ip route add 8.8.8.8/32 via 192.168.122.251 + +Prepare on server B, disable send_redirects for all interfaces:: + + $ sudo sysctl -w net.ipv4.conf.all.send_redirects=0 + $ sudo sysctl -w net.ipv4.conf.ens3.send_redirects=0 + $ sudo sysctl -w net.ipv4.conf.lo.send_redirects=0 + $ sudo sysctl -w net.ipv4.conf.default.send_redirects=0 + +We want to let sever A send a packet to 8.8.8.8, and route the packet +to server B. When server B receives such packet, it might send a ICMP +Redirect message to server A, set send_redirects to 0 will disable +this behavior. + +First, generate InAddrErrors. On server B, we disable IP forwarding:: + + $ sudo sysctl -w net.ipv4.conf.all.forwarding=0 + +On server A, we send packets to 8.8.8.8:: + + $ nc -v 8.8.8.8 53 + +On server B, we check the output of nstat:: + + $ nstat + #kernel + IpInReceives 3 0.0 + IpInAddrErrors 3 0.0 + IpExtInOctets 180 0.0 + IpExtInNoECTPkts 3 0.0 + +As we have let server A route 8.8.8.8 to server B, and we disabled IP +forwarding on server B, Server A sent packets to server B, then server B +dropped packets and increased IpInAddrErrors. As the nc command would +re-send the SYN packet if it didn't receive a SYN+ACK, we could find +multiple IpInAddrErrors. + +Second, generate IpExtInNoRoutes. On server B, we enable IP +forwarding:: + + $ sudo sysctl -w net.ipv4.conf.all.forwarding=1 + +Check the route table of server B and remove the default route:: + + $ ip route show + default via 192.168.122.1 dev ens3 proto static + 192.168.122.0/24 dev ens3 proto kernel scope link src 192.168.122.251 + $ sudo ip route delete default via 192.168.122.1 dev ens3 proto static + +On server A, we contact 8.8.8.8 again:: + + $ nc -v 8.8.8.8 53 + nc: connect to 8.8.8.8 port 53 (tcp) failed: Network is unreachable + +On server B, run nstat:: + + $ nstat + #kernel + IpInReceives 1 0.0 + IpOutRequests 1 0.0 + IcmpOutMsgs 1 0.0 + IcmpOutDestUnreachs 1 0.0 + IcmpMsgOutType3 1 0.0 + IpExtInNoRoutes 1 0.0 + IpExtInOctets 60 0.0 + IpExtOutOctets 88 0.0 + IpExtInNoECTPkts 1 0.0 + +We enabled IP forwarding on server B, when server B received a packet +which destination IP address is 8.8.8.8, server B will try to forward +this packet. We have deleted the default route, there was no route for +8.8.8.8, so server B increase IpExtInNoRoutes and sent the "ICMP +Destination Unreachable" message to server A. + +Third, generate IpOutNoRoutes. Run ping command on server B:: + + $ ping -c 1 8.8.8.8 + connect: Network is unreachable + +Run nstat on server B:: + + $ nstat + #kernel + IpOutNoRoutes 1 0.0 + +We have deleted the default route on server B. Server B couldn't find +a route for the 8.8.8.8 IP address, so server B increased +IpOutNoRoutes. + +TcpExtTCPACKSkippedSynRecv +-------------------------- +In this test, we send 3 same SYN packets from client to server. The +first SYN will let server create a socket, set it to Syn-Recv status, +and reply a SYN/ACK. The second SYN will let server reply the SYN/ACK +again, and record the reply time (the duplicate ACK reply time). The +third SYN will let server check the previous duplicate ACK reply time, +and decide to skip the duplicate ACK, then increase the +TcpExtTCPACKSkippedSynRecv counter. + +Run tcpdump to capture a SYN packet:: + + nstatuser@nstat-a:~$ sudo tcpdump -c 1 -w /tmp/syn.pcap port 9000 + tcpdump: listening on ens3, link-type EN10MB (Ethernet), capture size 262144 bytes + +Open another terminal, run nc command:: + + nstatuser@nstat-a:~$ nc nstat-b 9000 + +As the nstat-b didn't listen on port 9000, it should reply a RST, and +the nc command exited immediately. It was enough for the tcpdump +command to capture a SYN packet. A linux server might use hardware +offload for the TCP checksum, so the checksum in the /tmp/syn.pcap +might be not correct. We call tcprewrite to fix it:: + + nstatuser@nstat-a:~$ tcprewrite --infile=/tmp/syn.pcap --outfile=/tmp/syn_fixcsum.pcap --fixcsum + +On nstat-b, we run nc to listen on port 9000:: + + nstatuser@nstat-b:~$ nc -lkv 9000 + Listening on [0.0.0.0] (family 0, port 9000) + +On nstat-a, we blocked the packet from port 9000, or nstat-a would send +RST to nstat-b:: + + nstatuser@nstat-a:~$ sudo iptables -A INPUT -p tcp --sport 9000 -j DROP + +Send 3 SYN repeatly to nstat-b:: + + nstatuser@nstat-a:~$ for i in {1..3}; do sudo tcpreplay -i ens3 /tmp/syn_fixcsum.pcap; done + +Check snmp cunter on nstat-b:: + + nstatuser@nstat-b:~$ nstat | grep -i skip + TcpExtTCPACKSkippedSynRecv 1 0.0 + +As we expected, TcpExtTCPACKSkippedSynRecv is 1. + +TcpExtTCPACKSkippedPAWS +----------------------- +To trigger PAWS, we could send an old SYN. + +On nstat-b, let nc listen on port 9000:: + + nstatuser@nstat-b:~$ nc -lkv 9000 + Listening on [0.0.0.0] (family 0, port 9000) + +On nstat-a, run tcpdump to capture a SYN:: + + nstatuser@nstat-a:~$ sudo tcpdump -w /tmp/paws_pre.pcap -c 1 port 9000 + tcpdump: listening on ens3, link-type EN10MB (Ethernet), capture size 262144 bytes + +On nstat-a, run nc as a client to connect nstat-b:: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + +Now the tcpdump has captured the SYN and exit. We should fix the +checksum:: + + nstatuser@nstat-a:~$ tcprewrite --infile /tmp/paws_pre.pcap --outfile /tmp/paws.pcap --fixcsum + +Send the SYN packet twice:: + + nstatuser@nstat-a:~$ for i in {1..2}; do sudo tcpreplay -i ens3 /tmp/paws.pcap; done + +On nstat-b, check the snmp counter:: + + nstatuser@nstat-b:~$ nstat | grep -i skip + TcpExtTCPACKSkippedPAWS 1 0.0 + +We sent two SYN via tcpreplay, both of them would let PAWS check +failed, the nstat-b replied an ACK for the first SYN, skipped the ACK +for the second SYN, and updated TcpExtTCPACKSkippedPAWS. + +TcpExtTCPACKSkippedSeq +---------------------- +To trigger TcpExtTCPACKSkippedSeq, we send packets which have valid +timestamp (to pass PAWS check) but the sequence number is out of +window. The linux TCP stack would avoid to skip if the packet has +data, so we need a pure ACK packet. To generate such a packet, we +could create two sockets: one on port 9000, another on port 9001. Then +we capture an ACK on port 9001, change the source/destination port +numbers to match the port 9000 socket. Then we could trigger +TcpExtTCPACKSkippedSeq via this packet. + +On nstat-b, open two terminals, run two nc commands to listen on both +port 9000 and port 9001:: + + nstatuser@nstat-b:~$ nc -lkv 9000 + Listening on [0.0.0.0] (family 0, port 9000) + + nstatuser@nstat-b:~$ nc -lkv 9001 + Listening on [0.0.0.0] (family 0, port 9001) + +On nstat-a, run two nc clients:: + + nstatuser@nstat-a:~$ nc -v nstat-b 9000 + Connection to nstat-b 9000 port [tcp/*] succeeded! + + nstatuser@nstat-a:~$ nc -v nstat-b 9001 + Connection to nstat-b 9001 port [tcp/*] succeeded! + +On nstat-a, run tcpdump to capture an ACK:: + + nstatuser@nstat-a:~$ sudo tcpdump -w /tmp/seq_pre.pcap -c 1 dst port 9001 + tcpdump: listening on ens3, link-type EN10MB (Ethernet), capture size 262144 bytes + +On nstat-b, send a packet via the port 9001 socket. E.g. we sent a +string 'foo' in our example:: + + nstatuser@nstat-b:~$ nc -lkv 9001 + Listening on [0.0.0.0] (family 0, port 9001) + Connection from nstat-a 42132 received! + foo + +On nstat-a, the tcpdump should have caputred the ACK. We should check +the source port numbers of the two nc clients:: + + nstatuser@nstat-a:~$ ss -ta '( dport = :9000 || dport = :9001 )' | tee + State Recv-Q Send-Q Local Address:Port Peer Address:Port + ESTAB 0 0 192.168.122.250:50208 192.168.122.251:9000 + ESTAB 0 0 192.168.122.250:42132 192.168.122.251:9001 + +Run tcprewrite, change port 9001 to port 9000, chagne port 42132 to +port 50208:: + + nstatuser@nstat-a:~$ tcprewrite --infile /tmp/seq_pre.pcap --outfile /tmp/seq.pcap -r 9001:9000 -r 42132:50208 --fixcsum + +Now the /tmp/seq.pcap is the packet we need. Send it to nstat-b:: + + nstatuser@nstat-a:~$ for i in {1..2}; do sudo tcpreplay -i ens3 /tmp/seq.pcap; done + +Check TcpExtTCPACKSkippedSeq on nstat-b:: + + nstatuser@nstat-b:~$ nstat | grep -i skip + TcpExtTCPACKSkippedSeq 1 0.0 diff --git a/Documentation/networking/switchdev.txt b/Documentation/networking/switchdev.txt index 82236a17b5e6..86174ce8cd13 100644 --- a/Documentation/networking/switchdev.txt +++ b/Documentation/networking/switchdev.txt @@ -92,11 +92,11 @@ device. Switch ID ^^^^^^^^^ -The switchdev driver must implement the switchdev op switchdev_port_attr_get -for SWITCHDEV_ATTR_ID_PORT_PARENT_ID for each port netdev, returning the same -physical ID for each port of a switch. The ID must be unique between switches -on the same system. The ID does not need to be unique between switches on -different systems. +The switchdev driver must implement the net_device operation +ndo_get_port_parent_id for each port netdev, returning the same physical ID for +each port of a switch. The ID must be unique between switches on the same +system. The ID does not need to be unique between switches on different +systems. The switch ID is used to locate ports on a switch and to know if aggregated ports belong to the same switch. @@ -196,7 +196,7 @@ The switch device will learn/forget source MAC address/VLAN on ingress packets and notify the switch driver of the mac/vlan/port tuples. The switch driver, in turn, will notify the bridge driver using the switchdev notifier call: - err = call_switchdev_notifiers(val, dev, info); + err = call_switchdev_notifiers(val, dev, info, extack); Where val is SWITCHDEV_FDB_ADD when learning and SWITCHDEV_FDB_DEL when forgetting, and info points to a struct switchdev_notifier_fdb_info. On @@ -232,10 +232,8 @@ Learning_sync attribute enables syncing of the learned/forgotten FDB entry to the bridge's FDB. It's possible, but not optimal, to enable learning on the device port and on the bridge port, and disable learning_sync. -To support learning and learning_sync port attributes, the driver implements -switchdev op switchdev_port_attr_get/set for -SWITCHDEV_ATTR_PORT_ID_BRIDGE_FLAGS. The driver should initialize the attributes -to the hardware defaults. +To support learning, the driver implements switchdev op +switchdev_port_attr_set for SWITCHDEV_ATTR_PORT_ID_{PRE}_BRIDGE_FLAGS. FDB Ageing ^^^^^^^^^^ @@ -373,22 +371,3 @@ The driver can monitor for updates to arp_tbl using the netevent notifier NETEVENT_NEIGH_UPDATE. The device can be programmed with resolved nexthops for the routes as arp_tbl updates. The driver implements ndo_neigh_destroy to know when arp_tbl neighbor entries are purged from the port. - -Transaction item queue -^^^^^^^^^^^^^^^^^^^^^^ - -For switchdev ops attr_set and obj_add, there is a 2 phase transaction model -used. First phase is to "prepare" anything needed, including various checks, -memory allocation, etc. The goal is to handle the stuff that is not unlikely -to fail here. The second phase is to "commit" the actual changes. - -Switchdev provides an infrastructure for sharing items (for example memory -allocations) between the two phases. - -The object created by a driver in "prepare" phase and it is queued up by: -switchdev_trans_item_enqueue() -During the "commit" phase, the driver gets the object by: -switchdev_trans_item_dequeue() - -If a transaction is aborted during "prepare" phase, switchdev code will handle -cleanup of the queued-up objects. diff --git a/Documentation/networking/timestamping.txt b/Documentation/networking/timestamping.txt index 1be0b6f9e0cb..bbdaf8990031 100644 --- a/Documentation/networking/timestamping.txt +++ b/Documentation/networking/timestamping.txt @@ -6,11 +6,21 @@ The interfaces for receiving network packages timestamps are: * SO_TIMESTAMP Generates a timestamp for each incoming packet in (not necessarily monotonic) system time. Reports the timestamp via recvmsg() in a - control message as struct timeval (usec resolution). + control message in usec resolution. + SO_TIMESTAMP is defined as SO_TIMESTAMP_NEW or SO_TIMESTAMP_OLD + based on the architecture type and time_t representation of libc. + Control message format is in struct __kernel_old_timeval for + SO_TIMESTAMP_OLD and in struct __kernel_sock_timeval for + SO_TIMESTAMP_NEW options respectively. * SO_TIMESTAMPNS Same timestamping mechanism as SO_TIMESTAMP, but reports the - timestamp as struct timespec (nsec resolution). + timestamp as struct timespec in nsec resolution. + SO_TIMESTAMPNS is defined as SO_TIMESTAMPNS_NEW or SO_TIMESTAMPNS_OLD + based on the architecture type and time_t representation of libc. + Control message format is in struct timespec for SO_TIMESTAMPNS_OLD + and in struct __kernel_timespec for SO_TIMESTAMPNS_NEW options + respectively. * IP_MULTICAST_LOOP + SO_TIMESTAMP[NS] Only for multicast:approximate transmit timestamp obtained by @@ -22,7 +32,7 @@ The interfaces for receiving network packages timestamps are: timestamps for stream sockets. -1.1 SO_TIMESTAMP: +1.1 SO_TIMESTAMP (also SO_TIMESTAMP_OLD and SO_TIMESTAMP_NEW): This socket option enables timestamping of datagrams on the reception path. Because the destination socket, if any, is not known early in @@ -31,15 +41,25 @@ same is true for all early receive timestamp options. For interface details, see `man 7 socket`. +Always use SO_TIMESTAMP_NEW timestamp to always get timestamp in +struct __kernel_sock_timeval format. -1.2 SO_TIMESTAMPNS: +SO_TIMESTAMP_OLD returns incorrect timestamps after the year 2038 +on 32 bit machines. + +1.2 SO_TIMESTAMPNS (also SO_TIMESTAMPNS_OLD and SO_TIMESTAMPNS_NEW): This option is identical to SO_TIMESTAMP except for the returned data type. Its struct timespec allows for higher resolution (ns) timestamps than the timeval of SO_TIMESTAMP (ms). +Always use SO_TIMESTAMPNS_NEW timestamp to always get timestamp in +struct __kernel_timespec format. + +SO_TIMESTAMPNS_OLD returns incorrect timestamps after the year 2038 +on 32 bit machines. -1.3 SO_TIMESTAMPING: +1.3 SO_TIMESTAMPING (also SO_TIMESTAMPING_OLD and SO_TIMESTAMPING_NEW): Supports multiple types of timestamp requests. As a result, this socket option takes a bitmap of flags, not a boolean. In @@ -323,10 +343,23 @@ SO_TIMESTAMP and SO_TIMESTAMPNS records can be retrieved. These timestamps are returned in a control message with cmsg_level SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type +For SO_TIMESTAMPING_OLD: + struct scm_timestamping { struct timespec ts[3]; }; +For SO_TIMESTAMPING_NEW: + +struct scm_timestamping64 { + struct __kernel_timespec ts[3]; + +Always use SO_TIMESTAMPING_NEW timestamp to always get timestamp in +struct scm_timestamping64 format. + +SO_TIMESTAMPING_OLD returns incorrect timestamps after the year 2038 +on 32 bit machines. + The structure can return up to three timestamps. This is a legacy feature. At least one field is non-zero at any time. Most timestamps are passed in ts[0]. Hardware timestamps are passed in ts[2]. @@ -417,7 +450,7 @@ is again deprecated and ts[2] holds a hardware timestamp if set. Hardware time stamping must also be initialized for each device driver that is expected to do hardware time stamping. The parameter is defined in -/include/linux/net_tstamp.h as: +include/uapi/linux/net_tstamp.h as: struct hwtstamp_config { int flags; /* no flags defined right now, must be zero */ @@ -487,7 +520,7 @@ enum { HWTSTAMP_FILTER_PTP_V1_L4_EVENT, /* for the complete list of values, please check - * the include file /include/linux/net_tstamp.h + * the include file include/uapi/linux/net_tstamp.h */ }; diff --git a/Documentation/networking/vrf.txt b/Documentation/networking/vrf.txt index 8ff7b4c8f91b..a5f103b083a0 100644 --- a/Documentation/networking/vrf.txt +++ b/Documentation/networking/vrf.txt @@ -103,19 +103,33 @@ VRF device: or to specify the output device using cmsg and IP_PKTINFO. +By default the scope of the port bindings for unbound sockets is +limited to the default VRF. That is, it will not be matched by packets +arriving on interfaces enslaved to an l3mdev and processes may bind to +the same port if they bind to an l3mdev. + 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 +These options are disabled by default so that a socket in a VRF is only +selected for packets in that VRF. There is a similar option for RAW +sockets, which is enabled by default for reasons of backwards compatibility. +This is so as to specify the output device with cmsg and IP_PKTINFO, but +using a socket not bound to the corresponding VRF. This allows e.g. older ping +implementations to be run with specifying the device but without executing it +in the VRF. This option can be disabled so that packets received in a VRF +context are only handled by a raw socket bound to the VRF, and packets in the +default VRF are only handled by a socket not bound to any VRF: + + sysctl -w net.ipv4.raw_l3mdev_accept=0 + netfilter rules on the VRF device can be used to limit access to services running in the default VRF context as well. -The default VRF does not have limited scope with respect to port bindings. -That is, if a process does a wildcard bind to a port in the default VRF it -owns the port across all VRF domains within the network namespace. - ################################################################################ Using iproute2 for VRFs diff --git a/Documentation/networking/xfrm_device.txt b/Documentation/networking/xfrm_device.txt index 267f55b5f54a..a1c904dc70dc 100644 --- a/Documentation/networking/xfrm_device.txt +++ b/Documentation/networking/xfrm_device.txt @@ -111,9 +111,10 @@ the stack in xfrm_input(). xfrm_state_hold(xs); store the state information into the skb - skb->sp = secpath_dup(skb->sp); - skb->sp->xvec[skb->sp->len++] = xs; - skb->sp->olen++; + sp = secpath_set(skb); + if (!sp) return; + sp->xvec[sp->len++] = xs; + sp->olen++; indicate the success and/or error status of the offload xo = xfrm_offload(skb); diff --git a/Documentation/nvdimm/security.txt b/Documentation/nvdimm/security.txt new file mode 100644 index 000000000000..4c36c05ca98e --- /dev/null +++ b/Documentation/nvdimm/security.txt @@ -0,0 +1,141 @@ +NVDIMM SECURITY +=============== + +1. Introduction +--------------- + +With the introduction of Intel Device Specific Methods (DSM) v1.8 +specification [1], security DSMs are introduced. The spec added the following +security DSMs: "get security state", "set passphrase", "disable passphrase", +"unlock unit", "freeze lock", "secure erase", and "overwrite". A security_ops +data structure has been added to struct dimm in order to support the security +operations and generic APIs are exposed to allow vendor neutral operations. + +2. Sysfs Interface +------------------ +The "security" sysfs attribute is provided in the nvdimm sysfs directory. For +example: +/sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security + +The "show" attribute of that attribute will display the security state for +that DIMM. The following states are available: disabled, unlocked, locked, +frozen, and overwrite. If security is not supported, the sysfs attribute +will not be visible. + +The "store" attribute takes several commands when it is being written to +in order to support some of the security functionalities: +update <old_keyid> <new_keyid> - enable or update passphrase. +disable <keyid> - disable enabled security and remove key. +freeze - freeze changing of security states. +erase <keyid> - delete existing user encryption key. +overwrite <keyid> - wipe the entire nvdimm. +master_update <keyid> <new_keyid> - enable or update master passphrase. +master_erase <keyid> - delete existing user encryption key. + +3. Key Management +----------------- + +The key is associated to the payload by the DIMM id. For example: +# cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id +8089-a2-1740-00000133 +The DIMM id would be provided along with the key payload (passphrase) to +the kernel. + +The security keys are managed on the basis of a single key per DIMM. The +key "passphrase" is expected to be 32bytes long. This is similar to the ATA +security specification [2]. A key is initially acquired via the request_key() +kernel API call during nvdimm unlock. It is up to the user to make sure that +all the keys are in the kernel user keyring for unlock. + +A nvdimm encrypted-key of format enc32 has the description format of: +nvdimm:<bus-provider-specific-unique-id> + +See file ``Documentation/security/keys/trusted-encrypted.rst`` for creating +encrypted-keys of enc32 format. TPM usage with a master trusted key is +preferred for sealing the encrypted-keys. + +4. Unlocking +------------ +When the DIMMs are being enumerated by the kernel, the kernel will attempt to +retrieve the key from the kernel user keyring. This is the only time +a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked +until reboot. Typically an entity (i.e. shell script) will inject all the +relevant encrypted-keys into the kernel user keyring during the initramfs phase. +This provides the unlock function access to all the related keys that contain +the passphrase for the respective nvdimms. It is also recommended that the +keys are injected before libnvdimm is loaded by modprobe. + +5. Update +--------- +When doing an update, it is expected that the existing key is removed from +the kernel user keyring and reinjected as different (old) key. It's irrelevant +what the key description is for the old key since we are only interested in the +keyid when doing the update operation. It is also expected that the new key +is injected with the description format described from earlier in this +document. The update command written to the sysfs attribute will be with +the format: +update <old keyid> <new keyid> + +If there is no old keyid due to a security enabling, then a 0 should be +passed in. + +6. Freeze +--------- +The freeze operation does not require any keys. The security config can be +frozen by a user with root privelege. + +7. Disable +---------- +The security disable command format is: +disable <keyid> + +An key with the current passphrase payload that is tied to the nvdimm should be +in the kernel user keyring. + +8. Secure Erase +--------------- +The command format for doing a secure erase is: +erase <keyid> + +An key with the current passphrase payload that is tied to the nvdimm should be +in the kernel user keyring. + +9. Overwrite +------------ +The command format for doing an overwrite is: +overwrite <keyid> + +Overwrite can be done without a key if security is not enabled. A key serial +of 0 can be passed in to indicate no key. + +The sysfs attribute "security" can be polled to wait on overwrite completion. +Overwrite can last tens of minutes or more depending on nvdimm size. + +An encrypted-key with the current user passphrase that is tied to the nvdimm +should be injected and its keyid should be passed in via sysfs. + +10. Master Update +----------------- +The command format for doing a master update is: +update <old keyid> <new keyid> + +The operating mechanism for master update is identical to update except the +master passphrase key is passed to the kernel. The master passphrase key +is just another encrypted-key. + +This command is only available when security is disabled. + +11. Master Erase +---------------- +The command format for doing a master erase is: +master_erase <current keyid> + +This command has the same operating mechanism as erase except the master +passphrase key is passed to the kernel. The master passphrase key is just +another encrypted-key. + +This command is only available when the master security is enabled, indicated +by the extended security status. + +[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf +[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.txt index 8d8d8f58f96f..fc2fe4b18655 100644 --- a/Documentation/nvmem/nvmem.txt +++ b/Documentation/nvmem/nvmem.txt @@ -58,6 +58,37 @@ static int qfprom_probe(struct platform_device *pdev) It is mandatory that the NVMEM provider has a regmap associated with its struct device. Failure to do would return error code from nvmem_register(). +Users of board files can define and register nvmem cells using the +nvmem_cell_table struct: + +static struct nvmem_cell_info foo_nvmem_cells[] = { + { + .name = "macaddr", + .offset = 0x7f00, + .bytes = ETH_ALEN, + } +}; + +static struct nvmem_cell_table foo_nvmem_cell_table = { + .nvmem_name = "i2c-eeprom", + .cells = foo_nvmem_cells, + .ncells = ARRAY_SIZE(foo_nvmem_cells), +}; + +nvmem_add_cell_table(&foo_nvmem_cell_table); + +Additionally it is possible to create nvmem cell lookup entries and register +them with the nvmem framework from machine code as shown in the example below: + +static struct nvmem_cell_lookup foo_nvmem_lookup = { + .nvmem_name = "i2c-eeprom", + .cell_name = "macaddr", + .dev_id = "foo_mac.0", + .con_id = "mac-address", +}; + +nvmem_add_cell_lookups(&foo_nvmem_lookup, 1); + NVMEM Consumers +++++++++++++++ diff --git a/Documentation/perf/thunderx2-pmu.txt b/Documentation/perf/thunderx2-pmu.txt new file mode 100644 index 000000000000..dffc57143736 --- /dev/null +++ b/Documentation/perf/thunderx2-pmu.txt @@ -0,0 +1,41 @@ +Cavium ThunderX2 SoC Performance Monitoring Unit (PMU UNCORE) +============================================================= + +The ThunderX2 SoC PMU consists of independent, system-wide, per-socket +PMUs such as the Level 3 Cache (L3C) and DDR4 Memory Controller (DMC). + +The DMC has 8 interleaved channels and the L3C has 16 interleaved tiles. +Events are counted for the default channel (i.e. channel 0) and prorated +to the total number of channels/tiles. + +The DMC and L3C support up to 4 counters. Counters are independently +programmable and can be started and stopped individually. Each counter +can be set to a different event. Counters are 32-bit and do not support +an overflow interrupt; they are read every 2 seconds. + +PMU UNCORE (perf) driver: + +The thunderx2_pmu driver registers per-socket perf PMUs for the DMC and +L3C devices. Each PMU can be used to count up to 4 events +simultaneously. The PMUs provide a description of their available events +and configuration options under sysfs, see +/sys/devices/uncore_<l3c_S/dmc_S/>; S is the socket id. + +The driver does not support sampling, therefore "perf record" will not +work. Per-task perf sessions are also not supported. + +Examples: + +# perf stat -a -e uncore_dmc_0/cnt_cycles/ sleep 1 + +# perf stat -a -e \ +uncore_dmc_0/cnt_cycles/,\ +uncore_dmc_0/data_transfers/,\ +uncore_dmc_0/read_txns/,\ +uncore_dmc_0/write_txns/ sleep 1 + +# perf stat -a -e \ +uncore_l3c_0/read_request/,\ +uncore_l3c_0/read_hit/,\ +uncore_l3c_0/inv_request/,\ +uncore_l3c_0/inv_hit/ sleep 1 diff --git a/Documentation/power/energy-model.txt b/Documentation/power/energy-model.txt new file mode 100644 index 000000000000..a2b0ae4c76bd --- /dev/null +++ b/Documentation/power/energy-model.txt @@ -0,0 +1,144 @@ + ==================== + Energy Model of CPUs + ==================== + +1. Overview +----------- + +The Energy Model (EM) framework serves as an interface between drivers knowing +the power consumed by CPUs at various performance levels, and the kernel +subsystems willing to use that information to make energy-aware decisions. + +The source of the information about the power consumed by CPUs can vary greatly +from one platform to another. These power costs can be estimated using +devicetree data in some cases. In others, the firmware will know better. +Alternatively, userspace might be best positioned. And so on. In order to avoid +each and every client subsystem to re-implement support for each and every +possible source of information on its own, the EM framework intervenes as an +abstraction layer which standardizes the format of power cost tables in the +kernel, hence enabling to avoid redundant work. + +The figure below depicts an example of drivers (Arm-specific here, but the +approach is applicable to any architecture) providing power costs to the EM +framework, and interested clients reading the data from it. + + +---------------+ +-----------------+ +---------------+ + | Thermal (IPA) | | Scheduler (EAS) | | Other | + +---------------+ +-----------------+ +---------------+ + | | em_pd_energy() | + | | em_cpu_get() | + +---------+ | +---------+ + | | | + v v v + +---------------------+ + | Energy Model | + | Framework | + +---------------------+ + ^ ^ ^ + | | | em_register_perf_domain() + +----------+ | +---------+ + | | | + +---------------+ +---------------+ +--------------+ + | cpufreq-dt | | arm_scmi | | Other | + +---------------+ +---------------+ +--------------+ + ^ ^ ^ + | | | + +--------------+ +---------------+ +--------------+ + | Device Tree | | Firmware | | ? | + +--------------+ +---------------+ +--------------+ + +The EM framework manages power cost tables per 'performance domain' in the +system. A performance domain is a group of CPUs whose performance is scaled +together. Performance domains generally have a 1-to-1 mapping with CPUFreq +policies. All CPUs in a performance domain are required to have the same +micro-architecture. CPUs in different performance domains can have different +micro-architectures. + + +2. Core APIs +------------ + + 2.1 Config options + +CONFIG_ENERGY_MODEL must be enabled to use the EM framework. + + + 2.2 Registration of performance domains + +Drivers are expected to register performance domains into the EM framework by +calling the following API: + + int em_register_perf_domain(cpumask_t *span, unsigned int nr_states, + struct em_data_callback *cb); + +Drivers must specify the CPUs of the performance domains using the cpumask +argument, and provide a callback function returning <frequency, power> tuples +for each capacity state. The callback function provided by the driver is free +to fetch data from any relevant location (DT, firmware, ...), and by any mean +deemed necessary. See Section 3. for an example of driver implementing this +callback, and kernel/power/energy_model.c for further documentation on this +API. + + + 2.3 Accessing performance domains + +Subsystems interested in the energy model of a CPU can retrieve it using the +em_cpu_get() API. The energy model tables are allocated once upon creation of +the performance domains, and kept in memory untouched. + +The energy consumed by a performance domain can be estimated using the +em_pd_energy() API. The estimation is performed assuming that the schedutil +CPUfreq governor is in use. + +More details about the above APIs can be found in include/linux/energy_model.h. + + +3. Example driver +----------------- + +This section provides a simple example of a CPUFreq driver registering a +performance domain in the Energy Model framework using the (fake) 'foo' +protocol. The driver implements an est_power() function to be provided to the +EM framework. + + -> drivers/cpufreq/foo_cpufreq.c + +01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu) +02 { +03 long freq, power; +04 +05 /* Use the 'foo' protocol to ceil the frequency */ +06 freq = foo_get_freq_ceil(cpu, *KHz); +07 if (freq < 0); +08 return freq; +09 +10 /* Estimate the power cost for the CPU at the relevant freq. */ +11 power = foo_estimate_power(cpu, freq); +12 if (power < 0); +13 return power; +14 +15 /* Return the values to the EM framework */ +16 *mW = power; +17 *KHz = freq; +18 +19 return 0; +20 } +21 +22 static int foo_cpufreq_init(struct cpufreq_policy *policy) +23 { +24 struct em_data_callback em_cb = EM_DATA_CB(est_power); +25 int nr_opp, ret; +26 +27 /* Do the actual CPUFreq init work ... */ +28 ret = do_foo_cpufreq_init(policy); +29 if (ret) +30 return ret; +31 +32 /* Find the number of OPPs for this policy */ +33 nr_opp = foo_get_nr_opp(policy); +34 +35 /* And register the new performance domain */ +36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb); +37 +38 return 0; +39 } diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.txt index 40ca2d6e2742..721b4739ec32 100644 --- a/Documentation/power/regulator/overview.txt +++ b/Documentation/power/regulator/overview.txt @@ -22,7 +22,7 @@ Nomenclature Some terms used in this document:- o Regulator - Electronic device that supplies power to other devices. - Most regulators can enable and disable their output whilst + Most regulators can enable and disable their output while some can control their output voltage and or current. Input Voltage -> Regulator -> Output Voltage diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.txt index bdd344aa18d9..18c5feef2577 100644 --- a/Documentation/powerpc/firmware-assisted-dump.txt +++ b/Documentation/powerpc/firmware-assisted-dump.txt @@ -113,7 +113,15 @@ header, is usually reserved at an offset greater than boot memory size (see Fig. 1). This area is *not* released: this region will be kept permanently reserved, so that it can act as a receptacle for a copy of the boot memory content in addition to CPU state -and HPTE region, in the case a crash does occur. +and HPTE region, in the case a crash does occur. Since this reserved +memory area is used only after the system crash, there is no point in +blocking this significant chunk of memory from production kernel. +Hence, the implementation uses the Linux kernel's Contiguous Memory +Allocator (CMA) for memory reservation if CMA is configured for kernel. +With CMA reservation this memory will be available for applications to +use it, while kernel is prevented from using it. With this fadump will +still be able to capture all of the kernel memory and most of the user +space memory except the user pages that were present in CMA region. o Memory Reservation during first kernel @@ -162,6 +170,9 @@ How to enable firmware-assisted dump (fadump): 1. Set config option CONFIG_FA_DUMP=y and build kernel. 2. Boot into linux kernel with 'fadump=on' kernel cmdline option. + By default, fadump reserved memory will be initialized as CMA area. + Alternatively, user can boot linux kernel with 'fadump=nocma' to + prevent fadump to use CMA. 3. Optionally, user can also set 'crashkernel=' kernel cmdline to specify size of the memory to reserve for boot memory dump preservation. @@ -172,6 +183,10 @@ NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead 2. If firmware-assisted dump fails to reserve memory then it will fallback to existing kdump mechanism if 'crashkernel=' option is set at kernel cmdline. + 3. if user wants to capture all of user space memory and ok with + reserved memory not available to production system, then + 'fadump=nocma' kernel parameter can be used to fallback to + old behaviour. Sysfs/debugfs files: ------------ diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst new file mode 100644 index 000000000000..812e20cc898c --- /dev/null +++ b/Documentation/powerpc/isa-versions.rst @@ -0,0 +1,74 @@ +CPU to ISA Version Mapping +========================== + +Mapping of some CPU versions to relevant ISA versions. + +========= ==================== +CPU Architecture version +========= ==================== +Power9 Power ISA v3.0B +Power8 Power ISA v2.07 +Power7 Power ISA v2.06 +Power6 Power ISA v2.05 +PA6T Power ISA v2.04 +Cell PPU - Power ISA v2.02 with some minor exceptions + - Plus Altivec/VMX ~= 2.03 +Power5++ Power ISA v2.04 (no VMX) +Power5+ Power ISA v2.03 +Power5 - PowerPC User Instruction Set Architecture Book I v2.02 + - PowerPC Virtual Environment Architecture Book II v2.02 + - PowerPC Operating Environment Architecture Book III v2.02 +PPC970 - PowerPC User Instruction Set Architecture Book I v2.01 + - PowerPC Virtual Environment Architecture Book II v2.01 + - PowerPC Operating Environment Architecture Book III v2.01 + - Plus Altivec/VMX ~= 2.03 +========= ==================== + + +Key Features +------------ + +========== ================== +CPU VMX (aka. Altivec) +========== ================== +Power9 Yes +Power8 Yes +Power7 Yes +Power6 Yes +PA6T Yes +Cell PPU Yes +Power5++ No +Power5+ No +Power5 No +PPC970 Yes +========== ================== + +========== ==== +CPU VSX +========== ==== +Power9 Yes +Power8 Yes +Power7 Yes +Power6 No +PA6T No +Cell PPU No +Power5++ No +Power5+ No +Power5 No +PPC970 No +========== ==== + +========== ==================== +CPU Transactional Memory +========== ==================== +Power9 Yes (* see transactional_memory.txt) +Power8 Yes +Power7 No +Power6 No +PA6T No +Cell PPU No +Power5++ No +Power5+ No +Power5 No +PPC970 No +========== ==================== diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst index e782ae2eef58..c3d0270bbfb3 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -1,3 +1,5 @@ +.. _development_process_intro: + Introduction ============ diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index eb4b185d168c..4b7a5ab3cec1 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -249,7 +249,7 @@ features; most of these are found in the "kernel hacking" submenu. Several of these options should be turned on for any kernel used for development or testing purposes. In particular, you should turn on: - - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an + - ENABLE_MUST_CHECK and FRAME_WARN to get an extra set of warnings for problems like the use of deprecated interfaces or ignoring an important return value from a function. The output generated by these warnings can be verbose, but one need not worry about @@ -315,7 +315,8 @@ variety of potential coding problems; it can also propose fixes for those problems. Quite a few "semantic patches" for the kernel have been packaged under the scripts/coccinelle directory; running "make coccicheck" will run through those semantic patches and report on any problems found. See -Documentation/dev-tools/coccinelle.rst for more information. +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>` +for more information. Other kinds of portability errors are best found by compiling your code for other architectures. If you do not happen to have an S/390 system or a diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index c418c5d6cae4..4213e580f273 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -9,9 +9,10 @@ kernel. Unsurprisingly, the kernel development community has evolved a set of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files process/submitting-patches.rst, -process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel -documentation directory. +more information can also be found in the files +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`, +:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` +and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`. When to post @@ -198,8 +199,10 @@ pass it to diff with the "-X" option. The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in -detail in the process/submitting-patches.rst document; what follows here is a -brief summary. Each of these lines has the format: +detail in +the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document; what follows here is a brief summary. Each of these lines has +the format: :: @@ -210,8 +213,8 @@ The tags in common use are: - Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/process/submitting-patches.rst. Code - without a proper signoff cannot be merged into the mainline. + which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + Code without a proper signoff cannot be merged into the mainline. - Co-developed-by: states that the patch was also created by another developer along with the original author. This is useful at times when multiple @@ -226,7 +229,7 @@ The tags in common use are: it to work. - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/process/submitting-patches.rst + see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` for more detail. - Reported-by: names a user who reported a problem which is fixed by this @@ -253,8 +256,8 @@ take care of: be examined in any detail. If there is any doubt at all, mail the patch to yourself and convince yourself that it shows up intact. - Documentation/process/email-clients.rst has some helpful hints on making - specific mail clients work for sending patches. + :ref:`Documentation/process/email-clients.rst <email_clients>` has some + helpful hints on making specific mail clients work for sending patches. - Are you sure your patch is free of silly mistakes? You should always run patches through scripts/checkpatch.pl and address the complaints it diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index 1c7f54cd0261..8395aa2c1f3a 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -5,9 +5,10 @@ For more information There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level process/howto.rst -file is an important starting point; process/submitting-patches.rst and -process/submitting-drivers.rst are also something which all kernel developers should +directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>` +file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>` +and :ref:`process/submitting-drivers.rst <submittingdrivers>` +are also something which all kernel developers should read. Many internal kernel APIs are documented using the kerneldoc mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those documents in HTML or PDF format (though the version of TeX shipped by some diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index 88a7d5c8bb2f..1c3a840d06b9 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -1,3 +1,6 @@ + +.. _addsyscalls: + Adding a New System Call ======================== diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index dc2ddc345044..fbb9297e6360 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -216,14 +216,14 @@ You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. -This will let you move from something like 4.7.2 to 4.7.3 in a single +This will let you move from something like 5.7.2 to 5.7.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: +Here's how you'd go from 5.7.2 to 5.7.3 in a single step:: - interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 + interdiff -z ../patch-5.7.2.gz ../patch-5.7.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. @@ -245,62 +245,67 @@ The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. -The 4.x.y (-stable) and 4.x patches live at +The 5.x.y (-stable) and 5.x patches live at - https://www.kernel.org/pub/linux/kernel/v4.x/ + https://www.kernel.org/pub/linux/kernel/v5.x/ -The -rc patches live at +The -rc patches are not stored on the webserver but are generated on +demand from git tags such as - https://www.kernel.org/pub/linux/kernel/v4.x/testing/ + https://git.kernel.org/torvalds/p/v5.1-rc1/v5.0 +The stable -rc patches live at -The 4.x kernels + https://www.kernel.org/pub/linux/kernel/v5.x/stable-review/ + + +The 5.x kernels =============== These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 4.x base +will be released (see below) on top of this base. Once a new 5.x base kernel is released, a patch is made available that is a delta between the -previous 4.x kernel and the new one. +previous 5.x kernel and the new one. -To apply a patch moving from 4.6 to 4.7, you'd do the following (note -that such patches do **NOT** apply on top of 4.x.y kernels but on top of the -base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to -first revert the 4.x.y patch). +To apply a patch moving from 5.6 to 5.7, you'd do the following (note +that such patches do **NOT** apply on top of 5.x.y kernels but on top of the +base 5.x kernel -- if you need to move from 5.x.y to 5.x+1 you need to +first revert the 5.x.y patch). Here are some examples:: - # moving from 4.6 to 4.7 + # moving from 5.6 to 5.7 - $ cd ~/linux-4.6 # change to kernel source dir - $ patch -p1 < ../patch-4.7 # apply the 4.7 patch + $ cd ~/linux-5.6 # change to kernel source dir + $ patch -p1 < ../patch-5.7 # apply the 5.7 patch $ cd .. - $ mv linux-4.6 linux-4.7 # rename source dir + $ mv linux-5.6 linux-5.7 # rename source dir - # moving from 4.6.1 to 4.7 + # moving from 5.6.1 to 5.7 - $ cd ~/linux-4.6.1 # change to kernel source dir - $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch - # source dir is now 4.6 - $ patch -p1 < ../patch-4.7 # apply new 4.7 patch + $ cd ~/linux-5.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-5.6.1 # revert the 5.6.1 patch + # source dir is now 5.6 + $ patch -p1 < ../patch-5.7 # apply new 5.7 patch $ cd .. - $ mv linux-4.6.1 linux-4.7 # rename source dir + $ mv linux-5.6.1 linux-5.7 # rename source dir -The 4.x.y kernels +The 5.x.y kernels ================= Kernels with 3-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered -in a given 4.x kernel. +in a given 5.x kernel. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 4.x.y kernel is available, then the highest numbered 4.x kernel is +If no 5.x.y kernel is available, then the highest numbered 5.x kernel is the current stable kernel. .. note:: @@ -308,23 +313,23 @@ the current stable kernel. The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - https://www.kernel.org/pub/linux/kernel/v4.x/incr/ + https://www.kernel.org/pub/linux/kernel/v5.x/incr/ -These patches are not incremental, meaning that for example the 4.7.3 -patch does not apply on top of the 4.7.2 kernel source, but rather on top -of the base 4.7 kernel source. +These patches are not incremental, meaning that for example the 5.7.3 +patch does not apply on top of the 5.7.2 kernel source, but rather on top +of the base 5.7 kernel source. -So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel -source you have to first back out the 4.7.2 patch (so you are left with a -base 4.7 kernel source) and then apply the new 4.7.3 patch. +So, in order to apply the 5.7.3 patch to your existing 5.7.2 kernel +source you have to first back out the 5.7.2 patch (so you are left with a +base 5.7 kernel source) and then apply the new 5.7.3 patch. Here's a small example:: - $ cd ~/linux-4.7.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch - $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch + $ cd ~/linux-5.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-5.7.2 # revert the 5.7.2 patch + $ patch -p1 < ../patch-5.7.3 # apply the new 5.7.3 patch $ cd .. - $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir + $ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir The -rc kernels =============== @@ -343,38 +348,38 @@ This is a good branch to run for people who want to help out testing development kernels but do not want to run some of the really experimental stuff (such people should see the sections about -next and -mm kernels below). -The -rc patches are not incremental, they apply to a base 4.x kernel, just -like the 4.x.y patches described above. The kernel version before the -rcN +The -rc patches are not incremental, they apply to a base 5.x kernel, just +like the 5.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. -So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 -kernel and the patch should be applied on top of the 4.7 kernel source. +So, 5.8-rc5 means that this is the fifth release candidate for the 5.8 +kernel and the patch should be applied on top of the 5.7 kernel source. Here are 3 examples of how to apply these patches:: - # first an example of moving from 4.7 to 4.8-rc3 + # first an example of moving from 5.7 to 5.8-rc3 - $ cd ~/linux-4.7 # change to the 4.7 source dir - $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch + $ cd ~/linux-5.7 # change to the 5.7 source dir + $ patch -p1 < ../patch-5.8-rc3 # apply the 5.8-rc3 patch $ cd .. - $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + $ mv linux-5.7 linux-5.8-rc3 # rename the source dir - # now let's move from 4.8-rc3 to 4.8-rc5 + # now let's move from 5.8-rc3 to 5.8-rc5 - $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir - $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch + $ cd ~/linux-5.8-rc3 # change to the 5.8-rc3 dir + $ patch -p1 -R < ../patch-5.8-rc3 # revert the 5.8-rc3 patch + $ patch -p1 < ../patch-5.8-rc5 # apply the new 5.8-rc5 patch $ cd .. - $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + $ mv linux-5.8-rc3 linux-5.8-rc5 # rename the source dir - # finally let's try and move from 4.7.3 to 4.8-rc5 + # finally let's try and move from 5.7.3 to 5.8-rc5 - $ cd ~/linux-4.7.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd ~/linux-5.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-5.7.3 # revert the 5.7.3 patch + $ patch -p1 < ../patch-5.8-rc5 # apply new 5.8-rc5 patch $ cd .. - $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir + $ mv linux-5.7.3 linux-5.8-rc5 # rename the kernel source dir The -mm patches and the linux-next tree diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index d1bf143b446f..18735dc460a0 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -326,7 +326,7 @@ Kernel documentation Sphinx ------ -Please see :ref:`sphinx_install` in ``Documentation/doc-guide/sphinx.rst`` +Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>` for details about Sphinx requirements. Getting updated software diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 4e7c0a1c427a..b78dd680c038 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -443,6 +443,9 @@ In function prototypes, include parameter names with their data types. Although this is not required by the C language, it is preferred in Linux because it is a simple way to add valuable information for the reader. +Do not use the `extern' keyword with function prototypes as this makes +lines longer and isn't strictly necessary. + 7) Centralized exiting of functions ----------------------------------- @@ -1075,5 +1078,5 @@ gcc internals and indent, all available from http://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: +Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index dcb25f94188e..58b2f46c4f98 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -1,3 +1,5 @@ +.. _process_howto: + HOWTO do Linux kernel development ================================= @@ -296,9 +298,9 @@ two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost instantly. -The file Documentation/process/stable-kernel-rules.rst in the kernel tree -documents what kinds of changes are acceptable for the -stable tree, and -how the release process works. +The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +in the kernel tree documents what kinds of changes are acceptable for +the -stable tree, and how the release process works. 4.x -git patches ~~~~~~~~~~~~~~~~ @@ -358,7 +360,8 @@ tool. For details on how to use the kernel bugzilla, please see: https://bugzilla.kernel.org/page.cgi?id=faq.html -The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good +The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>` +in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind of information is needed by the kernel developers to help track down the problem. @@ -424,7 +427,7 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/process/submitting-patches.rst. +as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 757808526d9a..878ebfda7eef 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -25,6 +25,7 @@ Below are the essential guides that every developer should read. code-of-conduct-interpretation development-process submitting-patches + programming-language coding-style maintainer-pgp-guide email-clients diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst index e78452c2164c..a849790a68bc 100644 --- a/Documentation/process/kernel-driver-statement.rst +++ b/Documentation/process/kernel-driver-statement.rst @@ -1,3 +1,5 @@ +.. _process_statement_driver: + Kernel Driver Statement ----------------------- diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst index 6816c12d6956..e5a1be476047 100644 --- a/Documentation/process/kernel-enforcement-statement.rst +++ b/Documentation/process/kernel-enforcement-statement.rst @@ -1,4 +1,6 @@ -Linux Kernel Enforcement Statement +.. _process_statement_kernel: + +Linux Kernel Enforcement Statement ---------------------------------- As developers of the Linux kernel, we have a keen interest in how our software diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst index 633be1043690..547bbf28e615 100644 --- a/Documentation/process/magic-number.rst +++ b/Documentation/process/magic-number.rst @@ -1,3 +1,5 @@ +.. _magicnumbers: + Linux magic numbers =================== diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst index 85ef8ca8f639..186753ff3d2d 100644 --- a/Documentation/process/management-style.rst +++ b/Documentation/process/management-style.rst @@ -5,8 +5,9 @@ Linux kernel management style This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to -mirror the process/coding-style.rst document to some degree, and mainly written to -avoid answering [#f1]_ the same (or similar) questions over and over again. +mirror the :ref:`process/coding-style.rst <codingstyle>` document to some +degree, and mainly written to avoid answering [#f1]_ the same (or similar) +questions over and over again. Management style is very personal and much harder to quantify than simple coding style rules, so this document may or may not have anything diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst new file mode 100644 index 000000000000..e5f5f065dc24 --- /dev/null +++ b/Documentation/process/programming-language.rst @@ -0,0 +1,45 @@ +.. _programming_language: + +Programming Language +==================== + +The kernel is written in the C programming language [c-language]_. +More precisely, the kernel is typically compiled with ``gcc`` [gcc]_ +under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90 +(including some C99 features). + +This dialect contains many extensions to the language [gnu-extensions]_, +and many of them are used within the kernel as a matter of course. + +There is some support for compiling the kernel with ``clang`` [clang]_ +and ``icc`` [icc]_ for several of the architectures, although at the time +of writing it is not completed, requiring third-party patches. + +Attributes +---------- + +One of the common extensions used throughout the kernel are attributes +[gcc-attribute-syntax]_. Attributes allow to introduce +implementation-defined semantics to language entities (like variables, +functions or types) without having to make significant syntactic changes +to the language (e.g. adding a new keyword) [n2049]_. + +In some cases, attributes are optional (i.e. a compiler not supporting them +should still produce proper code, even if it is slower or does not perform +as many compile-time checks/diagnostics). + +The kernel defines pseudo-keywords (e.g. ``__pure``) instead of using +directly the GNU attribute syntax (e.g. ``__attribute__((__pure__))``) +in order to feature detect which ones can be used and/or to shorten the code. + +Please refer to ``include/linux/compiler_attributes.h`` for more information. + +.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards +.. [gcc] https://gcc.gnu.org +.. [clang] https://clang.llvm.org +.. [icc] https://software.intel.com/en-us/c-compilers +.. [gcc-c-dialect-options] https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html +.. [gnu-extensions] https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html +.. [gcc-attribute-syntax] https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html +.. [n2049] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2049.pdf + diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index b38bf2054ce3..58bc047e7b95 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -16,7 +16,8 @@ you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org Oh, and we don't really recommend submitting changes to XFree86 :) -Also read the Documentation/process/submitting-patches.rst document. +Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` +document. Allocating Device Numbers @@ -27,7 +28,8 @@ by the Linux assigned name and number authority (currently this is Torben Mathiasen). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. -See Documentation/admin-guide/devices.rst for more information on this. +See :ref:`Documentation/admin-guide/devices.rst <admin_devices>` +for more information on this. If you don't use assigned numbers then when your device is submitted it will be given an assigned number even if that is different from values you may @@ -117,7 +119,7 @@ PM support: anything. For the driver testing instructions see Documentation/power/drivers-testing.txt and for a relatively complete overview of the power management issues related to - drivers see Documentation/driver-api/pm/devices.rst. + drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`. Control: In general if there is active maintenance of a driver by diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index c0917107b90a..30dc00a364e8 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -510,7 +510,7 @@ tracking your trees, and to people trying to troubleshoot bugs in your tree. -12) When to use Acked-by:, Cc:, and Co-Developed-by: +12) When to use Acked-by:, Cc:, and Co-developed-by: ------------------------------------------------------- The Signed-off-by: tag indicates that the signer was involved in the @@ -543,7 +543,7 @@ person it names - but it should indicate that this person was copied on the patch. This tag documents that potentially interested parties have been included in the discussion. -A Co-Developed-by: states that the patch was also created by another developer +A Co-developed-by: states that the patch was also created by another developer along with the original author. This is useful at times when multiple people work on a single patch. Note, this person also needs to have a Signed-off-by: line in the patch as well. diff --git a/Documentation/s390/3270.ChangeLog b/Documentation/s390/3270.ChangeLog index 031c36081946..ecaf60b6c381 100644 --- a/Documentation/s390/3270.ChangeLog +++ b/Documentation/s390/3270.ChangeLog @@ -16,7 +16,7 @@ Sep 2002: Dynamically get 3270 input buffer Sep 2002: Fix tubfs kmalloc()s * Do read and write lengths correctly in fs3270_read() - and fs3270_write(), whilst never asking kmalloc() + and fs3270_write(), while never asking kmalloc() for more than 0x800 bytes. Affects tubfs.c and tubio.h. Sep 2002: Recognize 3270 control unit type 3174 diff --git a/Documentation/s390/vfio-ap.txt b/Documentation/s390/vfio-ap.txt new file mode 100644 index 000000000000..65167cfe4485 --- /dev/null +++ b/Documentation/s390/vfio-ap.txt @@ -0,0 +1,837 @@ +Introduction: +============ +The Adjunct Processor (AP) facility is an IBM Z cryptographic facility comprised +of three AP instructions and from 1 up to 256 PCIe cryptographic adapter cards. +The AP devices provide cryptographic functions to all CPUs assigned to a +linux system running in an IBM Z system LPAR. + +The AP adapter cards are exposed via the AP bus. The motivation for vfio-ap +is to make AP cards available to KVM guests using the VFIO mediated device +framework. This implementation relies considerably on the s390 virtualization +facilities which do most of the hard work of providing direct access to AP +devices. + +AP Architectural Overview: +========================= +To facilitate the comprehension of the design, let's start with some +definitions: + +* AP adapter + + An AP adapter is an IBM Z adapter card that can perform cryptographic + functions. There can be from 0 to 256 adapters assigned to an LPAR. Adapters + assigned to the LPAR in which a linux host is running will be available to + the linux host. Each adapter is identified by a number from 0 to 255; however, + the maximum adapter number is determined by machine model and/or adapter type. + When installed, an AP adapter is accessed by AP instructions executed by any + CPU. + + The AP adapter cards are assigned to a given LPAR via the system's Activation + Profile which can be edited via the HMC. When the linux host system is IPL'd + in the LPAR, the AP bus detects the AP adapter cards assigned to the LPAR and + creates a sysfs device for each assigned adapter. For example, if AP adapters + 4 and 10 (0x0a) are assigned to the LPAR, the AP bus will create the following + sysfs device entries: + + /sys/devices/ap/card04 + /sys/devices/ap/card0a + + Symbolic links to these devices will also be created in the AP bus devices + sub-directory: + + /sys/bus/ap/devices/[card04] + /sys/bus/ap/devices/[card04] + +* AP domain + + An adapter is partitioned into domains. An adapter can hold up to 256 domains + depending upon the adapter type and hardware configuration. A domain is + identified by a number from 0 to 255; however, the maximum domain number is + determined by machine model and/or adapter type.. A domain can be thought of + as a set of hardware registers and memory used for processing AP commands. A + domain can be configured with a secure private key used for clear key + encryption. A domain is classified in one of two ways depending upon how it + may be accessed: + + * Usage domains are domains that are targeted by an AP instruction to + process an AP command. + + * Control domains are domains that are changed by an AP command sent to a + usage domain; for example, to set the secure private key for the control + domain. + + The AP usage and control domains are assigned to a given LPAR via the system's + Activation Profile which can be edited via the HMC. When a linux host system + is IPL'd in the LPAR, the AP bus module detects the AP usage and control + domains assigned to the LPAR. The domain number of each usage domain and + adapter number of each AP adapter are combined to create AP queue devices + (see AP Queue section below). The domain number of each control domain will be + represented in a bitmask and stored in a sysfs file + /sys/bus/ap/ap_control_domain_mask. The bits in the mask, from most to least + significant bit, correspond to domains 0-255. + +* AP Queue + + An AP queue is the means by which an AP command is sent to a usage domain + inside a specific adapter. An AP queue is identified by a tuple + comprised of an AP adapter ID (APID) and an AP queue index (APQI). The + APQI corresponds to a given usage domain number within the adapter. This tuple + forms an AP Queue Number (APQN) uniquely identifying an AP queue. AP + instructions include a field containing the APQN to identify the AP queue to + which the AP command is to be sent for processing. + + The AP bus will create a sysfs device for each APQN that can be derived from + the cross product of the AP adapter and usage domain numbers detected when the + AP bus module is loaded. For example, if adapters 4 and 10 (0x0a) and usage + domains 6 and 71 (0x47) are assigned to the LPAR, the AP bus will create the + following sysfs entries: + + /sys/devices/ap/card04/04.0006 + /sys/devices/ap/card04/04.0047 + /sys/devices/ap/card0a/0a.0006 + /sys/devices/ap/card0a/0a.0047 + + The following symbolic links to these devices will be created in the AP bus + devices subdirectory: + + /sys/bus/ap/devices/[04.0006] + /sys/bus/ap/devices/[04.0047] + /sys/bus/ap/devices/[0a.0006] + /sys/bus/ap/devices/[0a.0047] + +* AP Instructions: + + There are three AP instructions: + + * NQAP: to enqueue an AP command-request message to a queue + * DQAP: to dequeue an AP command-reply message from a queue + * PQAP: to administer the queues + + AP instructions identify the domain that is targeted to process the AP + command; this must be one of the usage domains. An AP command may modify a + domain that is not one of the usage domains, but the modified domain + must be one of the control domains. + +AP and SIE: +========== +Let's now take a look at how AP instructions executed on a guest are interpreted +by the hardware. + +A satellite control block called the Crypto Control Block (CRYCB) is attached to +our main hardware virtualization control block. The CRYCB contains three fields +to identify the adapters, usage domains and control domains assigned to the KVM +guest: + +* The AP Mask (APM) field is a bit mask that identifies the AP adapters assigned + to the KVM guest. Each bit in the mask, from left to right (i.e. from most + significant to least significant bit in big endian order), corresponds to + an APID from 0-255. If a bit is set, the corresponding adapter is valid for + use by the KVM guest. + +* The AP Queue Mask (AQM) field is a bit mask identifying the AP usage domains + assigned to the KVM guest. Each bit in the mask, from left to right (i.e. from + most significant to least significant bit in big endian order), corresponds to + an AP queue index (APQI) from 0-255. If a bit is set, the corresponding queue + is valid for use by the KVM guest. + +* The AP Domain Mask field is a bit mask that identifies the AP control domains + assigned to the KVM guest. The ADM bit mask controls which domains can be + changed by an AP command-request message sent to a usage domain from the + guest. Each bit in the mask, from left to right (i.e. from most significant to + least significant bit in big endian order), corresponds to a domain from + 0-255. If a bit is set, the corresponding domain can be modified by an AP + command-request message sent to a usage domain. + +If you recall from the description of an AP Queue, AP instructions include +an APQN to identify the AP queue to which an AP command-request message is to be +sent (NQAP and PQAP instructions), or from which a command-reply message is to +be received (DQAP instruction). The validity of an APQN is defined by the matrix +calculated from the APM and AQM; it is the cross product of all assigned adapter +numbers (APM) with all assigned queue indexes (AQM). For example, if adapters 1 +and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs (1,5), (1,6), +(2,5) and (2,6) will be valid for the guest. + +The APQNs can provide secure key functionality - i.e., a private key is stored +on the adapter card for each of its domains - so each APQN must be assigned to +at most one guest or to the linux host. + + Example 1: Valid configuration: + ------------------------------ + Guest1: adapters 1,2 domains 5,6 + Guest2: adapter 1,2 domain 7 + + This is valid because both guests have a unique set of APQNs: + Guest1 has APQNs (1,5), (1,6), (2,5), (2,6); + Guest2 has APQNs (1,7), (2,7) + + Example 2: Valid configuration: + ------------------------------ + Guest1: adapters 1,2 domains 5,6 + Guest2: adapters 3,4 domains 5,6 + + This is also valid because both guests have a unique set of APQNs: + Guest1 has APQNs (1,5), (1,6), (2,5), (2,6); + Guest2 has APQNs (3,5), (3,6), (4,5), (4,6) + + Example 3: Invalid configuration: + -------------------------------- + Guest1: adapters 1,2 domains 5,6 + Guest2: adapter 1 domains 6,7 + + This is an invalid configuration because both guests have access to + APQN (1,6). + +The Design: +=========== +The design introduces three new objects: + +1. AP matrix device +2. VFIO AP device driver (vfio_ap.ko) +3. VFIO AP mediated matrix pass-through device + +The VFIO AP device driver +------------------------- +The VFIO AP (vfio_ap) device driver serves the following purposes: + +1. Provides the interfaces to secure APQNs for exclusive use of KVM guests. + +2. Sets up the VFIO mediated device interfaces to manage a mediated matrix + device and creates the sysfs interfaces for assigning adapters, usage + domains, and control domains comprising the matrix for a KVM guest. + +3. Configures the APM, AQM and ADM in the CRYCB referenced by a KVM guest's + SIE state description to grant the guest access to a matrix of AP devices + +Reserve APQNs for exclusive use of KVM guests +--------------------------------------------- +The following block diagram illustrates the mechanism by which APQNs are +reserved: + + +------------------+ + 7 remove | | + +--------------------> cex4queue driver | + | | | + | +------------------+ + | + | + | +------------------+ +-----------------+ + | 5 register driver | | 3 create | | + | +----------------> Device core +----------> matrix device | + | | | | | | + | | +--------^---------+ +-----------------+ + | | | + | | +-------------------+ + | | +-----------------------------------+ | + | | | 4 register AP driver | | 2 register device + | | | | | ++--------+---+-v---+ +--------+-------+-+ +| | | | +| ap_bus +--------------------- > vfio_ap driver | +| | 8 probe | | ++--------^---------+ +--^--^------------+ +6 edit | | | + apmask | +-----------------------------+ | 9 mdev create + aqmask | | 1 modprobe | ++--------+-----+---+ +----------------+-+ +------------------+ +| | | |8 create | mediated | +| admin | | VFIO device core |---------> matrix | +| + | | | device | ++------+-+---------+ +--------^---------+ +--------^---------+ + | | | | + | | 9 create vfio_ap-passthrough | | + | +------------------------------+ | + +-------------------------------------------------------------+ + 10 assign adapter/domain/control domain + +The process for reserving an AP queue for use by a KVM guest is: + +1. The administrator loads the vfio_ap device driver +2. The vfio-ap driver during its initialization will register a single 'matrix' + device with the device core. This will serve as the parent device for + all mediated matrix devices used to configure an AP matrix for a guest. +3. The /sys/devices/vfio_ap/matrix device is created by the device core +4 The vfio_ap device driver will register with the AP bus for AP queue devices + of type 10 and higher (CEX4 and newer). The driver will provide the vfio_ap + driver's probe and remove callback interfaces. Devices older than CEX4 queues + are not supported to simplify the implementation by not needlessly + complicating the design by supporting older devices that will go out of + service in the relatively near future, and for which there are few older + systems around on which to test. +5. The AP bus registers the vfio_ap device driver with the device core +6. The administrator edits the AP adapter and queue masks to reserve AP queues + for use by the vfio_ap device driver. +7. The AP bus removes the AP queues reserved for the vfio_ap driver from the + default zcrypt cex4queue driver. +8. The AP bus probes the vfio_ap device driver to bind the queues reserved for + it. +9. The administrator creates a passthrough type mediated matrix device to be + used by a guest +10 The administrator assigns the adapters, usage domains and control domains + to be exclusively used by a guest. + +Set up the VFIO mediated device interfaces +------------------------------------------ +The VFIO AP device driver utilizes the common interface of the VFIO mediated +device core driver to: +* Register an AP mediated bus driver to add a mediated matrix device to and + remove it from a VFIO group. +* Create and destroy a mediated matrix device +* Add a mediated matrix device to and remove it from the AP mediated bus driver +* Add a mediated matrix device to and remove it from an IOMMU group + +The following high-level block diagram shows the main components and interfaces +of the VFIO AP mediated matrix device driver: + + +-------------+ + | | + | +---------+ | mdev_register_driver() +--------------+ + | | Mdev | +<-----------------------+ | + | | bus | | | vfio_mdev.ko | + | | driver | +----------------------->+ |<-> VFIO user + | +---------+ | probe()/remove() +--------------+ APIs + | | + | MDEV CORE | + | MODULE | + | mdev.ko | + | +---------+ | mdev_register_device() +--------------+ + | |Physical | +<-----------------------+ | + | | device | | | vfio_ap.ko |<-> matrix + | |interface| +----------------------->+ | device + | +---------+ | callback +--------------+ + +-------------+ + +During initialization of the vfio_ap module, the matrix device is registered +with an 'mdev_parent_ops' structure that provides the sysfs attribute +structures, mdev functions and callback interfaces for managing the mediated +matrix device. + +* sysfs attribute structures: + * supported_type_groups + The VFIO mediated device framework supports creation of user-defined + mediated device types. These mediated device types are specified + via the 'supported_type_groups' structure when a device is registered + with the mediated device framework. The registration process creates the + sysfs structures for each mediated device type specified in the + 'mdev_supported_types' sub-directory of the device being registered. Along + with the device type, the sysfs attributes of the mediated device type are + provided. + + The VFIO AP device driver will register one mediated device type for + passthrough devices: + /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough + Only the read-only attributes required by the VFIO mdev framework will + be provided: + ... name + ... device_api + ... available_instances + ... device_api + Where: + * name: specifies the name of the mediated device type + * device_api: the mediated device type's API + * available_instances: the number of mediated matrix passthrough devices + that can be created + * device_api: specifies the VFIO API + * mdev_attr_groups + This attribute group identifies the user-defined sysfs attributes of the + mediated device. When a device is registered with the VFIO mediated device + framework, the sysfs attribute files identified in the 'mdev_attr_groups' + structure will be created in the mediated matrix device's directory. The + sysfs attributes for a mediated matrix device are: + * assign_adapter: + * unassign_adapter: + Write-only attributes for assigning/unassigning an AP adapter to/from the + mediated matrix device. To assign/unassign an adapter, the APID of the + adapter is echoed to the respective attribute file. + * assign_domain: + * unassign_domain: + Write-only attributes for assigning/unassigning an AP usage domain to/from + the mediated matrix device. To assign/unassign a domain, the domain + number of the the usage domain is echoed to the respective attribute + file. + * matrix: + A read-only file for displaying the APQNs derived from the cross product + of the adapter and domain numbers assigned to the mediated matrix device. + * assign_control_domain: + * unassign_control_domain: + Write-only attributes for assigning/unassigning an AP control domain + to/from the mediated matrix device. To assign/unassign a control domain, + the ID of the domain to be assigned/unassigned is echoed to the respective + attribute file. + * control_domains: + A read-only file for displaying the control domain numbers assigned to the + mediated matrix device. + +* functions: + * create: + allocates the ap_matrix_mdev structure used by the vfio_ap driver to: + * Store the reference to the KVM structure for the guest using the mdev + * Store the AP matrix configuration for the adapters, domains, and control + domains assigned via the corresponding sysfs attributes files + * remove: + deallocates the mediated matrix device's ap_matrix_mdev structure. This will + be allowed only if a running guest is not using the mdev. + +* callback interfaces + * open: + The vfio_ap driver uses this callback to register a + VFIO_GROUP_NOTIFY_SET_KVM notifier callback function for the mdev matrix + device. The open is invoked when QEMU connects the VFIO iommu group + for the mdev matrix device to the MDEV bus. Access to the KVM structure used + to configure the KVM guest is provided via this callback. The KVM structure, + is used to configure the guest's access to the AP matrix defined via the + mediated matrix device's sysfs attribute files. + * release: + unregisters the VFIO_GROUP_NOTIFY_SET_KVM notifier callback function for the + mdev matrix device and deconfigures the guest's AP matrix. + +Configure the APM, AQM and ADM in the CRYCB: +------------------------------------------- +Configuring the AP matrix for a KVM guest will be performed when the +VFIO_GROUP_NOTIFY_SET_KVM notifier callback is invoked. The notifier +function is called when QEMU connects to KVM. The guest's AP matrix is +configured via it's CRYCB by: +* Setting the bits in the APM corresponding to the APIDs assigned to the + mediated matrix device via its 'assign_adapter' interface. +* Setting the bits in the AQM corresponding to the domains assigned to the + mediated matrix device via its 'assign_domain' interface. +* Setting the bits in the ADM corresponding to the domain dIDs assigned to the + mediated matrix device via its 'assign_control_domains' interface. + +The CPU model features for AP +----------------------------- +The AP stack relies on the presence of the AP instructions as well as two +facilities: The AP Facilities Test (APFT) facility; and the AP Query +Configuration Information (QCI) facility. These features/facilities are made +available to a KVM guest via the following CPU model features: + +1. ap: Indicates whether the AP instructions are installed on the guest. This + feature will be enabled by KVM only if the AP instructions are installed + on the host. + +2. apft: Indicates the APFT facility is available on the guest. This facility + can be made available to the guest only if it is available on the host (i.e., + facility bit 15 is set). + +3. apqci: Indicates the AP QCI facility is available on the guest. This facility + can be made available to the guest only if it is available on the host (i.e., + facility bit 12 is set). + +Note: If the user chooses to specify a CPU model different than the 'host' +model to QEMU, the CPU model features and facilities need to be turned on +explicitly; for example: + + /usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on + +A guest can be precluded from using AP features/facilities by turning them off +explicitly; for example: + + /usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off + +Note: If the APFT facility is turned off (apft=off) for the guest, the guest +will not see any AP devices. The zcrypt device drivers that register for type 10 +and newer AP devices - i.e., the cex4card and cex4queue device drivers - need +the APFT facility to ascertain the facilities installed on a given AP device. If +the APFT facility is not installed on the guest, then the probe of device +drivers will fail since only type 10 and newer devices can be configured for +guest use. + +Example: +======= +Let's now provide an example to illustrate how KVM guests may be given +access to AP facilities. For this example, we will show how to configure +three guests such that executing the lszcrypt command on the guests would +look like this: + +Guest1 +------ +CARD.DOMAIN TYPE MODE +------------------------------ +05 CEX5C CCA-Coproc +05.0004 CEX5C CCA-Coproc +05.00ab CEX5C CCA-Coproc +06 CEX5A Accelerator +06.0004 CEX5A Accelerator +06.00ab CEX5C CCA-Coproc + +Guest2 +------ +CARD.DOMAIN TYPE MODE +------------------------------ +05 CEX5A Accelerator +05.0047 CEX5A Accelerator +05.00ff CEX5A Accelerator + +Guest2 +------ +CARD.DOMAIN TYPE MODE +------------------------------ +06 CEX5A Accelerator +06.0047 CEX5A Accelerator +06.00ff CEX5A Accelerator + +These are the steps: + +1. Install the vfio_ap module on the linux host. The dependency chain for the + vfio_ap module is: + * iommu + * s390 + * zcrypt + * vfio + * vfio_mdev + * vfio_mdev_device + * KVM + + To build the vfio_ap module, the kernel build must be configured with the + following Kconfig elements selected: + * IOMMU_SUPPORT + * S390 + * ZCRYPT + * S390_AP_IOMMU + * VFIO + * VFIO_MDEV + * VFIO_MDEV_DEVICE + * KVM + + If using make menuconfig select the following to build the vfio_ap module: + -> Device Drivers + -> IOMMU Hardware Support + select S390 AP IOMMU Support + -> VFIO Non-Privileged userspace driver framework + -> Mediated device driver frramework + -> VFIO driver for Mediated devices + -> I/O subsystem + -> VFIO support for AP devices + +2. Secure the AP queues to be used by the three guests so that the host can not + access them. To secure them, there are two sysfs files that specify + bitmasks marking a subset of the APQN range as 'usable by the default AP + queue device drivers' or 'not usable by the default device drivers' and thus + available for use by the vfio_ap device driver'. The location of the sysfs + files containing the masks are: + + /sys/bus/ap/apmask + /sys/bus/ap/aqmask + + The 'apmask' is a 256-bit mask that identifies a set of AP adapter IDs + (APID). Each bit in the mask, from left to right (i.e., from most significant + to least significant bit in big endian order), corresponds to an APID from + 0-255. If a bit is set, the APID is marked as usable only by the default AP + queue device drivers; otherwise, the APID is usable by the vfio_ap + device driver. + + The 'aqmask' is a 256-bit mask that identifies a set of AP queue indexes + (APQI). Each bit in the mask, from left to right (i.e., from most significant + to least significant bit in big endian order), corresponds to an APQI from + 0-255. If a bit is set, the APQI is marked as usable only by the default AP + queue device drivers; otherwise, the APQI is usable by the vfio_ap device + driver. + + Take, for example, the following mask: + + 0x7dffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff + + It indicates: + + 1, 2, 3, 4, 5, and 7-255 belong to the default drivers' pool, and 0 and 6 + belong to the vfio_ap device driver's pool. + + The APQN of each AP queue device assigned to the linux host is checked by the + AP bus against the set of APQNs derived from the cross product of APIDs + and APQIs marked as usable only by the default AP queue device drivers. If a + match is detected, only the default AP queue device drivers will be probed; + otherwise, the vfio_ap device driver will be probed. + + By default, the two masks are set to reserve all APQNs for use by the default + AP queue device drivers. There are two ways the default masks can be changed: + + 1. The sysfs mask files can be edited by echoing a string into the + respective sysfs mask file in one of two formats: + + * An absolute hex string starting with 0x - like "0x12345678" - sets + the mask. If the given string is shorter than the mask, it is padded + with 0s on the right; for example, specifying a mask value of 0x41 is + the same as specifying: + + 0x4100000000000000000000000000000000000000000000000000000000000000 + + Keep in mind that the mask reads from left to right (i.e., most + significant to least significant bit in big endian order), so the mask + above identifies device numbers 1 and 7 (01000001). + + If the string is longer than the mask, the operation is terminated with + an error (EINVAL). + + * Individual bits in the mask can be switched on and off by specifying + each bit number to be switched in a comma separated list. Each bit + number string must be prepended with a ('+') or minus ('-') to indicate + the corresponding bit is to be switched on ('+') or off ('-'). Some + valid values are: + + "+0" switches bit 0 on + "-13" switches bit 13 off + "+0x41" switches bit 65 on + "-0xff" switches bit 255 off + + The following example: + +0,-6,+0x47,-0xf0 + + Switches bits 0 and 71 (0x47) on + Switches bits 6 and 240 (0xf0) off + + Note that the bits not specified in the list remain as they were before + the operation. + + 2. The masks can also be changed at boot time via parameters on the kernel + command line like this: + + ap.apmask=0xffff ap.aqmask=0x40 + + This would create the following masks: + + apmask: + 0xffff000000000000000000000000000000000000000000000000000000000000 + + aqmask: + 0x4000000000000000000000000000000000000000000000000000000000000000 + + Resulting in these two pools: + + default drivers pool: adapter 0-15, domain 1 + alternate drivers pool: adapter 16-255, domains 0, 2-255 + + Securing the APQNs for our example: + ---------------------------------- + To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, 06.0047, + 06.00ab, and 06.00ff for use by the vfio_ap device driver, the corresponding + APQNs can either be removed from the default masks: + + echo -5,-6 > /sys/bus/ap/apmask + + echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask + + Or the masks can be set as follows: + + echo 0xf9ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff \ + > apmask + + echo 0xf7fffffffffffffffeffffffffffffffffffffffffeffffffffffffffffffffe \ + > aqmask + + This will result in AP queues 05.0004, 05.0047, 05.00ab, 05.00ff, 06.0004, + 06.0047, 06.00ab, and 06.00ff getting bound to the vfio_ap device driver. The + sysfs directory for the vfio_ap device driver will now contain symbolic links + to the AP queue devices bound to it: + + /sys/bus/ap + ... [drivers] + ...... [vfio_ap] + ......... [05.0004] + ......... [05.0047] + ......... [05.00ab] + ......... [05.00ff] + ......... [06.0004] + ......... [06.0047] + ......... [06.00ab] + ......... [06.00ff] + + Keep in mind that only type 10 and newer adapters (i.e., CEX4 and later) + can be bound to the vfio_ap device driver. The reason for this is to + simplify the implementation by not needlessly complicating the design by + supporting older devices that will go out of service in the relatively near + future and for which there are few older systems on which to test. + + The administrator, therefore, must take care to secure only AP queues that + can be bound to the vfio_ap device driver. The device type for a given AP + queue device can be read from the parent card's sysfs directory. For example, + to see the hardware type of the queue 05.0004: + + cat /sys/bus/ap/devices/card05/hwtype + + The hwtype must be 10 or higher (CEX4 or newer) in order to be bound to the + vfio_ap device driver. + +3. Create the mediated devices needed to configure the AP matrixes for the + three guests and to provide an interface to the vfio_ap driver for + use by the guests: + + /sys/devices/vfio_ap/matrix/ + --- [mdev_supported_types] + ------ [vfio_ap-passthrough] (passthrough mediated matrix device type) + --------- create + --------- [devices] + + To create the mediated devices for the three guests: + + uuidgen > create + uuidgen > create + uuidgen > create + + or + + echo $uuid1 > create + echo $uuid2 > create + echo $uuid3 > create + + This will create three mediated devices in the [devices] subdirectory named + after the UUID written to the create attribute file. We call them $uuid1, + $uuid2 and $uuid3 and this is the sysfs directory structure after creation: + + /sys/devices/vfio_ap/matrix/ + --- [mdev_supported_types] + ------ [vfio_ap-passthrough] + --------- [devices] + ------------ [$uuid1] + --------------- assign_adapter + --------------- assign_control_domain + --------------- assign_domain + --------------- matrix + --------------- unassign_adapter + --------------- unassign_control_domain + --------------- unassign_domain + + ------------ [$uuid2] + --------------- assign_adapter + --------------- assign_control_domain + --------------- assign_domain + --------------- matrix + --------------- unassign_adapter + ----------------unassign_control_domain + ----------------unassign_domain + + ------------ [$uuid3] + --------------- assign_adapter + --------------- assign_control_domain + --------------- assign_domain + --------------- matrix + --------------- unassign_adapter + ----------------unassign_control_domain + ----------------unassign_domain + +4. The administrator now needs to configure the matrixes for the mediated + devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3). + + This is how the matrix is configured for Guest1: + + echo 5 > assign_adapter + echo 6 > assign_adapter + echo 4 > assign_domain + echo 0xab > assign_domain + + Control domains can similarly be assigned using the assign_control_domain + sysfs file. + + If a mistake is made configuring an adapter, domain or control domain, + you can use the unassign_xxx files to unassign the adapter, domain or + control domain. + + To display the matrix configuration for Guest1: + + cat matrix + + This is how the matrix is configured for Guest2: + + echo 5 > assign_adapter + echo 0x47 > assign_domain + echo 0xff > assign_domain + + This is how the matrix is configured for Guest3: + + echo 6 > assign_adapter + echo 0x47 > assign_domain + echo 0xff > assign_domain + + In order to successfully assign an adapter: + + * The adapter number specified must represent a value from 0 up to the + maximum adapter number configured for the system. If an adapter number + higher than the maximum is specified, the operation will terminate with + an error (ENODEV). + + * All APQNs that can be derived from the adapter ID and the IDs of + the previously assigned domains must be bound to the vfio_ap device + driver. If no domains have yet been assigned, then there must be at least + one APQN with the specified APID bound to the vfio_ap driver. If no such + APQNs are bound to the driver, the operation will terminate with an + error (EADDRNOTAVAIL). + + No APQN that can be derived from the adapter ID and the IDs of the + previously assigned domains can be assigned to another mediated matrix + device. If an APQN is assigned to another mediated matrix device, the + operation will terminate with an error (EADDRINUSE). + + In order to successfully assign a domain: + + * The domain number specified must represent a value from 0 up to the + maximum domain number configured for the system. If a domain number + higher than the maximum is specified, the operation will terminate with + an error (ENODEV). + + * All APQNs that can be derived from the domain ID and the IDs of + the previously assigned adapters must be bound to the vfio_ap device + driver. If no domains have yet been assigned, then there must be at least + one APQN with the specified APQI bound to the vfio_ap driver. If no such + APQNs are bound to the driver, the operation will terminate with an + error (EADDRNOTAVAIL). + + No APQN that can be derived from the domain ID and the IDs of the + previously assigned adapters can be assigned to another mediated matrix + device. If an APQN is assigned to another mediated matrix device, the + operation will terminate with an error (EADDRINUSE). + + In order to successfully assign a control domain, the domain number + specified must represent a value from 0 up to the maximum domain number + configured for the system. If a control domain number higher than the maximum + is specified, the operation will terminate with an error (ENODEV). + +5. Start Guest1: + + /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ + -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ... + +7. Start Guest2: + + /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ + -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ... + +7. Start Guest3: + + /usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on \ + -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ... + +When the guest is shut down, the mediated matrix devices may be removed. + +Using our example again, to remove the mediated matrix device $uuid1: + + /sys/devices/vfio_ap/matrix/ + --- [mdev_supported_types] + ------ [vfio_ap-passthrough] + --------- [devices] + ------------ [$uuid1] + --------------- remove + + + echo 1 > remove + + This will remove all of the mdev matrix device's sysfs structures including + the mdev device itself. To recreate and reconfigure the mdev matrix device, + all of the steps starting with step 3 will have to be performed again. Note + that the remove will fail if a guest using the mdev is still running. + + It is not necessary to remove an mdev matrix device, but one may want to + remove it if no guest will use it during the remaining lifetime of the linux + host. If the mdev matrix device is removed, one may want to also reconfigure + the pool of adapters and queues reserved for use by the default drivers. + +Limitations +=========== +* The KVM/kernel interfaces do not provide a way to prevent restoring an APQN + to the default drivers pool of a queue that is still assigned to a mediated + device in use by a guest. It is incumbent upon the administrator to + ensure there is no mediated device in use by a guest to which the APQN is + assigned lest the host be given access to the private data of the AP queue + device such as a private key configured specifically for the guest. + +* Dynamically modifying the AP matrix for a running guest (which would amount to + hot(un)plug of AP devices for the guest) is currently not supported + +* Live guest migration is not supported for guests using AP devices. diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.txt new file mode 100644 index 000000000000..197d81f4b836 --- /dev/null +++ b/Documentation/scheduler/sched-energy.txt @@ -0,0 +1,425 @@ + ======================= + Energy Aware Scheduling + ======================= + +1. Introduction +--------------- + +Energy Aware Scheduling (or EAS) gives the scheduler the ability to predict +the impact of its decisions on the energy consumed by CPUs. EAS relies on an +Energy Model (EM) of the CPUs to select an energy efficient CPU for each task, +with a minimal impact on throughput. This document aims at providing an +introduction on how EAS works, what are the main design decisions behind it, and +details what is needed to get it to run. + +Before going any further, please note that at the time of writing: + + /!\ EAS does not support platforms with symmetric CPU topologies /!\ + +EAS operates only on heterogeneous CPU topologies (such as Arm big.LITTLE) +because this is where the potential for saving energy through scheduling is +the highest. + +The actual EM used by EAS is _not_ maintained by the scheduler, but by a +dedicated framework. For details about this framework and what it provides, +please refer to its documentation (see Documentation/power/energy-model.txt). + + +2. Background and Terminology +----------------------------- + +To make it clear from the start: + - energy = [joule] (resource like a battery on powered devices) + - power = energy/time = [joule/second] = [watt] + +The goal of EAS is to minimize energy, while still getting the job done. That +is, we want to maximize: + + performance [inst/s] + -------------------- + power [W] + +which is equivalent to minimizing: + + energy [J] + ----------- + instruction + +while still getting 'good' performance. It is essentially an alternative +optimization objective to the current performance-only objective for the +scheduler. This alternative considers two objectives: energy-efficiency and +performance. + +The idea behind introducing an EM is to allow the scheduler to evaluate the +implications of its decisions rather than blindly applying energy-saving +techniques that may have positive effects only on some platforms. At the same +time, the EM must be as simple as possible to minimize the scheduler latency +impact. + +In short, EAS changes the way CFS tasks are assigned to CPUs. When it is time +for the scheduler to decide where a task should run (during wake-up), the EM +is used to break the tie between several good CPU candidates and pick the one +that is predicted to yield the best energy consumption without harming the +system's throughput. The predictions made by EAS rely on specific elements of +knowledge about the platform's topology, which include the 'capacity' of CPUs, +and their respective energy costs. + + +3. Topology information +----------------------- + +EAS (as well as the rest of the scheduler) uses the notion of 'capacity' to +differentiate CPUs with different computing throughput. The 'capacity' of a CPU +represents the amount of work it can absorb when running at its highest +frequency compared to the most capable CPU of the system. Capacity values are +normalized in a 1024 range, and are comparable with the utilization signals of +tasks and CPUs computed by the Per-Entity Load Tracking (PELT) mechanism. Thanks +to capacity and utilization values, EAS is able to estimate how big/busy a +task/CPU is, and to take this into consideration when evaluating performance vs +energy trade-offs. The capacity of CPUs is provided via arch-specific code +through the arch_scale_cpu_capacity() callback. + +The rest of platform knowledge used by EAS is directly read from the Energy +Model (EM) framework. The EM of a platform is composed of a power cost table +per 'performance domain' in the system (see Documentation/power/energy-model.txt +for futher details about performance domains). + +The scheduler manages references to the EM objects in the topology code when the +scheduling domains are built, or re-built. For each root domain (rd), the +scheduler maintains a singly linked list of all performance domains intersecting +the current rd->span. Each node in the list contains a pointer to a struct +em_perf_domain as provided by the EM framework. + +The lists are attached to the root domains in order to cope with exclusive +cpuset configurations. Since the boundaries of exclusive cpusets do not +necessarily match those of performance domains, the lists of different root +domains can contain duplicate elements. + +Example 1. + Let us consider a platform with 12 CPUs, split in 3 performance domains + (pd0, pd4 and pd8), organized as follows: + + CPUs: 0 1 2 3 4 5 6 7 8 9 10 11 + PDs: |--pd0--|--pd4--|---pd8---| + RDs: |----rd1----|-----rd2-----| + + Now, consider that userspace decided to split the system with two + exclusive cpusets, hence creating two independent root domains, each + containing 6 CPUs. The two root domains are denoted rd1 and rd2 in the + above figure. Since pd4 intersects with both rd1 and rd2, it will be + present in the linked list '->pd' attached to each of them: + * rd1->pd: pd0 -> pd4 + * rd2->pd: pd4 -> pd8 + + Please note that the scheduler will create two duplicate list nodes for + pd4 (one for each list). However, both just hold a pointer to the same + shared data structure of the EM framework. + +Since the access to these lists can happen concurrently with hotplug and other +things, they are protected by RCU, like the rest of topology structures +manipulated by the scheduler. + +EAS also maintains a static key (sched_energy_present) which is enabled when at +least one root domain meets all conditions for EAS to start. Those conditions +are summarized in Section 6. + + +4. Energy-Aware task placement +------------------------------ + +EAS overrides the CFS task wake-up balancing code. It uses the EM of the +platform and the PELT signals to choose an energy-efficient target CPU during +wake-up balance. When EAS is enabled, select_task_rq_fair() calls +find_energy_efficient_cpu() to do the placement decision. This function looks +for the CPU with the highest spare capacity (CPU capacity - CPU utilization) in +each performance domain since it is the one which will allow us to keep the +frequency the lowest. Then, the function checks if placing the task there could +save energy compared to leaving it on prev_cpu, i.e. the CPU where the task ran +in its previous activation. + +find_energy_efficient_cpu() uses compute_energy() to estimate what will be the +energy consumed by the system if the waking task was migrated. compute_energy() +looks at the current utilization landscape of the CPUs and adjusts it to +'simulate' the task migration. The EM framework provides the em_pd_energy() API +which computes the expected energy consumption of each performance domain for +the given utilization landscape. + +An example of energy-optimized task placement decision is detailed below. + +Example 2. + Let us consider a (fake) platform with 2 independent performance domains + composed of two CPUs each. CPU0 and CPU1 are little CPUs; CPU2 and CPU3 + are big. + + The scheduler must decide where to place a task P whose util_avg = 200 + and prev_cpu = 0. + + The current utilization landscape of the CPUs is depicted on the graph + below. CPUs 0-3 have a util_avg of 400, 100, 600 and 500 respectively + Each performance domain has three Operating Performance Points (OPPs). + The CPU capacity and power cost associated with each OPP is listed in + the Energy Model table. The util_avg of P is shown on the figures + below as 'PP'. + + CPU util. + 1024 - - - - - - - Energy Model + +-----------+-------------+ + | Little | Big | + 768 ============= +-----+-----+------+------+ + | Cap | Pwr | Cap | Pwr | + +-----+-----+------+------+ + 512 =========== - ##- - - - - | 170 | 50 | 512 | 400 | + ## ## | 341 | 150 | 768 | 800 | + 341 -PP - - - - ## ## | 512 | 300 | 1024 | 1700 | + PP ## ## +-----+-----+------+------+ + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + Current OPP: ===== Other OPP: - - - util_avg (100 each): ## + + + find_energy_efficient_cpu() will first look for the CPUs with the + maximum spare capacity in the two performance domains. In this example, + CPU1 and CPU3. Then it will estimate the energy of the system if P was + placed on either of them, and check if that would save some energy + compared to leaving P on CPU0. EAS assumes that OPPs follow utilization + (which is coherent with the behaviour of the schedutil CPUFreq + governor, see Section 6. for more details on this topic). + + Case 1. P is migrated to CPU1 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 300 / 341 * 150 = 131 + * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1364 + 341 =========== ## ## + PP ## ## + 170 -## - - PP- ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + + Case 2. P is migrated to CPU3 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 200 / 341 * 150 = 88 + * CPU1: 100 / 341 * 150 = 43 + PP * CPU2: 600 / 768 * 800 = 625 + 512 - - - - - - - ##- - -PP - * CPU3: 700 / 768 * 800 = 729 + ## ## => total_energy = 1485 + 341 =========== ## ## + ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + + Case 3. P stays on prev_cpu / CPU 0 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 1024 - - - - - - - + + Energy calculation: + 768 ============= * CPU0: 400 / 512 * 300 = 234 + * CPU1: 100 / 512 * 300 = 58 + * CPU2: 600 / 768 * 800 = 625 + 512 =========== - ##- - - - - * CPU3: 500 / 768 * 800 = 520 + ## ## => total_energy = 1437 + 341 -PP - - - - ## ## + PP ## ## + 170 -## - - - - ## ## + ## ## ## ## + ------------ ------------- + CPU0 CPU1 CPU2 CPU3 + + + From these calculations, the Case 1 has the lowest total energy. So CPU 1 + is be the best candidate from an energy-efficiency standpoint. + +Big CPUs are generally more power hungry than the little ones and are thus used +mainly when a task doesn't fit the littles. However, little CPUs aren't always +necessarily more energy-efficient than big CPUs. For some systems, the high OPPs +of the little CPUs can be less energy-efficient than the lowest OPPs of the +bigs, for example. So, if the little CPUs happen to have enough utilization at +a specific point in time, a small task waking up at that moment could be better +of executing on the big side in order to save energy, even though it would fit +on the little side. + +And even in the case where all OPPs of the big CPUs are less energy-efficient +than those of the little, using the big CPUs for a small task might still, under +specific conditions, save energy. Indeed, placing a task on a little CPU can +result in raising the OPP of the entire performance domain, and that will +increase the cost of the tasks already running there. If the waking task is +placed on a big CPU, its own execution cost might be higher than if it was +running on a little, but it won't impact the other tasks of the little CPUs +which will keep running at a lower OPP. So, when considering the total energy +consumed by CPUs, the extra cost of running that one task on a big core can be +smaller than the cost of raising the OPP on the little CPUs for all the other +tasks. + +The examples above would be nearly impossible to get right in a generic way, and +for all platforms, without knowing the cost of running at different OPPs on all +CPUs of the system. Thanks to its EM-based design, EAS should cope with them +correctly without too many troubles. However, in order to ensure a minimal +impact on throughput for high-utilization scenarios, EAS also implements another +mechanism called 'over-utilization'. + + +5. Over-utilization +------------------- + +From a general standpoint, the use-cases where EAS can help the most are those +involving a light/medium CPU utilization. Whenever long CPU-bound tasks are +being run, they will require all of the available CPU capacity, and there isn't +much that can be done by the scheduler to save energy without severly harming +throughput. In order to avoid hurting performance with EAS, CPUs are flagged as +'over-utilized' as soon as they are used at more than 80% of their compute +capacity. As long as no CPUs are over-utilized in a root domain, load balancing +is disabled and EAS overridess the wake-up balancing code. EAS is likely to load +the most energy efficient CPUs of the system more than the others if that can be +done without harming throughput. So, the load-balancer is disabled to prevent +it from breaking the energy-efficient task placement found by EAS. It is safe to +do so when the system isn't overutilized since being below the 80% tipping point +implies that: + + a. there is some idle time on all CPUs, so the utilization signals used by + EAS are likely to accurately represent the 'size' of the various tasks + in the system; + b. all tasks should already be provided with enough CPU capacity, + regardless of their nice values; + c. since there is spare capacity all tasks must be blocking/sleeping + regularly and balancing at wake-up is sufficient. + +As soon as one CPU goes above the 80% tipping point, at least one of the three +assumptions above becomes incorrect. In this scenario, the 'overutilized' flag +is raised for the entire root domain, EAS is disabled, and the load-balancer is +re-enabled. By doing so, the scheduler falls back onto load-based algorithms for +wake-up and load balance under CPU-bound conditions. This provides a better +respect of the nice values of tasks. + +Since the notion of overutilization largely relies on detecting whether or not +there is some idle time in the system, the CPU capacity 'stolen' by higher +(than CFS) scheduling classes (as well as IRQ) must be taken into account. As +such, the detection of overutilization accounts for the capacity used not only +by CFS tasks, but also by the other scheduling classes and IRQ. + + +6. Dependencies and requirements for EAS +---------------------------------------- + +Energy Aware Scheduling depends on the CPUs of the system having specific +hardware properties and on other features of the kernel being enabled. This +section lists these dependencies and provides hints as to how they can be met. + + + 6.1 - Asymmetric CPU topology + +As mentioned in the introduction, EAS is only supported on platforms with +asymmetric CPU topologies for now. This requirement is checked at run-time by +looking for the presence of the SD_ASYM_CPUCAPACITY flag when the scheduling +domains are built. + +The flag is set/cleared automatically by the scheduler topology code whenever +there are CPUs with different capacities in a root domain. The capacities of +CPUs are provided by arch-specific code through the arch_scale_cpu_capacity() +callback. As an example, arm and arm64 share an implementation of this callback +which uses a combination of CPUFreq data and device-tree bindings to compute the +capacity of CPUs (see drivers/base/arch_topology.c for more details). + +So, in order to use EAS on your platform your architecture must implement the +arch_scale_cpu_capacity() callback, and some of the CPUs must have a lower +capacity than others. + +Please note that EAS is not fundamentally incompatible with SMP, but no +significant savings on SMP platforms have been observed yet. This restriction +could be amended in the future if proven otherwise. + + + 6.2 - Energy Model presence + +EAS uses the EM of a platform to estimate the impact of scheduling decisions on +energy. So, your platform must provide power cost tables to the EM framework in +order to make EAS start. To do so, please refer to documentation of the +independent EM framework in Documentation/power/energy-model.txt. + +Please also note that the scheduling domains need to be re-built after the +EM has been registered in order to start EAS. + + + 6.3 - Energy Model complexity + +The task wake-up path is very latency-sensitive. When the EM of a platform is +too complex (too many CPUs, too many performance domains, too many performance +states, ...), the cost of using it in the wake-up path can become prohibitive. +The energy-aware wake-up algorithm has a complexity of: + + C = Nd * (Nc + Ns) + +with: Nd the number of performance domains; Nc the number of CPUs; and Ns the +total number of OPPs (ex: for two perf. domains with 4 OPPs each, Ns = 8). + +A complexity check is performed at the root domain level, when scheduling +domains are built. EAS will not start on a root domain if its C happens to be +higher than the completely arbitrary EM_MAX_COMPLEXITY threshold (2048 at the +time of writing). + +If you really want to use EAS but the complexity of your platform's Energy +Model is too high to be used with a single root domain, you're left with only +two possible options: + + 1. split your system into separate, smaller, root domains using exclusive + cpusets and enable EAS locally on each of them. This option has the + benefit to work out of the box but the drawback of preventing load + balance between root domains, which can result in an unbalanced system + overall; + 2. submit patches to reduce the complexity of the EAS wake-up algorithm, + hence enabling it to cope with larger EMs in reasonable time. + + + 6.4 - Schedutil governor + +EAS tries to predict at which OPP will the CPUs be running in the close future +in order to estimate their energy consumption. To do so, it is assumed that OPPs +of CPUs follow their utilization. + +Although it is very difficult to provide hard guarantees regarding the accuracy +of this assumption in practice (because the hardware might not do what it is +told to do, for example), schedutil as opposed to other CPUFreq governors at +least _requests_ frequencies calculated using the utilization signals. +Consequently, the only sane governor to use together with EAS is schedutil, +because it is the only one providing some degree of consistency between +frequency requests and energy predictions. + +Using EAS with any other governor than schedutil is not supported. + + + 6.5 Scale-invariant utilization signals + +In order to make accurate prediction across CPUs and for all performance +states, EAS needs frequency-invariant and CPU-invariant PELT signals. These can +be obtained using the architecture-defined arch_scale{cpu,freq}_capacity() +callbacks. + +Using EAS on a platform that doesn't implement these two callbacks is not +supported. + + + 6.6 Multithreading (SMT) + +EAS in its current form is SMT unaware and is not able to leverage +multithreaded hardware to save energy. EAS considers threads as independent +CPUs, which can actually be counter-productive for both performance and energy. + +EAS on SMT is not supported. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 92999d4e0cb8..25a4b4cf04a6 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -97,11 +97,6 @@ parameters may be changed at runtime by the command allowing boot to proceed. none ignores them, expecting user space to do the scan. - scsi_mod.use_blk_mq= - [SCSI] use blk-mq I/O path by default - See SCSI_MQ_DEFAULT in drivers/scsi/Kconfig. - Format: <y/n> - sim710= [SCSI,HW] See header of drivers/scsi/sim710.c. diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 177c031763c0..c1dd4939f4ae 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -1098,8 +1098,6 @@ of interest: unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing restriction), 0=>can use full 32 bit (or better) DMA address space - use_clustering - 1=>SCSI commands in mid level's queue can be merged, - 0=>disallow SCSI command merging no_async_abort - 1=>Asynchronous aborts are not supported 0=>Timed-out commands will be aborted asynchronously hostt - pointer to driver's struct scsi_host_template from which diff --git a/Documentation/security/credentials.rst b/Documentation/security/credentials.rst index 5bb7125faeee..282e79feee6a 100644 --- a/Documentation/security/credentials.rst +++ b/Documentation/security/credentials.rst @@ -291,7 +291,7 @@ for example), it must be considered immutable, barring two exceptions: 1. The reference count may be altered. - 2. Whilst the keyring subscriptions of a set of credentials may not be + 2. While the keyring subscriptions of a set of credentials may not be changed, the keyrings subscribed to may have their contents altered. To catch accidental credential alteration at compile time, struct task_struct @@ -358,7 +358,7 @@ Once a reference has been obtained, it must be released with ``put_cred()``, Accessing Another Task's Credentials ------------------------------------ -Whilst a task may access its own credentials without the need for locking, the +While a task may access its own credentials without the need for locking, the same is not true of a task wanting to access another task's credentials. It must use the RCU read lock and ``rcu_dereference()``. @@ -382,7 +382,7 @@ This should be used inside the RCU read lock, as in the following example:: } Should it be necessary to hold another task's credentials for a long period of -time, and possibly to sleep whilst doing so, then the caller should get a +time, and possibly to sleep while doing so, then the caller should get a reference on them using:: const struct cred *get_task_cred(struct task_struct *task); @@ -442,7 +442,7 @@ duplicate of the current process's credentials, returning with the mutex still held if successful. It returns NULL if not successful (out of memory). The mutex prevents ``ptrace()`` from altering the ptrace state of a process -whilst security checks on credentials construction and changing is taking place +while security checks on credentials construction and changing is taking place as the ptrace state may alter the outcome, particularly in the case of ``execve()``. diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index 9ce7256c6edb..9521c4207f01 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -859,6 +859,7 @@ The keyctl syscall functions are: and either the buffer length or the OtherInfo length exceeds the allowed length. + * Restrict keyring linkage:: long keyctl(KEYCTL_RESTRICT_KEYRING, key_serial_t keyring, @@ -890,6 +891,116 @@ The keyctl syscall functions are: applicable to the asymmetric key type. + * Query an asymmetric key:: + + long keyctl(KEYCTL_PKEY_QUERY, + key_serial_t key_id, unsigned long reserved, + struct keyctl_pkey_query *info); + + Get information about an asymmetric key. The information is returned in + the keyctl_pkey_query struct:: + + __u32 supported_ops; + __u32 key_size; + __u16 max_data_size; + __u16 max_sig_size; + __u16 max_enc_size; + __u16 max_dec_size; + __u32 __spare[10]; + + ``supported_ops`` contains a bit mask of flags indicating which ops are + supported. This is constructed from a bitwise-OR of:: + + KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY} + + ``key_size`` indicated the size of the key in bits. + + ``max_*_size`` indicate the maximum sizes in bytes of a blob of data to be + signed, a signature blob, a blob to be encrypted and a blob to be + decrypted. + + ``__spare[]`` must be set to 0. This is intended for future use to hand + over one or more passphrases needed unlock a key. + + If successful, 0 is returned. If the key is not an asymmetric key, + EOPNOTSUPP is returned. + + + * Encrypt, decrypt, sign or verify a blob using an asymmetric key:: + + long keyctl(KEYCTL_PKEY_ENCRYPT, + const struct keyctl_pkey_params *params, + const char *info, + const void *in, + void *out); + + long keyctl(KEYCTL_PKEY_DECRYPT, + const struct keyctl_pkey_params *params, + const char *info, + const void *in, + void *out); + + long keyctl(KEYCTL_PKEY_SIGN, + const struct keyctl_pkey_params *params, + const char *info, + const void *in, + void *out); + + long keyctl(KEYCTL_PKEY_VERIFY, + const struct keyctl_pkey_params *params, + const char *info, + const void *in, + const void *in2); + + Use an asymmetric key to perform a public-key cryptographic operation a + blob of data. For encryption and verification, the asymmetric key may + only need the public parts to be available, but for decryption and signing + the private parts are required also. + + The parameter block pointed to by params contains a number of integer + values:: + + __s32 key_id; + __u32 in_len; + __u32 out_len; + __u32 in2_len; + + ``key_id`` is the ID of the asymmetric key to be used. ``in_len`` and + ``in2_len`` indicate the amount of data in the in and in2 buffers and + ``out_len`` indicates the size of the out buffer as appropriate for the + above operations. + + For a given operation, the in and out buffers are used as follows:: + + Operation ID in,in_len out,out_len in2,in2_len + ======================= =============== =============== =============== + KEYCTL_PKEY_ENCRYPT Raw data Encrypted data - + KEYCTL_PKEY_DECRYPT Encrypted data Raw data - + KEYCTL_PKEY_SIGN Raw data Signature - + KEYCTL_PKEY_VERIFY Raw data - Signature + + ``info`` is a string of key=value pairs that supply supplementary + information. These include: + + ``enc=<encoding>`` The encoding of the encrypted/signature blob. This + can be "pkcs1" for RSASSA-PKCS1-v1.5 or + RSAES-PKCS1-v1.5; "pss" for "RSASSA-PSS"; "oaep" for + "RSAES-OAEP". If omitted or is "raw", the raw output + of the encryption function is specified. + + ``hash=<algo>`` If the data buffer contains the output of a hash + function and the encoding includes some indication of + which hash function was used, the hash function can be + specified with this, eg. "hash=sha256". + + The ``__spare[]`` space in the parameter block must be set to 0. This is + intended, amongst other things, to allow the passing of passphrases + required to unlock a key. + + If successful, encrypt, decrypt and sign all return the amount of data + written into the output buffer. Verification returns 0 on success. + + Kernel Services =============== @@ -1483,6 +1594,112 @@ The structure has a number of fields, some of which are mandatory: attempted key link operation. If there is no match, -EINVAL is returned. + * ``int (*asym_eds_op)(struct kernel_pkey_params *params, + const void *in, void *out);`` + ``int (*asym_verify_signature)(struct kernel_pkey_params *params, + const void *in, const void *in2);`` + + These methods are optional. If provided the first allows a key to be + used to encrypt, decrypt or sign a blob of data, and the second allows a + key to verify a signature. + + In all cases, the following information is provided in the params block:: + + struct kernel_pkey_params { + struct key *key; + const char *encoding; + const char *hash_algo; + char *info; + __u32 in_len; + union { + __u32 out_len; + __u32 in2_len; + }; + enum kernel_pkey_operation op : 8; + }; + + This includes the key to be used; a string indicating the encoding to use + (for instance, "pkcs1" may be used with an RSA key to indicate + RSASSA-PKCS1-v1.5 or RSAES-PKCS1-v1.5 encoding or "raw" if no encoding); + the name of the hash algorithm used to generate the data for a signature + (if appropriate); the sizes of the input and output (or second input) + buffers; and the ID of the operation to be performed. + + For a given operation ID, the input and output buffers are used as + follows:: + + Operation ID in,in_len out,out_len in2,in2_len + ======================= =============== =============== =============== + kernel_pkey_encrypt Raw data Encrypted data - + kernel_pkey_decrypt Encrypted data Raw data - + kernel_pkey_sign Raw data Signature - + kernel_pkey_verify Raw data - Signature + + asym_eds_op() deals with encryption, decryption and signature creation as + specified by params->op. Note that params->op is also set for + asym_verify_signature(). + + Encrypting and signature creation both take raw data in the input buffer + and return the encrypted result in the output buffer. Padding may have + been added if an encoding was set. In the case of signature creation, + depending on the encoding, the padding created may need to indicate the + digest algorithm - the name of which should be supplied in hash_algo. + + Decryption takes encrypted data in the input buffer and returns the raw + data in the output buffer. Padding will get checked and stripped off if + an encoding was set. + + Verification takes raw data in the input buffer and the signature in the + second input buffer and checks that the one matches the other. Padding + will be validated. Depending on the encoding, the digest algorithm used + to generate the raw data may need to be indicated in hash_algo. + + If successful, asym_eds_op() should return the number of bytes written + into the output buffer. asym_verify_signature() should return 0. + + A variety of errors may be returned, including EOPNOTSUPP if the operation + is not supported; EKEYREJECTED if verification fails; ENOPKG if the + required crypto isn't available. + + + * ``int (*asym_query)(const struct kernel_pkey_params *params, + struct kernel_pkey_query *info);`` + + This method is optional. If provided it allows information about the + public or asymmetric key held in the key to be determined. + + The parameter block is as for asym_eds_op() and co. but in_len and out_len + are unused. The encoding and hash_algo fields should be used to reduce + the returned buffer/data sizes as appropriate. + + If successful, the following information is filled in:: + + struct kernel_pkey_query { + __u32 supported_ops; + __u32 key_size; + __u16 max_data_size; + __u16 max_sig_size; + __u16 max_enc_size; + __u16 max_dec_size; + }; + + The supported_ops field will contain a bitmask indicating what operations + are supported by the key, including encryption of a blob, decryption of a + blob, signing a blob and verifying the signature on a blob. The following + constants are defined for this:: + + KEYCTL_SUPPORTS_{ENCRYPT,DECRYPT,SIGN,VERIFY} + + The key_size field is the size of the key in bits. max_data_size and + max_sig_size are the maximum raw data and signature sizes for creation and + verification of a signature; max_enc_size and max_dec_size are the maximum + raw data and signature sizes for encryption and decryption. The + max_*_size fields are measured in bytes. + + If successful, 0 will be returned. If the key doesn't support this, + EOPNOTSUPP will be returned. + + Request-Key Callback Service ============================ diff --git a/Documentation/security/keys/request-key.rst b/Documentation/security/keys/request-key.rst index 21e27238cec6..600ad67d1707 100644 --- a/Documentation/security/keys/request-key.rst +++ b/Documentation/security/keys/request-key.rst @@ -132,7 +132,7 @@ Negative Instantiation And Rejection Rather than instantiating a key, it is possible for the possessor of an authorisation key to negatively instantiate a key that's under construction. This is a short duration placeholder that causes any attempt at re-requesting -the key whilst it exists to fail with error ENOKEY if negated or the specified +the key while it exists to fail with error ENOKEY if negated or the specified error if rejected. This is provided to prevent excessive repeated spawning of /sbin/request-key diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 3bb24e09a332..7b35fcb58933 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -18,10 +18,33 @@ integrity verifications match. A loaded Trusted Key can be updated with new when the kernel and initramfs are updated. The same key can have many saved blobs under different PCR values, so multiple boots are easily supported. +TPM 1.2 +------- + By default, trusted keys are sealed under the SRK, which has the default authorization value (20 zeros). This can be set at takeownership time with the trouser's utility: "tpm_takeownership -u -z". +TPM 2.0 +------- + +The user must first create a storage key and make it persistent, so the key is +available after reboot. This can be done using the following commands. + +With the IBM TSS 2 stack:: + + #> tsscreateprimary -hi o -st + Handle 80000000 + #> tssevictcontrol -hi o -ho 80000000 -hp 81000001 + +Or with the Intel TSS 2 stack:: + + #> tpm2_createprimary --hierarchy o -G rsa2048 -o key.ctxt + [...] + handle: 0x800000FF + #> tpm2_evictcontrol -c key.ctxt -p 0x81000001 + persistentHandle: 0x81000001 + Usage:: keyctl add trusted name "new keylen [options]" ring @@ -30,7 +53,9 @@ Usage:: keyctl print keyid options: - keyhandle= ascii hex value of sealing key default 0x40000000 (SRK) + keyhandle= ascii hex value of sealing key + TPM 1.2: default 0x40000000 (SRK) + TPM 2.0: no default; must be passed every time keyauth= ascii hex auth for sealing key default 0x00...i (40 ascii zeros) blobauth= ascii hex auth for sealed data default 0x00... @@ -76,7 +101,7 @@ Usage:: Where:: - format:= 'default | ecryptfs' + format:= 'default | ecryptfs | enc32' key-type:= 'trusted' | 'user' @@ -84,6 +109,10 @@ Examples of trusted and encrypted key usage: Create and save a trusted key named "kmk" of length 32 bytes:: +Note: When using a TPM 2.0 with a persistent key with handle 0x81000001, +append 'keyhandle=0x81000001' to statements between quotes, such as +"new 32 keyhandle=0x81000001". + $ keyctl add trusted kmk "new 32" @u 440502848 @@ -173,3 +202,7 @@ are anticipated. In particular the new format 'ecryptfs' has been defined in in order to use encrypted keys to mount an eCryptfs filesystem. More details about the usage can be found in the file ``Documentation/security/keys/ecryptfs.rst``. + +Another new format 'enc32' has been defined in order to support encrypted keys +with payload size of 32 bytes. This will initially be used for nvdimm security +but may expand to other usages that require 32 bytes payload. diff --git a/Documentation/security/self-protection.rst b/Documentation/security/self-protection.rst index e1ca698e0006..f584fb74b4ff 100644 --- a/Documentation/security/self-protection.rst +++ b/Documentation/security/self-protection.rst @@ -302,11 +302,11 @@ sure structure holes are cleared. Memory poisoning ---------------- -When releasing memory, it is best to poison the contents (clear stack on -syscall return, wipe heap memory on a free), to avoid reuse attacks that -rely on the old contents of memory. This frustrates many uninitialized -variable attacks, stack content exposures, heap content exposures, and -use-after-free attacks. +When releasing memory, it is best to poison the contents, to avoid reuse +attacks that rely on the old contents of memory. E.g., clear stack on a +syscall return (``CONFIG_GCC_PLUGIN_STACKLEAK``), wipe heap memory on a +free. This frustrates many uninitialized variable attacks, stack content +exposures, heap content exposures, and use-after-free attacks. Destination tracking -------------------- diff --git a/Documentation/serial/driver b/Documentation/serial/driver index da193e092fc3..86e47c19a924 100644 --- a/Documentation/serial/driver +++ b/Documentation/serial/driver @@ -7,7 +7,7 @@ This document is meant as a brief overview of some aspects of the new serial driver. It is not complete, any questions you have should be directed to <rmk@arm.linux.org.uk> -The reference implementation is contained within amba_pl011.c. +The reference implementation is contained within amba-pl011.c. diff --git a/Documentation/serial/serial-iso7816.txt b/Documentation/serial/serial-iso7816.txt new file mode 100644 index 000000000000..3193d24a2b0f --- /dev/null +++ b/Documentation/serial/serial-iso7816.txt @@ -0,0 +1,83 @@ + ISO7816 SERIAL COMMUNICATIONS + +1. INTRODUCTION + + ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC) + also known as smart cards. + +2. HARDWARE-RELATED CONSIDERATIONS + + Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of + handling communication with a smart card. + + For these microcontrollers, the Linux driver should be made capable of + working in both modes, and proper ioctls (see later) should be made + available at user-level to allow switching from one mode to the other, and + vice versa. + +3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL + + The Linux kernel provides the serial_iso7816 structure (see [1]) to handle + ISO7816 communications. This data structure is used to set and configure + ISO7816 parameters in ioctls. + + Any driver for devices capable of working both as RS232 and ISO7816 should + implement the iso7816_config callback in the uart_port structure. The + serial_core calls iso7816_config to do the device specific part in response + to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config + callback receives a pointer to struct serial_iso7816. + +4. USAGE FROM USER-LEVEL + + From user-level, ISO7816 configuration can be get/set using the previous + ioctls. For instance, to set ISO7816 you can use the following code: + + #include <linux/serial.h> + + /* Include definition for ISO7816 ioctls: TIOCSISO7816 and TIOCGISO7816 */ + #include <sys/ioctl.h> + + /* Open your specific device (e.g., /dev/mydevice): */ + int fd = open ("/dev/mydevice", O_RDWR); + if (fd < 0) { + /* Error handling. See errno. */ + } + + struct serial_iso7816 iso7816conf; + + /* Reserved fields as to be zeroed */ + memset(&iso7816conf, 0, sizeof(iso7816conf)); + + /* Enable ISO7816 mode: */ + iso7816conf.flags |= SER_ISO7816_ENABLED; + + /* Select the protocol: */ + /* T=0 */ + iso7816conf.flags |= SER_ISO7816_T(0); + /* or T=1 */ + iso7816conf.flags |= SER_ISO7816_T(1); + + /* Set the guard time: */ + iso7816conf.tg = 2; + + /* Set the clock frequency*/ + iso7816conf.clk = 3571200; + + /* Set transmission factors: */ + iso7816conf.sc_fi = 372; + iso7816conf.sc_di = 1; + + if (ioctl(fd_usart, TIOCSISO7816, &iso7816conf) < 0) { + /* Error handling. See errno. */ + } + + /* Use read() and write() syscalls here... */ + + /* Close the device when finished: */ + if (close (fd) < 0) { + /* Error handling. See errno. */ + } + +5. REFERENCES + + [1] include/uapi/linux/serial.h diff --git a/Documentation/serial/serial-rs485.txt b/Documentation/serial/serial-rs485.txt index 389fcd4759e9..ce0c1a9b8aab 100644 --- a/Documentation/serial/serial-rs485.txt +++ b/Documentation/serial/serial-rs485.txt @@ -75,7 +75,7 @@ /* Set rts delay after send, if needed: */ rs485conf.delay_rts_after_send = ...; - /* Set this flag if you want to receive data even whilst sending data */ + /* Set this flag if you want to receive data even while sending data */ rs485conf.flags |= SER_RS485_RX_DURING_TX; if (ioctl (fd, TIOCSRS485, &rs485conf) < 0) { diff --git a/Documentation/sh/new-machine.txt b/Documentation/sh/new-machine.txt index f0354164cb0e..e0961a66130b 100644 --- a/Documentation/sh/new-machine.txt +++ b/Documentation/sh/new-machine.txt @@ -116,7 +116,6 @@ might look something like: * arch/sh/boards/vapor/setup.c - Setup code for imaginary board */ #include <linux/init.h> -#include <asm/rtc.h> /* for board_time_init() */ const char *get_system_type(void) { @@ -132,13 +131,6 @@ int __init platform_setup(void) * this board. */ - /* - * Presume all FooTech boards have the same broken timer, - * and also presume that we've defined foo_timer_init to - * do something useful. - */ - board_time_init = foo_timer_init; - /* Start-up imaginary PCI ... */ /* And whatever else ... */ diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst index 368a07a165f5..7d7c191102a7 100644 --- a/Documentation/sound/hd-audio/models.rst +++ b/Documentation/sound/hd-audio/models.rst @@ -254,10 +254,12 @@ alc274-dell-aio ALC274 fixups on Dell AIO machines alc255-dummy-lineout Dell Precision 3930 fixups -alc255-dell-headset"}, +alc255-dell-headset Dell Precision 3630 fixups alc295-hp-x360 HP Spectre X360 fixups +alc-sense-combo + Headset button support for Chrome platform ALC66x/67x/892 ============== diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index b37234afdfa1..6b154dbb02cc 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -3520,14 +3520,14 @@ allocator will try to get an area as large as possible within the given size. The second argument (type) and the third argument (device pointer) are -dependent on the bus. In the case of the ISA bus, pass -:c:func:`snd_dma_isa_data()` as the third argument with +dependent on the bus. For normal devices, pass the device pointer +(typically identical as ``card->dev``) to the third argument with ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the ``snd_dma_continuous_data(GFP_KERNEL)`` device pointer, where -``GFP_KERNEL`` is the kernel allocation flag to use. For the PCI -scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with -``snd_dma_pci_data(pci)`` (see the `Non-Contiguous Buffers`_ +``GFP_KERNEL`` is the kernel allocation flag to use. For the +scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the device +pointer (see the `Non-Contiguous Buffers`_ section). Once the buffer is pre-allocated, you can use the allocator in the @@ -3924,15 +3924,12 @@ The scheme of the real suspend job is as follows. 2. Call :c:func:`snd_power_change_state()` with ``SNDRV_CTL_POWER_D3hot`` to change the power status. -3. Call :c:func:`snd_pcm_suspend_all()` to suspend the running - PCM streams. - -4. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for +3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for each codec. -5. Save the register values if necessary. +4. Save the register values if necessary. -6. Stop the hardware if necessary. +5. Stop the hardware if necessary. A typical code would be like: @@ -3946,12 +3943,10 @@ A typical code would be like: /* (2) */ snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); /* (3) */ - snd_pcm_suspend_all(chip->pcm); - /* (4) */ snd_ac97_suspend(chip->ac97); - /* (5) */ + /* (4) */ snd_mychip_save_registers(chip); - /* (6) */ + /* (5) */ snd_mychip_stop_hardware(chip); return 0; } @@ -3994,13 +3989,9 @@ A typical code would be like: return 0; } -As shown in the above, it's better to save registers after suspending -the PCM operations via :c:func:`snd_pcm_suspend_all()` or -:c:func:`snd_pcm_suspend()`. It means that the PCM streams are -already stopped when the register snapshot is taken. But, remember that -you don't have to restart the PCM stream in the resume callback. It'll -be restarted via trigger call with ``SNDRV_PCM_TRIGGER_RESUME`` when -necessary. +Note that, at the time this callback gets called, the PCM stream has +been already suspended via its own PM ops calling +:c:func:`snd_pcm_suspend_all()` internally. OK, we have all callbacks now. Let's set them up. In the initialization of the card, make sure that you can get the chip data from the card diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst index 55820e51708f..2e99183a7a47 100644 --- a/Documentation/sound/soc/dai.rst +++ b/Documentation/sound/soc/dai.rst @@ -24,7 +24,7 @@ I2S === I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and -Rx lines are used for audio transmission, whilst the bit clock (BCLK) and +Rx lines are used for audio transmission, while the bit clock (BCLK) and left/right clock (LRC) synchronise the link. I2S is flexible in that either the controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock usually varies depending on the sample rate and the master system clock @@ -49,9 +49,9 @@ PCM PCM is another 4 wire interface, very similar to I2S, which can support a more flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used -to synchronise the link whilst the Tx and Rx lines are used to transmit and +to synchronise the link while the Tx and Rx lines are used to transmit and receive the audio data. Bit clock usually varies depending on sample rate -whilst sync runs at the sample rate. PCM also supports Time Division +while sync runs at the sample rate. PCM also supports Time Division Multiplexing (TDM) in that several devices can use the bus simultaneously (this is sometimes referred to as network mode). diff --git a/Documentation/sound/soc/dpcm.rst b/Documentation/sound/soc/dpcm.rst index fe61e02277f8..77f67ded53de 100644 --- a/Documentation/sound/soc/dpcm.rst +++ b/Documentation/sound/soc/dpcm.rst @@ -13,7 +13,7 @@ drivers that expose several ALSA PCMs and can route to multiple DAIs. The DPCM runtime routing is determined by the ALSA mixer settings in the same way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM graph representing the DSP internal audio paths and uses the mixer settings to -determine the patch used by each ALSA PCM. +determine the path used by each ALSA PCM. DPCM re-uses all the existing component codec, platform and DAI drivers without any modifications. @@ -101,7 +101,7 @@ The audio driver processes this as follows :- 4. Machine driver or audio HAL enables the speaker path. -5. DPCM runs the PCM ops for startup(), hw_params(), prepapre() and +5. DPCM runs the PCM ops for startup(), hw_params(), prepare() and trigger(start) for DAI1 Speakers since the path is enabled. In this example, the machine driver or userspace audio HAL can alter the routing @@ -218,10 +218,10 @@ like a BT phone call :- * * <----DAI5-----> FM ************* -This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are +This allows the host CPU to sleep while the DSP, MODEM DAI and the BT DAI are still in operation. -A BE DAI link can also set the codec to a dummy device if the code is a device +A BE DAI link can also set the codec to a dummy device if the codec is a device that is managed externally. Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the @@ -249,7 +249,7 @@ configuration. struct snd_interval *channels = hw_param_interval(params, SNDRV_PCM_HW_PARAM_CHANNELS); - /* The DSP will covert the FE rate to 48k, stereo */ + /* The DSP will convert the FE rate to 48k, stereo */ rate->min = rate->max = 48000; channels->min = channels->max = 2; @@ -386,5 +386,3 @@ This means creating a new FE that is connected with a virtual path to both DAI links. The DAI links will be started when the FE PCM is started and stopped when the FE PCM is stopped. Note that the FE PCM cannot read or write data in this configuration. - - diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx index 13a0b7fb192f..551325b66b23 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx @@ -21,15 +21,15 @@ Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a "platform device". The master configuration is passed to the driver via a table found in include/linux/spi/pxa2xx_spi.h: -struct pxa2xx_spi_master { +struct pxa2xx_spi_controller { u16 num_chipselect; u8 enable_dma; }; -The "pxa2xx_spi_master.num_chipselect" field is used to determine the number of +The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of slave device (chips) attached to this SPI master. -The "pxa2xx_spi_master.enable_dma" field informs the driver that SSP DMA should +The "pxa2xx_spi_controller.enable_dma" field informs the driver that SSP DMA should be used. This caused the driver to acquire two DMA channels: rx_channel and tx_channel. The rx_channel has a higher DMA service priority the tx_channel. See the "PXA2xx Developer Manual" section "DMA Controller". @@ -51,7 +51,7 @@ static struct resource pxa_spi_nssp_resources[] = { }, }; -static struct pxa2xx_spi_master pxa_nssp_master_info = { +static struct pxa2xx_spi_controller pxa_nssp_master_info = { .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ }; @@ -206,7 +206,7 @@ DMA and PIO I/O Support ----------------------- The pxa2xx_spi driver supports both DMA and interrupt driven PIO message transfers. The driver defaults to PIO mode and DMA transfers must be enabled -by setting the "enable_dma" flag in the "pxa2xx_spi_master" structure. The DMA +by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The DMA mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.txt index ab16efe0c79d..d68135560895 100644 --- a/Documentation/static-keys.txt +++ b/Documentation/static-keys.txt @@ -156,7 +156,7 @@ or increment/decrement function. Note that switching branches results in some locks being taken, particularly the CPU hotplug lock (in order to avoid races against -CPUs being brought in the kernel whilst the kernel is getting +CPUs being brought in the kernel while the kernel is getting patched). Calling the static key API from within a hotplug notifier is thus a sure deadlock recipe. In order to still allow use of the functionnality, the following functions are provided: diff --git a/Documentation/sysctl/fs.txt b/Documentation/sysctl/fs.txt index 819caf8ca05f..ebc679bcb2dc 100644 --- a/Documentation/sysctl/fs.txt +++ b/Documentation/sysctl/fs.txt @@ -56,26 +56,34 @@ of any kernel data structures. dentry-state: -From linux/fs/dentry.c: +From linux/include/linux/dcache.h: -------------------------------------------------------------- -struct { +struct dentry_stat_t dentry_stat { int nr_dentry; int nr_unused; int age_limit; /* age in seconds */ int want_pages; /* pages requested by system */ - int dummy[2]; -} dentry_stat = {0, 0, 45, 0,}; --------------------------------------------------------------- - -Dentries are dynamically allocated and deallocated, and -nr_dentry seems to be 0 all the time. Hence it's safe to -assume that only nr_unused, age_limit and want_pages are -used. Nr_unused seems to be exactly what its name says. + int nr_negative; /* # of unused negative dentries */ + int dummy; /* Reserved for future use */ +}; +-------------------------------------------------------------- + +Dentries are dynamically allocated and deallocated. + +nr_dentry shows the total number of dentries allocated (active ++ unused). nr_unused shows the number of dentries that are not +actively used, but are saved in the LRU list for future reuse. + Age_limit is the age in seconds after which dcache entries can be reclaimed when memory is short and want_pages is nonzero when shrink_dcache_pages() has been called and the dcache isn't pruned yet. +nr_negative shows the number of unused dentries that are also +negative dentries which do not map to any files. Instead, +they help speeding up rejection of non-existing files provided +by the users. + ============================================================== dquot-max & dquot-nr: diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 37a679501ddc..379063e58326 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -60,6 +60,7 @@ show up in /proc/sys/kernel: - panic_on_stackoverflow - panic_on_unrecovered_nmi - panic_on_warn +- panic_print - panic_on_rcu_stall - perf_cpu_time_max_percent - perf_event_paranoid @@ -78,6 +79,7 @@ show up in /proc/sys/kernel: - reboot-cmd [ SPARC only ] - rtsig-max - rtsig-nr +- sched_energy_aware - seccomp/ ==> Documentation/userspace-api/seccomp_filter.rst - sem - sem_next_id [ sysv ipc ] @@ -89,6 +91,7 @@ show up in /proc/sys/kernel: - shmmni - softlockup_all_cpu_backtrace - soft_watchdog +- stack_erasing - stop-a [ SPARC only ] - sysrq ==> Documentation/admin-guide/sysrq.rst - sysctl_writes_strict @@ -653,6 +656,22 @@ a kernel rebuild when attempting to kdump at the location of a WARN(). ============================================================== +panic_print: + +Bitmask for printing system info when panic happens. User can chose +combination of the following bits: + +bit 0: print all tasks info +bit 1: print system memory info +bit 2: print timer info +bit 3: print locks info if CONFIG_LOCKDEP is on +bit 4: print ftrace buffer + +So for example to print tasks and memory info on panic, user can: + echo 3 > /proc/sys/kernel/panic_print + +============================================================== + panic_on_rcu_stall: When set to 1, calls panic() after RCU stall detection messages. This @@ -872,6 +891,17 @@ rtsig-nr shows the number of RT signals currently queued. ============================================================== +sched_energy_aware: + +Enables/disables Energy Aware Scheduling (EAS). EAS starts +automatically on platforms where it can run (that is, +platforms with asymmetric CPU topologies and having an Energy +Model available). If your platform happens to meet the +requirements for EAS but you do not want to use it, change +this value to 0. + +============================================================== + sched_schedstats: Enables/disables scheduler statistics. Enabling this feature @@ -987,6 +1017,23 @@ detect a hard lockup condition. ============================================================== +stack_erasing + +This parameter can be used to control kernel stack erasing at the end +of syscalls for kernels built with CONFIG_GCC_PLUGIN_STACKLEAK. + +That erasing reduces the information which kernel stack leak bugs +can reveal and blocks some uninitialized stack variable attacks. +The tradeoff is the performance impact: on a single CPU system kernel +compilation sees a 1% slowdown, other systems and workloads may vary. + + 0: kernel stack erasing is disabled, STACKLEAK_METRICS are not updated. + + 1: kernel stack erasing is enabled (default), it is performed before + returning to the userspace at the end of syscalls. + +============================================================== + tainted: Non-zero if the kernel has been tainted. Numeric values, which can be diff --git a/Documentation/sysctl/net.txt b/Documentation/sysctl/net.txt index 9ecde517728c..2ae91d3873bb 100644 --- a/Documentation/sysctl/net.txt +++ b/Documentation/sysctl/net.txt @@ -52,6 +52,7 @@ two flavors of JITs, the newer eBPF JIT currently supported on: - sparc64 - mips64 - s390x + - riscv And the older cBPF JIT supported on the following archs: - mips @@ -92,6 +93,14 @@ Values : 0 - disable JIT kallsyms export (default value) 1 - enable JIT kallsyms export for privileged users only +bpf_jit_limit +------------- + +This enforces a global limit for memory allocations to the BPF JIT +compiler in order to reject unprivileged JIT requests once it has +been surpassed. bpf_jit_limit contains the value of the global limit +in bytes. + dev_weight -------------- @@ -283,6 +292,20 @@ user space is responsible for creating them if needed. Default : 0 (for compatibility reasons) +devconf_inherit_init_net +---------------------------- + +Controls if a new network namespace should inherit all current +settings under /proc/sys/net/{ipv4,ipv6}/conf/{all,default}/. By +default, we keep the current behavior: for IPv4 we inherit all current +settings from init_net and for IPv6 we reset all settings to default. + +If set to 1, both IPv4 and IPv6 settings are forced to inherit from +current ones in init_net. If set to 2, both IPv4 and IPv6 settings are +forced to reset to their default values. + +Default : 0 (for compatibility reasons) + 2. /proc/sys/net/unix - Parameters for Unix domain sockets ------------------------------------------------------- diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt index 7d73882e2c27..187ce4f599a2 100644 --- a/Documentation/sysctl/vm.txt +++ b/Documentation/sysctl/vm.txt @@ -63,6 +63,7 @@ Currently, these files are in /proc/sys/vm: - swappiness - user_reserve_kbytes - vfs_cache_pressure +- watermark_boost_factor - watermark_scale_factor - zone_reclaim_mode @@ -856,6 +857,26 @@ ten times more freeable objects than there are. ============================================================= +watermark_boost_factor: + +This factor controls the level of reclaim when memory is being fragmented. +It defines the percentage of the high watermark of a zone that will be +reclaimed if pages of different mobility are being mixed within pageblocks. +The intent is that compaction has less work to do in the future and to +increase the success rate of future high-order allocations such as SLUB +allocations, THP and hugetlbfs pages. + +To make it sensible with respect to the watermark_scale_factor parameter, +the unit is in fractions of 10,000. The default value of 15,000 means +that up to 150% of the high watermark will be reclaimed in the event of +a pageblock being mixed due to fragmentation. The level of reclaim is +determined by the number of fragmentation events that occurred in the +recent past. If this value is smaller than a pageblock then a pageblocks +worth of pages will be reclaimed (e.g. 2MB on 64-bit x86). A boost factor +of 0 will disable the feature. + +============================================================= + watermark_scale_factor: This factor controls the aggressiveness of kswapd. It defines the diff --git a/Documentation/thermal/power_allocator.txt b/Documentation/thermal/power_allocator.txt index a1ce2235f121..9fb0ff06dca9 100644 --- a/Documentation/thermal/power_allocator.txt +++ b/Documentation/thermal/power_allocator.txt @@ -110,7 +110,7 @@ the permitted thermal "ramp" of the system. For instance, a lower `k_pu` value will provide a slower ramp, at the cost of capping available capacity at a low temperature. On the other hand, a high value of `k_pu` will result in the governor granting very high power -whilst temperature is low, and may lead to temperature overshooting. +while temperature is low, and may lead to temperature overshooting. The default value for `k_pu` is: diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt index 89ab09e78e8d..f07e38094b40 100644 --- a/Documentation/trace/coresight-cpu-debug.txt +++ b/Documentation/trace/coresight-cpu-debug.txt @@ -165,7 +165,7 @@ Do some work... The same can also be done from an application program. Disable specific CPU's specific idle state from cpuidle sysfs (see -Documentation/cpuidle/sysfs.txt): +Documentation/admin-guide/pm/cpuidle.rst): # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index f82434f2795e..0131df7f5968 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -24,13 +24,13 @@ It can be used for debugging or analyzing latencies and performance issues that take place outside of user-space. Although ftrace is typically considered the function tracer, it -is really a frame work of several assorted tracing utilities. +is really a framework of several assorted tracing utilities. There's latency tracing to examine what occurs between interrupts disabled and enabled, as well as for preemption and from a time a task is woken to the task is actually scheduled in. One of the most common uses of ftrace is the event tracing. -Through out the kernel is hundreds of static event points that +Throughout the kernel is hundreds of static event points that can be enabled via the tracefs file system to see what is going on in certain parts of the kernel. @@ -462,7 +462,7 @@ of ftrace. Here is a list of some of the key files: mono_raw: This is the raw monotonic clock (CLOCK_MONOTONIC_RAW) - which is montonic but is not subject to any rate adjustments + which is monotonic but is not subject to any rate adjustments and ticks at the same rate as the hardware clocksource. boot: @@ -914,8 +914,8 @@ The above is mostly meaningful for kernel developers. current trace and the next trace. - '$' - greater than 1 second - - '@' - greater than 100 milisecond - - '*' - greater than 10 milisecond + - '@' - greater than 100 millisecond + - '*' - greater than 10 millisecond - '#' - greater than 1000 microsecond - '!' - greater than 100 microsecond - '+' - greater than 10 microsecond @@ -2541,7 +2541,7 @@ At compile time every C file object is run through the recordmcount program (located in the scripts directory). This program will parse the ELF headers in the C object to find all the locations in the .text section that call mcount. Starting -with gcc verson 4.6, the -mfentry has been added for x86, which +with gcc version 4.6, the -mfentry has been added for x86, which calls "__fentry__" instead of "mcount". Which is called before the creation of the stack frame. @@ -2978,7 +2978,7 @@ The following commands are supported: When the function is hit, it will dump the contents of the ftrace ring buffer to the console. This is useful if you need to debug something, and want to dump the trace when a certain function - is hit. Perhaps its a function that is called before a tripple + is hit. Perhaps it's a function that is called before a triple fault happens and does not allow you to get a regular dump. - cpudump: diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 306997941ba1..6b4107cf4b98 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -22,3 +22,4 @@ Linux Tracing Technologies hwlat_detector intel_th stm + sys-t diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst index 8bfc75c90806..235ce2ab131a 100644 --- a/Documentation/trace/kprobetrace.rst +++ b/Documentation/trace/kprobetrace.rst @@ -20,6 +20,9 @@ current_tracer. Instead of that, add probe points via /sys/kernel/debug/tracing/kprobe_events, and enable it via /sys/kernel/debug/tracing/events/kprobes/<EVENT>/enable. +You can also use /sys/kernel/debug/tracing/dynamic_events instead of +kprobe_events. That interface will provide unified access to other +dynamic events too. Synopsis of kprobe_events ------------------------- @@ -45,16 +48,18 @@ Synopsis of kprobe_events @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol) $stackN : Fetch Nth entry of stack (N >= 0) $stack : Fetch stack address. - $retval : Fetch return value.(*) + $argN : Fetch the Nth function argument. (N >= 1) (\*1) + $retval : Fetch return value.(\*2) $comm : Fetch current task comm. - +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(**) + +|-offs(FETCHARG) : Fetch memory at FETCHARG +|- offs address.(\*3) NAME=FETCHARG : Set NAME as the argument name of FETCHARG. FETCHARG:TYPE : Set TYPE as the type of FETCHARG. Currently, basic types (u8/u16/u32/u64/s8/s16/s32/s64), hexadecimal types (x8/x16/x32/x64), "string" and bitfield are supported. - (*) only for return probe. - (**) this is useful for fetching a field of data structures. + (\*1) only for the probe on function entry (offs == 0). + (\*2) only for return probe. + (\*3) this is useful for fetching a field of data structures. Types ----- @@ -64,14 +69,27 @@ respectively. 'x' prefix implies it is unsigned. Traced arguments are shown in decimal ('s' and 'u') or hexadecimal ('x'). Without type casting, 'x32' or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and x86-64 uses x64). +These value types can be an array. To record array data, you can add '[N]' +(where N is a fixed number, less than 64) to the base type. +E.g. 'x16[4]' means an array of x16 (2bytes hex) with 4 elements. +Note that the array can be applied to memory type fetchargs, you can not +apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is +wrong, but '+8($stack):x8[8]' is OK.) String type is a special type, which fetches a "null-terminated" string from kernel space. This means it will fail and store NULL if the string container has been paged out. +The string array type is a bit different from other types. For other base +types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same +as +0(%di):x32.) But string[1] is not equal to string. The string type itself +represents "char array", but string array type represents "char * array". +So, for example, +0(%di):string[1] is equal to +0(+0(%di)):string. Bitfield is another special type, which takes 3 parameters, bit-width, bit- offset, and container-size (usually 32). The syntax is:: b<bit-width>@<bit-offset>/<container-size> +Symbol type('symbol') is an alias of u32 or u64 type (depends on BITS_PER_LONG) +which shows given pointer in "symbol+offset" style. For $comm, the default type is "string"; any other type is invalid. diff --git a/Documentation/trace/stm.rst b/Documentation/trace/stm.rst index 2c22ddb7fd3e..99f99963e5e7 100644 --- a/Documentation/trace/stm.rst +++ b/Documentation/trace/stm.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + =================== System Trace Module =================== @@ -53,12 +55,30 @@ under "user" directory from the example above and this new rule will be used for trace sources with the id string of "user/dummy". Trace sources have to open the stm class device's node and write their -trace data into its file descriptor. In order to identify themselves -to the policy, they need to do a STP_POLICY_ID_SET ioctl on this file -descriptor providing their id string. Otherwise, they will be -automatically allocated a master/channel pair upon first write to this -file descriptor according to the "default" rule of the policy, if such -exists. +trace data into its file descriptor. + +In order to find an appropriate policy node for a given trace source, +several mechanisms can be used. First, a trace source can explicitly +identify itself by calling an STP_POLICY_ID_SET ioctl on the character +device's file descriptor, providing their id string, before they write +any data there. Secondly, if they chose not to perform the explicit +identification (because you may not want to patch existing software +to do this), they can just start writing the data, at which point the +stm core will try to find a policy node with the name matching the +task's name (e.g., "syslogd") and if one exists, it will be used. +Thirdly, if the task name can't be found among the policy nodes, the +catch-all entry "default" will be used, if it exists. This entry also +needs to be created and configured by the system administrator or +whatever tools are taking care of the policy configuration. Finally, +if all the above steps failed, the write() to an stm file descriptor +will return a error (EINVAL). + +Previously, if no policy nodes were found for a trace source, the stm +class would silently fall back to allocating the first available +contiguous range of master/channels from the beginning of the device's +master/channel range. The new requirement for a policy node to exist +will help programmers and sysadmins identify gaps in configuration +and have better control over the un-identified sources. Some STM devices may allow direct mapping of the channel mmio regions to userspace for zero-copy writing. One mappable page (in terms of @@ -92,9 +112,9 @@ allocated for the device according to the policy configuration. If there's a node in the root of the policy directory that matches the stm_source device's name (for example, "console"), this node will be used to allocate master and channel numbers. If there's no such policy -node, the stm core will pick the first contiguous chunk of channels -within the first available master. Note that the node must exist -before the stm_source device is connected to its stm device. +node, the stm core will use the catch-all entry "default", if one +exists. If neither policy nodes exist, the write() to stm_source_link +will return an error. stm_console =========== diff --git a/Documentation/trace/sys-t.rst b/Documentation/trace/sys-t.rst new file mode 100644 index 000000000000..3d8eb92735e9 --- /dev/null +++ b/Documentation/trace/sys-t.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================== +MIPI SyS-T over STP +=================== + +The MIPI SyS-T protocol driver can be used with STM class devices to +generate standardized trace stream. Aside from being a standard, it +provides better trace source identification and timestamp correlation. + +In order to use the MIPI SyS-T protocol driver with your STM device, +first, you'll need CONFIG_STM_PROTO_SYS_T. + +Now, you can select which protocol driver you want to use when you create +a policy for your STM device, by specifying it in the policy name: + +# mkdir /config/stp-policy/dummy_stm.0:p_sys-t.my-policy/ + +In other words, the policy name format is extended like this: + + <device_name>:<protocol_name>.<policy_name> + +With Intel TH, therefore it can look like "0-sth:p_sys-t.my-policy". + +If the protocol name is omitted, the STM class will chose whichever +protocol driver was loaded first. + +You can also double check that everything is working as expected by + +# cat /config/stp-policy/dummy_stm.0:p_sys-t.my-policy/protocol +p_sys-t + +Now, with the MIPI SyS-T protocol driver, each policy node in the +configfs gets a few additional attributes, which determine per-source +parameters specific to the protocol: + +# mkdir /config/stp-policy/dummy_stm.0:p_sys-t.my-policy/default +# ls /config/stp-policy/dummy_stm.0:p_sys-t.my-policy/default +channels +clocksync_interval +do_len +masters +ts_interval +uuid + +The most important one here is the "uuid", which determines the UUID +that will be used to tag all data coming from this source. It is +automatically generated when a new node is created, but it is likely +that you would want to change it. + +do_len switches on/off the additional "payload length" field in the +MIPI SyS-T message header. It is off by default as the STP already +marks message boundaries. + +ts_interval and clocksync_interval determine how much time in milliseconds +can pass before we need to include a protocol (not transport, aka STP) +timestamp in a message header or send a CLOCKSYNC packet, respectively. + +See Documentation/ABI/testing/configfs-stp-policy-p_sys-t for more +details. + +* [1] https://www.mipi.org/specifications/sys-t diff --git a/Documentation/trace/uprobetracer.rst b/Documentation/trace/uprobetracer.rst index d0822811527a..4c3bfde2ba47 100644 --- a/Documentation/trace/uprobetracer.rst +++ b/Documentation/trace/uprobetracer.rst @@ -18,6 +18,10 @@ current_tracer. Instead of that, add probe points via However unlike kprobe-event tracer, the uprobe event interface expects the user to calculate the offset of the probepoint in the object. +You can also use /sys/kernel/debug/tracing/dynamic_events instead of +uprobe_events. That interface will provide unified access to other +dynamic events too. + Synopsis of uprobe_tracer ------------------------- :: diff --git a/Documentation/translations/it_IT/admin-guide/README.rst b/Documentation/translations/it_IT/admin-guide/README.rst new file mode 100644 index 000000000000..b37166817842 --- /dev/null +++ b/Documentation/translations/it_IT/admin-guide/README.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/admin-guide/README.rst <readme>` + +.. _it_readme: + +Rilascio del kernel Linux 5.x <http://kernel.org/> +=================================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/admin-guide/security-bugs.rst b/Documentation/translations/it_IT/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..18a5822c7d9a --- /dev/null +++ b/Documentation/translations/it_IT/admin-guide/security-bugs.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + +.. _it_securitybugs: + +Bachi di sicurezza +================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index 2bf1c1e2f394..a4ecd8f27631 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -107,7 +107,7 @@ macro simil-funzioni è il seguente:: * Context: Describes whether the function can sleep, what locks it takes, * releases, or expects to be held. It can extend over multiple * lines. - * Return: Describe the return value of foobar. + * Return: Describe the return value of function_name. * * The return value description can also have multiple paragraphs, and should * be placed at the end of the comment block. diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index 898a7823a6f4..ea9b2916b3e4 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -86,6 +86,7 @@ vostre modifiche molto più semplice .. toctree:: :maxdepth: 2 + process/index doc-guide/index kernel-hacking/index diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst index 753643622c23..0ef31666663b 100644 --- a/Documentation/translations/it_IT/kernel-hacking/locking.rst +++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst @@ -593,8 +593,8 @@ l'opzione ``GFP_KERNEL`` che è permessa solo in contesto utente. Ho supposto che :c:func:`cache_add()` venga chiamata dal contesto utente, altrimenti questa opzione deve diventare un parametro di :c:func:`cache_add()`. -Exposing Objects Outside This File ----------------------------------- +Esporre gli oggetti al di fuori del file +---------------------------------------- Se i vostri oggetti contengono più informazioni, potrebbe non essere sufficiente copiare i dati avanti e indietro: per esempio, altre parti del diff --git a/Documentation/translations/it_IT/process/1.Intro.rst b/Documentation/translations/it_IT/process/1.Intro.rst new file mode 100644 index 000000000000..c1be6dc398a7 --- /dev/null +++ b/Documentation/translations/it_IT/process/1.Intro.rst @@ -0,0 +1,297 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/1.Intro.rst <development_process_intro>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_intro: + +Introduzione +============ + +Riepilogo generale +------------------ + +Il resto di questa sezione riguarda il processo di sviluppo del kernel e +quella sorta di frustrazione che gli sviluppatori e i loro datori di lavoro +potrebbero dover affrontare. Ci sono molte ragioni per le quali del codice +per il kernel debba essere incorporato nel kernel ufficiale, fra le quali: +disponibilità immediata agli utilizzatori, supporto della comunità in +differenti modalità, e la capacità di influenzare la direzione dello sviluppo +del kernel. +Il codice che contribuisce al kernel Linux deve essere reso disponibile sotto +una licenza GPL-compatibile. + +La sezione :ref:`it_development_process` introduce il processo di sviluppo, +il ciclo di rilascio del kernel, ed i meccanismi della finestra +d'incorporazione. Il capitolo copre le varie fasi di una modifica: sviluppo, +revisione e ciclo d'incorporazione. Ci sono alcuni dibattiti su strumenti e +liste di discussione. Gli sviluppatori che sono in attesa di poter sviluppare +qualcosa per il kernel sono invitati ad individuare e sistemare bachi come +esercizio iniziale. + +La sezione :ref:`it_development_early_stage` copre i primi stadi della +pianificazione di un progetto di sviluppo, con particolare enfasi sul +coinvolgimento della comunità, il prima possibile. + +La sezione :ref:`it_development_coding` riguarda il processo di scrittura +del codice. Qui, sono esposte le diverse insidie che sono state già affrontate +da altri sviluppatori. Il capitolo copre anche alcuni dei requisiti per le +modifiche, ed esiste un'introduzione ad alcuni strumenti che possono aiutarvi +nell'assicurarvi che le modifiche per il kernel siano corrette. + +La sezione :ref:`it_development_posting` parla del processo di pubblicazione +delle modifiche per la revisione. Per essere prese in considerazione dalla +comunità di sviluppo, le modifiche devono essere propriamente formattate ed +esposte, e devono essere inviate nel posto giusto. Seguire i consigli presenti +in questa sezione dovrebbe essere d'aiuto nell'assicurare la migliore +accoglienza possibile del vostro lavoro. + +La sezione :ref:`it_development_followthrough` copre ciò che accade dopo +la pubblicazione delle modifiche; a questo punto il lavoro è lontano +dall'essere concluso. Lavorare con i revisori è una parte cruciale del +processo di sviluppo; questa sezione offre una serie di consigli su come +evitare problemi in questa importante fase. Gli sviluppatori sono diffidenti +nell'affermare che il lavoro è concluso quando una modifica è incorporata nei +sorgenti principali. + +La sezione :ref:`it_development_advancedtopics` introduce un paio di argomenti +"avanzati": gestire le modifiche con git e controllare le modifiche pubblicate +da altri. + +La sezione :ref:`it_development_conclusion` chiude il documento con dei +riferimenti ad altre fonti che forniscono ulteriori informazioni sullo sviluppo +del kernel. + +Di cosa parla questo documento +------------------------------ + +Il kernel Linux, ha oltre 8 milioni di linee di codice e ben oltre 1000 +contributori ad ogni rilascio; è uno dei più vasti e più attivi software +liberi progettati mai esistiti. Sin dal sul modesto inizio nel 1991, +questo kernel si è evoluto nel miglior componente per sistemi operativi +che fanno funzionare piccoli riproduttori musicali, PC, grandi super computer +e tutte le altre tipologie di sistemi fra questi estremi. È una soluzione +robusta, efficiente ed adattabile a praticamente qualsiasi situazione. + +Con la crescita di Linux è arrivato anche un aumento di sviluppatori +(ed aziende) desiderosi di partecipare a questo sviluppo. I produttori di +hardware vogliono assicurarsi che il loro prodotti siano supportati da Linux, +rendendo questi prodotti attrattivi agli utenti Linux. I produttori di +sistemi integrati, che usano Linux come componente di un prodotto integrato, +vogliono che Linux sia capace ed adeguato agli obiettivi ed il più possibile +alla mano. Fornitori ed altri produttori di software che basano i propri +prodotti su Linux hanno un chiaro interesse verso capacità, prestazioni ed +affidabilità del kernel Linux. E gli utenti finali, anche, spesso vorrebbero +cambiare Linux per renderlo più aderente alle proprie necessità. + +Una delle caratteristiche più coinvolgenti di Linux è quella dell'accessibilità +per gli sviluppatori; chiunque con le capacità richieste può migliorare +Linux ed influenzarne la direzione di sviluppo. Prodotti non open-source non +possono offrire questo tipo di apertura, che è una caratteristica del software +libero. Ma, anzi, il kernel è persino più aperto rispetto a molti altri +progetti di software libero. Un classico ciclo di sviluppo trimestrale può +coinvolgere 1000 sviluppatori che lavorano per più di 100 differenti aziende +(o per nessuna azienda). + +Lavorare con la comunità di sviluppo del kernel non è particolarmente +difficile. Ma, ciononostante, diversi potenziali contributori hanno trovato +delle difficoltà quando hanno cercato di lavorare sul kernel. La comunità del +kernel utilizza un proprio modo di operare che gli permette di funzionare +agevolmente (e genera un prodotto di alta qualità) in un ambiente dove migliaia +di stringhe di codice sono modificate ogni giorni. Quindi non deve sorprendere +che il processo di sviluppo del kernel differisca notevolmente dai metodi di +sviluppo privati. + +Il processo di sviluppo del Kernel può, dall'altro lato, risultare +intimidatorio e strano ai nuovi sviluppatori, ma ha dietro di se buone ragioni +e solide esperienze. Uno sviluppatore che non comprende i modi della comunità +del kernel (o, peggio, che cerchi di aggirarli o violarli) avrà un'esperienza +deludente nel proprio bagaglio. La comunità di sviluppo, sebbene sia utile +a coloro che cercano di imparare, ha poco tempo da dedicare a coloro che non +ascoltano o coloro che non sono interessati al processo di sviluppo. + +Si spera che coloro che leggono questo documento saranno in grado di evitare +queste esperienze spiacevoli. C'è molto materiale qui, ma lo sforzo della +lettura sarà ripagato in breve tempo. La comunità di sviluppo ha sempre +bisogno di sviluppatori che vogliano aiutare a rendere il kernel migliore; +il testo seguente potrebbe esservi d'aiuto - o essere d'aiuto ai vostri +collaboratori- per entrare a far parte della nostra comunità. + +Crediti +------- + +Questo documento è stato scritto da Jonathan Corbet, corbet@lwn.net. +È stato migliorato da Johannes Berg, James Berry, Alex Chiang, Roland +Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, +Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata e Jochen Voß. + +Questo lavoro è stato supportato dalla Linux Foundation; un ringraziamento +speciale ad Amanda McPherson, che ha visto il valore di questo lavoro e lo ha +reso possibile. + +L'importanza d'avere il codice nei sorgenti principali +------------------------------------------------------ + +Alcune aziende e sviluppatori ogni tanto si domandano perché dovrebbero +preoccuparsi di apprendere come lavorare con la comunità del kernel e di +inserire il loro codice nel ramo di sviluppo principale (per ramo principale +s'intende quello mantenuto da Linus Torvalds e usato come base dai +distributori Linux). Nel breve termine, contribuire al codice può sembrare +un costo inutile; può sembra più facile tenere separato il proprio codice e +supportare direttamente i suoi utilizzatori. La verità è che il tenere il +codice separato ("fuori dai sorgenti", *"out-of-tree"*) è un falso risparmio. + +Per dimostrare i costi di un codice "fuori dai sorgenti", eccovi +alcuni aspetti rilevanti del processo di sviluppo kernel; la maggior parte +di essi saranno approfonditi dettagliatamente più avanti in questo documento. +Considerate: + +- Il codice che è stato inserito nel ramo principale del kernel è disponibile + a tutti gli utilizzatori Linux. Sarà automaticamente presente in tutte le + distribuzioni che lo consentono. Non c'è bisogno di: driver per dischi, + scaricare file, o della scocciatura del dover supportare diverse versioni di + diverse distribuzioni; funziona già tutto, per gli sviluppatori e per gli + utilizzatori. L'inserimento nel ramo principale risolve un gran numero di + problemi di distribuzione e di supporto. + +- Nonostante gli sviluppatori kernel si sforzino di tenere stabile + l'interfaccia dello spazio utente, quella interna al kernel è in continuo + cambiamento. La mancanza di un'interfaccia interna è deliberatamente una + decisione di progettazione; ciò permette che i miglioramenti fondamentali + vengano fatti in un qualsiasi momento e che risultino fatti con un codice di + alta qualità. Ma una delle conseguenze di questa politica è che qualsiasi + codice "fuori dai sorgenti" richiede costante manutenzione per renderlo + funzionante coi kernel più recenti. Tenere un codice "fuori dai sorgenti" + richiede una mole di lavoro significativa solo per farlo funzionare. + + Invece, il codice che si trova nel ramo principale non necessita di questo + tipo di lavoro poiché ad ogni sviluppatore che faccia una modifica alle + interfacce viene richiesto di sistemare anche il codice che utilizza + quell'interfaccia. Quindi, il codice che è stato inserito nel ramo principale + ha dei costi di mantenimento significativamente più bassi. + +- Oltre a ciò, spesso il codice che è all'interno del kernel sarà migliorato da + altri sviluppatori. Dare pieni poteri alla vostra comunità di utenti e ai + clienti può portare a sorprendenti risultati che migliorano i vostri + prodotti. + +- Il codice kernel è soggetto a revisioni, sia prima che dopo l'inserimento + nel ramo principale. Non importa quanto forti fossero le abilità dello + sviluppatore originale, il processo di revisione troverà il modo di migliore + il codice. Spesso la revisione trova bachi importanti e problemi di + sicurezza. Questo è particolarmente vero per il codice che è stato + sviluppato in un ambiente chiuso; tale codice ottiene un forte beneficio + dalle revisioni provenienti da sviluppatori esteri. Il codice + "fuori dai sorgenti", invece, è un codice di bassa qualità. + +- La partecipazione al processo di sviluppo costituisce la vostra via per + influenzare la direzione di sviluppo del kernel. Gli utilizzatori che + "reclamano da bordo campo" sono ascoltati, ma gli sviluppatori attivi + hanno una voce più forte - e la capacità di implementare modifiche che + renderanno il kernel più funzionale alle loro necessità. + +- Quando il codice è gestito separatamente, esiste sempre la possibilità che + terze parti contribuiscano con una differente implementazione che fornisce + le stesse funzionalità. Se dovesse accadere, l'inserimento del codice + diventerà molto più difficile - fino all'impossibilità. Poi, dovrete far + fronte a delle alternative poco piacevoli, come: (1) mantenere un elemento + non standard "fuori dai sorgenti" per un tempo indefinito, o (2) abbandonare + il codice e far migrare i vostri utenti alla versione "nei sorgenti". + +- Contribuire al codice è l'azione fondamentale che fa funzionare tutto il + processo. Contribuendo attraverso il vostro codice potete aggiungere nuove + funzioni al kernel e fornire competenze ed esempi che saranno utili ad + altri sviluppatori. Se avete sviluppato del codice Linux (o state pensando + di farlo), avete chiaramente interesse nel far proseguire il successo di + questa piattaforma. Contribuire al codice è une delle migliori vie per + aiutarne il successo. + +Il ragionamento sopra citato si applica ad ogni codice "fuori dai sorgenti" +dal kernel, incluso il codice proprietario distribuito solamente in formato +binario. Ci sono, comunque, dei fattori aggiuntivi che dovrebbero essere +tenuti in conto prima di prendere in considerazione qualsiasi tipo di +distribuzione binaria di codice kernel. Questo include che: + +- Le questioni legali legate alla distribuzione di moduli kernel proprietari + sono molto nebbiose; parecchi detentori di copyright sul kernel credono che + molti moduli binari siano prodotti derivati del kernel e che, come risultato, + la loro diffusione sia una violazione della licenza generale di GNU (della + quale si parlerà più avanti). L'autore qui non è un avvocato, e + niente in questo documento può essere considerato come un consiglio legale. + Il vero stato legale dei moduli proprietari può essere determinato + esclusivamente da un giudice. Ma l'incertezza che perseguita quei moduli + è lì comunque. + +- I moduli binari aumentano di molto la difficoltà di fare debugging del + kernel, al punto che la maggior parte degli sviluppatori del kernel non + vorranno nemmeno tentare. Quindi la diffusione di moduli esclusivamente + binari renderà difficile ai vostri utilizzatori trovare un supporto dalla + comunità. + +- Il supporto è anche difficile per i distributori di moduli binari che devono + fornire una versione del modulo per ogni distribuzione e per ogni versione + del kernel che vogliono supportate. Per fornire una copertura ragionevole e + comprensiva, può essere richiesto di produrre dozzine di singoli moduli. + E inoltre i vostri utilizzatori dovranno aggiornare il vostro modulo + separatamente ogni volta che aggiornano il loro kernel. + +- Tutto ciò che è stato detto prima riguardo alla revisione del codice si + applica doppiamente al codice proprietario. Dato che questo codice non è + del tutto disponibile, non può essere revisionato dalla comunità e avrà, + senza dubbio, seri problemi. + +I produttori di sistemi integrati, in particolare, potrebbero esser tentati +dall'evitare molto di ciò che è stato detto in questa sezione, credendo che +stiano distribuendo un prodotto finito che utilizza una versione del kernel +immutabile e che non richiede un ulteriore sviluppo dopo il rilascio. Questa +idea non comprende il valore di una vasta revisione del codice e il valore +del permettere ai propri utenti di aggiungere funzionalità al vostro prodotto. +Ma anche questi prodotti, hanno una vita commerciale limitata, dopo la quale +deve essere rilasciata una nuova versione. A quel punto, i produttori il cui +codice è nel ramo principale di sviluppo avranno un codice ben mantenuto e +saranno in una posizione migliore per ottenere velocemente un nuovo prodotto +pronto per essere distribuito. + + +Licenza +------- + +IL codice Linux utilizza diverse licenze, ma il codice completo deve essere +compatibile con la seconda versione della licenza GNU General Public License +(GPLv2), che è la licenza che copre la distribuzione del kernel. +Nella pratica, ciò significa che tutti i contributi al codice sono coperti +anche'essi dalla GPLv2 (con, opzionalmente, una dicitura che permette la +possibilità di distribuirlo con licenze più recenti di GPL) o dalla licenza +three-clause BSD. Qualsiasi contributo che non è coperto da una licenza +compatibile non verrà accettata nel kernel. + +Per il codice sottomesso al kernel non è necessario (o richiesto) la +concessione del Copyright. Tutto il codice inserito nel ramo principale del +kernel conserva la sua proprietà originale; ne risulta che ora il kernel abbia +migliaia di proprietari. + +Una conseguenza di questa organizzazione della proprietà è che qualsiasi +tentativo di modifica della licenza del kernel è destinata ad un quasi sicuro +fallimento. Esistono alcuni scenari pratici nei quali il consenso di tutti +i detentori di copyright può essere ottenuto (o il loro codice verrà rimosso +dal kernel). Quindi, in sostanza, non esiste la possibilità che si giunga ad +una versione 3 della licenza GPL nel prossimo futuro. + +È imperativo che tutto il codice che contribuisce al kernel sia legittimamente +software libero. Per questa ragione, un codice proveniente da un contributore +anonimo (o sotto pseudonimo) non verrà accettato. È richiesto a tutti i +contributori di firmare il proprio codice, attestando così che quest'ultimo +può essere distribuito insieme al kernel sotto la licenza GPL. Il codice che +non è stato licenziato come software libero dal proprio creatore, o che +potrebbe creare problemi di copyright per il kernel (come il codice derivante +da processi di ingegneria inversa senza le opportune tutele), non può essere +diffuso. + +Domande relative a questioni legate al copyright sono frequenti nelle liste +di discussione dedicate allo sviluppo di Linux. Tali quesiti, normalmente, +non riceveranno alcuna risposta, ma una cosa deve essere tenuta presente: +le persone che risponderanno a quelle domande non sono avvocati e non possono +fornire supporti legali. Se avete questioni legali relative ai sorgenti +del codice Linux, non esiste alternativa che quella di parlare con un +avvocato esperto nel settore. Fare affidamento sulle risposte ottenute da +una lista di discussione tecnica è rischioso. diff --git a/Documentation/translations/it_IT/process/2.Process.rst b/Documentation/translations/it_IT/process/2.Process.rst new file mode 100644 index 000000000000..9af4d01617c4 --- /dev/null +++ b/Documentation/translations/it_IT/process/2.Process.rst @@ -0,0 +1,531 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/2.Process.rst <development_process>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_process: + +Come funziona il processo di sviluppo +===================================== + +Lo sviluppo del Kernel agli inizi degli anno '90 era abbastanza libero, con +un numero di utenti e sviluppatori relativamente basso. Con una base +di milioni di utenti e con 2000 sviluppatori coinvolti nel giro di un anno, +il kernel da allora ha messo in atto un certo numero di procedure per rendere +lo sviluppo più agevole. È richiesta una solida conoscenza di come tale +processo si svolge per poter esserne parte attiva. + +Il quadro d'insieme +------------------- + +Gli sviluppatori kernel utilizzano un calendario di rilascio generico, dove +ogni due o tre mesi viene effettuata un rilascio importante del kernel. +I rilasci più recenti sono stati: + + ====== ================= + 4.11 Aprile 30, 2017 + 4.12 Luglio 2, 2017 + 4.13 Settembre 3, 2017 + 4.14 Novembre 12, 2017 + 4.15 Gennaio 28, 2018 + 4.16 Aprile 1, 2018 + ====== ================= + +Ciascun rilascio 4.x è un importante rilascio del kernel con nuove +funzionalità, modifiche interne dell'API, e molto altro. Un tipico +rilascio 4.x contiene quasi 13,000 gruppi di modifiche con ulteriori +modifiche a parecchie migliaia di linee di codice. La 4.x. è pertanto la +linea di confine nello sviluppo del kernel Linux; il kernel utilizza un sistema +di sviluppo continuo che integra costantemente nuove importanti modifiche. + +Viene seguita una disciplina abbastanza lineare per l'inclusione delle +patch di ogni rilascio. All'inizio di ogni ciclo di sviluppo, la +"finestra di inclusione" viene dichiarata aperta. In quel momento il codice +ritenuto sufficientemente stabile(e che è accettato dalla comunità di sviluppo) +viene incluso nel ramo principale del kernel. La maggior parte delle +patch per un nuovo ciclo di sviluppo (e tutte le più importanti modifiche) +saranno inserite durante questo periodo, ad un ritmo che si attesta sulle +1000 modifiche ("patch" o "gruppo di modifiche") al giorno. + +(per inciso, vale la pena notare che i cambiamenti integrati durante la +"finestra di inclusione" non escono dal nulla; questi infatti, sono stati +raccolti e, verificati in anticipo. Il funzionamento di tale procedimento +verrà descritto dettagliatamente più avanti). + +La finestra di inclusione resta attiva approssimativamente per due settimane. +Al termine di questo periodo, Linus Torvald dichiarerà che la finestra è +chiusa e rilascerà il primo degli "rc" del kernel. +Per il kernel che è destinato ad essere 2.6.40, per esempio, il rilascio +che emerge al termine della finestra d'inclusione si chiamerà 2.6.40-rc1. +Questo rilascio indica che il momento di aggiungere nuovi componenti è +passato, e che è iniziato il periodo di stabilizzazione del prossimo kernel. + +Nelle successive sei/dieci settimane, potranno essere sottoposte solo modifiche +che vanno a risolvere delle problematiche. Occasionalmente potrà essere +consentita una modifica più consistente, ma tali occasioni sono rare. +Gli sviluppatori che tenteranno di aggiungere nuovi elementi al di fuori della +finestra di inclusione, tendenzialmente, riceveranno un accoglienza poco +amichevole. Come regola generale: se vi perdete la finestra di inclusione per +un dato componente, la cosa migliore da fare è aspettare il ciclo di sviluppo +successivo (un'eccezione può essere fatta per i driver per hardware non +supportati in precedenza; se toccano codice non facente parte di quello +attuale, che non causino regressioni e che potrebbero essere aggiunti in +sicurezza in un qualsiasi momento) + +Mentre le correzioni si aprono la loro strada all'interno del ramo principale, +il ritmo delle modifiche rallenta col tempo. Linus rilascia un nuovo +kernel -rc circa una volta alla settimana; e ne usciranno circa 6 o 9 prima +che il kernel venga considerato sufficientemente stabile e che il rilascio +finale 2.6.x venga fatto. A quel punto tutto il processo ricomincerà. + +Esempio: ecco com'è andato il ciclo di sviluppo della versione 4.16 +(tutte le date si collocano nel 2018) + + + ============== ======================================= + Gennaio 28 4.15 rilascio stabile + Febbraio 11 4.16-rc1, finestra di inclusione chiusa + Febbraio 18 4.16-rc2 + Febbraio 25 4.16-rc3 + Marzo 4 4.16-rc4 + Marzo 11 4.16-rc5 + Marzo 18 4.16-rc6 + Marzo 25 4.16-rc7 + Aprile 1 4.17 rilascio stabile + ============== ======================================= + +In che modo gli sviluppatori decidono quando chiudere il ciclo di sviluppo e +creare quindi una rilascio stabile? Un metro valido è il numero di regressioni +rilevate nel precedente rilascio. Nessun baco è il benvenuto, ma quelli che +procurano problemi su sistemi che hanno funzionato in passato sono considerati +particolarmente seri. Per questa ragione, le modifiche che portano ad una +regressione sono viste sfavorevolmente e verranno quasi sicuramente annullate +durante il periodo di stabilizzazione. + +L'obiettivo degli sviluppatori è quello di aggiustare tutte le regressioni +conosciute prima che avvenga il rilascio stabile. Nel mondo reale, questo +tipo di perfezione difficilmente viene raggiunta; esistono troppe variabili +in un progetto di questa portata. Arriva un punto dove ritardare il rilascio +finale peggiora la situazione; la quantità di modifiche in attesa della +prossima finestra di inclusione crescerà enormemente, creando ancor più +regressioni al giro successivo. Quindi molti kernel 4.x escono con una +manciata di regressioni delle quali, si spera, nessuna è grave. + +Una volta che un rilascio stabile è fatto, il suo costante mantenimento è +affidato al "squadra stabilità", attualmente composta da Greg Kroah-Hartman. +Questa squadra rilascia occasionalmente degli aggiornamenti relativi al +rilascio stabile usando la numerazione 4.x.y. Per essere presa in +considerazione per un rilascio d'aggiornamento, una modifica deve: +(1) correggere un baco importante (2) essere già inserita nel ramo principale +per il prossimo sviluppo del kernel. Solitamente, passato il loro rilascio +iniziale, i kernel ricevono aggiornamenti per più di un ciclo di sviluppo. +Quindi, per esempio, la storia del kernel 4.13 appare così: + + ============== =============================== + Settembre 3 4.13 rilascio stabile + Settembre 13 4.13.1 + Settembre 20 4.13.2 + Settembre 27 4.13.3 + Ottobre 5 4.13.4 + Ottobre 12 4.13.5 + ... ... + Novembre 24 4.13.16 + ============== =============================== + +La 4.13.16 fu l'aggiornamento finale per la versione 4.13. + +Alcuni kernel sono destinati ad essere kernel a "lungo termine"; questi +riceveranno assistenza per un lungo periodo di tempo. Al momento in cui +scriviamo, i manutentori dei kernel stabili a lungo termine sono: + + ====== ====================== ========================================== + 3.16 Ben Hutchings (kernel stabile molto più a lungo termine) + 4.1 Sasha Levin + 4.4 Greg Kroah-Hartman (kernel stabile molto più a lungo termine) + 4.9 Greg Kroah-Hartman + 4.14 Greg Kroah-Hartman + ====== ====================== ========================================== + + +Questa selezione di kernel di lungo periodo sono puramente dovuti ai loro +manutentori, alla loro necessità e al tempo per tenere aggiornate proprio +quelle versioni. Non ci sono altri kernel a lungo termine in programma per +alcun rilascio in arrivo. + +Il ciclo di vita di una patch +----------------------------- + +Le patch non passano direttamente dalla tastiera dello sviluppatori +al ramo principale del kernel. Esiste, invece, una procedura disegnata +per assicurare che ogni patch sia di buona qualità e desiderata nel +ramo principale. Questo processo avviene velocemente per le correzioni +meno importanti, o, nel caso di patch ampie e controverse, va avanti per anni. +Per uno sviluppatore la maggior frustrazione viene dalla mancanza di +comprensione di questo processo o dai tentativi di aggirarlo. + +Nella speranza di ridurre questa frustrazione, questo documento spiegherà +come una patch viene inserita nel kernel. Ciò che segue è un'introduzione +che descrive il processo ideale. Approfondimenti verranno invece trattati +più avanti. + +Una patch attraversa, generalmente, le seguenti fasi: + + - Progetto. In questa fase sono stabilite quelli che sono i requisiti + della modifica - e come verranno soddisfatti. Il lavoro di progettazione + viene spesso svolto senza coinvolgere la comunità, ma è meglio renderlo + il più aperto possibile; questo può far risparmiare molto tempo evitando + eventuali riprogettazioni successive. + + - Prima revisione. Le patch vengono pubblicate sulle liste di discussione + interessate, e gli sviluppatori in quella lista risponderanno coi loro + commenti. Se si svolge correttamente, questo procedimento potrebbe far + emergere problemi rilevanti in una patch. + + - Revisione più ampia. Quando la patch è quasi pronta per essere inserita + nel ramo principale, un manutentore importante del sottosistema dovrebbe + accettarla - anche se, questa accettazione non è una garanzia che la + patch arriverà nel ramo principale. La patch sarà visibile nei sorgenti + del sottosistema in questione e nei sorgenti -next (descritti sotto). + Quando il processo va a buon fine, questo passo porta ad una revisione + più estesa della patch e alla scoperta di problemi d'integrazione + con il lavoro altrui. + +- Per favore, tenete da conto che la maggior parte dei manutentori ha + anche un lavoro quotidiano, quindi integrare le vostre patch potrebbe + non essere la loro priorità più alta. Se una vostra patch riceve + dei suggerimenti su dei cambiamenti necessari, dovreste applicare + quei cambiamenti o giustificare perché non sono necessari. Se la vostra + patch non riceve alcuna critica ma non è stata integrata dal + manutentore del driver o sottosistema, allora dovreste continuare con + i necessari aggiornamenti per mantenere la patch aggiornata al kernel + più recente cosicché questa possa integrarsi senza problemi; continuate + ad inviare gli aggiornamenti per essere revisionati e integrati. + + - Inclusione nel ramo principale. Eventualmente, una buona patch verrà + inserita all'interno nel repositorio principale, gestito da + Linus Torvalds. In questa fase potrebbero emergere nuovi problemi e/o + commenti; è importante che lo sviluppatore sia collaborativo e che sistemi + ogni questione che possa emergere. + + - Rilascio stabile. Ora, il numero di utilizzatori che sono potenzialmente + toccati dalla patch è aumentato, quindi, ancora una volta, potrebbero + emergere nuovi problemi. + + - Manutenzione di lungo periodo. Nonostante sia possibile che uno sviluppatore + si dimentichi del codice dopo la sua integrazione, questo comportamento + lascia una brutta impressione nella comunità di sviluppo. Integrare il + codice elimina alcuni degli oneri facenti parte della manutenzione, in + particolare, sistemerà le problematiche causate dalle modifiche all'API. + Ma lo sviluppatore originario dovrebbe continuare ad assumersi la + responsabilità per il codice se quest'ultimo continua ad essere utile + nel lungo periodo. + +Uno dei più grandi errori fatti dagli sviluppatori kernel (o dai loro datori +di lavoro) è quello di cercare di ridurre tutta la procedura ad una singola +"integrazione nel remo principale". Questo approccio inevitabilmente conduce +a una condizione di frustrazione per tutti coloro che sono coinvolti. + +Come le modifiche finiscono nel Kernel +-------------------------------------- + +Esiste una sola persona che può inserire le patch nel repositorio principale +del kernel: Linus Torvalds. Ma, di tutte le 9500 patch che entrarono nella +versione 2.6.38 del kernel, solo 112 (circa l'1,3%) furono scelte direttamente +da Linus in persona. Il progetto del kernel è cresciuto fino a raggiungere +una dimensione tale per cui un singolo sviluppatore non può controllare e +selezionare indipendentemente ogni modifica senza essere supportato. +La via scelta dagli sviluppatori per indirizzare tale crescita è stata quella +di utilizzare un sistema di "sottotenenti" basato sulla fiducia. + +Il codice base del kernel è spezzato in una serie si sottosistemi: rete, +supporto per specifiche architetture, gestione della memoria, video e +strumenti, etc. Molti sottosistemi hanno un manutentore designato: ovvero uno +sviluppatore che ha piena responsabilità di tutto il codice presente in quel +sottosistema. Tali manutentori di sottosistema sono i guardiani +(in un certo senso) della parte di kernel che gestiscono; sono coloro che +(solitamente) accetteranno una patch per l'inclusione nel ramo principale +del kernel. + +I manutentori di sottosistema gestiscono ciascuno la propria parte dei sorgenti +del kernel, utilizzando abitualmente (ma certamente non sempre) git. +Strumenti come git (e affini come quilt o mercurial) permettono ai manutentori +di stilare una lista delle patch, includendo informazioni sull'autore ed +altri metadati. In ogni momento, il manutentore può individuare quale patch +nel sua repositorio non si trova nel ramo principale. + +Quando la "finestra di integrazione" si apre, i manutentori di alto livello +chiederanno a Linus di "prendere" dai loro repositori le modifiche che hanno +selezionato per l'inclusione. Se Linus acconsente, il flusso di patch si +convoglierà nel repositorio di quest ultimo, divenendo così parte del ramo +principale del kernel. La quantità d'attenzione che Linus presta alle +singole patch ricevute durante l'operazione di integrazione varia. +È chiaro che, qualche volta, guardi più attentamente. Ma, come regola +generale, Linus confida nel fatto che i manutentori di sottosistema non +selezionino pessime patch. + +I manutentori di sottosistemi, a turno, possono "prendere" patch +provenienti da altri manutentori. Per esempio, i sorgenti per la rete rete +sono costruiti da modifiche che si sono accumulate inizialmente nei sorgenti +dedicati ai driver per dispositivi di rete, rete senza fili, ecc. Tale +catena di repositori può essere più o meno lunga, benché raramente ecceda +i due o tre collegamenti. Questo processo è conosciuto come +"la catena della fiducia", perché ogni manutentore all'interno della +catena si fida di coloro che gestiscono i livelli più bassi. + +Chiaramente, in un sistema come questo, l'inserimento delle patch all'interno +del kernel si basa sul trovare il manutentore giusto. Di norma, inviare +patch direttamente a Linus non è la via giusta. + + +Sorgenti -next +-------------- + +La catena di sottosistemi guida il flusso di patch all'interno del kernel, +ma solleva anche un interessante quesito: se qualcuno volesse vedere tutte le +patch pronte per la prossima finestra di integrazione? +Gli sviluppatori si interesseranno alle patch in sospeso per verificare +che non ci siano altri conflitti di cui preoccuparsi; una modifica che, per +esempio, cambia il prototipo di una funzione fondamentale del kernel andrà in +conflitto con qualsiasi altra modifica che utilizzi la vecchia versione di +quella funzione. Revisori e tester vogliono invece avere accesso alle +modifiche nella loro totalità prima che approdino nel ramo principale del +kernel. Uno potrebbe prendere le patch provenienti da tutti i sottosistemi +d'interesse, ma questo sarebbe un lavoro enorme e fallace. + +La risposta ci viene sotto forma di sorgenti -next, dove i sottosistemi sono +raccolti per essere testati e controllati. Il più vecchio di questi sorgenti, +gestito da Andrew Morton, è chiamato "-mm" (memory management, che è l'inizio +di tutto). L'-mm integra patch proveniente da una lunga lista di sottosistemi; +e ha, inoltre, alcune patch destinate al supporto del debugging. + +Oltre a questo, -mm contiene una raccolta significativa di patch che sono +state selezionate da Andrew direttamente. Queste patch potrebbero essere +state inviate in una lista di discussione, o possono essere applicate ad una +parte del kernel per la quale non esiste un sottosistema dedicato. +Di conseguenza, -mm opera come una specie di sottosistema "ultima spiaggia"; +se per una patch non esiste una via chiara per entrare nel ramo principale, +allora è probabile che finirà in -mm. Le patch passate per -mm +eventualmente finiranno nel sottosistema più appropriato o saranno inviate +direttamente a Linus. In un tipico ciclo di sviluppo, circa il 5-10% delle +patch andrà nel ramo principale attraverso -mm. + +La patch -mm correnti sono disponibili nella cartella "mmotm" (-mm of +the moment) all'indirizzo: + + http://www.ozlabs.org/~akpm/mmotm/ + +È molto probabile che l'uso dei sorgenti MMOTM diventi un'esperienza +frustrante; ci sono buone probabilità che non compili nemmeno. + +I sorgenti principali per il prossimo ciclo d'integrazione delle patch +è linux-next, gestito da Stephen Rothwell. I sorgenti linux-next sono, per +definizione, un'istantanea di come dovrà apparire il ramo principale dopo che +la prossima finestra di inclusione si chiuderà. I linux-next sono annunciati +sulla lista di discussione linux-kernel e linux-next nel momento in cui +vengono assemblati; e possono essere scaricate da: + + http://www.kernel.org/pub/linux/kernel/next/ + +Linux-next è divenuto parte integrante del processo di sviluppo del kernel; +tutte le patch incorporate durante una finestra di integrazione dovrebbero +aver trovato la propria strada in linux-next, a volte anche prima dell'apertura +della finestra di integrazione. + + +Sorgenti in preparazione +------------------------ + +Nei sorgenti del kernel esiste la cartella drivers/staging/, dove risiedono +molte sotto-cartelle per i driver o i filesystem che stanno per essere aggiunti +al kernel. Questi restano nella cartella drivers/staging fintanto che avranno +bisogno di maggior lavoro; una volta completato, possono essere spostate +all'interno del kernel nel posto più appropriato. Questo è il modo di tener +traccia dei driver che non sono ancora in linea con gli standard di codifica +o qualità, ma che le persone potrebbero voler usare ugualmente e tracciarne +lo sviluppo. + +Greg Kroah-Hartman attualmente gestisce i sorgenti in preparazione. I driver +che non sono completamente pronti vengono inviati a lui, e ciascun driver avrà +la propria sotto-cartella in drivers/staging/. Assieme ai file sorgenti +dei driver, dovrebbe essere presente nella stessa cartella anche un file TODO. +Il file TODO elenca il lavoro ancora da fare su questi driver per poter essere +accettati nel kernel, e indica anche la lista di persone da inserire in copia +conoscenza per ogni modifica fatta. Le regole attuali richiedono che i +driver debbano, come minimo, compilare adeguatamente. + +La *preparazione* può essere una via relativamente facile per inserire nuovi +driver all'interno del ramo principale, dove, con un po' di fortuna, saranno +notati da altri sviluppatori e migliorati velocemente. Entrare nella fase +di preparazione non è però la fine della storia, infatti, il codice che si +trova nella cartella staging che non mostra regolari progressi potrebbe +essere rimosso. Le distribuzioni, inoltre, tendono a dimostrarsi relativamente +riluttanti nell'attivare driver in preparazione. Quindi lo preparazione è, +nel migliore dei casi, una tappa sulla strada verso il divenire un driver +del ramo principale. + + +Strumenti +--------- + +Come è possibile notare dal testo sopra, il processo di sviluppo del kernel +dipende pesantemente dalla capacità di guidare la raccolta di patch in +diverse direzioni. L'intera cosa non funzionerebbe se non venisse svolta +con l'uso di strumenti appropriati e potenti. Spiegare l'uso di tali +strumenti non è lo scopo di questo documento, ma c'è spazio per alcuni +consigli. + +In assoluto, nella comunità del kernel, predomina l'uso di git come sistema +di gestione dei sorgenti. Git è una delle diverse tipologie di sistemi +distribuiti di controllo versione che sono stati sviluppati nella comunità +del software libero. Esso è calibrato per lo sviluppo del kernel, e si +comporta abbastanza bene quando ha a che fare con repositori grandi e con un +vasto numero di patch. Git ha inoltre la reputazione di essere difficile +da imparare e utilizzare, benché stia migliorando. Agli sviluppatori +del kernel viene richiesta un po' di familiarità con git; anche se non lo +utilizzano per il proprio lavoro, hanno bisogno di git per tenersi al passo +con il lavoro degli altri sviluppatori (e con il ramo principale). + +Git è ora compreso in quasi tutte le distribuzioni Linux. Esiste una sito che +potete consultare: + + http://git-scm.com/ + +Qui troverete i riferimenti alla documentazione e alle guide passo-passo. + +Tra gli sviluppatori Kernel che non usano git, la scelta alternativa più +popolare è quasi sicuramente Mercurial: + + http://www.selenic.com/mercurial/ + +Mercurial condivide diverse caratteristiche con git, ma fornisce +un'interfaccia che potrebbe risultare più semplice da utilizzare. + +L'altro strumento che vale la pena conoscere è Quilt: + + http://savannah.nongnu.org/projects/quilt/ + + +Quilt è un sistema di gestione delle patch, piuttosto che un sistema +di gestione dei sorgenti. Non mantiene uno storico degli eventi; ma piuttosto +è orientato verso il tracciamento di uno specifico insieme di modifiche +rispetto ad un codice in evoluzione. Molti dei più grandi manutentori di +sottosistema utilizzano quilt per gestire le patch che dovrebbero essere +integrate. Per la gestione di certe tipologie di sorgenti (-mm, per esempio), +quilt è il miglior strumento per svolgere il lavoro. + + +Liste di discussione +-------------------- + +Una grossa parte del lavoro di sviluppo del Kernel Linux viene svolto tramite +le liste di discussione. È difficile essere un membro della comunità +pienamente coinvolto se non si partecipa almeno ad una lista da qualche +parte. Ma, le liste di discussione di Linux rappresentano un potenziale +problema per gli sviluppatori, che rischiano di venir sepolti da un mare di +email, restare incagliati nelle convenzioni in vigore nelle liste Linux, +o entrambi. + +Molte delle liste di discussione del Kernel girano su vger.kernel.org; +l'elenco principale lo si trova sul sito: + + http://vger.kernel.org/vger-lists.html + +Esistono liste gestite altrove; un certo numero di queste sono in +lists.redhat.com. + +La lista di discussione principale per lo sviluppo del kernel è, ovviamente, +linux-kernel. Questa lista è un luogo ostile dove trovarsi; i volumi possono +raggiungere i 500 messaggi al giorno, la quantità di "rumore" è elevata, +la conversazione può essere strettamente tecnica e i partecipanti non sono +sempre preoccupati di mostrare un alto livello di educazione. Ma non esiste +altro luogo dove la comunità di sviluppo del kernel si unisce per intero; +gli sviluppatori che evitano tale lista si perderanno informazioni importanti. + +Ci sono alcuni consigli che possono essere utili per sopravvivere a +linux-kernel: + +- Tenete la lista in una cartella separata, piuttosto che inserirla nella + casella di posta principale. Così da essere in grado di ignorare il flusso + di mail per un certo periodo di tempo. + +- Non cercate di seguire ogni conversazione - nessuno lo fa. È importante + filtrare solo gli argomenti d'interesse (sebbene va notato che le + conversazioni di lungo periodo possono deviare dall'argomento originario + senza cambiare il titolo della mail) e le persone che stanno partecipando. + +- Non alimentate i troll. Se qualcuno cerca di creare nervosismo, ignoratelo. + +- Quando rispondete ad una mail linux-kernel (o ad altre liste) mantenete + tutti i Cc:. In assenza di importanti motivazioni (come una richiesta + esplicita), non dovreste mai togliere destinatari. Assicuratevi sempre che + la persona alla quale state rispondendo sia presente nella lista Cc. Questa + usanza fa si che divenga inutile chiedere esplicitamente di essere inseriti + in copia nel rispondere al vostro messaggio. + +- Cercate nell'archivio della lista (e nella rete nella sua totalità) prima + di far domande. Molti sviluppatori possono divenire impazienti con le + persone che chiaramente non hanno svolto i propri compiti a casa. + +- Evitate il *top-posting* (cioè la pratica di mettere la vostra risposta sopra + alla frase alla quale state rispondendo). Ciò renderebbe la vostra risposta + difficile da leggere e genera scarsa impressione. + +- Chiedete nella lista di discussione corretta. Linux-kernel può essere un + punto di incontro generale, ma non è il miglior posto dove trovare + sviluppatori da tutti i sottosistemi. + +Infine, la ricerca della corretta lista di discussione è uno degli errori più +comuni per gli sviluppatori principianti. Qualcuno che pone una domanda +relativa alla rete su linux-kernel riceverà quasi certamente il suggerimento +di chiedere sulla lista netdev, che è la lista frequentata dagli sviluppatori +di rete. Ci sono poi altre liste per i sottosistemi SCSI, video4linux, IDE, +filesystem, etc. Il miglior posto dove cercare una lista di discussione è il +file MAINTAINERS che si trova nei sorgenti del kernel. + +Iniziare con lo sviluppo del Kernel +----------------------------------- + +Sono comuni le domande sul come iniziare con lo sviluppo del kernel - sia da +singole persone che da aziende. Altrettanto comuni sono i passi falsi che +rendono l'inizio di tale relazione più difficile di quello che dovrebbe essere. + +Le aziende spesso cercano di assumere sviluppatori noti per creare un gruppo +di sviluppo iniziale. Questo, in effetti, può essere una tecnica efficace. +Ma risulta anche essere dispendiosa e non va ad accrescere il bacino di +sviluppatori kernel con esperienza. È possibile anche "portare a casa" +sviluppatori per accelerare lo sviluppo del kernel, dando comunque +all'investimento un po' di tempo. Prendersi questo tempo può fornire +al datore di lavoro un gruppo di sviluppatori che comprendono sia il kernel +che l'azienda stessa, e che possono supportare la formazione di altre persone. +Nel medio periodo, questa è spesso uno delle soluzioni più proficue. + +I singoli sviluppatori sono spesso, comprensibilmente, una perdita come punto +di partenza. Iniziare con un grande progetto può rivelarsi intimidatorio; +spesso all'inizio si vuole solo verificare il terreno con qualcosa di piccolo. +Questa è una delle motivazioni per le quali molti sviluppatori saltano alla +creazione di patch che vanno a sistemare errori di battitura o +problematiche minori legate allo stile del codice. Sfortunatamente, tali +patch creano un certo livello di rumore che distrae l'intera comunità di +sviluppo, quindi, sempre di più, esse vengono degradate. I nuovi sviluppatori +che desiderano presentarsi alla comunità non riceveranno l'accoglienza +che vorrebbero con questi mezzi. + +Andrew Morton da questo consiglio agli aspiranti sviluppatori kernel + +:: + + Il primo progetto per un neofita del kernel dovrebbe essere + sicuramente quello di "assicurarsi che il kernel funzioni alla + perfezione sempre e su tutte le macchine sulle quali potete stendere + la vostra mano". Solitamente il modo per fare ciò è quello di + collaborare con gli altri nel sistemare le cose (questo richiede + persistenza!) ma va bene - è parte dello sviluppo kernel. + +(http://lwn.net/Articles/283982/). + +In assenza di problemi ovvi da risolvere, si consiglia agli sviluppatori +di consultare, in generale, la lista di regressioni e di bachi aperti. +Non c'è mai carenza di problematiche bisognose di essere sistemate; +accollandosi tali questioni gli sviluppatori accumuleranno esperienza con +la procedura, ed allo stesso tempo, aumenteranno la loro rispettabilità +all'interno della comunità di sviluppo. diff --git a/Documentation/translations/it_IT/process/3.Early-stage.rst b/Documentation/translations/it_IT/process/3.Early-stage.rst new file mode 100644 index 000000000000..443ac1e5558f --- /dev/null +++ b/Documentation/translations/it_IT/process/3.Early-stage.rst @@ -0,0 +1,241 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/3.Early-stage.rst <development_early_stage>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_early_stage: + +I primi passi della pianificazione +================================== + +Osservando un progetto di sviluppo per il kernel Linux, si potrebbe essere +tentati dal saltare tutto e iniziare a codificare. Tuttavia, come ogni +progetto significativo, molta della preparazione per giungere al successo +viene fatta prima che una sola linea di codice venga scritta. Il tempo speso +nella pianificazione e la comunicazione può far risparmiare molto +tempo in futuro. + +Specificare il problema +----------------------- + +Come qualsiasi progetto ingegneristico, un miglioramento del kernel di +successo parte con una chiara descrizione del problema da risolvere. +In alcuni casi, questo passaggio è facile: ad esempio quando un driver è +richiesto per un particolare dispositivo. In altri casi invece, si +tende a confondere il problema reale con le soluzioni proposte e questo +può portare all'emergere di problemi. + +Facciamo un esempio: qualche anno fa, gli sviluppatori che lavoravano con +linux audio cercarono un modo per far girare le applicazioni senza dropouts +o altri artefatti dovuti all'eccessivo ritardo nel sistema. La soluzione +alla quale giunsero fu un modulo del kernel destinato ad agganciarsi al +framework Linux Security Module (LSM); questo modulo poteva essere +configurato per dare ad una specifica applicazione accesso allo +schedulatore *realtime*. Tale modulo fu implementato e inviato nella +lista di discussione linux-kernel, dove incontrò subito dei problemi. + +Per gli sviluppatori audio, questo modulo di sicurezza era sufficiente a +risolvere il loro problema nell'immediato. Per l'intera comunità kernel, +invece, era un uso improprio del framework LSM (che non è progettato per +conferire privilegi a processi che altrimenti non avrebbero potuto ottenerli) +e un rischio per la stabilità del sistema. Le loro soluzioni di punta nel +breve periodo, comportavano un accesso alla schedulazione realtime attraverso +il meccanismo rlimit, e nel lungo periodo un costante lavoro nella riduzione +dei ritardi. + +La comunità audio, comunque, non poteva vedere al di là della singola +soluzione che avevano implementato; erano riluttanti ad accettare alternative. +Il conseguente dissenso lasciò in quegli sviluppatori un senso di +disillusione nei confronti dell'intero processo di sviluppo; uno di loro +scrisse questo messaggio: + + Ci sono numerosi sviluppatori del kernel Linux davvero bravi, ma + rischiano di restare sovrastati da una vasta massa di stolti arroganti. + Cercare di comunicare le richieste degli utenti a queste persone è + una perdita di tempo. Loro sono troppo "intelligenti" per stare ad + ascoltare dei poveri mortali. + + (http://lwn.net/Articles/131776/). + +La realtà delle cose fu differente; gli sviluppatori del kernel erano molto +più preoccupati per la stabilità del sistema, per la manutenzione di lungo +periodo e cercavano la giusta soluzione alla problematica esistente con uno +specifico modulo. La morale della storia è quella di concentrarsi sul +problema - non su di una specifica soluzione- e di discuterne con la comunità +di sviluppo prima di investire tempo nella scrittura del codice. + +Quindi, osservando un progetto di sviluppo del kernel, si dovrebbe +rispondere a questa lista di domande: + +- Qual'è, precisamente, il problema che dev'essere risolto? + +- Chi sono gli utenti coinvolti da tal problema? A quale caso dovrebbe + essere indirizzata la soluzione? + +- In che modo il kernel risulta manchevole nell'indirizzare il problema + in questione? + +Solo dopo ha senso iniziare a considerare le possibili soluzioni. + +Prime discussioni +----------------- + +Quando si pianifica un progetto di sviluppo per il kernel, sarebbe quanto meno +opportuno discuterne inizialmente con la comunità prima di lanciarsi +nell'implementazione. Una discussione preliminare può far risparmiare sia +tempo che problemi in svariati modi: + + - Potrebbe essere che il problema sia già stato risolto nel kernel in + una maniera che non avete ancora compreso. Il kernel Linux è grande e ha + una serie di funzionalità e capacità che non sono scontate nell'immediato. + Non tutte le capacità del kernel sono documentate così bene come ci + piacerebbe, ed è facile perdersi qualcosa. Il vostro autore ha assistito + alla pubblicazione di un driver intero che duplica un altro driver + esistente di cui il nuovo autore era ignaro. Il codice che rinnova + ingranaggi già esistenti non è soltanto dispendioso; non verrà nemmeno + accettato nel ramo principale del kernel. + + - Potrebbero esserci proposte che non sono considerate accettabili per + l'integrazione all'interno del ramo principale. È meglio affrontarle + prima di scrivere il codice. + + - È possibile che altri sviluppatori abbiano pensato al problema; potrebbero + avere delle idee per soluzioni migliori, e potrebbero voler contribuire + alla loro creazione. + +Anni di esperienza con la comunità di sviluppo del kernel hanno impartito una +chiara lezione: il codice per il kernel che è pensato e sviluppato a porte +chiuse, inevitabilmente, ha problematiche che si rivelano solo quando il +codice viene rilasciato pubblicamente. Qualche volta tali problemi sono +importanti e richiedono mesi o anni di sforzi prima che il codice possa +raggiungere gli standard richiesti della comunità. +Alcuni esempi possono essere: + + - La rete Devicescape è stata creata e implementata per sistemi + mono-processore. Non avrebbe potuto essere inserita nel ramo principale + fino a che non avesse supportato anche i sistemi multi-processore. + Riadattare i meccanismi di sincronizzazione e simili è un compito difficile; + come risultato, l'inserimento di questo codice (ora chiamato mac80211) + fu rimandato per più di un anno. + + - Il filesystem Reiser4 include una seria di funzionalità che, secondo + l'opinione degli sviluppatori principali del kernel, avrebbero dovuto + essere implementate a livello di filesystem virtuale. Comprende + anche funzionalità che non sono facilmente implementabili senza esporre + il sistema al rischio di uno stallo. La scoperta tardiva di questi + problemi - e il diniego a risolverne alcuni - ha avuto come conseguenza + il fatto che Raiser4 resta fuori dal ramo principale del kernel. + + - Il modulo di sicurezza AppArmor utilizzava strutture dati del + filesystem virtuale interno in modi che sono stati considerati rischiosi e + inattendibili. Questi problemi (tra le altre cose) hanno tenuto AppArmor + fuori dal ramo principale per anni. + +Ciascuno di questi casi è stato un travaglio e ha richiesto del lavoro +straordinario, cose che avrebbero potuto essere evitate con alcune +"chiacchierate" preliminari con gli sviluppatori kernel. + +Con chi parlare? +---------------- + +Quando gli sviluppatori hanno deciso di rendere pubblici i propri progetti, la +domanda successiva sarà: da dove partiamo? La risposta è quella di trovare +la giusta lista di discussione e il giusto manutentore. Per le liste di +discussione, il miglior approccio è quello di cercare la lista più adatta +nel file MAINTAINERS. Se esiste una lista di discussione di sottosistema, +è preferibile pubblicare lì piuttosto che sulla lista di discussione generale +del kernel Linux; avrete maggiori probabilità di trovare sviluppatori con +esperienza sul tema, e l'ambiente che troverete potrebbe essere più +incoraggiante. + +Trovare manutentori può rivelarsi un po' difficoltoso. Ancora, il file +MAINTAINERS è il posto giusto da dove iniziare. Il file potrebbe non essere +sempre aggiornato, inoltre, non tutti i sottosistemi sono rappresentati qui. +Coloro che sono elencati nel file MAINTAINERS potrebbero, in effetti, non +essere le persone che attualmente svolgono quel determinato ruolo. Quindi, +quando c'è un dubbio su chi contattare, un trucco utile è quello di usare +git (git log in particolare) per vedere chi attualmente è attivo all'interno +del sottosistema interessato. Controllate chi sta scrivendo le patch, +e chi, se non ci fosse nessuno, sta aggiungendo la propria firma +(Signed-off-by) a quelle patch. Quelle sono le persone maggiormente +qualificate per aiutarvi con lo sviluppo di nuovo progetto. + +Il compito di trovare il giusto manutentore, a volte, è una tale sfida che +ha spinto gli sviluppatori del kernel a scrivere uno script che li aiutasse +in questa ricerca: + +:: + + .../scripts/get_maintainer.pl + +Se questo script viene eseguito con l'opzione "-f" ritornerà il +manutentore(i) attuale per un dato file o cartella. Se viene passata una +patch sulla linea di comando, lo script elencherà i manutentori che +dovrebbero riceverne una copia. Ci sono svariate opzioni che regolano +quanto a fondo get_maintainer.pl debba cercare i manutentori; +siate quindi prudenti nell'utilizzare le opzioni più aggressive poiché +potreste finire per includere sviluppatori che non hanno un vero interesse +per il codice che state modificando. + +Se tutto ciò dovesse fallire, parlare con Andrew Morton potrebbe essere +un modo efficace per capire chi è il manutentore di un dato pezzo di codice. + +Quando pubblicare +----------------- + +Se potete, pubblicate i vostri intenti durante le fasi preliminari, sarà +molto utile. Descrivete il problema da risolvere e ogni piano che è stato +elaborato per l'implementazione. Ogni informazione fornita può aiutare +la comunità di sviluppo a fornire spunti utili per il progetto. + +Un evento che potrebbe risultare scoraggiate e che potrebbe accadere in +questa fase non è il ricevere una risposta ostile, ma, invece, ottenere +una misera o inesistente reazione. La triste verità è che: (1) gli +sviluppatori del kernel tendono ad essere occupati, (2) ci sono tante persone +con grandi progetti e poco codice (o anche solo la prospettiva di +avere un codice) a cui riferirsi e (3) nessuno è obbligato a revisionare +o a fare osservazioni in merito ad idee pubblicate da altri. Oltre a +questo, progetti di alto livello spesso nascondono problematiche che si +rivelano solo quando qualcuno cerca di implementarle; per questa ragione +gli sviluppatori kernel preferirebbero vedere il codice. + +Quindi, se una richiesta pubblica di commenti riscuote poco successo, non +pensate che ciò significhi che non ci sia interesse nel progetto. +Sfortunatamente, non potete nemmeno assumere che non ci siano problemi con +la vostra idea. La cosa migliore da fare in questa situazione è quella di +andare avanti e tenere la comunità informata mentre procedete. + +Ottenere riscontri ufficiali +---------------------------- + +Se il vostro lavoro è stato svolto in un ambiente aziendale - come molto +del lavoro fatto su Linux - dovete, ovviamente, avere il permesso dei +dirigenti prima che possiate pubblicare i progetti, o il codice aziendale, +su una lista di discussione pubblica. La pubblicazione di codice che non +è stato rilascio espressamente con licenza GPL-compatibile può rivelarsi +problematico; prima la dirigenza, e il personale legale, troverà una decisione +sulla pubblicazione di un progetto, meglio sarà per tutte le persone coinvolte. + +A questo punto, alcuni lettori potrebbero pensare che il loro lavoro sul +kernel è preposto a supportare un prodotto che non è ancora ufficialmente +riconosciuto. Rivelare le intenzioni dei propri datori di lavori in una +lista di discussione pubblica potrebbe non essere una soluzione valida. +In questi casi, vale la pena considerare se la segretezza sia necessaria +o meno; spesso non c'è una reale necessità di mantenere chiusi i progetti di +sviluppo. + +Detto ciò, ci sono anche casi dove l'azienda legittimamente non può rivelare +le proprie intenzioni in anticipo durante il processo di sviluppo. Le aziende +che hanno sviluppatori kernel esperti possono scegliere di procedere a +carte coperte partendo dall'assunto che saranno in grado di evitare, o gestire, +in futuro, eventuali problemi d'integrazione. Per le aziende senza questo tipo +di esperti, la migliore opzione è spesso quella di assumere uno sviluppatore +esterno che revisioni i progetti con un accordo di segretezza. +La Linux Foundation applica un programma di NDA creato appositamente per +aiutare le aziende in questa particolare situazione; potrete trovare più +informazioni sul sito: + + http://www.linuxfoundation.org/en/NDA_program + +Questa tipologia di revisione è spesso sufficiente per evitare gravi problemi +senza che sia richiesta l'esposizione pubblica del progetto. diff --git a/Documentation/translations/it_IT/process/4.Coding.rst b/Documentation/translations/it_IT/process/4.Coding.rst new file mode 100644 index 000000000000..c05b89e616dd --- /dev/null +++ b/Documentation/translations/it_IT/process/4.Coding.rst @@ -0,0 +1,447 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/4.Coding.rst <development_coding>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_coding: + +Scrivere codice corretto +======================== + +Nonostante ci sia molto da dire sul processo di creazione, sulla sua solidità +e sul suo orientamento alla comunità, la prova di ogni progetto di sviluppo +del kernel si trova nel codice stesso. È il codice che sarà esaminato dagli +altri sviluppatori ed inserito (o no) nel ramo principale. Quindi è la +qualità di questo codice che determinerà il successo finale del progetto. + +Questa sezione esaminerà il processo di codifica. Inizieremo con uno sguardo +sulle diverse casistiche nelle quali gli sviluppatori kernel possono +sbagliare. Poi, l'attenzione si sposterà verso "il fare le cose +correttamente" e sugli strumenti che possono essere utili in questa missione. + +Trappole +-------- + +Lo stile del codice +******************* + +Il kernel ha da tempo delle norme sullo stile di codifica che sono descritte in +:ref:`Documentation/translations/it_IT/process/coding-style.rst <codingstyle>`. +Per la maggior parte del tempo, la politica descritta in quel file è stata +praticamente informativa. Ne risulta che ci sia una quantità sostanziale di +codice nel kernel che non rispetta le linee guida relative allo stile. +La presenza di quel codice conduce a due distinti pericoli per gli +sviluppatori kernel. + +Il primo di questi è credere che gli standard di codifica del kernel +non sono importanti e possono non essere applicati. La verità è che +aggiungere nuovo codice al kernel è davvero difficile se questo non +rispetta le norme; molti sviluppatori richiederanno che il codice sia +riformulato prima che anche solo lo revisionino. Una base di codice larga +quanto il kernel richiede una certa uniformità, in modo da rendere possibile +per gli sviluppatori una comprensione veloce di ogni sua parte. Non ci sono, +quindi, più spazi per un codice formattato alla carlona. + +Occasionalmente, lo stile di codifica del kernel andrà in conflitto con lo +stile richiesto da un datore di lavoro. In alcuni casi, lo stile del kernel +dovrà prevalere prima che il codice venga inserito. Mettere il codice +all'interno del kernel significa rinunciare a un certo grado di controllo +in differenti modi - incluso il controllo sul come formattare il codice. + +L’altra trappola è quella di pensare che il codice già presente nel kernel +abbia urgentemente bisogno di essere sistemato. Gli sviluppatori potrebbero +iniziare a generare patch che correggono lo stile come modo per prendere +famigliarità con il processo, o come modo per inserire i propri nomi nei +changelog del kernel – o entrambe. La comunità di sviluppo vede un attività +di codifica puramente correttiva come "rumore"; queste attività riceveranno +una fredda accoglienza. Di conseguenza è meglio evitare questo tipo di patch. +Mentre si lavora su un pezzo di codice è normale correggerne anche lo stile, +ma le modifiche di stile non dovrebbero essere fatte fini a se stesse. + +Il documento sullo stile del codice non dovrebbe essere letto come una legge +assoluta che non può mai essere trasgredita. Se c’è un a buona ragione +(per esempio, una linea che diviene poco leggibile se divisa per rientrare +nel limite di 80 colonne), fatelo e basta. + +Notate che potete utilizzare lo strumento “clang-format” per aiutarvi con +le regole, per una riformattazione automatica e veloce del vostro codice +e per revisionare interi file per individuare errori nello stile di codifica, +refusi e possibili miglioramenti. Inoltre è utile anche per classificare gli +``#includes``, per allineare variabili/macro, per testi derivati ed altri +compiti del genere. Consultate il file +:ref:`Documentation/translations/it_IT/process/clang-format.rst <clangformat>` +per maggiori dettagli + + +Livelli di astrazione +********************* + + +I professori di Informatica insegnano ai propri studenti a fare ampio uso dei +livelli di astrazione nel nome della flessibilità e del nascondere informazioni. +Certo il kernel fa un grande uso dell'astrazione; nessun progetto con milioni +di righe di codice potrebbe fare altrimenti e sopravvivere. Ma l'esperienza +ha dimostrato che un'eccessiva o prematura astrazione può rivelarsi dannosa +al pari di una prematura ottimizzazione. L'astrazione dovrebbe essere usata +fino al livello necessario e non oltre. + +Ad un livello base, considerate una funzione che ha un argomento che viene +sempre impostato a zero da tutti i chiamanti. Uno potrebbe mantenere +quell'argomento nell'eventualità qualcuno volesse sfruttare la flessibilità +offerta. In ogni caso, tuttavia, ci sono buone possibilità che il codice +che va ad implementare questo argomento aggiuntivo, sia stato rotto in maniera +sottile, in un modo che non è mai stato notato - perché non è mai stato usato. +Oppure, quando sorge la necessità di avere più flessibilità, questo argomento +non la fornisce in maniera soddisfacente. Gli sviluppatori di Kernel, +sottopongono costantemente patch che vanno a rimuovere gli argomenti +inutilizzate; anche se, in generale, non avrebbero dovuto essere aggiunti. + +I livelli di astrazione che nascondono l'accesso all'hardware - +spesso per poter usare dei driver su diversi sistemi operativi - vengono +particolarmente disapprovati. Tali livelli oscurano il codice e possono +peggiorare le prestazioni; essi non appartengono al kernel Linux. + +D'altro canto, se vi ritrovate a dover copiare una quantità significativa di +codice proveniente da un altro sottosistema del kernel, è tempo di chiedersi +se, in effetti, non avrebbe più senso togliere parte di quel codice e metterlo +in una libreria separata o di implementare quella funzionalità ad un livello +più elevato. Non c'è utilità nel replicare lo stesso codice per tutto +il kernel. + + +#ifdef e l'uso del preprocessore in generale +******************************************** + +Il preprocessore C sembra essere una fonte di attrazione per qualche +programmatore C, che ci vede una via per ottenere una grande flessibilità +all'interno di un file sorgente. Ma il preprocessore non è scritto in C, +e un suo massiccio impiego conduce a un codice che è molto più difficile +da leggere per gli altri e che rende più difficile il lavoro di verifica del +compilatore. L'uso eccessivo del preprocessore è praticamente sempre il segno +di un codice che necessita di un certo lavoro di pulizia. + +La compilazione condizionata con #ifdef è, in effetti, un potente strumento, +ed esso viene usato all'interno del kernel. Ma esiste un piccolo desiderio: +quello di vedere il codice coperto solo da una leggera spolverata di +blocchi #ifdef. Come regola generale, quando possibile, l'uso di #ifdef +dovrebbe essere confinato nei file d'intestazione. Il codice compilato +condizionatamente può essere confinato a funzioni tali che, nel caso in cui +il codice non deve essere presente, diventano vuote. Il compilatore poi +ottimizzerà la chiamata alla funzione vuota rimuovendola. Il risultato è +un codice molto più pulito, più facile da seguire. + +Le macro del preprocessore C presentano una serie di pericoli, inclusi +valutazioni multiple di espressioni che hanno effetti collaterali e non +garantiscono una sicurezza rispetto ai tipi. Se siete tentati dal definire +una macro, considerate l'idea di creare invece una funzione inline. Il codice +che ne risulterà sarà lo stesso, ma le funzioni inline sono più leggibili, +non considerano i propri argomenti più volte, e permettono al compilatore di +effettuare controlli sul tipo degli argomenti e del valore di ritorno. + + +Funzioni inline +*************** + +Comunque, anche le funzioni inline hanno i loro pericoli. I programmatori +potrebbero innamorarsi dell'efficienza percepita derivata dalla rimozione +di una chiamata a funzione. Queste funzioni, tuttavia, possono ridurre le +prestazioni. Dato che il loro codice viene replicato ovunque vi sia una +chiamata ad esse, si finisce per gonfiare le dimensioni del kernel compilato. +Questi, a turno, creano pressione sulla memoria cache del processore, e questo +può causare rallentamenti importanti. Le funzioni inline, di norma, dovrebbero +essere piccole e usate raramente. Il costo di una chiamata a funzione, dopo +tutto, non è così alto; la creazione di molte funzioni inline è il classico +esempio di un'ottimizzazione prematura. + +In generale, i programmatori del kernel ignorano gli effetti della cache a +loro rischio e pericolo. Il classico compromesso tempo/spazio teorizzato +all'inizio delle lezioni sulle strutture dati spesso non si applica +all'hardware moderno. Lo spazio *è* tempo, in questo senso un programma +più grande sarà più lento rispetto ad uno più compatto. + +I compilatori più recenti hanno preso un ruolo attivo nel decidere se +una data funzione deve essere resa inline oppure no. Quindi l'uso +indiscriminato della parola chiave "inline" potrebbe non essere non solo +eccessivo, ma anche irrilevante. + +Sincronizzazione +**************** + +Nel maggio 2006, il sistema di rete "Devicescape" fu rilasciato in pompa magna +sotto la licenza GPL e reso disponibile per la sua inclusione nella ramo +principale del kernel. Questa donazione fu una notizia bene accolta; +il supporto per le reti senza fili era considerata, nel migliore dei casi, +al di sotto degli standard; il sistema Deviscape offrì la promessa di una +risoluzione a tale situazione. Tuttavia, questo codice non fu inserito nel +ramo principale fino al giugno del 2007 (2.6.22). Cosa accadde? + +Quel codice mostrava numerosi segnali di uno sviluppo in azienda avvenuto +a porte chiuse. Ma in particolare, un grosso problema fu che non fu +progettato per girare in un sistema multiprocessore. Prima che questo +sistema di rete (ora chiamato mac80211) potesse essere inserito, fu necessario +un lavoro sugli schemi di sincronizzazione. + +Una volta, il codice del kernel Linux poteva essere sviluppato senza pensare +ai problemi di concorrenza presenti nei sistemi multiprocessore. Ora, +comunque, questo documento è stato scritto su di un portatile dual-core. +Persino su sistemi a singolo processore, il lavoro svolto per incrementare +la capacità di risposta aumenterà il livello di concorrenza interno al kernel. +I giorni nei quali il codice poteva essere scritto senza pensare alla +sincronizzazione sono da passati tempo. + +Ogni risorsa (strutture dati, registri hardware, etc.) ai quali si potrebbe +avere accesso simultaneo da più di un thread deve essere sincronizzato. Il +nuovo codice dovrebbe essere scritto avendo tale accortezza in testa; +riadattare la sincronizzazione a posteriori è un compito molto più difficile. +Gli sviluppatori del kernel dovrebbero prendersi il tempo di comprendere bene +le primitive di sincronizzazione, in modo da sceglier lo strumento corretto +per eseguire un compito. Il codice che presenta una mancanza di attenzione +alla concorrenza avrà un percorso difficile all'interno del ramo principale. + +Regressioni +*********** + +Vale la pena menzionare un ultimo pericolo: potrebbe rivelarsi accattivante +l'idea di eseguire un cambiamento (che potrebbe portare a grandi +miglioramenti) che porterà ad alcune rotture per gli utenti esistenti. +Questa tipologia di cambiamento è chiamata "regressione", e le regressioni son +diventate mal viste nel ramo principale del kernel. Con alcune eccezioni, +i cambiamenti che causano regressioni saranno fermati se quest'ultime non +potranno essere corrette in tempo utile. È molto meglio quindi evitare +la regressione fin dall'inizio. + +Spesso si è argomentato che una regressione può essere giustificata se essa +porta risolve più problemi di quanti non ne crei. Perché, dunque, non fare +un cambiamento se questo porta a nuove funzionalità a dieci sistemi per +ognuno dei quali esso determina una rottura? La migliore risposta a questa +domanda ci è stata fornita da Linus nel luglio 2007: + +:: + Dunque, noi non sistemiamo bachi introducendo nuovi problemi. Quella + via nasconde insidie, e nessuno può sapere del tutto se state facendo + dei progressi reali. Sono due passi avanti e uno indietro, oppure + un passo avanti e due indietro? + +(http://lwn.net/Articles/243460/). + +Una particolare tipologia di regressione mal vista consiste in una qualsiasi +sorta di modifica all'ABI dello spazio utente. Una volta che un'interfaccia +viene esportata verso lo spazio utente, dev'essere supportata all'infinito. +Questo fatto rende la creazione di interfacce per lo spazio utente +particolarmente complicato: dato che non possono venir cambiate introducendo +incompatibilità, esse devono essere fatte bene al primo colpo. Per questa +ragione sono sempre richieste: ampie riflessioni, documentazione chiara e +ampie revisioni dell'interfaccia verso lo spazio utente. + + +Strumenti di verifica del codice +-------------------------------- +Almeno per ora la scrittura di codice priva di errori resta un ideale +irraggiungibile ai più. Quello che speriamo di poter fare, tuttavia, è +trovare e correggere molti di questi errori prima che il codice entri nel +ramo principale del kernel. A tal scopo gli sviluppatori del kernel devono +mettere insieme una schiera impressionante di strumenti che possano +localizzare automaticamente un'ampia varietà di problemi. Qualsiasi problema +trovato dal computer è un problema che non affliggerà l'utente in seguito, +ne consegue che gli strumenti automatici dovrebbero essere impiegati ovunque +possibile. + +Il primo passo consiste semplicemente nel fare attenzione agli avvertimenti +proveniente dal compilatore. Versioni moderne di gcc possono individuare +(e segnalare) un gran numero di potenziali errori. Molto spesso, questi +avvertimenti indicano problemi reali. Di regola, il codice inviato per la +revisione non dovrebbe produrre nessun avvertimento da parte del compilatore. +Per mettere a tacere gli avvertimenti, cercate di comprenderne le cause reali +e cercate di evitare le "riparazioni" che fan sparire l'avvertimento senza +però averne trovato la causa. + +Tenete a mente che non tutti gli avvertimenti sono disabilitati di default. +Costruite il kernel con "make EXTRA_CFLAGS=-W" per ottenerli tutti. + +Il kernel fornisce differenti opzioni che abilitano funzionalità di debugging; +molti di queste sono trovano all'interno del sotto menu "kernel hacking". +La maggior parte di queste opzioni possono essere attivate per qualsiasi +kernel utilizzato per lo sviluppo o a scopo di test. In particolare dovreste +attivare: + + - ENABLE_MUST_CHECK e FRAME_WARN per ottenere degli + avvertimenti dedicati a problemi come l'uso di interfacce deprecate o + l'ignorare un importante valore di ritorno di una funzione. Il risultato + generato da questi avvertimenti può risultare verboso, ma non bisogna + preoccuparsi per gli avvertimenti provenienti da altre parti del kernel. + + - DEBUG_OBJECTS aggiungerà un codice per tracciare il ciclo di vita di + diversi oggetti creati dal kernel e avvisa quando qualcosa viene eseguito + fuori controllo. Se state aggiungendo un sottosistema che crea (ed + esporta) oggetti complessi propri, considerate l'aggiunta di un supporto + al debugging dell'oggetto. + + - DEBUG_SLAB può trovare svariati errori di uso e di allocazione di memoria; + esso dovrebbe esser usato dalla maggior parte dei kernel di sviluppo. + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, e DEBUG_MUTEXES troveranno un certo + numero di errori comuni di sincronizzazione. + +Esistono ancora delle altre opzioni di debugging, di alcune di esse +discuteremo qui sotto. Alcune di esse hanno un forte impatto e non dovrebbero +essere usate tutte le volte. Ma qualche volta il tempo speso nell'capire +le opzioni disponibili porterà ad un risparmio di tempo nel breve termine. + +Uno degli strumenti di debugging più tosti è il *locking checker*, o +"lockdep". Questo strumento traccerà qualsiasi acquisizione e rilascio di +ogni *lock* (spinlock o mutex) nel sistema, l'ordine con il quale i *lock* +sono acquisiti in relazione l'uno con l'altro, l'ambiente corrente di +interruzione, eccetera. Inoltre esso può assicurare che i *lock* vengano +acquisiti sempre nello stesso ordine, che le stesse assunzioni sulle +interruzioni si applichino in tutte le occasioni, e così via. In altre parole, +lockdep può scovare diversi scenari nei quali il sistema potrebbe, in rari +casi, trovarsi in stallo. Questa tipologia di problema può essere grave +(sia per gli sviluppatori che per gli utenti) in un sistema in uso; lockdep +permette di trovare tali problemi automaticamente e in anticipo. + +In qualità di programmatore kernel diligente, senza dubbio, dovrete controllare +il valore di ritorno di ogni operazione (come l'allocazione della memoria) +poiché esso potrebbe fallire. Il nocciolo della questione è che i percorsi +di gestione degli errori, con grande probabilità, non sono mai stati +collaudati del tutto. Il codice collaudato tende ad essere codice bacato; +potrete quindi essere più a vostro agio con il vostro codice se tutti questi +percorsi fossero stati verificati un po' di volte. + +Il kernel fornisce un framework per l'inserimento di fallimenti che fa +esattamente al caso, specialmente dove sono coinvolte allocazioni di memoria. +Con l'opzione per l'inserimento dei fallimenti abilitata, una certa percentuale +di allocazione di memoria sarà destinata al fallimento; questi fallimenti +possono essere ridotti ad uno specifico pezzo di codice. Procedere con +l'inserimento dei fallimenti attivo permette al programmatore di verificare +come il codice risponde quando le cose vanno male. Consultate: +Documentation/fault-injection/fault-injection.txt per avere maggiori +informazioni su come utilizzare questo strumento. + +Altre tipologie di errori possono essere riscontrati con lo strumento di +analisi statica "sparse". Con Sparse, il programmatore può essere avvisato +circa la confusione tra gli indirizzi dello spazio utente e dello spazio +kernel, un miscuglio fra quantità big-endian e little-endian, il passaggio +di un valore intero dove ci sia aspetta un gruppo di flag, e così via. +Sparse deve essere installato separatamente (se il vostra distribuzione non +lo prevede, potete trovarlo su https://sparse.wiki.kernel.org/index.php/Main_Page); +può essere attivato sul codice aggiungendo "C=1" al comando make. + +Lo strumento "Coccinelle" (http://coccinelle.lip6.fr/) è in grado di trovare +una vasta varietà di potenziali problemi di codifica; e può inoltre proporre +soluzioni per risolverli. Un buon numero di "patch semantiche" per il kernel +sono state preparate nella cartella scripts/coccinelle; utilizzando +"make coccicheck" esso percorrerà tali patch semantiche e farà rapporto su +qualsiasi problema trovato. Per maggiori informazioni, consultate +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`. + +Altri errori di portabilità sono meglio scovati compilando il vostro codice +per altre architetture. Se non vi accade di avere un sistema S/390 o una +scheda di sviluppo Blackfin sotto mano, potete comunque continuare la fase +di compilazione. Un vasto numero di cross-compilatori per x86 possono +essere trovati al sito: + + http://www.kernel.org/pub/tools/crosstool/ + +Il tempo impiegato nell'installare e usare questi compilatori sarà d'aiuto +nell'evitare situazioni imbarazzanti nel futuro. + + +Documentazione +-------------- + +La documentazione è spesso stata più un'eccezione che una regola nello +sviluppo del kernel. Nonostante questo, un'adeguata documentazione aiuterà +a facilitare l'inserimento di nuovo codice nel kernel, rende la vita più +facile per gli altri sviluppatori e sarà utile per i vostri utenti. In molti +casi, la documentazione è divenuta sostanzialmente obbligatoria. + +La prima parte di documentazione per qualsiasi patch è il suo changelog. +Questi dovrebbero descrivere le problematiche risolte, la tipologia di +soluzione, le persone che lavorano alla patch, ogni effetto rilevante +sulle prestazioni e tutto ciò che può servire per la comprensione della +patch. Assicuratevi che il changelog dica *perché*, vale la pena aggiungere +la patch; un numero sorprendente di sviluppatori sbaglia nel fornire tale +informazione. + +Qualsiasi codice che aggiunge una nuova interfaccia in spazio utente - inclusi +nuovi file in sysfs o /proc - dovrebbe includere la documentazione di tale +interfaccia così da permette agli sviluppatori dello spazio utente di sapere +con cosa stanno lavorando. Consultate: Documentation/ABI/README per avere una +descrizione di come questi documenti devono essere impostati e quali +informazioni devono essere fornite. + +Il file :ref:`Documentation/translations/it_IT/admin-guide/kernel-parameters.rst <kernelparameters>` +descrive tutti i parametri di avvio del kernel. Ogni patch che aggiunga +nuovi parametri dovrebbe aggiungere nuove voci a questo file. + +Ogni nuova configurazione deve essere accompagnata da un testo di supporto +che spieghi chiaramente le opzioni e spieghi quando l'utente potrebbe volerle +selezionare. + +Per molti sottosistemi le informazioni sull'API interna sono documentate sotto +forma di commenti formattati in maniera particolare; questi commenti possono +essere estratti e formattati in differenti modi attraverso lo script +"kernel-doc". Se state lavorando all'interno di un sottosistema che ha +commenti kerneldoc dovreste mantenerli e aggiungerli, in maniera appropriata, +per le funzioni disponibili esternamente. Anche in aree che non sono molto +documentate, non c'è motivo per non aggiungere commenti kerneldoc per il +futuro; infatti, questa può essere un'attività utile per sviluppatori novizi +del kernel. Il formato di questi commenti, assieme alle informazione su come +creare modelli per kerneldoc, possono essere trovati in +:ref:`Documentation/translations/it_IT/doc-guide/ <doc_guide>`. + +Chiunque legga un ammontare significativo di codice kernel noterà che, spesso, +i commenti si fanno maggiormente notare per la loro assenza. Ancora una volta, +le aspettative verso il nuovo codice sono più alte rispetto al passato; +inserire codice privo di commenti sarà più difficile. Detto ciò, va aggiunto +che non si desiderano commenti prolissi per il codice. Il codice dovrebbe +essere, di per sé, leggibile, con dei commenti che spieghino gli aspetti più +sottili. + +Determinate cose dovrebbero essere sempre commentate. L'uso di barriere +di memoria dovrebbero essere accompagnate da una riga che spieghi perché sia +necessaria. Le regole di sincronizzazione per le strutture dati, generalmente, +necessitano di una spiegazioni da qualche parte. Le strutture dati più +importanti, in generale, hanno bisogno di una documentazione onnicomprensiva. +Le dipendenze che non sono ovvie tra bit separati di codice dovrebbero essere +indicate. Tutto ciò che potrebbe indurre un inserviente del codice a fare +una "pulizia" incorretta, ha bisogno di un commento che dica perché è stato +fatto in quel modo. E così via. + +Cambiamenti interni dell'API +---------------------------- + +L'interfaccia binaria fornita dal kernel allo spazio utente non può essere +rotta tranne che in circostanze eccezionali. L'interfaccia di programmazione +interna al kernel, invece, è estremamente fluida e può essere modificata al +bisogno. Se vi trovate a dover lavorare attorno ad un'API del kernel o +semplicemente non state utilizzando una funzionalità offerta perché questa +non rispecchia i vostri bisogni, allora questo potrebbe essere un segno che +l'API ha bisogno di essere cambiata. In qualità di sviluppatore del kernel, +hai il potere di fare questo tipo di modifica. + +Ci sono ovviamente alcuni punti da cogliere. I cambiamenti API possono essere +fatti, ma devono essere giustificati. Quindi ogni patch che porta ad una +modifica dell'API interna dovrebbe essere accompagnata da una descrizione +della modifica in sé e del perché essa è necessaria. Questo tipo di +cambiamenti dovrebbero, inoltre, essere fatti in una patch separata, invece di +essere sepolti all'interno di una patch più grande. + +L'altro punto da cogliere consiste nel fatto che uno sviluppatore che +modifica l'API deve, in generale, essere responsabile della correzione +di tutto il codice del kernel che viene rotto per via della sua modifica. +Per una funzione ampiamente usata, questo compito può condurre letteralmente +a centinaia o migliaia di modifiche, molte delle quali sono in conflitto con +il lavoro svolto da altri sviluppatori. Non c'è bisogno di dire che questo +può essere un lavoro molto grosso, quindi è meglio essere sicuri che la +motivazione sia ben solida. Notate che lo strumento Coccinelle può fornire +un aiuto con modifiche estese dell'API. + +Quando viene fatta una modifica API incompatibile, una persona dovrebbe, +quando possibile, assicurarsi che quel codice non aggiornato sia trovato +dal compilatore. Questo vi aiuterà ad essere sicuri d'avere trovato, +tutti gli usi di quell'interfaccia. Inoltre questo avviserà gli sviluppatori +di codice fuori dal kernel che c'è un cambiamento per il quale è necessario del +lavoro. Il supporto al codice fuori dal kernel non è qualcosa di cui gli +sviluppatori del kernel devono preoccuparsi, ma non dobbiamo nemmeno rendere +più difficile del necessario la vita agli sviluppatori di questo codice. diff --git a/Documentation/translations/it_IT/process/5.Posting.rst b/Documentation/translations/it_IT/process/5.Posting.rst new file mode 100644 index 000000000000..b979266aa884 --- /dev/null +++ b/Documentation/translations/it_IT/process/5.Posting.rst @@ -0,0 +1,348 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/5.Posting.rst <development_posting>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_development_posting: + +Pubblicare modifiche +==================== + +Prima o poi arriva il momento in cui il vostro lavoro è pronto per essere +presentato alla comunità per una revisione ed eventualmente per la sua +inclusione nel ramo principale del kernel. Com'era prevedibile, +la comunità di sviluppo del kernel ha elaborato un insieme di convenzioni +e di procedure per la pubblicazione delle patch; seguirle renderà la vita +più facile a tutti quanti. Questo documento cercherà di coprire questi +argomenti con un ragionevole livello di dettaglio; più informazioni possono +essere trovare nella cartella 'Documentation', nei file +:ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`, +:ref:`translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`, e +:ref:`translations/it_IT/process/submit-checklist.rst <it_submitchecklist>`. + + +Quando pubblicarle +------------------ + +C'è sempre una certa resistenza nel pubblicare patch finché non sono +veramente "pronte". Per semplici patch questo non è un problema. +Ma quando il lavoro è di una certa complessità, c'è molto da guadagnare +dai riscontri che la comunità può darvi prima che completiate il lavoro. +Dovreste considerare l'idea di pubblicare un lavoro incompleto, o anche +preparare un ramo git disponibile agli sviluppatori interessati, cosicché +possano stare al passo col vostro lavoro in qualunque momento. + +Quando pubblicate del codice che non è considerato pronto per l'inclusione, +è bene che lo diciate al momento della pubblicazione. Inoltre, aggiungete +informazioni sulle cose ancora da sviluppare e sui problemi conosciuti. +Poche persone guarderanno delle patch che si sa essere fatte a metà, +ma quelli che lo faranno penseranno di potervi aiutare a condurre il vostro +sviluppo nella giusta direzione. + + +Prima di creare patch +--------------------- + +Ci sono un certo numero di cose che dovreste fare prima di considerare +l'invio delle patch alla comunità di sviluppo. Queste cose includono: + + - Verificare il codice fino al massimo che vi è consentito. Usate gli + strumenti di debug del kernel, assicuratevi che il kernel compili con + tutte le più ragionevoli combinazioni d'opzioni, usate cross-compilatori + per compilare il codice per differenti architetture, eccetera. + + - Assicuratevi che il vostro codice sia conforme alla linee guida del + kernel sullo stile del codice. + + - La vostra patch ha delle conseguenze in termini di prestazioni? + Se è così, dovreste eseguire dei *benchmark* che mostrino il loro + impatto (anche positivo); un riassunto dei risultati dovrebbe essere + incluso nella patch. + + - Siate certi d'avere i diritti per pubblicare il codice. Se questo + lavoro è stato fatto per un datore di lavoro, egli avrà dei diritti su + questo lavoro e dovrà quindi essere d'accordo alla sua pubblicazione + con una licenza GPL + +Come regola generale, pensarci un po' di più prima di inviare il codice +ripaga quasi sempre lo sforzo. + + +Preparazione di una patch +------------------------- + +La preparazione delle patch per la pubblicazione può richiedere una quantità +di lavoro significativa, ma, ripetiamolo ancora, generalmente sconsigliamo +di risparmiare tempo in questa fase, anche sul breve periodo. + +Le patch devono essere preparate per una specifica versione del kernel. +Come regola generale, una patch dovrebbe basarsi sul ramo principale attuale +così come lo si trova nei sorgenti git di Linus. Quando vi basate sul ramo +principale, cominciate da un punto di rilascio ben noto - uno stabile o +un -rc - piuttosto che creare il vostro ramo da quello principale in un punto +a caso. + +Per facilitare una revisione e una verifica più estesa, potrebbe diventare +necessaria la produzione di versioni per -mm, linux-next o i sorgenti di un +sottosistema. Basare questa patch sui suddetti sorgenti potrebbe richiedere +un lavoro significativo nella risoluzione dei conflitti e nella correzione dei +cambiamenti di API; questo potrebbe variare a seconda dell'area d'interesse +della vostra patch e da quello che succede altrove nel kernel. + +Solo le modifiche più semplici dovrebbero essere preparate come una singola +patch; tutto il resto dovrebbe essere preparato come una serie logica di +modifiche. Spezzettare le patch è un po' un'arte; alcuni sviluppatori +passano molto tempo nel capire come farlo in modo che piaccia alla comunità. +Ci sono alcune regole spannometriche, che comunque possono aiutare +considerevolmente: + + - La serie di patch che pubblicherete, quasi sicuramente, non sarà + come quella che trovate nel vostro sistema di controllo di versione. + Invece, le vostre modifiche dovranno essere considerate nella loro forma + finale, e quindi separate in parti che abbiano un senso. Gli sviluppatori + sono interessati in modifiche che siano discrete e indipendenti, non + alla strada che avete percorso per ottenerle. + + - Ogni modifica logicamente indipendente dovrebbe essere preparata come una + patch separata. Queste modifiche possono essere piccole ("aggiunto un + campo in questa struttura") o grandi (l'aggiunta di un driver nuovo, + per esempio), ma dovrebbero essere concettualmente piccole da permettere + una descrizione in una sola riga. Ogni patch dovrebbe fare modifiche + specifiche che si possano revisionare indipendentemente e di cui si possa + verificare la veridicità. + + - Giusto per riaffermare quando detto sopra: non mischiate diversi tipi di + modifiche nella stessa patch. Se una modifica corregge un baco critico + per la sicurezza, riorganizza alcune strutture, e riformatta il codice, + ci sono buone probabilità che venga ignorata e che la correzione importante + venga persa. + + - Ogni modifica dovrebbe portare ad un kernel che compila e funziona + correttamente; se la vostra serie di patch si interrompe a metà il + risultato dovrebbe essere comunque un kernel funzionante. L'applicazione + parziale di una serie di patch è uno scenario comune nel quale il + comando "git bisect" viene usato per trovare delle regressioni; se il + risultato è un kernel guasto, renderete la vita degli sviluppatori più + difficile così come quella di chi s'impegna nel nobile lavoro di + scovare i problemi. + + - Però, non strafate. Una volta uno sviluppatore pubblicò una serie di 500 + patch che modificavano un unico file - un atto che non lo rese la persona + più popolare sulla lista di discussione del kernel. Una singola patch + può essere ragionevolmente grande fintanto che contenga un singolo + cambiamento *logico*. + + - Potrebbe essere allettante l'idea di aggiungere una nuova infrastruttura + come una serie di patch, ma di lasciare questa infrastruttura inutilizzata + finché l'ultima patch della serie non abilita tutto quanto. Quando è + possibile, questo dovrebbe essere evitato; se questa serie aggiunge delle + regressioni, "bisect" indicherà quest'ultima patch come causa del + problema anche se il baco si trova altrove. Possibilmente, quando una + patch aggiunge del nuovo codice dovrebbe renderlo attivo immediatamente. + +Lavorare per creare la serie di patch perfetta potrebbe essere frustrante +perché richiede un certo tempo e soprattutto dopo che il "vero lavoro" è +già stato fatto. Quando ben fatto, comunque, è tempo ben speso. + + +Formattazione delle patch e i changelog +--------------------------------------- + +Quindi adesso avete una serie perfetta di patch pronte per la pubblicazione, +ma il lavoro non è davvero finito. Ogni patch deve essere preparata con +un messaggio che spieghi al resto del mondo, in modo chiaro e veloce, +il suo scopo. Per ottenerlo, ogni patch sarà composta dai seguenti elementi: + + - Un campo opzionale "From" col nome dell'autore della patch. Questa riga + è necessaria solo se state passando la patch di qualcun altro via email, + ma nel dubbio non fa di certo male aggiungerlo. + + - Una descrizione di una riga che spieghi cosa fa la patch. Questo + messaggio dovrebbe essere sufficiente per far comprendere al lettore lo + scopo della patch senza altre informazioni. Questo messaggio, + solitamente, presenta in testa il nome del sottosistema a cui si riferisce, + seguito dallo scopo della patch. Per esempio: + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - Una riga bianca seguita da una descrizione dettagliata della patch. + Questa descrizione può essere lunga tanto quanto serve; dovrebbe spiegare + cosa fa e perché dovrebbe essere aggiunta al kernel. + + - Una o più righe etichette, con, minimo, una riga *Signed-off-by:* + col nome dall'autore della patch. Queste etichette verranno descritte + meglio più avanti. + +Gli elementi qui sopra, assieme, formano il changelog di una patch. +Scrivere un buon changelog è cruciale ma è spesso un'arte trascurata; +vale la pena spendere qualche parola in più al riguardo. Quando scrivete +un changelog dovreste tenere ben presente che molte persone leggeranno +le vostre parole. Queste includono i manutentori di un sotto-sistema, e i +revisori che devono decidere se la patch debba essere inclusa o no, +le distribuzioni e altri manutentori che cercano di valutare se la patch +debba essere applicata su kernel più vecchi, i cacciatori di bachi che si +chiederanno se la patch è la causa di un problema che stanno cercando, +gli utenti che vogliono sapere com'è cambiato il kernel, e molti altri. +Un buon changelog fornisce le informazioni necessarie a tutte queste +persone nel modo più diretto e conciso possibile. + +A questo scopo, la riga riassuntiva dovrebbe descrivere gli effetti della +modifica e la motivazione della patch nel modo migliore possibile nonostante +il limite di una sola riga. La descrizione dettagliata può spiegare meglio +i temi e fornire maggiori informazioni. Se una patch corregge un baco, +citate, se possibile, il commit che lo introdusse (e per favore, quando +citate un commit aggiungete sia il suo identificativo che il titolo), +Se il problema è associabile ad un file di log o all' output del compilatore, +includeteli al fine d'aiutare gli altri a trovare soluzioni per lo stesso +problema. Se la modifica ha lo scopo di essere di supporto a sviluppi +successivi, ditelo. Se le API interne vengono cambiate, dettagliate queste +modifiche e come gli altri dovrebbero agire per applicarle. In generale, +più riuscirete ad entrare nei panni di tutti quelli che leggeranno il +vostro changelog, meglio sarà il changelog (e il kernel nel suo insieme). + +Non serve dirlo, un changelog dovrebbe essere il testo usato nel messaggio +di commit in un sistema di controllo di versione. Sarà seguito da: + + - La patch stessa, nel formato unificato per patch ("-u"). Usare + l'opzione "-p" assocerà alla modifica il nome della funzione alla quale + si riferisce, rendendo il risultato più facile da leggere per gli altri. + +Dovreste evitare di includere nelle patch delle modifiche per file +irrilevanti (quelli generati dal processo di generazione, per esempio, o i file +di backup del vostro editor). Il file "dontdiff" nella cartella Documentation +potrà esservi d'aiuto su questo punto; passatelo a diff con l'opzione "-X". + +Le etichette sopra menzionante sono usate per descrivere come i vari +sviluppatori sono stati associati allo sviluppo di una patch. Sono descritte +in dettaglio nel documento :ref:`translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`; +quello che segue è un breve riassunto. Ognuna di queste righe ha il seguente +formato: + +:: + + tag: Full Name <email address> optional-other-stuff + +Le etichette in uso più comuni sono: + + - Signed-off-by: questa è la certificazione che lo sviluppatore ha il diritto + di sottomettere la patch per l'integrazione nel kernel. Questo rappresenta + il consenso verso il certificato d'origine degli sviluppatori, il testo + completo potrà essere trovato in + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. + Codice che non presenta una firma appropriata non potrà essere integrato. + + - Co-developed-by: indica che la patch è stata sviluppata anche da un altro + sviluppatore assieme all'autore originale. Questo è utile quando più + persone lavorano sulla stessa patch. Da notare che questa persona deve + avere anche una riga "Signed-off-by:" nella patch. + + - Acked-by: indica il consenso di un altro sviluppatore (spesso il manutentore + del codice in oggetto) all'integrazione della patch nel kernel. + + - Tested-by: menziona la persona che ha verificato la patch e l'ha trovata + funzionante. + + - Reviwed-by: menziona lo sviluppatore che ha revisionato la patch; per + maggiori dettagli leggete la dichiarazione dei revisori in + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` + + - Reported-by: menziona l'utente che ha riportato il problema corretto da + questa patch; quest'etichetta viene usata per dare credito alle persone + che hanno verificato il codice e ci hanno fatto sapere quando le cose non + funzionavano correttamente. + + - Cc: la persona menzionata ha ricevuto una copia della patch ed ha avuto + l'opportunità di commentarla. + +State attenti ad aggiungere queste etichette alla vostra patch: solo +"Cc:" può essere aggiunta senza il permesso esplicito della persona menzionata. + +Inviare la modifica +------------------- + +Prima di inviare la vostra patch, ci sarebbero ancora un paio di cose di cui +dovreste aver cura: + + - Siete sicuri che il vostro programma di posta non corromperà le patch? + Le patch che hanno spazi bianchi in libertà o andate a capo aggiunti + dai programmi di posta non funzioneranno per chi le riceve, e spesso + non verranno nemmeno esaminate in dettaglio. Se avete un qualsiasi dubbio, + inviate la patch a voi stessi e verificate che sia integra. + + :ref:`Documentation/translations/it_IT/process/email-clients.rst <it_email_clients>` + contiene alcuni suggerimenti utili sulla configurazione dei programmi + di posta al fine di inviare patch. + + - Siete sicuri che la vostra patch non contenga sciocchi errori? Dovreste + sempre processare le patch con scripts/checkpatch.pl e correggere eventuali + problemi riportati. Per favore tenete ben presente che checkpatch.pl non è + più intelligente di voi, nonostante sia il risultato di un certa quantità di + ragionamenti su come debba essere una patch per il kernel. Se seguire + i suggerimenti di checkpatch.pl rende il codice peggiore, allora non fatelo. + +Le patch dovrebbero essere sempre inviate come testo puro. Per favore non +inviatele come allegati; questo rende molto più difficile, per i revisori, +citare parti della patch che si vogliono commentare. Invece, mettete la vostra +patch direttamente nel messaggio. + +Quando inviate le patch, è importante inviarne una copia a tutte le persone che +potrebbero esserne interessate. Al contrario di altri progetti, il kernel +incoraggia le persone a peccare nell'invio di tante copie; non presumente che +le persone interessate vedano i vostri messaggi sulla lista di discussione. +In particolare le copie dovrebbero essere inviate a: + + - I manutentori dei sottosistemi affetti della modifica. Come descritto + in precedenza, il file MAINTAINERS è il primo luogo dove cercare i nomi + di queste persone. + + - Altri sviluppatori che hanno lavorato nello stesso ambiente - specialmente + quelli che potrebbero lavorarci proprio ora. Usate git potrebbe essere + utile per vedere chi altri ha modificato i file su cui state lavorando. + + - Se state rispondendo a un rapporto su un baco, o a una richiesta di + funzionalità, includete anche gli autori di quei rapporti/richieste. + + - Inviate una copia alle liste di discussione interessate, o, se nient'altro + è adatto, alla lista linux-kernel + + - Se state correggendo un baco, pensate se la patch dovrebbe essere inclusa + nel prossimo rilascio stabile. Se è così, la lista di discussione + stable@vger.kernel.org dovrebbe riceverne una copia. Aggiungete anche + l'etichetta "Cc: stable@vger.kernel.org" nella patch stessa; questo + permetterà alla squadra *stable* di ricevere una notifica quando questa + correzione viene integrata nel ramo principale. + +Quando scegliete i destinatari della patch, è bene avere un'idea di chi +pensiate che sia colui che, eventualmente, accetterà la vostra patch e +la integrerà. Nonostante sia possibile inviare patch direttamente a +Linus Torvalds, e lasciare che sia lui ad integrarle,solitamente non è la +strada migliore da seguire. Linus è occupato, e ci sono dei manutentori di +sotto-sistema che controllano una parte specifica del kernel. Solitamente, +vorreste che siano questi manutentori ad integrare le vostre patch. Se non +c'è un chiaro manutentore, l'ultima spiaggia è spesso Andrew Morton. + +Le patch devono avere anche un buon oggetto. Il tipico formato per l'oggetto +di una patch assomiglia a questo: + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +dove "nn" è il numero ordinale della patch, "mm" è il numero totale delle patch +nella serie, e "subsys" è il nome del sottosistema interessato. Chiaramente, +nn/mm può essere omesso per una serie composta da una singola patch. + +Se avete una significative serie di patch, è prassi inviare una descrizione +introduttiva come parte zero. Tuttavia questa convenzione non è universalmente +seguita; se la usate, ricordate che le informazioni nell'introduzione non +faranno parte del changelog del kernel. Quindi per favore, assicuratevi che +ogni patch abbia un changelog completo. + +In generale, la seconda parte e quelle successive di una patch "composta" +dovrebbero essere inviate come risposta alla prima, cosicché vengano viste +come un unico *thread*. Strumenti come git e quilt hanno comandi per inviare +gruppi di patch con la struttura appropriata. Se avete una serie lunga +e state usando git, per favore state alla larga dall'opzione --chain-reply-to +per evitare di creare un annidamento eccessivo. diff --git a/Documentation/translations/it_IT/process/6.Followthrough.rst b/Documentation/translations/it_IT/process/6.Followthrough.rst new file mode 100644 index 000000000000..df7d5fb28832 --- /dev/null +++ b/Documentation/translations/it_IT/process/6.Followthrough.rst @@ -0,0 +1,240 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/6.Followthrough.rst <development_followthrough>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_followthrough: + +============= +Completamento +============= + +A questo punto, avete seguito le linee guida fino a questo punto e, con +l'aggiunta delle vostre capacità ingegneristiche, avete pubblicato una serie +perfetta di patch. Uno dei più grandi errori che possono essere commessi +persino da sviluppatori kernel esperti è quello di concludere che il +lavoro sia ormai finito. In verità, la pubblicazione delle patch +simboleggia una transizione alla fase successiva del processo, con, +probabilmente, ancora un po' di lavoro da fare. + +È raro che una modifica sia così bella alla sua prima pubblicazione che non +ci sia alcuno spazio di miglioramento. Il programma di sviluppo del kernel +riconosce questo fatto e quindi, è fortemente orientato al miglioramento +del codice pubblicato. Voi, in qualità di autori del codice, dovrete +lavorare con la comunità del kernel per assicurare che il vostro codice +mantenga gli standard qualitativi richiesti. Un fallimento in questo +processo è quasi come impedire l'inclusione delle vostre patch nel +ramo principale. + +Lavorare con i revisori +======================= + +Una patch che abbia una certa rilevanza avrà ricevuto numerosi commenti +da parte di altri sviluppatori dato che avranno revisionato il codice. +Lavorare con i revisori può rivelarsi, per molti sviluppatori, la parte +più intimidatoria del processo di sviluppo del kernel. La vita può esservi +resa molto più facile se tenete presente alcuni dettagli: + + - Se avete descritto la vostra modifica correttamente, i revisori ne + comprenderanno il valore e il perché vi siete presi il disturbo di + scriverla. Ma tale valore non li tratterrà dal porvi una domanda + fondamentale: come verrà mantenuto questo codice nel kernel nei prossimi + cinque o dieci anni? Molti dei cambiamenti che potrebbero esservi + richiesti - da piccoli problemi di stile a sostanziali ristesure - + vengono dalla consapevolezza che Linux resterà in circolazione e in + continuo sviluppo ancora per diverse decadi. + + - La revisione del codice è un duro lavoro, ed è un mestiere poco + riconosciuto; le persone ricordano chi ha scritto il codice, ma meno + fama è attribuita a chi lo ha revisionato. Quindi i revisori potrebbero + divenire burberi, specialmente quando vendono i medesimi errori venire + fatti ancora e ancora. Se ricevete una revisione che vi sembra abbia + un tono arrabbiato, insultante o addirittura offensivo, resistente alla + tentazione di rispondere a tono. La revisione riguarda il codice e non + la persona, e i revisori non vi stanno attaccando personalmente. + + - Similarmente, i revisori del codice non stanno cercando di promuovere + i loro interessi a vostre spese. Gli sviluppatori del kernel spesso si + aspettano di lavorare sul kernel per anni, ma sanno che il loro datore + di lavoro può cambiare. Davvero, senza praticamente eccezioni, loro + stanno lavorando per la creazione del miglior kernel possibile; non + stanno cercando di creare un disagio ad aziende concorrenti. + +Quello che si sta cercando di dire è che, quando i revisori vi inviano degli +appunti dovete fare attenzione alle osservazioni tecniche che vi stanno +facendo. Non lasciate che il loro modo di esprimersi o il vostro orgoglio +impediscano che ciò accada. Quando avete dei suggerimenti sulla revisione, +prendetevi il tempo per comprendere cosa il revisore stia cercando di +comunicarvi. Se possibile, sistemate le cose che il revisore vi chiede di +modificare. E rispondete al revisore ringraziandolo e spiegando come +intendete fare. + +Notate che non dovete per forza essere d'accordo con ogni singola modifica +suggerita dai revisori. Se credete che il revisore non abbia compreso +il vostro codice, spiegateglielo. Se avete un'obiezione tecnica da fargli +su di una modifica suggerita, spiegatela inserendo anche la vostra soluzione +al problema. Se la vostra spiegazione ha senso, il revisore la accetterà. +Tuttavia, la vostra motivazione potrebbe non essere del tutto persuasiva, +specialmente se altri iniziano ad essere d'accordo con il revisore. +Prendetevi quindi un po' di tempo per pensare ancora alla cosa. Può risultare +facile essere accecati dalla propria soluzione al punto che non realizzate che +c'è qualcosa di fondamentalmente sbagliato o, magari, non state nemmeno +risolvendo il problema giusto. + +Andrew Morton suggerisce che ogni suggerimento di revisione che non è +presente nella modifica del codice dovrebbe essere inserito in un commento +aggiuntivo; ciò può essere d'aiuto ai futuri revisori nell'evitare domande +che sorgono al primo sguardo. + +Un errore fatale è quello di ignorare i commenti di revisione nella speranza +che se ne andranno. Non andranno via. Se pubblicherete nuovamente il +codice senza aver risposto ai commenti ricevuti, probabilmente le vostre +modifiche non andranno da nessuna parte. + +Parlando di ripubblicazione del codice: per favore tenete a mente che i +revisori non ricorderanno tutti i dettagli del codice che avete pubblicato +l'ultima volta. Quindi è sempre una buona idea quella di ricordare ai +revisori le questioni sollevate precedetemene e come le avete risolte. +I revisori non dovrebbero star lì a cercare all'interno degli archivi per +famigliarizzare con ciò che è stato detto l'ultima volta; se li aiutate +in questo senso, saranno di umore migliore quando riguarderanno il vostro +codice. + +Se invece avete cercato di far tutto correttamente ma le cose continuano +a non andar bene? Molti disaccordi di natura tecnica possono essere risolti +attraverso la discussione, ma ci sono volte dove qualcuno deve prendere +una decisione. Se credete veramente che tale decisione andrà contro di voi +ingiustamente, potete sempre tentare di rivolgervi a qualcuno più +in alto di voi. Per cose di questo genere la persona con più potere è +Andrew Morton. Andrew è una figura molto rispettata all'interno della +comunità di sviluppo del kernel; lui può spesso sbrogliare situazioni che +sembrano irrimediabilmente bloccate. Rivolgersi ad Andrew non deve essere +fatto alla leggera, e non deve essere fatto prima di aver esplorato tutte +le altre alternative. E tenete a mente, ovviamente, che nemmeno lui +potrebbe non essere d'accordo con voi. + +Cosa accade poi +=============== + +Se la modifica è ritenuta un elemento valido da essere aggiunta al kernel, +e una volta che la maggior parte degli appunti dei revisori sono stati +sistemati, il passo successivo solitamente è quello di entrare in un +sottosistema gestito da un manutentore. Come ciò avviene dipende dal +sottosistema medesimo; ogni manutentore ha il proprio modo di fare le cose. +In particolare, ci potrebbero essere diversi sorgenti - uno, magari, dedicato +alle modifiche pianificate per la finestra di fusione successiva, e un altro +per il lavoro di lungo periodo. + +Per le modifiche proposte in aree per le quali non esiste un sottosistema +preciso (modifiche di gestione della memoria, per esempio), i sorgenti di +ripiego finiscono per essere -mm. Ed anche le modifiche che riguardano +più sottosistemi possono finire in quest'ultimo. + +L'inclusione nei sorgenti di un sottosistema può comportare per una patch, +un alto livello di visibilità. Ora altri sviluppatori che stanno lavorando +in quei medesimi sorgenti avranno le vostre modifiche. I sottosistemi +solitamente riforniscono anche Linux-next, rendendo i propri contenuti +visibili all'intera comunità di sviluppo. A questo punto, ci sono buone +possibilità per voi di ricevere ulteriori commenti da un nuovo gruppo di +revisori; anche a questi commenti dovrete rispondere come avete già fatto per +gli altri. + +Ciò che potrebbe accadere a questo punto, in base alla natura della vostra +modifica, riguarda eventuali conflitti con il lavoro svolto da altri. +Nella peggiore delle situazioni, i conflitti più pesanti tra modifiche possono +concludersi con la messa a lato di alcuni dei lavori svolti cosicché le +modifiche restanti possano funzionare ed essere integrate. Altre volte, la +risoluzione dei conflitti richiederà del lavoro con altri sviluppatori e, +possibilmente, lo spostamento di alcune patch da dei sorgenti a degli altri +in modo da assicurare che tutto sia applicato in modo pulito. Questo lavoro +può rivelarsi una spina nel fianco, ma consideratevi fortunati: prima +dell'avvento dei sorgenti linux-next, questi conflitti spesso emergevano solo +durante l'apertura della finestra di integrazione e dovevano essere smaltiti +in fretta. Ora essi possono essere risolti comodamente, prima dell'apertura +della finestra. + +Un giorno, se tutto va bene, vi collegherete e vedrete che la vostra patch +è stata inserita nel ramo principale de kernel. Congratulazioni! Terminati +i festeggiamenti (nel frattempo avrete inserito il vostro nome nel file +MAINTAINERS) vale la pena ricordare una piccola cosa, ma importante: il +lavoro non è ancora finito. L'inserimento nel ramo principale porta con se +nuove sfide. + +Cominciamo con il dire che ora la visibilità della vostra modifica è +ulteriormente cresciuta. Ci potrebbe portare ad una nuova fase di +commenti dagli sviluppatori che non erano ancora a conoscenza della vostra +patch. Ignorarli potrebbe essere allettante dato che non ci sono più +dubbi sull'integrazione della modifica. Resistete a tale tentazione, dovete +mantenervi disponibili agli sviluppatori che hanno domande o suggerimenti +per voi. + +Ancora più importante: l'inclusione nel ramo principale mette il vostro +codice nelle mani di un gruppo di *tester* molto più esteso. Anche se avete +contribuito ad un driver per un hardware che non è ancora disponibile, sarete +sorpresi da quante persone inseriranno il vostro codice nei loro kernel. +E, ovviamente, dove ci sono *tester*, ci saranno anche dei rapporti su +eventuali bachi. + +La peggior specie di rapporti sono quelli che indicano delle regressioni. +Se la vostra modifica causa una regressione, avrete un gran numero di +occhi puntati su di voi; la regressione deve essere sistemata il prima +possibile. Se non vorrete o non sarete capaci di sistemarla (e nessuno +lo farà per voi), la vostra modifica sarà quasi certamente rimossa durante +la fase di stabilizzazione. Oltre alla perdita di tutto il lavoro svolto +per far si che la vostra modifica fosse inserita nel ramo principale, +l'avere una modifica rimossa a causa del fallimento nel sistemare una +regressione, potrebbe rendere più difficile per voi far accettare +il vostro lavoro in futuro. + +Dopo che ogni regressione è stata affrontata, ci potrebbero essere altri +bachi ordinari da "sconfiggere". Il periodo di stabilizzazione è la +vostra migliore opportunità per sistemare questi bachi e assicurarvi che +il debutto del vostro codice nel ramo principale del kernel sia il più solido +possibile. Quindi, per favore, rispondete ai rapporti sui bachi e ponete +rimedio, se possibile, a tutti i problemi. È a questo che serve il periodo +di stabilizzazione; potete iniziare creando nuove fantastiche modifiche +una volta che ogni problema con le vecchie sia stato risolto. + +Non dimenticate che esistono altre pietre miliari che possono generare +rapporti sui bachi: il successivo rilascio stabile, quando una distribuzione +importante usa una versione del kernel nel quale è presente la vostra +modifica, eccetera. Il continuare a rispondere a questi rapporti è fonte di +orgoglio per il vostro lavoro. Se questa non è una sufficiente motivazione, +allora, è anche consigliabile considera che la comunità di sviluppo ricorda +gli sviluppatori che hanno perso interesse per il loro codice una volta +integrato. La prossima volta che pubblicherete una patch, la comunità +la valuterà anche sulla base del fatto che non sarete disponibili a +prendervene cura anche nel futuro. + + +Altre cose che posso accadere +============================= + +Un giorno, potreste aprire la vostra email e vedere che qualcuno vi ha +inviato una patch per il vostro codice. Questo, dopo tutto, è uno dei +vantaggi di avere il vostro codice "là fuori". Se siete d'accordo con +la modifica, potrete anche inoltrarla ad un manutentore di sottosistema +(assicuratevi di includere la riga "From:" cosicché l'attribuzione sia +corretta, e aggiungete una vostra firma "Signed-off-by"), oppure inviate +un "Acked-by:" e lasciate che l'autore originale la invii. + +Se non siete d'accordo con la patch, inviate una risposta educata +spiegando il perché. Se possibile, dite all'autore quali cambiamenti +servirebbero per rendere la patch accettabile da voi. C'è una certa +riluttanza nell'inserire modifiche con un conflitto fra autore +e manutentore del codice, ma solo fino ad un certo punto. Se siete visti +come qualcuno che blocca un buon lavoro senza motivo, quelle patch vi +passeranno oltre e andranno nel ramo principale in ogni caso. Nel kernel +Linux, nessuno ha potere di veto assoluto su alcun codice. Eccezione +fatta per Linus, forse. + +In rarissime occasioni, potreste vedere qualcosa di completamente diverso: +un altro sviluppatore che pubblica una soluzione differente al vostro +problema. A questo punto, c'è una buona probabilità che una delle due +modifiche non verrà integrata, e il "c'ero prima io" non è considerato +un argomento tecnico rilevante. Se la modifica di qualcun'altro rimpiazza +la vostra ed entra nel ramo principale, esiste un unico modo di reagire: +siate contenti che il vostro problema sia stato risolto e andate avanti con +il vostro lavoro. L'avere un vostro lavoro spintonato da parte in questo +modo può essere avvilente e scoraggiante, ma la comunità ricorderà come +avrete reagito anche dopo che avrà dimenticato quale fu la modifica accettata. diff --git a/Documentation/translations/it_IT/process/7.AdvancedTopics.rst b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..cc1cff5d23ae --- /dev/null +++ b/Documentation/translations/it_IT/process/7.AdvancedTopics.rst @@ -0,0 +1,191 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/7.AdvancedTopics.rst <development_advancedtopics>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_development_advancedtopics: + +Argomenti avanzati +================== + +A questo punto, si spera, dovreste avere un'idea su come funziona il processo +di sviluppo. Ma rimane comunque molto da imparare! Questo capitolo copre +alcuni argomenti che potrebbero essere utili per gli sviluppatori che stanno +per diventare parte integrante del processo di sviluppo del kernel. + +Gestire le modifiche con git +----------------------------- + +L'uso di un sistema distribuito per il controllo delle versioni del kernel +ebbe iniziò nel 2002 quando Linux iniziò a provare il programma proprietario +BitKeeper. Nonostante l'uso di BitKeeper fosse opinabile, di certo il suo +approccio alla gestione dei sorgenti non lo era. Un sistema distribuito per +il controllo delle versioni accelerò immediatamente lo sviluppo del kernel. +Oggigiorno, ci sono diverse alternative libere a BitKeeper. Per il meglio o il +peggio, il progetto del kernel ha deciso di usare git per gestire i sorgenti. + +Gestire le modifiche con git può rendere la vita dello sviluppatore molto +più facile, specialmente quando il volume delle modifiche cresce. +Git ha anche i suoi lati taglienti che possono essere pericolosi; è uno +strumento giovane e potente che è ancora in fase di civilizzazione da parte +dei suoi sviluppatori. Questo documento non ha lo scopo di insegnare l'uso +di git ai suoi lettori; ci sarebbe materiale a sufficienza per un lungo +documento al riguardo. Invece, qui ci concentriamo in particolare su come +git è parte del processo di sviluppo del kernel. Gli sviluppatori che +desiderassero diventare agili con git troveranno più informazioni ai +seguenti indirizzi: + + http://git-scm.com/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +e su varie guide che potrete trovare su internet. + +La prima cosa da fare prima di usarlo per produrre patch che saranno +disponibili ad altri, è quella di leggere i siti qui sopra e di acquisire una +base solida su come funziona git. Uno sviluppatore che sappia usare git +dovrebbe essere capace di ottenere una copia del repositorio principale, +esplorare la storia della revisione, registrare le modifiche, usare i rami, +eccetera. Una certa comprensione degli strumenti git per riscrivere la storia +(come ``rebase``) è altrettanto utile. Git ha i propri concetti e la propria +terminologia; un nuovo utente dovrebbe conoscere *refs*, *remote branch*, +*index*, *fast-forward merge*, *push* e *pull*, *detached head*, eccetera. +Il tutto potrebbe essere un po' intimidatorio visto da fuori, ma con un po' +di studio i concetti non saranno così difficili da capire. + +Utilizzare git per produrre patch da sottomettere via email può essere +un buon esercizio da fare mentre si sta prendendo confidenza con lo strumento. + +Quando sarete in grado di creare rami git che siano guardabili da altri, +vi servirà, ovviamente, un server dal quale sia possibile attingere le vostre +modifiche. Se avete un server accessibile da Internet, configurarlo per +eseguire git-daemon è relativamente semplice . Altrimenti, iniziano a +svilupparsi piattaforme che offrono spazi pubblici, e gratuiti (Github, +per esempio). Gli sviluppatori permanenti possono ottenere un account +su kernel.org, ma non è proprio facile da ottenere; per maggiori informazioni +consultate la pagina web http://kernel.org/faq/. + +In git è normale avere a che fare con tanti rami. Ogni linea di sviluppo +può essere separata in "rami per argomenti" e gestiti indipendentemente. +In git i rami sono facilissimi, per cui non c'è motivo per non usarli +in libertà. In ogni caso, non dovreste sviluppare su alcun ramo dal +quale altri potrebbero attingere. I rami disponibili pubblicamente dovrebbero +essere creati con attenzione; integrate patch dai rami di sviluppo +solo quando sono complete e pronte ad essere consegnate - non prima. + +Git offre alcuni strumenti che vi permettono di riscrivere la storia del +vostro sviluppo. Una modifica errata (diciamo, una che rompe la bisezione, +oppure che ha un qualche tipo di baco evidente) può essere corretta sul posto +o fatta sparire completamente dalla storia. Una serie di patch può essere +riscritta come se fosse stata scritta in cima al ramo principale di oggi, +anche se ci avete lavorato per mesi. Le modifiche possono essere spostate +in modo trasparente da un ramo ad un altro. E così via. Un uso giudizioso +di git per revisionare la storia può aiutare nella creazione di una serie +di patch pulite e con meno problemi. + +Un uso eccessivo può portare ad altri tipi di problemi, tuttavia, oltre +alla semplice ossessione per la creazione di una storia del progetto che sia +perfetta. Riscrivere la storia riscriverà le patch contenute in quella +storia, trasformando un kernel verificato (si spera) in uno da verificare. +Ma, oltre a questo, gli sviluppatori non possono collaborare se non condividono +la stessa vista sulla storia del progetto; se riscrivete la storia dalla quale +altri sviluppatori hanno attinto per i loro repositori, renderete la loro vita +molto più difficile. Quindi tenete conto di questa semplice regola generale: +la storia che avete esposto ad altri, generalmente, dovrebbe essere vista come +immutabile. + +Dunque, una volta che il vostro insieme di patch è stato reso disponibile +pubblicamente non dovrebbe essere più sovrascritto. Git tenterà di imporre +questa regola, e si rifiuterà di pubblicare nuove patch che non risultino +essere dirette discendenti di quelle pubblicate in precedenza (in altre parole, +patch che non condividono la stessa storia). È possibile ignorare questo +controllo, e ci saranno momenti in cui sarà davvero necessario riscrivere +un ramo già pubblicato. Un esempio è linux-next dove le patch vengono +spostate da un ramo all'altro al fine di evitare conflitti. Ma questo tipo +d'azione dovrebbe essere un'eccezione. Questo è uno dei motivi per cui lo +sviluppo dovrebbe avvenire in rami privati (che possono essere sovrascritti +quando lo si ritiene necessario) e reso pubblico solo quando è in uno stato +avanzato. + +Man mano che il ramo principale (o altri rami su cui avete basato le +modifiche) avanza, diventa allettante l'idea di integrare tutte le patch +per rimanere sempre aggiornati. Per un ramo privato, il *rebase* può essere +un modo semplice per rimanere aggiornati, ma questa non è un'opzione nel +momento in cui il vostro ramo è stato esposto al mondo intero. +*Merge* occasionali possono essere considerati di buon senso, ma quando +diventano troppo frequenti confondono inutilmente la storia. La tecnica +suggerita in questi casi è quella di fare *merge* raramente, e più in generale +solo nei momenti di rilascio (per esempio gli -rc del ramo principale). +Se siete nervosi circa alcune patch in particolare, potete sempre fare +dei *merge* di test in un ramo privato. In queste situazioni git "rerere" +può essere utile; questo strumento si ricorda come i conflitti di *merge* +furono risolti in passato cosicché non dovrete fare lo stesso lavoro due volte. + +Una delle lamentele più grosse e ricorrenti sull'uso di strumenti come git +è il grande movimento di patch da un repositorio all'altro che rende +facile l'integrazione nel ramo principale di modifiche mediocri, il tutto +sotto il naso dei revisori. Gli sviluppatori del kernel tendono ad essere +scontenti quando vedono succedere queste cose; preparare un ramo git con +patch che non hanno ricevuto alcuna revisione o completamente avulse, potrebbe +influire sulla vostra capacita di proporre, in futuro, l'integrazione dei +vostri rami. Citando Linus + +:: + + Potete inviarmi le vostre patch, ma per far si che io integri una + vostra modifica da git, devo sapere che voi sappiate cosa state + facendo, e ho bisogno di fidarmi *senza* dover passare tutte + le modifiche manualmente una per una. + +(http://lwn.net/Articles/224135/). + +Per evitare queste situazioni, assicuratevi che tutte le patch in un ramo +siano strettamente correlate al tema delle modifiche; un ramo "driver fixes" +non dovrebbe fare modifiche al codice principale per la gestione della memoria. +E, più importante ancora, non usate un repositorio git per tentare di +evitare il processo di revisione. Pubblicate un sommario di quello che il +vostro ramo contiene sulle liste di discussione più opportune, e , quando +sarà il momento, richiedete che il vostro ramo venga integrato in linux-next. + +Se e quando altri inizieranno ad inviarvi patch per essere incluse nel +vostro repositorio, non dovete dimenticare di revisionarle. Inoltre +assicuratevi di mantenerne le informazioni di paternità; al riguardo git "am" +fa del suo meglio, ma potreste dover aggiungere una riga "From:" alla patch +nel caso in cui sia arrivata per vie traverse. + +Quando richiedete l'integrazione, siate certi di fornire tutte le informazioni: +dov'è il vostro repositorio, quale ramo integrare, e quali cambiamenti si +otterranno dall'integrazione. Il comando git request-pull può essere d'aiuto; +preparerà una richiesta nel modo in cui gli altri sviluppatori se l'aspettano, +e verificherà che vi siate ricordati di pubblicare quelle patch su un +server pubblico. + +Revisionare le patch +-------------------- + +Alcuni lettori potrebbero avere obiezioni sulla presenza di questa sezione +negli "argomenti avanzati" sulla base che anche gli sviluppatori principianti +dovrebbero revisionare le patch. É certamente vero che non c'è modo +migliore di imparare come programmare per il kernel che guardare il codice +pubblicato dagli altri. In aggiunta, i revisori sono sempre troppo pochi; +guardando il codice potete apportare un significativo contributo all'intero +processo. + +Revisionare il codice potrebbe risultare intimidatorio, specialmente per i +nuovi arrivati che potrebbero sentirsi un po' nervosi nel questionare +il codice - in pubblico - pubblicato da sviluppatori più esperti. Perfino +il codice scritto dagli sviluppatori più esperti può essere migliorato. +Forse il suggerimento migliore per i revisori (tutti) è questo: formulate +i commenti come domande e non come critiche. Chiedere "Come viene rilasciato +il *lock* in questo percorso?" funziona sempre molto meglio che +"qui la sincronizzazione è sbagliata". + +Diversi sviluppatori revisioneranno il codice con diversi punti di vista. +Alcuni potrebbero concentrarsi principalmente sullo stile del codice e se +alcune linee hanno degli spazio bianchi di troppo. Altri si chiederanno +se accettare una modifica interamente è una cosa positiva per il kernel +o no. E altri ancora si focalizzeranno sui problemi di sincronizzazione, +l'uso eccessivo di *stack*, problemi di sicurezza, duplicazione del codice +in altri contesti, documentazione, effetti negativi sulle prestazioni, cambi +all'ABI dello spazio utente, eccetera. Qualunque tipo di revisione è ben +accetta e di valore, se porta ad avere un codice migliore nel kernel. diff --git a/Documentation/translations/it_IT/process/8.Conclusion.rst b/Documentation/translations/it_IT/process/8.Conclusion.rst new file mode 100644 index 000000000000..039bfc5a4108 --- /dev/null +++ b/Documentation/translations/it_IT/process/8.Conclusion.rst @@ -0,0 +1,85 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/8.Conclusion.rst <development_conclusion>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_conclusion: + +Per maggiori informazioni +========================= + +Esistono numerose fonti di informazioni sullo sviluppo del kernel Linux +e argomenti correlati. Primo tra questi sarà sempre la cartella Documentation +che si trova nei sorgenti kernel. + +Il file :ref:`process/howto.rst <it_process_howto>` è un punto di partenza +importante; :ref:`process/submitting-patches.rst <it_submittingpatches>` e +:ref:`process/submitting-drivers.rst <it_submittingdrivers>` sono +anch'essi qualcosa che tutti gli sviluppatori del kernel dovrebbero leggere. +Molte API interne al kernel sono documentate utilizzando il meccanismo +kerneldoc; "make htmldocs" o "make pdfdocs" possono essere usati per generare +quei documenti in HTML o PDF (sebbene le versioni di TeX di alcune +distribuzioni hanno dei limiti interni e fallisce nel processare +appropriatamente i documenti). + +Diversi siti web approfondiscono lo sviluppo del kernel ad ogni livello +di dettaglio. Il vostro autore vorrebbe umilmente suggerirvi +http://lwn.net/ come fonte; usando l'indice 'kernel' su LWN troverete +molti argomenti specifici sul kernel: + + http://lwn.net/Kernel/Index/ + +Oltre a ciò, una risorsa valida per gli sviluppatori kernel è: + + http://kernelnewbies.org/ + +E, ovviamente, una fonte da non dimenticare è http://kernel.org/, il luogo +definitivo per le informazioni sui rilasci del kernel. + +Ci sono numerosi libri sullo sviluppo del kernel: + + Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro + Rubini, and Greg Kroah-Hartman). In linea all'indirizzo + http://lwn.net/Kernel/LDD3/. + + Linux Kernel Development (Robert Love). + + Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). + +Tutti questi libri soffrono di un errore comune: tendono a risultare in un +certo senso obsoleti dal momento che si trovano in libreria da diverso +tempo. Comunque contengono informazioni abbastanza buone. + +La documentazione per git la troverete su: + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + + + +Conclusioni +=========== + +Congratulazioni a chiunque ce l'abbia fatta a terminare questo documento di +lungo-respiro. Si spera che abbia fornito un'utile comprensione d'insieme +di come il kernel Linux viene sviluppato e di come potete partecipare a +tale processo. + +Infine, quello che conta è partecipare. Qualsiasi progetto software +open-source non è altro che la somma di quello che i suoi contributori +mettono al suo interno. Il kernel Linux è cresciuto velocemente e bene +perché ha ricevuto il supporto di un impressionante gruppo di sviluppatori, +ognuno dei quali sta lavorando per renderlo migliore. Il kernel è un esempio +importante di cosa può essere fatto quando migliaia di persone lavorano +insieme verso un obiettivo comune. + +Il kernel può sempre beneficiare di una larga base di sviluppatori, tuttavia, +c'è sempre molto lavoro da fare. Ma, cosa non meno importante, molti degli +altri partecipanti all'ecosistema Linux possono trarre beneficio attraverso +il contributo al kernel. Inserire codice nel ramo principale è la chiave +per arrivare ad una qualità del codice più alta, bassa manutenzione e +bassi prezzi di distribuzione, alti livelli d'influenza sulla direzione +dello sviluppo del kernel, e molto altro. È una situazione nella quale +tutti coloro che sono coinvolti vincono. Mollate il vostro editor e +raggiungeteci; sarete più che benvenuti. diff --git a/Documentation/translations/it_IT/process/adding-syscalls.rst b/Documentation/translations/it_IT/process/adding-syscalls.rst new file mode 100644 index 000000000000..e0a64b0688a7 --- /dev/null +++ b/Documentation/translations/it_IT/process/adding-syscalls.rst @@ -0,0 +1,643 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/adding-syscalls.rst <addsyscalls>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_addsyscalls: + +Aggiungere una nuova chiamata di sistema +======================================== + +Questo documento descrive quello che è necessario sapere per aggiungere +nuove chiamate di sistema al kernel Linux; questo è da considerarsi come +un'aggiunta ai soliti consigli su come proporre nuove modifiche +:ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>`. + + +Alternative alle chiamate di sistema +------------------------------------ + +La prima considerazione da fare quando si aggiunge una nuova chiamata di +sistema è quella di valutare le alternative. Nonostante le chiamate di sistema +siano il punto di interazione fra spazio utente e kernel più tradizionale ed +ovvio, esistono altre possibilità - scegliete quella che meglio si adatta alle +vostra interfaccia. + + - Se le operazioni coinvolte possono rassomigliare a quelle di un filesystem, + allora potrebbe avere molto più senso la creazione di un nuovo filesystem o + dispositivo. Inoltre, questo rende più facile incapsulare la nuova + funzionalità in un modulo kernel piuttosto che essere sviluppata nel cuore + del kernel. + + - Se la nuova funzionalità prevede operazioni dove il kernel notifica + lo spazio utente su un avvenimento, allora restituire un descrittore + di file all'oggetto corrispondente permette allo spazio utente di + utilizzare ``poll``/``select``/``epoll`` per ricevere quelle notifiche. + - Tuttavia, le operazioni che non si sposano bene con operazioni tipo + :manpage:`read(2)`/:manpage:`write(2)` dovrebbero essere implementate + come chiamate :manpage:`ioctl(2)`, il che potrebbe portare ad un'API in + un qualche modo opaca. + + - Se dovete esporre solo delle informazioni sul sistema, un nuovo nodo in + sysfs (vedere ``Documentation/translations/it_IT/filesystems/sysfs.txt``) o + in procfs potrebbe essere sufficiente. Tuttavia, l'accesso a questi + meccanismi richiede che il filesystem sia montato, il che potrebbe non + essere sempre vero (per esempio, in ambienti come namespace/sandbox/chroot). + Evitate d'aggiungere nuove API in debugfs perché questo non viene + considerata un'interfaccia di 'produzione' verso lo spazio utente. + - Se l'operazione è specifica ad un particolare file o descrittore, allora + potrebbe essere appropriata l'aggiunta di un comando :manpage:`fcntl(2)`. + Tuttavia, :manpage:`fcntl(2)` è una chiamata di sistema multiplatrice che + nasconde una notevole complessità, quindi è ottima solo quando la nuova + funzione assomiglia a quelle già esistenti in :manpage:`fcntl(2)`, oppure + la nuova funzionalità è veramente semplice (per esempio, leggere/scrivere + un semplice flag associato ad un descrittore di file). + - Se l'operazione è specifica ad un particolare processo, allora + potrebbe essere appropriata l'aggiunta di un comando :manpage:`prctl(2)`. + Come per :manpage:`fcntl(2)`, questa chiamata di sistema è un complesso + multiplatore quindi è meglio usarlo per cose molto simili a quelle esistenti + nel comando ``prctl`` oppure per leggere/scrivere un semplice flag relativo + al processo. + + +Progettare l'API: pianificare le estensioni +------------------------------------------- + +Una nuova chiamata di sistema diventerà parte dell'API del kernel, e +dev'essere supportata per un periodo indefinito. Per questo, è davvero +un'ottima idea quella di discutere apertamente l'interfaccia sulla lista +di discussione del kernel, ed è altrettanto importante pianificarne eventuali +estensioni future. + +(Nella tabella delle chiamate di sistema sono disseminati esempi dove questo +non fu fatto, assieme ai corrispondenti aggiornamenti - +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` --quindi imparate dalla storia +del kernel e pianificate le estensioni fin dall'inizio) + +Per semplici chiamate di sistema che accettano solo un paio di argomenti, +il modo migliore di permettere l'estensibilità è quello di includere un +argomento *flags* alla chiamata di sistema. Per assicurarsi che i programmi +dello spazio utente possano usare in sicurezza *flags* con diverse versioni +del kernel, verificate se *flags* contiene un qualsiasi valore sconosciuto, +in qual caso rifiutate la chiamata di sistema (con ``EINVAL``):: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(Se *flags* non viene ancora utilizzato, verificate che l'argomento sia zero) + +Per chiamate di sistema più sofisticate che coinvolgono un numero più grande di +argomenti, il modo migliore è quello di incapsularne la maggior parte in una +struttura dati che verrà passata per puntatore. Questa struttura potrà +funzionare con future estensioni includendo un campo *size*:: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +Fintanto che un qualsiasi campo nuovo, diciamo ``param_4``, è progettato per +offrire il comportamento precedente quando vale zero, allora questo permetterà +di gestire un conflitto di versione in entrambe le direzioni: + + - un vecchio kernel può gestire l'accesso di una versione moderna di un + programma in spazio utente verificando che la memoria oltre la dimensione + della struttura dati attesa sia zero (in pratica verificare che + ``param_4 == 0``). + - un nuovo kernel può gestire l'accesso di una versione vecchia di un + programma in spazio utente estendendo la struttura dati con zeri (in pratica + ``param_4 = 0``). + +Vedere :manpage:`perf_event_open(2)` e la funzione ``perf_copy_attr()`` (in +``kernel/events/core.c``) per un esempio pratico di questo approccio. + + +Progettare l'API: altre considerazioni +-------------------------------------- + +Se la vostra nuova chiamata di sistema permette allo spazio utente di fare +riferimento ad un oggetto del kernel, allora questa dovrebbe usare un +descrittore di file per accesso all'oggetto - non inventatevi nuovi tipi di +accesso da spazio utente quando il kernel ha già dei meccanismi e una semantica +ben definita per utilizzare i descrittori di file. + +Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ritorna un nuovo +descrittore di file, allora l'argomento *flags* dovrebbe includere un valore +equivalente a ``O_CLOEXEC`` per i nuovi descrittori. Questo rende possibile, +nello spazio utente, la chiusura della finestra temporale fra le chiamate a +``xyzzy()`` e ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, dove un inaspettato +``fork()`` o ``execve()`` potrebbe trasferire il descrittore al programma +eseguito (Comunque, resistete alla tentazione di riutilizzare il valore di +``O_CLOEXEC`` dato che è specifico dell'architettura e fa parte di una +enumerazione di flag ``O_*`` che è abbastanza ricca). + +Se la vostra nuova chiamata di sistema ritorna un nuovo descrittore di file, +dovreste considerare che significato avrà l'uso delle chiamate di sistema +della famiglia di :manpage:`poll(2)`. Rendere un descrittore di file pronto +per la lettura o la scrittura è il tipico modo del kernel per notificare lo +spazio utente circa un evento associato all'oggetto del kernel. + +Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` ha un argomento +che è il percorso ad un file:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +dovreste anche considerare se non sia più appropriata una versione +:manpage:`xyzzyat(2)`:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +Questo permette più flessibilità su come lo spazio utente specificherà il file +in questione; in particolare, permette allo spazio utente di richiedere la +funzionalità su un descrittore di file già aperto utilizzando il *flag* +``AT_EMPTY_PATH``, in pratica otterremmo gratuitamente l'operazione +:manpage:`fxyzzy(3)`:: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(Per maggiori dettagli sulla logica delle chiamate \*at(), leggete la pagina +man :manpage:`openat(2)`; per un esempio di AT_EMPTY_PATH, leggere la pagina +man :manpage:`fstatat(2)`). + +Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede un parametro +per descrivere uno scostamento all'interno di un file, usate ``loff_t`` come +tipo cosicché scostamenti a 64-bit potranno essere supportati anche su +architetture a 32-bit. + +Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` prevede l'uso di +funzioni riservate, allora dev'essere gestita da un opportuno bit di privilegio +(verificato con una chiamata a ``capable()``), come descritto nella pagina man +:manpage:`capabilities(7)`. Scegliete un bit di privilegio già esistente per +gestire la funzionalità associata, ma evitate la combinazione di diverse +funzionalità vagamente collegate dietro lo stesso bit, in quanto va contro il +principio di *capabilities* di separare i poteri di root. In particolare, +evitate di aggiungere nuovi usi al fin-troppo-generico privilegio +``CAP_SYS_ADMIN``. + +Se la vostra nuova chiamata di sistema :manpage:`xyzzy(2)` manipola altri +processi oltre a quello chiamato, allora dovrebbe essere limitata (usando +la chiamata ``ptrace_may_access()``) di modo che solo un processo chiamante +con gli stessi permessi del processo in oggetto, o con i necessari privilegi, +possa manipolarlo. + +Infine, state attenti che in alcune architetture non-x86 la vita delle chiamate +di sistema con argomenti a 64-bit viene semplificata se questi argomenti +ricadono in posizioni dispari (pratica, i parametri 1, 3, 5); questo permette +l'uso di coppie contigue di registri a 32-bit. (Questo non conta se gli +argomenti sono parte di una struttura dati che viene passata per puntatore). + + +Proporre l'API +-------------- + +Al fine di rendere le nuove chiamate di sistema di facile revisione, è meglio +che dividiate le modifiche i pezzi separati. Questi dovrebbero includere +almeno le seguenti voci in *commit* distinti (ognuno dei quali sarà descritto +più avanti): + + - l'essenza dell'implementazione della chiamata di sistema, con i prototipi, + i numeri generici, le modifiche al Kconfig e l'implementazione *stub* di + ripiego. + - preparare la nuova chiamata di sistema per un'architettura specifica, + solitamente x86 (ovvero tutti: x86_64, x86_32 e x32). + - un programma di auto-verifica da mettere in ``tools/testing/selftests/`` + che mostri l'uso della chiamata di sistema. + - una bozza di pagina man per la nuova chiamata di sistema. Può essere + scritta nell'email di presentazione, oppure come modifica vera e propria + al repositorio delle pagine man. + +Le proposte di nuove chiamate di sistema, come ogni altro modifica all'API del +kernel, deve essere sottomessa alla lista di discussione +linux-api@vger.kernel.org. + + +Implementazione di chiamate di sistema generiche +------------------------------------------------ + +Il principale punto d'accesso alla vostra nuova chiamata di sistema +:manpage:`xyzzy(2)` verrà chiamato ``sys_xyzzy()``; ma, piuttosto che in modo +esplicito, lo aggiungerete tramite la macro ``SYSCALL_DEFINEn``. La 'n' +indica il numero di argomenti della chiamata di sistema; la macro ha come +argomento il nome della chiamata di sistema, seguito dalle coppie (tipo, nome) +per definire i suoi parametri. L'uso di questa macro permette di avere +i metadati della nuova chiamata di sistema disponibili anche per altri +strumenti. + +Il nuovo punto d'accesso necessita anche del suo prototipo di funzione in +``include/linux/syscalls.h``, marcato come asmlinkage di modo da abbinargli +il modo in cui quelle chiamate di sistema verranno invocate:: + + asmlinkage long sys_xyzzy(...); + +Alcune architetture (per esempio x86) hanno le loro specifiche tabelle di +chiamate di sistema (syscall), ma molte altre architetture condividono una +tabella comune di syscall. Aggiungete alla lista generica la vostra nuova +chiamata di sistema aggiungendo un nuovo elemento alla lista in +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Aggiornate anche il contatore __NR_syscalls di modo che sia coerente con +l'aggiunta della nuove chiamate di sistema; va notato che se più di una nuova +chiamata di sistema viene aggiunga nella stessa finestra di sviluppo, il numero +della vostra nuova syscall potrebbe essere aggiustato al fine di risolvere i +conflitti. + +Il file ``kernel/sys_ni.c`` fornisce le implementazioni *stub* di ripiego che +ritornano ``-ENOSYS``. Aggiungete la vostra nuova chiamata di sistema anche +qui:: + + COND_SYSCALL(xyzzy); + +La vostra nuova funzionalità del kernel, e la chiamata di sistema che la +controlla, dovrebbero essere opzionali. Quindi, aggiungete un'opzione +``CONFIG`` (solitamente in ``init/Kconfig``). Come al solito per le nuove +opzioni ``CONFIG``: + + - Includete una descrizione della nuova funzionalità e della chiamata di + sistema che la controlla. + - Rendete l'opzione dipendente da EXPERT se dev'essere nascosta agli utenti + normali. + - Nel Makefile, rendere tutti i nuovi file sorgenti, che implementano la + nuova funzionalità, dipendenti dall'opzione CONFIG (per esempio + ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``). + - Controllate due volte che sia possibile generare il kernel con la nuova + opzione CONFIG disabilitata. + +Per riassumere, vi serve un *commit* che includa: + + - un'opzione ``CONFIG``per la nuova funzione, normalmente in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` per il punto d'accesso + - il corrispondente prototipo in ``include/linux/syscalls.h`` + - un elemento nella tabella generica in ``include/uapi/asm-generic/unistd.h`` + - *stub* di ripiego in ``kernel/sys_ni.c`` + + +Implementazione delle chiamate di sistema x86 +--------------------------------------------- + +Per collegare la vostra nuova chiamate di sistema alle piattaforme x86, +dovete aggiornate la tabella principale di syscall. Assumendo che la vostra +nuova chiamata di sistema non sia particolarmente speciale (vedere sotto), +dovete aggiungere un elemento *common* (per x86_64 e x32) in +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzzy sys_xyzzy + +e un elemento per *i386* ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy + +Ancora una volta, questi numeri potrebbero essere cambiati se generano +conflitti durante la finestra di integrazione. + + +Chiamate di sistema compatibili (generico) +------------------------------------------ + +Per molte chiamate di sistema, la stessa implementazione a 64-bit può essere +invocata anche quando il programma in spazio utente è a 32-bit; anche se la +chiamata di sistema include esplicitamente un puntatore, questo viene gestito +in modo trasparente. + +Tuttavia, ci sono un paio di situazione dove diventa necessario avere un +livello di gestione della compatibilità per risolvere le differenze di +dimensioni fra 32-bit e 64-bit. + +Il primo caso è quando un kernel a 64-bit supporta anche programmi in spazio +utente a 32-bit, perciò dovrà ispezionare aree della memoria (``__user``) che +potrebbero contenere valori a 32-bit o a 64-bit. In particolar modo, questo +è necessario quando un argomento di una chiamata di sistema è: + + - un puntatore ad un puntatore + - un puntatore ad una struttura dati contenente a sua volta un puntatore + ( ad esempio ``struct iovec __user *``) + - un puntatore ad un tipo intero di dimensione variabile (``time_t``, + ``off_t``, ``long``, ...) + - un puntatore ad una struttura dati contenente un tipo intero di dimensione + variabile. + +Il secondo caso che richiede un livello di gestione della compatibilità è +quando uno degli argomenti di una chiamata a sistema è esplicitamente un tipo +a 64-bit anche su architetture a 32-bit, per esempio ``loff_t`` o ``__u64``. +In questo caso, un valore che arriva ad un kernel a 64-bit da un'applicazione +a 32-bit verrà diviso in due valori a 32-bit che dovranno essere riassemblati +in questo livello di compatibilità. + +(Da notare che non serve questo livello di compatibilità per argomenti che +sono puntatori ad un tipo esplicitamente a 64-bit; per esempio, in +:manpage:`splice(2)` l'argomento di tipo ``loff_t __user *`` non necessita +di una chiamata di sistema ``compat_``) + +La versione compatibile della nostra chiamata di sistema si chiamerà +``compat_sys_xyzzy()``, e viene aggiunta utilizzando la macro +``COMPAT_SYSCALL_DEFINEn()`` (simile a SYSCALL_DEFINEn). Questa versione +dell'implementazione è parte del kernel a 64-bit ma accetta parametri a 32-bit +che trasformerà secondo le necessità (tipicamente, la versione +``compat_sys_`` converte questi valori nello loro corrispondente a 64-bit e +può chiamare la versione ``sys_`` oppure invocare una funzione che implementa +le parti comuni). + +Il punto d'accesso *compat* deve avere il corrispondente prototipo di funzione +in ``include/linux/compat.h``, marcato come asmlinkage di modo da abbinargli +il modo in cui quelle chiamate di sistema verranno invocate:: + + asmlinkage long compat_sys_xyzzy(...); + +Se la chiamata di sistema prevede una struttura dati organizzata in modo +diverso per sistemi a 32-bit e per quelli a 64-bit, diciamo +``struct xyzzy_args``, allora il file d'intestazione +``then the include/linux/compat.h`` deve includere la sua versione +*compatibile* (``struct compat_xyzzy_args``); ogni variabile con +dimensione variabile deve avere il proprio tipo ``compat_`` corrispondente +a quello in ``struct xyzzy_args``. La funzione ``compat_sys_xyzzy()`` +può usare la struttura ``compat_`` per analizzare gli argomenti ricevuti +da una chiamata a 32-bit. + +Per esempio, se avete i seguenti campi:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +nella struttura ``struct xyzzy_args``, allora la struttura +``struct compat_xyzzy_args`` dovrebbe avere:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +La lista generica delle chiamate di sistema ha bisogno di essere +aggiustata al fine di permettere l'uso della versione *compatibile*; +la voce in ``include/uapi/asm-generic/unistd.h`` dovrebbero usare +``__SC_COMP`` piuttosto di ``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +Riassumendo, vi serve: + + - un ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` per il punto d'accesso + *compatibile* + - un prototipo in ``include/linux/compat.h`` + - (se necessario) una struttura di compatibilità a 32-bit in + ``include/linux/compat.h`` + - una voce ``__SC_COMP``, e non ``__SYSCALL``, in + ``include/uapi/asm-generic/unistd.h`` + +Compatibilità delle chiamate di sistema (x86) +--------------------------------------------- + +Per collegare una chiamata di sistema, su un'architettura x86, con la sua +versione *compatibile*, è necessario aggiustare la voce nella tabella +delle syscall. + +Per prima cosa, la voce in ``arch/x86/entry/syscalls/syscall_32.tbl`` prende +un argomento aggiuntivo per indicare che un programma in spazio utente +a 32-bit, eseguito su un kernel a 64-bit, dovrebbe accedere tramite il punto +d'accesso compatibile:: + + 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy + +Secondo, dovete capire cosa dovrebbe succedere alla nuova chiamata di sistema +per la versione dell'ABI x32. Qui C'è una scelta da fare: gli argomenti +possono corrisponde alla versione a 64-bit o a quella a 32-bit. + +Se c'è un puntatore ad un puntatore, la decisione è semplice: x32 è ILP32, +quindi gli argomenti dovrebbero corrispondere a quelli a 32-bit, e la voce in +``arch/x86/entry/syscalls/syscall_64.tbl`` sarà divisa cosicché i programmi +x32 eseguano la chiamata *compatibile*:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy __x32_compat_sys_xyzzy + +Se non ci sono puntatori, allora è preferibile riutilizzare la chiamata di +sistema a 64-bit per l'ABI x32 (e di conseguenza la voce in +arch/x86/entry/syscalls/syscall_64.tbl rimane immutata). + +In ambo i casi, dovreste verificare che i tipi usati dagli argomenti +abbiano un'esatta corrispondenza da x32 (-mx32) al loro equivalente a +32-bit (-m32) o 64-bit (-m64). + + +Chiamate di sistema che ritornano altrove +----------------------------------------- + +Nella maggior parte delle chiamate di sistema, al termine della loro +esecuzione, i programmi in spazio utente riprendono esattamente dal punto +in cui si erano interrotti -- quindi dall'istruzione successiva, con lo +stesso *stack* e con la maggior parte del registri com'erano stati +lasciati prima della chiamata di sistema, e anche con la stessa memoria +virtuale. + +Tuttavia, alcune chiamata di sistema fanno le cose in modo differente. +Potrebbero ritornare ad un punto diverso (``rt_sigreturn``) o cambiare +la memoria in spazio utente (``fork``/``vfork``/``clone``) o perfino +l'architettura del programma (``execve``/``execveat``). + +Per permettere tutto ciò, l'implementazione nel kernel di questo tipo di +chiamate di sistema potrebbero dover salvare e ripristinare registri +aggiuntivi nello *stack* del kernel, permettendo così un controllo completo +su dove e come l'esecuzione dovrà continuare dopo l'esecuzione della +chiamata di sistema. + +Queste saranno specifiche per ogni architettura, ma tipicamente si definiscono +dei punti d'accesso in *assembly* per salvare/ripristinare i registri +aggiuntivi e quindi chiamare il vero punto d'accesso per la chiamata di +sistema. + +Per l'architettura x86_64, questo è implementato come un punto d'accesso +``stub_xyzzy`` in ``arch/x86/entry/entry_64.S``, e la voce nella tabella +di syscall (``arch/x86/entry/syscalls/syscall_64.tbl``) verrà corretta di +conseguenza:: + + 333 common xyzzy stub_xyzzy + +L'equivalente per programmi a 32-bit eseguiti su un kernel a 64-bit viene +normalmente chiamato ``stub32_xyzzy`` e implementato in +``arch/x86/entry/entry_64_compat.S`` con la corrispondente voce nella tabella +di syscall ``arch/x86/entry/syscalls/syscall_32.tbl`` corretta nel +seguente modo:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +Se una chiamata di sistema necessita di un livello di compatibilità (come +nella sezione precedente), allora la versione ``stub32_`` deve invocare +la versione ``compat_sys_`` piuttosto che quella nativa a 64-bit. In aggiunta, +se l'implementazione dell'ABI x32 è diversa da quella x86_64, allora la sua +voce nella tabella di syscall dovrà chiamare uno *stub* che invoca la versione +``compat_sys_``, + +Per completezza, sarebbe carino impostare una mappatura cosicché +*user-mode* Linux (UML) continui a funzionare -- la sua tabella di syscall +farà riferimento a stub_xyzzy, ma UML non include l'implementazione +in ``arch/x86/entry/entry_64.S`` (perché UML simula i registri eccetera). +Correggerlo è semplice, basta aggiungere una #define in +``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Altri dettagli +-------------- + +La maggior parte dei kernel tratta le chiamate di sistema allo stesso modo, +ma possono esserci rare eccezioni per le quali potrebbe essere necessario +l'aggiornamento della vostra chiamata di sistema. + +Il sotto-sistema di controllo (*audit subsystem*) è uno di questi casi +speciali; esso include (per architettura) funzioni che classificano alcuni +tipi di chiamate di sistema -- in particolare apertura dei file +(``open``/``openat``), esecuzione dei programmi (``execve``/``exeveat``) +oppure multiplatori di socket (``socketcall``). Se la vostra nuova chiamata +di sistema è simile ad una di queste, allora il sistema di controllo dovrebbe +essere aggiornato. + +Più in generale, se esiste una chiamata di sistema che è simile alla vostra, +vale la pena fare una ricerca con ``grep`` su tutto il kernel per la chiamata +di sistema esistente per verificare che non ci siano altri casi speciali. + + +Verifica +-------- + +Una nuova chiamata di sistema dev'essere, ovviamente, provata; è utile fornire +ai revisori un programma in spazio utente che mostri l'uso della chiamata di +sistema. Un buon modo per combinare queste cose è quello di aggiungere un +semplice programma di auto-verifica in una nuova cartella in +``tools/testing/selftests/``. + +Per una nuova chiamata di sistema, ovviamente, non ci sarà alcuna funzione +in libc e quindi il programma di verifica dovrà invocarla usando ``syscall()``; +inoltre, se la nuova chiamata di sistema prevede un nuova struttura dati +visibile in spazio utente, il file d'intestazione necessario dev'essere +installato al fine di compilare il programma. + +Assicuratevi che il programma di auto-verifica possa essere eseguito +correttamente su tutte le architetture supportate. Per esempio, verificate che +funzioni quando viene compilato per x86_64 (-m64), x86_32 (-m32) e x32 (-mx32). + +Al fine di una più meticolosa ed estesa verifica della nuova funzionalità, +dovreste considerare l'aggiunta di nuove verifica al progetto 'Linux Test', +oppure al progetto xfstests per cambiamenti relativi al filesystem. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Pagine man +---------- + +Tutte le nuove chiamate di sistema dovrebbero avere una pagina man completa, +idealmente usando i marcatori groff, ma anche il puro testo può andare. Se +state usando groff, è utile che includiate nella email di presentazione una +versione già convertita in formato ASCII: semplificherà la vita dei revisori. + +Le pagine man dovrebbero essere in copia-conoscenza verso +linux-man@vger.kernel.org +Per maggiori dettagli, leggere +https://www.kernel.org/doc/man-pages/patches.html + + +Non invocate chiamate di sistema dal kernel +------------------------------------------- + +Le chiamate di sistema sono, come già detto prima, punti di interazione fra +lo spazio utente e il kernel. Perciò, le chiamate di sistema come +``sys_xyzzy()`` o ``compat_sys_xyzzy()`` dovrebbero essere chiamate solo dallo +spazio utente attraverso la tabella syscall, ma non da nessun altro punto nel +kernel. Se la nuova funzionalità è utile all'interno del kernel, per esempio +dev'essere condivisa fra una vecchia e una nuova chiamata di sistema o +dev'essere utilizzata da una chiamata di sistema e la sua variante compatibile, +allora dev'essere implementata come una funzione di supporto +(*helper function*) (per esempio ``kern_xyzzy()``). Questa funzione potrà +essere chiamata dallo *stub* (``sys_xyzzy()``), dalla variante compatibile +(``compat_sys_xyzzy()``), e/o da altri parti del kernel. + +Sui sistemi x86 a 64-bit, a partire dalla versione v4.17 è un requisito +fondamentale quello di non invocare chiamate di sistema all'interno del kernel. +Esso usa una diversa convenzione per l'invocazione di chiamate di sistema dove +``struct pt_regs`` viene decodificata al volo in una funzione che racchiude +la chiamata di sistema la quale verrà eseguita successivamente. +Questo significa che verranno passati solo i parametri che sono davvero +necessari ad una specifica chiamata di sistema, invece che riempire ogni volta +6 registri del processore con contenuti presi dallo spazio utente (potrebbe +causare seri problemi nella sequenza di chiamate). + +Inoltre, le regole su come i dati possano essere usati potrebbero differire +fra il kernel e l'utente. Questo è un altro motivo per cui invocare +``sys_xyzzy()`` è generalmente una brutta idea. + +Eccezioni a questa regola vengono accettate solo per funzioni d'architetture +che surclassano quelle generiche, per funzioni d'architettura di compatibilità, +o per altro codice in arch/ + + +Riferimenti e fonti +------------------- + + - Articolo di Michael Kerris su LWN sull'uso dell'argomento flags nelle + chiamate di sistema: https://lwn.net/Articles/585415/ + - Articolo di Michael Kerris su LWN su come gestire flag sconosciuti in + una chiamata di sistema: https://lwn.net/Articles/588444/ + - Articolo di Jake Edge su LWN che descrive i limiti degli argomenti a 64-bit + delle chiamate di sistema: https://lwn.net/Articles/311630/ + - Una coppia di articoli di David Drysdale che descrivono i dettagli del + percorso implementativo di una chiamata di sistema per la versione v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Requisiti specifici alle architetture sono discussi nella pagina man + :manpage:`syscall(2)` : + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collezione di email di Linux Torvalds sui problemi relativi a ``ioctl()``: + http://yarchive.net/comp/linux/ioctl.html + - "Come non inventare interfacce del kernel", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - Articolo di Michael Kerris su LWN sull'evitare nuovi usi di CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Raccomandazioni da Andrew Morton circa il fatto che tutte le informazioni + su una nuova chiamata di sistema dovrebbero essere contenute nello stesso + filone di discussione di email: https://lkml.org/lkml/2014/7/24/641 + - Raccomandazioni da Michael Kerrisk circa il fatto che le nuove chiamate di + sistema dovrebbero avere una pagina man: https://lkml.org/lkml/2014/6/13/309 + - Consigli da Thomas Gleixner sul fatto che il collegamento all'architettura + x86 dovrebbe avvenire in un *commit* differente: + https://lkml.org/lkml/2014/11/19/254 + - Consigli da Greg Kroah-Hartman circa la bontà d'avere una pagina man e un + programma di auto-verifica per le nuove chiamate di sistema: + https://lkml.org/lkml/2014/3/19/710 + - Discussione di Michael Kerrisk sulle nuove chiamate di sistema contro + le estensioni :manpage:`prctl(2)`: https://lkml.org/lkml/2014/6/3/411 + - Consigli da Ingo Molnar che le chiamate di sistema con più argomenti + dovrebbero incapsularli in una struttura che includa un argomento + *size* per garantire l'estensibilità futura: + https://lkml.org/lkml/2015/7/30/117 + - Un certo numero di casi strani emersi dall'uso (riuso) dei flag O_*: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Raccomandazioni da Greg Kroah-Hartman sul fatto che i flag sconosciuti dovrebbero + essere controllati: https://lkml.org/lkml/2014/7/17/577 + - Raccomandazioni da Linus Torvalds che le chiamate di sistema x32 dovrebbero + favorire la compatibilità con le versioni a 64-bit piuttosto che quelle a 32-bit: + https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/translations/it_IT/process/applying-patches.rst b/Documentation/translations/it_IT/process/applying-patches.rst new file mode 100644 index 000000000000..f5e9c7d0b16d --- /dev/null +++ b/Documentation/translations/it_IT/process/applying-patches.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/applying-patches.rst <applying_patches>` + + +.. _it_applying_patches: + +Applicare modifiche al kernel Linux +=================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst new file mode 100644 index 000000000000..956cf95a1214 --- /dev/null +++ b/Documentation/translations/it_IT/process/changes.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/changes.rst <changes>` + +.. _it_changes: + +Requisiti minimi per compilare il kernel +++++++++++++++++++++++++++++++++++++++++ + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/clang-format.rst b/Documentation/translations/it_IT/process/clang-format.rst new file mode 100644 index 000000000000..77eac809a639 --- /dev/null +++ b/Documentation/translations/it_IT/process/clang-format.rst @@ -0,0 +1,197 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/clang-format.rst <clangformat>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_clangformat: + +clang-format +============ +``clang-format`` è uno strumento per formattare codice C/C++/... secondo +un gruppo di regole ed euristiche. Come tutti gli strumenti, non è perfetto +e non copre tutti i singoli casi, ma è abbastanza buono per essere utile. + +``clang-format`` può essere usato per diversi fini: + + - Per riformattare rapidamente un blocco di codice secondo lo stile del + kernel. Particolarmente utile quando si sposta del codice e lo si + allinea/ordina. Vedere it_clangformatreformat_. + + - Identificare errori di stile, refusi e possibili miglioramenti nei + file che mantieni, le modifiche che revisioni, le differenze, + eccetera. Vedere it_clangformatreview_. + + - Ti aiuta a seguire lo stile del codice, particolarmente utile per i + nuovi arrivati o per coloro che lavorano allo stesso tempo su diversi + progetti con stili di codifica differenti. + +Il suo file di configurazione è ``.clang-format`` e si trova nella cartella +principale dei sorgenti del kernel. Le regole scritte in quel file tentano +di approssimare le lo stile di codifica del kernel. Si tenta anche di seguire +il più possibile +:ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>`. +Dato che non tutto il kernel segue lo stesso stile, potreste voler aggiustare +le regole di base per un particolare sottosistema o cartella. Per farlo, +potete sovrascriverle scrivendole in un altro file ``.clang-format`` in +una sottocartella. + +Questo strumento è già stato incluso da molto tempo nelle distribuzioni +Linux più popolari. Cercate ``clang-format`` nel vostro repositorio. +Altrimenti, potete scaricare una versione pre-generata dei binari di LLVM/clang +oppure generarlo dai codici sorgenti: + + http://releases.llvm.org/download.html + +Troverete più informazioni ai seguenti indirizzi: + + https://clang.llvm.org/docs/ClangFormat.html + + https://clang.llvm.org/docs/ClangFormatStyleOptions.html + + +.. _it_clangformatreview: + +Revisionare lo stile di codifica per file e modifiche +----------------------------------------------------- + +Eseguendo questo programma, potrete revisionare un intero sottosistema, +cartella o singoli file alla ricerca di errori di stile, refusi o +miglioramenti. + +Per farlo, potete eseguire qualcosa del genere:: + + # Make sure your working directory is clean! + clang-format -i kernel/*.[ch] + +E poi date un'occhiata a *git diff*. + +Osservare le righe di questo diff è utile a migliorare/aggiustare +le opzioni di stile nel file di configurazione; così come per verificare +le nuove funzionalità/versioni di ``clang-format``. + +``clang-format`` è in grado di leggere diversi diff unificati, quindi +potrete revisionare facilmente delle modifiche e *git diff*. +La documentazione si trova al seguente indirizzo: + + https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting + +Per evitare che ``clang-format`` formatti alcune parti di un file, potete +scrivere nel codice:: + + int formatted_code; + // clang-format off + void unformatted_code ; + // clang-format on + void formatted_code_again; + +Nonostante si attraente l'idea di utilizzarlo per mantenere un file +sempre in sintonia con ``clang-format``, specialmente per file nuovi o +se siete un manutentore, ricordatevi che altre persone potrebbero usare +una versione diversa di ``clang-format`` oppure non utilizzarlo del tutto. +Quindi, dovreste trattenervi dall'usare questi marcatori nel codice del +kernel; almeno finché non vediamo che ``clang-format`` è diventato largamente +utilizzato. + + +.. _it_clangformatreformat: + +Riformattare blocchi di codice +------------------------------ + +Utilizzando dei plugin per il vostro editor, potete riformattare una +blocco (selezione) di codice con una singola combinazione di tasti. +Questo è particolarmente utile: quando si riorganizza il codice, per codice +complesso, macro multi-riga (e allineare le loro "barre"), eccetera. + +Ricordatevi che potete sempre aggiustare le modifiche in quei casi dove +questo strumento non ha fatto un buon lavoro. Ma come prima approssimazione, +può essere davvero molto utile. + +Questo programma si integra con molti dei più popolari editor. Alcuni di +essi come vim, emacs, BBEdit, Visaul Studio, lo supportano direttamente. +Al seguente indirizzo troverete le istruzioni: + + https://clang.llvm.org/docs/ClangFormat.html + +Per Atom, Eclipse, Sublime Text, Visual Studio Code, XCode e altri editor +e IDEs dovreste essere in grado di trovare dei plugin pronti all'uso. + +Per questo caso d'uso, considerate l'uso di un secondo ``.clang-format`` +che potete personalizzare con le vostre opzioni. +Consultare it_clangformatextra_. + + +.. _it_clangformatmissing: + +Cose non supportate +------------------- + +``clang-format`` non ha il supporto per alcune cose che sono comuni nel +codice del kernel. Sono facili da ricordare; quindi, se lo usate +regolarmente, imparerete rapidamente a evitare/ignorare certi problemi. + +In particolare, quelli più comuni che noterete sono: + + - Allineamento di ``#define`` su una singola riga, per esempio:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + contro:: + + #define TRACING_MAP_BITS_DEFAULT 11 + #define TRACING_MAP_BITS_MAX 17 + #define TRACING_MAP_BITS_MIN 7 + + - Allineamento dei valori iniziali, per esempio:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + contro:: + + static const struct file_operations uprobe_events_ops = { + .owner = THIS_MODULE, + .open = probes_open, + .read = seq_read, + .llseek = seq_lseek, + .release = seq_release, + .write = probes_write, + }; + + +.. _it_clangformatextra: + +Funzionalità e opzioni aggiuntive +--------------------------------- + +Al fine di minimizzare le differenze fra il codice attuale e l'output +del programma, alcune opzioni di stile e funzionalità non sono abilitate +nella configurazione base. In altre parole, lo scopo è di rendere le +differenze le più piccole possibili, permettendo la semplificazione +della revisione di file, differenze e modifiche. + +In altri casi (per esempio un particolare sottosistema/cartella/file), lo +stile del kernel potrebbe essere diverso e abilitare alcune di queste +opzioni potrebbe dare risultati migliori. + +Per esempio: + + - Allineare assegnamenti (``AlignConsecutiveAssignments``). + + - Allineare dichiarazioni (``AlignConsecutiveDeclarations``). + + - Riorganizzare il testo nei commenti (``ReflowComments``). + + - Ordinare gli ``#include`` (``SortIncludes``). + +Piuttosto che per interi file, solitamente sono utili per la riformattazione +di singoli blocchi. In alternativa, potete creare un altro file +``.clang-format`` da utilizzare con il vostro editor/IDE. diff --git a/Documentation/translations/it_IT/process/code-of-conduct.rst b/Documentation/translations/it_IT/process/code-of-conduct.rst new file mode 100644 index 000000000000..7dbd7f55f37c --- /dev/null +++ b/Documentation/translations/it_IT/process/code-of-conduct.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/code-of-conduct.rst <code_of_conduct>` + +.. _it_code_of_conduct: + +Accordo dei contributori sul codice di condotta ++++++++++++++++++++++++++++++++++++++++++++++++ + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst new file mode 100644 index 000000000000..b707bdbe178c --- /dev/null +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -0,0 +1,1094 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/coding-style.rst <codingstyle>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_codingstyle: + +Stile del codice per il kernel Linux +==================================== + +Questo è un breve documento che descrive lo stile di codice preferito per +il kernel Linux. Lo stile di codifica è molto personale e non voglio +**forzare** nessuno ad accettare il mio, ma questo stile è quello che +dev'essere usato per qualsiasi cosa che io sia in grado di mantenere, e l'ho +preferito anche per molte altre cose. Per favore, almeno tenete in +considerazione le osservazioni espresse qui. + +La prima cosa che suggerisco è quella di stamparsi una copia degli standard +di codifica GNU e di NON leggerla. Bruciatela, è un grande gesto simbolico. + +Comunque, ecco i punti: + +1) Indentazione +--------------- + +La tabulazione (tab) è di 8 caratteri e così anche le indentazioni. Ci sono +alcuni movimenti di eretici che vorrebbero l'indentazione a 4 (o perfino 2!) +caratteri di profondità, che è simile al tentativo di definire il valore del +pi-greco a 3. + +Motivazione: l'idea dell'indentazione è di definire chiaramente dove un blocco +di controllo inizia e finisce. Specialmente quando siete rimasti a guardare lo +schermo per 20 ore a file, troverete molto più facile capire i livelli di +indentazione se questi sono larghi. + +Ora, alcuni rivendicano che un'indentazione da 8 caratteri sposta il codice +troppo a destra e che quindi rende difficile la lettura su schermi a 80 +caratteri. La risposta a questa affermazione è che se vi servono più di 3 +livelli di indentazione, siete comunque fregati e dovreste correggere il vostro +programma. + +In breve, l'indentazione ad 8 caratteri rende più facile la lettura, e in +aggiunta vi avvisa quando state annidando troppo le vostre funzioni. +Tenete ben a mente questo avviso. + +Al fine di facilitare l'indentazione del costrutto switch, si preferisce +allineare sulla stessa colonna la parola chiave ``switch`` e i suoi +subordinati ``case``. In questo modo si evita una doppia indentazione per +i ``case``. Un esempio.: + +.. 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; + } + +A meno che non vogliate nascondere qualcosa, non mettete più istruzioni sulla +stessa riga: + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +né mettete più assegnamenti sulla stessa riga. Lo stile del kernel +è ultrasemplice. Evitate espressioni intricate. + +Al di fuori dei commenti, della documentazione ed escludendo i Kconfig, gli +spazi non vengono mai usati per l'indentazione, e l'esempio qui sopra è +volutamente errato. + +Procuratevi un buon editor di testo e non lasciate spazi bianchi alla fine +delle righe. + + +2) Spezzare righe lunghe e stringhe +----------------------------------- + +Lo stile del codice riguarda la leggibilità e la manutenibilità utilizzando +strumenti comuni. + +Il limite delle righe è di 80 colonne e questo e un limite fortemente +desiderato. + +Espressioni più lunghe di 80 colonne saranno spezzettate in pezzi più piccoli, +a meno che eccedere le 80 colonne non aiuti ad aumentare la leggibilità senza +nascondere informazioni. I pezzi derivati sono sostanzialmente più corti degli +originali e vengono posizionati più a destra. Lo stesso si applica, nei file +d'intestazione, alle funzioni con una lista di argomenti molto lunga. Tuttavia, +non spezzettate mai le stringhe visibili agli utenti come i messaggi di +printk, questo perché inibireste la possibilità d'utilizzare grep per cercarle. + +3) Posizionamento di parentesi graffe e spazi +--------------------------------------------- + +Un altro problema che s'affronta sempre quando si parla di stile in C è +il posizionamento delle parentesi graffe. Al contrario della dimensione +dell'indentazione, non ci sono motivi tecnici sulla base dei quali scegliere +una strategia di posizionamento o un'altra; ma il modo qui preferito, +come mostratoci dai profeti Kernighan e Ritchie, è quello di +posizionare la parentesi graffa di apertura per ultima sulla riga, e quella +di chiusura per prima su una nuova riga, così: + +.. code-block:: c + + if (x is true) { + we do y + } + +Questo è valido per tutte le espressioni che non siano funzioni (if, switch, +for, while, do). Per esempio: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +Tuttavia, c'è il caso speciale, le funzioni: queste hanno la parentesi graffa +di apertura all'inizio della riga successiva, quindi: + +.. code-block:: c + + int function(int x) + { + body of function + } + +Eretici da tutto il mondo affermano che questa incoerenza è ... +insomma ... incoerente, ma tutte le persone ragionevoli sanno che (a) +K&R hanno **ragione** e (b) K&R hanno ragione. A parte questo, le funzioni +sono comunque speciali (non potete annidarle in C). + +Notate che la graffa di chiusura è da sola su una riga propria, ad +**eccezione** di quei casi dove è seguita dalla continuazione della stessa +espressione, in pratica ``while`` nell'espressione do-while, oppure ``else`` +nell'espressione if-else, come questo: + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +e + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Motivazione: K&R. + +Inoltre, notate che questo posizionamento delle graffe minimizza il numero +di righe vuote senza perdere di leggibilità. In questo modo, dato che le +righe sul vostro schermo non sono una risorsa illimitata (pensate ad uno +terminale con 25 righe), avrete delle righe vuote da riempire con dei +commenti. + +Non usate inutilmente le graffe dove una singola espressione è sufficiente. + +.. code-block:: c + + if (condition) + action(); + +e + +.. code-block:: none + + if (condition) + do_this(); + else + do_that(); + +Questo non vale nel caso in cui solo un ramo dell'espressione if-else +contiene una sola espressione; in quest'ultimo caso usate le graffe per +entrambe i rami: + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +Inoltre, usate le graffe se un ciclo contiene più di una semplice istruzione: + +.. code-block:: c + + while (condition) { + if (test) + do_something(); + } + +3.1) Spazi +********** + +Lo stile del kernel Linux per quanto riguarda gli spazi, dipende +(principalmente) dalle funzioni e dalle parole chiave. Usate una spazio dopo +(quasi tutte) le parole chiave. L'eccezioni più evidenti sono sizeof, typeof, +alignof, e __attribute__, il cui aspetto è molto simile a quello delle +funzioni (e in Linux, solitamente, sono usate con le parentesi, anche se il +linguaggio non lo richiede; come ``sizeof info`` dopo aver dichiarato +``struct fileinfo info``). + +Quindi utilizzate uno spazio dopo le seguenti parole chiave:: + + if, switch, case, for, do, while + +ma non con sizeof, typeof, alignof, o __attribute__. Ad esempio, + +.. code-block:: c + + + s = sizeof(struct file); + +Non aggiungete spazi attorno (dentro) ad un'espressione fra parentesi. Questo +esempio è **brutto**: + +.. code-block:: c + + + s = sizeof( struct file ); + +Quando dichiarate un puntatore ad una variabile o una funzione che ritorna un +puntatore, il posto suggerito per l'asterisco ``*`` è adiacente al nome della +variabile o della funzione, e non adiacente al nome del tipo. Esempi: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Usate uno spazio attorno (da ogni parte) alla maggior parte degli operatori +binari o ternari, come i seguenti:: + + = + - < > * / % | & ^ <= >= == != ? : + +ma non mettete spazi dopo gli operatori unari:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +nessuno spazio dopo l'operatore unario suffisso di incremento o decremento:: + + ++ -- + +nessuno spazio dopo l'operatore unario prefisso di incremento o decremento:: + + ++ -- + +e nessuno spazio attorno agli operatori dei membri di una struttura ``.`` e +``->``. + +Non lasciate spazi bianchi alla fine delle righe. Alcuni editor con +l'indentazione ``furba`` inseriranno gli spazi bianchi all'inizio di una nuova +riga in modo appropriato, quindi potrete scrivere la riga di codice successiva +immediatamente. Tuttavia, alcuni di questi stessi editor non rimuovono +questi spazi bianchi quando non scrivete nulla sulla nuova riga, ad esempio +perché volete lasciare una riga vuota. Il risultato è che finirete per avere +delle righe che contengono spazi bianchi in coda. + +Git vi avviserà delle modifiche che aggiungono questi spazi vuoti di fine riga, +e può opzionalmente rimuoverli per conto vostro; tuttavia, se state applicando +una serie di modifiche, questo potrebbe far fallire delle modifiche successive +perché il contesto delle righe verrà cambiato. + +4) Assegnare nomi +----------------- + +C è un linguaggio spartano, e così dovrebbero esserlo i vostri nomi. Al +contrario dei programmatori Modula-2 o Pascal, i programmatori C non usano +nomi graziosi come ThisVariableIsATemporaryCounter. Un programmatore C +chiamerebbe questa variabile ``tmp``, che è molto più facile da scrivere e +non è una delle più difficili da capire. + +TUTTAVIA, nonostante i nomi con notazione mista siano da condannare, i nomi +descrittivi per variabili globali sono un dovere. Chiamare una funzione +globale ``pippo`` è un insulto. + +Le variabili GLOBALI (da usare solo se vi servono **davvero**) devono avere +dei nomi descrittivi, così come le funzioni globali. Se avete una funzione +che conta gli utenti attivi, dovreste chiamarla ``count_active_users()`` o +qualcosa di simile, **non** dovreste chiamarla ``cntusr()``. + +Codificare il tipo di funzione nel suo nome (quella cosa chiamata notazione +ungherese) fa male al cervello - il compilatore conosce comunque il tipo e +può verificarli, e inoltre confonde i programmatori. Non c'è da +sorprendersi che MicroSoft faccia programmi bacati. + +Le variabili LOCALI dovrebbero avere nomi corti, e significativi. Se avete +un qualsiasi contatore di ciclo, probabilmente sarà chiamato ``i``. +Chiamarlo ``loop_counter`` non è produttivo, non ci sono possibilità che +``i`` possa non essere capito. Analogamente, ``tmp`` può essere una qualsiasi +variabile che viene usata per salvare temporaneamente un valore. + +Se avete paura di fare casino coi nomi delle vostre variabili locali, allora +avete un altro problema che è chiamato sindrome dello squilibrio dell'ormone +della crescita delle funzioni. Vedere il capitolo 6 (funzioni). + +5) Definizione di tipi (typedef) +-------------------------------- + +Per favore non usate cose come ``vps_t``. +Usare il typedef per strutture e puntatori è uno **sbaglio**. Quando vedete: + +.. code-block:: c + + vps_t a; + +nei sorgenti, cosa significa? +Se, invece, dicesse: + +.. code-block:: c + + struct virtual_container *a; + +potreste dire cos'è effettivamente ``a``. + +Molte persone pensano che la definizione dei tipi ``migliori la leggibilità``. +Non molto. Sono utili per: + + (a) gli oggetti completamente opachi (dove typedef viene proprio usato allo + scopo di **nascondere** cosa sia davvero l'oggetto). + + Esempio: ``pte_t`` eccetera sono oggetti opachi che potete usare solamente + con le loro funzioni accessorie. + + .. note:: + Gli oggetti opachi e le ``funzioni accessorie`` non sono, di per se, + una bella cosa. Il motivo per cui abbiamo cose come pte_t eccetera è + che davvero non c'è alcuna informazione portabile. + + (b) i tipi chiaramente interi, dove l'astrazione **aiuta** ad evitare + confusione sul fatto che siano ``int`` oppure ``long``. + + u8/u16/u32 sono typedef perfettamente accettabili, anche se ricadono + nella categoria (d) piuttosto che in questa. + + .. note:: + + Ancora - dev'esserci una **ragione** per farlo. Se qualcosa è + ``unsigned long``, non c'è alcun bisogno di avere: + + typedef unsigned long myfalgs_t; + + ma se ci sono chiare circostanze in cui potrebbe essere ``unsigned int`` + e in altre configurazioni ``unsigned long``, allora certamente typedef + è una buona scelta. + + (c) quando di rado create letteralmente dei **nuovi** tipi su cui effettuare + verifiche. + + (d) circostanze eccezionali, in cui si definiscono nuovi tipi identici a + quelli definiti dallo standard C99. + + Nonostante ci voglia poco tempo per abituare occhi e cervello all'uso dei + tipi standard come ``uint32_t``, alcune persone ne obiettano l'uso. + + Perciò, i tipi specifici di Linux ``u8/u16/u32/u64`` e i loro equivalenti + con segno, identici ai tipi standard, sono permessi- tuttavia, non sono + obbligatori per il nuovo codice. + + (e) i tipi sicuri nella spazio utente. + + In alcune strutture dati visibili dallo spazio utente non possiamo + richiedere l'uso dei tipi C99 e nemmeno i vari ``u32`` descritti prima. + Perciò, utilizziamo __u32 e tipi simili in tutte le strutture dati + condivise con lo spazio utente. + +Magari ci sono altri casi validi, ma la regola di base dovrebbe essere di +non usare MAI MAI un typedef a meno che non rientri in una delle regole +descritte qui. + +In generale, un puntatore, o una struttura a cui si ha accesso diretto in +modo ragionevole, non dovrebbero **mai** essere definite con un typedef. + +6) Funzioni +----------- + +Le funzioni dovrebbero essere brevi e carine, e fare una cosa sola. Dovrebbero +occupare uno o due schermi di testo (come tutti sappiamo, la dimensione +di uno schermo secondo ISO/ANSI è di 80x24), e fare una cosa sola e bene. + +La massima lunghezza di una funziona è inversamente proporzionale alla sua +complessità e al livello di indentazione di quella funzione. Quindi, se avete +una funzione che è concettualmente semplice ma che è implementata come un +lunga (ma semplice) sequenza di caso-istruzione, dove avete molte piccole cose +per molti casi differenti, allora va bene avere funzioni più lunghe. + +Comunque, se avete una funzione complessa e sospettate che uno studente +non particolarmente dotato del primo anno delle scuole superiori potrebbe +non capire cosa faccia la funzione, allora dovreste attenervi strettamente ai +limiti. Usate funzioni di supporto con nomi descrittivi (potete chiedere al +compilatore di renderle inline se credete che sia necessario per le +prestazioni, e probabilmente farà un lavoro migliore di quanto avreste potuto +fare voi). + +Un'altra misura delle funzioni sono il numero di variabili locali. Non +dovrebbero eccedere le 5-10, oppure state sbagliando qualcosa. Ripensate la +funzione, e dividetela in pezzettini. Generalmente, un cervello umano può +seguire facilmente circa 7 cose diverse, di più lo confonderebbe. Lo sai +d'essere brillante, ma magari vorresti riuscire a capire cos'avevi fatto due +settimane prima. + +Nei file sorgenti, separate le funzioni con una riga vuota. Se la funzione è +esportata, la macro **EXPORT** per questa funzione deve seguire immediatamente +la riga della parentesi graffa di chiusura. Ad esempio: + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +Nei prototipi di funzione, includete i nomi dei parametri e i loro tipi. +Nonostante questo non sia richiesto dal linguaggio C, in Linux viene preferito +perché è un modo semplice per aggiungere informazioni importanti per il +lettore. + +7) Centralizzare il ritorno delle funzioni +------------------------------------------ + +Sebbene sia deprecata da molte persone, l'istruzione goto è impiegata di +frequente dai compilatori sotto forma di salto incondizionato. + +L'istruzione goto diventa utile quando una funzione ha punti d'uscita multipli +e vanno eseguite alcune procedure di pulizia in comune. Se non è necessario +pulire alcunché, allora ritornate direttamente. + +Assegnate un nome all'etichetta di modo che suggerisca cosa fa la goto o +perché esiste. Un esempio di un buon nome potrebbe essere ``out_free_buffer:`` +se la goto libera (free) un ``buffer``. Evitate l'uso di nomi GW-BASIC come +``err1:`` ed ``err2:``, potreste doverli riordinare se aggiungete o rimuovete +punti d'uscita, e inoltre rende difficile verificarne la correttezza. + +I motivo per usare le goto sono: + +- i salti incondizionati sono più facili da capire e seguire +- l'annidamento si riduce +- si evita di dimenticare, per errore, di aggiornare un singolo punto d'uscita +- aiuta il compilatore ad ottimizzare il codice ridondante ;) + +.. 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; + } + +Un baco abbastanza comune di cui bisogna prendere nota è il ``one err bugs`` +che assomiglia a questo: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +Il baco in questo codice è che in alcuni punti d'uscita la variabile ``foo`` è +NULL. Normalmente si corregge questo baco dividendo la gestione dell'errore in +due parti ``err_free_bar:`` e ``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Idealmente, dovreste simulare condizioni d'errore per verificare i vostri +percorsi d'uscita. + + +8) Commenti +----------- + +I commenti sono una buona cosa, ma c'è anche il rischio di esagerare. MAI +spiegare COME funziona il vostro codice in un commento: è molto meglio +scrivere il codice di modo che il suo funzionamento sia ovvio, inoltre +spiegare codice scritto male è una perdita di tempo. + +Solitamente, i commenti devono dire COSA fa il codice, e non COME lo fa. +Inoltre, cercate di evitare i commenti nel corpo della funzione: se la +funzione è così complessa che dovete commentarla a pezzi, allora dovreste +tornare al punto 6 per un momento. Potete mettere dei piccoli commenti per +annotare o avvisare il lettore circa un qualcosa di particolarmente arguto +(o brutto), ma cercate di non esagerare. Invece, mettete i commenti in +testa alla funzione spiegando alle persone cosa fa, e possibilmente anche +il PERCHÉ. + +Per favore, quando commentate una funzione dell'API del kernel usate il +formato kernel-doc. Per maggiori dettagli, leggete i file in +:ref::ref:`Documentation/translations/it_IT/doc-guide/ <it_doc_guide>` e in +``script/kernel-doc``. + +Lo stile preferito per i commenti più lunghi (multi-riga) è: + +.. 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. + */ + +Per i file in net/ e in drivers/net/ lo stile preferito per i commenti +più lunghi (multi-riga) è leggermente diverso. + +.. 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. + */ + +È anche importante commentare i dati, sia per i tipi base che per tipi +derivati. A questo scopo, dichiarate un dato per riga (niente virgole +per una dichiarazione multipla). Questo vi lascerà spazio per un piccolo +commento per spiegarne l'uso. + + +9) Avete fatto un pasticcio +--------------------------- + +Va bene, li facciamo tutti. Probabilmente vi è stato detto dal vostro +aiutante Unix di fiducia che ``GNU emacs`` formatta automaticamente il +codice C per conto vostro, e avete notato che sì, in effetti lo fa, ma che +i modi predefiniti non sono proprio allettanti (infatti, sono peggio che +premere tasti a caso - un numero infinito di scimmie che scrivono in +GNU emacs non faranno mai un buon programma). + +Quindi, potete sbarazzarvi di GNU emacs, o riconfigurarlo con valori più +sensati. Per fare quest'ultima cosa, potete appiccicare il codice che +segue nel vostro file .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"))))) + +Questo farà funzionare meglio emacs con lo stile del kernel per i file che +si trovano nella cartella ``~/src/linux-trees``. + +Ma anche se doveste fallire nell'ottenere una formattazione sensata in emacs +non tutto è perduto: usate ``indent``. + +Ora, ancora, GNU indent ha la stessa configurazione decerebrata di GNU emacs, +ed è per questo che dovete passargli alcune opzioni da riga di comando. +Tuttavia, non è così terribile, perché perfino i creatori di GNU indent +riconoscono l'autorità di K&R (le persone del progetto GNU non sono cattive, +sono solo mal indirizzate sull'argomento), quindi date ad indent le opzioni +``-kr -i8`` (che significa ``K&R, 8 caratteri di indentazione``), o utilizzate +``scripts/Lindent`` che indenterà usando l'ultimo stile. + +``indent`` ha un sacco di opzioni, e specialmente quando si tratta di +riformattare i commenti dovreste dare un'occhiata alle pagine man. +Ma ricordatevi: ``indent`` non è un correttore per una cattiva programmazione. + +Da notare che potete utilizzare anche ``clang-format`` per aiutarvi con queste +regole, per riformattare rapidamente ad automaticamente alcune parti del +vostro codice, e per revisionare interi file al fine di identificare errori +di stile, refusi e possibilmente anche delle migliorie. È anche utile per +ordinare gli ``#include``, per allineare variabili/macro, per ridistribuire +il testo e altre cose simili. +Per maggiori dettagli, consultate il file +:ref:`Documentation/translations/it_IT/process/clang-format.rst <it_clangformat>`. + + +10) File di configurazione Kconfig +---------------------------------- + +Per tutti i file di configurazione Kconfig* che si possono trovare nei +sorgenti, l'indentazione è un po' differente. Le linee dopo un ``config`` +sono indentate con un tab, mentre il testo descrittivo è indentato di +ulteriori due spazi. Esempio:: + + 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. + +Le funzionalità davvero pericolose (per esempio il supporto alla scrittura +per certi filesystem) dovrebbero essere dichiarate chiaramente come tali +nella stringa di titolo:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +Per la documentazione completa sui file di configurazione, consultate +il documento Documentation/translations/it_IT/kbuild/kconfig-language.txt + + +11) Strutture dati +------------------ + +Le strutture dati che hanno una visibilità superiore al contesto del +singolo thread in cui vengono create e distrutte, dovrebbero sempre +avere un contatore di riferimenti. Nel kernel non esiste un +*garbage collector* (e fuori dal kernel i *garbage collector* sono lenti +e inefficienti), questo significa che **dovete** assolutamente avere un +contatore di riferimenti per ogni cosa che usate. + +Avere un contatore di riferimenti significa che potete evitare la +sincronizzazione e permette a più utenti di accedere alla struttura dati +in parallelo - e non doversi preoccupare di una struttura dati che +improvvisamente sparisce dalla loro vista perché il loro processo dormiva +o stava facendo altro per un attimo. + +Da notare che la sincronizzazione **non** si sostituisce al conteggio dei +riferimenti. La sincronizzazione ha lo scopo di mantenere le strutture +dati coerenti, mentre il conteggio dei riferimenti è una tecnica di gestione +della memoria. Solitamente servono entrambe le cose, e non vanno confuse fra +di loro. + +Quando si hanno diverse classi di utenti, le strutture dati possono avere +due livelli di contatori di riferimenti. Il contatore di classe conta +il numero dei suoi utenti, e il contatore globale viene decrementato una +sola volta quando il contatore di classe va a zero. + +Un esempio di questo tipo di conteggio dei riferimenti multi-livello può +essere trovato nella gestore della memoria (``struct mm_sturct``: mm_user e +mm_count), e nel codice dei filesystem (``struct super_block``: s_count e +s_active). + +Ricordatevi: se un altro thread può trovare la vostra struttura dati, e non +avete un contatore di riferimenti per essa, quasi certamente avete un baco. + +12) Macro, enumerati e RTL +--------------------------- + +I nomi delle macro che definiscono delle costanti e le etichette degli +enumerati sono scritte in maiuscolo. + +.. code-block:: c + + #define CONSTANT 0x12345 + +Gli enumerati sono da preferire quando si definiscono molte costanti correlate. + +I nomi delle macro in MAIUSCOLO sono preferibili ma le macro che assomigliano +a delle funzioni possono essere scritte in minuscolo. + +Generalmente, le funzioni inline sono preferibili rispetto alle macro che +sembrano funzioni. + +Le macro che contengono più istruzioni dovrebbero essere sempre chiuse in un +blocco do - while: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +Cose da evitare quando si usano le macro: + +1) le macro che hanno effetti sul flusso del codice: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +sono **proprio** una pessima idea. Sembra una chiamata a funzione ma termina +la funzione chiamante; non cercate di rompere il decodificatore interno di +chi legge il codice. + +2) le macro che dipendono dall'uso di una variabile locale con un nome magico: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +potrebbe sembrare una bella cosa, ma è dannatamente confusionario quando uno +legge il codice e potrebbe romperlo con una cambiamento che sembra innocente. + +3) le macro con argomenti che sono utilizzati come l-values; questo potrebbe +ritorcervisi contro se qualcuno, per esempio, trasforma FOO in una funzione +inline. + +4) dimenticatevi delle precedenze: le macro che definiscono espressioni devono +essere racchiuse fra parentesi. State attenti a problemi simili con le macro +parametrizzate. + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) collisione nello spazio dei nomi quando si definisce una variabile locale in +una macro che sembra una funzione: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret è un nome comune per una variabile locale - __foo_ret difficilmente +andrà in conflitto con una variabile già esistente. + +Il manuale di cpp si occupa esaustivamente delle macro. Il manuale di sviluppo +di gcc copre anche l'RTL che viene usato frequentemente nel kernel per il +linguaggio assembler. + +13) Visualizzare i messaggi del kernel +-------------------------------------- + +Agli sviluppatori del kernel piace essere visti come dotti. Tenete un occhio +di riguardo per l'ortografia e farete una belle figura. In inglese, evitate +l'uso di parole mozzate come ``dont``: usate ``do not`` oppure ``don't``. +Scrivete messaggi concisi, chiari, e inequivocabili. + +I messaggi del kernel non devono terminare con un punto fermo. + +Scrivere i numeri fra parentesi (%d) non migliora alcunché e per questo +dovrebbero essere evitati. + +Ci sono alcune macro per la diagnostica in <linux/device.h> che dovreste +usare per assicurarvi che i messaggi vengano associati correttamente ai +dispositivi e ai driver, e che siano etichettati correttamente: dev_err(), +dev_warn(), dev_info(), e così via. Per messaggi che non sono associati ad +alcun dispositivo, <linux/printk.h> definisce pr_info(), pr_warn(), pr_err(), +eccetera. + +Tirar fuori un buon messaggio di debug può essere una vera sfida; e quando +l'avete può essere d'enorme aiuto per risolvere problemi da remoto. +Tuttavia, i messaggi di debug sono gestiti differentemente rispetto agli +altri. Le funzioni pr_XXX() stampano incondizionatamente ma pr_debug() no; +essa non viene compilata nella configurazione predefinita, a meno che +DEBUG o CONFIG_DYNAMIC_DEBUG non vengono impostati. Questo vale anche per +dev_dbg() e in aggiunta VERBOSE_DEBUG per aggiungere i messaggi dev_vdbg(). + +Molti sottosistemi hanno delle opzioni di debug in Kconfig che aggiungono +-DDEBUG nei corrispettivi Makefile, e in altri casi aggiungono #define DEBUG +in specifici file. Infine, quando un messaggio di debug dev'essere stampato +incondizionatamente, per esempio perché siete già in una sezione di debug +racchiusa in #ifdef, potete usare printk(KERN_DEBUG ...). + +14) Assegnare memoria +--------------------- + +Il kernel fornisce i seguenti assegnatori ad uso generico: +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), e vzalloc(). +Per maggiori informazioni, consultate la documentazione dell'API. + +Il modo preferito per passare la dimensione di una struttura è il seguente: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +La forma alternativa, dove il nome della struttura viene scritto interamente, +peggiora la leggibilità e introduce possibili bachi quando il tipo di +puntatore cambia tipo ma il corrispondente sizeof non viene aggiornato. + +Il valore di ritorno è un puntatore void, effettuare un cast su di esso è +ridondante. La conversione fra un puntatore void e un qualsiasi altro tipo +di puntatore è garantito dal linguaggio di programmazione C. + +Il modo preferito per assegnare un vettore è il seguente: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +Il modo preferito per assegnare un vettore a zero è il seguente: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Entrambe verificano la condizione di overflow per la dimensione +d'assegnamento n * sizeof(...), se accade ritorneranno NULL. + +15) Il morbo inline +------------------- + +Sembra che ci sia la percezione errata che gcc abbia una qualche magica +opzione "rendimi più veloce" chiamata ``inline``. In alcuni casi l'uso di +inline è appropriato (per esempio in sostituzione delle macro, vedi +capitolo 12), ma molto spesso non lo è. L'uso abbondante della parola chiave +inline porta ad avere un kernel più grande, che si traduce in un sistema nel +suo complesso più lento per via di una cache per le istruzioni della CPU più +grande e poi semplicemente perché ci sarà meno spazio disponibile per una +pagina di cache. Pensateci un attimo; una fallimento nella cache causa una +ricerca su disco che può tranquillamente richiedere 5 millisecondi. Ci sono +TANTI cicli di CPU che potrebbero essere usati in questi 5 millisecondi. + +Spesso le persone dicono che aggiungere inline a delle funzioni dichiarate +static e utilizzare una sola volta è sempre una scelta vincente perché non +ci sono altri compromessi. Questo è tecnicamente vero ma gcc è in grado di +trasformare automaticamente queste funzioni in inline; i problemi di +manutenzione del codice per rimuovere gli inline quando compare un secondo +utente surclassano il potenziale vantaggio nel suggerire a gcc di fare una +cosa che avrebbe fatto comunque. + +16) Nomi e valori di ritorno delle funzioni +------------------------------------------- + +Le funzioni possono ritornare diversi tipi di valori, e uno dei più comuni +è quel valore che indica se una funzione ha completato con successo o meno. +Questo valore può essere rappresentato come un codice di errore intero +(-Exxx = fallimento, 0 = successo) oppure un booleano di successo +(0 = fallimento, non-zero = successo). + +Mischiare questi due tipi di rappresentazioni è un terreno fertile per +i bachi più insidiosi. Se il linguaggio C includesse una forte distinzione +fra gli interi e i booleani, allora il compilatore potrebbe trovare questi +errori per conto nostro ... ma questo non c'è. Per evitare di imbattersi +in questo tipo di baco, seguite sempre la seguente convenzione:: + + Se il nome di una funzione è un'azione o un comando imperativo, + essa dovrebbe ritornare un codice di errore intero. Se il nome + è un predicato, la funzione dovrebbe ritornare un booleano di + "successo" + +Per esempio, ``add work`` è un comando, e la funzione add_work() ritorna 0 +in caso di successo o -EBUSY in caso di fallimento. Allo stesso modo, +``PCI device present`` è un predicato, e la funzione pci_dev_present() ritorna +1 se trova il dispositivo corrispondente con successo, altrimenti 0. + +Tutte le funzioni esportate (EXPORT) devono rispettare questa convenzione, e +così dovrebbero anche tutte le funzioni pubbliche. Le funzioni private +(static) possono non seguire questa convenzione, ma è comunque raccomandato +che lo facciano. + +Le funzioni il cui valore di ritorno è il risultato di una computazione, +piuttosto che l'indicazione sul successo di tale computazione, non sono +soggette a questa regola. Solitamente si indicano gli errori ritornando un +qualche valore fuori dai limiti. Un tipico esempio è quello delle funzioni +che ritornano un puntatore; queste utilizzano NULL o ERR_PTR come meccanismo +di notifica degli errori. + +17) Non reinventate le macro del kernel +--------------------------------------- + +Il file di intestazione include/linux/kernel.h contiene un certo numero +di macro che dovreste usare piuttosto che implementarne una qualche variante. +Per esempio, se dovete calcolare la lunghezza di un vettore, sfruttate la +macro: + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Analogamente, se dovete calcolare la dimensione di un qualche campo di una +struttura, usate + +.. code-block:: c + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +Ci sono anche le macro min() e max() che, se vi serve, effettuano un controllo +rigido sui tipi. Sentitevi liberi di leggere attentamente questo file +d'intestazione per scoprire cos'altro è stato definito che non dovreste +reinventare nel vostro codice. + +18) Linee di configurazione degli editor e altre schifezze +----------------------------------------------------------- + +Alcuni editor possono interpretare dei parametri di configurazione integrati +nei file sorgenti e indicati con dai marcatori speciali. Per esempio, emacs +interpreta le linee marcate nel seguente modo: + +.. code-block:: c + + -*- mode: c -*- + +O come queste: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interpreta i marcatori come questi: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +Non includete nessuna di queste cose nei file sorgenti. Le persone hanno le +proprie configurazioni personali per l'editor, e i vostri sorgenti non +dovrebbero sovrascrivergliele. Questo vale anche per i marcatori +d'indentazione e di modalità d'uso. Le persone potrebbero aver configurato una +modalità su misura, oppure potrebbero avere qualche altra magia per far +funzionare bene l'indentazione. + +19) Inline assembly +--------------------- + +Nel codice specifico per un'architettura, potreste aver bisogno di codice +*inline assembly* per interfacciarvi col processore o con una funzionalità +specifica della piattaforma. Non esitate a farlo quando è necessario. +Comunque, non usatele gratuitamente quando il C può fare la stessa cosa. +Potete e dovreste punzecchiare l'hardware in C quando è possibile. + +Considerate la scrittura di una semplice funzione che racchiude pezzi comuni +di codice assembler piuttosto che continuare a riscrivere delle piccole +varianti. Ricordatevi che l' *inline assembly* può utilizzare i parametri C. + +Il codice assembler più corposo e non banale dovrebbe andare nei file .S, +coi rispettivi prototipi C definiti nei file d'intestazione. I prototipi C +per le funzioni assembler dovrebbero usare ``asmlinkage``. + +Potreste aver bisogno di marcare il vostro codice asm come volatile al fine +d'evitare che GCC lo rimuova quando pensa che non ci siano effetti collaterali. +Non c'è sempre bisogno di farlo, e farlo quando non serve limita le +ottimizzazioni. + +Quando scrivete una singola espressione *inline assembly* contenente più +istruzioni, mettete ognuna di queste istruzioni in una stringa e riga diversa; +ad eccezione dell'ultima stringa/istruzione, ognuna deve terminare con ``\n\t`` +al fine di allineare correttamente l'assembler che verrà generato: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + +20) Compilazione sotto condizione +--------------------------------- + +Ovunque sia possibile, non usate le direttive condizionali del preprocessore +(#if, #ifdef) nei file .c; farlo rende il codice difficile da leggere e da +seguire. Invece, usate queste direttive nei file d'intestazione per definire +le funzioni usate nei file .c, fornendo i relativi stub nel caso #else, +e quindi chiamate queste funzioni senza condizioni di preprocessore. Il +compilatore non produrrà alcun codice per le funzioni stub, produrrà gli +stessi risultati, e la logica rimarrà semplice da seguire. + +È preferibile non compilare intere funzioni piuttosto che porzioni d'esse o +porzioni d'espressioni. Piuttosto che mettere una ifdef in un'espressione, +fattorizzate parte dell'espressione, o interamente, in funzioni e applicate +la direttiva condizionale su di esse. + +Se avete una variabile o funzione che potrebbe non essere usata in alcune +configurazioni, e quindi il compilatore potrebbe avvisarvi circa la definizione +inutilizzata, marcate questa definizione come __maybe_used piuttosto che +racchiuderla in una direttiva condizionale del preprocessore. (Comunque, +se una variabile o funzione è *sempre* inutilizzata, rimuovetela). + +Nel codice, dov'è possibile, usate la macro IS_ENABLED per convertire i +simboli Kconfig in espressioni booleane C, e quindi usatela nelle classiche +condizioni C: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +Il compilatore valuterà la condizione come costante (constant-fold), e quindi +includerà o escluderà il blocco di codice come se fosse in un #ifdef, quindi +non ne aumenterà il tempo di esecuzione. Tuttavia, questo permette al +compilatore C di vedere il codice nel blocco condizionale e verificarne la +correttezza (sintassi, tipi, riferimenti ai simboli, eccetera). Quindi +dovete comunque utilizzare #ifdef se il codice nel blocco condizionale esiste +solo quando la condizione è soddisfatta. + +Alla fine di un blocco corposo di #if o #ifdef (più di alcune linee), +mettete un commento sulla stessa riga di #endif, annotando la condizione +che termina. Per esempio: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + +Appendice I) riferimenti +------------------------ + +The C Programming Language, Second Edition +by Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +Manuali GNU - nei casi in cui sono compatibili con K&R e questo documento - +per indent, cpp, gcc e i suoi dettagli interni, tutto disponibile qui +http://www.gnu.org/manual/ + +WG14 è il gruppo internazionale di standardizzazione per il linguaggio C, +URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/translations/it_IT/process/development-process.rst b/Documentation/translations/it_IT/process/development-process.rst new file mode 100644 index 000000000000..f1a6eca30824 --- /dev/null +++ b/Documentation/translations/it_IT/process/development-process.rst @@ -0,0 +1,33 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/development-process.rst <development_process_main>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_development_process_main: + +Una guida al processo di sviluppo del Kernel +============================================ + +Contenuti: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +Lo scopo di questo documento è quello di aiutare gli sviluppatori (ed i loro +supervisori) a lavorare con la communità di sviluppo con il minimo sforzo. È +un tentativo di documentare il funzionamento di questa communità in modo che +sia accessibile anche a coloro che non hanno famigliarità con lo sviluppo del +Kernel Linux (o, anzi, con lo sviluppo di software libero in generale). Benchè +qui sia presente del materiale tecnico, questa è una discussione rivolta in +particolare al procedimento, e quindi per essere compreso non richiede una +conoscenza approfondità sullo sviluppo del kernel. diff --git a/Documentation/translations/it_IT/process/email-clients.rst b/Documentation/translations/it_IT/process/email-clients.rst new file mode 100644 index 000000000000..224ab031ffd3 --- /dev/null +++ b/Documentation/translations/it_IT/process/email-clients.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/email-clients.rst <email_clients>` + +.. _it_email_clients: + +Informazioni sui programmi di posta elettronica per Linux +========================================================= + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst new file mode 100644 index 000000000000..909e6a55bc43 --- /dev/null +++ b/Documentation/translations/it_IT/process/howto.rst @@ -0,0 +1,655 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/howto.rst <process_howto>` +:Translator: Alessia Mantegazza <amantegazza@vaga.pv.it> + +.. _it_process_howto: + +Come partecipare allo sviluppo del kernel Linux +=============================================== + +Questo è il documento fulcro di quanto trattato sull'argomento. +Esso contiene le istruzioni su come diventare uno sviluppatore +del kernel Linux e spiega come lavorare con la comunità di +sviluppo kernel Linux. Il documento non tratterà alcun aspetto +tecnico relativo alla programmazione del kernel, ma vi aiuterà +indirizzandovi sulla corretta strada. + +Se qualsiasi cosa presente in questo documento diventasse obsoleta, +vi preghiamo di inviare le correzioni agli amministratori di questo +file, indicati in fondo al presente documento. + +Introduzione +------------ +Dunque, volete imparare come diventare sviluppatori del kernel Linux? +O vi è stato detto dal vostro capo, "Vai, scrivi un driver Linux per +questo dispositivo". Bene, l'obbiettivo di questo documento è quello +di insegnarvi tutto ciò che dovete sapere per raggiungere il vostro +scopo descrivendo il procedimento da seguire e consigliandovi +su come lavorare con la comunità. Il documento cercherà, inoltre, +di spiegare alcune delle ragioni per le quali la comunità lavora in un +modo suo particolare. + +Il kernel è scritto prevalentemente nel linguaggio C con alcune parti +specifiche dell'architettura scritte in linguaggio assembly. +Per lo sviluppo kernel è richiesta una buona conoscenza del linguaggio C. +L'assembly (di qualsiasi architettura) non è richiesto, a meno che non +pensiate di fare dello sviluppo di basso livello per un'architettura. +Sebbene essi non siano un buon sostituto ad un solido studio del +linguaggio C o ad anni di esperienza, i seguenti libri sono, se non +altro, utili riferimenti: + +- "The C Programming Language" di Kernighan e Ritchie [Prentice Hall] +- "Practical C Programming" di Steve Oualline [O'Reilly] +- "C: A Reference Manual" di Harbison and Steele [Prentice Hall] + +Il kernel è stato scritto usando GNU C e la toolchain GNU. +Sebbene si attenga allo standard ISO C89, esso utilizza una serie di +estensioni che non sono previste in questo standard. Il kernel è un +ambiente C indipendente, che non ha alcuna dipendenza dalle librerie +C standard, così alcune parti del C standard non sono supportate. +Le divisioni ``long long`` e numeri in virgola mobile non sono permessi. +Qualche volta è difficile comprendere gli assunti che il kernel ha +riguardo gli strumenti e le estensioni in uso, e sfortunatamente non +esiste alcuna indicazione definitiva. Per maggiori informazioni, controllate, +la pagina `info gcc`. + +Tenete a mente che state cercando di apprendere come lavorare con la comunità +di sviluppo già esistente. Questo è un gruppo eterogeneo di persone, con alti +standard di codifica, di stile e di procedura. Questi standard sono stati +creati nel corso del tempo basandosi su quanto hanno riscontrato funzionare al +meglio per un squadra così grande e geograficamente sparsa. Cercate di +imparare, in anticipo, il più possibile circa questi standard, poichè ben +spiegati; non aspettatevi che gli altri si adattino al vostro modo di fare +o a quello della vostra azienda. + +Note legali +------------ +Il codice sorgente del kernel Linux è rilasciato sotto GPL. Siete pregati +di visionare il file, COPYING, presente nella cartella principale dei +sorgente, per eventuali dettagli sulla licenza. Se avete ulteriori domande +sulla licenza, contattate un avvocato, non chiedete sulle liste di discussione +del kernel Linux. Le persone presenti in queste liste non sono avvocati, +e non dovreste basarvi sulle loro dichiarazioni in materia giuridica. + +Per domande più frequenti e risposte sulla licenza GPL, guardare: + + https://www.gnu.org/licenses/gpl-faq.html + +Documentazione +-------------- +I sorgenti del kernel Linux hanno una vasta base di documenti che vi +insegneranno come interagire con la comunità del kernel. Quando nuove +funzionalità vengono aggiunte al kernel, si raccomanda di aggiungere anche i +relativi file di documentatione che spiegano come usarele. +Quando un cambiamento del kernel genera anche un cambiamento nell'interfaccia +con lo spazio utente, è raccomandabile che inviate una notifica o una +correzione alle pagine *man* spiegando tale modifica agli amministratori di +queste pagine all'indirizzo mtk.manpages@gmail.com, aggiungendo +in CC la lista linux-api@vger.kernel.org. + +Di seguito una lista di file che sono presenti nei sorgente del kernel e che +è richiesto che voi leggiate: + + :ref:`Documentation/translations/it_IT/admin-guide/README.rst <it_readme>` + Questo file da una piccola anteprima del kernel Linux e descrive il + minimo necessario per configurare e generare il kernel. I novizi + del kernel dovrebbero iniziare da qui. + + :ref:`Documentation/translations/it_IT/process/changes.rst <it_changes>` + + Questo file fornisce una lista dei pacchetti software necessari + a compilare e far funzionare il kernel con successo. + + :ref:`Documentation/translations/it_IT/process/coding-style.rst <it_codingstyle>` + + Questo file descrive lo stile della codifica per il kernel Linux, + e parte delle motivazioni che ne sono alla base. Tutto il nuovo codice deve + seguire le linee guida in questo documento. Molti amministratori + accetteranno patch solo se queste osserveranno tali regole, e molte + persone revisioneranno il codice solo se scritto nello stile appropriato. + + :ref:`Documentation/translations/it_IT/process/submitting-patches.rst <it_submittingpatches>` e + :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>` + + Questo file descrive dettagliatamente come creare ed inviare una patch + con successo, includendo (ma non solo questo): + + - Contenuto delle email + - Formato delle email + - I destinatari delle email + + Seguire tali regole non garantirà il successo (tutte le patch sono soggette + a controlli realitivi a contenuto e stile), ma non seguirle lo precluderà + sempre. + + Altre ottime descrizioni di come creare buone patch sono: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/process/translations/it_IT/stable-api-nonsense.rst <it_stable_api_nonsense>` + + Questo file descrive la motivazioni sottostanti la conscia decisione di + non avere un API stabile all'interno del kernel, incluso cose come: + + - Sottosistemi shim-layers (per compatibilità?) + - Portabilità fra Sistemi Operativi dei driver. + - Attenuare i rapidi cambiamenti all'interno dei sorgenti del kernel + (o prevenirli) + + Questo documento è vitale per la comprensione della filosifia alla base + dello sviluppo di Linux ed è molto importante per le persone che arrivano + da esperienze con altri Sistemi Operativi. + + :ref:`Documentation/translations/it_IT/admin-guide/security-bugs.rst <it_securitybugs>` + Se ritenete di aver trovato un problema di sicurezza nel kernel Linux, + seguite i passaggi scritti in questo documento per notificarlo agli + sviluppatori del kernel, ed aiutare la risoluzione del problema. + + :ref:`Documentation/translations/it_IT/process/management-style.rst <it_managementstyle>` + Questo documento descrive come i manutentori del kernel Linux operano + e la filosofia comune alla base del loro metodo. Questa è un'importante + lettura per tutti coloro che sono nuovi allo sviluppo del kernel (o per + chi è semplicemente curioso), poiché risolve molti dei più comuni + fraintendimenti e confusioni dovuti al particolare comportamento dei + manutentori del kernel. + + :ref:`Documentation/translations/it_IT/process/stable-kernel-rules.rst <it_stable_kernel_rules>` + Questo file descrive le regole sulle quali vengono basati i rilasci del + kernel, e spiega cosa fare se si vuole che una modifica venga inserita + in uno di questi rilasci. + + :ref:`Documentation/translations/it_IT/process/kernel-docs.rst <it_kernel_docs>` + Una lista di documenti pertinenti allo sviluppo del kernel. + Per favore consultate questa lista se non trovate ciò che cercate nella + documentazione interna del kernel. + + :ref:`Documentation/translations/it_IT/process/applying-patches.rst <it_applying_patches>` + Una buona introduzione che descrivere esattamente cos'è una patch e come + applicarla ai differenti rami di sviluppo del kernel. + +Il kernel inoltre ha un vasto numero di documenti che possono essere +automaticamente generati dal codice sorgente stesso o da file +ReStructuredText (ReST), come questo. Esso include una completa +descrizione dell'API interna del kernel, e le regole su come gestire la +sincronizzazione (locking) correttamente + +Tutte queste tipologie di documenti possono essere generati in PDF o in +HTML utilizzando:: + + make pdfdocs + make htmldocs + +rispettivamente dalla cartella principale dei sorgenti del kernel. + +I documenti che impiegano ReST saranno generati nella cartella +Documentation/output. +Questi posso essere generati anche in formato LaTex e ePub con:: + + make latexdocs + make epubdocs + +Diventare uno sviluppatore del kernel +------------------------------------- +Se non sapete nulla sullo sviluppo del kernel Linux, dovreste dare uno +sguardo al progetto *Linux KernelNewbies*: + + https://kernelnewbies.org + +Esso prevede un'utile lista di discussione dove potete porre più o meno ogni +tipo di quesito relativo ai concetti fondamentali sullo sviluppo del kernel +(assicuratevi di cercare negli archivi, prima di chiedere qualcosa alla +quale è già stata fornita risposta in passato). Esistono inoltre, un canale IRC +che potete usare per formulare domande in tempo reale, e molti documenti utili +che vi faciliteranno nell'apprendimento dello sviluppo del kernel Linux. + +Il sito internet contiene informazioni di base circa l'organizzazione del +codice, sottosistemi e progetti attuali (sia interni che esterni a Linux). +Esso descrive, inoltre, informazioni logistiche di base, riguardanti ad esempio +la compilazione del kernel e l'applicazione di una modifica. + +Se non sapete dove cominciare, ma volete cercare delle attività dalle quali +partire per partecipare alla comunità di sviluppo, andate al progetto Linux +Kernel Janitor's. + + https://kernelnewbies.org/KernelJanitors + +È un buon posto da cui iniziare. Esso presenta una lista di problematiche +relativamente semplici da sistemare e pulire all'interno della sorgente del +kernel Linux. Lavorando con gli sviluppatori incaricati di questo progetto, +imparerete le basi per l'inserimento delle vostre modifiche all'interno dei +sorgenti del kernel Linux, e possibilmente, sarete indirizzati al lavoro +successivo da svolgere, se non ne avrete ancora idea. + +Prima di apportare una qualsiasi modifica al codice del kernel Linux, +è imperativo comprendere come tale codice funziona. A questo scopo, non c'è +nulla di meglio che leggerlo direttamente (la maggior parte dei bit più +complessi sono ben commentati), eventualmente anche con l'aiuto di strumenti +specializzati. Uno degli strumenti che è particolarmente raccomandato è +il progetto Linux Cross-Reference, che è in grado di presentare codice +sorgente in un formato autoreferenziale ed indicizzato. Un eccellente ed +aggiornata fonte di consultazione del codice del kernel la potete trovare qui: + + http://lxr.free-electrons.com/ + + +Il processo di sviluppo +----------------------- +Il processo di sviluppo del kernel Linux si compone di pochi "rami" principali +e di molti altri rami per specifici sottosistemi. Questi rami sono: + + - I sorgenti kernel 4.x + - I sorgenti stabili del kernel 4.x.y -stable + - Le modifiche in 4.x -git + - Sorgenti dei sottosistemi del kernel e le loro modifiche + - Il kernel 4.x -next per test d'integrazione + +I sorgenti kernel 4.x +~~~~~~~~~~~~~~~~~~~~~ + +I kernel 4.x sono amministrati da Linus Torvald, e possono essere trovati +su https://kernel.org nella cartella pub/linux/kernel/v4.x/. Il processo +di sviluppo è il seguente: + + - Non appena un nuovo kernel viene rilasciato si apre una finestra di due + settimane. Durante questo periodo i manutentori possono proporre a Linus + dei grossi cambiamenti; solitamente i cambiamenti che sono già stati + inseriti nel ramo -next del kernel per alcune settimane. Il modo migliore + per sottoporre dei cambiamenti è attraverso git (lo strumento usato per + gestire i sorgenti del kernel, più informazioni sul sito + https://git-scm.com/) ma anche delle patch vanno bene. + + - Al termine delle due settimane un kernel -rc1 viene rilasciato e + l'obbiettivo ora è quello di renderlo il più solido possibile. A questo + punto la maggior parte delle patch dovrebbero correggere un'eventuale + regressione. I bachi che sono sempre esistiti non sono considerabili come + regressioni, quindi inviate questo tipo di cambiamenti solo se sono + importanti. Notate che un intero driver (o filesystem) potrebbe essere + accettato dopo la -rc1 poiché non esistono rischi di una possibile + regressione con tale cambiamento, fintanto che quest'ultimo è + auto-contenuto e non influisce su aree esterne al codice che è stato + aggiunto. git può essere utilizzato per inviare le patch a Linus dopo che + la -rc1 è stata rilasciata, ma è anche necessario inviare le patch ad + una lista di discussione pubblica per un'ulteriore revisione. + + - Una nuova -rc viene rilasciata ogni volta che Linus reputa che gli attuali + sorgenti siano in uno stato di salute ragionevolmente adeguato ai test. + L'obiettivo è quello di rilasciare una nuova -rc ogni settimana. + + - Il processo continua fino a che il kernel è considerato "pronto"; tale + processo dovrebbe durare circa in 6 settimane. + +È utile menzionare quanto scritto da Andrew Morton sulla lista di discussione +kernel-linux in merito ai rilasci del kernel: + + *"Nessuno sa quando un kernel verrà rilasciato, poichè questo è + legato allo stato dei bachi e non ad una cronologia preventiva."* + +I sorgenti stabili del kernel 4.x.y -stable +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +I kernel con versioni in 3-parti sono "kernel stabili". Essi contengono +correzioni critiche relativamente piccole nell'ambito della sicurezza +oppure significative regressioni scoperte in un dato 4.x kernel. + +Questo è il ramo raccomandato per gli utenti che vogliono un kernel recente +e stabile e non sono interessati a dare il proprio contributo alla verifica +delle versioni di sviluppo o sperimentali. + +Se non è disponibile alcun kernel 4.x.y., quello più aggiornato e stabile +sarà il kernel 4.x con la numerazione più alta. + +4.x.y sono amministrati dal gruppo "stable" <stable@vger.kernel.org>, e sono +rilasciati a seconda delle esigenze. Il normale periodo di rilascio è +approssimativamente di due settimane, ma può essere più lungo se non si +verificano problematiche urgenti. Un problema relativo alla sicurezza, invece, +può determinare un rilascio immediato. + +Il file Documentation/process/stable-kernel-rules.rst (nei sorgenti) documenta +quali tipologie di modifiche sono accettate per i sorgenti -stable, e come +avviene il processo di rilascio. + +Le modifiche in 4.x -git +~~~~~~~~~~~~~~~~~~~~~~~~ + +Queste sono istantanee quotidiane del kernel di Linus e sono gestite in +una repositorio git (da qui il nome). Queste modifiche sono solitamente +rilasciate giornalmente e rappresentano l'attuale stato dei sorgenti di +Linus. Queste sono da considerarsi più sperimentali di un -rc in quanto +generate automaticamente senza nemmeno aver dato una rapida occhiata +per verificarne lo stato. + + +Sorgenti dei sottosistemi del kernel e le loro patch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +I manutentori dei diversi sottosistemi del kernel --- ed anche molti +sviluppatori di sottosistemi --- mostrano il loro attuale stato di sviluppo +nei loro repositori. In questo modo, altri possono vedere cosa succede nelle +diverse parti del kernel. In aree dove lo sviluppo è rapido, potrebbe essere +chiesto ad uno sviluppatore di basare le proprie modifiche su questi repositori +in modo da evitare i conflitti fra le sottomissioni ed altri lavori in corso + +La maggior parte di questi repositori sono git, ma esistono anche altri SCM +in uso, o file di patch pubblicate come una serie quilt. +Gli indirizzi dei repositori di sottosistema sono indicati nel file +MAINTAINERS. Molti di questi posso essere trovati su https://git.kernel.org/. + +Prima che una modifica venga inclusa in questi sottosistemi, sarà soggetta ad +una revisione che inizialmente avviene tramite liste di discussione (vedere la +sezione dedicata qui sotto). Per molti sottosistemi del kernel, tale processo +di revisione è monitorato con lo strumento patchwork. +Patchwork offre un'interfaccia web che mostra le patch pubblicate, inclusi i +commenti o le revisioni fatte, e gli amministratori possono indicare le patch +come "in revisione", "accettate", o "rifiutate". Diversi siti Patchwork sono +elencati al sito https://patchwork.kernel.org/. + +Il kernel 4.x -next per test d'integrazione +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Prima che gli aggiornamenti dei sottosistemi siano accorpati nel ramo +principale 4.x, sarà necessario un test d'integrazione. +A tale scopo, esiste un repositorio speciale di test nel quale virtualmente +tutti i rami dei sottosistemi vengono inclusi su base quotidiana: + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +In questo modo, i kernel -next offrono uno sguardo riassuntivo su quello che +ci si aspetterà essere nel kernel principale nel successivo periodo +d'incorporazione. +Coloro che vorranno fare dei test d'esecuzione del kernel -next sono più che +benvenuti. + + +Riportare Bug +------------- + +https://bugzilla.kernel.org è dove gli sviluppatori del kernel Linux tracciano +i bachi del kernel. Gli utenti sono incoraggiati nel riportare tutti i bachi +che trovano utilizzando questo strumento. +Per maggiori dettagli su come usare il bugzilla del kernel, guardare: + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +Il file admin-guide/reporting-bugs.rst nella cartella principale del kernel +fornisce un buon modello sul come segnalare un baco nel kernel, e spiega quali +informazioni sono necessarie agli sviluppatori per poter aiutare il +rintracciamento del problema. + +Gestire i rapporti sui bug +-------------------------- + +Uno dei modi migliori per mettere in pratica le vostre capacità di hacking è +quello di riparare bachi riportati da altre persone. Non solo aiuterete a far +diventare il kernel più stabile, ma imparerete a riparare problemi veri dal +mondo ed accrescerete le vostre competenze, e gli altri sviluppatori saranno +al corrente della vostra presenza. Riparare bachi è una delle migliori vie per +acquisire meriti tra gli altri sviluppatori, perchè non a molte persone piace +perdere tempo a sistemare i bachi di altri. + +Per lavorare sui rapporti di bachi già riportati, andate su +https://bugzilla.kernel.org. + +Liste di discussione +-------------------- + +Come descritto in molti dei documenti qui sopra, la maggior parte degli +sviluppatori del kernel partecipano alla lista di discussione Linux Kernel. +I dettagli su come iscriversi e disiscriversi dalla lista possono essere +trovati al sito: + + http://vger.kernel.org/vger-lists.html#linux-kernel + +Ci sono diversi archivi della lista di discussione. Usate un qualsiasi motore +di ricerca per trovarli. Per esempio: + + http://dir.gmane.org/gmane.linux.kernel + +É caldamente consigliata una ricerca in questi archivi sul tema che volete +sollevare, prima di pubblicarlo sulla lista. Molte cose sono già state +discusse in dettaglio e registrate negli archivi della lista di discussione. + +Molti dei sottosistemi del kernel hanno anche una loro lista di discussione +dedicata. Guardate nel file MAINTAINERS per avere una lista delle liste di +discussione e il loro uso. + +Molte di queste liste sono gestite su kernel.org. Per informazioni consultate +la seguente pagina: + + http://vger.kernel.org/vger-lists.html + +Per favore ricordatevi della buona educazione quando utilizzate queste liste. +Sebbene sia un pò dozzinale, il seguente URL contiene alcune semplici linee +guida per interagire con la lista (o con qualsiasi altra lista): + + http://www.albion.com/netiquette/ + +Se diverse persone rispondo alla vostra mail, la lista dei riceventi (copia +conoscenza) potrebbe diventare abbastanza lunga. Non cancellate nessuno dalla +lista di CC: senza un buon motivo, e non rispondete solo all'indirizzo +della lista di discussione. Fateci l'abitudine perché capita spesso di +ricevere la stessa email due volte: una dal mittente ed una dalla lista; e non +cercate di modificarla aggiungendo intestazioni stravaganti, agli altri non +piacerà. + +Ricordate di rimanere sempre in argomento e di mantenere le attribuzioni +delle vostre risposte invariate; mantenete il "John Kernelhacker wrote ...:" +in cima alla vostra replica e aggiungete le vostre risposte fra i singoli +blocchi citati, non scrivete all'inizio dell'email. + +Se aggiungete patch alla vostra mail, assicuratevi che siano del tutto +leggibili come indicato in Documentation/process/submitting-patches.rst. +Gli sviluppatori kernel non vogliono avere a che fare con allegati o patch +compresse; vogliono invece poter commentare le righe dei vostri cambiamenti, +il che può funzionare solo in questo modo. +Assicuratevi di utilizzare un gestore di mail che non alterì gli spazi ed i +caratteri. Un ottimo primo test è quello di inviare a voi stessi una mail e +cercare di sottoporre la vostra stessa patch. Se non funziona, sistemate il +vostro programma di posta, o cambiatelo, finché non funziona. + +Ed infine, per favore ricordatevi di mostrare rispetto per gli altri +sottoscriventi. + +Lavorare con la comunità +------------------------ + +L'obiettivo di questa comunità è quello di fornire il miglior kernel possibile. +Quando inviate una modifica che volete integrare, sarà valutata esclusivamente +dal punto di vista tecnico. Quindi, cosa dovreste aspettarvi? + + - critiche + - commenti + - richieste di cambiamento + - richieste di spiegazioni + - nulla + +Ricordatevi che questo fa parte dell'integrazione della vostra modifica +all'interno del kernel. Dovete essere in grado di accettare le critiche, +valutarle a livello tecnico ed eventualmente rielaborare nuovamente le vostre +modifiche o fornire delle chiare e concise motivazioni per le quali le +modifiche suggerite non dovrebbero essere fatte. +Se non riceverete risposte, aspettate qualche giorno e riprovate ancora, +qualche volta le cose si perdono nell'enorme mucchio di email. + +Cosa non dovreste fare? + + - aspettarvi che la vostra modifica venga accettata senza problemi + - mettervi sulla difensiva + - ignorare i commenti + - sottomettere nuovamente la modifica senza fare nessuno dei cambiamenti + richiesti + +In una comunità che è alla ricerca delle migliori soluzioni tecniche possibili, +ci saranno sempre opinioni differenti sull'utilità di una modifica. +Siate cooperativi e vogliate adattare la vostra idea in modo che sia inserita +nel kernel. O almeno vogliate dimostrare che la vostra idea vale. +Ricordatevi, sbagliare è accettato fintanto che siate disposti a lavorare verso +una soluzione che è corretta. + +È normale che le risposte alla vostra prima modifica possa essere +semplicemente una lista con dozzine di cose che dovreste correggere. +Questo **non** implica che la vostra patch non sarà accettata, e questo +**non** è contro di voi personalmente. +Semplicemente correggete tutte le questioni sollevate contro la vostra modifica +ed inviatela nuovamente. + +Differenze tra la comunità del kernel e le strutture aziendali +-------------------------------------------------------------- + +La comunità del kernel funziona diversamente rispetto a molti ambienti di +sviluppo aziendali. Qui di seguito una lista di cose che potete provare a +fare per evitare problemi: + + Cose da dire riguardanti le modifiche da voi proposte: + + - "Questo risolve più problematiche." + - "Questo elimina 2000 stringhe di codice." + - "Qui una modifica che spiega cosa sto cercando di fare." + - "L'ho testato su 5 diverse architetture.." + - "Qui una serie di piccole modifiche che.." + - "Questo aumenta le prestazioni di macchine standard..." + + Cose che dovreste evitare di dire: + + - "Lo abbiamo fatto in questo modo in AIX/ptx/Solaris, di conseguenza + deve per forza essere giusto..." + - "Ho fatto questo per 20 anni, quindi.." + - "Questo è richiesto dalla mia Azienda per far soldi" + - "Questo è per la linea di prodotti della nostra Azienda" + - "Ecco il mio documento di design di 1000 pagine che descrive ciò che ho + in mente" + - "Ci ho lavorato per 6 mesi..." + - "Ecco una patch da 5000 righe che.." + - "Ho riscritto il pasticcio attuale, ed ecco qua.." + - "Ho una scadenza, e questa modifica ha bisogno di essere approvata ora" + +Un'altra cosa nella quale la comunità del kernel si differenzia dai più +classici ambienti di ingegneria del software è la natura "senza volto" delle +interazioni umane. Uno dei benefici dell'uso delle email e di irc come forma +primordiale di comunicazione è l'assenza di discriminazione basata su genere e +razza. L'ambienti di lavoro Linux accetta donne e minoranze perchè tutto quello +che sei è un indirizzo email. Aiuta anche l'aspetto internazionale nel +livellare il terreno di gioco perchè non è possibile indovinare il genere +basandosi sul nome di una persona. Un uomo può chiamarsi Andrea ed una donna +potrebbe chiamarsi Pat. Gran parte delle donne che hanno lavorato al kernel +Linux e che hanno espresso una personale opinione hanno avuto esperienze +positive. + +La lingua potrebbe essere un ostacolo per quelle persone che non si trovano +a loro agio con l'inglese. Una buona padronanza del linguaggio può essere +necessaria per esporre le proprie idee in maniera appropiata all'interno +delle liste di discussione, quindi è consigliabile che rileggiate le vostre +email prima di inviarle in modo da essere certi che abbiano senso in inglese. + + +Spezzare le vostre modifiche +---------------------------- + +La comunità del kernel Linux non accetta con piacere grossi pezzi di codice +buttati lì tutti in una volta. Le modifiche necessitano di essere +adeguatamente presentate, discusse, e suddivise in parti più piccole ed +indipendenti. Questo è praticamente l'esatto opposto di quello che le +aziende fanno solitamente. La vostra proposta dovrebbe, inoltre, essere +presentata prestissimo nel processo di sviluppo, così che possiate ricevere +un riscontro su quello che state facendo. Lasciate che la comunità +senta che state lavorando con loro, e che non li stiate sfruttando come +discarica per le vostre aggiunte. In ogni caso, non inviate 50 email nello +stesso momento in una lista di discussione, il più delle volte la vostra serie +di modifiche dovrebbe essere più piccola. + +I motivi per i quali dovreste frammentare le cose sono i seguenti: + +1) Piccole modifiche aumentano le probabilità che vengano accettate, + altrimenti richiederebbe troppo tempo o sforzo nel verificarne + la correttezza. Una modifica di 5 righe può essere accettata da un + manutentore con a mala pena una seconda occhiata. Invece, una modifica da + 500 linee può richiedere ore di rilettura per verificarne la correttezza + (il tempo necessario è esponenzialmente proporzionale alla dimensione della + modifica, o giù di lì) + + Piccole modifiche sono inoltre molto facili da debuggare quando qualcosa + non va. È molto più facile annullare le modifiche una per una che + dissezionare una patch molto grande dopo la sua sottomissione (e rompere + qualcosa). + +2) È importante non solo inviare piccole modifiche, ma anche riscriverle e + semplificarle (o più semplicemente ordinarle) prima di sottoporle. + +Qui un'analogia dello sviluppatore kernel Al Viro: + + *"Pensate ad un insegnante di matematica che corregge il compito + di uno studente (di matematica). L'insegnante non vuole vedere le + prove e gli errori commessi dallo studente prima che arrivi alla + soluzione. Vuole vedere la risposta più pulita ed elegante + possibile. Un buono studente lo sa, e non presenterebbe mai le + proprie bozze prima prima della soluzione finale"* + + *"Lo stesso vale per lo sviluppo del kernel. I manutentori ed i + revisori non vogliono vedere il procedimento che sta dietro al + problema che uno sta risolvendo. Vogliono vedere una soluzione + semplice ed elegante."* + +Può essere una vera sfida il saper mantenere l'equilibrio fra una presentazione +elegante della vostra soluzione, lavorare insieme ad una comunità e dibattere +su un lavoro incompleto. Pertanto è bene entrare presto nel processo di +revisione per migliorare il vostro lavoro, ma anche per riuscire a tenere le +vostre modifiche in pezzettini che potrebbero essere già accettate, nonostante +la vostra intera attività non lo sia ancora. + +In fine, rendetevi conto che non è accettabile inviare delle modifiche +incomplete con la promessa che saranno "sistemate dopo". + + +Giustificare le vostre modifiche +-------------------------------- + +Insieme alla frammentazione delle vostre modifiche, è altrettanto importante +permettere alla comunità Linux di capire perché dovrebbero accettarle. +Nuove funzionalità devono essere motivate come necessarie ed utili. + + +Documentare le vostre modifiche +------------------------------- + +Quando inviate le vostre modifiche, fate particolare attenzione a quello che +scrivete nella vostra email. Questa diventerà il *ChangeLog* per la modifica, +e sarà visibile a tutti per sempre. Dovrebbe descrivere la modifica nella sua +interezza, contenendo: + + - perchè la modifica è necessaria + - l'approccio d'insieme alla patch + - dettagli supplementari + - risultati dei test + +Per maggiori dettagli su come tutto ciò dovrebbe apparire, riferitevi alla +sezione ChangeLog del documento: + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + +A volte tutto questo è difficile da realizzare. Il perfezionamento di queste +pratiche può richiedere anni (eventualmente). È un processo continuo di +miglioramento che richiede molta pazienza e determinazione. Ma non mollate, +si può fare. Molti lo hanno fatto prima, ed ognuno ha dovuto iniziare dove +siete voi ora. + + + + +---------- + +Grazie a Paolo Ciarrocchi che ha permesso che la sezione "Development Process" +(https://lwn.net/Articles/94386/) fosse basata sui testi da lui scritti, ed a +Randy Dunlap e Gerrit Huizenga per la lista di cose che dovreste e non +dovreste dire. Grazie anche a Pat Mochel, Hanna Linder, Randy Dunlap, +Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, +Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, e Alex Shepard per le +loro revisioni, commenti e contributi. Senza il loro aiuto, questo documento +non sarebbe stato possibile. + +Manutentore: Greg Kroah-Hartman <greg@kroah.com> diff --git a/Documentation/translations/it_IT/process/index.rst b/Documentation/translations/it_IT/process/index.rst new file mode 100644 index 000000000000..2eda85d5cd1e --- /dev/null +++ b/Documentation/translations/it_IT/process/index.rst @@ -0,0 +1,67 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/index.rst <process_index>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_process_index: + +Lavorare con la comunità di sviluppo del kernel +=============================================== + +Quindi volete diventare sviluppatori del kernel? Benvenuti! C'è molto da +imparare sul lato tecnico del kernel, ma è anche importante capire come +funziona la nostra comunità. Leggere questi documenti renderà più facile +l'accettazione delle vostre modifiche con il minimo sforzo. + +Di seguito le guide che ogni sviluppatore dovrebbe leggere. + +.. toctree:: + :maxdepth: 1 + + howto + code-of-conduct + development-process + submitting-patches + coding-style + maintainer-pgp-guide + email-clients + kernel-enforcement-statement + kernel-driver-statement + +Poi ci sono altre guide sulla comunità che sono di interesse per molti +degli sviluppatori: + +.. toctree:: + :maxdepth: 1 + + changes + submitting-drivers + stable-api-nonsense + management-style + stable-kernel-rules + submit-checklist + kernel-docs + +Ed infine, qui ci sono alcune guide più tecniche che son state messe qua solo +perché non si è trovato un posto migliore. + +.. toctree:: + :maxdepth: 1 + + applying-patches + adding-syscalls + magic-number + volatile-considered-harmful + clang-format + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/process/kernel-docs.rst b/Documentation/translations/it_IT/process/kernel-docs.rst new file mode 100644 index 000000000000..7bd70d661737 --- /dev/null +++ b/Documentation/translations/it_IT/process/kernel-docs.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/kernel-docs.rst <kernel_docs>` + + +.. _it_kernel_docs: + +Indice di documenti per le persone interessate a capire e/o scrivere per il kernel Linux +======================================================================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/kernel-driver-statement.rst b/Documentation/translations/it_IT/process/kernel-driver-statement.rst new file mode 100644 index 000000000000..f016a75a9d6e --- /dev/null +++ b/Documentation/translations/it_IT/process/kernel-driver-statement.rst @@ -0,0 +1,211 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/kernel-driver-statement.rst <process_statement_driver>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_process_statement_driver: + +Dichiarazioni sui driver per il kernel +====================================== + +Presa di posizione sui moduli per il kernel Linux +------------------------------------------------- + +Noi, i sottoscritti sviluppatori del kernel, consideriamo pericoloso +o indesiderato qualsiasi modulo o driver per il kernel Linux di tipo +*a sorgenti chiusi* (*closed-source*). Ripetutamente, li abbiamo +trovati deleteri per gli utenti Linux, le aziende, ed in generale +l'ecosistema Linux. Questi moduli impediscono l'apertura, la stabilità, +la flessibilità, e la manutenibilità del modello di sviluppo di Linux +e impediscono ai loro utenti di beneficiare dell'esperienza dalla +comunità Linux. I fornitori che distribuiscono codice a sorgenti chiusi +obbligano i propri utenti a rinunciare ai principali vantaggi di Linux +o a cercarsi nuovi fornitori. +Perciò, al fine di sfruttare i vantaggi che codice aperto ha da offrire, +come l'abbattimento dei costi e un supporto condiviso, spingiamo i +fornitori ad adottare una politica di supporto ai loro clienti Linux +che preveda il rilascio dei sorgenti per il kernel. + +Parliamo solo per noi stessi, e non per una qualsiasi azienda per la +quale lavoriamo oggi, o abbiamo lavorato in passato, o lavoreremo in +futuro. + + + - Dave Airlie + - Nick Andrew + - Jens Axboe + - Ralf Baechle + - Felipe Balbi + - Ohad Ben-Cohen + - Muli Ben-Yehuda + - Jiri Benc + - Arnd Bergmann + - Thomas Bogendoerfer + - Vitaly Bordug + - James Bottomley + - Josh Boyer + - Neil Brown + - Mark Brown + - David Brownell + - Michael Buesch + - Franck Bui-Huu + - Adrian Bunk + - François Cami + - Ralph Campbell + - Luiz Fernando N. Capitulino + - Mauro Carvalho Chehab + - Denis Cheng + - Jonathan Corbet + - Glauber Costa + - Alan Cox + - Magnus Damm + - Ahmed S. Darwish + - Robert P. J. Day + - Hans de Goede + - Arnaldo Carvalho de Melo + - Helge Deller + - Jean Delvare + - Mathieu Desnoyers + - Sven-Thorsten Dietrich + - Alexey Dobriyan + - Daniel Drake + - Alex Dubov + - Randy Dunlap + - Michael Ellerman + - Pekka Enberg + - Jan Engelhardt + - Mark Fasheh + - J. Bruce Fields + - Larry Finger + - Jeremy Fitzhardinge + - Mike Frysinger + - Kumar Gala + - Robin Getz + - Liam Girdwood + - Jan-Benedict Glaw + - Thomas Gleixner + - Brice Goglin + - Cyrill Gorcunov + - Andy Gospodarek + - Thomas Graf + - Krzysztof Halasa + - Harvey Harrison + - Stephen Hemminger + - Michael Hennerich + - Tejun Heo + - Benjamin Herrenschmidt + - Kristian Høgsberg + - Henrique de Moraes Holschuh + - Marcel Holtmann + - Mike Isely + - Takashi Iwai + - Olof Johansson + - Dave Jones + - Jesper Juhl + - Matthias Kaehlcke + - Kenji Kaneshige + - Jan Kara + - Jeremy Kerr + - Russell King + - Olaf Kirch + - Roel Kluin + - Hans-Jürgen Koch + - Auke Kok + - Peter Korsgaard + - Jiri Kosina + - Aaro Koskinen + - Mariusz Kozlowski + - Greg Kroah-Hartman + - Michael Krufky + - Aneesh Kumar + - Clemens Ladisch + - Christoph Lameter + - Gunnar Larisch + - Anders Larsen + - Grant Likely + - John W. Linville + - Yinghai Lu + - Tony Luck + - Pavel Machek + - Matt Mackall + - Paul Mackerras + - Roland McGrath + - Patrick McHardy + - Kyle McMartin + - Paul Menage + - Thierry Merle + - Eric Miao + - Akinobu Mita + - Ingo Molnar + - James Morris + - Andrew Morton + - Paul Mundt + - Oleg Nesterov + - Luca Olivetti + - S.Çağlar Onur + - Pierre Ossman + - Keith Owens + - Venkatesh Pallipadi + - Nick Piggin + - Nicolas Pitre + - Evgeniy Polyakov + - Richard Purdie + - Mike Rapoport + - Sam Ravnborg + - Gerrit Renker + - Stefan Richter + - David Rientjes + - Luis R. Rodriguez + - Stefan Roese + - Francois Romieu + - Rami Rosen + - Stephen Rothwell + - Maciej W. Rozycki + - Mark Salyzyn + - Yoshinori Sato + - Deepak Saxena + - Holger Schurig + - Amit Shah + - Yoshihiro Shimoda + - Sergei Shtylyov + - Kay Sievers + - Sebastian Siewior + - Rik Snel + - Jes Sorensen + - Alexey Starikovskiy + - Alan Stern + - Timur Tabi + - Hirokazu Takata + - Eliezer Tamir + - Eugene Teo + - Doug Thompson + - FUJITA Tomonori + - Dmitry Torokhov + - Marcelo Tosatti + - Steven Toth + - Theodore Tso + - Matthias Urlichs + - Geert Uytterhoeven + - Arjan van de Ven + - Ivo van Doorn + - Rik van Riel + - Wim Van Sebroeck + - Hans Verkuil + - Horst H. von Brand + - Dmitri Vorobiev + - Anton Vorontsov + - Daniel Walker + - Johannes Weiner + - Harald Welte + - Matthew Wilcox + - Dan J. Williams + - Darrick J. Wong + - David Woodhouse + - Chris Wright + - Bryan Wu + - Rafael J. Wysocki + - Herbert Xu + - Vlad Yasevich + - Peter Zijlstra + - Bartlomiej Zolnierkiewicz + diff --git a/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst b/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst new file mode 100644 index 000000000000..4ddf5a35b270 --- /dev/null +++ b/Documentation/translations/it_IT/process/kernel-enforcement-statement.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/kernel-enforcement-statement.rst <process_statement_kernel>` + + +.. _it_process_statement_kernel: + +Applicazione della licenza sul kernel Linux +=========================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/magic-number.rst b/Documentation/translations/it_IT/process/magic-number.rst new file mode 100644 index 000000000000..5281d53e57ee --- /dev/null +++ b/Documentation/translations/it_IT/process/magic-number.rst @@ -0,0 +1,170 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/magic-numbers.rst <magicnumbers>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_magicnumbers: + +I numeri magici di Linux +======================== + +Questo documento è un registro dei numeri magici in uso. Quando +aggiungete un numero magico ad una struttura, dovreste aggiungerlo anche +a questo documento; la cosa migliore è che tutti i numeri magici usati +dalle varie strutture siano unici. + +È **davvero** un'ottima idea proteggere le strutture dati del kernel con +dei numeri magici. Questo vi permette in fase d'esecuzione di (a) verificare +se una struttura è stata malmenata, o (b) avete passato a una procedura la +struttura errata. Quest'ultimo è molto utile - particolarmente quando si passa +una struttura dati tramite un puntatore void \*. Il codice tty, per esempio, +effettua questa operazione con regolarità passando avanti e indietro le +strutture specifiche per driver e discipline. + +Per utilizzare un numero magico, dovete dichiararlo all'inizio della struttura +dati, come di seguito:: + + struct tty_ldisc { + int magic; + ... + }; + +Per favore, seguite questa direttiva quando aggiungerete migliorie al kernel! +Mi ha risparmiato un numero illimitato di ore di debug, specialmente nei casi +più ostici dove si è andati oltre la dimensione di un vettore e la struttura +dati che lo seguiva in memoria è stata sovrascritta. Seguendo questa +direttiva, questi casi vengono identificati velocemente e in sicurezza. + +Registro dei cambiamenti:: + + Theodore Ts'o + 31 Mar 94 + + La tabella magica è aggiornata a Linux 2.1.55. + + Michael Chastain + <mailto:mec@shout.net> + 22 Sep 1997 + + Ora dovrebbe essere aggiornata a Linux 2.1.112. Dato che + siamo in un momento di congelamento delle funzionalità + (*feature freeze*) è improbabile che qualcosa cambi prima + della versione 2.2.x. Le righe sono ordinate secondo il + campo numero. + + Krzysztof G. Baranowski + <mailto: kgb@knm.org.pl> + 29 Jul 1998 + + Aggiornamento della tabella a Linux 2.5.45. Giusti nel congelamento + delle funzionalità ma è comunque possibile che qualche nuovo + numero magico s'intrufoli prima del kernel 2.6.x. + + Petr Baudis + <pasky@ucw.cz> + 03 Nov 2002 + + Aggiornamento della tabella magica a Linux 2.5.74. + + Fabian Frederick + <ffrederick@users.sourceforge.net> + 09 Jul 2003 + + +===================== ================ ======================== ========================================== +Nome magico Numero Struttura File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== + +Da notare che ci sono anche dei numeri magici specifici per driver nel +*sound memory management*. Consultate ``include/sound/sndmagic.h`` per una +lista completa. Molti driver audio OSS hanno i loro numeri magici costruiti a +partire dall'identificativo PCI della scheda audio - nemmeno questi sono +elencati in questo file. + +Il file-system HFS è un altro grande utilizzatore di numeri magici - potete +trovarli qui ``fs/hfs/hfs.h``. diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst new file mode 100644 index 000000000000..24a133f0a51d --- /dev/null +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/maintainer-pgp-guide.rst <pgpguide>` + +.. _it_pgpguide: + +======================================== +Guida a PGP per i manutentori del kernel +======================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/management-style.rst b/Documentation/translations/it_IT/process/management-style.rst new file mode 100644 index 000000000000..07e68bfb8402 --- /dev/null +++ b/Documentation/translations/it_IT/process/management-style.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/management-style.rst <managementstyle>` + +.. _it_managementstyle: + +Tipo di gestione del kernel Linux +================================= + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/stable-api-nonsense.rst b/Documentation/translations/it_IT/process/stable-api-nonsense.rst new file mode 100644 index 000000000000..d4fa4abf8dd3 --- /dev/null +++ b/Documentation/translations/it_IT/process/stable-api-nonsense.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` + + +.. _it_stable_api_nonsense: + +L'interfaccia dei driver per il kernel Linux +============================================ + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/stable-kernel-rules.rst b/Documentation/translations/it_IT/process/stable-kernel-rules.rst new file mode 100644 index 000000000000..6fa5ce9c3572 --- /dev/null +++ b/Documentation/translations/it_IT/process/stable-kernel-rules.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` + +.. _it_stable_kernel_rules: + +Tutto quello che volevate sapere sui rilasci -stable di Linux +============================================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst new file mode 100644 index 000000000000..b6b4dd94a660 --- /dev/null +++ b/Documentation/translations/it_IT/process/submit-checklist.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/submit-checklist.rst <submitchecklist>` + +.. _it_submitchecklist: + +Lista delle cose da fare per inviare una modifica al kernel Linux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/submitting-drivers.rst b/Documentation/translations/it_IT/process/submitting-drivers.rst new file mode 100644 index 000000000000..16df950ef808 --- /dev/null +++ b/Documentation/translations/it_IT/process/submitting-drivers.rst @@ -0,0 +1,12 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` + +.. _it_submittingdrivers: + +Sottomettere driver per il kernel Linux +======================================= + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst new file mode 100644 index 000000000000..d633775ed556 --- /dev/null +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -0,0 +1,13 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + + +.. _it_submittingpatches: + +Sottomettere modifiche: la guida essenziale per vedere il vostro codice nel kernel +================================================================================== + +.. warning:: + + TODO ancora da tradurre diff --git a/Documentation/translations/it_IT/process/volatile-considered-harmful.rst b/Documentation/translations/it_IT/process/volatile-considered-harmful.rst new file mode 100644 index 000000000000..efc640cac596 --- /dev/null +++ b/Documentation/translations/it_IT/process/volatile-considered-harmful.rst @@ -0,0 +1,134 @@ +.. include:: ../disclaimer-ita.rst + +:Original: :ref:`Documentation/process/volatile-considered-harmful.rst <volatile_considered_harmful>` +:Translator: Federico Vaga <federico.vaga@vaga.pv.it> + +.. _it_volatile_considered_harmful: + +Perché la parola chiave "volatile" non dovrebbe essere usata +------------------------------------------------------------ + +Spesso i programmatori C considerano volatili quelle variabili che potrebbero +essere cambiate al di fuori dal thread di esecuzione corrente; come risultato, +a volte saranno tentati dall'utilizzare *volatile* nel kernel per le +strutture dati condivise. In altre parole, gli è stato insegnato ad usare +*volatile* come una variabile atomica di facile utilizzo, ma non è così. +L'uso di *volatile* nel kernel non è quasi mai corretto; questo documento ne +descrive le ragioni. + +Il punto chiave da capire su *volatile* è che il suo scopo è quello di +sopprimere le ottimizzazioni, che non è quasi mai quello che si vuole. +Nel kernel si devono proteggere le strutture dati condivise contro accessi +concorrenti e indesiderati: questa è un'attività completamente diversa. +Il processo di protezione contro gli accessi concorrenti indesiderati eviterà +anche la maggior parte dei problemi relativi all'ottimizzazione in modo più +efficiente. + +Come *volatile*, le primitive del kernel che rendono sicuro l'accesso ai dati +(spinlock, mutex, barriere di sincronizzazione, ecc) sono progettate per +prevenire le ottimizzazioni indesiderate. Se vengono usate opportunamente, +non ci sarà bisogno di utilizzare *volatile*. Se vi sembra che *volatile* sia +comunque necessario, ci dev'essere quasi sicuramente un baco da qualche parte. +In un pezzo di codice kernel scritto a dovere, *volatile* può solo servire a +rallentare le cose. + +Considerate questo tipico blocco di codice kernel:: + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +Se tutto il codice seguisse le regole di sincronizzazione, il valore di un +dato condiviso non potrebbe cambiare inaspettatamente mentre si trattiene un +lock. Un qualsiasi altro blocco di codice che vorrà usare quel dato rimarrà +in attesa del lock. Gli spinlock agiscono come barriere di sincronizzazione +- sono stati esplicitamente scritti per agire così - il che significa che gli +accessi al dato condiviso non saranno ottimizzati. Quindi il compilatore +potrebbe pensare di sapere cosa ci sarà nel dato condiviso ma la chiamata +spin_lock(), che agisce come una barriera di sincronizzazione, gli imporrà di +dimenticarsi tutto ciò che sapeva su di esso. + +Se il dato condiviso fosse stato dichiarato come *volatile*, la +sincronizzazione rimarrebbe comunque necessaria. Ma verrà impedito al +compilatore di ottimizzare gli accessi al dato anche _dentro_ alla sezione +critica, dove sappiamo che in realtà nessun altro può accedervi. Mentre si +trattiene un lock, il dato condiviso non è *volatile*. Quando si ha a che +fare con dei dati condivisi, un'opportuna sincronizzazione rende inutile +l'uso di *volatile* - anzi potenzialmente dannoso. + +L'uso di *volatile* fu originalmente pensato per l'accesso ai registri di I/O +mappati in memoria. All'interno del kernel, l'accesso ai registri, dovrebbe +essere protetto dai lock, ma si potrebbe anche desiderare che il compilatore +non "ottimizzi" l'accesso ai registri all'interno di una sezione critica. +Ma, all'interno del kernel, l'accesso alla memoria di I/O viene sempre fatto +attraverso funzioni d'accesso; accedere alla memoria di I/O direttamente +con i puntatori è sconsigliato e non funziona su tutte le architetture. +Queste funzioni d'accesso sono scritte per evitare ottimizzazioni indesiderate, +quindi, di nuovo, *volatile* è inutile. + +Un'altra situazione dove qualcuno potrebbe essere tentato dall'uso di +*volatile*, è nel caso in cui il processore è in un'attesa attiva sul valore +di una variabile. Il modo giusto di fare questo tipo di attesa è il seguente:: + + while (my_variable != what_i_want) + cpu_relax(); + +La chiamata cpu_relax() può ridurre il consumo di energia del processore +o cedere il passo ad un processore hyperthreaded gemello; funziona anche come +una barriera per il compilatore, quindi, ancora una volta, *volatile* non è +necessario. Ovviamente, tanto per puntualizzare, le attese attive sono +generalmente un atto antisociale. + +Ci sono comunque alcune rare situazioni dove l'uso di *volatile* nel kernel +ha senso: + + - Le funzioni d'accesso sopracitate potrebbero usare *volatile* su quelle + architetture che supportano l'accesso diretto alla memoria di I/O. + In pratica, ogni chiamata ad una funzione d'accesso diventa una piccola + sezione critica a se stante, e garantisce che l'accesso avvenga secondo + le aspettative del programmatore. + + - I codice *inline assembly* che fa cambiamenti nella memoria, ma che non + ha altri effetti espliciti, rischia di essere rimosso da GCC. Aggiungere + la parola chiave *volatile* a questo codice ne previene la rimozione. + + - La variabile jiffies è speciale in quanto assume un valore diverso ogni + volta che viene letta ma può essere lette senza alcuna sincronizzazione. + Quindi jiffies può essere *volatile*, ma l'aggiunta ad altre variabili di + questo è sconsigliata. Jiffies è considerata uno "stupido retaggio" + (parole di Linus) in questo contesto; correggerla non ne varrebbe la pena e + causerebbe più problemi. + + - I puntatori a delle strutture dati in una memoria coerente che potrebbe + essere modificata da dispositivi di I/O può, a volte, essere legittimamente + *volatile*. Un esempio pratico può essere quello di un adattatore di rete + che utilizza un puntatore ad un buffer circolare, questo viene cambiato + dall'adattatore per indicare quali descrittori sono stati processati. + +Per la maggior parte del codice, nessuna delle giustificazioni sopracitate può +essere considerata. Di conseguenza, l'uso di *volatile* è probabile che venga +visto come un baco e porterà a verifiche aggiuntive. Gli sviluppatori tentati +dall'uso di *volatile* dovrebbero fermarsi e pensare a cosa vogliono davvero +ottenere. + +Le modifiche che rimuovono variabili *volatile* sono generalmente ben accette +- purché accompagnate da una giustificazione che dimostri che i problemi di +concorrenza siano stati opportunamente considerati. + +Riferimenti +=========== + +[1] http://lwn.net/Articles/233481/ + +[2] http://lwn.net/Articles/233482/ + +Crediti +======= + +Impulso e ricerca originale di Randy Dunlap + +Scritto da Jonathan Corbet + +Migliorato dai commenti di Satyam Sharma, Johannes Stezenbach, Jesper +Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, e Stefan Richter. diff --git a/Documentation/usb/authorization.txt b/Documentation/usb/authorization.txt index c7e985f05d8f..9dd1dc7b1009 100644 --- a/Documentation/usb/authorization.txt +++ b/Documentation/usb/authorization.txt @@ -34,7 +34,9 @@ $ echo 1 > /sys/bus/usb/devices/usbX/authorized_default By default, Wired USB devices are authorized by default to connect. Wireless USB hosts deauthorize by default all new connected devices (this is so because we need to do an authentication phase -before authorizing). +before authorizing). Writing "2" to the authorized_default attribute +causes kernel to only authorize by default devices connected to internal +USB ports. Example system lockdown (lame) @@ -119,5 +121,5 @@ If a deauthorized interface will be authorized so the driver probing must be triggered manually by writing INTERFACE to /sys/bus/usb/drivers_probe For drivers that need multiple interfaces all needed interfaces should be -authroized first. After that the drivers should be probed. +authorized first. After that the drivers should be probed. This avoids side effects. diff --git a/Documentation/userspace-api/seccomp_filter.rst b/Documentation/userspace-api/seccomp_filter.rst index 82a468bc7560..b1b846d8a094 100644 --- a/Documentation/userspace-api/seccomp_filter.rst +++ b/Documentation/userspace-api/seccomp_filter.rst @@ -122,6 +122,11 @@ In precedence order, they are: Results in the lower 16-bits of the return value being passed to userland as the errno without executing the system call. +``SECCOMP_RET_USER_NOTIF``: + Results in a ``struct seccomp_notif`` message sent on the userspace + notification fd, if it is attached, or ``-ENOSYS`` if it is not. See below + on discussion of how to handle user notifications. + ``SECCOMP_RET_TRACE``: When returned, this value will cause the kernel to attempt to notify a ``ptrace()``-based tracer prior to executing the system @@ -183,6 +188,85 @@ The ``samples/seccomp/`` directory contains both an x86-specific example and a more generic example of a higher level macro interface for BPF program generation. +Userspace Notification +====================== + +The ``SECCOMP_RET_USER_NOTIF`` return code lets seccomp filters pass a +particular syscall to userspace to be handled. This may be useful for +applications like container managers, which wish to intercept particular +syscalls (``mount()``, ``finit_module()``, etc.) and change their behavior. + +To acquire a notification FD, use the ``SECCOMP_FILTER_FLAG_NEW_LISTENER`` +argument to the ``seccomp()`` syscall: + +.. code-block:: c + + fd = seccomp(SECCOMP_SET_MODE_FILTER, SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog); + +which (on success) will return a listener fd for the filter, which can then be +passed around via ``SCM_RIGHTS`` or similar. Note that filter fds correspond to +a particular filter, and not a particular task. So if this task then forks, +notifications from both tasks will appear on the same filter fd. Reads and +writes to/from a filter fd are also synchronized, so a filter fd can safely +have many readers. + +The interface for a seccomp notification fd consists of two structures: + +.. code-block:: c + + struct seccomp_notif_sizes { + __u16 seccomp_notif; + __u16 seccomp_notif_resp; + __u16 seccomp_data; + }; + + struct seccomp_notif { + __u64 id; + __u32 pid; + __u32 flags; + struct seccomp_data data; + }; + + struct seccomp_notif_resp { + __u64 id; + __s64 val; + __s32 error; + __u32 flags; + }; + +The ``struct seccomp_notif_sizes`` structure can be used to determine the size +of the various structures used in seccomp notifications. The size of ``struct +seccomp_data`` may change in the future, so code should use: + +.. code-block:: c + + struct seccomp_notif_sizes sizes; + seccomp(SECCOMP_GET_NOTIF_SIZES, 0, &sizes); + +to determine the size of the various structures to allocate. See +samples/seccomp/user-trap.c for an example. + +Users can read via ``ioctl(SECCOMP_IOCTL_NOTIF_RECV)`` (or ``poll()``) on a +seccomp notification fd to receive a ``struct seccomp_notif``, which contains +five members: the input length of the structure, a unique-per-filter ``id``, +the ``pid`` of the task which triggered this request (which may be 0 if the +task is in a pid ns not visible from the listener's pid namespace), a ``flags`` +member which for now only has ``SECCOMP_NOTIF_FLAG_SIGNALED``, representing +whether or not the notification is a result of a non-fatal signal, and the +``data`` passed to seccomp. Userspace can then make a decision based on this +information about what to do, and ``ioctl(SECCOMP_IOCTL_NOTIF_SEND)`` a +response, indicating what should be returned to userspace. The ``id`` member of +``struct seccomp_notif_resp`` should be the same ``id`` as in ``struct +seccomp_notif``. + +It is worth noting that ``struct seccomp_data`` contains the values of register +arguments to the syscall, but does not contain pointers to memory. The task's +memory is accessible to suitably privileged traces via ``ptrace()`` or +``/proc/pid/mem``. However, care should be taken to avoid the TOCTOU mentioned +above in this document: all arguments being read from the tracee's memory +should be read into the tracer's memory before any policy decisions are made. +This allows for an atomic decision on syscall arguments. + Sysctls ======= diff --git a/Documentation/userspace-api/spec_ctrl.rst b/Documentation/userspace-api/spec_ctrl.rst index 32f3d55c54b7..1129c7550a48 100644 --- a/Documentation/userspace-api/spec_ctrl.rst +++ b/Documentation/userspace-api/spec_ctrl.rst @@ -28,18 +28,20 @@ PR_GET_SPECULATION_CTRL returns the state of the speculation misfeature which is selected with arg2 of prctl(2). The return value uses bits 0-3 with the following meaning: -==== ===================== =================================================== -Bit Define Description -==== ===================== =================================================== -0 PR_SPEC_PRCTL Mitigation can be controlled per task by - PR_SET_SPECULATION_CTRL. -1 PR_SPEC_ENABLE The speculation feature is enabled, mitigation is - disabled. -2 PR_SPEC_DISABLE The speculation feature is disabled, mitigation is - enabled. -3 PR_SPEC_FORCE_DISABLE Same as PR_SPEC_DISABLE, but cannot be undone. A - subsequent prctl(..., PR_SPEC_ENABLE) will fail. -==== ===================== =================================================== +==== ====================== ================================================== +Bit Define Description +==== ====================== ================================================== +0 PR_SPEC_PRCTL Mitigation can be controlled per task by + PR_SET_SPECULATION_CTRL. +1 PR_SPEC_ENABLE The speculation feature is enabled, mitigation is + disabled. +2 PR_SPEC_DISABLE The speculation feature is disabled, mitigation is + enabled. +3 PR_SPEC_FORCE_DISABLE Same as PR_SPEC_DISABLE, but cannot be undone. A + subsequent prctl(..., PR_SPEC_ENABLE) will fail. +4 PR_SPEC_DISABLE_NOEXEC Same as PR_SPEC_DISABLE, but the state will be + cleared on :manpage:`execve(2)`. +==== ====================== ================================================== If all bits are 0 the CPU is not affected by the speculation misfeature. @@ -92,3 +94,13 @@ Speculation misfeature controls * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_ENABLE, 0, 0); * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_DISABLE, 0, 0); * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_FORCE_DISABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_STORE_BYPASS, PR_SPEC_DISABLE_NOEXEC, 0, 0); + +- PR_SPEC_INDIR_BRANCH: Indirect Branch Speculation in User Processes + (Mitigate Spectre V2 style attacks against user processes) + + Invocations: + * prctl(PR_GET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, 0, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_ENABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE, 0, 0); + * prctl(PR_SET_SPECULATION_CTRL, PR_SPEC_INDIRECT_BRANCH, PR_SPEC_FORCE_DISABLE, 0, 0); diff --git a/Documentation/virtual/kvm/amd-memory-encryption.rst b/Documentation/virtual/kvm/amd-memory-encryption.rst index 71d6d257074f..659bbc093b52 100644 --- a/Documentation/virtual/kvm/amd-memory-encryption.rst +++ b/Documentation/virtual/kvm/amd-memory-encryption.rst @@ -242,6 +242,6 @@ References ========== .. [white-paper] http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2013/12/AMD_Memory_Encryption_Whitepaper_v7-Public.pdf -.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM%20API_Specification.pdf +.. [api-spec] http://support.amd.com/TechDocs/55766_SEV-KM_API_Specification.pdf .. [amd-apm] http://support.amd.com/TechDocs/24593.pdf (section 15.34) .. [kvm-forum] http://www.linux-kvm.org/images/7/74/02x08A-Thomas_Lendacky-AMDs_Virtualizatoin_Memory_Encryption_Technology.pdf diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 647f94128a85..356156f5c52d 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -123,6 +123,37 @@ memory layout to fit in user mode), check KVM_CAP_MIPS_VZ and use the flag KVM_VM_MIPS_VZ. +On arm64, the physical address size for a VM (IPA Size limit) is limited +to 40bits by default. The limit can be configured if the host supports the +extension KVM_CAP_ARM_VM_IPA_SIZE. When supported, use +KVM_VM_TYPE_ARM_IPA_SIZE(IPA_Bits) to set the size in the machine type +identifier, where IPA_Bits is the maximum width of any physical +address used by the VM. The IPA_Bits is encoded in bits[7-0] of the +machine type identifier. + +e.g, to configure a guest to use 48bit physical address size : + + vm_fd = ioctl(dev_fd, KVM_CREATE_VM, KVM_VM_TYPE_ARM_IPA_SIZE(48)); + +The requested size (IPA_Bits) must be : + 0 - Implies default size, 40bits (for backward compatibility) + + or + + N - Implies N bits, where N is a positive integer such that, + 32 <= N <= Host_IPA_Limit + +Host_IPA_Limit is the maximum possible value for IPA_Bits on the host and +is dependent on the CPU capability and the kernel configuration. The limit can +be retrieved using KVM_CAP_ARM_VM_IPA_SIZE of the KVM_CHECK_EXTENSION +ioctl() at run-time. + +Please note that configuring the IPA size does not affect the capability +exposed by the guest CPUs in ID_AA64MMFR0_EL1[PARange]. It only affects +size of the address translated by the stage2 level (guest physical to +host physical address translations). + + 4.3 KVM_GET_MSR_INDEX_LIST, KVM_GET_MSR_FEATURE_INDEX_LIST Capability: basic, KVM_CAP_GET_MSR_FEATURES for KVM_GET_MSR_FEATURE_INDEX_LIST @@ -274,6 +305,9 @@ the address space for which you want to return the dirty bitmap. They must be less than the value that KVM_CHECK_EXTENSION returns for the KVM_CAP_MULTI_ADDRESS_SPACE capability. +The bits in the dirty bitmap are cleared before the ioctl returns, unless +KVM_CAP_MANUAL_DIRTY_LOG_PROTECT is enabled. For more information, +see the description of the capability. 4.9 KVM_SET_MEMORY_ALIAS @@ -850,7 +884,7 @@ struct kvm_vcpu_events { __u8 injected; __u8 nr; __u8 has_error_code; - __u8 pad; + __u8 pending; __u32 error_code; } exception; struct { @@ -873,15 +907,23 @@ struct kvm_vcpu_events { __u8 smm_inside_nmi; __u8 latched_init; } smi; + __u8 reserved[27]; + __u8 exception_has_payload; + __u64 exception_payload; }; -Only two fields are defined in the flags field: +The following bits are defined in the flags field: -- KVM_VCPUEVENT_VALID_SHADOW may be set in the flags field to signal that +- KVM_VCPUEVENT_VALID_SHADOW may be set to signal that interrupt.shadow contains a valid state. -- KVM_VCPUEVENT_VALID_SMM may be set in the flags field to signal that - smi contains a valid state. +- KVM_VCPUEVENT_VALID_SMM may be set to signal that smi contains a + valid state. + +- KVM_VCPUEVENT_VALID_PAYLOAD may be set to signal that the + exception_has_payload, exception_payload, and exception.pending + fields contain a valid state. This bit will be set whenever + KVM_CAP_EXCEPTION_PAYLOAD is enabled. ARM/ARM64: @@ -961,6 +1003,11 @@ shall be written into the VCPU. KVM_VCPUEVENT_VALID_SMM can only be set if KVM_CAP_X86_SMM is available. +If KVM_CAP_EXCEPTION_PAYLOAD is enabled, KVM_VCPUEVENT_VALID_PAYLOAD +can be set in the flags field to signal that the +exception_has_payload, exception_payload, and exception.pending fields +contain a valid state and shall be written into the VCPU. + ARM/ARM64: Set the pending SError exception state for this VCPU. It is not possible to @@ -1085,10 +1132,15 @@ documentation when it pops into existence). 4.37 KVM_ENABLE_CAP -Capability: KVM_CAP_ENABLE_CAP, KVM_CAP_ENABLE_CAP_VM -Architectures: x86 (only KVM_CAP_ENABLE_CAP_VM), - mips (only KVM_CAP_ENABLE_CAP), ppc, s390 -Type: vcpu ioctl, vm ioctl (with KVM_CAP_ENABLE_CAP_VM) +Capability: KVM_CAP_ENABLE_CAP +Architectures: mips, ppc, s390 +Type: vcpu ioctl +Parameters: struct kvm_enable_cap (in) +Returns: 0 on success; -1 on error + +Capability: KVM_CAP_ENABLE_CAP_VM +Architectures: all +Type: vcpu ioctl Parameters: struct kvm_enable_cap (in) Returns: 0 on success; -1 on error @@ -1922,6 +1974,7 @@ registers, find a list below: PPC | KVM_REG_PPC_TIDR | 64 PPC | KVM_REG_PPC_PSSCR | 64 PPC | KVM_REG_PPC_DEC_EXPIRY | 64 + PPC | KVM_REG_PPC_PTCR | 64 PPC | KVM_REG_PPC_TM_GPR0 | 64 ... PPC | KVM_REG_PPC_TM_GPR31 | 64 @@ -2269,6 +2322,10 @@ The supported flags are: The emulated MMU supports 1T segments in addition to the standard 256M ones. + - KVM_PPC_NO_HASH + This flag indicates that HPT guests are not supported by KVM, + thus all guests must use radix MMU mode. + The "slb_size" field indicates how many SLB entries are supported The "sps" array contains 8 entries indicating the supported base @@ -3676,6 +3733,130 @@ Returns: 0 on success, -1 on error This copies the vcpu's kvm_nested_state struct from userspace to the kernel. For the definition of struct kvm_nested_state, see KVM_GET_NESTED_STATE. +4.116 KVM_(UN)REGISTER_COALESCED_MMIO + +Capability: KVM_CAP_COALESCED_MMIO (for coalesced mmio) + KVM_CAP_COALESCED_PIO (for coalesced pio) +Architectures: all +Type: vm ioctl +Parameters: struct kvm_coalesced_mmio_zone +Returns: 0 on success, < 0 on error + +Coalesced I/O is a performance optimization that defers hardware +register write emulation so that userspace exits are avoided. It is +typically used to reduce the overhead of emulating frequently accessed +hardware registers. + +When a hardware register is configured for coalesced I/O, write accesses +do not exit to userspace and their value is recorded in a ring buffer +that is shared between kernel and userspace. + +Coalesced I/O is used if one or more write accesses to a hardware +register can be deferred until a read or a write to another hardware +register on the same device. This last access will cause a vmexit and +userspace will process accesses from the ring buffer before emulating +it. That will avoid exiting to userspace on repeated writes. + +Coalesced pio is based on coalesced mmio. There is little difference +between coalesced mmio and pio except that coalesced pio records accesses +to I/O ports. + +4.117 KVM_CLEAR_DIRTY_LOG (vm ioctl) + +Capability: KVM_CAP_MANUAL_DIRTY_LOG_PROTECT +Architectures: x86 +Type: vm ioctl +Parameters: struct kvm_dirty_log (in) +Returns: 0 on success, -1 on error + +/* for KVM_CLEAR_DIRTY_LOG */ +struct kvm_clear_dirty_log { + __u32 slot; + __u32 num_pages; + __u64 first_page; + union { + void __user *dirty_bitmap; /* one bit per page */ + __u64 padding; + }; +}; + +The ioctl clears the dirty status of pages in a memory slot, according to +the bitmap that is passed in struct kvm_clear_dirty_log's dirty_bitmap +field. Bit 0 of the bitmap corresponds to page "first_page" in the +memory slot, and num_pages is the size in bits of the input bitmap. +Both first_page and num_pages must be a multiple of 64. For each bit +that is set in the input bitmap, the corresponding page is marked "clean" +in KVM's dirty bitmap, and dirty tracking is re-enabled for that page +(for example via write-protection, or by clearing the dirty bit in +a page table entry). + +If KVM_CAP_MULTI_ADDRESS_SPACE is available, bits 16-31 specifies +the address space for which you want to return the dirty bitmap. +They must be less than the value that KVM_CHECK_EXTENSION returns for +the KVM_CAP_MULTI_ADDRESS_SPACE capability. + +This ioctl is mostly useful when KVM_CAP_MANUAL_DIRTY_LOG_PROTECT +is enabled; for more information, see the description of the capability. +However, it can always be used as long as KVM_CHECK_EXTENSION confirms +that KVM_CAP_MANUAL_DIRTY_LOG_PROTECT is present. + +4.118 KVM_GET_SUPPORTED_HV_CPUID + +Capability: KVM_CAP_HYPERV_CPUID +Architectures: x86 +Type: vcpu ioctl +Parameters: struct kvm_cpuid2 (in/out) +Returns: 0 on success, -1 on error + +struct kvm_cpuid2 { + __u32 nent; + __u32 padding; + struct kvm_cpuid_entry2 entries[0]; +}; + +struct kvm_cpuid_entry2 { + __u32 function; + __u32 index; + __u32 flags; + __u32 eax; + __u32 ebx; + __u32 ecx; + __u32 edx; + __u32 padding[3]; +}; + +This ioctl returns x86 cpuid features leaves related to Hyper-V emulation in +KVM. Userspace can use the information returned by this ioctl to construct +cpuid information presented to guests consuming Hyper-V enlightenments (e.g. +Windows or Hyper-V guests). + +CPUID feature leaves returned by this ioctl are defined by Hyper-V Top Level +Functional Specification (TLFS). These leaves can't be obtained with +KVM_GET_SUPPORTED_CPUID ioctl because some of them intersect with KVM feature +leaves (0x40000000, 0x40000001). + +Currently, the following list of CPUID leaves are returned: + HYPERV_CPUID_VENDOR_AND_MAX_FUNCTIONS + HYPERV_CPUID_INTERFACE + HYPERV_CPUID_VERSION + HYPERV_CPUID_FEATURES + HYPERV_CPUID_ENLIGHTMENT_INFO + HYPERV_CPUID_IMPLEMENT_LIMITS + HYPERV_CPUID_NESTED_FEATURES + +HYPERV_CPUID_NESTED_FEATURES leaf is only exposed when Enlightened VMCS was +enabled on the corresponding vCPU (KVM_CAP_HYPERV_ENLIGHTENED_VMCS). + +Userspace invokes KVM_GET_SUPPORTED_CPUID by passing a kvm_cpuid2 structure +with the 'nent' field indicating the number of entries in the variable-size +array 'entries'. If the number of entries is too low to describe all Hyper-V +feature leaves, an error (E2BIG) is returned. If the number is more or equal +to the number of Hyper-V feature leaves, the 'nent' field is adjusted to the +number of valid entries in the 'entries' array, which is then filled. + +'index' and 'flags' fields in 'struct kvm_cpuid_entry2' are currently reserved, +userspace should not expect to get any particular value there. + 5. The kvm_run structure ------------------------ @@ -4522,7 +4703,7 @@ hpage module parameter is not set to 1, -EINVAL is returned. While it is generally possible to create a huge page backed VM without this capability, the VM will not be able to run. -7.14 KVM_CAP_MSR_PLATFORM_INFO +7.15 KVM_CAP_MSR_PLATFORM_INFO Architectures: x86 Parameters: args[0] whether feature should be enabled or not @@ -4531,6 +4712,69 @@ With this capability, a guest may read the MSR_PLATFORM_INFO MSR. Otherwise, a #GP would be raised when the guest tries to access. Currently, this capability does not enable write permissions of this MSR for the guest. +7.16 KVM_CAP_PPC_NESTED_HV + +Architectures: ppc +Parameters: none +Returns: 0 on success, -EINVAL when the implementation doesn't support + nested-HV virtualization. + +HV-KVM on POWER9 and later systems allows for "nested-HV" +virtualization, which provides a way for a guest VM to run guests that +can run using the CPU's supervisor mode (privileged non-hypervisor +state). Enabling this capability on a VM depends on the CPU having +the necessary functionality and on the facility being enabled with a +kvm-hv module parameter. + +7.17 KVM_CAP_EXCEPTION_PAYLOAD + +Architectures: x86 +Parameters: args[0] whether feature should be enabled or not + +With this capability enabled, CR2 will not be modified prior to the +emulated VM-exit when L1 intercepts a #PF exception that occurs in +L2. Similarly, for kvm-intel only, DR6 will not be modified prior to +the emulated VM-exit when L1 intercepts a #DB exception that occurs in +L2. As a result, when KVM_GET_VCPU_EVENTS reports a pending #PF (or +#DB) exception for L2, exception.has_payload will be set and the +faulting address (or the new DR6 bits*) will be reported in the +exception_payload field. Similarly, when userspace injects a #PF (or +#DB) into L2 using KVM_SET_VCPU_EVENTS, it is expected to set +exception.has_payload and to put the faulting address (or the new DR6 +bits*) in the exception_payload field. + +This capability also enables exception.pending in struct +kvm_vcpu_events, which allows userspace to distinguish between pending +and injected exceptions. + + +* For the new DR6 bits, note that bit 16 is set iff the #DB exception + will clear DR6.RTM. + +7.18 KVM_CAP_MANUAL_DIRTY_LOG_PROTECT + +Architectures: all +Parameters: args[0] whether feature should be enabled or not + +With this capability enabled, KVM_GET_DIRTY_LOG will not automatically +clear and write-protect all pages that are returned as dirty. +Rather, userspace will have to do this operation separately using +KVM_CLEAR_DIRTY_LOG. + +At the cost of a slightly more complicated operation, this provides better +scalability and responsiveness for two reasons. First, +KVM_CLEAR_DIRTY_LOG ioctl can operate on a 64-page granularity rather +than requiring to sync a full memslot; this ensures that KVM does not +take spinlocks for an extended period of time. Second, in some cases a +large amount of time can pass between a call to KVM_GET_DIRTY_LOG and +userspace actually using the data in the page. Pages can be modified +during this time, which is inefficint for both the guest and userspace: +the guest will incur a higher penalty due to write protection faults, +while userspace can see false reports of dirty pages. Manual reprotection +helps reducing this time, improving guest performance and reducing the +number of dirty log false positives. + + 8. Other capabilities. ---------------------- @@ -4772,3 +5016,10 @@ CPU when the exception is taken. If this virtual SError is taken to EL1 using AArch64, this value will be reported in the ISS field of ESR_ELx. See KVM_CAP_VCPU_EVENTS for more details. +8.20 KVM_CAP_HYPERV_SEND_IPI + +Architectures: x86 + +This capability indicates that KVM supports paravirtualized Hyper-V IPI send +hypercalls: +HvCallSendSyntheticClusterIpi, HvCallSendSyntheticClusterIpiEx. diff --git a/Documentation/vm/index.rst b/Documentation/vm/index.rst index c4ded22197ca..2b3ab3a1ccf3 100644 --- a/Documentation/vm/index.rst +++ b/Documentation/vm/index.rst @@ -2,7 +2,9 @@ Linux Memory Management Documentation ===================================== -This is a collection of documents about Linux memory management (mm) subsystem. +This is a collection of documents about the Linux memory management (mm) +subsystem. If you are looking for advice on simply allocating memory, +see the :ref:`memory-allocation`. User guides for MM features =========================== diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst index 3a775fd64e2d..195928808bac 100644 --- a/Documentation/vm/slub.rst +++ b/Documentation/vm/slub.rst @@ -36,9 +36,10 @@ debugging is enabled. Format: slub_debug=<Debug-Options> Enable options for all slabs -slub_debug=<Debug-Options>,<slab name> - Enable options only for select slabs +slub_debug=<Debug-Options>,<slab name1>,<slab name2>,... + Enable options only for select slabs (no spaces + after a comma) Possible debug options are:: @@ -62,7 +63,12 @@ Trying to find an issue in the dentry cache? Try:: slub_debug=,dentry -to only enable debugging on the dentry cache. +to only enable debugging on the dentry cache. You may use an asterisk at the +end of the slab name, in order to cover all slabs with the same prefix. For +example, here's how you can poison the dentry cache as well as all kmalloc +slabs: + + slub_debug=P,kmalloc-*,dentry Red zoning and tracking may realign the slab. We can just apply sanity checks to the dentry cache with:: diff --git a/Documentation/vm/unevictable-lru.rst b/Documentation/vm/unevictable-lru.rst index fdd84cb8d511..b8e29f977f2d 100644 --- a/Documentation/vm/unevictable-lru.rst +++ b/Documentation/vm/unevictable-lru.rst @@ -143,7 +143,7 @@ using a number of wrapper functions: Query the address space, and return true if it is completely unevictable. -These are currently used in two places in the kernel: +These are currently used in three places in the kernel: (1) By ramfs to mark the address spaces of its inodes when they are created, and this mark remains for the life of the inode. @@ -154,6 +154,10 @@ These are currently used in two places in the kernel: swapped out; the application must touch the pages manually if it wants to ensure they're in memory. + (3) By the i915 driver to mark pinned address space until it's unpinned. The + amount of unevictable memory marked by i915 driver is roughly the bounded + object size in debugfs/dri/0/i915_gem_objects. + Detecting Unevictable Pages --------------------------- diff --git a/Documentation/watchdog/hpwdt.txt b/Documentation/watchdog/hpwdt.txt index 6d866c537127..55df692c5595 100644 --- a/Documentation/watchdog/hpwdt.txt +++ b/Documentation/watchdog/hpwdt.txt @@ -1,15 +1,12 @@ -Last reviewed: 05/20/2016 +Last reviewed: 08/20/2018 HPE iLO NMI Watchdog Driver - NMI sourcing for iLO based ProLiant Servers - Documentation and Driver by - Thomas Mingarelli + for iLO based ProLiant Servers The HPE iLO NMI Watchdog driver is a kernel module that provides basic - watchdog functionality and the added benefit of NMI sourcing. Both the - watchdog functionality and the NMI sourcing capability need to be enabled - by the user. Remember that the two modes are not dependent on one another. - A user can have the NMI sourcing without the watchdog timer and vice-versa. + watchdog functionality and handler for the iLO "Generate NMI to System" + virtual button. + All references to iLO in this document imply it also works on iLO2 and all subsequent generations. @@ -21,12 +18,16 @@ Last reviewed: 05/20/2016 not be updated in a timely fashion and a hardware system reset (also known as an Automatic Server Recovery (ASR)) event will occur. - The hpwdt driver also has three (3) module parameters. They are the following: + The hpwdt driver also has the following module parameters: soft_margin - allows the user to set the watchdog timer value. Default value is 30 seconds. - allow_kdump - allows the user to save off a kernel dump image after an NMI. - Default value is 1/ON + timeout - an alias of soft_margin. + pretimeout - allows the user to set the watchdog pretimeout value. + This is the number of seconds before timeout when an + NMI is delivered to the system. Setting the value to + zero disables the pretimeout NMI. + Default value is 9 seconds. nowayout - basic watchdog parameter that does not allow the timer to be restarted or an impending ASR to be escaped. Default value is set when compiling the kernel. If it is set @@ -37,61 +38,29 @@ Last reviewed: 05/20/2016 interface to /dev/watchdog can be found in Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt. - The NMI sourcing capability is disabled by default due to the inability to - distinguish between "NMI Watchdog Ticks" and "HW generated NMI events" in the - Linux kernel. What this means is that the hpwdt nmi handler code is called - each time the NMI signal fires off. This could amount to several thousands of - NMIs in a matter of seconds. If a user sees the Linux kernel's "dazed and - confused" message in the logs or if the system gets into a hung state, then - the hpwdt driver can be reloaded. - - 1. If the kernel has not been booted with nmi_watchdog turned off then - edit and place the nmi_watchdog=0 at the end of the currently booting - kernel line. Depending on your Linux distribution and platform setup: - For non-UEFI systems - /boot/grub/grub.conf or - /boot/grub/menu.lst - For UEFI systems - /boot/efi/EFI/distroname/grub.conf or - /boot/efi/efi/distroname/elilo.conf - 2. reboot the sever - 3. Once the system comes up perform a modprobe -r hpwdt - 4. modprobe /lib/modules/`uname -r`/kernel/drivers/watchdog/hpwdt.ko - - Now, the hpwdt can successfully receive and source the NMI and provide a log - message that details the reason for the NMI (as determined by the HPE BIOS). - - Below is a list of NMIs the HPE BIOS understands along with the associated - code (reason): - - No source found 00h - - Uncorrectable Memory Error 01h - - ASR NMI 1Bh - - PCI Parity Error 20h - - NMI Button Press 27h - - SB_BUS_NMI 28h - - ILO Doorbell NMI 29h - - ILO IOP NMI 2Ah - - ILO Watchdog NMI 2Bh - - Proc Throt NMI 2Ch + Due to limitations in the iLO hardware, the NMI pretimeout if enabled, + can only be set to 9 seconds. Attempts to set pretimeout to other + non-zero values will be rounded, possibly to zero. Users should verify + the pretimeout value after attempting to set pretimeout or timeout. - Front Side Bus NMI 2Dh + Upon receipt of an NMI from the iLO, the hpwdt driver will initiate a + panic. This is to allow for a crash dump to be collected. It is incumbent + upon the user to have properly configured the system for kdump. - PCI Express Error 2Fh + The default Linux kernel behavior upon panic is to print a kernel tombstone + and loop forever. This is generally not what a watchdog user wants. - DMA controller NMI 30h + For those wishing to learn more please see: + Documentation/kdump/kdump.txt + Documentation/admin-guide/kernel-parameters.txt (panic=) + Your Linux Distribution specific documentation. - Hypertransport/CSI Error 31h + If the hpwdt does not receive the NMI associated with an expiring timer, + the iLO will proceed to reset the system at timeout if the timer hasn't + been updated. +-- + The HPE iLO NMI Watchdog Driver and documentation were originally developed + by Tom Mingarelli. - -- Tom Mingarelli diff --git a/Documentation/watchdog/watchdog-kernel-api.txt b/Documentation/watchdog/watchdog-kernel-api.txt index 9b93953f69cf..3a91ef5af044 100644 --- a/Documentation/watchdog/watchdog-kernel-api.txt +++ b/Documentation/watchdog/watchdog-kernel-api.txt @@ -128,8 +128,6 @@ struct watchdog_ops { int (*set_pretimeout)(struct watchdog_device *, unsigned int); unsigned int (*get_timeleft)(struct watchdog_device *); int (*restart)(struct watchdog_device *); - void (*ref)(struct watchdog_device *) __deprecated; - void (*unref)(struct watchdog_device *) __deprecated; long (*ioctl)(struct watchdog_device *, unsigned int, unsigned long); }; @@ -218,8 +216,6 @@ they are supported. These optional routines/operations are: if a command is not supported. The parameters that are passed to the ioctl call are: watchdog_device, cmd and arg. -The 'ref' and 'unref' operations are no longer used and deprecated. - The status bits should (preferably) be set with the set_bit and clear_bit alike bit-operations. The status bits that are defined are: * WDOG_ACTIVE: this status bit indicates whether or not a watchdog timer device diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index 6d6200ea27b8..0b88e333f9e1 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -40,6 +40,11 @@ margin: Watchdog margin in seconds (default=60) nowayout: Disable watchdog shutdown on close (default=kernel config parameter) ------------------------------------------------- +armada_37xx_wdt: +timeout: Watchdog timeout in seconds. (default=120) +nowayout: Disable watchdog shutdown on close + (default=kernel config parameter) +------------------------------------------------- at91rm9200_wdt: wdt_time: Watchdog time in seconds. (default=5) nowayout: Watchdog cannot be stopped once started diff --git a/Documentation/watchdog/watchdog-pm.txt b/Documentation/watchdog/watchdog-pm.txt new file mode 100644 index 000000000000..7a4dd46e0d24 --- /dev/null +++ b/Documentation/watchdog/watchdog-pm.txt @@ -0,0 +1,19 @@ +The Linux WatchDog Timer Power Management Guide +=============================================== +Last reviewed: 17-Dec-2018 + +Wolfram Sang <wsa+renesas@sang-engineering.com> + +Introduction +------------ +This document states rules about watchdog devices and their power management +handling to ensure a uniform behaviour for Linux systems. + + +Ping on resume +-------------- +On resume, a watchdog timer shall be reset to its selected value to give +userspace enough time to resume. [1] [2] + +[1] https://patchwork.kernel.org/patch/10252209/ +[2] https://patchwork.kernel.org/patch/10711625/ diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 7727db8f94bc..f4c2a97bfdbd 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -58,21 +58,9 @@ Protocol 2.11: (Kernel 3.6) Added a field for offset of EFI handover protocol entry point. Protocol 2.12: (Kernel 3.8) Added the xloadflags field and extension fields - to struct boot_params for loading bzImage and ramdisk + to struct boot_params for loading bzImage and ramdisk above 4G in 64bit. -Protocol 2.13: (Kernel 3.14) Support 32- and 64-bit flags being set in - xloadflags to support booting a 64-bit kernel from 32-bit - EFI - -Protocol 2.14: (Kernel 4.20) Added acpi_rsdp_addr holding the physical - address of the ACPI RSDP table. - The bootloader updates version with: - 0x8000 | min(kernel-version, bootloader-version) - kernel-version being the protocol version supported by - the kernel and bootloader-version the protocol version - supported by the bootloader. - **** MEMORY LAYOUT The traditional memory map for the kernel loader, used for Image or @@ -209,7 +197,6 @@ Offset Proto Name Meaning 0258/8 2.10+ pref_address Preferred loading address 0260/4 2.10+ init_size Linear memory required during initialization 0264/4 2.11+ handover_offset Offset of handover entry point -0268/8 2.14+ acpi_rsdp_addr Physical address of RSDP table (1) For backwards compatibility, if the setup_sects field contains 0, the real value is 4. @@ -322,7 +309,7 @@ Protocol: 2.00+ Contains the magic number "HdrS" (0x53726448). Field name: version -Type: modify +Type: read Offset/size: 0x206/2 Protocol: 2.00+ @@ -330,12 +317,6 @@ Protocol: 2.00+ e.g. 0x0204 for version 2.04, and 0x0a11 for a hypothetical version 10.17. - Up to protocol version 2.13 this information is only read by the - bootloader. From protocol version 2.14 onwards the bootloader will - write the used protocol version or-ed with 0x8000 to the field. The - used protocol version will be the minimum of the supported protocol - versions of the bootloader and the kernel. - Field name: realmode_swtch Type: modify (optional) Offset/size: 0x208/4 @@ -763,17 +744,6 @@ Offset/size: 0x264/4 See EFI HANDOVER PROTOCOL below for more details. -Field name: acpi_rsdp_addr -Type: write -Offset/size: 0x268/8 -Protocol: 2.14+ - - This field can be set by the boot loader to tell the kernel the - physical address of the ACPI RSDP table. - - A value of 0 indicates the kernel should fall back to the standard - methods to locate the RSDP. - **** THE IMAGE CHECKSUM diff --git a/Documentation/x86/pat.txt b/Documentation/x86/pat.txt index 2a4ee6302122..481d8d8536ac 100644 --- a/Documentation/x86/pat.txt +++ b/Documentation/x86/pat.txt @@ -90,12 +90,12 @@ pci proc | -- | -- | WC | Advanced APIs for drivers ------------------------- A. Exporting pages to users with remap_pfn_range, io_remap_pfn_range, -vm_insert_pfn +vmf_insert_pfn Drivers wanting to export some pages to userspace do it by using mmap interface and a combination of 1) pgprot_noncached() -2) io_remap_pfn_range() or remap_pfn_range() or vm_insert_pfn() +2) io_remap_pfn_range() or remap_pfn_range() or vmf_insert_pfn() With PAT support, a new API pgprot_writecombine is being added. So, drivers can continue to use the above sequence, with either pgprot_noncached() or diff --git a/Documentation/x86/intel_rdt_ui.txt b/Documentation/x86/resctrl_ui.txt index 52b10945ff75..c1f95b59e14d 100644 --- a/Documentation/x86/intel_rdt_ui.txt +++ b/Documentation/x86/resctrl_ui.txt @@ -1,4 +1,7 @@ -User Interface for Resource Allocation in Intel Resource Director Technology +User Interface for Resource Control feature + +Intel refers to this feature as Intel Resource Director Technology(Intel(R) RDT). +AMD refers to this feature as AMD Platform Quality of Service(AMD QoS). Copyright (C) 2016 Intel Corporation @@ -6,8 +9,8 @@ Fenghua Yu <fenghua.yu@intel.com> Tony Luck <tony.luck@intel.com> Vikas Shivappa <vikas.shivappa@intel.com> -This feature is enabled by the CONFIG_INTEL_RDT Kconfig and the -X86 /proc/cpuinfo flag bits: +This feature is enabled by the CONFIG_X86_CPU_RESCTRL and the x86 /proc/cpuinfo +flag bits: RDT (Resource Director Technology) Allocation - "rdt_a" CAT (Cache Allocation Technology) - "cat_l3", "cat_l2" CDP (Code and Data Prioritization ) - "cdp_l3", "cdp_l2" diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index ad6d2a80cf05..abc53886655e 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -209,7 +209,7 @@ IOMMU (input/output memory management unit) mapping with memory protection, etc. Kernel boot message: "PCI-DMA: Using Calgary IOMMU" - iommu=[<size>][,noagp][,off][,force][,noforce][,leak[=<nr_of_leak_pages>] + iommu=[<size>][,noagp][,off][,force][,noforce] [,memaper[=<order>]][,merge][,fullflush][,nomerge] [,noaperture][,calgary] @@ -228,9 +228,6 @@ IOMMU (input/output memory management unit) allowed Overwrite iommu off workarounds for specific chipsets. fullflush Flush IOMMU on each allocation (default). nofullflush Don't use IOMMU fullflush. - leak Turn on simple iommu leak tracing (only when - CONFIG_IOMMU_LEAK is on). Default number of leak pages - is 20. memaper[=<order>] Allocate an own aperture over RAM with size 32MB<<order. (default: order=1, i.e. 64MB) merge Do scatter-gather (SG) merging. Implies "force" diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 702898633b00..804f9426ed17 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -34,23 +34,24 @@ __________________|____________|__________________|_________|___________________ ____________________________________________________________|___________________________________________________________ | | | | ffff800000000000 | -128 TB | ffff87ffffffffff | 8 TB | ... guard hole, also reserved for hypervisor - ffff880000000000 | -120 TB | ffffc7ffffffffff | 64 TB | direct mapping of all physical memory (page_offset_base) - ffffc80000000000 | -56 TB | ffffc8ffffffffff | 1 TB | ... unused hole + ffff880000000000 | -120 TB | ffff887fffffffff | 0.5 TB | LDT remap for PTI + ffff888000000000 | -119.5 TB | ffffc87fffffffff | 64 TB | direct mapping of all physical memory (page_offset_base) + ffffc88000000000 | -55.5 TB | ffffc8ffffffffff | 0.5 TB | ... unused hole ffffc90000000000 | -55 TB | ffffe8ffffffffff | 32 TB | vmalloc/ioremap space (vmalloc_base) ffffe90000000000 | -23 TB | ffffe9ffffffffff | 1 TB | ... unused hole ffffea0000000000 | -22 TB | ffffeaffffffffff | 1 TB | virtual memory map (vmemmap_base) ffffeb0000000000 | -21 TB | ffffebffffffffff | 1 TB | ... unused hole ffffec0000000000 | -20 TB | fffffbffffffffff | 16 TB | KASAN shadow memory - fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole - | | | | vaddr_end for KASLR - fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping - fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | LDT remap for PTI - ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks __________________|____________|__________________|_________|____________________________________________________________ | - | Identical layout to the 47-bit one from here on: + | Identical layout to the 56-bit one from here on: ____________________________________________________________|____________________________________________________________ | | | | + fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole + | | | | vaddr_end for KASLR + fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping + fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole + ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole @@ -83,7 +84,7 @@ Notes: __________________|____________|__________________|_________|___________________________________________________________ | | | | 0000800000000000 | +64 PB | ffff7fffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical - | | | | virtual memory addresses up to the -128 TB + | | | | virtual memory addresses up to the -64 PB | | | | starting offset of kernel mappings. __________________|____________|__________________|_________|___________________________________________________________ | @@ -91,23 +92,24 @@ __________________|____________|__________________|_________|___________________ ____________________________________________________________|___________________________________________________________ | | | | ff00000000000000 | -64 PB | ff0fffffffffffff | 4 PB | ... guard hole, also reserved for hypervisor - ff10000000000000 | -60 PB | ff8fffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base) - ff90000000000000 | -28 PB | ff9fffffffffffff | 4 PB | LDT remap for PTI + ff10000000000000 | -60 PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI + ff11000000000000 | -59.75 PB | ff90ffffffffffff | 32 PB | direct mapping of all physical memory (page_offset_base) + ff91000000000000 | -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole ffa0000000000000 | -24 PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base) ffd2000000000000 | -11.5 PB | ffd3ffffffffffff | 0.5 PB | ... unused hole ffd4000000000000 | -11 PB | ffd5ffffffffffff | 0.5 PB | virtual memory map (vmemmap_base) ffd6000000000000 | -10.5 PB | ffdeffffffffffff | 2.25 PB | ... unused hole ffdf000000000000 | -8.25 PB | fffffdffffffffff | ~8 PB | KASAN shadow memory - fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole - | | | | vaddr_end for KASLR - fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping - fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole - ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks __________________|____________|__________________|_________|____________________________________________________________ | | Identical layout to the 47-bit one from here on: ____________________________________________________________|____________________________________________________________ | | | | + fffffc0000000000 | -4 TB | fffffdffffffffff | 2 TB | ... unused hole + | | | | vaddr_end for KASLR + fffffe0000000000 | -2 TB | fffffe7fffffffff | 0.5 TB | cpu_entry_area mapping + fffffe8000000000 | -1.5 TB | fffffeffffffffff | 0.5 TB | ... unused hole + ffffff0000000000 | -1 TB | ffffff7fffffffff | 0.5 TB | %esp fixup stacks ffffff8000000000 | -512 GB | ffffffeeffffffff | 444 GB | ... unused hole ffffffef00000000 | -68 GB | fffffffeffffffff | 64 GB | EFI region mapping space ffffffff00000000 | -4 GB | ffffffff7fffffff | 2 GB | ... unused hole @@ -146,3 +148,6 @@ Their order is preserved but their base will be offset early at boot time. Be very careful vs. KASLR when changing anything here. The KASLR address range must not overlap with anything except the KASAN shadow area, which is correct as KASAN disables KASLR. + +For both 4- and 5-level layouts, the STACKLEAK_POISON value in the last 2MB +hole: ffffffffffff4111 diff --git a/Documentation/x86/zero-page.txt b/Documentation/x86/zero-page.txt index 97b7adbceda4..68aed077f7b6 100644 --- a/Documentation/x86/zero-page.txt +++ b/Documentation/x86/zero-page.txt @@ -25,7 +25,7 @@ Offset Proto Name Meaning 0C8/004 ALL ext_cmd_line_ptr cmd_line_ptr high 32bits 140/080 ALL edid_info Video mode setup (struct edid_info) 1C0/020 ALL efi_info EFI 32 information (struct efi_info) -1E0/004 ALL alk_mem_k Alternative mem check, in KB +1E0/004 ALL alt_mem_k Alternative mem check, in KB 1E4/004 ALL scratch Scratch field for the kernel setup code 1E8/001 ALL e820_entries Number of entries in e820_table (below) 1E9/001 ALL eddbuf_entries Number of entries in eddbuf (below) diff --git a/Documentation/xilinx/eemi.txt b/Documentation/xilinx/eemi.txt new file mode 100644 index 000000000000..0ab686c173be --- /dev/null +++ b/Documentation/xilinx/eemi.txt @@ -0,0 +1,67 @@ +--------------------------------------------------------------------- +Xilinx Zynq MPSoC EEMI Documentation +--------------------------------------------------------------------- + +Xilinx Zynq MPSoC Firmware Interface +------------------------------------- +The zynqmp-firmware node describes the interface to platform firmware. +ZynqMP has an interface to communicate with secure firmware. Firmware +driver provides an interface to firmware APIs. Interface APIs can be +used by any driver to communicate with PMC(Platform Management Controller). + +Embedded Energy Management Interface (EEMI) +---------------------------------------------- +The embedded energy management interface is used to allow software +components running across different processing clusters on a chip or +device to communicate with a power management controller (PMC) on a +device to issue or respond to power management requests. + +EEMI ops is a structure containing all eemi APIs supported by Zynq MPSoC. +The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops +structure. Any driver who want to communicate with PMC using EEMI APIs +can call zynqmp_pm_get_eemi_ops(). + +Example of EEMI ops: + + /* zynqmp-firmware driver maintain all EEMI APIs */ + struct zynqmp_eemi_ops { + int (*get_api_version)(u32 *version); + int (*query_data)(struct zynqmp_pm_query_data qdata, u32 *out); + }; + + static const struct zynqmp_eemi_ops eemi_ops = { + .get_api_version = zynqmp_pm_get_api_version, + .query_data = zynqmp_pm_query_data, + }; + +Example of EEMI ops usage: + + static const struct zynqmp_eemi_ops *eemi_ops; + u32 ret_payload[PAYLOAD_ARG_CNT]; + int ret; + + eemi_ops = zynqmp_pm_get_eemi_ops(); + if (!eemi_ops) + return -ENXIO; + + ret = eemi_ops->query_data(qdata, ret_payload); + +IOCTL +------ +IOCTL API is for device control and configuration. It is not a system +IOCTL but it is an EEMI API. This API can be used by master to control +any device specific configuration. IOCTL definitions can be platform +specific. This API also manage shared device configuration. + +The following IOCTL IDs are valid for device control: +- IOCTL_SET_PLL_FRAC_MODE 8 +- IOCTL_GET_PLL_FRAC_MODE 9 +- IOCTL_SET_PLL_FRAC_DATA 10 +- IOCTL_GET_PLL_FRAC_DATA 11 + +Refer EEMI API guide [0] for IOCTL specific parameters and other EEMI APIs. + +References +---------- +[0] Embedded Energy Management Interface (EEMI) API guide: + https://www.xilinx.com/support/documentation/user_guides/ug1200-eemi-api.pdf diff --git a/Documentation/xtensa/booting.txt b/Documentation/xtensa/booting.txt new file mode 100644 index 000000000000..402b33a2619f --- /dev/null +++ b/Documentation/xtensa/booting.txt @@ -0,0 +1,19 @@ +Passing boot parameters to the kernel. + +Boot parameters are represented as a TLV list in the memory. Please see +arch/xtensa/include/asm/bootparam.h for definition of the bp_tag structure and +tag value constants. First entry in the list must have type BP_TAG_FIRST, last +entry must have type BP_TAG_LAST. The address of the first list entry is +passed to the kernel in the register a2. The address type depends on MMU type: +- For configurations without MMU, with region protection or with MPU the + address must be the physical address. +- For configurations with region translarion MMU or with MMUv3 and CONFIG_MMU=n + the address must be a valid address in the current mapping. The kernel will + not change the mapping on its own. +- For configurations with MMUv2 the address must be a virtual address in the + default virtual mapping (0xd0000000..0xffffffff). +- For configurations with MMUv3 and CONFIG_MMU=y the address may be either a + virtual or physical address. In either case it must be within the default + virtual mapping. It is considered physical if it is within the range of + physical addresses covered by the default KSEG mapping (XCHAL_KSEG_PADDR.. + XCHAL_KSEG_PADDR + XCHAL_KSEG_SIZE), otherwise it is considered virtual. |
