diff --git a/.gitignore b/.gitignore index 689a4fa3f5477a..c59dc60ba62ef0 100644 --- a/.gitignore +++ b/.gitignore @@ -52,6 +52,7 @@ *.xz *.zst Module.symvers +dtbs-list modules.order # diff --git a/.mailmap b/.mailmap index 04998f7bda8181..6ac0d469c7fa5b 100644 --- a/.mailmap +++ b/.mailmap @@ -191,10 +191,11 @@ Gao Xiang Gao Xiang Gao Xiang Gao Xiang -Geliang Tang -Geliang Tang -Geliang Tang -Geliang Tang +Geliang Tang +Geliang Tang +Geliang Tang +Geliang Tang +Geliang Tang Georgi Djakov Gerald Schaefer Gerald Schaefer @@ -289,6 +290,7 @@ Johan Hovold John Crispin John Fastabend John Keeping +John Moon John Paul Adrian Glaubitz John Stultz @@ -344,6 +346,7 @@ Leonid I Ananiev Leon Romanovsky Leon Romanovsky Leon Romanovsky +Leo Yan Liam Mark Linas Vepstas Linus Lüssing @@ -550,6 +553,7 @@ Senthilkumar N L Serge Hallyn Serge Hallyn Seth Forshee +Shakeel Butt Shannon Nelson Shannon Nelson Shannon Nelson @@ -568,6 +572,7 @@ Simon Kelley Sricharan Ramabadhran Srinivas Ramana Sriram R +Stefan Wahren Stéphane Witzmann Stephen Hemminger Stephen Hemminger diff --git a/CREDITS b/CREDITS index 5797e8f7e92b06..3c2bb55847c607 100644 --- a/CREDITS +++ b/CREDITS @@ -63,6 +63,11 @@ D: dosfs, LILO, some fd features, ATM, various other hacks here and there S: Buenos Aires S: Argentina +NTFS FILESYSTEM +N: Anton Altaparmakov +E: anton@tuxera.com +D: NTFS filesystem + N: Tim Alpaerts E: tim_alpaerts@toyota-motor-europe.com D: 802.2 class II logical link control layer, @@ -2161,6 +2166,19 @@ N: Mike Kravetz E: mike.kravetz@oracle.com D: Maintenance and development of the hugetlb subsystem +N: Seth Jennings +E: sjenning@redhat.com +D: Creation and maintenance of zswap + +N: Dan Streetman +E: ddstreet@ieee.org +D: Maintenance and development of zswap +D: Creation and maintenance of the zpool API + +N: Vitaly Wool +E: vitaly.wool@konsulko.com +D: Maintenance and development of zswap + N: Andreas S. Krebs E: akrebs@altavista.net D: CYPRESS CY82C693 chipset IDE, Digital's PC-Alpha 164SX boards diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio index b8b0fd341c1797..da1345d854b4ad 100644 --- a/Documentation/ABI/obsolete/sysfs-gpio +++ b/Documentation/ABI/obsolete/sysfs-gpio @@ -28,5 +28,5 @@ Description: /label ... (r/o) descriptive, not necessarily unique /ngpio ... (r/o) number of GPIOs; numbered N to N + (ngpio - 1) - This ABI is deprecated and will be removed after 2020. It is - replaced with the GPIO character device. + This ABI is obsoleted by Documentation/ABI/testing/gpio-cdev and will be + removed after 2020. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ffs b/Documentation/ABI/testing/configfs-usb-gadget-ffs index e39b27653c65c1..bf8936ff6d38c3 100644 --- a/Documentation/ABI/testing/configfs-usb-gadget-ffs +++ b/Documentation/ABI/testing/configfs-usb-gadget-ffs @@ -4,6 +4,14 @@ KernelVersion: 3.13 Description: The purpose of this directory is to create and remove it. A corresponding USB function instance is created/removed. - There are no attributes here. - All parameters are set through FunctionFS. + All attributes are read only: + + ============= ============================================ + ready 1 if the function is ready to be used, E.G. + if userspace has written descriptors and + strings to ep0, so the gadget can be + enabled - 0 otherwise. + ============= ============================================ + + All other parameters are set through FunctionFS. diff --git a/Documentation/ABI/testing/debugfs-driver-qat b/Documentation/ABI/testing/debugfs-driver-qat index b2db010d851eeb..bd6793760f2984 100644 --- a/Documentation/ABI/testing/debugfs-driver-qat +++ b/Documentation/ABI/testing/debugfs-driver-qat @@ -81,3 +81,29 @@ Description: (RO) Read returns, for each Acceleration Engine (AE), the number : Number of Compress and Verify (CnV) errors and type of the last CnV error detected by Acceleration Engine N. + +What: /sys/kernel/debug/qat__/heartbeat/inject_error +Date: March 2024 +KernelVersion: 6.8 +Contact: qat-linux@intel.com +Description: (WO) Write to inject an error that simulates an heartbeat + failure. This is to be used for testing purposes. + + After writing this file, the driver stops arbitration on a + random engine and disables the fetching of heartbeat counters. + If a workload is running on the device, a job submitted to the + accelerator might not get a response and a read of the + `heartbeat/status` attribute might report -1, i.e. device + unresponsive. + The error is unrecoverable thus the device must be restarted to + restore its functionality. + + This attribute is available only when the kernel is built with + CONFIG_CRYPTO_DEV_QAT_ERROR_INJECTION=y. + + A write of 1 enables error injection. + + The following example shows how to enable error injection:: + + # cd /sys/kernel/debug/qat__ + # echo 1 > heartbeat/inject_error diff --git a/Documentation/ABI/testing/debugfs-hisi-hpre b/Documentation/ABI/testing/debugfs-hisi-hpre index 8e8de49c5cc669..d4e16ef9ac9a99 100644 --- a/Documentation/ABI/testing/debugfs-hisi-hpre +++ b/Documentation/ABI/testing/debugfs-hisi-hpre @@ -111,6 +111,28 @@ Description: QM debug registers(regs) read hardware register value. This node is used to show the change of the qm register values. This node can be help users to check the change of register values. +What: /sys/kernel/debug/hisi_hpre//qm/qm_state +Date: Jan 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the state of the device. + 0: busy, 1: idle. + Only available for PF, and take no other effect on HPRE. + +What: /sys/kernel/debug/hisi_hpre//qm/dev_timeout +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Set the wait time when stop queue fails. Available for both PF + and VF, and take no other effect on HPRE. + 0: not wait(default), others value: wait dev_timeout * 20 microsecond. + +What: /sys/kernel/debug/hisi_hpre//qm/dev_state +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the stop queue status of the QM. The default value is 0, + if dev_timeout is set, when stop queue fails, the dev_state + will return non-zero value. Available for both PF and VF, + and take no other effect on HPRE. + What: /sys/kernel/debug/hisi_hpre//hpre_dfx/diff_regs Date: Mar 2022 Contact: linux-crypto@vger.kernel.org diff --git a/Documentation/ABI/testing/debugfs-hisi-sec b/Documentation/ABI/testing/debugfs-hisi-sec index deeefe2c735ed7..6c6c9a6e150acb 100644 --- a/Documentation/ABI/testing/debugfs-hisi-sec +++ b/Documentation/ABI/testing/debugfs-hisi-sec @@ -91,6 +91,28 @@ Description: QM debug registers(regs) read hardware register value. This node is used to show the change of the qm register values. This node can be help users to check the change of register values. +What: /sys/kernel/debug/hisi_sec2//qm/qm_state +Date: Jan 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the state of the device. + 0: busy, 1: idle. + Only available for PF, and take no other effect on SEC. + +What: /sys/kernel/debug/hisi_sec2//qm/dev_timeout +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Set the wait time when stop queue fails. Available for both PF + and VF, and take no other effect on SEC. + 0: not wait(default), others value: wait dev_timeout * 20 microsecond. + +What: /sys/kernel/debug/hisi_sec2//qm/dev_state +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the stop queue status of the QM. The default value is 0, + if dev_timeout is set, when stop queue fails, the dev_state + will return non-zero value. Available for both PF and VF, + and take no other effect on SEC. + What: /sys/kernel/debug/hisi_sec2//sec_dfx/diff_regs Date: Mar 2022 Contact: linux-crypto@vger.kernel.org diff --git a/Documentation/ABI/testing/debugfs-hisi-zip b/Documentation/ABI/testing/debugfs-hisi-zip index 593714afaed249..a22dd694221935 100644 --- a/Documentation/ABI/testing/debugfs-hisi-zip +++ b/Documentation/ABI/testing/debugfs-hisi-zip @@ -104,6 +104,28 @@ Description: QM debug registers(regs) read hardware register value. This node is used to show the change of the qm registers value. This node can be help users to check the change of register values. +What: /sys/kernel/debug/hisi_zip//qm/qm_state +Date: Jan 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the state of the device. + 0: busy, 1: idle. + Only available for PF, and take no other effect on ZIP. + +What: /sys/kernel/debug/hisi_zip//qm/dev_timeout +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Set the wait time when stop queue fails. Available for both PF + and VF, and take no other effect on ZIP. + 0: not wait(default), others value: wait dev_timeout * 20 microsecond. + +What: /sys/kernel/debug/hisi_zip//qm/dev_state +Date: Feb 2024 +Contact: linux-crypto@vger.kernel.org +Description: Dump the stop queue status of the QM. The default value is 0, + if dev_timeout is set, when stop queue fails, the dev_state + will return non-zero value. Available for both PF and VF, + and take no other effect on ZIP. + What: /sys/kernel/debug/hisi_zip//zip_dfx/diff_regs Date: Mar 2022 Contact: linux-crypto@vger.kernel.org diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev index 66bdcd188b6c98..c9689b2a6fed21 100644 --- a/Documentation/ABI/testing/gpio-cdev +++ b/Documentation/ABI/testing/gpio-cdev @@ -6,8 +6,9 @@ Description: The character device files /dev/gpiochip* are the interface between GPIO chips and userspace. - The ioctl(2)-based ABI is defined and documented in - [include/uapi]. + The ioctl(2)-based ABI is defined in + [include/uapi] and documented in + Documentation/userspace-api/gpio/chardev.rst. The following file operations are supported: @@ -17,8 +18,8 @@ Description: ioctl(2) Initiate various actions. - See the inline documentation in [include/uapi] - for descriptions of all ioctls. + See Documentation/userspace-api/gpio/chardev.rst + for a description of all ioctls. close(2) Stops and free up the I/O contexts that was associated diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm index 4dd49b159543b6..b4d0fc8d319df7 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tpdm @@ -170,3 +170,90 @@ Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) /cmb_mode +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: (Write) Set the data collection mode of CMB tpdm. Continuous + change creates CMB data set elements on every CMBCLK edge. + Trace-on-change creates CMB data set elements only when a new + data set element differs in value from the previous element + in a CMB data set. + + Accepts only one of the 2 values - 0 or 1. + 0 : Continuous CMB collection mode. + 1 : Trace-on-change CMB collection mode. + +What: /sys/bus/coresight/devices//cmb_trig_patt/xpr[0:1] +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the value of the trigger pattern for the CMB + subunit TPDM. + +What: /sys/bus/coresight/devices//cmb_trig_patt/xpmr[0:1] +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the mask of the trigger pattern for the CMB + subunit TPDM. + +What: /sys/bus/coresight/devices//dsb_patt/tpr[0:1] +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the value of the pattern for the CMB subunit TPDM. + +What: /sys/bus/coresight/devices//dsb_patt/tpmr[0:1] +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the mask of the pattern for the CMB subunit TPDM. + +What: /sys/bus/coresight/devices//cmb_patt/enable_ts +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (Write) Set the pattern timestamp of CMB tpdm. Read + the pattern timestamp of CMB tpdm. + + Accepts only one of the 2 values - 0 or 1. + 0 : Disable CMB pattern timestamp. + 1 : Enable CMB pattern timestamp. + +What: /sys/bus/coresight/devices//cmb_trig_ts +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the trigger timestamp of the CMB for tpdm. + + Accepts only one of the 2 values - 0 or 1. + 0 : Set the CMB trigger type to false + 1 : Set the CMB trigger type to true + +What: /sys/bus/coresight/devices//cmb_ts_all +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Read or write the status of timestamp upon all interface. + Only value 0 and 1 can be written to this node. Set this node to 1 to requeset + timestamp to all trace packet. + Accepts only one of the 2 values - 0 or 1. + 0 : Disable the timestamp of all trace packets. + 1 : Enable the timestamp of all trace packets. + +What: /sys/bus/coresight/devices//cmb_msr/msr[0:31] +Date: January 2024 +KernelVersion 6.9 +Contact: Jinlong Mao (QUIC) , Tao Zhang (QUIC) +Description: + (RW) Set/Get the MSR(mux select register) for the CMB subunit + TPDM. diff --git a/Documentation/ABI/testing/sysfs-bus-dax b/Documentation/ABI/testing/sysfs-bus-dax new file mode 100644 index 00000000000000..b34266bfae49ae --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-dax @@ -0,0 +1,153 @@ +What: /sys/bus/dax/devices/daxX.Y/align +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RW) Provides a way to specify an alignment for a dax device. + Values allowed are constrained by the physical address ranges + that back the dax device, and also by arch requirements. + +What: /sys/bus/dax/devices/daxX.Y/mapping +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (WO) Provides a way to allocate a mapping range under a dax + device. Specified in the format -. + +What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/start +What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/end +What: /sys/bus/dax/devices/daxX.Y/mapping[0..N]/page_offset +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RO) A dax device may have multiple constituent discontiguous + address ranges. These are represented by the different + 'mappingX' subdirectories. The 'start' attribute indicates the + start physical address for the given range. The 'end' attribute + indicates the end physical address for the given range. The + 'page_offset' attribute indicates the offset of the current + range in the dax device. + +What: /sys/bus/dax/devices/daxX.Y/resource +Date: June, 2019 +KernelVersion: v5.3 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The resource attribute indicates the starting physical + address of a dax device. In case of a device with multiple + constituent ranges, it indicates the starting address of the + first range. + +What: /sys/bus/dax/devices/daxX.Y/size +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RW) The size attribute indicates the total size of a dax + device. For creating subdivided dax devices, or for resizing + an existing device, the new size can be written to this as + part of the reconfiguration process. + +What: /sys/bus/dax/devices/daxX.Y/numa_node +Date: November, 2019 +KernelVersion: v5.5 +Contact: nvdimm@lists.linux.dev +Description: + (RO) If NUMA is enabled and the platform has affinitized the + backing device for this dax device, emit the CPU node + affinity for this device. + +What: /sys/bus/dax/devices/daxX.Y/target_node +Date: February, 2019 +KernelVersion: v5.1 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The target-node attribute is the Linux numa-node that a + device-dax instance may create when it is online. Prior to + being online the device's 'numa_node' property reflects the + closest online cpu node which is the typical expectation of a + device 'numa_node'. Once it is online it becomes its own + distinct numa node. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/available_size +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The available_size attribute tracks available dax region + capacity. This only applies to volatile hmem devices, not pmem + devices, since pmem devices are defined by nvdimm namespace + boundaries. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/size +Date: July, 2017 +KernelVersion: v5.1 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The size attribute indicates the size of a given dax region + in bytes. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/align +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The align attribute indicates alignment of the dax region. + Changes on align may not always be valid, when say certain + mappings were created with 2M and then we switch to 1G. This + validates all ranges against the new value being attempted, post + resizing. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/seed +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The seed device is a concept for dynamic dax regions to be + able to split the region amongst multiple sub-instances. The + seed device, similar to libnvdimm seed devices, is a device + that starts with zero capacity allocated and unbound to a + driver. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/create +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (RW) The create interface to the dax region provides a way to + create a new unconfigured dax device under the given region, which + can then be configured (with a size etc.) and then probed. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/delete +Date: October, 2020 +KernelVersion: v5.10 +Contact: nvdimm@lists.linux.dev +Description: + (WO) The delete interface for a dax region provides for deletion + of any 0-sized and idle dax devices. + +What: $(readlink -f /sys/bus/dax/devices/daxX.Y)/../dax_region/id +Date: July, 2017 +KernelVersion: v5.1 +Contact: nvdimm@lists.linux.dev +Description: + (RO) The id attribute indicates the region id of a dax region. + +What: /sys/bus/dax/devices/daxX.Y/memmap_on_memory +Date: January, 2024 +KernelVersion: v6.8 +Contact: nvdimm@lists.linux.dev +Description: + (RW) Control the memmap_on_memory setting if the dax device + were to be hotplugged as system memory. This determines whether + the 'altmap' for the hotplugged memory will be placed on the + device being hotplugged (memmap_on_memory=1) or if it will be + placed on regular memory (memmap_on_memory=0). This attribute + must be set before the device is handed over to the 'kmem' + driver (i.e. hotplugged into system-ram). Additionally, this + depends on CONFIG_MHP_MEMMAP_ON_MEMORY, and a globally enabled + memmap_on_memory parameter for memory_hotplug. This is + typically set on the kernel command line - + memory_hotplug.memmap_on_memory set to 'true' or 'force'." diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats index 860db53037a58f..d1f67bb81d5d14 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats @@ -11,7 +11,7 @@ saw any problems). What: /sys/bus/pci/devices//aer_dev_correctable Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: List of correctable errors seen and reported by this PCI device using ERR_COR. Note that since multiple errors may @@ -32,7 +32,7 @@ Description: List of correctable errors seen and reported by this What: /sys/bus/pci/devices//aer_dev_fatal Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: List of uncorrectable fatal errors seen and reported by this PCI device using ERR_FATAL. Note that since multiple errors may @@ -62,7 +62,7 @@ Description: List of uncorrectable fatal errors seen and reported by this What: /sys/bus/pci/devices//aer_dev_nonfatal Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: List of uncorrectable nonfatal errors seen and reported by this PCI device using ERR_NONFATAL. Note that since multiple errors @@ -100,20 +100,20 @@ collectors) that are AER capable. These indicate the number of error messages as device, so these counters include them and are thus cumulative of all the error messages on the PCI hierarchy originating at that root port. -What: /sys/bus/pci/devices//aer_stats/aer_rootport_total_err_cor +What: /sys/bus/pci/devices//aer_rootport_total_err_cor Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: Total number of ERR_COR messages reported to rootport. -What: /sys/bus/pci/devices//aer_stats/aer_rootport_total_err_fatal +What: /sys/bus/pci/devices//aer_rootport_total_err_fatal Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: Total number of ERR_FATAL messages reported to rootport. -What: /sys/bus/pci/devices//aer_stats/aer_rootport_total_err_nonfatal +What: /sys/bus/pci/devices//aer_rootport_total_err_nonfatal Date: July 2018 -KernelVersion: 4.19.0 +KernelVersion: 4.19.0 Contact: linux-pci@vger.kernel.org, rajatja@google.com Description: Total number of ERR_NONFATAL messages reported to rootport. diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-avs b/Documentation/ABI/testing/sysfs-bus-pci-devices-avs new file mode 100644 index 00000000000000..ebff3fa12055db --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-avs @@ -0,0 +1,8 @@ +What: /sys/devices/pci0000:00//avs/fw_version +Date: February 2024 +Contact: Cezary Rojewski +Description: + Version of AudioDSP firmware ASoC avs driver is communicating + with. + + Format: %d.%d.%d.%d, type:major:minor:build. diff --git a/Documentation/ABI/testing/sysfs-bus-vdpa b/Documentation/ABI/testing/sysfs-bus-vdpa index 4da53878bff6b8..2c833b5163f217 100644 --- a/Documentation/ABI/testing/sysfs-bus-vdpa +++ b/Documentation/ABI/testing/sysfs-bus-vdpa @@ -1,6 +1,6 @@ What: /sys/bus/vdpa/drivers_autoprobe Date: March 2020 -Contact: virtualization@lists.linux-foundation.org +Contact: virtualization@lists.linux.dev Description: This file determines whether new devices are immediately bound to a driver after the creation. It initially contains 1, which @@ -12,7 +12,7 @@ Description: What: /sys/bus/vdpa/driver_probe Date: March 2020 -Contact: virtualization@lists.linux-foundation.org +Contact: virtualization@lists.linux.dev Description: Writing a device name to this file will cause the kernel binds devices to a compatible driver. @@ -22,7 +22,7 @@ Description: What: /sys/bus/vdpa/drivers/.../bind Date: March 2020 -Contact: virtualization@lists.linux-foundation.org +Contact: virtualization@lists.linux.dev Description: Writing a device name to this file will cause the driver to attempt to bind to the device. This is useful for overriding @@ -30,7 +30,7 @@ Description: What: /sys/bus/vdpa/drivers/.../unbind Date: March 2020 -Contact: virtualization@lists.linux-foundation.org +Contact: virtualization@lists.linux.dev Description: Writing a device name to this file will cause the driver to attempt to unbind from the device. This may be useful when @@ -38,7 +38,7 @@ Description: What: /sys/bus/vdpa/devices/.../driver_override Date: November 2021 -Contact: virtualization@lists.linux-foundation.org +Contact: virtualization@lists.linux.dev Description: This file allows the driver for a device to be specified. When specified, only a driver with a name matching the value diff --git a/Documentation/ABI/testing/sysfs-class-hwmon b/Documentation/ABI/testing/sysfs-class-hwmon index 3dac923c9b0ef0..cfd0d0bab48398 100644 --- a/Documentation/ABI/testing/sysfs-class-hwmon +++ b/Documentation/ABI/testing/sysfs-class-hwmon @@ -149,6 +149,15 @@ Description: RW +What: /sys/class/hwmon/hwmonX/inY_fault +Description: + Reports a voltage hard failure (eg: shorted component) + + - 1: Failed + - 0: Ok + + RO + What: /sys/class/hwmon/hwmonX/cpuY_vid Description: CPU core reference voltage. @@ -968,6 +977,15 @@ Description: RW +What: /sys/class/hwmon/hwmonX/humidityY_max_alarm +Description: + Maximum humidity detection + + - 0: OK + - 1: Maximum humidity detected + + RO + What: /sys/class/hwmon/hwmonX/humidityY_max_hyst Description: Humidity hysteresis value for max limit. @@ -987,6 +1005,15 @@ Description: RW +What: /sys/class/hwmon/hwmonX/humidityY_min_alarm +Description: + Minimum humidity detection + + - 0: OK + - 1: Minimum humidity detected + + RO + What: /sys/class/hwmon/hwmonX/humidityY_min_hyst Description: Humidity hysteresis value for min limit. diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev index a6c307c4befa09..ed46b37ab8a284 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev @@ -88,6 +88,8 @@ Description: speed of 10MBps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 10Mbps link speed. + What: /sys/class/leds//link_100 Date: Jun 2023 KernelVersion: 6.5 @@ -101,6 +103,8 @@ Description: speed of 100Mbps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 100Mbps link speed. + What: /sys/class/leds//link_1000 Date: Jun 2023 KernelVersion: 6.5 @@ -114,6 +118,8 @@ Description: speed of 1000Mbps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 1000Mbps link speed. + What: /sys/class/leds//link_2500 Date: Nov 2023 KernelVersion: 6.8 @@ -127,6 +133,8 @@ Description: speed of 2500Mbps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 2500Mbps link speed. + What: /sys/class/leds//link_5000 Date: Nov 2023 KernelVersion: 6.8 @@ -140,6 +148,8 @@ Description: speed of 5000Mbps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 5000Mbps link speed. + What: /sys/class/leds//link_10000 Date: Nov 2023 KernelVersion: 6.8 @@ -153,6 +163,8 @@ Description: speed of 10000Mbps of the named network device. Setting this value also immediately changes the LED state. + Present only if the named network device supports 10000Mbps link speed. + What: /sys/class/leds//half_duplex Date: Jun 2023 KernelVersion: 6.5 diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-tty b/Documentation/ABI/testing/sysfs-class-led-trigger-tty index 30cef9ac0f493a..308fbc3627cd1a 100644 --- a/Documentation/ABI/testing/sysfs-class-led-trigger-tty +++ b/Documentation/ABI/testing/sysfs-class-led-trigger-tty @@ -1,11 +1,11 @@ -What: /sys/class/leds//ttyname +What: /sys/class/leds//ttyname Date: Dec 2020 KernelVersion: 5.10 Contact: linux-leds@vger.kernel.org Description: Specifies the tty device name of the triggering tty -What: /sys/class/leds//rx +What: /sys/class/leds//rx Date: February 2024 KernelVersion: 6.8 Description: @@ -13,7 +13,7 @@ Description: If set to 0, the LED will not blink on reception. If set to 1 (default), the LED will blink on reception. -What: /sys/class/leds//tx +What: /sys/class/leds//tx Date: February 2024 KernelVersion: 6.8 Description: @@ -21,7 +21,7 @@ Description: If set to 0, the LED will not blink on transmission. If set to 1 (default), the LED will blink on transmission. -What: /sys/class/leds//cts +What: /sys/class/leds//cts Date: February 2024 KernelVersion: 6.8 Description: @@ -31,7 +31,7 @@ Description: If set to 0 (default), the LED will not evaluate CTS. If set to 1, the LED will evaluate CTS. -What: /sys/class/leds//dsr +What: /sys/class/leds//dsr Date: February 2024 KernelVersion: 6.8 Description: @@ -41,7 +41,7 @@ Description: If set to 0 (default), the LED will not evaluate DSR. If set to 1, the LED will evaluate DSR. -What: /sys/class/leds//dcd +What: /sys/class/leds//dcd Date: February 2024 KernelVersion: 6.8 Description: @@ -51,7 +51,7 @@ Description: If set to 0 (default), the LED will not evaluate CAR (DCD). If set to 1, the LED will evaluate CAR (DCD). -What: /sys/class/leds//rng +What: /sys/class/leds//rng Date: February 2024 KernelVersion: 6.8 Description: diff --git a/Documentation/ABI/testing/sysfs-class-net-queues b/Documentation/ABI/testing/sysfs-class-net-queues index 906ff3ca928ac1..5bff64d256c207 100644 --- a/Documentation/ABI/testing/sysfs-class-net-queues +++ b/Documentation/ABI/testing/sysfs-class-net-queues @@ -1,4 +1,4 @@ -What: /sys/class//queues/rx-/rps_cpus +What: /sys/class/net//queues/rx-/rps_cpus Date: March 2010 KernelVersion: 2.6.35 Contact: netdev@vger.kernel.org @@ -8,7 +8,7 @@ Description: network device queue. Possible values depend on the number of available CPU(s) in the system. -What: /sys/class//queues/rx-/rps_flow_cnt +What: /sys/class/net//queues/rx-/rps_flow_cnt Date: April 2010 KernelVersion: 2.6.35 Contact: netdev@vger.kernel.org @@ -16,7 +16,7 @@ Description: Number of Receive Packet Steering flows being currently processed by this particular network device receive queue. -What: /sys/class//queues/tx-/tx_timeout +What: /sys/class/net//queues/tx-/tx_timeout Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org @@ -24,7 +24,7 @@ Description: Indicates the number of transmit timeout events seen by this network interface transmit queue. -What: /sys/class//queues/tx-/tx_maxrate +What: /sys/class/net//queues/tx-/tx_maxrate Date: March 2015 KernelVersion: 4.1 Contact: netdev@vger.kernel.org @@ -32,7 +32,7 @@ Description: A Mbps max-rate set for the queue, a value of zero means disabled, default is disabled. -What: /sys/class//queues/tx-/xps_cpus +What: /sys/class/net//queues/tx-/xps_cpus Date: November 2010 KernelVersion: 2.6.38 Contact: netdev@vger.kernel.org @@ -42,7 +42,7 @@ Description: network device transmit queue. Possible values depend on the number of available CPU(s) in the system. -What: /sys/class//queues/tx-/xps_rxqs +What: /sys/class/net//queues/tx-/xps_rxqs Date: June 2018 KernelVersion: 4.18.0 Contact: netdev@vger.kernel.org @@ -53,7 +53,7 @@ Description: number of available receive queue(s) in the network device. Default is disabled. -What: /sys/class//queues/tx-/byte_queue_limits/hold_time +What: /sys/class/net//queues/tx-/byte_queue_limits/hold_time Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org @@ -62,7 +62,7 @@ Description: of this particular network device transmit queue. Default value is 1000. -What: /sys/class//queues/tx-/byte_queue_limits/inflight +What: /sys/class/net//queues/tx-/byte_queue_limits/inflight Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org @@ -70,7 +70,7 @@ Description: Indicates the number of bytes (objects) in flight on this network device transmit queue. -What: /sys/class//queues/tx-/byte_queue_limits/limit +What: /sys/class/net//queues/tx-/byte_queue_limits/limit Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org @@ -79,7 +79,7 @@ Description: on this network device transmit queue. This value is clamped to be within the bounds defined by limit_max and limit_min. -What: /sys/class//queues/tx-/byte_queue_limits/limit_max +What: /sys/class/net//queues/tx-/byte_queue_limits/limit_max Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org @@ -88,7 +88,7 @@ Description: queued on this network device transmit queue. See include/linux/dynamic_queue_limits.h for the default value. -What: /sys/class//queues/tx-/byte_queue_limits/limit_min +What: /sys/class/net//queues/tx-/byte_queue_limits/limit_min Date: November 2011 KernelVersion: 3.3 Contact: netdev@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-net-statistics b/Documentation/ABI/testing/sysfs-class-net-statistics index 55db27815361b2..53e508c6936a51 100644 --- a/Documentation/ABI/testing/sysfs-class-net-statistics +++ b/Documentation/ABI/testing/sysfs-class-net-statistics @@ -1,4 +1,4 @@ -What: /sys/class//statistics/collisions +What: /sys/class/net//statistics/collisions Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -6,7 +6,7 @@ Description: Indicates the number of collisions seen by this network device. This value might not be relevant with all MAC layers. -What: /sys/class//statistics/multicast +What: /sys/class/net//statistics/multicast Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -14,7 +14,7 @@ Description: Indicates the number of multicast packets received by this network device. -What: /sys/class//statistics/rx_bytes +What: /sys/class/net//statistics/rx_bytes Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -23,7 +23,7 @@ Description: See the network driver for the exact meaning of when this value is incremented. -What: /sys/class//statistics/rx_compressed +What: /sys/class/net//statistics/rx_compressed Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -32,7 +32,7 @@ Description: network device. This value might only be relevant for interfaces that support packet compression (e.g: PPP). -What: /sys/class//statistics/rx_crc_errors +What: /sys/class/net//statistics/rx_crc_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -41,7 +41,7 @@ Description: by this network device. Note that the specific meaning might depend on the MAC layer used by the interface. -What: /sys/class//statistics/rx_dropped +What: /sys/class/net//statistics/rx_dropped Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -51,7 +51,7 @@ Description: packet processing. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_errors +What: /sys/class/net//statistics/rx_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -59,7 +59,7 @@ Description: Indicates the number of receive errors on this network device. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_fifo_errors +What: /sys/class/net//statistics/rx_fifo_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -68,7 +68,7 @@ Description: network device. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_frame_errors +What: /sys/class/net//statistics/rx_frame_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -78,7 +78,7 @@ Description: on the MAC layer protocol used. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_length_errors +What: /sys/class/net//statistics/rx_length_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -87,7 +87,7 @@ Description: error, oversized or undersized. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_missed_errors +What: /sys/class/net//statistics/rx_missed_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -96,7 +96,7 @@ Description: due to lack of capacity in the receive side. See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_nohandler +What: /sys/class/net//statistics/rx_nohandler Date: February 2016 KernelVersion: 4.6 Contact: netdev@vger.kernel.org @@ -104,7 +104,7 @@ Description: Indicates the number of received packets that were dropped on an inactive device by the network core. -What: /sys/class//statistics/rx_over_errors +What: /sys/class/net//statistics/rx_over_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -114,7 +114,7 @@ Description: (e.g: larger than MTU). See the network driver for the exact meaning of this value. -What: /sys/class//statistics/rx_packets +What: /sys/class/net//statistics/rx_packets Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -122,7 +122,7 @@ Description: Indicates the total number of good packets received by this network device. -What: /sys/class//statistics/tx_aborted_errors +What: /sys/class/net//statistics/tx_aborted_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -132,7 +132,7 @@ Description: a medium collision). See the network driver for the exact meaning of this value. -What: /sys/class//statistics/tx_bytes +What: /sys/class/net//statistics/tx_bytes Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -143,7 +143,7 @@ Description: transmitted packets or all packets that have been queued for transmission. -What: /sys/class//statistics/tx_carrier_errors +What: /sys/class/net//statistics/tx_carrier_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -152,7 +152,7 @@ Description: because of carrier errors (e.g: physical link down). See the network driver for the exact meaning of this value. -What: /sys/class//statistics/tx_compressed +What: /sys/class/net//statistics/tx_compressed Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -161,7 +161,7 @@ Description: this might only be relevant for devices that support compression (e.g: PPP). -What: /sys/class//statistics/tx_dropped +What: /sys/class/net//statistics/tx_dropped Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -170,7 +170,7 @@ Description: See the driver for the exact reasons as to why the packets were dropped. -What: /sys/class//statistics/tx_errors +What: /sys/class/net//statistics/tx_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -179,7 +179,7 @@ Description: a network device. See the driver for the exact reasons as to why the packets were dropped. -What: /sys/class//statistics/tx_fifo_errors +What: /sys/class/net//statistics/tx_fifo_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -188,7 +188,7 @@ Description: FIFO error. See the driver for the exact reasons as to why the packets were dropped. -What: /sys/class//statistics/tx_heartbeat_errors +What: /sys/class/net//statistics/tx_heartbeat_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -197,7 +197,7 @@ Description: reported as heartbeat errors. See the driver for the exact reasons as to why the packets were dropped. -What: /sys/class//statistics/tx_packets +What: /sys/class/net//statistics/tx_packets Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org @@ -206,7 +206,7 @@ Description: device. See the driver for whether this reports the number of all attempted or successful transmissions. -What: /sys/class//statistics/tx_window_errors +What: /sys/class/net//statistics/tx_window_errors Date: April 2005 KernelVersion: 2.6.12 Contact: netdev@vger.kernel.org diff --git a/Documentation/ABI/testing/sysfs-class-usb_role b/Documentation/ABI/testing/sysfs-class-usb_role index 3b810a425a52c8..9fab3f06679e29 100644 --- a/Documentation/ABI/testing/sysfs-class-usb_role +++ b/Documentation/ABI/testing/sysfs-class-usb_role @@ -19,3 +19,9 @@ Description: - none - host - device + +What: /sys/class/usb_role//connector +Date: Feb 2024 +Contact: Heikki Krogerus +Description: + Optional symlink to the USB Type-C connector. diff --git a/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon index 8d7d8f05f6cd0a..92fe7c5c5ac1d1 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon +++ b/Documentation/ABI/testing/sysfs-driver-intel-i915-hwmon @@ -1,4 +1,4 @@ -What: /sys/devices/.../hwmon/hwmon/in0_input +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/in0_input Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -6,7 +6,7 @@ Description: RO. Current Voltage in millivolt. Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_max +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/power1_max Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -20,7 +20,7 @@ Description: RW. Card reactive sustained (PL1/Tau) power limit in microwatts. Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_rated_max +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/power1_rated_max Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -28,7 +28,7 @@ Description: RO. Card default power limit (default TDP setting). Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_max_interval +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/power1_max_interval Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -37,7 +37,7 @@ Description: RW. Sustained power limit interval (Tau in PL1/Tau) in Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_crit +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/power1_crit Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -50,7 +50,7 @@ Description: RW. Card reactive critical (I1) power limit in microwatts. Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/curr1_crit +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/curr1_crit Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org @@ -63,7 +63,7 @@ Description: RW. Card reactive critical (I1) power limit in milliamperes. Only supported for particular Intel i915 graphics platforms. -What: /sys/devices/.../hwmon/hwmon/energy1_input +What: /sys/bus/pci/drivers/i915/.../hwmon/hwmon/energy1_input Date: February 2023 KernelVersion: 6.2 Contact: intel-gfx@lists.freedesktop.org diff --git a/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon index 8c321bc9dc0440..023fd82de3f70a 100644 --- a/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon +++ b/Documentation/ABI/testing/sysfs-driver-intel-xe-hwmon @@ -1,4 +1,4 @@ -What: /sys/devices/.../hwmon/hwmon/power1_max +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/power1_max Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -12,7 +12,7 @@ Description: RW. Card reactive sustained (PL1) power limit in microwatts. Only supported for particular Intel xe graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_rated_max +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/power1_rated_max Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -20,7 +20,7 @@ Description: RO. Card default power limit (default TDP setting). Only supported for particular Intel xe graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_crit +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/power1_crit Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -33,7 +33,7 @@ Description: RW. Card reactive critical (I1) power limit in microwatts. Only supported for particular Intel xe graphics platforms. -What: /sys/devices/.../hwmon/hwmon/curr1_crit +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/curr1_crit Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -44,7 +44,7 @@ Description: RW. Card reactive critical (I1) power limit in milliamperes. the operating frequency if the power averaged over a window exceeds this limit. -What: /sys/devices/.../hwmon/hwmon/in0_input +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/in0_input Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -52,7 +52,7 @@ Description: RO. Current Voltage in millivolt. Only supported for particular Intel xe graphics platforms. -What: /sys/devices/.../hwmon/hwmon/energy1_input +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/energy1_input Date: September 2023 KernelVersion: 6.5 Contact: intel-xe@lists.freedesktop.org @@ -60,7 +60,7 @@ Description: RO. Energy input of device in microjoules. Only supported for particular Intel xe graphics platforms. -What: /sys/devices/.../hwmon/hwmon/power1_max_interval +What: /sys/bus/pci/drivers/xe/.../hwmon/hwmon/power1_max_interval Date: October 2023 KernelVersion: 6.6 Contact: intel-xe@lists.freedesktop.org diff --git a/Documentation/ABI/testing/sysfs-driver-qat b/Documentation/ABI/testing/sysfs-driver-qat index bbf329cf0d67bc..6778f1fea8740d 100644 --- a/Documentation/ABI/testing/sysfs-driver-qat +++ b/Documentation/ABI/testing/sysfs-driver-qat @@ -141,3 +141,23 @@ Description: 64 This attribute is only available for qat_4xxx devices. + +What: /sys/bus/pci/devices//qat/auto_reset +Date: March 2024 +KernelVersion: 6.8 +Contact: qat-linux@intel.com +Description: (RW) Reports the current state of the autoreset feature + for a QAT device + + Write to the attribute to enable or disable device auto reset. + + Device auto reset is disabled by default. + + The values are:: + + * 1/Yy/on: auto reset enabled. If the device encounters an + unrecoverable error, it will be reset automatically. + * 0/Nn/off: auto reset disabled. If the device encounters an + unrecoverable error, it will not be reset. + + This attribute is only available for qat_4xxx devices. diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs index 99fa87a43926e6..48c135e24eb57d 100644 --- a/Documentation/ABI/testing/sysfs-fs-f2fs +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -701,29 +701,30 @@ Description: Support configuring fault injection type, should be enabled with fault_injection option, fault type value is shown below, it supports single or combined type. - =================== =========== - Type_Name Type_Value - =================== =========== - FAULT_KMALLOC 0x000000001 - FAULT_KVMALLOC 0x000000002 - FAULT_PAGE_ALLOC 0x000000004 - FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 (obsolete) - FAULT_ALLOC_NID 0x000000020 - FAULT_ORPHAN 0x000000040 - FAULT_BLOCK 0x000000080 - FAULT_DIR_DEPTH 0x000000100 - FAULT_EVICT_INODE 0x000000200 - FAULT_TRUNCATE 0x000000400 - FAULT_READ_IO 0x000000800 - FAULT_CHECKPOINT 0x000001000 - FAULT_DISCARD 0x000002000 - FAULT_WRITE_IO 0x000004000 - FAULT_SLAB_ALLOC 0x000008000 - FAULT_DQUOT_INIT 0x000010000 - FAULT_LOCK_OP 0x000020000 - FAULT_BLKADDR 0x000040000 - =================== =========== + =========================== =========== + Type_Name Type_Value + =========================== =========== + FAULT_KMALLOC 0x000000001 + FAULT_KVMALLOC 0x000000002 + FAULT_PAGE_ALLOC 0x000000004 + FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 (obsolete) + FAULT_ALLOC_NID 0x000000020 + FAULT_ORPHAN 0x000000040 + FAULT_BLOCK 0x000000080 + FAULT_DIR_DEPTH 0x000000100 + FAULT_EVICT_INODE 0x000000200 + FAULT_TRUNCATE 0x000000400 + FAULT_READ_IO 0x000000800 + FAULT_CHECKPOINT 0x000001000 + FAULT_DISCARD 0x000002000 + FAULT_WRITE_IO 0x000004000 + FAULT_SLAB_ALLOC 0x000008000 + FAULT_DQUOT_INIT 0x000010000 + FAULT_LOCK_OP 0x000020000 + FAULT_BLKADDR_VALIDITY 0x000040000 + FAULT_BLKADDR_CONSISTENCE 0x000080000 + =========================== =========== What: /sys/fs/f2fs//discard_io_aware_gran Date: January 2023 diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-cma b/Documentation/ABI/testing/sysfs-kernel-mm-cma index 02b2bb60c2969c..dfd755201142f1 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-cma +++ b/Documentation/ABI/testing/sysfs-kernel-mm-cma @@ -23,3 +23,9 @@ Date: Feb 2021 Contact: Minchan Kim Description: the number of pages CMA API failed to allocate + +What: /sys/kernel/mm/cma//release_pages_success +Date: Feb 2024 +Contact: Anshuman Khandual +Description: + the number of pages CMA API succeeded to release diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon index bfa5b8288d8d11..dad4d5ffd78656 100644 --- a/Documentation/ABI/testing/sysfs-kernel-mm-damon +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -34,7 +34,9 @@ Description: Writing 'on' or 'off' to this file makes the kdamond starts or kdamond. Writing 'update_schemes_tried_bytes' to the file updates only '.../tried_regions/total_bytes' files of this kdamond. Writing 'clear_schemes_tried_regions' to the file - removes contents of the 'tried_regions' directory. + removes contents of the 'tried_regions' directory. Writing + 'update_schemes_effective_quotas' to the file updates + '.../quotas/effective_bytes' files of this kdamond. What: /sys/kernel/mm/damon/admin/kdamonds//pid Date: Mar 2022 @@ -208,6 +210,12 @@ Contact: SeongJae Park Description: Writing to and reading from this file sets and gets the size quota of the scheme in bytes. +What: /sys/kernel/mm/damon/admin/kdamonds//contexts//schemes//quotas/effective_bytes +Date: Feb 2024 +Contact: SeongJae Park +Description: Reading from this file gets the effective size quota of the + scheme in bytes, which adjusted for the time quota and goals. + What: /sys/kernel/mm/damon/admin/kdamonds//contexts//schemes//quotas/reset_interval_ms Date: Mar 2022 Contact: SeongJae Park @@ -221,6 +229,12 @@ Description: Writing a number 'N' to this file creates the number of directories for setting automatic tuning of the scheme's aggressiveness named '0' to 'N-1' under the goals/ directory. +What: /sys/kernel/mm/damon/admin/kdamonds//contexts//schemes//quotas/goals//target_metric +Date: Feb 2024 +Contact: SeongJae Park +Description: Writing to and reading from this file sets and gets the quota + auto-tuning goal metric. + What: /sys/kernel/mm/damon/admin/kdamonds//contexts//schemes//quotas/goals//target_value Date: Nov 2023 Contact: SeongJae Park diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy new file mode 100644 index 00000000000000..8ac327fd7fb6e3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy @@ -0,0 +1,4 @@ +What: /sys/kernel/mm/mempolicy/ +Date: January 2024 +Contact: Linux memory management mailing list +Description: Interface for Mempolicy diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave new file mode 100644 index 00000000000000..0b7972de04e939 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-mempolicy-weighted-interleave @@ -0,0 +1,25 @@ +What: /sys/kernel/mm/mempolicy/weighted_interleave/ +Date: January 2024 +Contact: Linux memory management mailing list +Description: Configuration Interface for the Weighted Interleave policy + +What: /sys/kernel/mm/mempolicy/weighted_interleave/nodeN +Date: January 2024 +Contact: Linux memory management mailing list +Description: Weight configuration interface for nodeN + + The interleave weight for a memory node (N). These weights are + utilized by tasks which have set their mempolicy to + MPOL_WEIGHTED_INTERLEAVE. + + These weights only affect new allocations, and changes at runtime + will not cause migrations on already allocated pages. + + The minimum weight for a node is always 1. + + Minimum weight: 1 + Maximum weight: 255 + + Writing an empty string or `0` will reset the weight to the + system default. The system default may be set by the kernel + or drivers at boot or during hotplug events. diff --git a/Documentation/ABI/testing/sysfs-nvmem-cells b/Documentation/ABI/testing/sysfs-nvmem-cells index 7af70adf3690e3..c7c9444f92a880 100644 --- a/Documentation/ABI/testing/sysfs-nvmem-cells +++ b/Documentation/ABI/testing/sysfs-nvmem-cells @@ -4,18 +4,18 @@ KernelVersion: 6.5 Contact: Miquel Raynal Description: The "cells" folder contains one file per cell exposed by the - NVMEM device. The name of the file is: @, with - being the cell name and its location in the NVMEM - device, in hexadecimal (without the '0x' prefix, to mimic device - tree node names). The length of the file is the size of the cell - (when known). The content of the file is the binary content of - the cell (may sometimes be ASCII, likely without trailing - character). + NVMEM device. The name of the file is: "@,", + with being the cell name and its location in + the NVMEM device, in hexadecimal bytes and bits (without the + '0x' prefix, to mimic device tree node names). The length of + the file is the size of the cell (when known). The content of + the file is the binary content of the cell (may sometimes be + ASCII, likely without trailing character). Note: This file is only present if CONFIG_NVMEM_SYSFS is enabled. Example:: - hexdump -C /sys/bus/nvmem/devices/1-00563/cells/product-name@d + hexdump -C /sys/bus/nvmem/devices/1-00563/cells/product-name@d,0 00000000 54 4e 34 38 4d 2d 50 2d 44 4e |TN48M-P-DN| 0000000a diff --git a/Documentation/ABI/testing/sysfs-platform-silicom b/Documentation/ABI/testing/sysfs-platform-silicom index 2288b3665d160a..4d1cc5bdbcc5f9 100644 --- a/Documentation/ABI/testing/sysfs-platform-silicom +++ b/Documentation/ABI/testing/sysfs-platform-silicom @@ -10,6 +10,7 @@ What: /sys/devices/platform/silicom-platform/power_cycle Date: November 2023 KernelVersion: 6.7 Contact: Henry Shi +Description: This file allow user to power cycle the platform. Default value is 0; when set to 1, it powers down the platform, waits 5 seconds, then powers on the diff --git a/Documentation/Makefile b/Documentation/Makefile index 3885bbe260eb23..4479910166fc10 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -176,6 +176,7 @@ refcheckdocs: $(Q)cd $(srctree);scripts/documentation-file-ref-check cleandocs: + $(Q)rm -f $(YNL_INDEX) $(YNL_RST_FILES) $(Q)rm -rf $(BUILDDIR) $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 2d42998a89a637..3e6407de231c99 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -68,7 +68,8 @@ over a rather long period of time, but improvements are always welcome! rcu_read_lock_sched(), or by the appropriate update-side lock. Explicit disabling of preemption (preempt_disable(), for example) can serve as rcu_read_lock_sched(), but is less readable and - prevents lockdep from detecting locking issues. + prevents lockdep from detecting locking issues. Acquiring a + spinlock also enters an RCU read-side critical section. Please note that you *cannot* rely on code known to be built only in non-preemptible kernels. Such code can and will break, @@ -382,16 +383,17 @@ over a rather long period of time, but improvements are always welcome! must use whatever locking or other synchronization is required to safely access and/or modify that data structure. - Do not assume that RCU callbacks will be executed on the same - CPU that executed the corresponding call_rcu() or call_srcu(). - For example, if a given CPU goes offline while having an RCU - callback pending, then that RCU callback will execute on some - surviving CPU. (If this was not the case, a self-spawning RCU - callback would prevent the victim CPU from ever going offline.) - Furthermore, CPUs designated by rcu_nocbs= might well *always* - have their RCU callbacks executed on some other CPUs, in fact, - for some real-time workloads, this is the whole point of using - the rcu_nocbs= kernel boot parameter. + Do not assume that RCU callbacks will be executed on + the same CPU that executed the corresponding call_rcu(), + call_srcu(), call_rcu_tasks(), call_rcu_tasks_rude(), or + call_rcu_tasks_trace(). For example, if a given CPU goes offline + while having an RCU callback pending, then that RCU callback + will execute on some surviving CPU. (If this was not the case, + a self-spawning RCU callback would prevent the victim CPU from + ever going offline.) Furthermore, CPUs designated by rcu_nocbs= + might well *always* have their RCU callbacks executed on some + other CPUs, in fact, for some real-time workloads, this is the + whole point of using the rcu_nocbs= kernel boot parameter. In addition, do not assume that callbacks queued in a given order will be invoked in that order, even if they all are queued on the @@ -444,7 +446,7 @@ over a rather long period of time, but improvements are always welcome! real-time workloads than is synchronize_rcu_expedited(). It is also permissible to sleep in RCU Tasks Trace read-side - critical, which are delimited by rcu_read_lock_trace() and + critical section, which are delimited by rcu_read_lock_trace() and rcu_read_unlock_trace(). However, this is a specialized flavor of RCU, and you should not use it without first checking with its current users. In most cases, you should instead use SRCU. @@ -490,6 +492,12 @@ over a rather long period of time, but improvements are always welcome! since the last time that you passed that same object to call_rcu() (or friends). + CONFIG_RCU_STRICT_GRACE_PERIOD: + combine with KASAN to check for pointers leaked out + of RCU read-side critical sections. This Kconfig + option is tough on both performance and scalability, + and so is limited to four-CPU systems. + __rcu sparse checks: tag the pointer to the RCU-protected data structure with __rcu, and sparse will warn you if you access that diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index 659d5913784d0d..2524dcdadde2b8 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -408,7 +408,10 @@ member of the rcu_dereference() to use in various situations: RCU flavors, an RCU read-side critical section is entered using rcu_read_lock(), anything that disables bottom halves, anything that disables interrupts, or anything that disables - preemption. + preemption. Please note that spinlock critical sections + are also implied RCU read-side critical sections, even when + they are preemptible, as they are in kernels built with + CONFIG_PREEMPT_RT=y. 2. If the access might be within an RCU read-side critical section on the one hand, or protected by (say) my_lock on the other, diff --git a/Documentation/RCU/torture.rst b/Documentation/RCU/torture.rst index 49e7beea6ae151..4b1f99c4181fee 100644 --- a/Documentation/RCU/torture.rst +++ b/Documentation/RCU/torture.rst @@ -318,7 +318,7 @@ Suppose that a previous kvm.sh run left its output in this directory:: tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 -Then this run can be re-run without rebuilding as follow: +Then this run can be re-run without rebuilding as follow:: kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 diff --git a/Documentation/RCU/whatisRCU.rst b/Documentation/RCU/whatisRCU.rst index 60ce02475142d8..94838c65c7d971 100644 --- a/Documentation/RCU/whatisRCU.rst +++ b/Documentation/RCU/whatisRCU.rst @@ -172,14 +172,25 @@ rcu_read_lock() critical section. Reference counts may be used in conjunction with RCU to maintain longer-term references to data structures. + Note that anything that disables bottom halves, preemption, + or interrupts also enters an RCU read-side critical section. + Acquiring a spinlock also enters an RCU read-side critical + sections, even for spinlocks that do not disable preemption, + as is the case in kernels built with CONFIG_PREEMPT_RT=y. + Sleeplocks do *not* enter RCU read-side critical sections. + rcu_read_unlock() ^^^^^^^^^^^^^^^^^ void rcu_read_unlock(void); This temporal primitives is used by a reader to inform the reclaimer that the reader is exiting an RCU read-side critical - section. Note that RCU read-side critical sections may be nested - and/or overlapping. + section. Anything that enables bottom halves, preemption, + or interrupts also exits an RCU read-side critical section. + Releasing a spinlock also exits an RCU read-side critical section. + + Note that RCU read-side critical sections may be nested and/or + overlapping. synchronize_rcu() ^^^^^^^^^^^^^^^^^ @@ -416,7 +427,7 @@ their assorted primitives. This section shows a simple use of the core RCU API to protect a global pointer to a dynamically allocated structure. More-typical -uses of RCU may be found in listRCU.rst, arrayRCU.rst, and NMI-RCU.rst. +uses of RCU may be found in listRCU.rst and NMI-RCU.rst. :: struct foo { @@ -499,8 +510,8 @@ So, to sum up: data item. See checklist.rst for additional rules to follow when using RCU. -And again, more-typical uses of RCU may be found in listRCU.rst, -arrayRCU.rst, and NMI-RCU.rst. +And again, more-typical uses of RCU may be found in listRCU.rst +and NMI-RCU.rst. .. _4_whatisRCU: @@ -952,8 +963,8 @@ unfortunately any spinlock in a ``SLAB_TYPESAFE_BY_RCU`` object must be initialized after each and every call to kmem_cache_alloc(), which renders reference-free spinlock acquisition completely unsafe. Therefore, when using ``SLAB_TYPESAFE_BY_RCU``, make proper use of a reference counter. -(Those willing to use a kmem_cache constructor may also use locking, -including cache-friendly sequence locking.) +(Those willing to initialize their locks in a kmem_cache constructor +may also use locking, including cache-friendly sequence locking.) With traditional reference counting -- such as that implemented by the kref library in Linux -- there is typically code that runs when the last diff --git a/Documentation/accel/introduction.rst b/Documentation/accel/introduction.rst index 89984dfececf0b..ae30301366379d 100644 --- a/Documentation/accel/introduction.rst +++ b/Documentation/accel/introduction.rst @@ -101,8 +101,8 @@ External References email threads ------------- -* `Initial discussion on the New subsystem for acceleration devices `_ - Oded Gabbay (2022) -* `patch-set to add the new subsystem `_ - Oded Gabbay (2022) +* `Initial discussion on the New subsystem for acceleration devices `_ - Oded Gabbay (2022) +* `patch-set to add the new subsystem `_ - Oded Gabbay (2022) Conference talks ---------------- diff --git a/Documentation/admin-guide/RAS/address-translation.rst b/Documentation/admin-guide/RAS/address-translation.rst new file mode 100644 index 00000000000000..f0ca17b43cd3de --- /dev/null +++ b/Documentation/admin-guide/RAS/address-translation.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Address translation +=================== + +x86 AMD +------- + +Zen-based AMD systems include a Data Fabric that manages the layout of +physical memory. Devices attached to the Fabric, like memory controllers, +I/O, etc., may not have a complete view of the system physical memory map. +These devices may provide a "normalized", i.e. device physical, address +when reporting memory errors. Normalized addresses must be translated to +a system physical address for the kernel to action on the memory. + +AMD Address Translation Library (CONFIG_AMD_ATL) provides translation for +this case. + +Glossary of acronyms used in address translation for Zen-based systems + +* CCM = Cache Coherent Moderator +* COD = Cluster-on-Die +* COH_ST = Coherent Station +* DF = Data Fabric diff --git a/Documentation/RAS/ras.rst b/Documentation/admin-guide/RAS/error-decoding.rst similarity index 73% rename from Documentation/RAS/ras.rst rename to Documentation/admin-guide/RAS/error-decoding.rst index 2556b397cd271f..26a72f3fe5de83 100644 --- a/Documentation/RAS/ras.rst +++ b/Documentation/admin-guide/RAS/error-decoding.rst @@ -1,15 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 -Reliability, Availability and Serviceability features -===================================================== - -This documents different aspects of the RAS functionality present in the -kernel. - Error decoding ---------------- +============== -* x86 +x86 +--- Error decoding on AMD systems should be done using the rasdaemon tool: https://github.com/mchehab/rasdaemon/ diff --git a/Documentation/admin-guide/RAS/index.rst b/Documentation/admin-guide/RAS/index.rst new file mode 100644 index 00000000000000..f4087040a7c054 --- /dev/null +++ b/Documentation/admin-guide/RAS/index.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. toctree:: + :maxdepth: 2 + + main + error-decoding + address-translation diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/RAS/main.rst similarity index 99% rename from Documentation/admin-guide/ras.rst rename to Documentation/admin-guide/RAS/main.rst index 8e03751d126d01..7ac1d4ccc50993 100644 --- a/Documentation/admin-guide/ras.rst +++ b/Documentation/admin-guide/RAS/main.rst @@ -1,8 +1,12 @@ +.. SPDX-License-Identifier: GPL-2.0 .. include:: -============================================ -Reliability, Availability and Serviceability -============================================ +================================================== +Reliability, Availability and Serviceability (RAS) +================================================== + +This documents different aspects of the RAS functionality present in the +kernel. RAS concepts ************ diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 9a969c0157f1e5..f2bebff6a733f6 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -262,9 +262,11 @@ Compiling the kernel - Make sure you have at least gcc 5.1 available. For more information, refer to :ref:`Documentation/process/changes.rst `. - - Do a ``make`` to create a compressed kernel image. It is also - possible to do ``make install`` if you have lilo installed to suit the - kernel makefiles, but you may want to check your particular lilo setup first. + - Do a ``make`` to create a compressed kernel image. It is also possible to do + ``make install`` if you have lilo installed or if your distribution has an + install script recognised by the kernel's installer. Most popular + distributions will have a recognized install script. You may want to + check your distribution's setup first. To do the actual install, you have to be root, but none of the normal build should require that. Don't take the name of root in vain. @@ -301,32 +303,51 @@ Compiling the kernel image (e.g. .../linux/arch/x86/boot/bzImage after compilation) to the place where your regular bootable kernel is found. - - Booting a kernel directly from a floppy without the assistance of a - bootloader such as LILO, is no longer supported. - - If you boot Linux from the hard drive, chances are you use LILO, which - uses the kernel image as specified in the file /etc/lilo.conf. The - kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or - /boot/bzImage. To use the new kernel, save a copy of the old image - and copy the new image over the old one. Then, you MUST RERUN LILO - to update the loading map! If you don't, you won't be able to boot - the new kernel image. - - Reinstalling LILO is usually a matter of running /sbin/lilo. - You may wish to edit /etc/lilo.conf to specify an entry for your - old kernel image (say, /vmlinux.old) in case the new one does not - work. See the LILO docs for more information. - - After reinstalling LILO, you should be all set. Shutdown the system, + - Booting a kernel directly from a storage device without the assistance + of a bootloader such as LILO or GRUB, is no longer supported in BIOS + (non-EFI systems). On UEFI/EFI systems, however, you can use EFISTUB + which allows the motherboard to boot directly to the kernel. + On modern workstations and desktops, it's generally recommended to use a + bootloader as difficulties can arise with multiple kernels and secure boot. + For more details on EFISTUB, + see "Documentation/admin-guide/efi-stub.rst". + + - It's important to note that as of 2016 LILO (LInux LOader) is no longer in + active development, though as it was extremely popular, it often comes up + in documentation. Popular alternatives include GRUB2, rEFInd, Syslinux, + systemd-boot, or EFISTUB. For various reasons, it's not recommended to use + software that's no longer in active development. + + - Chances are your distribution includes an install script and running + ``make install`` will be all that's needed. Should that not be the case + you'll have to identify your bootloader and reference its documentation or + configure your EFI. + +Legacy LILO Instructions +------------------------ + + + - If you use LILO the kernel images are specified in the file /etc/lilo.conf. + The kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or + /boot/bzImage. To use the new kernel, save a copy of the old image and copy + the new image over the old one. Then, you MUST RERUN LILO to update the + loading map! If you don't, you won't be able to boot the new kernel image. + + - Reinstalling LILO is usually a matter of running /sbin/lilo. You may wish + to edit /etc/lilo.conf to specify an entry for your old kernel image + (say, /vmlinux.old) in case the new one does not work. See the LILO docs + for more information. + + - After reinstalling LILO, you should be all set. Shutdown the system, reboot, and enjoy! - If you ever need to change the default root device, video mode, - etc. in the kernel image, use your bootloader's boot options - where appropriate. No need to recompile the kernel to change - these parameters. + - If you ever need to change the default root device, video mode, etc. in the + kernel image, use your bootloader's boot options where appropriate. No need + to recompile the kernel to change these parameters. - Reboot with the new kernel and enjoy. + If something goes wrong ----------------------- diff --git a/Documentation/admin-guide/cgroup-v1/hugetlb.rst b/Documentation/admin-guide/cgroup-v1/hugetlb.rst index 0fa724d82abb60..493a8e386700ae 100644 --- a/Documentation/admin-guide/cgroup-v1/hugetlb.rst +++ b/Documentation/admin-guide/cgroup-v1/hugetlb.rst @@ -65,10 +65,12 @@ files include:: 1. Page fault accounting -hugetlb..limit_in_bytes -hugetlb..max_usage_in_bytes -hugetlb..usage_in_bytes -hugetlb..failcnt +:: + + hugetlb..limit_in_bytes + hugetlb..max_usage_in_bytes + hugetlb..usage_in_bytes + hugetlb..failcnt The HugeTLB controller allows users to limit the HugeTLB usage (page fault) per control group and enforces the limit during page fault. Since HugeTLB @@ -82,10 +84,12 @@ getting SIGBUS. 2. Reservation accounting -hugetlb..rsvd.limit_in_bytes -hugetlb..rsvd.max_usage_in_bytes -hugetlb..rsvd.usage_in_bytes -hugetlb..rsvd.failcnt +:: + + hugetlb..rsvd.limit_in_bytes + hugetlb..rsvd.max_usage_in_bytes + hugetlb..rsvd.usage_in_bytes + hugetlb..rsvd.failcnt The HugeTLB controller allows to limit the HugeTLB reservations per control group and enforces the controller limit at reservation time and at the fault of diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 17e6e956515640..0270517ade47cf 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1296,17 +1296,10 @@ PAGE_SIZE multiple when read back. This is a simple interface to trigger memory reclaim in the target cgroup. - This file accepts a single key, the number of bytes to reclaim. - No nested keys are currently supported. - Example:: echo "1G" > memory.reclaim - The interface can be later extended with nested keys to - configure the reclaim behavior. For example, specify the - type of memory to reclaim from (anon, file, ..). - Please note that the kernel can over or under reclaim from the target cgroup. If less bytes are reclaimed than the specified amount, -EAGAIN is returned. @@ -1318,6 +1311,17 @@ PAGE_SIZE multiple when read back. This means that the networking layer will not adapt based on reclaim induced by memory.reclaim. +The following nested keys are defined. + + ========== ================================ + swappiness Swappiness value to reclaim with + ========== ================================ + + Specifying a swappiness value instructs the kernel to perform + the reclaim with that swappiness value. Note that this has the + same semantics as vm.swappiness applied to memcg reclaim with + all the existing limitations and potential future extensions. + memory.peak A read-only single value file which exists on non-root cgroups. diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index cde52cc09645e7..cc5aec8615765e 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -34,6 +34,8 @@ Device Mapper switch thin-provisioning unstriped + vdo-design + vdo verity writecache zero diff --git a/Documentation/admin-guide/device-mapper/vdo-design.rst b/Documentation/admin-guide/device-mapper/vdo-design.rst new file mode 100644 index 00000000000000..3cd59decbec0bb --- /dev/null +++ b/Documentation/admin-guide/device-mapper/vdo-design.rst @@ -0,0 +1,633 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +================ +Design of dm-vdo +================ + +The dm-vdo (virtual data optimizer) target provides inline deduplication, +compression, zero-block elimination, and thin provisioning. A dm-vdo target +can be backed by up to 256TB of storage, and can present a logical size of +up to 4PB. This target was originally developed at Permabit Technology +Corp. starting in 2009. It was first released in 2013 and has been used in +production environments ever since. It was made open-source in 2017 after +Permabit was acquired by Red Hat. This document describes the design of +dm-vdo. For usage, see vdo.rst in the same directory as this file. + +Because deduplication rates fall drastically as the block size increases, a +vdo target has a maximum block size of 4K. However, it can achieve +deduplication rates of 254:1, i.e. up to 254 copies of a given 4K block can +reference a single 4K of actual storage. It can achieve compression rates +of 14:1. All zero blocks consume no storage at all. + +Theory of Operation +=================== + +The design of dm-vdo is based on the idea that deduplication is a two-part +problem. The first is to recognize duplicate data. The second is to avoid +storing multiple copies of those duplicates. Therefore, dm-vdo has two main +parts: a deduplication index (called UDS) that is used to discover +duplicate data, and a data store with a reference counted block map that +maps from logical block addresses to the actual storage location of the +data. + +Zones and Threading +------------------- + +Due to the complexity of data optimization, the number of metadata +structures involved in a single write operation to a vdo target is larger +than most other targets. Furthermore, because vdo must operate on small +block sizes in order to achieve good deduplication rates, acceptable +performance can only be achieved through parallelism. Therefore, vdo's +design attempts to be lock-free. + +Most of a vdo's main data structures are designed to be easily divided into +"zones" such that any given bio must only access a single zone of any zoned +structure. Safety with minimal locking is achieved by ensuring that during +normal operation, each zone is assigned to a specific thread, and only that +thread will access the portion of the data structure in that zone. +Associated with each thread is a work queue. Each bio is associated with a +request object (the "data_vio") which will be added to a work queue when +the next phase of its operation requires access to the structures in the +zone associated with that queue. + +Another way of thinking about this arrangement is that the work queue for +each zone has an implicit lock on the structures it manages for all its +operations, because vdo guarantees that no other thread will alter those +structures. + +Although each structure is divided into zones, this division is not +reflected in the on-disk representation of each data structure. Therefore, +the number of zones for each structure, and hence the number of threads, +can be reconfigured each time a vdo target is started. + +The Deduplication Index +----------------------- + +In order to identify duplicate data efficiently, vdo was designed to +leverage some common characteristics of duplicate data. From empirical +observations, we gathered two key insights. The first is that in most data +sets with significant amounts of duplicate data, the duplicates tend to +have temporal locality. When a duplicate appears, it is more likely that +other duplicates will be detected, and that those duplicates will have been +written at about the same time. This is why the index keeps records in +temporal order. The second insight is that new data is more likely to +duplicate recent data than it is to duplicate older data and in general, +there are diminishing returns to looking further back in time. Therefore, +when the index is full, it should cull its oldest records to make space for +new ones. Another important idea behind the design of the index is that the +ultimate goal of deduplication is to reduce storage costs. Since there is a +trade-off between the storage saved and the resources expended to achieve +those savings, vdo does not attempt to find every last duplicate block. It +is sufficient to find and eliminate most of the redundancy. + +Each block of data is hashed to produce a 16-byte block name. An index +record consists of this block name paired with the presumed location of +that data on the underlying storage. However, it is not possible to +guarantee that the index is accurate. In the most common case, this occurs +because it is too costly to update the index when a block is over-written +or discarded. Doing so would require either storing the block name along +with the blocks, which is difficult to do efficiently in block-based +storage, or reading and rehashing each block before overwriting it. +Inaccuracy can also result from a hash collision where two different blocks +have the same name. In practice, this is extremely unlikely, but because +vdo does not use a cryptographic hash, a malicious workload could be +constructed. Because of these inaccuracies, vdo treats the locations in the +index as hints, and reads each indicated block to verify that it is indeed +a duplicate before sharing the existing block with a new one. + +Records are collected into groups called chapters. New records are added to +the newest chapter, called the open chapter. This chapter is stored in a +format optimized for adding and modifying records, and the content of the +open chapter is not finalized until it runs out of space for new records. +When the open chapter fills up, it is closed and a new open chapter is +created to collect new records. + +Closing a chapter converts it to a different format which is optimized for +reading. The records are written to a series of record pages based on the +order in which they were received. This means that records with temporal +locality should be on a small number of pages, reducing the I/O required to +retrieve them. The chapter also compiles an index that indicates which +record page contains any given name. This index means that a request for a +name can determine exactly which record page may contain that record, +without having to load the entire chapter from storage. This index uses +only a subset of the block name as its key, so it cannot guarantee that an +index entry refers to the desired block name. It can only guarantee that if +there is a record for this name, it will be on the indicated page. Closed +chapters are read-only structures and their contents are never altered in +any way. + +Once enough records have been written to fill up all the available index +space, the oldest chapter is removed to make space for new chapters. Any +time a request finds a matching record in the index, that record is copied +into the open chapter. This ensures that useful block names remain available +in the index, while unreferenced block names are forgotten over time. + +In order to find records in older chapters, the index also maintains a +higher level structure called the volume index, which contains entries +mapping each block name to the chapter containing its newest record. This +mapping is updated as records for the block name are copied or updated, +ensuring that only the newest record for a given block name can be found. +An older record for a block name will no longer be found even though it has +not been deleted from its chapter. Like the chapter index, the volume index +uses only a subset of the block name as its key and can not definitively +say that a record exists for a name. It can only say which chapter would +contain the record if a record exists. The volume index is stored entirely +in memory and is saved to storage only when the vdo target is shut down. + +From the viewpoint of a request for a particular block name, it will first +look up the name in the volume index. This search will either indicate that +the name is new, or which chapter to search. If it returns a chapter, the +request looks up its name in the chapter index. This will indicate either +that the name is new, or which record page to search. Finally, if it is not +new, the request will look for its name in the indicated record page. +This process may require up to two page reads per request (one for the +chapter index page and one for the request page). However, recently +accessed pages are cached so that these page reads can be amortized across +many block name requests. + +The volume index and the chapter indexes are implemented using a +memory-efficient structure called a delta index. Instead of storing the +entire block name (the key) for each entry, the entries are sorted by name +and only the difference between adjacent keys (the delta) is stored. +Because we expect the hashes to be randomly distributed, the size of the +deltas follows an exponential distribution. Because of this distribution, +the deltas are expressed using a Huffman code to take up even less space. +The entire sorted list of keys is called a delta list. This structure +allows the index to use many fewer bytes per entry than a traditional hash +table, but it is slightly more expensive to look up entries, because a +request must read every entry in a delta list to add up the deltas in order +to find the record it needs. The delta index reduces this lookup cost by +splitting its key space into many sub-lists, each starting at a fixed key +value, so that each individual list is short. + +The default index size can hold 64 million records, corresponding to about +256GB of data. This means that the index can identify duplicate data if the +original data was written within the last 256GB of writes. This range is +called the deduplication window. If new writes duplicate data that is older +than that, the index will not be able to find it because the records of the +older data have been removed. This means that if an application writes a +200 GB file to a vdo target and then immediately writes it again, the two +copies will deduplicate perfectly. Doing the same with a 500 GB file will +result in no deduplication, because the beginning of the file will no +longer be in the index by the time the second write begins (assuming there +is no duplication within the file itself). + +If an application anticipates a data workload that will see useful +deduplication beyond the 256GB threshold, vdo can be configured to use a +larger index with a correspondingly larger deduplication window. (This +configuration can only be set when the target is created, not altered +later. It is important to consider the expected workload for a vdo target +before configuring it.) There are two ways to do this. + +One way is to increase the memory size of the index, which also increases +the amount of backing storage required. Doubling the size of the index will +double the length of the deduplication window at the expense of doubling +the storage size and the memory requirements. + +The other option is to enable sparse indexing. Sparse indexing increases +the deduplication window by a factor of 10, at the expense of also +increasing the storage size by a factor of 10. However with sparse +indexing, the memory requirements do not increase. The trade-off is +slightly more computation per request and a slight decrease in the amount +of deduplication detected. For most workloads with significant amounts of +duplicate data, sparse indexing will detect 97-99% of the deduplication +that a standard index will detect. + +The vio and data_vio Structures +------------------------------- + +A vio (short for Vdo I/O) is conceptually similar to a bio, with additional +fields and data to track vdo-specific information. A struct vio maintains a +pointer to a bio but also tracks other fields specific to the operation of +vdo. The vio is kept separate from its related bio because there are many +circumstances where vdo completes the bio but must continue to do work +related to deduplication or compression. + +Metadata reads and writes, and other writes that originate within vdo, use +a struct vio directly. Application reads and writes use a larger structure +called a data_vio to track information about their progress. A struct +data_vio contain a struct vio and also includes several other fields +related to deduplication and other vdo features. The data_vio is the +primary unit of application work in vdo. Each data_vio proceeds through a +set of steps to handle the application data, after which it is reset and +returned to a pool of data_vios for reuse. + +There is a fixed pool of 2048 data_vios. This number was chosen to bound +the amount of work that is required to recover from a crash. In addition, +benchmarks have indicated that increasing the size of the pool does not +significantly improve performance. + +The Data Store +-------------- + +The data store is implemented by three main data structures, all of which +work in concert to reduce or amortize metadata updates across as many data +writes as possible. + +*The Slab Depot* + +Most of the vdo volume belongs to the slab depot. The depot contains a +collection of slabs. The slabs can be up to 32GB, and are divided into +three sections. Most of a slab consists of a linear sequence of 4K blocks. +These blocks are used either to store data, or to hold portions of the +block map (see below). In addition to the data blocks, each slab has a set +of reference counters, using 1 byte for each data block. Finally each slab +has a journal. + +Reference updates are written to the slab journal. Slab journal blocks are +written out either when they are full, or when the recovery journal +requests they do so in order to allow the main recovery journal (see below) +to free up space. The slab journal is used both to ensure that the main +recovery journal can regularly free up space, and also to amortize the cost +of updating individual reference blocks. The reference counters are kept in +memory and are written out, a block at a time in oldest-dirtied-order, only +when there is a need to reclaim slab journal space. The write operations +are performed in the background as needed so they do not add latency to +particular I/O operations. + +Each slab is independent of every other. They are assigned to "physical +zones" in round-robin fashion. If there are P physical zones, then slab n +is assigned to zone n mod P. + +The slab depot maintains an additional small data structure, the "slab +summary," which is used to reduce the amount of work needed to come back +online after a crash. The slab summary maintains an entry for each slab +indicating whether or not the slab has ever been used, whether all of its +reference count updates have been persisted to storage, and approximately +how full it is. During recovery, each physical zone will attempt to recover +at least one slab, stopping whenever it has recovered a slab which has some +free blocks. Once each zone has some space, or has determined that none is +available, the target can resume normal operation in a degraded mode. Read +and write requests can be serviced, perhaps with degraded performance, +while the remainder of the dirty slabs are recovered. + +*The Block Map* + +The block map contains the logical to physical mapping. It can be thought +of as an array with one entry per logical address. Each entry is 5 bytes, +36 bits of which contain the physical block number which holds the data for +the given logical address. The other 4 bits are used to indicate the nature +of the mapping. Of the 16 possible states, one represents a logical address +which is unmapped (i.e. it has never been written, or has been discarded), +one represents an uncompressed block, and the other 14 states are used to +indicate that the mapped data is compressed, and which of the compression +slots in the compressed block contains the data for this logical address. + +In practice, the array of mapping entries is divided into "block map +pages," each of which fits in a single 4K block. Each block map page +consists of a header and 812 mapping entries. Each mapping page is actually +a leaf of a radix tree which consists of block map pages at each level. +There are 60 radix trees which are assigned to "logical zones" in round +robin fashion. (If there are L logical zones, tree n will belong to zone n +mod L.) At each level, the trees are interleaved, so logical addresses +0-811 belong to tree 0, logical addresses 812-1623 belong to tree 1, and so +on. The interleaving is maintained all the way up to the 60 root nodes. +Choosing 60 trees results in an evenly distributed number of trees per zone +for a large number of possible logical zone counts. The storage for the 60 +tree roots is allocated at format time. All other block map pages are +allocated out of the slabs as needed. This flexible allocation avoids the +need to pre-allocate space for the entire set of logical mappings and also +makes growing the logical size of a vdo relatively easy. + +In operation, the block map maintains two caches. It is prohibitive to keep +the entire leaf level of the trees in memory, so each logical zone +maintains its own cache of leaf pages. The size of this cache is +configurable at target start time. The second cache is allocated at start +time, and is large enough to hold all the non-leaf pages of the entire +block map. This cache is populated as pages are needed. + +*The Recovery Journal* + +The recovery journal is used to amortize updates across the block map and +slab depot. Each write request causes an entry to be made in the journal. +Entries are either "data remappings" or "block map remappings." For a data +remapping, the journal records the logical address affected and its old and +new physical mappings. For a block map remapping, the journal records the +block map page number and the physical block allocated for it. Block map +pages are never reclaimed or repurposed, so the old mapping is always 0. + +Each journal entry is an intent record summarizing the metadata updates +that are required for a data_vio. The recovery journal issues a flush +before each journal block write to ensure that the physical data for the +new block mappings in that block are stable on storage, and journal block +writes are all issued with the FUA bit set to ensure the recovery journal +entries themselves are stable. The journal entry and the data write it +represents must be stable on disk before the other metadata structures may +be updated to reflect the operation. These entries allow the vdo device to +reconstruct the logical to physical mappings after an unexpected +interruption such as a loss of power. + +*Write Path* + +All write I/O to vdo is asynchronous. Each bio will be acknowledged as soon +as vdo has done enough work to guarantee that it can complete the write +eventually. Generally, the data for acknowledged but unflushed write I/O +can be treated as though it is cached in memory. If an application +requires data to be stable on storage, it must issue a flush or write the +data with the FUA bit set like any other asynchronous I/O. Shutting down +the vdo target will also flush any remaining I/O. + +Application write bios follow the steps outlined below. + +1. A data_vio is obtained from the data_vio pool and associated with the + application bio. If there are no data_vios available, the incoming bio + will block until a data_vio is available. This provides back pressure + to the application. The data_vio pool is protected by a spin lock. + + The newly acquired data_vio is reset and the bio's data is copied into + the data_vio if it is a write and the data is not all zeroes. The data + must be copied because the application bio can be acknowledged before + the data_vio processing is complete, which means later processing steps + will no longer have access to the application bio. The application bio + may also be smaller than 4K, in which case the data_vio will have + already read the underlying block and the data is instead copied over + the relevant portion of the larger block. + +2. The data_vio places a claim (the "logical lock") on the logical address + of the bio. It is vital to prevent simultaneous modifications of the + same logical address, because deduplication involves sharing blocks. + This claim is implemented as an entry in a hashtable where the key is + the logical address and the value is a pointer to the data_vio + currently handling that address. + + If a data_vio looks in the hashtable and finds that another data_vio is + already operating on that logical address, it waits until the previous + operation finishes. It also sends a message to inform the current + lock holder that it is waiting. Most notably, a new data_vio waiting + for a logical lock will flush the previous lock holder out of the + compression packer (step 8d) rather than allowing it to continue + waiting to be packed. + + This stage requires the data_vio to get an implicit lock on the + appropriate logical zone to prevent concurrent modifications of the + hashtable. This implicit locking is handled by the zone divisions + described above. + +3. The data_vio traverses the block map tree to ensure that all the + necessary internal tree nodes have been allocated, by trying to find + the leaf page for its logical address. If any interior tree page is + missing, it is allocated at this time out of the same physical storage + pool used to store application data. + + a. If any page-node in the tree has not yet been allocated, it must be + allocated before the write can continue. This step requires the + data_vio to lock the page-node that needs to be allocated. This + lock, like the logical block lock in step 2, is a hashtable entry + that causes other data_vios to wait for the allocation process to + complete. + + The implicit logical zone lock is released while the allocation is + happening, in order to allow other operations in the same logical + zone to proceed. The details of allocation are the same as in + step 4. Once a new node has been allocated, that node is added to + the tree using a similar process to adding a new data block mapping. + The data_vio journals the intent to add the new node to the block + map tree (step 10), updates the reference count of the new block + (step 11), and reacquires the implicit logical zone lock to add the + new mapping to the parent tree node (step 12). Once the tree is + updated, the data_vio proceeds down the tree. Any other data_vios + waiting on this allocation also proceed. + + b. In the steady-state case, the block map tree nodes will already be + allocated, so the data_vio just traverses the tree until it finds + the required leaf node. The location of the mapping (the "block map + slot") is recorded in the data_vio so that later steps do not need + to traverse the tree again. The data_vio then releases the implicit + logical zone lock. + +4. If the block is a zero block, skip to step 9. Otherwise, an attempt is + made to allocate a free data block. This allocation ensures that the + data_vio can write its data somewhere even if deduplication and + compression are not possible. This stage gets an implicit lock on a + physical zone to search for free space within that zone. + + The data_vio will search each slab in a zone until it finds a free + block or decides there are none. If the first zone has no free space, + it will proceed to search the next physical zone by taking the implicit + lock for that zone and releasing the previous one until it finds a + free block or runs out of zones to search. The data_vio will acquire a + struct pbn_lock (the "physical block lock") on the free block. The + struct pbn_lock also has several fields to record the various kinds of + claims that data_vios can have on physical blocks. The pbn_lock is + added to a hashtable like the logical block locks in step 2. This + hashtable is also covered by the implicit physical zone lock. The + reference count of the free block is updated to prevent any other + data_vio from considering it free. The reference counters are a + sub-component of the slab and are thus also covered by the implicit + physical zone lock. + +5. If an allocation was obtained, the data_vio has all the resources it + needs to complete the write. The application bio can safely be + acknowledged at this point. The acknowledgment happens on a separate + thread to prevent the application callback from blocking other data_vio + operations. + + If an allocation could not be obtained, the data_vio continues to + attempt to deduplicate or compress the data, but the bio is not + acknowledged because the vdo device may be out of space. + +6. At this point vdo must determine where to store the application data. + The data_vio's data is hashed and the hash (the "record name") is + recorded in the data_vio. + +7. The data_vio reserves or joins a struct hash_lock, which manages all of + the data_vios currently writing the same data. Active hash locks are + tracked in a hashtable similar to the way logical block locks are + tracked in step 2. This hashtable is covered by the implicit lock on + the hash zone. + + If there is no existing hash lock for this data_vio's record_name, the + data_vio obtains a hash lock from the pool, adds it to the hashtable, + and sets itself as the new hash lock's "agent." The hash_lock pool is + also covered by the implicit hash zone lock. The hash lock agent will + do all the work to decide where the application data will be + written. If a hash lock for the data_vio's record_name already exists, + and the data_vio's data is the same as the agent's data, the new + data_vio will wait for the agent to complete its work and then share + its result. + + In the rare case that a hash lock exists for the data_vio's hash but + the data does not match the hash lock's agent, the data_vio skips to + step 8h and attempts to write its data directly. This can happen if two + different data blocks produce the same hash, for example. + +8. The hash lock agent attempts to deduplicate or compress its data with + the following steps. + + a. The agent initializes and sends its embedded deduplication request + (struct uds_request) to the deduplication index. This does not + require the data_vio to get any locks because the index components + manage their own locking. The data_vio waits until it either gets a + response from the index or times out. + + b. If the deduplication index returns advice, the data_vio attempts to + obtain a physical block lock on the indicated physical address, in + order to read the data and verify that it is the same as the + data_vio's data, and that it can accept more references. If the + physical address is already locked by another data_vio, the data at + that address may soon be overwritten so it is not safe to use the + address for deduplication. + + c. If the data matches and the physical block can add references, the + agent and any other data_vios waiting on it will record this + physical block as their new physical address and proceed to step 9 + to record their new mapping. If there are more data_vios in the hash + lock than there are references available, one of the remaining + data_vios becomes the new agent and continues to step 8d as if no + valid advice was returned. + + d. If no usable duplicate block was found, the agent first checks that + it has an allocated physical block (from step 3) that it can write + to. If the agent does not have an allocation, some other data_vio in + the hash lock that does have an allocation takes over as agent. If + none of the data_vios have an allocated physical block, these writes + are out of space, so they proceed to step 13 for cleanup. + + e. The agent attempts to compress its data. If the data does not + compress, the data_vio will continue to step 8h to write its data + directly. + + If the compressed size is small enough, the agent will release the + implicit hash zone lock and go to the packer (struct packer) where + it will be placed in a bin (struct packer_bin) along with other + data_vios. All compression operations require the implicit lock on + the packer zone. + + The packer can combine up to 14 compressed blocks in a single 4k + data block. Compression is only helpful if vdo can pack at least 2 + data_vios into a single data block. This means that a data_vio may + wait in the packer for an arbitrarily long time for other data_vios + to fill out the compressed block. There is a mechanism for vdo to + evict waiting data_vios when continuing to wait would cause + problems. Circumstances causing an eviction include an application + flush, device shutdown, or a subsequent data_vio trying to overwrite + the same logical block address. A data_vio may also be evicted from + the packer if it cannot be paired with any other compressed block + before more compressible blocks need to use its bin. An evicted + data_vio will proceed to step 8h to write its data directly. + + f. If the agent fills a packer bin, either because all 14 of its slots + are used or because it has no remaining space, it is written out + using the allocated physical block from one of its data_vios. Step + 8d has already ensured that an allocation is available. + + g. Each data_vio sets the compressed block as its new physical address. + The data_vio obtains an implicit lock on the physical zone and + acquires the struct pbn_lock for the compressed block, which is + modified to be a shared lock. Then it releases the implicit physical + zone lock and proceeds to step 8i. + + h. Any data_vio evicted from the packer will have an allocation from + step 3. It will write its data to that allocated physical block. + + i. After the data is written, if the data_vio is the agent of a hash + lock, it will reacquire the implicit hash zone lock and share its + physical address with as many other data_vios in the hash lock as + possible. Each data_vio will then proceed to step 9 to record its + new mapping. + + j. If the agent actually wrote new data (whether compressed or not), + the deduplication index is updated to reflect the location of the + new data. The agent then releases the implicit hash zone lock. + +9. The data_vio determines the previous mapping of the logical address. + There is a cache for block map leaf pages (the "block map cache"), + because there are usually too many block map leaf nodes to store + entirely in memory. If the desired leaf page is not in the cache, the + data_vio will reserve a slot in the cache and load the desired page + into it, possibly evicting an older cached page. The data_vio then + finds the current physical address for this logical address (the "old + physical mapping"), if any, and records it. This step requires a lock + on the block map cache structures, covered by the implicit logical zone + lock. + +10. The data_vio makes an entry in the recovery journal containing the + logical block address, the old physical mapping, and the new physical + mapping. Making this journal entry requires holding the implicit + recovery journal lock. The data_vio will wait in the journal until all + recovery blocks up to the one containing its entry have been written + and flushed to ensure the transaction is stable on storage. + +11. Once the recovery journal entry is stable, the data_vio makes two slab + journal entries: an increment entry for the new mapping, and a + decrement entry for the old mapping. These two operations each require + holding a lock on the affected physical slab, covered by its implicit + physical zone lock. For correctness during recovery, the slab journal + entries in any given slab journal must be in the same order as the + corresponding recovery journal entries. Therefore, if the two entries + are in different zones, they are made concurrently, and if they are in + the same zone, the increment is always made before the decrement in + order to avoid underflow. After each slab journal entry is made in + memory, the associated reference count is also updated in memory. + +12. Once both of the reference count updates are done, the data_vio + acquires the implicit logical zone lock and updates the + logical-to-physical mapping in the block map to point to the new + physical block. At this point the write operation is complete. + +13. If the data_vio has a hash lock, it acquires the implicit hash zone + lock and releases its hash lock to the pool. + + The data_vio then acquires the implicit physical zone lock and releases + the struct pbn_lock it holds for its allocated block. If it had an + allocation that it did not use, it also sets the reference count for + that block back to zero to free it for use by subsequent data_vios. + + The data_vio then acquires the implicit logical zone lock and releases + the logical block lock acquired in step 2. + + The application bio is then acknowledged if it has not previously been + acknowledged, and the data_vio is returned to the pool. + +*Read Path* + +An application read bio follows a much simpler set of steps. It does steps +1 and 2 in the write path to obtain a data_vio and lock its logical +address. If there is already a write data_vio in progress for that logical +address that is guaranteed to complete, the read data_vio will copy the +data from the write data_vio and return it. Otherwise, it will look up the +logical-to-physical mapping by traversing the block map tree as in step 3, +and then read and possibly decompress the indicated data at the indicated +physical block address. A read data_vio will not allocate block map tree +nodes if they are missing. If the interior block map nodes do not exist +yet, the logical block map address must still be unmapped and the read +data_vio will return all zeroes. A read data_vio handles cleanup and +acknowledgment as in step 13, although it only needs to release the logical +lock and return itself to the pool. + +*Small Writes* + +All storage within vdo is managed as 4KB blocks, but it can accept writes +as small as 512 bytes. Processing a write that is smaller than 4K requires +a read-modify-write operation that reads the relevant 4K block, copies the +new data over the approriate sectors of the block, and then launches a +write operation for the modified data block. The read and write stages of +this operation are nearly identical to the normal read and write +operations, and a single data_vio is used throughout this operation. + +*Recovery* + +When a vdo is restarted after a crash, it will attempt to recover from the +recovery journal. During the pre-resume phase of the next start, the +recovery journal is read. The increment portion of valid entries are played +into the block map. Next, valid entries are played, in order as required, +into the slab journals. Finally, each physical zone attempts to replay at +least one slab journal to reconstruct the reference counts of one slab. +Once each zone has some free space (or has determined that it has none), +the vdo comes back online, while the remainder of the slab journals are +used to reconstruct the rest of the reference counts in the background. + +*Read-only Rebuild* + +If a vdo encounters an unrecoverable error, it will enter read-only mode. +This mode indicates that some previously acknowledged data may have been +lost. The vdo may be instructed to rebuild as best it can in order to +return to a writable state. However, this is never done automatically due +to the possibility that data has been lost. During a read-only rebuild, the +block map is recovered from the recovery journal as before. However, the +reference counts are not rebuilt from the slab journals. Instead, the +reference counts are zeroed, the entire block map is traversed, and the +reference counts are updated from the block mappings. While this may lose +some data, it ensures that the block map and reference counts are +consistent with each other. This allows vdo to resume normal operation and +accept further writes. diff --git a/Documentation/admin-guide/device-mapper/vdo.rst b/Documentation/admin-guide/device-mapper/vdo.rst new file mode 100644 index 00000000000000..a199009979d993 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/vdo.rst @@ -0,0 +1,388 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +dm-vdo +====== + +The dm-vdo (virtual data optimizer) device mapper target provides +block-level deduplication, compression, and thin provisioning. As a device +mapper target, it can add these features to the storage stack, compatible +with any file system. The vdo target does not protect against data +corruption, relying instead on integrity protection of the storage below +it. It is strongly recommended that lvm be used to manage vdo volumes. See +lvmvdo(7). + +Userspace component +=================== + +Formatting a vdo volume requires the use of the 'vdoformat' tool, available +at: + +https://github.com/dm-vdo/vdo/ + +In most cases, a vdo target will recover from a crash automatically the +next time it is started. In cases where it encountered an unrecoverable +error (either during normal operation or crash recovery) the target will +enter or come up in read-only mode. Because read-only mode is indicative of +data-loss, a positive action must be taken to bring vdo out of read-only +mode. The 'vdoforcerebuild' tool, available from the same repo, is used to +prepare a read-only vdo to exit read-only mode. After running this tool, +the vdo target will rebuild its metadata the next time it is +started. Although some data may be lost, the rebuilt vdo's metadata will be +internally consistent and the target will be writable again. + +The repo also contains additional userspace tools which can be used to +inspect a vdo target's on-disk metadata. Fortunately, these tools are +rarely needed except by dm-vdo developers. + +Target interface +================ + +Table line +---------- + +:: + + vdo V4 + + [optional arguments] + + +Required parameters: + + offset: + The offset, in sectors, at which the vdo volume's logical + space begins. + + logical device size: + The size of the device which the vdo volume will service, + in sectors. Must match the current logical size of the vdo + volume. + + storage device: + The device holding the vdo volume's data and metadata. + + storage device size: + The size of the device holding the vdo volume, as a number + of 4096-byte blocks. Must match the current size of the vdo + volume. + + minimum I/O size: + The minimum I/O size for this vdo volume to accept, in + bytes. Valid values are 512 or 4096. The recommended value + is 4096. + + block map cache size: + The size of the block map cache, as a number of 4096-byte + blocks. The minimum and recommended value is 32768 blocks. + If the logical thread count is non-zero, the cache size + must be at least 4096 blocks per logical thread. + + block map era length: + The speed with which the block map cache writes out + modified block map pages. A smaller era length is likely to + reduce the amount of time spent rebuilding, at the cost of + increased block map writes during normal operation. The + maximum and recommended value is 16380; the minimum value + is 1. + +Optional parameters: +-------------------- +Some or all of these parameters may be specified as pairs. + +Thread related parameters: + +Different categories of work are assigned to separate thread groups, and +the number of threads in each group can be configured separately. + +If , , and are all set to 0, the work handled by +all three thread types will be handled by a single thread. If any of these +values are non-zero, all of them must be non-zero. + + ack: + The number of threads used to complete bios. Since + completing a bio calls an arbitrary completion function + outside the vdo volume, threads of this type allow the vdo + volume to continue processing requests even when bio + completion is slow. The default is 1. + + bio: + The number of threads used to issue bios to the underlying + storage. Threads of this type allow the vdo volume to + continue processing requests even when bio submission is + slow. The default is 4. + + bioRotationInterval: + The number of bios to enqueue on each bio thread before + switching to the next thread. The value must be greater + than 0 and not more than 1024; the default is 64. + + cpu: + The number of threads used to do CPU-intensive work, such + as hashing and compression. The default is 1. + + hash: + The number of threads used to manage data comparisons for + deduplication based on the hash value of data blocks. The + default is 0. + + logical: + The number of threads used to manage caching and locking + based on the logical address of incoming bios. The default + is 0; the maximum is 60. + + physical: + The number of threads used to manage administration of the + underlying storage device. At format time, a slab size for + the vdo is chosen; the vdo storage device must be large + enough to have at least 1 slab per physical thread. The + default is 0; the maximum is 16. + +Miscellaneous parameters: + + maxDiscard: + The maximum size of discard bio accepted, in 4096-byte + blocks. I/O requests to a vdo volume are normally split + into 4096-byte blocks, and processed up to 2048 at a time. + However, discard requests to a vdo volume can be + automatically split to a larger size, up to + 4096-byte blocks in a single bio, and are limited to 1500 + at a time. Increasing this value may provide better overall + performance, at the cost of increased latency for the + individual discard requests. The default and minimum is 1; + the maximum is UINT_MAX / 4096. + + deduplication: + Whether deduplication is enabled. The default is 'on'; the + acceptable values are 'on' and 'off'. + + compression: + Whether compression is enabled. The default is 'off'; the + acceptable values are 'on' and 'off'. + +Device modification +------------------- + +A modified table may be loaded into a running, non-suspended vdo volume. +The modifications will take effect when the device is next resumed. The +modifiable parameters are , , +, , and . + +If the logical device size or physical device size are changed, upon +successful resume vdo will store the new values and require them on future +startups. These two parameters may not be decreased. The logical device +size may not exceed 4 PB. The physical device size must increase by at +least 32832 4096-byte blocks if at all, and must not exceed the size of the +underlying storage device. Additionally, when formatting the vdo device, a +slab size is chosen: the physical device size may never increase above the +size which provides 8192 slabs, and each increase must be large enough to +add at least one new slab. + +Examples: + +Start a previously-formatted vdo volume with 1 GB logical space and 1 GB +physical space, storing to /dev/dm-1 which has more than 1 GB of space. + +:: + + dmsetup create vdo0 --table \ + "0 2097152 vdo V4 /dev/dm-1 262144 4096 32768 16380" + +Grow the logical size to 4 GB. + +:: + + dmsetup reload vdo0 --table \ + "0 8388608 vdo V4 /dev/dm-1 262144 4096 32768 16380" + dmsetup resume vdo0 + +Grow the physical size to 2 GB. + +:: + + dmsetup reload vdo0 --table \ + "0 8388608 vdo V4 /dev/dm-1 524288 4096 32768 16380" + dmsetup resume vdo0 + +Grow the physical size by 1 GB more and increase max discard sectors. + +:: + + dmsetup reload vdo0 --table \ + "0 10485760 vdo V4 /dev/dm-1 786432 4096 32768 16380 maxDiscard 8" + dmsetup resume vdo0 + +Stop the vdo volume. + +:: + + dmsetup remove vdo0 + +Start the vdo volume again. Note that the logical and physical device sizes +must still match, but other parameters can change. + +:: + + dmsetup create vdo1 --table \ + "0 10485760 vdo V4 /dev/dm-1 786432 512 65550 5000 hash 1 logical 3 physical 2" + +Messages +-------- +All vdo devices accept messages in the form: + +:: + dmsetup message 0 + +The messages are: + + stats: + Outputs the current view of the vdo statistics. Mostly used + by the vdostats userspace program to interpret the output + buffer. + + dump: + Dumps many internal structures to the system log. This is + not always safe to run, so it should only be used to debug + a hung vdo. Optional parameters to specify structures to + dump are: + + viopool: The pool of I/O requests incoming bios + pools: A synonym of 'viopool' + vdo: Most of the structures managing on-disk data + queues: Basic information about each vdo thread + threads: A synonym of 'queues' + default: Equivalent to 'queues vdo' + all: All of the above. + + dump-on-shutdown: + Perform a default dump next time vdo shuts down. + + +Status +------ + +:: + + + + + device: + The name of the vdo volume. + + operating mode: + The current operating mode of the vdo volume; values may be + 'normal', 'recovering' (the volume has detected an issue + with its metadata and is attempting to repair itself), and + 'read-only' (an error has occurred that forces the vdo + volume to only support read operations and not writes). + + in recovery: + Whether the vdo volume is currently in recovery mode; + values may be 'recovering' or '-' which indicates not + recovering. + + index state: + The current state of the deduplication index in the vdo + volume; values may be 'closed', 'closing', 'error', + 'offline', 'online', 'opening', and 'unknown'. + + compression state: + The current state of compression in the vdo volume; values + may be 'offline' and 'online'. + + used physical blocks: + The number of physical blocks in use by the vdo volume. + + total physical blocks: + The total number of physical blocks the vdo volume may use; + the difference between this value and the + is the number of blocks the vdo + volume has left before being full. + +Memory Requirements +=================== + +A vdo target requires a fixed 38 MB of RAM along with the following amounts +that scale with the target: + +- 1.15 MB of RAM for each 1 MB of configured block map cache size. The + block map cache requires a minimum of 150 MB. +- 1.6 MB of RAM for each 1 TB of logical space. +- 268 MB of RAM for each 1 TB of physical storage managed by the volume. + +The deduplication index requires additional memory which scales with the +size of the deduplication window. For dense indexes, the index requires 1 +GB of RAM per 1 TB of window. For sparse indexes, the index requires 1 GB +of RAM per 10 TB of window. The index configuration is set when the target +is formatted and may not be modified. + +Run-time Usage +============== + +When using dm-vdo, it is important to be aware of the ways in which its +behavior differs from other storage targets. + +- There is no guarantee that over-writes of existing blocks will succeed. + Because the underlying storage may be multiply referenced, over-writing + an existing block generally requires a vdo to have a free block + available. + +- When blocks are no longer in use, sending a discard request for those + blocks lets the vdo release references for those blocks. If the vdo is + thinly provisioned, discarding unused blocks is essential to prevent the + target from running out of space. However, due to the sharing of + duplicate blocks, no discard request for any given logical block is + guaranteed to reclaim space. + +- Assuming the underlying storage properly implements flush requests, vdo + is resilient against crashes, however, unflushed writes may or may not + persist after a crash. + +- Each write to a vdo target entails a significant amount of processing. + However, much of the work is paralellizable. Therefore, vdo targets + achieve better throughput at higher I/O depths, and can support up 2048 + requests in parallel. + +Tuning +====== + +The vdo device has many options, and it can be difficult to make optimal +choices without perfect knowledge of the workload. Additionally, most +configuration options must be set when a vdo target is started, and cannot +be changed without shutting it down completely; the configuration cannot be +changed while the target is active. Ideally, tuning with simulated +workloads should be performed before deploying vdo in production +environments. + +The most important value to adjust is the block map cache size. In order to +service a request for any logical address, a vdo must load the portion of +the block map which holds the relevant mapping. These mappings are cached. +Performance will suffer when the working set does not fit in the cache. By +default, a vdo allocates 128 MB of metadata cache in RAM to support +efficient access to 100 GB of logical space at a time. It should be scaled +up proportionally for larger working sets. + +The logical and physical thread counts should also be adjusted. A logical +thread controls a disjoint section of the block map, so additional logical +threads increase parallelism and can increase throughput. Physical threads +control a disjoint section of the data blocks, so additional physical +threads can also increase throughput. However, excess threads can waste +resources and increase contention. + +Bio submission threads control the parallelism involved in sending I/O to +the underlying storage; fewer threads mean there is more opportunity to +reorder I/O requests for performance benefit, but also that each I/O +request has to wait longer before being submitted. + +Bio acknowledgment threads are used for finishing I/O requests. This is +done on dedicated threads since the amount of work required to execute a +bio's callback can not be controlled by the vdo itself. Usually one thread +is sufficient but additional threads may be beneficial, particularly when +bios have CPU-heavy callbacks. + +CPU threads are used for hashing and for compression; in workloads with +compression enabled, more threads may result in higher throughput. + +Hash threads are used to sort active requests by hash and determine whether +they should deduplicate; the most CPU intensive actions done by these +threads are comparison of 4096-byte data blocks. In most cases, a single +hash thread is sufficient. diff --git a/Documentation/admin-guide/gpio/gpio-mockup.rst b/Documentation/admin-guide/gpio/gpio-mockup.rst index 493071da1738c7..d6e7438a7550a9 100644 --- a/Documentation/admin-guide/gpio/gpio-mockup.rst +++ b/Documentation/admin-guide/gpio/gpio-mockup.rst @@ -3,6 +3,14 @@ GPIO Testing Driver =================== +.. note:: + + This module has been obsoleted by the more flexible gpio-sim.rst. + New developments should use that API and existing developments are + encouraged to migrate as soon as possible. + This module will continue to be maintained but no new features will be + added. + The GPIO Testing Driver (gpio-mockup) provides a way to create simulated GPIO chips for testing purposes. The lines exposed by these chips can be accessed using the standard GPIO character device interface as well as manipulated diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst index f6861ca16ffe6b..460afd29617e0d 100644 --- a/Documentation/admin-guide/gpio/index.rst +++ b/Documentation/admin-guide/gpio/index.rst @@ -1,16 +1,16 @@ .. SPDX-License-Identifier: GPL-2.0 ==== -gpio +GPIO ==== .. toctree:: :maxdepth: 1 + Character Device Userspace API <../../userspace-api/gpio/chardev> gpio-aggregator - sysfs - gpio-mockup gpio-sim + Obsolete APIs .. only:: subproject and html diff --git a/Documentation/admin-guide/gpio/obsolete.rst b/Documentation/admin-guide/gpio/obsolete.rst new file mode 100644 index 00000000000000..5adbff02d61f43 --- /dev/null +++ b/Documentation/admin-guide/gpio/obsolete.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +Obsolete GPIO APIs +================== + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1> + Sysfs Interface <../../userspace-api/gpio/sysfs> + Mockup Testing Module + diff --git a/Documentation/admin-guide/hw-vuln/spectre.rst b/Documentation/admin-guide/hw-vuln/spectre.rst index 32a8893e561776..cce768afec6bed 100644 --- a/Documentation/admin-guide/hw-vuln/spectre.rst +++ b/Documentation/admin-guide/hw-vuln/spectre.rst @@ -473,8 +473,8 @@ Spectre variant 2 -mindirect-branch=thunk-extern -mindirect-branch-register options. If the kernel is compiled with a Clang compiler, the compiler needs to support -mretpoline-external-thunk option. The kernel config - CONFIG_RETPOLINE needs to be turned on, and the CPU needs to run with - the latest updated microcode. + CONFIG_MITIGATION_RETPOLINE needs to be turned on, and the CPU needs + to run with the latest updated microcode. On Intel Skylake-era systems the mitigation covers most, but not all, cases. See :ref:`[3] ` for more details. @@ -609,8 +609,8 @@ kernel command line. Selecting 'on' will, and 'auto' may, choose a mitigation method at run time according to the CPU, the available microcode, the setting of the - CONFIG_RETPOLINE configuration option, and the - compiler with which the kernel was built. + CONFIG_MITIGATION_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. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index fb40a1f6f79e18..dfc06fab943225 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -122,7 +122,7 @@ configure specific aspects of kernel behavior to your liking. pmf pnp rapidio - ras + RAS/index rtc serial-console svga diff --git a/Documentation/admin-guide/kdump/vmcoreinfo.rst b/Documentation/admin-guide/kdump/vmcoreinfo.rst index bced9e4b6e0899..0f714fc945acf4 100644 --- a/Documentation/admin-guide/kdump/vmcoreinfo.rst +++ b/Documentation/admin-guide/kdump/vmcoreinfo.rst @@ -65,11 +65,11 @@ 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 --------------- +VMALLOC_START +------------- -Stores the virtual area list. makedumpfile gets the vmalloc start value -from this variable and its value is necessary for vmalloc translation. +Stores the base address of vmalloc area. makedumpfile gets this value +since is necessary for vmalloc translation. mem_map ------- diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 102937bc8443a2..e8bdf5e86a9ba1 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -108,6 +108,7 @@ is applicable:: CMA Contiguous Memory Area support is enabled. DRM Direct Rendering Management support is enabled. DYNAMIC_DEBUG Build in debug messages and enable them at runtime + EARLY Parameter processed too early to be embedded in initrd. EDD BIOS Enhanced Disk Drive Services (EDD) is enabled EFI EFI Partitioning (GPT) is enabled EVM Extended Verification Module @@ -218,8 +219,3 @@ bytes respectively. Such letter suffixes can also be entirely omitted: .. include:: kernel-parameters.txt :literal: - -Todo ----- - - Add more DRM drivers. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 31b3a25680d08c..460b97a1d0da65 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -9,7 +9,7 @@ accept_memory=eager can be used to accept all memory at once during boot. - acpi= [HW,ACPI,X86,ARM64,RISCV64] + acpi= [HW,ACPI,X86,ARM64,RISCV64,EARLY] Advanced Configuration and Power Interface Format: { force | on | off | strict | noirq | rsdt | copy_dsdt } @@ -26,7 +26,7 @@ See also Documentation/power/runtime_pm.rst, pci=noacpi - acpi_apic_instance= [ACPI, IOAPIC] + acpi_apic_instance= [ACPI,IOAPIC,EARLY] Format: 2: use 2nd APIC table, if available 1,0: use 1st APIC table @@ -41,7 +41,7 @@ If set to native, use the device's native backlight mode. If set to none, disable the ACPI backlight interface. - acpi_force_32bit_fadt_addr + acpi_force_32bit_fadt_addr [ACPI,EARLY] force FADT to use 32 bit addresses rather than the 64 bit X_* addresses. Some firmware have broken 64 bit addresses for force ACPI ignore these and use @@ -97,7 +97,7 @@ no: ACPI OperationRegions are not marked as reserved, no further checks are performed. - acpi_force_table_verification [HW,ACPI] + acpi_force_table_verification [HW,ACPI,EARLY] Enable table checksum verification during early stage. By default, this is disabled due to x86 early mapping size limitation. @@ -137,7 +137,7 @@ acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump kernels. - acpi_no_static_ssdt [HW,ACPI] + acpi_no_static_ssdt [HW,ACPI,EARLY] Disable installation of static SSDTs at early boot time By default, SSDTs contained in the RSDT/XSDT will be installed automatically and they will appear under @@ -151,7 +151,7 @@ Ignore the ACPI-based watchdog interface (WDAT) and let a native driver control the watchdog device instead. - acpi_rsdp= [ACPI,EFI,KEXEC] + acpi_rsdp= [ACPI,EFI,KEXEC,EARLY] Pass the RSDP address to the kernel, mostly used on machines running EFI runtime service to boot the second kernel for kdump. @@ -228,10 +228,10 @@ to assume that this machine's pmtimer latches its value and always returns good values. - acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode + acpi_sci= [HW,ACPI,EARLY] ACPI System Control Interrupt trigger mode Format: { level | edge | high | low } - acpi_skip_timer_override [HW,ACPI] + acpi_skip_timer_override [HW,ACPI,EARLY] Recognize and ignore IRQ0/pin2 Interrupt Override. For broken nForce2 BIOS resulting in XT-PIC timer. @@ -266,11 +266,11 @@ behave incorrectly in some ways with respect to system suspend and resume to be ignored (use wisely). - acpi_use_timer_override [HW,ACPI] + acpi_use_timer_override [HW,ACPI,EARLY] Use timer override. For some broken Nvidia NF5 boards that require a timer override, but don't have HPET - add_efi_memmap [EFI; X86] Include EFI memory map in + add_efi_memmap [EFI,X86,EARLY] Include EFI memory map in kernel's map of available physical RAM. agp= [AGP] @@ -307,7 +307,7 @@ do not want to use tracing_snapshot_alloc() as it needs to be done where GFP_KERNEL allocations are allowed. - allow_mismatched_32bit_el0 [ARM64] + allow_mismatched_32bit_el0 [ARM64,EARLY] Allow execve() of 32-bit applications and setting of the PER_LINUX32 personality on systems where only a strict subset of the CPUs support 32-bit EL0. When this @@ -351,7 +351,7 @@ This mode requires kvm-amd.avic=1. (Default when IOMMU HW support is present.) - amd_pstate= [X86] + amd_pstate= [X86,EARLY] disable Do not enable amd_pstate as the default scaling driver for the supported processors @@ -374,6 +374,11 @@ selects a performance level in this range and appropriate to the current workload. + amd_prefcore= + [X86] + disable + Disable amd-pstate preferred core. + amijoy.map= [HW,JOY] Amiga joystick support Map of devices attached to JOY0DAT and JOY1DAT Format: , @@ -391,7 +396,7 @@ not play well with APC CPU idle - disable it if you have APC and your system crashes randomly. - apic= [APIC,X86] Advanced Programmable Interrupt Controller + apic= [APIC,X86,EARLY] Advanced Programmable Interrupt Controller Change the output verbosity while booting Format: { quiet (default) | verbose | debug } Change the amount of debugging information output @@ -401,7 +406,7 @@ Format: apic=driver_name Examples: apic=bigsmp - apic_extnmi= [APIC,X86] External NMI delivery setting + apic_extnmi= [APIC,X86,EARLY] External NMI delivery setting Format: { bsp (default) | all | none } bsp: External NMI is delivered only to CPU 0 all: External NMIs are broadcast to all CPUs as a @@ -508,21 +513,22 @@ bert_disable [ACPI] Disable BERT OS support on buggy BIOSes. - bgrt_disable [ACPI][X86] + bgrt_disable [ACPI,X86,EARLY] Disable BGRT to avoid flickering OEM logo. blkdevparts= Manual partition parsing of block device(s) for embedded devices based on command line input. See Documentation/block/cmdline-partition.rst - boot_delay= Milliseconds to delay each printk during boot. + boot_delay= [KNL,EARLY] + Milliseconds to delay each printk during boot. Only works if CONFIG_BOOT_PRINTK_DELAY is enabled, and you may also have to specify "lpj=". Boot_delay values larger than 10 seconds (10000) are assumed erroneous and ignored. Format: integer - bootconfig [KNL] + bootconfig [KNL,EARLY] Extended command line options can be added to an initrd and this will cause the kernel to look for it. @@ -557,7 +563,7 @@ trust validation. format: { id: | builtin } - cca= [MIPS] Override the kernel pages' cache coherency + cca= [MIPS,EARLY] Override the kernel pages' cache coherency algorithm. Accepted values range from 0 to 7 inclusive. See arch/mips/include/asm/pgtable-bits.h for platform specific values (SB1, Loongson3 and @@ -672,7 +678,7 @@ [X86-64] hpet,tsc clocksource.arm_arch_timer.evtstrm= - [ARM,ARM64] + [ARM,ARM64,EARLY] Format: Enable/disable the eventstream feature of the ARM architected timer so that code using WFE-based polling @@ -702,7 +708,7 @@ 10 seconds when built into the kernel. cma=nn[MG]@[start[MG][-end[MG]]] - [KNL,CMA] + [KNL,CMA,EARLY] Sets the size of kernel global memory area for contiguous memory allocations and optionally the placement constraint by the physical address range of @@ -711,7 +717,7 @@ kernel/dma/contiguous.c cma_pernuma=nn[MG] - [KNL,CMA] + [KNL,CMA,EARLY] Sets the size of kernel per-numa memory area for contiguous memory allocations. A value of 0 disables per-numa CMA altogether. And If this option is not @@ -722,7 +728,7 @@ they will fallback to the global default memory area. numa_cma=:nn[MG][,:nn[MG]] - [KNL,CMA] + [KNL,CMA,EARLY] Sets the size of kernel numa memory area for contiguous memory allocations. It will reserve CMA area for the specified node. @@ -739,7 +745,7 @@ a hypervisor. Default: yes - coherent_pool=nn[KMG] [ARM,KNL] + coherent_pool=nn[KMG] [ARM,KNL,EARLY] Sets the size of memory pool for coherent, atomic dma allocations, by default set to 256K. @@ -757,7 +763,7 @@ condev= [HW,S390] console device conmode= - con3215_drop= [S390] 3215 console drop mode. + con3215_drop= [S390,EARLY] 3215 console drop mode. Format: y|n|Y|N|1|0 When set to true, drop data on the 3215 console when the console buffer is full. In this case the @@ -863,7 +869,7 @@ kernel before the cpufreq driver probes. cpu_init_udelay=N - [X86] Delay for N microsec between assert and de-assert + [X86,EARLY] Delay for N microsec between assert and de-assert of APIC INIT to start processors. This delay occurs on every CPU online, such as boot, and resume from suspend. Default: 10000 @@ -883,7 +889,7 @@ kernel more unstable. crashkernel=size[KMG][@offset[KMG]] - [KNL] Using kexec, Linux can switch to a 'crash kernel' + [KNL,EARLY] Using kexec, Linux can switch to a 'crash kernel' upon panic. This parameter reserves the physical memory region [offset, offset + size] for that kernel image. If '@offset' is omitted, then a suitable offset @@ -954,10 +960,10 @@ Format: , See also Documentation/input/devices/joystick-parport.rst - debug [KNL] Enable kernel debugging (events log level). + debug [KNL,EARLY] Enable kernel debugging (events log level). debug_boot_weak_hash - [KNL] Enable printing [hashed] pointers early in the + [KNL,EARLY] Enable printing [hashed] pointers early in the boot sequence. If enabled, we use a weak hash instead of siphash to hash pointers. Use this option if you are seeing instances of '(___ptrval___)') and need to see a @@ -974,10 +980,10 @@ will print _a_lot_ more information - normally only useful to lockdep developers. - debug_objects [KNL] Enable object debugging + debug_objects [KNL,EARLY] Enable object debugging debug_guardpage_minorder= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + [KNL,EARLY] When CONFIG_DEBUG_PAGEALLOC is set, this parameter allows control of the order of pages that will be intentionally kept free (and hence protected) by the buddy allocator. Bigger value increase the probability @@ -996,7 +1002,7 @@ help tracking down these problems. debug_pagealloc= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this parameter + [KNL,EARLY] When CONFIG_DEBUG_PAGEALLOC is set, this parameter enables the feature at boot time. By default, it is disabled and the system will work mostly the same as a kernel built without CONFIG_DEBUG_PAGEALLOC. @@ -1004,8 +1010,8 @@ useful to also enable the page_owner functionality. on: enable the feature - debugfs= [KNL] This parameter enables what is exposed to userspace - and debugfs internal clients. + debugfs= [KNL,EARLY] This parameter enables what is exposed to + userspace and debugfs internal clients. Format: { on, no-mount, off } on: All functions are enabled. no-mount: @@ -1084,7 +1090,7 @@ dhash_entries= [KNL] Set number of hash buckets for dentry cache. - disable_1tb_segments [PPC] + disable_1tb_segments [PPC,EARLY] Disables the use of 1TB hash page table segments. This causes the kernel to fall back to 256MB segments which can be useful when debugging issues that require an SLB @@ -1093,7 +1099,7 @@ disable= [IPV6] See Documentation/networking/ipv6.rst. - disable_radix [PPC] + disable_radix [PPC,EARLY] Disable RADIX MMU mode on POWER9 disable_tlbie [PPC] @@ -1109,25 +1115,25 @@ causing system reset or hang due to sending INIT from AP to BSP. - disable_ddw [PPC/PSERIES] + disable_ddw [PPC/PSERIES,EARLY] Disable Dynamic DMA Window support. Use this to workaround buggy firmware. disable_ipv6= [IPV6] See Documentation/networking/ipv6.rst. - disable_mtrr_cleanup [X86] + disable_mtrr_cleanup [X86,EARLY] The kernel tries to adjust MTRR layout from continuous to discrete, to make X server driver able to add WB entry later. This parameter disables that. - disable_mtrr_trim [X86, Intel and AMD only] + disable_mtrr_trim [X86, Intel and AMD only,EARLY] By default the kernel will trim any uncacheable memory out of your available memory pool based on MTRR settings. This parameter disables that behavior, possibly causing your machine to run very slowly. - disable_timer_pin_1 [X86] + disable_timer_pin_1 [X86,EARLY] Disable PIN 1 of APIC timer Can be useful to work around chipset bugs. @@ -1177,7 +1183,7 @@ dscc4.setup= [NET] - dt_cpu_ftrs= [PPC] + dt_cpu_ftrs= [PPC,EARLY] Format: {"off" | "known"} Control how the dt_cpu_ftrs device-tree binding is used for CPU feature discovery and setup (if it @@ -1197,12 +1203,12 @@ Documentation/admin-guide/dynamic-debug-howto.rst for details. - early_ioremap_debug [KNL] + early_ioremap_debug [KNL,EARLY] Enable debug messages in early_ioremap support. This is useful for tracking down temporary early mappings which are not unmapped. - earlycon= [KNL] Output early console device and options. + earlycon= [KNL,EARLY] Output early console device and options. When used with no options, the early console is determined by stdout-path property in device tree's @@ -1338,7 +1344,7 @@ address must be provided, and the serial port must already be setup and configured. - earlyprintk= [X86,SH,ARM,M68k,S390] + earlyprintk= [X86,SH,ARM,M68k,S390,UM,EARLY] earlyprintk=vga earlyprintk=sclp earlyprintk=xen @@ -1396,7 +1402,7 @@ edd= [EDD] Format: {"off" | "on" | "skip[mbr]"} - efi= [EFI] + efi= [EFI,EARLY] Format: { "debug", "disable_early_pci_dma", "nochunk", "noruntime", "nosoftreserve", "novamap", "no_disable_early_pci_dma" } @@ -1417,13 +1423,13 @@ no_disable_early_pci_dma: Leave the busmaster bit set on all PCI bridges while in the EFI boot stub - efi_no_storage_paranoia [EFI; X86] + efi_no_storage_paranoia [EFI,X86,EARLY] Using this parameter you can use more than 50% of your efi variable storage. Use this parameter only if you are really sure that your UEFI does sane gc and fulfills the spec otherwise your board may brick. - efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] + efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI,X86,EARLY] Add arbitrary attribute to specific memory range by updating original EFI memory map. Region of memory which aa attribute is added to is @@ -1454,7 +1460,7 @@ eisa_irq_edge= [PARISC,HW] See header of drivers/parisc/eisa.c. - ekgdboc= [X86,KGDB] Allow early kernel console debugging + ekgdboc= [X86,KGDB,EARLY] Allow early kernel console debugging Format: ekgdboc=kbd This is designed to be used in conjunction with @@ -1469,13 +1475,13 @@ See comment before function elanfreq_setup() in arch/x86/kernel/cpu/cpufreq/elanfreq.c. - elfcorehdr=[size[KMG]@]offset[KMG] [PPC,SH,X86,S390] + elfcorehdr=[size[KMG]@]offset[KMG] [PPC,SH,X86,S390,EARLY] Specifies physical address of start of kernel core image elf header and optionally the size. Generally kexec loader will pass this option to capture kernel. See Documentation/admin-guide/kdump/kdump.rst for details. - enable_mtrr_cleanup [X86] + enable_mtrr_cleanup [X86,EARLY] The kernel tries to adjust MTRR layout from continuous to discrete, to make X server driver able to add WB entry later. This parameter enables that. @@ -1508,7 +1514,7 @@ Permit 'security.evm' to be updated regardless of current integrity status. - early_page_ext [KNL] Enforces page_ext initialization to earlier + early_page_ext [KNL,EARLY] Enforces page_ext initialization to earlier stages so cover more early boot allocations. Please note that as side effect some optimizations might be disabled to achieve that (e.g. parallelized @@ -1539,6 +1545,12 @@ Warning: use of this parameter will taint the kernel and may cause unknown problems. + fred= [X86-64] + Enable/disable Flexible Return and Event Delivery. + Format: { on | off } + on: enable FRED when it's present. + off: disable FRED, the default setting. + ftrace=[tracer] [FTRACE] will set and start the specified tracer as early as possible in order to facilitate early @@ -1600,7 +1612,7 @@ can be changed at run time by the max_graph_depth file in the tracefs tracing directory. default: 0 (no limit) - fw_devlink= [KNL] Create device links between consumer and supplier + fw_devlink= [KNL,EARLY] Create device links between consumer and supplier devices by scanning the firmware to infer the consumer/supplier relationships. This feature is especially useful when drivers are loaded as modules as @@ -1619,12 +1631,12 @@ rpm -- Like "on", but also use to order runtime PM. fw_devlink.strict= - [KNL] Treat all inferred dependencies as mandatory + [KNL,EARLY] Treat all inferred dependencies as mandatory dependencies. This only applies for fw_devlink=on|rpm. Format: fw_devlink.sync_state = - [KNL] When all devices that could probe have finished + [KNL,EARLY] When all devices that could probe have finished probing, this parameter controls what to do with devices that haven't yet received their sync_state() calls. @@ -1645,12 +1657,12 @@ gamma= [HW,DRM] - gart_fix_e820= [X86-64] disable the fix e820 for K8 GART + gart_fix_e820= [X86-64,EARLY] disable the fix e820 for K8 GART Format: off | on default: on gather_data_sampling= - [X86,INTEL] Control the Gather Data Sampling (GDS) + [X86,INTEL,EARLY] Control the Gather Data Sampling (GDS) mitigation. Gather Data Sampling is a hardware vulnerability which @@ -1748,7 +1760,7 @@ (that will set all pages holding image data during restoration read-only). - highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact + highmem=nn[KMG] [KNL,BOOT,EARLY] forces the highmem zone to have an exact size of . This works even on boxes that have no highmem otherwise. This also works to reduce highmem size on bigger boxes. @@ -1759,7 +1771,7 @@ hlt [BUGS=ARM,SH] - hostname= [KNL] Set the hostname (aka UTS nodename). + hostname= [KNL,EARLY] Set the hostname (aka UTS nodename). Format: This allows setting the system's hostname during early startup. This sets the name returned by gethostname. @@ -1804,7 +1816,7 @@ Documentation/admin-guide/mm/hugetlbpage.rst. Format: size[KMG] - hugetlb_cma= [HW,CMA] The size of a CMA area used for allocation + hugetlb_cma= [HW,CMA,EARLY] The size of a CMA area used for allocation of gigantic hugepages. Or using node format, the size of a CMA area per node can be specified. Format: nn[KMGTPE] or (node format) @@ -1850,9 +1862,10 @@ If specified, z/VM IUCV HVC accepts connections from listed z/VM user IDs only. - hv_nopvspin [X86,HYPER_V] Disables the paravirt spinlock optimizations - which allow the hypervisor to 'idle' the - guest on lock contention. + hv_nopvspin [X86,HYPER_V,EARLY] + Disables the paravirt spinlock optimizations + which allow the hypervisor to 'idle' the guest + on lock contention. i2c_bus= [HW] Override the default board specific I2C bus speed or register an additional I2C bus that is not @@ -1917,7 +1930,7 @@ Format: [,[,[,]]] - idle= [X86] + idle= [X86,EARLY] Format: idle=poll, idle=halt, idle=nomwait Poll forces a polling idle loop that can slightly improve the performance of waking up a idle CPU, but @@ -1973,7 +1986,7 @@ mode generally follows that for the NaN encoding, except where unsupported by hardware. - ignore_loglevel [KNL] + ignore_loglevel [KNL,EARLY] Ignore loglevel setting - this will print /all/ kernel messages to the console. Useful for debugging. We also add it as printk module parameter, so users @@ -2091,21 +2104,21 @@ unpacking being completed before device_ and late_ initcalls. - initrd= [BOOT] Specify the location of the initial ramdisk + initrd= [BOOT,EARLY] Specify the location of the initial ramdisk - initrdmem= [KNL] Specify a physical address and size from which to + initrdmem= [KNL,EARLY] Specify a physical address and size from which to load the initrd. If an initrd is compiled in or specified in the bootparams, it takes priority over this setting. Format: ss[KMG],nn[KMG] Default is 0, 0 - init_on_alloc= [MM] Fill newly allocated pages and heap objects with + init_on_alloc= [MM,EARLY] Fill newly allocated pages and heap objects with zeroes. Format: 0 | 1 Default set by CONFIG_INIT_ON_ALLOC_DEFAULT_ON. - init_on_free= [MM] Fill freed pages and heap objects with zeroes. + init_on_free= [MM,EARLY] Fill freed pages and heap objects with zeroes. Format: 0 | 1 Default set by CONFIG_INIT_ON_FREE_DEFAULT_ON. @@ -2161,7 +2174,7 @@ 0 disables intel_idle and fall back on acpi_idle. 1 to 9 specify maximum depth of C-state. - intel_pstate= [X86] + intel_pstate= [X86,EARLY] disable Do not enable intel_pstate as the default scaling driver for the supported processors @@ -2205,7 +2218,7 @@ Allow per-logical-CPU P-State performance control limits using cpufreq sysfs interface - intremap= [X86-64, Intel-IOMMU] + intremap= [X86-64,Intel-IOMMU,EARLY] on enable Interrupt Remapping (default) off disable Interrupt Remapping nosid disable Source ID checking @@ -2217,7 +2230,7 @@ strict regions from userspace. relaxed - iommu= [X86] + iommu= [X86,EARLY] off force noforce @@ -2232,7 +2245,7 @@ nobypass [PPC/POWERNV] Disable IOMMU bypass, using IOMMU for PCI devices. - iommu.forcedac= [ARM64, X86] Control IOVA allocation for PCI devices. + iommu.forcedac= [ARM64,X86,EARLY] Control IOVA allocation for PCI devices. Format: { "0" | "1" } 0 - Try to allocate a 32-bit DMA address first, before falling back to the full range if needed. @@ -2240,7 +2253,7 @@ forcing Dual Address Cycle for PCI cards supporting greater than 32-bit addressing. - iommu.strict= [ARM64, X86, S390] Configure TLB invalidation behaviour + iommu.strict= [ARM64,X86,S390,EARLY] Configure TLB invalidation behaviour Format: { "0" | "1" } 0 - Lazy mode. Request that DMA unmap operations use deferred @@ -2256,7 +2269,7 @@ legacy driver-specific options takes precedence. iommu.passthrough= - [ARM64, X86] Configure DMA to bypass the IOMMU by default. + [ARM64,X86,EARLY] Configure DMA to bypass the IOMMU by default. Format: { "0" | "1" } 0 - Use IOMMU translation for DMA. 1 - Bypass the IOMMU for DMA. @@ -2266,7 +2279,7 @@ See comment before marvel_specify_io7 in arch/alpha/kernel/core_marvel.c. - io_delay= [X86] I/O delay method + io_delay= [X86,EARLY] I/O delay method 0x80 Standard port 0x80 based delay 0xed @@ -2279,28 +2292,28 @@ ip= [IP_PNP] See Documentation/admin-guide/nfs/nfsroot.rst. - ipcmni_extend [KNL] Extend the maximum number of unique System V + ipcmni_extend [KNL,EARLY] Extend the maximum number of unique System V IPC identifiers from 32,768 to 16,777,216. irqaffinity= [SMP] Set the default irq affinity mask The argument is a cpu list, as described above. irqchip.gicv2_force_probe= - [ARM, ARM64] + [ARM,ARM64,EARLY] Format: Force the kernel to look for the second 4kB page of a GICv2 controller even if the memory range exposed by the device tree is too small. irqchip.gicv3_nolpi= - [ARM, ARM64] + [ARM,ARM64,EARLY] Force the kernel to ignore the availability of LPIs (and by consequence ITSs). Intended for system that use the kernel as a bootloader, and thus want to let secondary kernels in charge of setting up LPIs. - irqchip.gicv3_pseudo_nmi= [ARM64] + irqchip.gicv3_pseudo_nmi= [ARM64,EARLY] Enables support for pseudo-NMIs in the kernel. This requires the kernel to be built with CONFIG_ARM64_PSEUDO_NMI. @@ -2445,7 +2458,7 @@ parameter KASAN will print report only for the first invalid access. - keep_bootcon [KNL] + keep_bootcon [KNL,EARLY] Do not unregister boot console at start. This is only useful for debugging when something happens in the window between unregistering the boot console and initializing @@ -2453,7 +2466,7 @@ keepinitrd [HW,ARM] See retain_initrd. - kernelcore= [KNL,X86,IA-64,PPC] + kernelcore= [KNL,X86,IA-64,PPC,EARLY] Format: nn[KMGTPE] | nn% | "mirror" This parameter specifies the amount of memory usable by the kernel for non-movable allocations. The requested @@ -2478,7 +2491,7 @@ for Movable pages. "nn[KMGTPE]", "nn%", and "mirror" are exclusive, so you cannot specify multiple forms. - kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. + kgdbdbgp= [KGDB,HW,EARLY] kgdb over EHCI usb debug port. Format: [,poll interval] The controller # is the number of the ehci usb debug port as it is probed via PCI. The poll interval is @@ -2499,7 +2512,7 @@ kms, kbd format: kms,kbd kms, kbd and serial format: kms,kbd,[,baud] - kgdboc_earlycon= [KGDB,HW] + kgdboc_earlycon= [KGDB,HW,EARLY] If the boot console provides the ability to read characters and can work in polling mode, you can use this parameter to tell kgdb to use it as a backend @@ -2514,14 +2527,14 @@ blank and the first boot console that implements read() will be picked. - kgdbwait [KGDB] Stop kernel execution and enter the + kgdbwait [KGDB,EARLY] Stop kernel execution and enter the kernel debugger at the earliest opportunity. kmac= [MIPS] Korina ethernet MAC address. Configure the RouterBoard 532 series on-chip Ethernet adapter MAC address. - kmemleak= [KNL] Boot-time kmemleak enable/disable + kmemleak= [KNL,EARLY] Boot-time kmemleak enable/disable Valid arguments: on, off Default: on Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, @@ -2540,8 +2553,8 @@ See also Documentation/trace/kprobetrace.rst "Kernel Boot Parameter" section. - kpti= [ARM64] Control page table isolation of user - and kernel address spaces. + kpti= [ARM64,EARLY] Control page table isolation of + user and kernel address spaces. Default: enabled on cores which need mitigation. 0: force disabled 1: force enabled @@ -2618,7 +2631,8 @@ for NPT. kvm-arm.mode= - [KVM,ARM] Select one of KVM/arm64's modes of operation. + [KVM,ARM,EARLY] Select one of KVM/arm64's modes of + operation. none: Forcefully disable KVM. @@ -2638,22 +2652,22 @@ used with extreme caution. kvm-arm.vgic_v3_group0_trap= - [KVM,ARM] Trap guest accesses to GICv3 group-0 + [KVM,ARM,EARLY] Trap guest accesses to GICv3 group-0 system registers kvm-arm.vgic_v3_group1_trap= - [KVM,ARM] Trap guest accesses to GICv3 group-1 + [KVM,ARM,EARLY] Trap guest accesses to GICv3 group-1 system registers kvm-arm.vgic_v3_common_trap= - [KVM,ARM] Trap guest accesses to GICv3 common + [KVM,ARM,EARLY] Trap guest accesses to GICv3 common system registers kvm-arm.vgic_v4_enable= - [KVM,ARM] Allow use of GICv4 for direct injection of - LPIs. + [KVM,ARM,EARLY] Allow use of GICv4 for direct + injection of LPIs. - kvm_cma_resv_ratio=n [PPC] + kvm_cma_resv_ratio=n [PPC,EARLY] Reserves given percentage from system memory area for contiguous memory allocation for KVM hash pagetable allocation. @@ -2706,7 +2720,7 @@ (enabled). Disable by KVM if hardware lacks support for it. - l1d_flush= [X86,INTEL] + l1d_flush= [X86,INTEL,EARLY] Control mitigation for L1D based snooping vulnerability. Certain CPUs are vulnerable to an exploit against CPU @@ -2723,7 +2737,7 @@ on - enable the interface for the mitigation - l1tf= [X86] Control mitigation of the L1TF vulnerability on + l1tf= [X86,EARLY] Control mitigation of the L1TF vulnerability on affected CPUs The kernel PTE inversion protection is unconditionally @@ -2792,7 +2806,7 @@ l3cr= [PPC] - lapic [X86-32,APIC] Enable the local APIC even if BIOS + lapic [X86-32,APIC,EARLY] Enable the local APIC even if BIOS disabled it. lapic= [X86,APIC] Do not use TSC deadline @@ -2800,7 +2814,7 @@ back to the programmable timer unit in the LAPIC. Format: notscdeadline - lapic_timer_c2_ok [X86,APIC] trust the local apic timer + lapic_timer_c2_ok [X86,APIC,EARLY] trust the local apic timer in C2 power state. libata.dma= [LIBATA] DMA control @@ -2924,7 +2938,7 @@ lockd.nlm_udpport=M [NFS] Assign UDP port. Format: - lockdown= [SECURITY] + lockdown= [SECURITY,EARLY] { integrity | confidentiality } Enable the kernel lockdown feature. If set to integrity, kernel features that allow userland to @@ -3031,7 +3045,8 @@ logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver Format: - loglevel= All Kernel Messages with a loglevel smaller than the + loglevel= [KNL,EARLY] + All Kernel Messages with a loglevel smaller than the console loglevel will be printed to the console. It can also be changed with klogd or other programs. The loglevels are defined as follows: @@ -3045,13 +3060,15 @@ 6 (KERN_INFO) informational 7 (KERN_DEBUG) debug-level messages - log_buf_len=n[KMG] Sets the size of the printk ring buffer, - in bytes. n must be a power of two and greater - than the minimal size. The minimal size is defined - by LOG_BUF_SHIFT kernel config parameter. There is - also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter - that allows to increase the default size depending on - the number of CPUs. See init/Kconfig for more details. + log_buf_len=n[KMG] [KNL,EARLY] + Sets the size of the printk ring buffer, in bytes. + n must be a power of two and greater than the + minimal size. The minimal size is defined by + LOG_BUF_SHIFT kernel config parameter. There + is also CONFIG_LOG_CPU_MAX_BUF_SHIFT config + parameter that allows to increase the default size + depending on the number of CPUs. See init/Kconfig + for more details. logo.nologo [FB] Disables display of the built-in Linux logo. This may be used to provide more screen space for @@ -3109,7 +3126,7 @@ max_addr=nn[KMG] [KNL,BOOT,IA-64] All physical memory greater than or equal to this physical address is ignored. - maxcpus= [SMP] Maximum number of processors that an SMP kernel + maxcpus= [SMP,EARLY] Maximum number of processors that an SMP kernel will bring up during bootup. maxcpus=n : n >= 0 limits the kernel to bring up 'n' processors. Surely after bootup you can bring up the other plugged cpu by executing @@ -3136,7 +3153,7 @@ Format: , Specifies range of consoles to be captured by the MDA. - mds= [X86,INTEL] + mds= [X86,INTEL,EARLY] Control mitigation for the Micro-architectural Data Sampling (MDS) vulnerability. @@ -3168,11 +3185,12 @@ For details see: Documentation/admin-guide/hw-vuln/mds.rst - mem=nn[KMG] [HEXAGON] Set the memory size. + mem=nn[KMG] [HEXAGON,EARLY] Set the memory size. Must be specified, otherwise memory size will be 0. - mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory - Amount of memory to be used in cases as follows: + mem=nn[KMG] [KNL,BOOT,EARLY] Force usage of a specific amount + of memory Amount of memory to be used in cases + as follows: 1 for test; 2 when the kernel is not able to see the whole system memory; @@ -3196,8 +3214,8 @@ if system memory of hypervisor is not sufficient. mem=nn[KMG]@ss[KMG] - [ARM,MIPS] - override the memory layout reported by - firmware. + [ARM,MIPS,EARLY] - override the memory layout + reported by firmware. Define a memory region of size nn[KMG] starting at ss[KMG]. Multiple different regions can be specified with @@ -3206,7 +3224,7 @@ mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel memory. - memblock=debug [KNL] Enable memblock debug messages. + memblock=debug [KNL,EARLY] Enable memblock debug messages. memchunk=nn[KMG] [KNL,SH] Allow user to override the default size for @@ -3220,14 +3238,14 @@ option. See Documentation/admin-guide/mm/memory-hotplug.rst. - memmap=exactmap [KNL,X86] Enable setting of an exact + memmap=exactmap [KNL,X86,EARLY] Enable setting of an exact E820 memory map, as specified by the user. Such memmap=exactmap lines can be constructed based on BIOS output or other requirements. See the memmap=nn@ss option description. memmap=nn[KMG]@ss[KMG] - [KNL, X86, MIPS, XTENSA] Force usage of a specific region of memory. + [KNL, X86,MIPS,XTENSA,EARLY] Force usage of a specific region of memory. Region of memory to be used is from ss to ss+nn. If @ss[KMG] is omitted, it is equivalent to mem=nn[KMG], which limits max address to nn[KMG]. @@ -3237,11 +3255,11 @@ memmap=100M@2G,100M#3G,1G!1024G memmap=nn[KMG]#ss[KMG] - [KNL,ACPI] Mark specific memory as ACPI data. + [KNL,ACPI,EARLY] Mark specific memory as ACPI data. Region of memory to be marked is from ss to ss+nn. memmap=nn[KMG]$ss[KMG] - [KNL,ACPI] Mark specific memory as reserved. + [KNL,ACPI,EARLY] Mark specific memory as reserved. Region of memory to be reserved is from ss to ss+nn. Example: Exclude memory from 0x18690000-0x1869ffff memmap=64K$0x18690000 @@ -3251,14 +3269,14 @@ like Grub2, otherwise '$' and the following number will be eaten. - memmap=nn[KMG]!ss[KMG] + memmap=nn[KMG]!ss[KMG,EARLY] [KNL,X86] Mark specific memory as protected. Region of memory to be used, from ss to ss+nn. The memory region may be marked as e820 type 12 (0xc) and is NVDIMM or ADR memory. memmap=%-+ - [KNL,ACPI] Convert memory within the specified region + [KNL,ACPI,EARLY] Convert memory within the specified region from to . If "-" is left out, the whole region will be marked as , even if previously unavailable. If "+" is left @@ -3266,7 +3284,7 @@ specified as e820 types, e.g., 1 = RAM, 2 = reserved, 3 = ACPI, 12 = PRAM. - memory_corruption_check=0/1 [X86] + memory_corruption_check=0/1 [X86,EARLY] Some BIOSes seem to corrupt the first 64k of memory when doing things like suspend/resume. Setting this option will scan the memory @@ -3278,13 +3296,13 @@ affects the same memory, you can use memmap= to prevent the kernel from using that memory. - memory_corruption_check_size=size [X86] + memory_corruption_check_size=size [X86,EARLY] By default it checks for corruption in the low 64k, making this memory unavailable for normal use. Use this parameter to scan for corruption in more or less memory. - memory_corruption_check_period=seconds [X86] + memory_corruption_check_period=seconds [X86,EARLY] By default it checks for corruption every 60 seconds. Use this parameter to check at some other rate. 0 disables periodic checking. @@ -3308,7 +3326,7 @@ Note that even when enabled, there are a few cases where the feature is not effective. - memtest= [KNL,X86,ARM,M68K,PPC,RISCV] Enable memtest + memtest= [KNL,X86,ARM,M68K,PPC,RISCV,EARLY] Enable memtest Format: default : 0 Specifies the number of memtest passes to be @@ -3320,9 +3338,7 @@ mem_encrypt= [X86-64] AMD Secure Memory Encryption (SME) control Valid arguments: on, off - Default (depends on kernel configuration option): - on (CONFIG_AMD_MEM_ENCRYPT_ACTIVE_BY_DEFAULT=y) - off (CONFIG_AMD_MEM_ENCRYPT_ACTIVE_BY_DEFAULT=n) + Default: off mem_encrypt=on: Activate SME mem_encrypt=off: Do not activate SME @@ -3376,7 +3392,7 @@ https://repo.or.cz/w/linux-2.6/mini2440.git mitigations= - [X86,PPC,S390,ARM64] Control optional mitigations for + [X86,PPC,S390,ARM64,EARLY] Control optional mitigations for CPU vulnerabilities. This is a set of curated, arch-independent options, each of which is an aggregation of existing arch-specific options. @@ -3399,6 +3415,7 @@ nospectre_v1 [X86,PPC] nospectre_v2 [X86,PPC,S390,ARM64] retbleed=off [X86] + spec_rstack_overflow=off [X86] spec_store_bypass_disable=off [X86,PPC] spectre_v2_user=off [X86] srbds=off [X86,INTEL] @@ -3429,7 +3446,7 @@ retbleed=auto,nosmt [X86] mminit_loglevel= - [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this + [KNL,EARLY] When CONFIG_DEBUG_MEMORY_INIT is set, this parameter allows control of the logging verbosity for the additional memory initialisation checks. A value of 0 disables mminit logging and a level of 4 will @@ -3437,7 +3454,7 @@ so loglevel=8 may also need to be specified. mmio_stale_data= - [X86,INTEL] Control mitigation for the Processor + [X86,INTEL,EARLY] Control mitigation for the Processor MMIO Stale Data vulnerabilities. Processor MMIO Stale Data is a class of @@ -3512,7 +3529,7 @@ mousedev.yres= [MOUSE] Vertical screen resolution, used for devices reporting absolute coordinates, such as tablets - movablecore= [KNL,X86,IA-64,PPC] + movablecore= [KNL,X86,IA-64,PPC,EARLY] Format: nn[KMGTPE] | nn% This parameter is the complement to kernelcore=, it specifies the amount of memory used for migratable @@ -3523,7 +3540,7 @@ that the amount of memory usable for all allocations is not too small. - movable_node [KNL] Boot-time switch to make hotplugable memory + movable_node [KNL,EARLY] Boot-time switch to make hotplugable memory NUMA nodes to be movable. This means that the memory of such nodes will be usable only for movable allocations which rules out almost all kernel @@ -3547,21 +3564,21 @@ [HW] Make the MicroTouch USB driver use raw coordinates ('y', default) or cooked coordinates ('n') - mtrr=debug [X86] + mtrr=debug [X86,EARLY] Enable printing debug information related to MTRR registers at boot time. - mtrr_chunk_size=nn[KMG] [X86] + mtrr_chunk_size=nn[KMG,X86,EARLY] used for mtrr cleanup. It is largest continuous chunk that could hold holes aka. UC entries. - mtrr_gran_size=nn[KMG] [X86] + mtrr_gran_size=nn[KMG,X86,EARLY] Used for mtrr cleanup. It is granularity of mtrr block. Default is 1. Large value could prevent small alignment from using up MTRRs. - mtrr_spare_reg_nr=n [X86] + mtrr_spare_reg_nr=n [X86,EARLY] Format: Range: 0,7 : spare reg number Default : 1 @@ -3747,27 +3764,23 @@ emulation library even if a 387 maths coprocessor is present. - no4lvl [RISCV] Disable 4-level and 5-level paging modes. Forces - kernel to use 3-level paging instead. + no4lvl [RISCV,EARLY] Disable 4-level and 5-level paging modes. + Forces kernel to use 3-level paging instead. - no5lvl [X86-64,RISCV] Disable 5-level paging mode. Forces + no5lvl [X86-64,RISCV,EARLY] Disable 5-level paging mode. Forces kernel to use 4-level paging instead. - noaliencache [MM, NUMA, SLAB] Disables the allocation of alien - caches in the slab allocator. Saves per-node memory, - but will impact performance. - noalign [KNL,ARM] - noaltinstr [S390] Disables alternative instructions patching - (CPU alternatives feature). + noaltinstr [S390,EARLY] Disables alternative instructions + patching (CPU alternatives feature). - noapic [SMP,APIC] Tells the kernel to not make use of any + noapic [SMP,APIC,EARLY] Tells the kernel to not make use of any IOAPICs that may be present in the system. noautogroup Disable scheduler automatic task group creation. - nocache [ARM] + nocache [ARM,EARLY] no_console_suspend [HW] Never suspend the console @@ -3785,13 +3798,13 @@ turn on/off it dynamically. no_debug_objects - [KNL] Disable object debugging + [KNL,EARLY] Disable object debugging nodsp [SH] Disable hardware DSP at boot time. - noefi Disable EFI runtime services support. + noefi [EFI,EARLY] Disable EFI runtime services support. - no_entry_flush [PPC] Don't flush the L1-D cache when entering the kernel. + no_entry_flush [PPC,EARLY] Don't flush the L1-D cache when entering the kernel. noexec [IA-64] @@ -3822,6 +3835,7 @@ real-time systems. no_hash_pointers + [KNL,EARLY] Force pointers printed to the console or buffers to be unhashed. By default, when a pointer is printed via %p format string, that pointer is "hashed", i.e. obscured @@ -3846,9 +3860,9 @@ the impact of the sleep instructions. This is also useful when using JTAG debugger. - nohugeiomap [KNL,X86,PPC,ARM64] Disable kernel huge I/O mappings. + nohugeiomap [KNL,X86,PPC,ARM64,EARLY] Disable kernel huge I/O mappings. - nohugevmalloc [KNL,X86,PPC,ARM64] Disable kernel huge vmalloc mappings. + nohugevmalloc [KNL,X86,PPC,ARM64,EARLY] Disable kernel huge vmalloc mappings. nohz= [KNL] Boottime enable/disable dynamic ticks Valid arguments: on, off @@ -3870,13 +3884,13 @@ noinitrd [RAM] Tells the kernel not to load any configured initial RAM disk. - nointremap [X86-64, Intel-IOMMU] Do not enable interrupt + nointremap [X86-64,Intel-IOMMU,EARLY] Do not enable interrupt remapping. [Deprecated - use intremap=off] nointroute [IA-64] - noinvpcid [X86] Disable the INVPCID cpu feature. + noinvpcid [X86,EARLY] Disable the INVPCID cpu feature. noiotrap [SH] Disables trapped I/O port accesses. @@ -3887,19 +3901,19 @@ nojitter [IA-64] Disables jitter checking for ITC timers. - nokaslr [KNL] + nokaslr [KNL,EARLY] When CONFIG_RANDOMIZE_BASE is set, this disables kernel and module base offset ASLR (Address Space Layout Randomization). - no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page + no-kvmapf [X86,KVM,EARLY] Disable paravirtualized asynchronous page fault handling. - no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + no-kvmclock [X86,KVM,EARLY] Disable paravirtualized KVM clock driver - nolapic [X86-32,APIC] Do not enable or use the local APIC. + nolapic [X86-32,APIC,EARLY] Do not enable or use the local APIC. - nolapic_timer [X86-32,APIC] Do not use the local APIC timer. + nolapic_timer [X86-32,APIC,EARLY] Do not use the local APIC timer. nomca [IA-64] Disable machine check abort handling @@ -3924,23 +3938,23 @@ shutdown the other cpus. Instead use the REBOOT_VECTOR irq. - nopat [X86] Disable PAT (page attribute table extension of + nopat [X86,EARLY] Disable PAT (page attribute table extension of pagetables) support. - nopcid [X86-64] Disable the PCID cpu feature. + nopcid [X86-64,EARLY] Disable the PCID cpu feature. nopku [X86] Disable Memory Protection Keys CPU feature found in some Intel CPUs. - nopti [X86-64] + nopti [X86-64,EARLY] Equivalent to pti=off - nopv= [X86,XEN,KVM,HYPER_V,VMWARE] + nopv= [X86,XEN,KVM,HYPER_V,VMWARE,EARLY] Disables the PV optimizations forcing the guest to run as generic guest with no PV drivers. Currently support XEN HVM, KVM, HYPER_V and VMWARE guest. - nopvspin [X86,XEN,KVM] + nopvspin [X86,XEN,KVM,EARLY] Disables the qspinlock slow path using PV optimizations which allow the hypervisor to 'idle' the guest on lock contention. @@ -3960,20 +3974,20 @@ This is required for the Braillex ib80-piezo Braille reader made by F.H. Papenmeier (Germany). - nosgx [X86-64,SGX] Disables Intel SGX kernel support. + nosgx [X86-64,SGX,EARLY] Disables Intel SGX kernel support. - nosmap [PPC] + nosmap [PPC,EARLY] Disable SMAP (Supervisor Mode Access Prevention) even if it is supported by processor. - nosmep [PPC64s] + nosmep [PPC64s,EARLY] Disable SMEP (Supervisor Mode Execution Prevention) even if it is supported by processor. - nosmp [SMP] Tells an SMP kernel to act as a UP kernel, + nosmp [SMP,EARLY] Tells an SMP kernel to act as a UP kernel, and disable the IO APIC. legacy for "maxcpus=0". - nosmt [KNL,MIPS,PPC,S390] Disable symmetric multithreading (SMT). + nosmt [KNL,MIPS,PPC,S390,EARLY] Disable symmetric multithreading (SMT). Equivalent to smt=1. [KNL,X86,PPC] Disable symmetric multithreading (SMT). @@ -3983,22 +3997,23 @@ nosoftlockup [KNL] Disable the soft-lockup detector. nospec_store_bypass_disable - [HW] Disable all mitigations for the Speculative Store Bypass vulnerability + [HW,EARLY] Disable all mitigations for the Speculative + Store Bypass vulnerability - nospectre_bhb [ARM64] Disable all mitigations for Spectre-BHB (branch + nospectre_bhb [ARM64,EARLY] Disable all mitigations for Spectre-BHB (branch history injection) vulnerability. System may allow data leaks with this option. - nospectre_v1 [X86,PPC] Disable mitigations for Spectre Variant 1 + nospectre_v1 [X86,PPC,EARLY] Disable mitigations for Spectre Variant 1 (bounds check bypass). With this option data leaks are possible in the system. - nospectre_v2 [X86,PPC_E500,ARM64] Disable all mitigations for - the Spectre variant 2 (indirect branch prediction) - vulnerability. System may allow data leaks with this - option. + nospectre_v2 [X86,PPC_E500,ARM64,EARLY] Disable all mitigations + for the Spectre variant 2 (indirect branch + prediction) vulnerability. System may allow data + leaks with this option. - no-steal-acc [X86,PV_OPS,ARM64,PPC/PSERIES,RISCV] Disable + no-steal-acc [X86,PV_OPS,ARM64,PPC/PSERIES,RISCV,EARLY] Disable paravirtualized steal time accounting. steal time is computed, but won't influence scheduler behaviour @@ -4008,7 +4023,7 @@ broken timer IRQ sources. no_uaccess_flush - [PPC] Don't flush the L1-D cache after accessing user data. + [PPC,EARLY] Don't flush the L1-D cache after accessing user data. novmcoredd [KNL,KDUMP] Disable device dump. Device dump allows drivers to @@ -4022,15 +4037,15 @@ is set. no-vmw-sched-clock - [X86,PV_OPS] Disable paravirtualized VMware scheduler - clock and use the default one. + [X86,PV_OPS,EARLY] Disable paravirtualized VMware + scheduler clock and use the default one. nowatchdog [KNL] Disable both lockup detectors, i.e. soft-lockup and NMI watchdog (hard-lockup). - nowb [ARM] + nowb [ARM,EARLY] - nox2apic [X86-64,APIC] Do not enable x2APIC mode. + nox2apic [X86-64,APIC,EARLY] Do not enable x2APIC mode. NOTE: this parameter will be ignored on systems with the LEGACY_XAPIC_DISABLED bit set in the @@ -4068,7 +4083,7 @@ purges which is reported from either PAL_VM_SUMMARY or SAL PALO. - nr_cpus= [SMP] Maximum number of processors that an SMP kernel + nr_cpus= [SMP,EARLY] Maximum number of processors that an SMP kernel could support. nr_cpus=n : n >= 1 limits the kernel to support 'n' processors. It could be larger than the number of already plugged CPU during bootup, later in @@ -4079,8 +4094,9 @@ nr_uarts= [SERIAL] maximum number of UARTs to be registered. - numa=off [KNL, ARM64, PPC, RISCV, SPARC, X86] Disable NUMA, Only - set up a single NUMA node spanning all memory. + numa=off [KNL, ARM64, PPC, RISCV, SPARC, X86, EARLY] + Disable NUMA, Only set up a single NUMA node + spanning all memory. numa_balancing= [KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic NUMA balancing. @@ -4091,7 +4107,7 @@ This can be set from sysctl after boot. See Documentation/admin-guide/sysctl/vm.rst for details. - ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. + ohci1394_dma=early [HW,EARLY] enable debugging via the ohci1394 driver. See Documentation/core-api/debugging-via-ohci1394.rst for more info. @@ -4117,7 +4133,8 @@ Once locked, the boundary cannot be changed. 1 indicates lock status, 0 indicates unlock status. - oops=panic Always panic on oopses. Default is to just kill the + oops=panic [KNL,EARLY] + Always panic on oopses. Default is to just kill the process, but there is a small probability of deadlocking the machine. This will also cause panics on machine check exceptions. @@ -4133,13 +4150,13 @@ can be read from sysfs at: /sys/module/page_alloc/parameters/shuffle. - page_owner= [KNL] Boot-time page_owner enabling option. + page_owner= [KNL,EARLY] Boot-time page_owner enabling option. Storage of the information about who allocated each page is disabled in default. With this switch, we can turn it on. on: enable the feature - page_poison= [KNL] Boot-time parameter changing the state of + page_poison= [KNL,EARLY] Boot-time parameter changing the state of poisoning on the buddy allocator, available with CONFIG_PAGE_POISONING=y. off: turn off poisoning (default) @@ -4157,7 +4174,8 @@ timeout < 0: reboot immediately Format: - panic_on_taint= Bitmask for conditionally calling panic() in add_taint() + panic_on_taint= [KNL,EARLY] + Bitmask for conditionally calling panic() in add_taint() Format: [,nousertaint] Hexadecimal bitmask representing the set of TAINT flags that will cause the kernel to panic when add_taint() is @@ -4182,6 +4200,7 @@ bit 4: print ftrace buffer bit 5: print all printk messages in buffer bit 6: print all CPUs backtrace (if available in the arch) + bit 7: print only tasks in uninterruptible (blocked) state *Be aware* that this option may print a _lot_ of lines, so there are risks of losing older messages in the log. Use this option carefully, maybe worth to setup a @@ -4313,7 +4332,7 @@ pcbit= [HW,ISDN] - pci=option[,option...] [PCI] various PCI subsystem options. + pci=option[,option...] [PCI,EARLY] various PCI subsystem options. Some options herein operate on a specific device or a set of devices (). These are @@ -4582,7 +4601,8 @@ Format: { 0 | 1 } See arch/parisc/kernel/pdc_chassis.c - percpu_alloc= Select which percpu first chunk allocator to use. + percpu_alloc= [MM,EARLY] + Select which percpu first chunk allocator to use. Currently supported values are "embed" and "page". Archs may support subset or none of the selections. See comments in mm/percpu.c for details on each @@ -4644,6 +4664,11 @@ may be specified. Format: ,.... + possible_cpus= [SMP,S390,X86] + Format: + Set the number of possible CPUs, overriding the + regular discovery mechanisms (such as ACPI/FW, etc). + powersave=off [PPC] This option disables power saving features. It specifically disables cpuidle and sets the platform machine description specific power_save @@ -4651,12 +4676,12 @@ execution priority. ppc_strict_facility_enable - [PPC] This option catches any kernel floating point, + [PPC,ENABLE] This option catches any kernel floating point, Altivec, VSX and SPE outside of regions specifically allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). There is some performance impact when enabling this. - ppc_tm= [PPC] + ppc_tm= [PPC,EARLY] Format: {"off"} Disable Hardware Transactional Memory @@ -4766,7 +4791,7 @@ [KNL] Number of legacy pty's. Overwrites compiled-in default number. - quiet [KNL] Disable most log messages + quiet [KNL,EARLY] Disable most log messages r128= [HW,DRM] @@ -4783,17 +4808,17 @@ ramdisk_start= [RAM] RAM disk image start address random.trust_cpu=off - [KNL] Disable trusting the use of the CPU's + [KNL,EARLY] Disable trusting the use of the CPU's random number generator (if available) to initialize the kernel's RNG. random.trust_bootloader=off - [KNL] Disable trusting the use of the a seed + [KNL,EARLY] Disable trusting the use of the a seed passed by the bootloader (if available) to initialize the kernel's RNG. randomize_kstack_offset= - [KNL] Enable or disable kernel stack offset + [KNL,EARLY] Enable or disable kernel stack offset randomization, which provides roughly 5 bits of entropy, frustrating memory corruption attacks that depend on stack address determinism or @@ -5034,6 +5059,11 @@ this kernel boot parameter, forcibly setting it to zero. + rcutree.enable_rcu_lazy= [KNL] + To save power, batch RCU callbacks and flush after + delay, memory pressure or callback list growing too + big. + rcuscale.gp_async= [KNL] Measure performance of asynchronous grace-period primitives such as call_rcu(). @@ -5484,7 +5514,7 @@ Run specified binary instead of /init from the ramdisk, used for early userspace startup. See initrd. - rdrand= [X86] + rdrand= [X86,EARLY] force - Override the decision by the kernel to hide the advertisement of RDRAND support (this affects certain AMD processors because of buggy BIOS @@ -5580,7 +5610,7 @@ them. If is less than 0x10000, the region is assumed to be I/O ports; otherwise it is memory. - reservetop= [X86-32] + reservetop= [X86-32,EARLY] Format: nn[KMG] Reserves a hole at the top of the kernel virtual address space. @@ -5665,7 +5695,7 @@ [KNL] Disable ring 3 MONITOR/MWAIT feature on supported CPUs. - riscv_isa_fallback [RISCV] + riscv_isa_fallback [RISCV,EARLY] When CONFIG_RISCV_ISA_FALLBACK is not enabled, permit falling back to detecting extension support by parsing "riscv,isa" property on devicetree systems when the @@ -5674,13 +5704,14 @@ ro [KNL] Mount root device read-only on boot - rodata= [KNL] + rodata= [KNL,EARLY] on Mark read-only kernel memory as read-only (default). off Leave read-only kernel memory writable for debugging. full Mark read-only kernel memory and aliases as read-only [arm64] rockchip.usb_uart + [EARLY] Enable the uart passthrough on the designated usb port on Rockchip SoCs. When active, the signals of the debug-uart get routed to the D+ and D- pins of the usb @@ -5741,7 +5772,7 @@ sa1100ir [NET] See drivers/net/irda/sa1100_ir.c. - sched_verbose [KNL] Enables verbose scheduler debug messages. + sched_verbose [KNL,EARLY] Enables verbose scheduler debug messages. schedstats= [KNL,X86] Enable or disable scheduled statistics. Allowed values are enable and disable. This feature @@ -5856,7 +5887,7 @@ non-zero "wait" parameter. See weight_single and weight_many. - skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate + skew_tick= [KNL,EARLY] Offset the periodic timer tick per cpu to mitigate xtime_lock contention on larger systems, and/or RCU lock contention on all systems with CONFIG_MAXSMP set. Format: { "0" | "1" } @@ -5895,65 +5926,58 @@ simeth= [IA-64] simscsi= - slram= [HW,MTD] - - slab_merge [MM] - Enable merging of slabs with similar size when the - kernel is built without CONFIG_SLAB_MERGE_DEFAULT. - - slab_nomerge [MM] - Disable merging of slabs with similar size. May be - necessary if there is some reason to distinguish - allocs to different slabs, especially in hardened - environments where the risk of heap overflows and - layout control by attackers can usually be - frustrated by disabling merging. This will reduce - most of the exposure of a heap attack to a single - cache (risks via metadata attacks are mostly - unchanged). Debug options disable merging on their - own. - For more information see Documentation/mm/slub.rst. - - slab_max_order= [MM, SLAB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. Defaults to 1 for systems with - more than 32MB of RAM, 0 otherwise. - - slub_debug[=options[,slabs][;[options[,slabs]]...] [MM, SLUB] - Enabling slub_debug allows one to determine the + slab_debug[=options[,slabs][;[options[,slabs]]...] [MM] + Enabling slab_debug allows one to determine the culprit if slab objects become corrupted. Enabling - slub_debug can create guard zones around objects and + slab_debug can create guard zones around objects and may poison objects when not in use. Also tracks the last alloc / free. For more information see Documentation/mm/slub.rst. + (slub_debug legacy name also accepted for now) - slub_max_order= [MM, SLUB] + slab_max_order= [MM] Determines the maximum allowed order for slabs. A high setting may cause OOMs due to memory fragmentation. For more information see Documentation/mm/slub.rst. + (slub_max_order legacy name also accepted for now) - slub_min_objects= [MM, SLUB] + slab_merge [MM] + Enable merging of slabs with similar size when the + kernel is built without CONFIG_SLAB_MERGE_DEFAULT. + (slub_merge legacy name also accepted for now) + + slab_min_objects= [MM] The minimum number of objects per slab. SLUB will - increase the slab order up to slub_max_order to + increase the slab order up to slab_max_order to generate a sufficiently large slab able to contain the number of objects indicated. The higher the number of objects the smaller the overhead of tracking slabs and the less frequently locks need to be acquired. For more information see Documentation/mm/slub.rst. + (slub_min_objects legacy name also accepted for now) - slub_min_order= [MM, SLUB] + slab_min_order= [MM] Determines the minimum page order for slabs. Must be - lower than slub_max_order. - For more information see Documentation/mm/slub.rst. + lower or equal to slab_max_order. For more information see + Documentation/mm/slub.rst. + (slub_min_order legacy name also accepted for now) - slub_merge [MM, SLUB] - Same with slab_merge. + slab_nomerge [MM] + Disable merging of slabs with similar size. May be + necessary if there is some reason to distinguish + allocs to different slabs, especially in hardened + environments where the risk of heap overflows and + layout control by attackers can usually be + frustrated by disabling merging. This will reduce + most of the exposure of a heap attack to a single + cache (risks via metadata attacks are mostly + unchanged). Debug options disable merging on their + own. + For more information see Documentation/mm/slub.rst. + (slub_nomerge legacy name also accepted for now) - slub_nomerge [MM, SLUB] - Same with slab_nomerge. This is supported for legacy. - See slab_nomerge for more information. + slram= [HW,MTD] smart2= [HW] Format: [,[,...,]] @@ -5987,10 +6011,10 @@ 1: Fast pin select (default) 2: ATC IRMode - smt= [KNL,MIPS,S390] Set the maximum number of threads (logical - CPUs) to use per physical CPU on systems capable of - symmetric multithreading (SMT). Will be capped to the - actual hardware limit. + smt= [KNL,MIPS,S390,EARLY] Set the maximum number of threads + (logical CPUs) to use per physical CPU on systems + capable of symmetric multithreading (SMT). Will + be capped to the actual hardware limit. Format: Default: -1 (no limit) @@ -6012,7 +6036,7 @@ sonypi.*= [HW] Sony Programmable I/O Control Device driver See Documentation/admin-guide/laptops/sonypi.rst - spectre_v2= [X86] Control mitigation of Spectre variant 2 + spectre_v2= [X86,EARLY] Control mitigation of Spectre variant 2 (indirect branch speculation) vulnerability. The default operation protects the kernel from user space attacks. @@ -6027,8 +6051,8 @@ Selecting 'on' will, and 'auto' may, choose a mitigation method at run time according to the CPU, the available microcode, the setting of the - CONFIG_RETPOLINE configuration option, and the - compiler with which the kernel was built. + CONFIG_MITIGATION_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. @@ -6092,7 +6116,7 @@ spectre_v2_user=auto. spec_rstack_overflow= - [X86] Control RAS overflow mitigation on AMD Zen CPUs + [X86,EARLY] Control RAS overflow mitigation on AMD Zen CPUs off - Disable mitigation microcode - Enable microcode mitigation only @@ -6103,7 +6127,7 @@ (cloud-specific mitigation) spec_store_bypass_disable= - [HW] Control Speculative Store Bypass (SSB) Disable mitigation + [HW,EARLY] Control Speculative Store Bypass (SSB) Disable mitigation (Speculative Store Bypass vulnerability) Certain CPUs are vulnerable to an exploit against a @@ -6199,7 +6223,7 @@ #DB exception for bus lock is triggered only when CPL > 0. - srbds= [X86,INTEL] + srbds= [X86,INTEL,EARLY] Control the Special Register Buffer Data Sampling (SRBDS) mitigation. @@ -6286,7 +6310,7 @@ srcutree.convert_to_big must have the 0x10 bit set for contention-based conversions to occur. - ssbd= [ARM64,HW] + ssbd= [ARM64,HW,EARLY] Speculative Store Bypass Disable control On CPUs that are vulnerable to the Speculative @@ -6310,7 +6334,7 @@ growing up) the main stack are reserved for no other mapping. Default value is 256 pages. - stack_depot_disable= [KNL] + stack_depot_disable= [KNL,EARLY] Setting this to true through kernel command line will disable the stack depot thereby saving the static memory consumed by the stack hash table. By default this is set @@ -6349,12 +6373,12 @@ be used to filter out binaries which have not yet been made aware of AT_MINSIGSTKSZ. - stress_hpt [PPC] + stress_hpt [PPC,EARLY] Limits the number of kernel HPT entries in the hash page table to increase the rate of hash page table faults on kernel addresses. - stress_slb [PPC] + stress_slb [PPC,EARLY] Limits the number of kernel SLB entries, and flushes them frequently to increase the rate of SLB faults on kernel addresses. @@ -6414,7 +6438,7 @@ This parameter controls use of the Protected Execution Facility on pSeries. - swiotlb= [ARM,IA-64,PPC,MIPS,X86] + swiotlb= [ARM,IA-64,PPC,MIPS,X86,EARLY] Format: { [,] | force | noforce } -- Number of I/O TLB slabs -- Second integer after comma. Number of swiotlb @@ -6424,7 +6448,7 @@ wouldn't be automatically used by the kernel noforce -- Never use bounce buffers (for debugging) - switches= [HW,M68k] + switches= [HW,M68k,EARLY] sysctl.*= [KNL] Set a sysctl parameter, right before loading the init @@ -6483,11 +6507,11 @@ : poll all this frequency 0: no polling (default) - threadirqs [KNL] + threadirqs [KNL,EARLY] Force threading of all interrupt handlers except those marked explicitly IRQF_NO_THREAD. - topology= [S390] + topology= [S390,EARLY] Format: {off | on} Specify if the kernel should make use of the cpu topology information if the hardware supports this. @@ -6728,7 +6752,7 @@ can be overridden by a later tsc=nowatchdog. A console message will flag any such suppression or overriding. - tsc_early_khz= [X86] Skip early TSC calibration and use the given + tsc_early_khz= [X86,EARLY] Skip early TSC calibration and use the given value instead. Useful when the early TSC frequency discovery procedure is not reliable, such as on overclocked systems with CPUID.16h support and partial CPUID.15h support. @@ -6763,7 +6787,7 @@ See Documentation/admin-guide/hw-vuln/tsx_async_abort.rst for more details. - tsx_async_abort= [X86,INTEL] Control mitigation for the TSX Async + tsx_async_abort= [X86,INTEL,EARLY] Control mitigation for the TSX Async Abort (TAA) vulnerability. Similar to Micro-architectural Data Sampling (MDS) @@ -6829,7 +6853,7 @@ unknown_nmi_panic [X86] Cause panic on unknown NMI. - unwind_debug [X86-64] + unwind_debug [X86-64,EARLY] Enable unwinder debug output. This can be useful for debugging certain unwinder error conditions, including corrupt stacks and @@ -7019,7 +7043,7 @@ Example: user_debug=31 userpte= - [X86] Flags controlling user PTE allocations. + [X86,EARLY] Flags controlling user PTE allocations. nohigh = do not allocate PTE pages in HIGHMEM regardless of setting @@ -7048,7 +7072,7 @@ vector= [IA-64,SMP] vector=percpu: enable percpu vector domain - video= [FB] Frame buffer configuration + video= [FB,EARLY] Frame buffer configuration See Documentation/fb/modedb.rst. video.brightness_switch_enabled= [ACPI] @@ -7096,13 +7120,13 @@ 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 . This can be used to increase the - minimum size (128MB on x86). It can also be used to - decrease the size and leave more room for directly - mapped kernel RAM. + vmalloc=nn[KMG] [KNL,BOOT,EARLY] Forces the vmalloc area to have an + exact size of . This can be used to increase + the minimum size (128MB on x86). It can also be + used to decrease the size and leave more room + for directly mapped kernel RAM. - vmcp_cma=nn[MG] [KNL,S390] + vmcp_cma=nn[MG] [KNL,S390,EARLY] Sets the memory size reserved for contiguous memory allocations for the vmcp device driver. @@ -7115,7 +7139,7 @@ vmpoff= [KNL,S390] Perform z/VM CP command after power off. Format: - vsyscall= [X86-64] + vsyscall= [X86-64,EARLY] Controls the behavior of vsyscalls (i.e. calls to fixed addresses of 0xffffffffff600x00 from legacy code). Most statically-linked binaries and older @@ -7263,13 +7287,13 @@ When enabled, memory and cache locality will be impacted. - writecombine= [LOONGARCH] Control the MAT (Memory Access Type) of - ioremap_wc(). + writecombine= [LOONGARCH,EARLY] Control the MAT (Memory Access + Type) of ioremap_wc(). on - Enable writecombine, use WUC for ioremap_wc() off - Disable writecombine, use SUC for ioremap_wc() - x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of + x2apic_phys [X86-64,APIC,EARLY] Use x2apic physical mode instead of default x2apic cluster mode on platforms supporting x2apic. @@ -7280,7 +7304,7 @@ save/restore/migration must be enabled to handle larger domains. - xen_emul_unplug= [HW,X86,XEN] + xen_emul_unplug= [HW,X86,XEN,EARLY] Unplug Xen emulated devices Format: [unplug0,][unplug1] ide-disks -- unplug primary master IDE devices @@ -7292,17 +7316,17 @@ the unplug protocol never -- do not unplug even if version check succeeds - xen_legacy_crash [X86,XEN] + xen_legacy_crash [X86,XEN,EARLY] Crash from Xen panic notifier, without executing late panic() code such as dumping handler. - xen_msr_safe= [X86,XEN] + xen_msr_safe= [X86,XEN,EARLY] Format: Select whether to always use non-faulting (safe) MSR access functions when running as Xen PV guest. The default value is controlled by CONFIG_XEN_PV_MSR_SAFE. - xen_nopvspin [X86,XEN] + xen_nopvspin [X86,XEN,EARLY] Disables the qspinlock slowpath using Xen PV optimizations. This parameter is obsoleted by "nopvspin" parameter, which has equivalent effect for XEN platform. @@ -7314,7 +7338,7 @@ has equivalent effect for XEN platform. xen_no_vector_callback - [KNL,X86,XEN] Disable the vector callback for Xen + [KNL,X86,XEN,EARLY] Disable the vector callback for Xen event channel interrupts. xen_scrub_pages= [XEN] @@ -7323,7 +7347,7 @@ with /sys/devices/system/xen_memory/xen_memory0/scrub_pages. Default value controlled with CONFIG_XEN_SCRUB_PAGES_DEFAULT. - xen_timer_slop= [X86-64,XEN] + xen_timer_slop= [X86-64,XEN,EARLY] Set the timer slop (in nanoseconds) for the virtual Xen timers (default is 100000). This adjusts the minimum delta of virtualized Xen timers, where lower values @@ -7376,7 +7400,7 @@ host controller quirks. Meaning of each bit can be consulted in header drivers/usb/host/xhci.h. - xmon [PPC] + xmon [PPC,EARLY] Format: { early | on | rw | ro | off } Controls if xmon debugger is enabled. Default is off. Passing only "xmon" is equivalent to "xmon=early". diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst index 993c2a05f5eeab..b6aeae3327ceb5 100644 --- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst +++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst @@ -243,13 +243,9 @@ To reduce its OS jitter, do any of the following: 3. Do any of the following needed to avoid jitter that your application cannot tolerate: - a. Build your kernel with CONFIG_SLUB=y rather than - CONFIG_SLAB=y, thus avoiding the slab allocator's periodic - use of each CPU's workqueues to run its cache_reap() - function. - b. Avoid using oprofile, thus avoiding OS jitter from + a. Avoid using oprofile, thus avoiding OS jitter from wq_sync_buffer(). - c. Limit your CPU frequency so that a CPU-frequency + b. Limit your CPU frequency so that a CPU-frequency governor is not required, possibly enlisting the aid of special heatsinks or other cooling technologies. If done correctly, and if you CPU architecture permits, you should @@ -259,7 +255,7 @@ To reduce its OS jitter, do any of the following: WARNING: Please check your CPU specifications to make sure that this is safe on your particular system. - d. As of v3.18, Christoph Lameter's on-demand vmstat workers + c. As of v3.18, Christoph Lameter's on-demand vmstat workers commit prevents OS jitter due to vmstat_update() on CONFIG_SMP=y systems. Before v3.18, is not possible to entirely get rid of the OS jitter, but you can @@ -274,7 +270,7 @@ To reduce its OS jitter, do any of the following: (based on an earlier one from Gilad Ben-Yossef) that reduces or even eliminates vmstat overhead for some workloads at https://lore.kernel.org/r/00000140e9dfd6bd-40db3d4f-c1be-434f-8132-7820f81bb586-000000@email.amazonses.com. - e. If running on high-end powerpc servers, build with + d. If running on high-end powerpc servers, build with CONFIG_PPC_RTAS_DAEMON=n. This prevents the RTAS daemon from running on each CPU every second or so. (This will require editing Kconfig files and will defeat @@ -282,12 +278,12 @@ To reduce its OS jitter, do any of the following: due to the rtas_event_scan() function. WARNING: Please check your CPU specifications to make sure that this is safe on your particular system. - f. If running on Cell Processor, build your kernel with + e. If running on Cell Processor, build your kernel with CBE_CPUFREQ_SPU_GOVERNOR=n to avoid OS jitter from spu_gov_work(). WARNING: Please check your CPU specifications to make sure that this is safe on your particular system. - g. If running on PowerMAC, build your kernel with + f. If running on PowerMAC, build your kernel with CONFIG_PMAC_RACKMETER=n to disable the CPU-meter, avoiding OS jitter from rackmeter_do_timer(). diff --git a/Documentation/admin-guide/laptops/thinkpad-acpi.rst b/Documentation/admin-guide/laptops/thinkpad-acpi.rst index 98d30401017012..7f674a6cfa8a7b 100644 --- a/Documentation/admin-guide/laptops/thinkpad-acpi.rst +++ b/Documentation/admin-guide/laptops/thinkpad-acpi.rst @@ -444,7 +444,9 @@ event code Key Notes 0x1008 0x07 FN+F8 IBM: toggle screen expand Lenovo: configure UltraNav, - or toggle screen expand + or toggle screen expand. + On newer platforms (2024+) + replaced by 0x131f (see below) 0x1009 0x08 FN+F9 - @@ -504,6 +506,9 @@ event code Key Notes 0x1019 0x18 unknown +0x131f ... FN+F8 Platform Mode change. + Implemented in driver. + ... ... ... 0x1020 0x1F unknown diff --git a/Documentation/admin-guide/media/visl.rst b/Documentation/admin-guide/media/visl.rst index db1ef29438e16c..cd45145cde686a 100644 --- a/Documentation/admin-guide/media/visl.rst +++ b/Documentation/admin-guide/media/visl.rst @@ -49,6 +49,10 @@ Module parameters visl_dprintk_frame_start, visl_dprintk_nframes, but controls the dumping of buffer data through debugfs instead. +- tpg_verbose: Write extra information on each output frame to ease debugging + the API. When set to true, the output frames are not stable for a given input + as some information like pointers or queue status will be added to them. + What is the default use case for this driver? --------------------------------------------- @@ -57,8 +61,12 @@ This assumes that a working client is run against visl and that the ftrace and OUTPUT buffer data is subsequently used to debug a work-in-progress implementation. -Information on reference frames, their timestamps, the status of the OUTPUT and -CAPTURE queues and more can be read directly from the CAPTURE buffers. +Even though no video decoding is actually done, the output frames can be used +against a reference for a given input, except if tpg_verbose is set to true. + +Depending on the tpg_verbose parameter value, information on reference frames, +their timestamps, the status of the OUTPUT and CAPTURE queues and more can be +read directly from the CAPTURE buffers. Supported codecs ---------------- diff --git a/Documentation/admin-guide/media/vivid.rst b/Documentation/admin-guide/media/vivid.rst index 58ac25b2c385c4..b6f658c0997ec3 100644 --- a/Documentation/admin-guide/media/vivid.rst +++ b/Documentation/admin-guide/media/vivid.rst @@ -60,7 +60,7 @@ all configurable using the following module options: - node_types: which devices should each driver instance create. An array of - hexadecimal values, one for each instance. The default is 0x1d3d. + hexadecimal values, one for each instance. The default is 0xe1d3d. Each value is a bitmask with the following meaning: - bit 0: Video Capture node diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst index 343e25b252f430..af05ae6170184f 100644 --- a/Documentation/admin-guide/mm/damon/reclaim.rst +++ b/Documentation/admin-guide/mm/damon/reclaim.rst @@ -117,6 +117,33 @@ milliseconds. 1 second by default. +quota_mem_pressure_us +--------------------- + +Desired level of memory pressure-stall time in microseconds. + +While keeping the caps that set by other quotas, DAMON_RECLAIM automatically +increases and decreases the effective level of the quota aiming this level of +memory pressure is incurred. System-wide ``some`` memory PSI in microseconds +per quota reset interval (``quota_reset_interval_ms``) is collected and +compared to this value to see if the aim is satisfied. Value zero means +disabling this auto-tuning feature. + +Disabled by default. + +quota_autotune_feedback +----------------------- + +User-specifiable feedback for auto-tuning of the effective quota. + +While keeping the caps that set by other quotas, DAMON_RECLAIM automatically +increases and decreases the effective level of the quota aiming receiving this +feedback of value ``10,000`` from the user. DAMON_RECLAIM assumes the feedback +value and the quota are positively proportional. Value zero means disabling +this auto-tuning feature. + +Disabled by default. + wmarks_interval --------------- diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index 9d23144bf98501..b33eecfd0e901c 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -83,10 +83,10 @@ comma (","). │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max │ │ │ │ │ │ │ │ age/min,max - │ │ │ │ │ │ │ :ref:`quotas `/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ :ref:`quotas `/ms,bytes,reset_interval_ms,effective_bytes │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil │ │ │ │ │ │ │ │ :ref:`goals `/nr_goals - │ │ │ │ │ │ │ │ │ 0/target_value,current_value + │ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value │ │ │ │ │ │ │ :ref:`watermarks `/metric,interval_us,high,mid,low │ │ │ │ │ │ │ :ref:`filters `/nr_filters │ │ │ │ │ │ │ │ 0/type,matching,memcg_id @@ -153,6 +153,9 @@ Users can write below commands for the kdamond to the ``state`` file. - ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme action tried regions directory for each DAMON-based operation scheme of the kdamond. +- ``update_schemes_effective_bytes``: Update the contents of + ``effective_bytes`` files for each DAMON-based operation scheme of the + kdamond. For more details, refer to :ref:`quotas directory `. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. @@ -180,19 +183,14 @@ In each context directory, two files (``avail_operations`` and ``operations``) and three directories (``monitoring_attrs``, ``targets``, and ``schemes``) exist. -DAMON supports multiple types of monitoring operations, including those for -virtual address space and the physical address space. You can get the list of -available monitoring operations set on the currently running kernel by reading +DAMON supports multiple types of :ref:`monitoring operations +`, including those for virtual address +space and the physical address space. You can get the list of available +monitoring operations set on the currently running kernel by reading ``avail_operations`` file. Based on the kernel configuration, the file will -list some or all of below keywords. - - - vaddr: Monitor virtual address spaces of specific processes - - fvaddr: Monitor fixed virtual address ranges - - paddr: Monitor the physical address space of the system - -Please refer to :ref:`regions sysfs directory ` for detailed -differences between the operations sets in terms of the monitoring target -regions. +list different available operation sets. Please refer to the :ref:`design +` for the list of all available operation sets and their +brief explanations. You can set and get what type of monitoring operations DAMON will use for the context by writing one of the keywords listed in ``avail_operations`` file and @@ -247,17 +245,11 @@ process to the ``pid_target`` file. targets//regions ------------------- -When ``vaddr`` monitoring operations set is being used (``vaddr`` is written to -the ``contexts//operations`` file), DAMON automatically sets and updates the -monitoring target regions so that entire memory mappings of target processes -can be covered. However, users could want to set the initial monitoring region -to specific address ranges. - -In contrast, DAMON do not automatically sets and updates the monitoring target -regions when ``fvaddr`` or ``paddr`` monitoring operations sets are being used -(``fvaddr`` or ``paddr`` have written to the ``contexts//operations``). -Therefore, users should set the monitoring target regions by themselves in the -cases. +In case of ``fvaddr`` or ``paddr`` monitoring operations sets, users are +required to set the monitoring target address ranges. In case of ``vaddr`` +operations set, it is not mandatory, but users can optionally set the initial +monitoring region to specific address ranges. Please refer to the :ref:`design +` for more details. For such cases, users can explicitly set the initial monitoring target regions as they want, by writing proper values to the files under this directory. @@ -302,27 +294,8 @@ In each scheme directory, five directories (``access_pattern``, ``quotas``, The ``action`` file is for setting and getting the scheme's :ref:`action `. The keywords that can be written to and read -from the file and their meaning are as below. - -Note that support of each action depends on the running DAMON operations set -:ref:`implementation `. - - - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. - Supported by ``vaddr`` and ``fvaddr`` operations set. - - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD``. - Supported by ``vaddr`` and ``fvaddr`` operations set. - - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. - Supported by ``vaddr``, ``fvaddr`` and ``paddr`` operations set. - - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. - Supported by ``vaddr`` and ``fvaddr`` operations set. - - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. - Supported by ``vaddr`` and ``fvaddr`` operations set. - - ``lru_prio``: Prioritize the region on its LRU lists. - Supported by ``paddr`` operations set. - - ``lru_deprio``: Deprioritize the region on its LRU lists. - Supported by ``paddr`` operations set. - - ``stat``: Do nothing but count the statistics. - Supported by all operations sets. +from the file and their meaning are same to those of the list on +:ref:`design doc `. The ``apply_interval_us`` file is for setting and getting the scheme's :ref:`apply_interval ` in microseconds. @@ -350,8 +323,9 @@ schemes//quotas/ The directory for the :ref:`quotas ` of the given DAMON-based operation scheme. -Under ``quotas`` directory, three files (``ms``, ``bytes``, -``reset_interval_ms``) and two directores (``weights`` and ``goals``) exist. +Under ``quotas`` directory, four files (``ms``, ``bytes``, +``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and +``goals``) exist. You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and ``reset interval`` in milliseconds by writing the values to the three files, @@ -359,7 +333,17 @@ respectively. Then, DAMON tries to use only up to ``time quota`` milliseconds for applying the ``action`` to memory regions of the ``access_pattern``, and to apply the action to only up to ``bytes`` bytes of memory regions within the ``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the -quota limits. +quota limits unless at least one :ref:`goal ` is +set. + +The time quota is internally transformed to a size quota. Between the +transformed size quota and user-specified size quota, smaller one is applied. +Based on the user-specified :ref:`goal `, the +effective size quota is further adjusted. Reading ``effective_bytes`` returns +the current effective size quota. The file is not updated in real time, so +users should ask DAMON sysfs interface to update the content of the file for +the stats by writing a special keyword, ``update_schemes_effective_bytes`` to +the relevant ``kdamonds//state`` file. Under ``weights`` directory, three files (``sz_permil``, ``nr_accesses_permil``, and ``age_permil``) exist. @@ -382,11 +366,11 @@ number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each goal and current achievement. Among the multiple feedback, the best one is used. -Each goal directory contains two files, namely ``target_value`` and -``current_value``. Users can set and get any number to those files to set the -feedback. User space main workload's latency or throughput, system metrics -like free memory ratio or memory pressure stall time (PSI) could be example -metrics for the values. Note that users should write +Each goal directory contains three files, namely ``target_metric``, +``target_value`` and ``current_value``. Users can set and get the three +parameters for the quota auto-tuning goals that specified on the :ref:`design +doc ` by writing to and reading from each +of the files. Note that users should further write ``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond directory ` to pass the feedback to DAMON. @@ -579,11 +563,11 @@ monitoring results recording. While the monitoring is turned on, you could record the tracepoint events and show results using tracepoint supporting tools like ``perf``. For example:: - # echo on > monitor_on + # echo on > kdamonds/0/state # perf record -e damon:damon_aggregated & # sleep 5 # kill 9 $(pidof perf) - # echo off > monitor_on + # echo off > kdamonds/0/state # perf script kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864 [...] @@ -628,9 +612,17 @@ debugfs Interface (DEPRECATED!) move, please report your usecase to damon@lists.linux.dev and linux-mm@kvack.org. -DAMON exports eight files, ``attrs``, ``target_ids``, ``init_regions``, -``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` and -``rm_contexts`` under its debugfs directory, ``/damon/``. +DAMON exports nine files, ``DEPRECATED``, ``attrs``, ``target_ids``, +``init_regions``, ``schemes``, ``monitor_on_DEPRECATED``, ``kdamond_pid``, +``mk_contexts`` and ``rm_contexts`` under its debugfs directory, +``/damon/``. + + +``DEPRECATED`` is a read-only file for the DAMON debugfs interface deprecation +notice. Reading it returns the deprecation notice, as below:: + + # cat DEPRECATED + DAMON debugfs interface is deprecated, so users should move to DAMON_SYSFS. If you cannot, please report your usecase to damon@lists.linux.dev and linux-mm@kvack.org. Attributes @@ -755,19 +747,17 @@ Action ~~~~~~ The ```` is a predefined integer for memory management :ref:`actions -`. The supported numbers and their meanings are as -below. - - - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Ignored if - ``target`` is ``paddr``. - - 1: Call ``madvise()`` for the region with ``MADV_COLD``. Ignored if - ``target`` is ``paddr``. - - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. - - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. Ignored if - ``target`` is ``paddr``. - - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. Ignored if - ``target`` is ``paddr``. - - 5: Do nothing but count the statistics +`. The mapping between the ```` values and +the memory management actions is as below. For the detailed meaning of the +action and DAMON operations set supporting each action, please refer to the +list on :ref:`design doc `. + + - 0: ``willneed`` + - 1: ``cold`` + - 2: ``pageout`` + - 3: ``hugepage`` + - 4: ``nohugepage`` + - 5: ``stat`` Quota ~~~~~ @@ -848,16 +838,16 @@ Turning On/Off Setting the files as described above doesn't incur effect unless you explicitly start the monitoring. You can start, stop, and check the current status of the -monitoring by writing to and reading from the ``monitor_on`` file. Writing -``on`` to the file starts the monitoring of the targets with the attributes. -Writing ``off`` to the file stops those. DAMON also stops if every target -process is terminated. Below example commands turn on, off, and check the -status of DAMON:: +monitoring by writing to and reading from the ``monitor_on_DEPRECATED`` file. +Writing ``on`` to the file starts the monitoring of the targets with the +attributes. Writing ``off`` to the file stops those. DAMON also stops if +every target process is terminated. Below example commands turn on, off, and +check the status of DAMON:: # cd /damon - # echo on > monitor_on - # echo off > monitor_on - # cat monitor_on + # echo on > monitor_on_DEPRECATED + # echo off > monitor_on_DEPRECATED + # cat monitor_on_DEPRECATED off Please note that you cannot write to the above-mentioned debugfs files while @@ -873,11 +863,11 @@ can get the pid of the thread by reading the ``kdamond_pid`` file. When the monitoring is turned off, reading the file returns ``none``. :: # cd /damon - # cat monitor_on + # cat monitor_on_DEPRECATED off # cat kdamond_pid none - # echo on > monitor_on + # echo on > monitor_on_DEPRECATED # cat kdamond_pid 18594 @@ -907,5 +897,5 @@ directory by putting the name of the context to the ``rm_contexts`` file. :: # ls foo # ls: cannot access 'foo': No such file or directory -Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on`` files are in the -root directory only. +Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on_DEPRECATED`` files +are in the root directory only. diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst index eca38fa81e0f98..a70f20ce1ffb4f 100644 --- a/Documentation/admin-guide/mm/numa_memory_policy.rst +++ b/Documentation/admin-guide/mm/numa_memory_policy.rst @@ -250,6 +250,15 @@ MPOL_PREFERRED_MANY can fall back to all existing numa nodes. This is effectively MPOL_PREFERRED allowed for a mask rather than a single node. +MPOL_WEIGHTED_INTERLEAVE + This mode operates the same as MPOL_INTERLEAVE, except that + interleaving behavior is executed based on weights set in + /sys/kernel/mm/mempolicy/weighted_interleave/ + + Weighted interleave allocates pages on nodes according to a + weight. For example if nodes [0,1] are weighted [5,2], 5 pages + will be allocated on node0 for every 2 pages allocated on node1. + NUMA memory policy supports the following optional mode flags: MPOL_F_STATIC_NODES diff --git a/Documentation/admin-guide/pm/amd-pstate.rst b/Documentation/admin-guide/pm/amd-pstate.rst index 9eb26014d34b6c..1e0d101b020a08 100644 --- a/Documentation/admin-guide/pm/amd-pstate.rst +++ b/Documentation/admin-guide/pm/amd-pstate.rst @@ -300,8 +300,8 @@ platforms. The AMD P-States mechanism is the more performance and energy efficiency frequency management method on AMD processors. -AMD Pstate Driver Operation Modes -================================= +``amd-pstate`` Driver Operation Modes +====================================== ``amd_pstate`` CPPC has 3 operation modes: autonomous (active) mode, non-autonomous (passive) mode and guided autonomous (guided) mode. @@ -353,6 +353,48 @@ is activated. In this mode, driver requests minimum and maximum performance level and the platform autonomously selects a performance level in this range and appropriate to the current workload. +``amd-pstate`` Preferred Core +================================= + +The core frequency is subjected to the process variation in semiconductors. +Not all cores are able to reach the maximum frequency respecting the +infrastructure limits. Consequently, AMD has redefined the concept of +maximum frequency of a part. This means that a fraction of cores can reach +maximum frequency. To find the best process scheduling policy for a given +scenario, OS needs to know the core ordering informed by the platform through +highest performance capability register of the CPPC interface. + +``amd-pstate`` preferred core enables the scheduler to prefer scheduling on +cores that can achieve a higher frequency with lower voltage. The preferred +core rankings can dynamically change based on the workload, platform conditions, +thermals and ageing. + +The priority metric will be initialized by the ``amd-pstate`` driver. The ``amd-pstate`` +driver will also determine whether or not ``amd-pstate`` preferred core is +supported by the platform. + +``amd-pstate`` driver will provide an initial core ordering when the system boots. +The platform uses the CPPC interfaces to communicate the core ranking to the +operating system and scheduler to make sure that OS is choosing the cores +with highest performance firstly for scheduling the process. When ``amd-pstate`` +driver receives a message with the highest performance change, it will +update the core ranking and set the cpu's priority. + +``amd-pstate`` Preferred Core Switch +===================================== +Kernel Parameters +----------------- + +``amd-pstate`` peferred core`` has two states: enable and disable. +Enable/disable states can be chosen by different kernel parameters. +Default enable ``amd-pstate`` preferred core. + +``amd_prefcore=disable`` + +For systems that support ``amd-pstate`` preferred core, the core rankings will +always be advertised by the platform. But OS can choose to ignore that via the +kernel parameter ``amd_prefcore=disable``. + User Space Interface in ``sysfs`` - General =========================================== @@ -385,6 +427,19 @@ control its functionality at the system level. They are located in the to the operation mode represented by that string - or to be unregistered in the "disable" case. +``prefcore`` + Preferred core state of the driver: "enabled" or "disabled". + + "enabled" + Enable the ``amd-pstate`` preferred core. + + "disabled" + Disable the ``amd-pstate`` preferred core + + + This attribute is read-only to check the state of preferred core set + by the kernel parameter. + ``cpupower`` tool support for ``amd-pstate`` =============================================== diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 6584a1f9bfe39d..a9b71190399d9e 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -594,6 +594,9 @@ default (``MSGMNB``). ``msgmni`` is the maximum number of IPC queues. 32000 by default (``MSGMNI``). +All of these parameters are set per ipc namespace. The maximum number of bytes +in POSIX message queues is limited by ``RLIMIT_MSGQUEUE``. This limit is +respected hierarchically in the each user namespace. msg_next_id, sem_next_id, and shm_next_id (System V IPC) ======================================================== @@ -850,6 +853,7 @@ bit 3 print locks info if ``CONFIG_LOCKDEP`` is on bit 4 print ftrace buffer bit 5 print all printk messages in buffer bit 6 print all CPUs backtrace (if available in the arch) +bit 7 print only tasks in uninterruptible (blocked) state ===== ============================================ So for example to print tasks and memory info on panic, user can:: @@ -1274,15 +1278,20 @@ are doing anyway :) shmall ====== -This parameter sets the total amount of shared memory pages that -can be used system wide. Hence, ``shmall`` should always be at least -``ceil(shmmax/PAGE_SIZE)``. +This parameter sets the total amount of shared memory pages that can be used +inside ipc namespace. The shared memory pages counting occurs for each ipc +namespace separately and is not inherited. Hence, ``shmall`` should always be at +least ``ceil(shmmax/PAGE_SIZE)``. If you are not sure what the default ``PAGE_SIZE`` is on your Linux system, you can run the following command:: # getconf PAGE_SIZE +To reduce or disable the ability to allocate shared memory, you must create a +new ipc namespace, set this parameter to the required value and prohibit the +creation of a new ipc namespace in the current user namespace or cgroups can +be used. shmmax ====== diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 92a8a07f5c438c..f92551539e8a66 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -34,7 +34,7 @@ name of the command ('Comm:') that triggered the event:: You'll find a 'Not tainted: ' there if the kernel was not tainted at the time of the event; if it was, then it will print 'Tainted: ' and characters -either letters or blanks. In above example it looks like this:: +either letters or blanks. In the example above it looks like this:: Tainted: P W O @@ -52,7 +52,7 @@ At runtime, you can query the tainted state by reading tainted; any other number indicates the reasons why it is. The easiest way to decode that number is the script ``tools/debugging/kernel-chktaint``, which your distribution might ship as part of a package called ``linux-tools`` or -``kernel-tools``; if it doesn't you can download the script from +``kernel-tools``; if it doesn't, you can download the script from `git.kernel.org `_ and execute it with ``sh kernel-chktaint``, which would print something like this on the machine that had the statements in the logs that were quoted earlier:: diff --git a/Documentation/arch/arm64/silicon-errata.rst b/Documentation/arch/arm64/silicon-errata.rst index e8c2ce1f9df68d..d33e27c5ce6108 100644 --- a/Documentation/arch/arm64/silicon-errata.rst +++ b/Documentation/arch/arm64/silicon-errata.rst @@ -35,8 +35,9 @@ can be triggered by Linux). For software workarounds that may adversely impact systems unaffected by the erratum in question, a Kconfig entry is added under "Kernel Features" -> "ARM errata workarounds via the alternatives framework". -These are enabled by default and patched in at runtime when an affected -CPU is detected. For less-intrusive workarounds, a Kconfig option is not +With the exception of workarounds for errata deemed "rare" by Arm, these +are enabled by default and patched in at runtime when an affected CPU is +detected. For less-intrusive workarounds, a Kconfig option is not available and the code is structured (preferably with a comment) in such a way that the erratum will not be hit. @@ -243,3 +244,10 @@ stable kernels. +----------------+-----------------+-----------------+-----------------------------+ | ASR | ASR8601 | #8601001 | N/A | +----------------+-----------------+-----------------+-----------------------------+ ++----------------+-----------------+-----------------+-----------------------------+ +| Microsoft | Azure Cobalt 100| #2139208 | ARM64_ERRATUM_2139208 | ++----------------+-----------------+-----------------+-----------------------------+ +| Microsoft | Azure Cobalt 100| #2067961 | ARM64_ERRATUM_2067961 | ++----------------+-----------------+-----------------+-----------------------------+ +| Microsoft | Azure Cobalt 100| #2253138 | ARM64_ERRATUM_2253138 | ++----------------+-----------------+-----------------+-----------------------------+ diff --git a/Documentation/arch/x86/amd-memory-encryption.rst b/Documentation/arch/x86/amd-memory-encryption.rst index 07caa8fff852ee..414bc7402ae7db 100644 --- a/Documentation/arch/x86/amd-memory-encryption.rst +++ b/Documentation/arch/x86/amd-memory-encryption.rst @@ -87,14 +87,14 @@ The state of SME in the Linux kernel can be documented as follows: kernel is non-zero). SME can also be enabled and activated in the BIOS. If SME is enabled and -activated in the BIOS, then all memory accesses will be encrypted and it will -not be necessary to activate the Linux memory encryption support. If the BIOS -merely enables SME (sets bit 23 of the MSR_AMD64_SYSCFG), then Linux can activate -memory encryption by default (CONFIG_AMD_MEM_ENCRYPT_ACTIVE_BY_DEFAULT=y) or -by supplying mem_encrypt=on on the kernel command line. However, if BIOS does -not enable SME, then Linux will not be able to activate memory encryption, even -if configured to do so by default or the mem_encrypt=on command line parameter -is specified. +activated in the BIOS, then all memory accesses will be encrypted and it +will not be necessary to activate the Linux memory encryption support. + +If the BIOS merely enables SME (sets bit 23 of the MSR_AMD64_SYSCFG), +then memory encryption can be enabled by supplying mem_encrypt=on on the +kernel command line. However, if BIOS does not enable SME, then Linux +will not be able to activate memory encryption, even if configured to do +so by default or the mem_encrypt=on command line parameter is specified. Secure Nested Paging (SNP) ========================== diff --git a/Documentation/arch/x86/mds.rst b/Documentation/arch/x86/mds.rst index e73fdff62c0aa1..c58c72362911cd 100644 --- a/Documentation/arch/x86/mds.rst +++ b/Documentation/arch/x86/mds.rst @@ -95,6 +95,9 @@ The kernel provides a function to invoke the buffer clearing: mds_clear_cpu_buffers() +Also macro CLEAR_CPU_BUFFERS can be used in ASM late in exit-to-user path. +Other than CFLAGS.ZF, this macro doesn't clobber any registers. + The mitigation is invoked on kernel/userspace, hypervisor/guest and C-state (idle) transitions. @@ -138,17 +141,30 @@ Mitigation points When transitioning from kernel to user space the CPU buffers are flushed on affected CPUs when the mitigation is not disabled on the kernel - command line. The migitation is enabled through the static key - mds_user_clear. - - The mitigation is invoked in prepare_exit_to_usermode() which covers - all but one of the kernel to user space transitions. The exception - is when we return from a Non Maskable Interrupt (NMI), which is - handled directly in do_nmi(). - - (The reason that NMI is special is that prepare_exit_to_usermode() can - enable IRQs. In NMI context, NMIs are blocked, and we don't want to - enable IRQs with NMIs blocked.) + command line. The mitigation is enabled through the feature flag + X86_FEATURE_CLEAR_CPU_BUF. + + The mitigation is invoked just before transitioning to userspace after + user registers are restored. This is done to minimize the window in + which kernel data could be accessed after VERW e.g. via an NMI after + VERW. + + **Corner case not handled** + Interrupts returning to kernel don't clear CPUs buffers since the + exit-to-user path is expected to do that anyways. But, there could be + a case when an NMI is generated in kernel after the exit-to-user path + has cleared the buffers. This case is not handled and NMI returning to + kernel don't clear CPU buffers because: + + 1. It is rare to get an NMI after VERW, but before returning to userspace. + 2. For an unprivileged user, there is no known way to make that NMI + less rare or target it. + 3. It would take a large number of these precisely-timed NMIs to mount + an actual attack. There's presumably not enough bandwidth. + 4. The NMI in question occurs after a VERW, i.e. when user state is + restored and most interesting data is already scrubbed. Whats left + is only the data that NMI touches, and that may or may not be of + any interest. 2. C-State transition diff --git a/Documentation/arch/x86/pti.rst b/Documentation/arch/x86/pti.rst index e08d35177bc028..57e8392f61d354 100644 --- a/Documentation/arch/x86/pti.rst +++ b/Documentation/arch/x86/pti.rst @@ -26,9 +26,9 @@ comments in pti.c). This approach helps to ensure that side-channel attacks leveraging the paging structures do not function when PTI is enabled. It can be -enabled by setting CONFIG_PAGE_TABLE_ISOLATION=y at compile time. -Once enabled at compile-time, it can be disabled at boot with the -'nopti' or 'pti=' kernel parameters (see kernel-parameters.txt). +enabled by setting CONFIG_MITIGATION_PAGE_TABLE_ISOLATION=y at compile +time. Once enabled at compile-time, it can be disabled at boot with +the 'nopti' or 'pti=' kernel parameters (see kernel-parameters.txt). Page Table Management ===================== diff --git a/Documentation/arch/x86/x86_64/fred.rst b/Documentation/arch/x86/x86_64/fred.rst new file mode 100644 index 00000000000000..9f57e7b91f7e7a --- /dev/null +++ b/Documentation/arch/x86/x86_64/fred.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================= +Flexible Return and Event Delivery (FRED) +========================================= + +Overview +======== + +The FRED architecture defines simple new transitions that change +privilege level (ring transitions). The FRED architecture was +designed with the following goals: + +1) Improve overall performance and response time by replacing event + delivery through the interrupt descriptor table (IDT event + delivery) and event return by the IRET instruction with lower + latency transitions. + +2) Improve software robustness by ensuring that event delivery + establishes the full supervisor context and that event return + establishes the full user context. + +The new transitions defined by the FRED architecture are FRED event +delivery and, for returning from events, two FRED return instructions. +FRED event delivery can effect a transition from ring 3 to ring 0, but +it is used also to deliver events incident to ring 0. One FRED +instruction (ERETU) effects a return from ring 0 to ring 3, while the +other (ERETS) returns while remaining in ring 0. Collectively, FRED +event delivery and the FRED return instructions are FRED transitions. + +In addition to these transitions, the FRED architecture defines a new +instruction (LKGS) for managing the state of the GS segment register. +The LKGS instruction can be used by 64-bit operating systems that do +not use the new FRED transitions. + +Furthermore, the FRED architecture is easy to extend for future CPU +architectures. + +Software based event dispatching +================================ + +FRED operates differently from IDT in terms of event handling. Instead +of directly dispatching an event to its handler based on the event +vector, FRED requires the software to dispatch an event to its handler +based on both the event's type and vector. Therefore, an event dispatch +framework must be implemented to facilitate the event-to-handler +dispatch process. The FRED event dispatch framework takes control +once an event is delivered, and employs a two-level dispatch. + +The first level dispatching is event type based, and the second level +dispatching is event vector based. + +Full supervisor/user context +============================ + +FRED event delivery atomically save and restore full supervisor/user +context upon event delivery and return. Thus it avoids the problem of +transient states due to %cr2 and/or %dr6, and it is no longer needed +to handle all the ugly corner cases caused by half baked entry states. + +FRED allows explicit unblock of NMI with new event return instructions +ERETS/ERETU, avoiding the mess caused by IRET which unconditionally +unblocks NMI, e.g., when an exception happens during NMI handling. + +FRED always restores the full value of %rsp, thus ESPFIX is no longer +needed when FRED is enabled. + +LKGS +==== + +LKGS behaves like the MOV to GS instruction except that it loads the +base address into the IA32_KERNEL_GS_BASE MSR instead of the GS +segment’s descriptor cache. With LKGS, it ends up with avoiding +mucking with kernel GS, i.e., an operating system can always operate +with its own GS base address. + +Because FRED event delivery from ring 3 and ERETU both swap the value +of the GS base address and that of the IA32_KERNEL_GS_BASE MSR, plus +the introduction of LKGS instruction, the SWAPGS instruction is no +longer needed when FRED is enabled, thus is disallowed (#UD). + +Stack levels +============ + +4 stack levels 0~3 are introduced to replace the nonreentrant IST for +event handling, and each stack level should be configured to use a +dedicated stack. + +The current stack level could be unchanged or go higher upon FRED +event delivery. If unchanged, the CPU keeps using the current event +stack. If higher, the CPU switches to a new event stack specified by +the MSR of the new stack level, i.e., MSR_IA32_FRED_RSP[123]. + +Only execution of a FRED return instruction ERET[US], could lower the +current stack level, causing the CPU to switch back to the stack it was +on before a previous event delivery that promoted the stack level. diff --git a/Documentation/arch/x86/x86_64/index.rst b/Documentation/arch/x86/x86_64/index.rst index a56070fc8e77a9..ad15e9bd623f68 100644 --- a/Documentation/arch/x86/x86_64/index.rst +++ b/Documentation/arch/x86/x86_64/index.rst @@ -15,3 +15,4 @@ x86_64 Support cpu-hotplug-spec machinecheck fsgs + fred diff --git a/Documentation/atomic_t.txt b/Documentation/atomic_t.txt index d7adc6d543db4f..bee3b1bca9a7b4 100644 --- a/Documentation/atomic_t.txt +++ b/Documentation/atomic_t.txt @@ -171,14 +171,14 @@ The rule of thumb: - RMW operations that are conditional are unordered on FAILURE, otherwise the above rules apply. -Except of course when an operation has an explicit ordering like: +Except of course when a successful operation has an explicit ordering like: {}_relaxed: unordered {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE {}_release: the W of the RMW (or atomic_set) is a RELEASE Where 'unordered' is against other memory locations. Address dependencies are -not defeated. +not defeated. Conditional operations are still unordered on FAILURE. Fully ordered primitives are ordered against everything prior and everything subsequent. Therefore a fully ordered primitive is like having an smp_mb() diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst index 7985c6615f3c2f..a8f5782bd83318 100644 --- a/Documentation/bpf/kfuncs.rst +++ b/Documentation/bpf/kfuncs.rst @@ -177,10 +177,10 @@ In addition to kfuncs' arguments, verifier may need more information about the type of kfunc(s) being registered with the BPF subsystem. To do so, we define flags on a set of kfuncs as follows:: - BTF_SET8_START(bpf_task_set) + BTF_KFUNCS_START(bpf_task_set) BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) - BTF_SET8_END(bpf_task_set) + BTF_KFUNCS_END(bpf_task_set) This set encodes the BTF ID of each kfunc listed above, and encodes the flags along with it. Ofcourse, it is also allowed to specify no flags. @@ -347,10 +347,10 @@ Once the kfunc is prepared for use, the final step to making it visible is registering it with the BPF subsystem. Registration is done per BPF program type. An example is shown below:: - BTF_SET8_START(bpf_task_set) + BTF_KFUNCS_START(bpf_task_set) BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) - BTF_SET8_END(bpf_task_set) + BTF_KFUNCS_END(bpf_task_set) static const struct btf_kfunc_id_set bpf_task_kfunc_set = { .owner = THIS_MODULE, diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index 245b6defc298c2..868d9f6177e36c 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -1,11 +1,11 @@ .. contents:: .. sectnum:: -======================================= -BPF Instruction Set Specification, v1.0 -======================================= +====================================== +BPF Instruction Set Architecture (ISA) +====================================== -This document specifies version 1.0 of the BPF instruction set. +This document specifies the BPF instruction set architecture (ISA). Documentation conventions ========================= @@ -97,6 +97,38 @@ Definitions A: 10000110 B: 11111111 10000110 +Conformance groups +------------------ + +An implementation does not need to support all instructions specified in this +document (e.g., deprecated instructions). Instead, a number of conformance +groups are specified. An implementation must support the base32 conformance +group and may support additional conformance groups, where supporting a +conformance group means it must support all instructions in that conformance +group. + +The use of named conformance groups enables interoperability between a runtime +that executes instructions, and tools as such compilers that generate +instructions for the runtime. Thus, capability discovery in terms of +conformance groups might be done manually by users or automatically by tools. + +Each conformance group has a short ASCII label (e.g., "base32") that +corresponds to a set of instructions that are mandatory. That is, each +instruction has one or more conformance groups of which it is a member. + +This document defines the following conformance groups: + +* base32: includes all instructions defined in this + specification unless otherwise noted. +* base64: includes base32, plus instructions explicitly noted + as being in the base64 conformance group. +* atomic32: includes 32-bit atomic operation instructions (see `Atomic operations`_). +* atomic64: includes atomic32, plus 64-bit atomic operation instructions. +* divmul32: includes 32-bit division, multiplication, and modulo instructions. +* divmul64: includes divmul32, plus 64-bit division, multiplication, + and modulo instructions. +* legacy: deprecated packet access instructions. + Instruction encoding ==================== @@ -144,7 +176,7 @@ Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. As discussed below in `64-bit immediate instructions`_, a 64-bit immediate -instruction uses a 64-bit immediate value that is constructed as follows. +instruction uses two 32-bit immediate values that are constructed as follows. The 64 bits following the basic instruction contain a pseudo instruction using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, and imm containing the high 32 bits of the immediate value. @@ -152,20 +184,15 @@ and imm containing the high 32 bits of the immediate value. This is depicted in the following figure:: basic_instruction - .-----------------------------. - | | - code:8 regs:8 offset:16 imm:32 unused:32 imm:32 - | | - '--------------' - pseudo instruction - -Thus the 64-bit immediate value is constructed as follows: - - imm64 = (next_imm << 32) | imm + .------------------------------. + | | + opcode:8 regs:8 offset:16 imm:32 unused:32 imm:32 + | | + '--------------' + pseudo instruction -where 'next_imm' refers to the imm value of the pseudo instruction -following the basic instruction. The unused bytes in the pseudo -instruction are reserved and shall be cleared to zero. +Here, the imm value of the pseudo instruction is called 'next_imm'. The unused +bytes in the pseudo instruction are reserved and shall be cleared to zero. Instruction classes ------------------- @@ -217,7 +244,8 @@ Arithmetic instructions ----------------------- ``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for -otherwise identical operations. +otherwise identical operations. ``BPF_ALU64`` instructions belong to the +base64 conformance group unless noted otherwise. The 'code' field encodes the operation as below, where 'src' and 'dst' refer to the values of the source and destination registers, respectively. @@ -262,15 +290,19 @@ where '(u32)' indicates that the upper 32 bits are zeroed. ``BPF_XOR | BPF_K | BPF_ALU`` means:: - dst = (u32) dst ^ (u32) imm32 + dst = (u32) dst ^ (u32) imm ``BPF_XOR | BPF_K | BPF_ALU64`` means:: - dst = dst ^ imm32 + dst = dst ^ imm Note that most instructions have instruction offset of 0. Only three instructions (``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset. +Division, multiplication, and modulo operations for ``BPF_ALU`` are part +of the "divmul32" conformance group, and division, multiplication, and +modulo operations for ``BPF_ALU64`` are part of the "divmul64" conformance +group. The division and modulo operations support both unsigned and signed flavors. For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``, @@ -295,7 +327,11 @@ The ``BPF_MOVSX`` instruction does a move operation with sign extension. ``BPF_ALU | BPF_MOVSX`` :term:`sign extends` 8-bit and 16-bit operands into 32 bit operands, and zeroes the remaining upper 32 bits. ``BPF_ALU64 | BPF_MOVSX`` :term:`sign extends` 8-bit, 16-bit, and 32-bit -operands into 64 bit operands. +operands into 64 bit operands. Unlike other arithmetic instructions, +``BPF_MOVSX`` is only defined for register source operands (``BPF_X``). + +The ``BPF_NEG`` instruction is only defined when the source bit is clear +(``BPF_K``). Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) for 32-bit operations. @@ -323,7 +359,9 @@ BPF_ALU64 Reserved 0x00 do byte swap unconditionally ========= ========= ===== ================================================= The 'imm' field encodes the width of the swap operations. The following widths -are supported: 16, 32 and 64. +are supported: 16, 32 and 64. Width 64 operations belong to the base64 +conformance group and other swap operations belong to the base32 +conformance group. Examples: @@ -348,31 +386,33 @@ Examples: Jump instructions ----------------- -``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for -otherwise identical operations. +``BPF_JMP32`` uses 32-bit wide operands and indicates the base32 +conformance group, while ``BPF_JMP`` uses 64-bit wide operands for +otherwise identical operations, and indicates the base64 conformance +group unless otherwise specified. The 'code' field encodes the operation as below: -======== ===== === =========================================== ========================================= -code value src description notes -======== ===== === =========================================== ========================================= -BPF_JA 0x0 0x0 PC += offset BPF_JMP class -BPF_JA 0x0 0x0 PC += imm BPF_JMP32 class +======== ===== === =============================== ============================================= +code value src description notes +======== ===== === =============================== ============================================= +BPF_JA 0x0 0x0 PC += offset BPF_JMP | BPF_K only +BPF_JA 0x0 0x0 PC += imm BPF_JMP32 | BPF_K only BPF_JEQ 0x1 any PC += offset if dst == src -BPF_JGT 0x2 any PC += offset if dst > src unsigned -BPF_JGE 0x3 any PC += offset if dst >= src unsigned +BPF_JGT 0x2 any PC += offset if dst > src unsigned +BPF_JGE 0x3 any PC += offset if dst >= src unsigned BPF_JSET 0x4 any PC += offset if dst & src BPF_JNE 0x5 any PC += offset if dst != src -BPF_JSGT 0x6 any PC += offset if dst > src signed -BPF_JSGE 0x7 any PC += offset if dst >= src signed -BPF_CALL 0x8 0x0 call helper function by address see `Helper functions`_ -BPF_CALL 0x8 0x1 call PC += imm see `Program-local functions`_ -BPF_CALL 0x8 0x2 call helper function by BTF ID see `Helper functions`_ -BPF_EXIT 0x9 0x0 return BPF_JMP only -BPF_JLT 0xa any PC += offset if dst < src unsigned -BPF_JLE 0xb any PC += offset if dst <= src unsigned -BPF_JSLT 0xc any PC += offset if dst < src signed -BPF_JSLE 0xd any PC += offset if dst <= src signed -======== ===== === =========================================== ========================================= +BPF_JSGT 0x6 any PC += offset if dst > src signed +BPF_JSGE 0x7 any PC += offset if dst >= src signed +BPF_CALL 0x8 0x0 call helper function by address BPF_JMP | BPF_K only, see `Helper functions`_ +BPF_CALL 0x8 0x1 call PC += imm BPF_JMP | BPF_K only, see `Program-local functions`_ +BPF_CALL 0x8 0x2 call helper function by BTF ID BPF_JMP | BPF_K only, see `Helper functions`_ +BPF_EXIT 0x9 0x0 return BPF_JMP | BPF_K only +BPF_JLT 0xa any PC += offset if dst < src unsigned +BPF_JLE 0xb any PC += offset if dst <= src unsigned +BPF_JSLT 0xc any PC += offset if dst < src signed +BPF_JSLE 0xd any PC += offset if dst <= src signed +======== ===== === =============================== ============================================= The BPF program needs to store the return value into register R0 before doing a ``BPF_EXIT``. @@ -398,6 +438,9 @@ specified by the 'imm' field. A > 16-bit conditional jump may be converted to a < 16-bit conditional jump plus a 32-bit unconditional jump. +All ``BPF_CALL`` and ``BPF_JA`` instructions belong to the +base32 conformance group. + Helper functions ~~~~~~~~~~~~~~~~ @@ -455,6 +498,8 @@ The size modifier is one of: BPF_DW 0x18 double word (8 bytes) ============= ===== ===================== +Instructions using ``BPF_DW`` belong to the base64 conformance group. + Regular load and store operations --------------------------------- @@ -467,7 +512,7 @@ instructions that transfer data between a register and memory. ``BPF_MEM | | BPF_ST`` means:: - *(size *) (dst + offset) = imm32 + *(size *) (dst + offset) = imm ``BPF_MEM | | BPF_LDX`` means:: @@ -499,8 +544,10 @@ by other BPF programs or means outside of this specification. All atomic operations supported by BPF are encoded as store operations that use the ``BPF_ATOMIC`` mode modifier as follows: -* ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations -* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations +* ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations, which are + part of the "atomic32" conformance group. +* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations, which are + part of the "atomic64" conformance group. * 8-bit and 16-bit wide atomic operations are not supported. The 'imm' field is used to encode the actual atomic operation. @@ -564,7 +611,7 @@ defined further below: ========================= ====== === ========================================= =========== ============== opcode construction opcode src pseudocode imm type dst type ========================= ====== === ========================================= =========== ============== -BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = (next_imm << 32) | imm integer integer BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data pointer BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer @@ -609,5 +656,8 @@ Legacy BPF Packet access instructions ------------------------------------- BPF previously introduced special instructions for access to packet data that were -carried over from classic BPF. However, these instructions are -deprecated and should no longer be used. +carried over from classic BPF. These instructions used an instruction +class of BPF_LD, a size modifier of BPF_W, BPF_H, or BPF_B, and a +mode modifier of BPF_ABS or BPF_IND. However, these instructions are +deprecated and should no longer be used. All legacy packet access +instructions belong to the "legacy" conformance group. diff --git a/Documentation/bpf/verifier.rst b/Documentation/bpf/verifier.rst index f0ec19db301c69..356894399fbf83 100644 --- a/Documentation/bpf/verifier.rst +++ b/Documentation/bpf/verifier.rst @@ -562,7 +562,7 @@ works:: * ``checkpoint[0].r1`` is marked as read; * At instruction #5 exit is reached and ``checkpoint[0]`` can now be processed - by ``clean_live_states()``. After this processing ``checkpoint[0].r0`` has a + by ``clean_live_states()``. After this processing ``checkpoint[0].r1`` has a read mark and all other registers and stack slots are marked as ``NOT_INIT`` or ``STACK_INVALID`` diff --git a/Documentation/conf.py b/Documentation/conf.py index 5830b01c56429d..da64c9fb7e0723 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -388,6 +388,12 @@ def get_cline_version(): verbatimhintsturnover=false, ''', + # + # Some of our authors are fond of deep nesting; tell latex to + # cope. + # + 'maxlistdepth': '10', + # For CJK One-half spacing, need to be in front of hyperref 'extrapackages': r'\usepackage{setspace}', diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst index 3599cf9267b476..ed73c612174d4c 100644 --- a/Documentation/core-api/workqueue.rst +++ b/Documentation/core-api/workqueue.rst @@ -77,10 +77,12 @@ wants a function to be executed asynchronously it has to set up a work item pointing to that function and queue that work item on a workqueue. -Special purpose threads, called worker threads, execute the functions -off of the queue, one after the other. If no work is queued, the -worker threads become idle. These worker threads are managed in so -called worker-pools. +A work item can be executed in either a thread or the BH (softirq) context. + +For threaded workqueues, special purpose threads, called [k]workers, execute +the functions off of the queue, one after the other. If no work is queued, +the worker threads become idle. These worker threads are managed in +worker-pools. The cmwq design differentiates between the user-facing workqueues that subsystems and drivers queue work items on and the backend mechanism @@ -91,6 +93,12 @@ for high priority ones, for each possible CPU and some extra worker-pools to serve work items queued on unbound workqueues - the number of these backing pools is dynamic. +BH workqueues use the same framework. However, as there can only be one +concurrent execution context, there's no need to worry about concurrency. +Each per-CPU BH worker pool contains only one pseudo worker which represents +the BH execution context. A BH workqueue can be considered a convenience +interface to softirq. + Subsystems and drivers can create and queue work items through special workqueue API functions as they see fit. They can influence some aspects of the way the work items are executed by setting flags on the @@ -106,7 +114,7 @@ unless specifically overridden, a work item of a bound workqueue will be queued on the worklist of either normal or highpri worker-pool that is associated to the CPU the issuer is running on. -For any worker pool implementation, managing the concurrency level +For any thread pool implementation, managing the concurrency level (how many execution contexts are active) is an important issue. cmwq tries to keep the concurrency at a minimal but sufficient level. Minimal to save resources and sufficient in that the system is used at @@ -164,6 +172,17 @@ resources, scheduled and executed. ``flags`` --------- +``WQ_BH`` + BH workqueues can be considered a convenience interface to softirq. BH + workqueues are always per-CPU and all BH work items are executed in the + queueing CPU's softirq context in the queueing order. + + All BH workqueues must have 0 ``max_active`` and ``WQ_HIGHPRI`` is the + only allowed additional flag. + + BH work items cannot sleep. All other features such as delayed queueing, + flushing and canceling are supported. + ``WQ_UNBOUND`` Work items queued to an unbound wq are served by the special worker-pools which host workers which are not bound to any @@ -237,15 +256,11 @@ may queue at the same time. Unless there is a specific need for throttling the number of active work items, specifying '0' is recommended. -Some users depend on the strict execution ordering of ST wq. The -combination of ``@max_active`` of 1 and ``WQ_UNBOUND`` used to -achieve this behavior. Work items on such wq were always queued to the -unbound worker-pools and only one work item could be active at any given -time thus achieving the same ordering property as ST wq. - -In the current implementation the above configuration only guarantees -ST behavior within a given NUMA node. Instead ``alloc_ordered_workqueue()`` should -be used to achieve system-wide ST behavior. +Some users depend on strict execution ordering where only one work item +is in flight at any given time and the work items are processed in +queueing order. While the combination of ``@max_active`` of 1 and +``WQ_UNBOUND`` used to achieve this behavior, this is no longer the +case. Use ``alloc_ordered_queue()`` instead. Example Execution Scenarios diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst index c3389c6f38381f..12796899584739 100644 --- a/Documentation/dev-tools/checkpatch.rst +++ b/Documentation/dev-tools/checkpatch.rst @@ -168,7 +168,7 @@ Available options: - --fix - This is an EXPERIMENTAL feature. If correctable errors exists, a file + This is an EXPERIMENTAL feature. If correctable errors exist, a file .EXPERIMENTAL-checkpatch-fixes is created which has the automatically fixable errors corrected. @@ -181,7 +181,7 @@ Available options: - --ignore-perl-version - Override checking of perl version. Runtime errors maybe encountered after + Override checking of perl version. Runtime errors may be encountered after enabling this flag if the perl version does not meet the minimum specified. - --codespell diff --git a/Documentation/dev-tools/kasan.rst b/Documentation/dev-tools/kasan.rst index 858c77fe7dc46c..d7de44f5339d43 100644 --- a/Documentation/dev-tools/kasan.rst +++ b/Documentation/dev-tools/kasan.rst @@ -169,7 +169,7 @@ Error reports A typical KASAN report looks like this:: ================================================================== - BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [kasan_test] Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 @@ -179,8 +179,8 @@ A typical KASAN report looks like this:: 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] + kmalloc_oob_right+0xa8/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -200,8 +200,8 @@ A typical KASAN report looks like this:: 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] + kmalloc_oob_right+0x56/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -277,6 +277,27 @@ traces point to places in code that interacted with the object but that are not directly present in the bad access stack trace. Currently, this includes call_rcu() and workqueue queuing. +CONFIG_KASAN_EXTRA_INFO +~~~~~~~~~~~~~~~~~~~~~~~ + +Enabling CONFIG_KASAN_EXTRA_INFO allows KASAN to record and report more +information. The extra information currently supported is the CPU number and +timestamp at allocation and free. More information can help find the cause of +the bug and correlate the error with other system events, at the cost of using +extra memory to record more information (more cost details in the help text of +CONFIG_KASAN_EXTRA_INFO). + +Here is the report with CONFIG_KASAN_EXTRA_INFO enabled (only the +different parts are shown):: + + ================================================================== + ... + Allocated by task 134 on cpu 5 at 229.133855s: + ... + Freed by task 136 on cpu 3 at 230.199335s: + ... + ================================================================== + Implementation details ---------------------- @@ -510,15 +531,15 @@ When a test passes:: When a test fails due to a failed ``kmalloc``:: - # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 + # kmalloc_large_oob_right: ASSERTION FAILED at mm/kasan/kasan_test.c:245 Expected ptr is not null, but is - not ok 4 - kmalloc_large_oob_right + not ok 5 - kmalloc_large_oob_right When a test fails due to a missing KASAN report:: - # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + # kmalloc_double_kzfree: EXPECTATION FAILED at mm/kasan/kasan_test.c:709 KASAN failure expected in "kfree_sensitive(ptr)", but none occurred - not ok 44 - kmalloc_double_kzfree + not ok 28 - kmalloc_double_kzfree At the end the cumulative status of all KASAN tests is printed. On success:: @@ -534,7 +555,7 @@ There are a few ways to run KUnit-compatible KASAN tests. 1. Loadable module With ``CONFIG_KUNIT`` enabled, KASAN-KUnit tests can be built as a loadable - module and run by loading ``test_kasan.ko`` with ``insmod`` or ``modprobe``. + module and run by loading ``kasan_test.ko`` with ``insmod`` or ``modprobe``. 2. Built-In diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 7f3582a67318be..ff10dc6eef5d91 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -259,9 +259,21 @@ Contributing new tests (details) TEST_PROGS_EXTENDED, TEST_GEN_PROGS_EXTENDED mean it is the executable which is not tested by default. + TEST_FILES, TEST_GEN_FILES mean it is the file which is used by test. + TEST_INCLUDES is similar to TEST_FILES, it lists files which should be + included when exporting or installing the tests, with the following + differences: + + * symlinks to files in other directories are preserved + * the part of paths below tools/testing/selftests/ is preserved when + copying the files to the output directory + + TEST_INCLUDES is meant to list dependencies located in other directories of + the selftests hierarchy. + * First use the headers inside the kernel source and/or git repo, and then the system headers. Headers for the kernel release as opposed to headers installed by the distro on the system should be the primary focus to be able diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index a9efab50eed83e..22955d56b3799b 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -671,8 +671,23 @@ Testing Static Functions ------------------------ If we do not want to expose functions or variables for testing, one option is to -conditionally ``#include`` the test file at the end of your .c file. For -example: +conditionally export the used symbol. For example: + +.. code-block:: c + + /* In my_file.c */ + + VISIBLE_IF_KUNIT int do_interesting_thing(); + EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing); + + /* In my_file.h */ + + #if IS_ENABLED(CONFIG_KUNIT) + int do_interesting_thing(void); + #endif + +Alternatively, you could conditionally ``#include`` the test file at the end of +your .c file. For example: .. code-block:: c diff --git a/Documentation/dev-tools/ubsan.rst b/Documentation/dev-tools/ubsan.rst index 2de7c63415da0e..e3591f8e9d5b4d 100644 --- a/Documentation/dev-tools/ubsan.rst +++ b/Documentation/dev-tools/ubsan.rst @@ -49,34 +49,22 @@ Report example Usage ----- -To enable UBSAN configure kernel with:: +To enable UBSAN, configure the kernel with:: - CONFIG_UBSAN=y + CONFIG_UBSAN=y -and to check the entire kernel:: - - CONFIG_UBSAN_SANITIZE_ALL=y - -To enable instrumentation for specific files or directories, add a line -similar to the following to the respective kernel Makefile: - -- For a single file (e.g. main.o):: - - UBSAN_SANITIZE_main.o := y - -- For all files in one directory:: - - UBSAN_SANITIZE := y - -To exclude files from being instrumented even if -``CONFIG_UBSAN_SANITIZE_ALL=y``, use:: +To exclude files from being instrumented use:: UBSAN_SANITIZE_main.o := n -and:: +and to exclude all targets in one directory use:: UBSAN_SANITIZE := n +When disabled for all targets, specific files can be enabled using:: + + UBSAN_SANITIZE_main.o := y + Detection of unaligned accesses controlled through the separate option - CONFIG_UBSAN_ALIGNMENT. It's off by default on architectures that support unaligned accesses (CONFIG_HAVE_EFFICIENT_UNALIGNED_ACCESS=y). One could diff --git a/Documentation/devicetree/bindings/Makefile b/Documentation/devicetree/bindings/Makefile index 2323fd5b7cdae1..5e08e3a6a97b10 100644 --- a/Documentation/devicetree/bindings/Makefile +++ b/Documentation/devicetree/bindings/Makefile @@ -28,7 +28,10 @@ $(obj)/%.example.dts: $(src)/%.yaml check_dtschema_version FORCE find_all_cmd = find $(srctree)/$(src) \( -name '*.yaml' ! \ -name 'processed-schema*' \) -find_cmd = $(find_all_cmd) | sed 's|^$(srctree)/$(src)/||' | grep -F -e "$(subst :," -e ",$(DT_SCHEMA_FILES))" | sed 's|^|$(srctree)/$(src)/|' +find_cmd = $(find_all_cmd) | \ + sed 's|^$(srctree)/||' | \ + grep -F -e "$(subst :," -e ",$(DT_SCHEMA_FILES))" | \ + sed 's|^|$(srctree)/|' CHK_DT_DOCS := $(shell $(find_cmd)) quiet_cmd_yamllint = LINT $(src) @@ -61,9 +64,6 @@ override DTC_FLAGS := \ -Wno-unique_unit_address \ -Wunique_unit_address_if_enabled -# Disable undocumented compatible checks until warning free -override DT_CHECKER_FLAGS ?= - $(obj)/processed-schema.json: $(DT_DOCS) $(src)/.yamllint check_dtschema_version FORCE $(call if_changed_rule,chkdt) diff --git a/Documentation/devicetree/bindings/arm/amlogic.yaml b/Documentation/devicetree/bindings/arm/amlogic.yaml index caab7ceeda45a8..ce0ea36de0c09b 100644 --- a/Documentation/devicetree/bindings/arm/amlogic.yaml +++ b/Documentation/devicetree/bindings/arm/amlogic.yaml @@ -146,6 +146,7 @@ properties: - enum: - amediatech,x96-max - amlogic,u200 + - freebox,fbx8am - radxa,zero - seirobotics,sei510 - const: amlogic,g12a diff --git a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml index 749ee54a3ff83a..7dfcdc2d571eb0 100644 --- a/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml +++ b/Documentation/devicetree/bindings/arm/aspeed/aspeed.yaml @@ -35,7 +35,10 @@ properties: - ampere,mtjade-bmc - aspeed,ast2500-evb - asrock,e3c246d4i-bmc + - asrock,e3c256d4i-bmc - asrock,romed8hm3-bmc + - asrock,spc621d8hm3-bmc + - asrock,x570d4u-bmc - bytedance,g220a-bmc - facebook,cmm-bmc - facebook,minipack-bmc @@ -79,6 +82,7 @@ properties: - facebook,elbert-bmc - facebook,fuji-bmc - facebook,greatlakes-bmc + - facebook,harma-bmc - facebook,minerva-cmc - facebook,yosemite4-bmc - ibm,everest-bmc diff --git a/Documentation/devicetree/bindings/arm/fsl.yaml b/Documentation/devicetree/bindings/arm/fsl.yaml index 228dcc5c7d6f3e..39378879777b89 100644 --- a/Documentation/devicetree/bindings/arm/fsl.yaml +++ b/Documentation/devicetree/bindings/arm/fsl.yaml @@ -384,7 +384,8 @@ properties: - toradex,apalis_imx6q-ixora # Apalis iMX6Q/D Module on Ixora Carrier Board - toradex,apalis_imx6q-ixora-v1.1 # Apalis iMX6Q/D Module on Ixora V1.1 Carrier Board - toradex,apalis_imx6q-ixora-v1.2 # Apalis iMX6Q/D Module on Ixora V1.2 Carrier Board - - toradex,apalis_imx6q-eval # Apalis iMX6Q/D Module on Apalis Evaluation Board + - toradex,apalis_imx6q-eval # Apalis iMX6Q/D Module on Apalis Evaluation Board v1.0/v1.1 + - toradex,apalis_imx6q-eval-v1.2 # Apalis iMX6Q/D Module on Apalis Evaluation Board v1.2 - const: toradex,apalis_imx6q - const: fsl,imx6q @@ -469,6 +470,7 @@ properties: - prt,prtvt7 # Protonic VT7 board - rex,imx6dl-rex-basic # Rex Basic i.MX6 Dual Lite Board - riot,imx6s-riotboard # RIoTboard i.MX6S + - sielaff,imx6dl-board # Sielaff i.MX6 Solo Board - skov,imx6dl-skov-revc-lt2 # SKOV IMX6 CPU SoloCore lt2 - skov,imx6dl-skov-revc-lt6 # SKOV IMX6 CPU SoloCore lt6 - solidrun,cubox-i/dl # SolidRun Cubox-i Solo/DualLite @@ -1026,7 +1028,7 @@ properties: items: - enum: - dimonoff,gateway-evk # i.MX8MN Dimonoff Gateway EVK Board - - rve,rve-gateway # i.MX8MN RVE Gateway Board + - rve,gateway # i.MX8MN RVE Gateway Board - variscite,var-som-mx8mn-symphony - const: variscite,var-som-mx8mn - const: fsl,imx8mn @@ -1194,7 +1196,8 @@ properties: - description: i.MX8QM Boards with Toradex Apalis iMX8 Modules items: - enum: - - toradex,apalis-imx8-eval # Apalis iMX8 Module on Apalis Evaluation Board + - toradex,apalis-imx8-eval # Apalis iMX8 Module on Apalis Evaluation V1.0/V1.1 Board + - toradex,apalis-imx8-eval-v1.2 # Apalis iMX8 Module on Apalis Evaluation V1.2 Board - toradex,apalis-imx8-ixora-v1.1 # Apalis iMX8 Module on Ixora V1.1 Carrier Board - const: toradex,apalis-imx8 - const: fsl,imx8qm @@ -1202,7 +1205,8 @@ properties: - description: i.MX8QM Boards with Toradex Apalis iMX8 V1.1 Modules items: - enum: - - toradex,apalis-imx8-v1.1-eval # Apalis iMX8 V1.1 Module on Apalis Eval. Board + - toradex,apalis-imx8-v1.1-eval # Apalis iMX8 V1.1 Module on Apalis Eval. V1.0/V1.1 Board + - toradex,apalis-imx8-v1.1-eval-v1.2 # Apalis iMX8 V1.1 Module on Apalis Eval. V1.2 Board - toradex,apalis-imx8-v1.1-ixora-v1.1 # Apalis iMX8 V1.1 Module on Ixora V1.1 C. Board - toradex,apalis-imx8-v1.1-ixora-v1.2 # Apalis iMX8 V1.1 Module on Ixora V1.2 C. Board - const: toradex,apalis-imx8-v1.1 @@ -1232,6 +1236,22 @@ properties: - const: toradex,colibri-imx8x - const: fsl,imx8qxp + - description: + TQMa8Xx is a series of SOM featuring NXP i.MX8X system-on-chip + variants. It is designed to be clicked on different carrier boards + MBa8Xx is the starterkit + oneOf: + - items: + - enum: + - tq,imx8dxp-tqma8xdp-mba8xx # TQ-Systems GmbH TQMa8XDP SOM on MBa8Xx + - const: tq,imx8dxp-tqma8xdp # TQ-Systems GmbH TQMa8XDP SOM (with i.MX8DXP) + - const: fsl,imx8dxp + - items: + - enum: + - tq,imx8qxp-tqma8xqp-mba8xx # TQ-Systems GmbH TQMa8XQP SOM on MBa8Xx + - const: tq,imx8qxp-tqma8xqp # TQ-Systems GmbH TQMa8XQP SOM (with i.MX8QXP) + - const: fsl,imx8qxp + - description: i.MX8ULP based Boards items: - enum: @@ -1275,6 +1295,18 @@ properties: - const: tq,imx93-tqma9352 # TQ-Systems GmbH i.MX93 TQMa93xxCA/LA SOM - const: fsl,imx93 + - description: PHYTEC phyCORE-i.MX93 SoM based boards + items: + - const: phytec,imx93-phyboard-segin # phyBOARD-Segin with i.MX93 + - const: phytec,imx93-phycore-som # phyCORE-i.MX93 SoM + - const: fsl,imx93 + + - description: Variscite VAR-SOM-MX93 based boards + items: + - const: variscite,var-som-mx93-symphony + - const: variscite,var-som-mx93 + - const: fsl,imx93 + - description: Freescale Vybrid Platform Device Tree Bindings diff --git a/Documentation/devicetree/bindings/arm/mediatek.yaml b/Documentation/devicetree/bindings/arm/mediatek.yaml index 6f2f64ae76fcf3..09f9ffd3ff7b2c 100644 --- a/Documentation/devicetree/bindings/arm/mediatek.yaml +++ b/Documentation/devicetree/bindings/arm/mediatek.yaml @@ -17,6 +17,7 @@ properties: const: '/' compatible: oneOf: + # Sort by SoC (last) compatible, then board compatible - items: - enum: - mediatek,mt2701-evb @@ -84,6 +85,11 @@ properties: - const: mediatek,mt7629 - items: - enum: + - xiaomi,ax3000t + - const: mediatek,mt7981b + - items: + - enum: + - acelink,ew-7886cax - bananapi,bpi-r3 - mediatek,mt7986a-rfb - const: mediatek,mt7986a @@ -91,6 +97,10 @@ properties: - enum: - mediatek,mt7986b-rfb - const: mediatek,mt7986b + - items: + - enum: + - bananapi,bpi-r4 + - const: mediatek,mt7988a - items: - enum: - mediatek,mt8127-moose @@ -129,75 +139,10 @@ properties: - enum: - mediatek,mt8173-evb - const: mediatek,mt8173 - - items: - - enum: - - mediatek,mt8183-evb - - const: mediatek,mt8183 - - description: Google Hayato rev5 - items: - - const: google,hayato-rev5-sku2 - - const: google,hayato-sku2 - - const: google,hayato - - const: mediatek,mt8192 - - description: Google Hayato - items: - - const: google,hayato-rev1 - - const: google,hayato - - const: mediatek,mt8192 - - description: Google Spherion rev4 (Acer Chromebook 514) - items: - - const: google,spherion-rev4 - - const: google,spherion - - const: mediatek,mt8192 - - description: Google Spherion (Acer Chromebook 514) - items: - - const: google,spherion-rev3 - - const: google,spherion-rev2 - - const: google,spherion-rev1 - - const: google,spherion-rev0 - - const: google,spherion - - const: mediatek,mt8192 - - description: Acer Tomato (Acer Chromebook Spin 513 CP513-2H) - items: - - enum: - - google,tomato-rev2 - - google,tomato-rev1 - - const: google,tomato - - const: mediatek,mt8195 - - description: Acer Tomato rev3 - 4 (Acer Chromebook Spin 513 CP513-2H) - items: - - const: google,tomato-rev4 - - const: google,tomato-rev3 - - const: google,tomato - - const: mediatek,mt8195 - - items: - - enum: - - mediatek,mt8186-evb - - const: mediatek,mt8186 - - items: - - enum: - - mediatek,mt8188-evb - - const: mediatek,mt8188 - - items: - - enum: - - mediatek,mt8192-evb - - const: mediatek,mt8192 - - items: - - enum: - - mediatek,mt8195-demo - - mediatek,mt8195-evb - - const: mediatek,mt8195 - description: Google Burnet (HP Chromebook x360 11MK G3 EE) items: - const: google,burnet - const: mediatek,mt8183 - - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) - items: - - enum: - - google,krane-sku0 - - google,krane-sku176 - - const: google,krane - - const: mediatek,mt8183 - description: Google Cozmo (Acer Chromebook 314) items: - const: google,cozmo @@ -255,6 +200,13 @@ properties: - google,kodama-sku32 - const: google,kodama - const: mediatek,mt8183 + - description: Google Krane (Lenovo IdeaPad Duet, 10e,...) + items: + - enum: + - google,krane-sku0 + - google,krane-sku176 + - const: google,krane + - const: mediatek,mt8183 - description: Google Makomo (Lenovo 100e Chromebook 2nd Gen MTK 2) items: - enum: @@ -276,10 +228,125 @@ properties: - google,willow-sku1 - const: google,willow - const: mediatek,mt8183 + - items: + - enum: + - mediatek,mt8183-evb + - const: mediatek,mt8183 - items: - enum: - mediatek,mt8183-pumpkin - const: mediatek,mt8183 + - description: Google Magneton (Lenovo IdeaPad Slim 3 Chromebook (14M868)) + items: + - const: google,steelix-sku393219 + - const: google,steelix-sku393216 + - const: google,steelix + - const: mediatek,mt8186 + - description: Google Magneton (Lenovo IdeaPad Slim 3 Chromebook (14M868)) + items: + - const: google,steelix-sku393220 + - const: google,steelix-sku393217 + - const: google,steelix + - const: mediatek,mt8186 + - description: Google Magneton (Lenovo IdeaPad Slim 3 Chromebook (14M868)) + items: + - const: google,steelix-sku393221 + - const: google,steelix-sku393218 + - const: google,steelix + - const: mediatek,mt8186 + - description: Google Rusty (Lenovo 100e Chromebook Gen 4) + items: + - const: google,steelix-sku196609 + - const: google,steelix-sku196608 + - const: google,steelix + - const: mediatek,mt8186 + - description: Google Steelix (Lenovo 300e Yoga Chromebook Gen 4) + items: + - enum: + - google,steelix-sku131072 + - google,steelix-sku131073 + - const: google,steelix + - const: mediatek,mt8186 + - description: Google Tentacruel (ASUS Chromebook CM14 Flip CM1402F) + items: + - const: google,tentacruel-sku262147 + - const: google,tentacruel-sku262146 + - const: google,tentacruel-sku262145 + - const: google,tentacruel-sku262144 + - const: google,tentacruel + - const: mediatek,mt8186 + - description: Google Tentacruel (ASUS Chromebook CM14 Flip CM1402F) + items: + - const: google,tentacruel-sku262151 + - const: google,tentacruel-sku262150 + - const: google,tentacruel-sku262149 + - const: google,tentacruel-sku262148 + - const: google,tentacruel + - const: mediatek,mt8186 + - description: Google Tentacool (ASUS Chromebook CM14 CM1402C) + items: + - const: google,tentacruel-sku327681 + - const: google,tentacruel + - const: mediatek,mt8186 + - description: Google Tentacool (ASUS Chromebook CM14 CM1402C) + items: + - const: google,tentacruel-sku327683 + - const: google,tentacruel + - const: mediatek,mt8186 + - items: + - enum: + - mediatek,mt8186-evb + - const: mediatek,mt8186 + - items: + - enum: + - mediatek,mt8188-evb + - const: mediatek,mt8188 + - description: Google Hayato + items: + - const: google,hayato-rev1 + - const: google,hayato + - const: mediatek,mt8192 + - description: Google Hayato rev5 + items: + - const: google,hayato-rev5-sku2 + - const: google,hayato-sku2 + - const: google,hayato + - const: mediatek,mt8192 + - description: Google Spherion (Acer Chromebook 514) + items: + - const: google,spherion-rev3 + - const: google,spherion-rev2 + - const: google,spherion-rev1 + - const: google,spherion-rev0 + - const: google,spherion + - const: mediatek,mt8192 + - description: Google Spherion rev4 (Acer Chromebook 514) + items: + - const: google,spherion-rev4 + - const: google,spherion + - const: mediatek,mt8192 + - items: + - enum: + - mediatek,mt8192-evb + - const: mediatek,mt8192 + - description: Acer Tomato (Acer Chromebook Spin 513 CP513-2H) + items: + - enum: + - google,tomato-rev2 + - google,tomato-rev1 + - const: google,tomato + - const: mediatek,mt8195 + - description: Acer Tomato rev3 - 4 (Acer Chromebook Spin 513 CP513-2H) + items: + - const: google,tomato-rev4 + - const: google,tomato-rev3 + - const: google,tomato + - const: mediatek,mt8195 + - items: + - enum: + - mediatek,mt8195-demo + - mediatek,mt8195-evb + - const: mediatek,mt8195 - items: - enum: - mediatek,mt8365-evk @@ -287,6 +354,7 @@ properties: - items: - enum: - mediatek,mt8395-evk + - radxa,nio-12l - const: mediatek,mt8395 - const: mediatek,mt8195 - items: diff --git a/Documentation/devicetree/bindings/arm/msm/qcom,saw2.txt b/Documentation/devicetree/bindings/arm/msm/qcom,saw2.txt deleted file mode 100644 index c0e3c3a42bea08..00000000000000 --- a/Documentation/devicetree/bindings/arm/msm/qcom,saw2.txt +++ /dev/null @@ -1,58 +0,0 @@ -SPM AVS Wrapper 2 (SAW2) - -The SAW2 is a wrapper around the Subsystem Power Manager (SPM) and the -Adaptive Voltage Scaling (AVS) hardware. The SPM is a programmable -power-controller that transitions a piece of hardware (like a processor or -subsystem) into and out of low power modes via a direct connection to -the PMIC. It can also be wired up to interact with other processors in the -system, notifying them when a low power state is entered or exited. - -Multiple revisions of the SAW hardware are supported using these Device Nodes. -SAW2 revisions differ in the register offset and configuration data. Also, the -same revision of the SAW in different SoCs may have different configuration -data due the differences in hardware capabilities. Hence the SoC name, the -version of the SAW hardware in that SoC and the distinction between cpu (big -or Little) or cache, may be needed to uniquely identify the SAW register -configuration and initialization data. The compatible string is used to -indicate this parameter. - -PROPERTIES - -- compatible: - Usage: required - Value type: - Definition: Must have - "qcom,saw2" - A more specific value could be one of: - "qcom,apq8064-saw2-v1.1-cpu" - "qcom,msm8226-saw2-v2.1-cpu" - "qcom,msm8974-saw2-v2.1-cpu" - "qcom,apq8084-saw2-v2.1-cpu" - -- reg: - Usage: required - Value type: - Definition: the first element specifies the base address and size of - the register region. An optional second element specifies - the base address and size of the alias register region. - -- regulator: - Usage: optional - Value type: boolean - Definition: Indicates that this SPM device acts as a regulator device - device for the core (CPU or Cache) the SPM is attached - to. - -Example 1: - - power-controller@2099000 { - compatible = "qcom,saw2"; - reg = <0x02099000 0x1000>, <0x02009000 0x1000>; - regulator; - }; - -Example 2: - saw0: power-controller@f9089000 { - compatible = "qcom,apq8084-saw2-v2.1-cpu", "qcom,saw2"; - reg = <0xf9089000 0x1000>, <0xf9009000 0x1000>; - }; diff --git a/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml index 61ddc3b5b247b0..d0647ffaed71e3 100644 --- a/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml +++ b/Documentation/devicetree/bindings/arm/qcom,coresight-tpdm.yaml @@ -52,6 +52,14 @@ properties: $ref: /schemas/types.yaml#/definitions/uint8 enum: [32, 64] + qcom,cmb-element-bits: + description: + Specifies the CMB(Continuous Multi-Bit) element size supported by + the monitor. The associated aggregator will read this size before it + is enabled. CMB element size currently only supports 8-bit, 32-bit + and 64-bit. + enum: [8, 32, 64] + qcom,dsb-msrs-num: description: Specifies the number of DSB(Discrete Single Bit) MSR(mux select register) @@ -61,6 +69,15 @@ properties: minimum: 0 maximum: 32 + qcom,cmb-msrs-num: + description: + Specifies the number of CMB MSR(mux select register) registers supported + by the monitor. If this property is not configured or set to 0, it means + this TPDM doesn't support CMB MSR. + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 0 + maximum: 32 + clocks: maxItems: 1 @@ -110,4 +127,22 @@ examples: }; }; + tpdm@6c29000 { + compatible = "qcom,coresight-tpdm", "arm,primecell"; + reg = <0x06c29000 0x1000>; + + qcom,cmb-element-bits = <64>; + qcom,cmb-msrs-num = <32>; + + clocks = <&aoss_qmp>; + clock-names = "apb_pclk"; + + out-ports { + port { + tpdm_ipcc_out_funnel_center: endpoint { + remote-endpoint = <&funnel_center_in_tpdm_ipcc>; + }; + }; + }; + }; ... diff --git a/Documentation/devicetree/bindings/arm/qcom.yaml b/Documentation/devicetree/bindings/arm/qcom.yaml index 1a5fb889a4440f..66beaac60e1dc4 100644 --- a/Documentation/devicetree/bindings/arm/qcom.yaml +++ b/Documentation/devicetree/bindings/arm/qcom.yaml @@ -10,17 +10,10 @@ maintainers: - Bjorn Andersson 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,[-][-]-[/][-]" - - The 'SoC' and 'board' elements are required. All other elements are optional. + For devices using the Qualcomm SoC the "compatible" properties consists of + one or several "manufacturer,model" strings, describing the device itself, + followed by one or several "qcom," strings, describing the SoC used in + the device. The 'SoC' element must be one of the following strings: @@ -90,43 +83,9 @@ description: | sm8650 x1e80100 - The 'board' element must be one of the following strings: - - adp - cdp - dragonboard - idp - liquid - mtp - qcp - qrd - rb2 - ride - sbc - x100 - - The 'soc_version' and 'board_version' elements take the form of v. - 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. - There are many devices in the list below that run the standard ChromeOS bootloader setup and use the open source depthcharge bootloader to boot the - OS. These devices do not use the scheme described above. For details, see: + OS. These devices use the bootflow explained at https://docs.kernel.org/arch/arm/google/chromebook-boot-flow.html properties: @@ -187,6 +146,7 @@ properties: - microsoft,superman-lte - microsoft,tesla - motorola,peregrine + - samsung,matisselte - const: qcom,msm8926 - const: qcom,msm8226 @@ -244,11 +204,15 @@ properties: - samsung,a5u-eur - samsung,e5 - samsung,e7 + - samsung,fortuna3g + - samsung,gprimeltecan - samsung,grandmax + - samsung,grandprimelte - samsung,gt510 - samsung,gt58 - samsung,j5 - samsung,j5x + - samsung,rossa - samsung,serranove - thwc,uf896 - thwc,ufi001c @@ -988,6 +952,7 @@ properties: - items: - enum: + - xiaomi,curtana - xiaomi,joyeuse - const: qcom,sm7125 @@ -1035,6 +1000,7 @@ properties: - items: - enum: + - qcom,sm8550-hdk - qcom,sm8550-mtp - qcom,sm8550-qrd - const: qcom,sm8550 diff --git a/Documentation/devicetree/bindings/arm/rockchip.yaml b/Documentation/devicetree/bindings/arm/rockchip.yaml index 5cf5cbef2cf550..ca2432e803b369 100644 --- a/Documentation/devicetree/bindings/arm/rockchip.yaml +++ b/Documentation/devicetree/bindings/arm/rockchip.yaml @@ -37,29 +37,16 @@ properties: - anbernic,rg351v - const: rockchip,rk3326 - - description: Anbernic RG353P + - description: Anbernic RK3566 Handheld Gaming Console items: - - const: anbernic,rg353p - - const: rockchip,rk3566 - - - description: Anbernic RG353PS - items: - - const: anbernic,rg353ps - - const: rockchip,rk3566 - - - description: Anbernic RG353V - items: - - const: anbernic,rg353v - - const: rockchip,rk3566 - - - description: Anbernic RG353VS - items: - - const: anbernic,rg353vs - - const: rockchip,rk3566 - - - description: Anbernic RG503 - items: - - const: anbernic,rg503 + - enum: + - anbernic,rg353p + - anbernic,rg353ps + - anbernic,rg353v + - anbernic,rg353vs + - anbernic,rg503 + - anbernic,rg-arc-d + - anbernic,rg-arc-s - const: rockchip,rk3566 - description: Asus Tinker board @@ -237,6 +224,13 @@ properties: - friendlyarm,nanopi-r5s - const: rockchip,rk3568 + - description: FriendlyElec NanoPi R6 series boards + items: + - enum: + - friendlyarm,nanopi-r6c + - friendlyarm,nanopi-r6s + - const: rockchip,rk3588s + - description: FriendlyElec NanoPC T6 items: - const: friendlyarm,nanopc-t6 @@ -655,6 +649,14 @@ properties: - const: pine64,pinephone-pro - const: rockchip,rk3399 + - description: Pine64 PineTab2 + items: + - enum: + - pine64,pinetab2-v0.1 + - pine64,pinetab2-v2.0 + - const: pine64,pinetab2 + - const: rockchip,rk3566 + - description: Pine64 Rock64 items: - const: pine64,rock64 @@ -692,6 +694,7 @@ properties: - description: Powkiddy RK3566 Handheld Gaming Console items: - enum: + - powkiddy,rgb10max3 - powkiddy,rgb30 - powkiddy,rk2023 - powkiddy,x55 diff --git a/Documentation/devicetree/bindings/arm/sunxi.yaml b/Documentation/devicetree/bindings/arm/sunxi.yaml index a9d8e85565b899..09d835db6db57a 100644 --- a/Documentation/devicetree/bindings/arm/sunxi.yaml +++ b/Documentation/devicetree/bindings/arm/sunxi.yaml @@ -815,6 +815,12 @@ properties: - const: allwinner,r7-tv-dongle - const: allwinner,sun5i-a10s + - description: Remix Mini PC + items: + - const: jide,remix-mini-pc + - const: allwinner,sun50i-h64 + - const: allwinner,sun50i-a64 + - description: RerVision H3-DVK items: - const: rervision,h3-dvk @@ -835,6 +841,12 @@ properties: - const: sinlinx,sina33 - const: allwinner,sun8i-a33 + - description: Sipeed Longan Pi 3H board for the Sipeed Longan Module 3H + items: + - const: sipeed,longan-pi-3h + - const: sipeed,longan-module-3h + - const: allwinner,sun50i-h618 + - description: SourceParts PopStick v1.1 items: - const: sourceparts,popstick-v1.1 diff --git a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml index 0faa403f68c879..ea4fbf655220be 100644 --- a/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml +++ b/Documentation/devicetree/bindings/arm/tegra/nvidia,tegra186-pmc.yaml @@ -27,7 +27,7 @@ properties: - const: pmc - const: wake - const: aotag - - const: scratch + - enum: [ scratch, misc ] - const: misc interrupt-controller: true @@ -41,25 +41,43 @@ properties: description: If present, inverts the PMU interrupt signal. $ref: /schemas/types.yaml#/definitions/flag -if: - properties: - compatible: - contains: - const: nvidia,tegra186-pmc -then: - properties: - reg: - maxItems: 4 - - reg-names: - maxItems: 4 -else: - properties: - reg: - minItems: 5 - - reg-names: - minItems: 5 +allOf: + - if: + properties: + compatible: + contains: + const: nvidia,tegra186-pmc + then: + properties: + reg: + maxItems: 4 + reg-names: + maxItems: 4 + contains: + const: scratch + + - if: + properties: + compatible: + contains: + const: nvidia,tegra194-pmc + then: + properties: + reg: + minItems: 5 + reg-names: + minItems: 5 + + - if: + properties: + compatible: + contains: + const: nvidia,tegra234-pmc + then: + properties: + reg-names: + contains: + const: misc patternProperties: "^[a-z0-9]+-[a-z0-9]+$": diff --git a/Documentation/devicetree/bindings/arm/ti/k3.yaml b/Documentation/devicetree/bindings/arm/ti/k3.yaml index c6506bccfe88fa..399249e7b22f66 100644 --- a/Documentation/devicetree/bindings/arm/ti/k3.yaml +++ b/Documentation/devicetree/bindings/arm/ti/k3.yaml @@ -93,6 +93,7 @@ properties: - siemens,iot2050-advanced - siemens,iot2050-advanced-m2 - siemens,iot2050-advanced-pg2 + - siemens,iot2050-advanced-sm - siemens,iot2050-basic - siemens,iot2050-basic-pg2 - ti,am654-evm @@ -123,6 +124,12 @@ properties: - ti,j721s2-evm - const: ti,j721s2 + - description: K3 J722S SoC and Boards + items: + - enum: + - ti,j722s-evm + - const: ti,j722s + - description: K3 J784s4 SoC items: - enum: diff --git a/Documentation/devicetree/bindings/ata/ahci-mtk.txt b/Documentation/devicetree/bindings/ata/ahci-mtk.txt deleted file mode 100644 index d2aa696b161b31..00000000000000 --- a/Documentation/devicetree/bindings/ata/ahci-mtk.txt +++ /dev/null @@ -1,51 +0,0 @@ -MediaTek Serial ATA controller - -Required properties: - - compatible : Must be "mediatek,-ahci", "mediatek,mtk-ahci". - When using "mediatek,mtk-ahci" compatible strings, you - need SoC specific ones in addition, one of: - - "mediatek,mt7622-ahci" - - reg : Physical base addresses and length of register sets. - - interrupts : Interrupt associated with the SATA device. - - interrupt-names : Associated name must be: "hostc". - - clocks : A list of phandle and clock specifier pairs, one for each - entry in clock-names. - - clock-names : Associated names must be: "ahb", "axi", "asic", "rbc", "pm". - - phys : A phandle and PHY specifier pair for the PHY port. - - phy-names : Associated name must be: "sata-phy". - - ports-implemented : See ./ahci-platform.txt for details. - -Optional properties: - - power-domains : A phandle and power domain specifier pair to the power - domain which is responsible for collapsing and restoring - power to the peripheral. - - resets : Must contain an entry for each entry in reset-names. - See ../reset/reset.txt for details. - - reset-names : Associated names must be: "axi", "sw", "reg". - - mediatek,phy-mode : A phandle to the system controller, used to enable - SATA function. - -Example: - - sata: sata@1a200000 { - compatible = "mediatek,mt7622-ahci", - "mediatek,mtk-ahci"; - reg = <0 0x1a200000 0 0x1100>; - interrupts = ; - interrupt-names = "hostc"; - clocks = <&pciesys CLK_SATA_AHB_EN>, - <&pciesys CLK_SATA_AXI_EN>, - <&pciesys CLK_SATA_ASIC_EN>, - <&pciesys CLK_SATA_RBC_EN>, - <&pciesys CLK_SATA_PM_EN>; - clock-names = "ahb", "axi", "asic", "rbc", "pm"; - phys = <&u3port1 PHY_TYPE_SATA>; - phy-names = "sata-phy"; - ports-implemented = <0x1>; - power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>; - resets = <&pciesys MT7622_SATA_AXI_BUS_RST>, - <&pciesys MT7622_SATA_PHY_SW_RST>, - <&pciesys MT7622_SATA_PHY_REG_RST>; - reset-names = "axi", "sw", "reg"; - mediatek,phy-mode = <&pciesys>; - }; diff --git a/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt b/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt deleted file mode 100644 index c1d22b3ae1348f..00000000000000 --- a/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt +++ /dev/null @@ -1,19 +0,0 @@ -Atmel AT91RM9200 CompactFlash - -Required properties: -- compatible : "atmel,at91rm9200-cf". -- reg : should specify localbus address and size used. -- gpios : specifies the gpio pins to control the CF device. Detect - and reset gpio's are mandatory while irq and vcc gpio's are - optional and may be set to 0 if not present. - -Example: -compact-flash@50000000 { - compatible = "atmel,at91rm9200-cf"; - reg = <0x50000000 0x30000000>; - gpios = <&pioC 13 0 /* irq */ - &pioC 15 0 /* detect */ - 0 /* vcc */ - &pioC 5 0 /* reset */ - >; -}; diff --git a/Documentation/devicetree/bindings/ata/ceva,ahci-1v84.yaml b/Documentation/devicetree/bindings/ata/ceva,ahci-1v84.yaml index b29ce598f9aaea..9952e0ef77674c 100644 --- a/Documentation/devicetree/bindings/ata/ceva,ahci-1v84.yaml +++ b/Documentation/devicetree/bindings/ata/ceva,ahci-1v84.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Ceva AHCI SATA Controller maintainers: - - Piyush Mehta + - Mubin Sayyed + - Radhey Shyam Pandey description: | The Ceva SATA controller mostly conforms to the AHCI interface with some diff --git a/Documentation/devicetree/bindings/ata/mediatek,mtk-ahci.yaml b/Documentation/devicetree/bindings/ata/mediatek,mtk-ahci.yaml new file mode 100644 index 00000000000000..a34bd2e9c352e4 --- /dev/null +++ b/Documentation/devicetree/bindings/ata/mediatek,mtk-ahci.yaml @@ -0,0 +1,98 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/ata/mediatek,mtk-ahci.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek Serial ATA controller + +maintainers: + - Ryder Lee + +allOf: + - $ref: ahci-common.yaml# + +properties: + compatible: + items: + - enum: + - mediatek,mt7622-ahci + - const: mediatek,mtk-ahci + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-names: + const: hostc + + clocks: + maxItems: 5 + + clock-names: + items: + - const: ahb + - const: axi + - const: asic + - const: rbc + - const: pm + + power-domains: + maxItems: 1 + + resets: + maxItems: 3 + + reset-names: + items: + - const: axi + - const: sw + - const: reg + + mediatek,phy-mode: + description: System controller phandle, used to enable SATA function + $ref: /schemas/types.yaml#/definitions/phandle + +required: + - reg + - interrupts + - interrupt-names + - clocks + - clock-names + - phys + - phy-names + - ports-implemented + +unevaluatedProperties: false + +examples: + - | + #include + #include + #include + #include + #include + + sata@1a200000 { + compatible = "mediatek,mt7622-ahci", "mediatek,mtk-ahci"; + reg = <0x1a200000 0x1100>; + interrupts = ; + interrupt-names = "hostc"; + clocks = <&pciesys CLK_SATA_AHB_EN>, + <&pciesys CLK_SATA_AXI_EN>, + <&pciesys CLK_SATA_ASIC_EN>, + <&pciesys CLK_SATA_RBC_EN>, + <&pciesys CLK_SATA_PM_EN>; + clock-names = "ahb", "axi", "asic", "rbc", "pm"; + phys = <&u3port1 PHY_TYPE_SATA>; + phy-names = "sata-phy"; + ports-implemented = <0x1>; + power-domains = <&scpsys MT7622_POWER_DOMAIN_HIF0>; + resets = <&pciesys MT7622_SATA_AXI_BUS_RST>, + <&pciesys MT7622_SATA_PHY_SW_RST>, + <&pciesys MT7622_SATA_PHY_REG_RST>; + reset-names = "axi", "sw", "reg"; + mediatek,phy-mode = <&pciesys>; + }; diff --git a/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml b/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml index 5d02bd032a85fe..439f7b811a94a4 100644 --- a/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml +++ b/Documentation/devicetree/bindings/auxdisplay/arm,versatile-lcd.yaml @@ -39,6 +39,6 @@ additionalProperties: false examples: - | lcd@10008000 { - compatible = "arm,versatile-lcd"; - reg = <0x10008000 0x1000>; + compatible = "arm,versatile-lcd"; + reg = <0x10008000 0x1000>; }; diff --git a/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.yaml b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.yaml index 406a922a714e8f..3ca0e9863d836d 100644 --- a/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.yaml +++ b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.yaml @@ -84,42 +84,44 @@ additionalProperties: false examples: - | #include - auxdisplay { - compatible = "hit,hd44780"; - - data-gpios = <&hc595 0 GPIO_ACTIVE_HIGH>, - <&hc595 1 GPIO_ACTIVE_HIGH>, - <&hc595 2 GPIO_ACTIVE_HIGH>, - <&hc595 3 GPIO_ACTIVE_HIGH>; - enable-gpios = <&hc595 4 GPIO_ACTIVE_HIGH>; - rs-gpios = <&hc595 5 GPIO_ACTIVE_HIGH>; - - display-height-chars = <2>; - display-width-chars = <16>; + display-controller { + compatible = "hit,hd44780"; + + data-gpios = <&hc595 0 GPIO_ACTIVE_HIGH>, + <&hc595 1 GPIO_ACTIVE_HIGH>, + <&hc595 2 GPIO_ACTIVE_HIGH>, + <&hc595 3 GPIO_ACTIVE_HIGH>; + enable-gpios = <&hc595 4 GPIO_ACTIVE_HIGH>; + rs-gpios = <&hc595 5 GPIO_ACTIVE_HIGH>; + + display-height-chars = <2>; + display-width-chars = <16>; }; + - | #include i2c { - #address-cells = <1>; - #size-cells = <0>; - - pcf8574: pcf8574@27 { - compatible = "nxp,pcf8574"; - reg = <0x27>; - gpio-controller; - #gpio-cells = <2>; - }; + #address-cells = <1>; + #size-cells = <0>; + + pcf8574: gpio-expander@27 { + compatible = "nxp,pcf8574"; + reg = <0x27>; + gpio-controller; + #gpio-cells = <2>; + }; }; - hd44780 { - compatible = "hit,hd44780"; - display-height-chars = <2>; - display-width-chars = <16>; - data-gpios = <&pcf8574 4 0>, - <&pcf8574 5 0>, - <&pcf8574 6 0>, - <&pcf8574 7 0>; - enable-gpios = <&pcf8574 2 0>; - rs-gpios = <&pcf8574 0 0>; - rw-gpios = <&pcf8574 1 0>; - backlight-gpios = <&pcf8574 3 0>; + + display-controller { + compatible = "hit,hd44780"; + display-height-chars = <2>; + display-width-chars = <16>; + data-gpios = <&pcf8574 4 GPIO_ACTIVE_HIGH>, + <&pcf8574 5 GPIO_ACTIVE_HIGH>, + <&pcf8574 6 GPIO_ACTIVE_HIGH>, + <&pcf8574 7 GPIO_ACTIVE_HIGH>; + enable-gpios = <&pcf8574 2 GPIO_ACTIVE_HIGH>; + rs-gpios = <&pcf8574 0 GPIO_ACTIVE_HIGH>; + rw-gpios = <&pcf8574 1 GPIO_ACTIVE_HIGH>; + backlight-gpios = <&pcf8574 3 GPIO_ACTIVE_HIGH>; }; diff --git a/Documentation/devicetree/bindings/auxdisplay/holtek,ht16k33.yaml b/Documentation/devicetree/bindings/auxdisplay/holtek,ht16k33.yaml index be95f6b97b41a5..b90eec2077b4bd 100644 --- a/Documentation/devicetree/bindings/auxdisplay/holtek,ht16k33.yaml +++ b/Documentation/devicetree/bindings/auxdisplay/holtek,ht16k33.yaml @@ -74,31 +74,31 @@ examples: #include #include i2c { - #address-cells = <1>; - #size-cells = <0>; - - ht16k33: ht16k33@70 { - compatible = "holtek,ht16k33"; - reg = <0x70>; - refresh-rate-hz = <20>; - interrupt-parent = <&gpio4>; - interrupts = <5 (IRQ_TYPE_LEVEL_HIGH | IRQ_TYPE_EDGE_RISING)>; - debounce-delay-ms = <50>; - linux,keymap = , - , - , - , - , - , - , - , - , - ; - - led { - color = ; - function = LED_FUNCTION_BACKLIGHT; - linux,default-trigger = "backlight"; - }; + #address-cells = <1>; + #size-cells = <0>; + + display-controller@70 { + compatible = "holtek,ht16k33"; + reg = <0x70>; + refresh-rate-hz = <20>; + interrupt-parent = <&gpio4>; + interrupts = <5 (IRQ_TYPE_LEVEL_HIGH | IRQ_TYPE_EDGE_RISING)>; + debounce-delay-ms = <50>; + linux,keymap = , + , + , + , + , + , + , + , + , + ; + + led { + color = ; + function = LED_FUNCTION_BACKLIGHT; + linux,default-trigger = "backlight"; }; - }; + }; + }; diff --git a/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml b/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml index 1899b23de7d1e4..55e9831b3f67c6 100644 --- a/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml +++ b/Documentation/devicetree/bindings/auxdisplay/img,ascii-lcd.yaml @@ -50,6 +50,6 @@ additionalProperties: false examples: - | lcd: lcd@17fff000 { - compatible = "img,boston-lcd"; - reg = <0x17fff000 0x8>; + compatible = "img,boston-lcd"; + reg = <0x17fff000 0x8>; }; diff --git a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml index 3aaefdbe361ebe..9017c5a3f3d20f 100644 --- a/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml +++ b/Documentation/devicetree/bindings/bus/brcm,gisb-arb.yaml @@ -18,6 +18,7 @@ properties: - const: brcm,gisb-arb - items: - enum: + - brcm,bcm74165-gisb-arb # for V7 new style 16nm chips - brcm,bcm7278-gisb-arb # for V7 28nm chips - brcm,bcm7435-gisb-arb # for newer 40nm chips - brcm,bcm7400-gisb-arb # for older 40nm chips and all 65nm chips diff --git a/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml index 3eebc03a309be2..1d2bcea41c8588 100644 --- a/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml +++ b/Documentation/devicetree/bindings/clock/google,gs101-clock.yaml @@ -30,14 +30,16 @@ properties: - google,gs101-cmu-top - google,gs101-cmu-apm - google,gs101-cmu-misc + - google,gs101-cmu-peric0 + - google,gs101-cmu-peric1 clocks: minItems: 1 - maxItems: 2 + maxItems: 3 clock-names: minItems: 1 - maxItems: 2 + maxItems: 3 "#clock-cells": const: 1 @@ -85,8 +87,30 @@ allOf: clock-names: items: - - const: dout_cmu_misc_bus - - const: dout_cmu_misc_sss + - const: bus + - const: sss + + - if: + properties: + compatible: + contains: + enum: + - google,gs101-cmu-peric0 + - google,gs101-cmu-peric1 + + then: + properties: + clocks: + items: + - description: External reference clock (24.576 MHz) + - description: Connectivity Peripheral 0/1 bus clock (from CMU_TOP) + - description: Connectivity Peripheral 0/1 IP clock (from CMU_TOP) + + clock-names: + items: + - const: oscclk + - const: bus + - const: ip additionalProperties: false diff --git a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml index 6c4846b34e4b50..a1085ef4fd05ad 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gcc-sc8180x.yaml @@ -31,10 +31,15 @@ properties: - const: bi_tcxo_ao - const: sleep_clk + power-domains: + items: + - description: CX domain + required: - compatible - clocks - clock-names + - power-domains allOf: - $ref: qcom,gcc.yaml# @@ -44,6 +49,7 @@ unevaluatedProperties: false examples: - | #include + #include clock-controller@100000 { compatible = "qcom,gcc-sc8180x"; reg = <0x00100000 0x1f0000>; @@ -51,6 +57,7 @@ examples: <&rpmhcc RPMH_CXO_CLK_A>, <&sleep_clk>; clock-names = "bi_tcxo", "bi_tcxo_ao", "sleep_clk"; + power-domains = <&rpmhpd SC8180X_CX>; #clock-cells = <1>; #reset-cells = <1>; #power-domain-cells = <1>; diff --git a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml index f369fa34e00cf8..f57aceddac6bed 100644 --- a/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,gpucc.yaml @@ -53,6 +53,9 @@ properties: power-domains: maxItems: 1 + vdd-gfx-supply: + description: Regulator supply for the VDD_GFX pads + '#clock-cells': const: 1 @@ -74,6 +77,12 @@ required: - '#reset-cells' - '#power-domain-cells' +# Require that power-domains and vdd-gfx-supply are not both present +not: + required: + - power-domains + - vdd-gfx-supply + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml b/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml index 03fa30fe925393..e0f4d692728c92 100644 --- a/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,q6sstopcc.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Q6SSTOP clock Controller maintainers: - - Govind Singh + - Bjorn Andersson properties: compatible: diff --git a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml b/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml deleted file mode 100644 index 873a2f918baceb..00000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,sc7180-mss.yaml +++ /dev/null @@ -1,61 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/clock/qcom,sc7180-mss.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Modem Clock Controller on SC7180 - -maintainers: - - Taniya Das - -description: | - Qualcomm modem clock control module provides the clocks on SC7180. - - See also:: include/dt-bindings/clock/qcom,mss-sc7180.h - -properties: - compatible: - const: qcom,sc7180-mss - - clocks: - items: - - description: gcc_mss_mfab_axi clock from GCC - - description: gcc_mss_nav_axi clock from GCC - - description: gcc_mss_cfg_ahb clock from GCC - - clock-names: - items: - - const: gcc_mss_mfab_axis - - const: gcc_mss_nav_axi - - const: cfg_ahb - - '#clock-cells': - const: 1 - - reg: - maxItems: 1 - -required: - - compatible - - reg - - clocks - - '#clock-cells' - -additionalProperties: false - -examples: - - | - #include - clock-controller@41a8000 { - compatible = "qcom,sc7180-mss"; - reg = <0x041a8000 0x8000>; - clocks = <&gcc GCC_MSS_MFAB_AXIS_CLK>, - <&gcc GCC_MSS_NAV_AXI_CLK>, - <&gcc GCC_MSS_CFG_AHB_CLK>; - clock-names = "gcc_mss_mfab_axis", - "gcc_mss_nav_axi", - "cfg_ahb"; - #clock-cells = <1>; - }; -... diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml index 48986460f9947d..fa0e5b6b02b817 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-camcc.yaml @@ -17,6 +17,7 @@ description: | include/dt-bindings/clock/qcom,sm8450-camcc.h include/dt-bindings/clock/qcom,sm8550-camcc.h include/dt-bindings/clock/qcom,sc8280xp-camcc.h + include/dt-bindings/clock/qcom,x1e80100-camcc.h allOf: - $ref: qcom,gcc.yaml# @@ -27,6 +28,7 @@ properties: - qcom,sc8280xp-camcc - qcom,sm8450-camcc - qcom,sm8550-camcc + - qcom,x1e80100-camcc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml index 1a384e8532a59c..36974309cf6964 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8450-gpucc.yaml @@ -18,6 +18,7 @@ description: | include/dt-bindings/clock/qcom,sm8550-gpucc.h include/dt-bindings/reset/qcom,sm8450-gpucc.h include/dt-bindings/reset/qcom,sm8650-gpucc.h + include/dt-bindings/reset/qcom,x1e80100-gpucc.h properties: compatible: @@ -25,6 +26,7 @@ properties: - qcom,sm8450-gpucc - qcom,sm8550-gpucc - qcom,sm8650-gpucc + - qcom,x1e80100-gpucc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml index c129f8c16b503b..bad0260764d464 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-dispcc.yaml @@ -14,12 +14,17 @@ description: | Qualcomm display clock control module provides the clocks, resets and power domains on SM8550. - See also:: include/dt-bindings/clock/qcom,sm8550-dispcc.h + See also: + - include/dt-bindings/clock/qcom,sm8550-dispcc.h + - include/dt-bindings/clock/qcom,sm8650-dispcc.h + - include/dt-bindings/clock/qcom,x1e80100-dispcc.h properties: compatible: enum: - qcom,sm8550-dispcc + - qcom,sm8650-dispcc + - qcom,x1e80100-dispcc clocks: items: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml index af16b05eac96e4..48fdd562d74394 100644 --- a/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml +++ b/Documentation/devicetree/bindings/clock/qcom,sm8550-tcsr.yaml @@ -23,6 +23,7 @@ properties: - enum: - qcom,sm8550-tcsr - qcom,sm8650-tcsr + - qcom,x1e80100-tcsr - const: syscon clocks: diff --git a/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml b/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml deleted file mode 100644 index 5e0c45c380f5d1..00000000000000 --- a/Documentation/devicetree/bindings/clock/qcom,sm8650-dispcc.yaml +++ /dev/null @@ -1,106 +0,0 @@ -# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) -%YAML 1.2 ---- -$id: http://devicetree.org/schemas/clock/qcom,sm8650-dispcc.yaml# -$schema: http://devicetree.org/meta-schemas/core.yaml# - -title: Qualcomm Display Clock & Reset Controller for SM8650 - -maintainers: - - Bjorn Andersson - - Neil Armstrong - -description: | - Qualcomm display clock control module provides the clocks, resets and power - domains on SM8650. - - See also:: include/dt-bindings/clock/qcom,sm8650-dispcc.h - -properties: - compatible: - enum: - - qcom,sm8650-dispcc - - clocks: - items: - - description: Board XO source - - description: Board Always On XO source - - description: Display's AHB clock - - description: sleep clock - - description: Byte clock from DSI PHY0 - - description: Pixel clock from DSI PHY0 - - description: Byte clock from DSI PHY1 - - description: Pixel clock from DSI PHY1 - - description: Link clock from DP PHY0 - - description: VCO DIV clock from DP PHY0 - - description: Link clock from DP PHY1 - - description: VCO DIV clock from DP PHY1 - - description: Link clock from DP PHY2 - - description: VCO DIV clock from DP PHY2 - - description: Link clock from DP PHY3 - - description: VCO DIV clock from DP PHY3 - - '#clock-cells': - const: 1 - - '#reset-cells': - const: 1 - - '#power-domain-cells': - const: 1 - - reg: - maxItems: 1 - - power-domains: - description: - A phandle and PM domain specifier for the MMCX power domain. - maxItems: 1 - - required-opps: - description: - A phandle to an OPP node describing required MMCX performance point. - maxItems: 1 - -required: - - compatible - - reg - - clocks - - '#clock-cells' - - '#reset-cells' - - '#power-domain-cells' - -additionalProperties: false - -examples: - - | - #include - #include - #include - #include - clock-controller@af00000 { - compatible = "qcom,sm8650-dispcc"; - reg = <0x0af00000 0x10000>; - clocks = <&rpmhcc RPMH_CXO_CLK>, - <&rpmhcc RPMH_CXO_CLK_A>, - <&gcc GCC_DISP_AHB_CLK>, - <&sleep_clk>, - <&dsi0_phy 0>, - <&dsi0_phy 1>, - <&dsi1_phy 0>, - <&dsi1_phy 1>, - <&dp0_phy 0>, - <&dp0_phy 1>, - <&dp1_phy 0>, - <&dp1_phy 1>, - <&dp2_phy 0>, - <&dp2_phy 1>, - <&dp3_phy 0>, - <&dp3_phy 1>; - #clock-cells = <1>; - #reset-cells = <1>; - #power-domain-cells = <1>; - power-domains = <&rpmhpd RPMHPD_MMCX>; - required-opps = <&rpmhpd_opp_low_svs>; - }; -... diff --git a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml index 9c3dc6c4fa9421..084259d30232aa 100644 --- a/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml +++ b/Documentation/devicetree/bindings/clock/renesas,cpg-mssr.yaml @@ -50,6 +50,7 @@ properties: - renesas,r8a779a0-cpg-mssr # R-Car V3U - renesas,r8a779f0-cpg-mssr # R-Car S4-8 - renesas,r8a779g0-cpg-mssr # R-Car V4H + - renesas,r8a779h0-cpg-mssr # R-Car V4M reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/clock/tesla,fsd-clock.yaml b/Documentation/devicetree/bindings/clock/tesla,fsd-clock.yaml index dc808e2f83272a..b370a10a23a64c 100644 --- a/Documentation/devicetree/bindings/clock/tesla,fsd-clock.yaml +++ b/Documentation/devicetree/bindings/clock/tesla,fsd-clock.yaml @@ -12,7 +12,7 @@ maintainers: description: | FSD clock controller consist of several clock management unit - (CMU), which generates clocks for various inteernal SoC blocks. + (CMU), which generates clocks for various internal SoC blocks. The root clock comes from external OSC clock (24 MHz). All available clocks are defined as preprocessor macros in diff --git a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml index 09e43157cc71fe..e91bc7dc6ad3d7 100644 --- a/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom,inline-crypto-engine.yaml @@ -14,6 +14,7 @@ properties: items: - enum: - qcom,sa8775p-inline-crypto-engine + - qcom,sc7180-inline-crypto-engine - qcom,sm8450-inline-crypto-engine - qcom,sm8550-inline-crypto-engine - qcom,sm8650-inline-crypto-engine diff --git a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml index a48bd381063aaf..e285e382d4ecce 100644 --- a/Documentation/devicetree/bindings/crypto/qcom-qce.yaml +++ b/Documentation/devicetree/bindings/crypto/qcom-qce.yaml @@ -45,6 +45,7 @@ properties: - items: - enum: - qcom,sc7280-qce + - qcom,sm6350-qce - qcom,sm8250-qce - qcom,sm8350-qce - qcom,sm8450-qce diff --git a/Documentation/devicetree/bindings/display/bridge/fsl,imx8mp-hdmi-tx.yaml b/Documentation/devicetree/bindings/display/bridge/fsl,imx8mp-hdmi-tx.yaml new file mode 100644 index 00000000000000..3791c9f4ebab0e --- /dev/null +++ b/Documentation/devicetree/bindings/display/bridge/fsl,imx8mp-hdmi-tx.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/bridge/fsl,imx8mp-hdmi-tx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX8MP DWC HDMI TX Encoder + +maintainers: + - Lucas Stach + +description: + The i.MX8MP HDMI transmitter is a Synopsys DesignWare + HDMI 2.0a TX controller IP. + +allOf: + - $ref: /schemas/display/bridge/synopsys,dw-hdmi.yaml# + +properties: + compatible: + enum: + - fsl,imx8mp-hdmi-tx + + reg-io-width: + const: 1 + + clocks: + maxItems: 4 + + clock-names: + items: + - const: iahb + - const: isfr + - const: cec + - const: pix + + power-domains: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Parallel RGB input port + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: HDMI output port + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + - power-domains + - ports + +unevaluatedProperties: false + +examples: + - | + #include + #include + #include + + hdmi@32fd8000 { + compatible = "fsl,imx8mp-hdmi-tx"; + reg = <0x32fd8000 0x7eff>; + interrupts = <0 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clk IMX8MP_CLK_HDMI_APB>, + <&clk IMX8MP_CLK_HDMI_REF_266M>, + <&clk IMX8MP_CLK_32K>, + <&hdmi_tx_phy>; + clock-names = "iahb", "isfr", "cec", "pix"; + power-domains = <&hdmi_blk_ctrl IMX8MP_HDMIBLK_PD_HDMI_TX>; + reg-io-width = <1>; + ports { + #address-cells = <1>; + #size-cells = <0>; + port@0 { + reg = <0>; + + hdmi_tx_from_pvi: endpoint { + remote-endpoint = <&pvi_to_hdmi_tx>; + }; + }; + + port@1 { + reg = <1>; + hdmi_tx_out: endpoint { + remote-endpoint = <&hdmi0_con>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/bridge/nxp,tda998x.yaml b/Documentation/devicetree/bindings/display/bridge/nxp,tda998x.yaml index 21d995f29a1e30..b8e9cf6ce4e611 100644 --- a/Documentation/devicetree/bindings/display/bridge/nxp,tda998x.yaml +++ b/Documentation/devicetree/bindings/display/bridge/nxp,tda998x.yaml @@ -29,19 +29,22 @@ properties: audio-ports: description: - Array of 8-bit values, 2 values per DAI (Documentation/sound/soc/dai.rst). + Array of 2 values per DAI (Documentation/sound/soc/dai.rst). The implementation allows one or two DAIs. If two DAIs are defined, they must be of different type. $ref: /schemas/types.yaml#/definitions/uint32-matrix + minItems: 1 + maxItems: 2 items: - minItems: 1 items: - description: | The first value defines the DAI type: TDA998x_SPDIF or TDA998x_I2S (see include/dt-bindings/display/tda998x.h). + enum: [ 1, 2 ] - description: The second value defines the tda998x AP_ENA reg content when the DAI in question is used. + maximum: 0xff '#sound-dai-cells': enum: [ 0, 1 ] diff --git a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml index 6ec6d287bff401..c93878b6d7182b 100644 --- a/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml +++ b/Documentation/devicetree/bindings/display/bridge/ti,sn65dsi86.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: SN65DSI86 DSI to eDP bridge chip maintainers: - - Sandeep Panda + - Douglas Anderson description: | The Texas Instruments SN65DSI86 bridge takes MIPI DSI in and outputs eDP. diff --git a/Documentation/devicetree/bindings/display/imx/fsl,imx8mp-hdmi-pvi.yaml b/Documentation/devicetree/bindings/display/imx/fsl,imx8mp-hdmi-pvi.yaml new file mode 100644 index 00000000000000..56da1636014ce7 --- /dev/null +++ b/Documentation/devicetree/bindings/display/imx/fsl,imx8mp-hdmi-pvi.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/imx/fsl,imx8mp-hdmi-pvi.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale i.MX8MP HDMI Parallel Video Interface + +maintainers: + - Lucas Stach + +description: + The HDMI parallel video interface is a timing and sync generator block in the + i.MX8MP SoC, that sits between the video source and the HDMI TX controller. + +properties: + compatible: + const: fsl,imx8mp-hdmi-pvi + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + power-domains: + maxItems: 1 + + ports: + $ref: /schemas/graph.yaml#/properties/ports + + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Input from the LCDIF controller. + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: Output to the HDMI TX controller. + + required: + - port@0 + - port@1 + +required: + - compatible + - reg + - interrupts + - power-domains + - ports + +additionalProperties: false + +examples: + - | + #include + #include + + display-bridge@32fc4000 { + compatible = "fsl,imx8mp-hdmi-pvi"; + reg = <0x32fc4000 0x44>; + interrupt-parent = <&irqsteer_hdmi>; + interrupts = <12 IRQ_TYPE_LEVEL_HIGH>; + power-domains = <&hdmi_blk_ctrl IMX8MP_HDMIBLK_PD_PVI>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + pvi_from_lcdif3: endpoint { + remote-endpoint = <&lcdif3_to_pvi>; + }; + }; + + port@1 { + reg = <1>; + pvi_to_hdmi_tx: endpoint { + remote-endpoint = <&hdmi_tx_from_pvi>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml index 4219936eda5a17..1fa28e9765593a 100644 --- a/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml +++ b/Documentation/devicetree/bindings/display/msm/dsi-controller-main.yaml @@ -19,6 +19,7 @@ properties: - qcom,msm8916-dsi-ctrl - qcom,msm8953-dsi-ctrl - qcom,msm8974-dsi-ctrl + - qcom,msm8976-dsi-ctrl - qcom,msm8996-dsi-ctrl - qcom,msm8998-dsi-ctrl - qcom,qcm2290-dsi-ctrl @@ -248,6 +249,7 @@ allOf: contains: enum: - qcom,msm8953-dsi-ctrl + - qcom,msm8976-dsi-ctrl then: properties: clocks: diff --git a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml index 0999ea07f47bb6..e4576546bf0dbb 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,mdss.yaml @@ -127,6 +127,7 @@ patternProperties: - qcom,dsi-phy-20nm - qcom,dsi-phy-28nm-8226 - qcom,dsi-phy-28nm-hpm + - qcom,dsi-phy-28nm-hpm-fam-b - qcom,dsi-phy-28nm-lp - qcom,hdmi-phy-8084 - qcom,hdmi-phy-8660 diff --git a/Documentation/devicetree/bindings/display/msm/qcom,sm8650-mdss.yaml b/Documentation/devicetree/bindings/display/msm/qcom,sm8650-mdss.yaml index bd11119dc93daf..24cece1e888bd3 100644 --- a/Documentation/devicetree/bindings/display/msm/qcom,sm8650-mdss.yaml +++ b/Documentation/devicetree/bindings/display/msm/qcom,sm8650-mdss.yaml @@ -37,18 +37,21 @@ properties: patternProperties: "^display-controller@[0-9a-f]+$": type: object + additionalProperties: true properties: compatible: const: qcom,sm8650-dpu "^displayport-controller@[0-9a-f]+$": type: object + additionalProperties: true properties: compatible: const: qcom,sm8650-dp "^dsi@[0-9a-f]+$": type: object + additionalProperties: true properties: compatible: items: @@ -57,6 +60,7 @@ patternProperties: "^phy@[0-9a-f]+$": type: object + additionalProperties: true properties: compatible: const: qcom,sm8650-dsi-phy-4nm diff --git a/Documentation/devicetree/bindings/display/panel/boe,th101mb31ig002-28a.yaml b/Documentation/devicetree/bindings/display/panel/boe,th101mb31ig002-28a.yaml new file mode 100644 index 00000000000000..32df26cbfeed73 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/boe,th101mb31ig002-28a.yaml @@ -0,0 +1,58 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/boe,th101mb31ig002-28a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: BOE TH101MB31IG002-28A WXGA DSI Display Panel + +maintainers: + - Manuel Traut + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + enum: + # BOE TH101MB31IG002-28A 10.1" WXGA TFT LCD panel + - boe,th101mb31ig002-28a + + reg: true + backlight: true + enable-gpios: true + power-supply: true + port: true + rotation: true + +required: + - compatible + - reg + - enable-gpios + - power-supply + +additionalProperties: false + +examples: + - | + #include + + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "boe,th101mb31ig002-28a"; + reg = <0>; + backlight = <&backlight_lcd0>; + enable-gpios = <&gpio 45 GPIO_ACTIVE_HIGH>; + rotation = <90>; + power-supply = <&vcc_3v3>; + port { + panel_in_dsi: endpoint { + remote-endpoint = <&dsi_out_con>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/himax,hx83112a.yaml b/Documentation/devicetree/bindings/display/panel/himax,hx83112a.yaml new file mode 100644 index 00000000000000..174661d1381111 --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/himax,hx83112a.yaml @@ -0,0 +1,74 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/himax,hx83112a.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Himax HX83112A-based DSI display panels + +maintainers: + - Luca Weiss + +description: + The Himax HX83112A is a generic DSI Panel IC used to control + LCD panels. + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + contains: + const: djn,9a-3r063-1102b + + vdd1-supply: + description: Digital voltage rail + + vsn-supply: + description: Positive source voltage rail + + vsp-supply: + description: Negative source voltage rail + + reg: true + port: true + +required: + - compatible + - reg + - reset-gpios + - vdd1-supply + - vsn-supply + - vsp-supply + - port + +unevaluatedProperties: false + +examples: + - | + #include + + dsi { + #address-cells = <1>; + #size-cells = <0>; + + panel@0 { + compatible = "djn,9a-3r063-1102b"; + reg = <0>; + + backlight = <&pm6150l_wled>; + reset-gpios = <&pm6150l_gpios 9 GPIO_ACTIVE_LOW>; + + vdd1-supply = <&vreg_l1e>; + vsn-supply = <&pm6150l_lcdb_ncp>; + vsp-supply = <&pm6150l_lcdb_ldo>; + + port { + panel_in_0: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml index c5944b4d636c54..d589f167721450 100644 --- a/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml +++ b/Documentation/devicetree/bindings/display/panel/leadtek,ltk500hd1829.yaml @@ -14,7 +14,9 @@ allOf: properties: compatible: - const: leadtek,ltk500hd1829 + enum: + - leadtek,ltk101b4029w + - leadtek,ltk500hd1829 reg: true backlight: true reset-gpios: true diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml index bc92928c805b9a..a4afaff483b73f 100644 --- a/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt35510.yaml @@ -15,7 +15,9 @@ allOf: properties: compatible: items: - - const: hydis,hva40wv1 + - enum: + - frida,frd400b25025 + - hydis,hva40wv1 - const: novatek,nt35510 description: This indicates the panel manufacturer of the panel that is in turn using the NT35510 panel driver. The compatible diff --git a/Documentation/devicetree/bindings/display/panel/novatek,nt36672e.yaml b/Documentation/devicetree/bindings/display/panel/novatek,nt36672e.yaml new file mode 100644 index 00000000000000..dc4672f3d01d7c --- /dev/null +++ b/Documentation/devicetree/bindings/display/panel/novatek,nt36672e.yaml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/panel/novatek,nt36672e.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Novatek NT36672E LCD DSI Panel + +maintainers: + - Ritesh Kumar + +allOf: + - $ref: panel-common.yaml# + +properties: + compatible: + const: novatek,nt36672e + + reg: + maxItems: 1 + description: DSI virtual channel + + vddi-supply: true + avdd-supply: true + avee-supply: true + port: true + reset-gpios: true + backlight: true + +required: + - compatible + - reg + - vddi-supply + - avdd-supply + - avee-supply + - reset-gpios + - port + +additionalProperties: false + +examples: + - | + #include + dsi { + #address-cells = <1>; + #size-cells = <0>; + panel@0 { + compatible = "novatek,nt36672e"; + reg = <0>; + + reset-gpios = <&tlmm 44 GPIO_ACTIVE_HIGH>; + + vddi-supply = <&vreg_l8c_1p8>; + avdd-supply = <&disp_avdd>; + avee-supply = <&disp_avee>; + + backlight = <&pwm_backlight>; + + port { + panel0_in: endpoint { + remote-endpoint = <&dsi0_out>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml b/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml index 9f1016551e0b27..155d8ffa8f6ef1 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-lvds.yaml @@ -39,9 +39,13 @@ properties: compatible: items: - enum: + # Admatec 9904379 10.1" 1024x600 LVDS panel + - admatec,9904379 - auo,b101ew05 # Chunghwa Picture Tubes Ltd. 7" WXGA (800x1280) TFT LCD LVDS panel - chunghwa,claa070wp03xg + # EDT ETML0700Z9NDHA 7.0" WSVGA (1024x600) color TFT LCD LVDS panel + - edt,etml0700z9ndha # HannStar Display Corp. HSD101PWW2 10.1" WXGA (1280x800) LVDS panel - hannstar,hsd101pww2 # Hydis Technologies 7" WXGA (800x1280) TFT LCD LVDS panel diff --git a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml index 634a10c6f2dddd..a95445f408700b 100644 --- a/Documentation/devicetree/bindings/display/panel/panel-simple.yaml +++ b/Documentation/devicetree/bindings/display/panel/panel-simple.yaml @@ -73,6 +73,8 @@ properties: - auo,t215hvn01 # Shanghai AVIC Optoelectronics 7" 1024x600 color TFT-LCD panel - avic,tm070ddh03 + # BOE BP082WX1-100 8.2" WXGA (1280x800) LVDS panel + - boe,bp082wx1-100 # BOE BP101WX1-100 10.1" WXGA (1280x800) LVDS panel - boe,bp101wx1-100 # BOE EV121WXM-N10-1850 12.1" WXGA (1280x800) TFT LCD panel @@ -141,6 +143,8 @@ properties: - edt,etm0700g0edh6 # Emerging Display Technology Corp. LVDS WSVGA TFT Display with capacitive touch - edt,etml0700y5dha + # Emerging Display Technology Corp. 10.1" LVDS WXGA TFT Display with capacitive touch + - edt,etml1010g3dra # Emerging Display Technology Corp. 5.7" VGA TFT LCD panel with # capacitive touch - edt,etmv570g2dhu diff --git a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml index 97cccd8a8479a5..6ec471284f97b6 100644 --- a/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml +++ b/Documentation/devicetree/bindings/display/panel/rocktech,jh057n00900.yaml @@ -22,6 +22,8 @@ properties: enum: # Anberic RG353V-V2 5.0" 640x480 TFT LCD panel - anbernic,rg353v-panel-v2 + # Powkiddy RGB10MAX3 5.0" 720x1280 TFT LCD panel + - powkiddy,rgb10max3-panel # Powkiddy RGB30 3.0" 720x720 TFT LCD panel - powkiddy,rgb30-panel # Rocktech JH057N00900 5.5" 720x1440 TFT LCD panel @@ -43,6 +45,7 @@ properties: reset-gpios: true backlight: true + rotation: true required: - compatible diff --git a/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml b/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml index 6ba3236839215a..187840bb76c7a5 100644 --- a/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml +++ b/Documentation/devicetree/bindings/display/panel/visionox,r66451.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- $id: http://devicetree.org/schemas/display/panel/visionox,r66451.yaml# diff --git a/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml index fa745a6f4456c5..77239906751587 100644 --- a/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml +++ b/Documentation/devicetree/bindings/display/panel/visionox,rm69299.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Visionox model RM69299 Panels maintainers: - - Harigovindan P + - Abhinav Kumar + - Jessica Zhang description: | This binding is for display panels using a Visionox RM692999 panel. diff --git a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml index 7e59dee15a5f4c..af638b6c0d2188 100644 --- a/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml +++ b/Documentation/devicetree/bindings/display/rockchip/rockchip,dw-hdmi.yaml @@ -94,11 +94,14 @@ properties: - const: default - const: unwedge + power-domains: + maxItems: 1 + ports: $ref: /schemas/graph.yaml#/properties/ports - patternProperties: - "^port(@0)?$": + properties: + port@0: $ref: /schemas/graph.yaml#/properties/port description: Input of the DWC HDMI TX properties: @@ -108,11 +111,14 @@ properties: description: Connection to the VOPB endpoint@1: description: Connection to the VOPL - properties: port@1: $ref: /schemas/graph.yaml#/properties/port description: Output of the DWC HDMI TX + required: + - port@0 + - port@1 + rockchip,grf: $ref: /schemas/types.yaml#/definitions/phandle description: @@ -135,19 +141,25 @@ examples: #include #include #include + #include hdmi: hdmi@ff980000 { compatible = "rockchip,rk3288-dw-hdmi"; reg = <0xff980000 0x20000>; reg-io-width = <4>; - ddc-i2c-bus = <&i2c5>; - rockchip,grf = <&grf>; interrupts = ; clocks = <&cru PCLK_HDMI_CTRL>, <&cru SCLK_HDMI_HDCP>; clock-names = "iahb", "isfr"; + ddc-i2c-bus = <&i2c5>; + power-domains = <&power RK3288_PD_VIO>; + rockchip,grf = <&grf>; ports { - port { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; #address-cells = <1>; #size-cells = <0>; @@ -155,11 +167,20 @@ examples: reg = <0>; remote-endpoint = <&vopb_out_hdmi>; }; + hdmi_in_vopl: endpoint@1 { reg = <1>; remote-endpoint = <&vopl_out_hdmi>; }; }; + + port@1 { + reg = <1>; + + hdmi_out_con: endpoint { + remote-endpoint = <&hdmi_con_in>; + }; + }; }; }; diff --git a/Documentation/devicetree/bindings/display/samsung/samsung,exynos-mixer.yaml b/Documentation/devicetree/bindings/display/samsung/samsung,exynos-mixer.yaml index 25d53fde92e110..597c9cc6a312ac 100644 --- a/Documentation/devicetree/bindings/display/samsung/samsung,exynos-mixer.yaml +++ b/Documentation/devicetree/bindings/display/samsung/samsung,exynos-mixer.yaml @@ -85,7 +85,7 @@ allOf: clocks: minItems: 6 maxItems: 6 - regs: + reg: minItems: 2 maxItems: 2 @@ -99,7 +99,7 @@ allOf: clocks: minItems: 4 maxItems: 4 - regs: + reg: minItems: 2 maxItems: 2 @@ -116,7 +116,7 @@ allOf: clocks: minItems: 3 maxItems: 3 - regs: + reg: minItems: 1 maxItems: 1 diff --git a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml index 3afbb52d1b7fe5..153ff86fb40590 100644 --- a/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml +++ b/Documentation/devicetree/bindings/display/solomon,ssd1307fb.yaml @@ -131,9 +131,9 @@ allOf: const: sinowealth,sh1106 then: properties: - width: + solomon,width: default: 132 - height: + solomon,height: default: 64 solomon,dclk-div: default: 1 @@ -149,9 +149,9 @@ allOf: - solomon,ssd1305 then: properties: - width: + solomon,width: default: 132 - height: + solomon,height: default: 64 solomon,dclk-div: default: 1 @@ -167,9 +167,9 @@ allOf: - solomon,ssd1306 then: properties: - width: + solomon,width: default: 128 - height: + solomon,height: default: 64 solomon,dclk-div: default: 1 @@ -185,9 +185,9 @@ allOf: - solomon,ssd1307 then: properties: - width: + solomon,width: default: 128 - height: + solomon,height: default: 39 solomon,dclk-div: default: 2 @@ -205,9 +205,9 @@ allOf: - solomon,ssd1309 then: properties: - width: + solomon,width: default: 128 - height: + solomon,height: default: 64 solomon,dclk-div: default: 1 diff --git a/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml b/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml index 37975ee61c5ad4..dd7939989cf4f1 100644 --- a/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml +++ b/Documentation/devicetree/bindings/display/solomon,ssd132x.yaml @@ -30,9 +30,9 @@ allOf: const: solomon,ssd1322 then: properties: - width: + solomon,width: default: 480 - height: + solomon,height: default: 128 - if: @@ -42,9 +42,9 @@ allOf: const: solomon,ssd1325 then: properties: - width: + solomon,width: default: 128 - height: + solomon,height: default: 80 - if: @@ -54,9 +54,9 @@ allOf: const: solomon,ssd1327 then: properties: - width: + solomon,width: default: 128 - height: + solomon,height: default: 128 unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/display/solomon,ssd133x.yaml b/Documentation/devicetree/bindings/display/solomon,ssd133x.yaml new file mode 100644 index 00000000000000..b7780038a34b40 --- /dev/null +++ b/Documentation/devicetree/bindings/display/solomon,ssd133x.yaml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/display/solomon,ssd133x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Solomon SSD133x OLED Display Controllers + +maintainers: + - Javier Martinez Canillas + +allOf: + - $ref: solomon,ssd-common.yaml# + +properties: + compatible: + enum: + - solomon,ssd1331 + + solomon,width: + default: 96 + + solomon,height: + default: 64 + +required: + - compatible + - reg + +unevaluatedProperties: false + +examples: + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + oled@0 { + compatible = "solomon,ssd1331"; + reg = <0x0>; + reset-gpios = <&gpio2 7>; + dc-gpios = <&gpio2 8>; + spi-max-frequency = <10000000>; + }; + }; diff --git a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml index b6767ef0d24dec..55e3e490d0e615 100644 --- a/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml +++ b/Documentation/devicetree/bindings/display/ti/ti,am65x-dss.yaml @@ -37,6 +37,7 @@ properties: - description: OVR2 overlay manager for vp2 - description: VP1 video port 1 - description: VP2 video port 2 + - description: common1 DSS register area reg-names: items: @@ -47,6 +48,7 @@ properties: - const: ovr2 - const: vp1 - const: vp2 + - const: common1 clocks: items: @@ -147,9 +149,10 @@ examples: <0x04a07000 0x1000>, /* ovr1 */ <0x04a08000 0x1000>, /* ovr2 */ <0x04a0a000 0x1000>, /* vp1 */ - <0x04a0b000 0x1000>; /* vp2 */ + <0x04a0b000 0x1000>, /* vp2 */ + <0x04a01000 0x1000>; /* common1 */ reg-names = "common", "vidl1", "vid", - "ovr1", "ovr2", "vp1", "vp2"; + "ovr1", "ovr2", "vp1", "vp2", "common1"; ti,am65x-oldi-io-ctrl = <&dss_oldi_io_ctrl>; power-domains = <&k3_pds 67 TI_SCI_PD_EXCLUSIVE>; clocks = <&k3_clks 67 1>, diff --git a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml index ec2d7a789ffe25..0f2501f72ccace 100644 --- a/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml +++ b/Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml @@ -28,6 +28,9 @@ properties: - items: - const: allwinner,sun8i-r40-dma - const: allwinner,sun50i-a64-dma + - items: + - const: allwinner,sun50i-h616-dma + - const: allwinner,sun50i-a100-dma reg: maxItems: 1 @@ -59,10 +62,11 @@ required: if: properties: compatible: - enum: - - allwinner,sun20i-d1-dma - - allwinner,sun50i-a100-dma - - allwinner,sun50i-h6-dma + contains: + enum: + - allwinner,sun20i-d1-dma + - allwinner,sun50i-a100-dma + - allwinner,sun50i-h6-dma then: properties: diff --git a/Documentation/devicetree/bindings/dma/fsl,edma.yaml b/Documentation/devicetree/bindings/dma/fsl,edma.yaml index 437db0c62339fa..aa51d278cb67b4 100644 --- a/Documentation/devicetree/bindings/dma/fsl,edma.yaml +++ b/Documentation/devicetree/bindings/dma/fsl,edma.yaml @@ -25,6 +25,7 @@ properties: - fsl,imx8qm-edma - fsl,imx93-edma3 - fsl,imx93-edma4 + - fsl,imx95-edma5 - items: - const: fsl,ls1028a-edma - const: fsl,vf610-edma @@ -83,6 +84,7 @@ allOf: - fsl,imx8qm-edma - fsl,imx93-edma3 - fsl,imx93-edma4 + - fsl,imx95-edma5 then: properties: "#dma-cells": diff --git a/Documentation/devicetree/bindings/dma/marvell,mmp-dma.yaml b/Documentation/devicetree/bindings/dma/marvell,mmp-dma.yaml new file mode 100644 index 00000000000000..d447d5207be043 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/marvell,mmp-dma.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/marvell,mmp-dma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell MMP DMA controller + +maintainers: + - Duje Mihanović + +description: + Marvell MMP SoCs may have two types of DMA controllers, peripheral and audio. + +properties: + compatible: + enum: + - marvell,pdma-1.0 + - marvell,adma-1.0 + - marvell,pxa910-squ + + reg: + maxItems: 1 + + interrupts: + description: + Interrupt lines for the controller, may be shared or one per DMA channel + minItems: 1 + + asram: + description: + A phandle to the SRAM pool + $ref: /schemas/types.yaml#/definitions/phandle + + '#dma-channels': + deprecated: true + + '#dma-requests': + deprecated: true + +required: + - compatible + - reg + - interrupts + - '#dma-cells' + +allOf: + - $ref: dma-controller.yaml# + - if: + properties: + compatible: + contains: + enum: + - marvell,pdma-1.0 + then: + properties: + asram: false + else: + required: + - asram + +unevaluatedProperties: false + +examples: + - | + dma-controller@d4000000 { + compatible = "marvell,pdma-1.0"; + reg = <0xd4000000 0x10000>; + interrupts = <47>; + #dma-cells = <2>; + dma-channels = <16>; + }; diff --git a/Documentation/devicetree/bindings/dma/mediatek,mt7622-hsdma.yaml b/Documentation/devicetree/bindings/dma/mediatek,mt7622-hsdma.yaml new file mode 100644 index 00000000000000..3f1e120e40a38c --- /dev/null +++ b/Documentation/devicetree/bindings/dma/mediatek,mt7622-hsdma.yaml @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/dma/mediatek,mt7622-hsdma.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek High-Speed DMA Controller + +maintainers: + - Sean Wang + +allOf: + - $ref: dma-controller.yaml# + +properties: + compatible: + enum: + - mediatek,mt7622-hsdma + - mediatek,mt7623-hsdma + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + + clock-names: + const: hsdma + + power-domains: + maxItems: 1 + + "#dma-cells": + description: Channel number + const: 1 + +required: + - reg + - interrupts + - clocks + - clock-names + - power-domains + +unevaluatedProperties: false + +examples: + - | + #include + #include + #include + + dma-controller@1b007000 { + compatible = "mediatek,mt7623-hsdma"; + reg = <0x1b007000 0x1000>; + interrupts = ; + clocks = <ðsys CLK_ETHSYS_HSDMA>; + clock-names = "hsdma"; + power-domains = <&scpsys MT2701_POWER_DOMAIN_ETH>; + #dma-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/dma/mmp-dma.txt b/Documentation/devicetree/bindings/dma/mmp-dma.txt deleted file mode 100644 index ec18bf0a802a79..00000000000000 --- a/Documentation/devicetree/bindings/dma/mmp-dma.txt +++ /dev/null @@ -1,81 +0,0 @@ -* MARVELL MMP DMA controller - -Marvell Peripheral DMA Controller -Used platforms: pxa688, pxa910, pxa3xx, etc - -Required properties: -- compatible: Should be "marvell,pdma-1.0" -- reg: Should contain DMA registers location and length. -- interrupts: Either contain all of the per-channel DMA interrupts - or one irq for pdma device - -Optional properties: -- dma-channels: Number of DMA channels supported by the controller (defaults - to 32 when not specified) -- #dma-channels: deprecated -- dma-requests: Number of DMA requestor lines supported by the controller - (defaults to 32 when not specified) -- #dma-requests: deprecated - -"marvell,pdma-1.0" -Used platforms: pxa25x, pxa27x, pxa3xx, pxa93x, pxa168, pxa910, pxa688. - -Examples: - -/* - * Each channel has specific irq - * ICU parse out irq channel from ICU register, - * while DMA controller may not able to distinguish the irq channel - * Using this method, interrupt-parent is required as demuxer - * For example, pxa688 icu register 0x128, bit 0~15 is PDMA channel irq, - * 18~21 is ADMA irq - */ -pdma: dma-controller@d4000000 { - compatible = "marvell,pdma-1.0"; - reg = <0xd4000000 0x10000>; - interrupts = <0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15>; - interrupt-parent = <&intcmux32>; - dma-channels = <16>; - }; - -/* - * One irq for all channels - * Dmaengine driver (DMA controller) distinguish irq channel via - * parsing internal register - */ -pdma: dma-controller@d4000000 { - compatible = "marvell,pdma-1.0"; - reg = <0xd4000000 0x10000>; - interrupts = <47>; - dma-channels = <16>; - }; - - -Marvell Two Channel DMA Controller used specifically for audio -Used platforms: pxa688, pxa910 - -Required properties: -- compatible: Should be "marvell,adma-1.0" or "marvell,pxa910-squ" -- reg: Should contain DMA registers location and length. -- interrupts: Either contain all of the per-channel DMA interrupts - or one irq for dma device - -"marvell,adma-1.0" used on pxa688 -"marvell,pxa910-squ" used on pxa910 - -Examples: - -/* each channel has specific irq */ -adma0: dma-controller@d42a0800 { - compatible = "marvell,adma-1.0"; - reg = <0xd42a0800 0x100>; - interrupts = <18 19>; - interrupt-parent = <&intcmux32>; - }; - -/* One irq for all channels */ -squ: dma-controller@d42a0800 { - compatible = "marvell,pxa910-squ"; - reg = <0xd42a0800 0x100>; - interrupts = <46>; - }; diff --git a/Documentation/devicetree/bindings/dma/mtk-hsdma.txt b/Documentation/devicetree/bindings/dma/mtk-hsdma.txt deleted file mode 100644 index 4bb317359dc696..00000000000000 --- a/Documentation/devicetree/bindings/dma/mtk-hsdma.txt +++ /dev/null @@ -1,33 +0,0 @@ -MediaTek High-Speed DMA Controller -================================== - -This device follows the generic DMA bindings defined in dma/dma.txt. - -Required properties: - -- compatible: Must be one of - "mediatek,mt7622-hsdma": for MT7622 SoC - "mediatek,mt7623-hsdma": for MT7623 SoC -- reg: Should contain the register's base address and length. -- interrupts: Should contain a reference to the interrupt used by this - device. -- clocks: Should be the clock specifiers corresponding to the entry in - clock-names property. -- clock-names: Should contain "hsdma" entries. -- power-domains: Phandle to the power domain that the device is part of -- #dma-cells: The length of the DMA specifier, must be <1>. This one cell - in dmas property of a client device represents the channel - number. -Example: - - hsdma: dma-controller@1b007000 { - compatible = "mediatek,mt7623-hsdma"; - reg = <0 0x1b007000 0 0x1000>; - interrupts = ; - clocks = <ðsys CLK_ETHSYS_HSDMA>; - clock-names = "hsdma"; - power-domains = <&scpsys MT2701_POWER_DOMAIN_ETH>; - #dma-cells = <1>; - }; - -DMA clients must use the format described in dma/dma.txt file. diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml index 03aa067b1229f6..04fc4a99a7cb53 100644 --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.yaml @@ -46,6 +46,7 @@ properties: - renesas,dmac-r8a779a0 # R-Car V3U - renesas,dmac-r8a779f0 # R-Car S4-8 - renesas,dmac-r8a779g0 # R-Car V4H + - renesas,dmac-r8a779h0 # R-Car V4M - const: renesas,rcar-gen4-dmac # R-Car Gen4 reg: true diff --git a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml index 8e584857ddd4fb..ab8f32c440dfa9 100644 --- a/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml +++ b/Documentation/devicetree/bindings/firmware/xilinx/xlnx,zynqmp-firmware.yaml @@ -26,6 +26,12 @@ properties: - description: For implementations complying for Versal. const: xlnx,versal-firmware + - description: For implementations complying for Versal NET. + items: + - enum: + - xlnx,versal-net-firmware + - const: xlnx,versal-firmware + method: description: | The method of calling the PM-API firmware layer. @@ -41,7 +47,53 @@ properties: "#power-domain-cells": const: 1 - versal_fpga: + clock-controller: + $ref: /schemas/clock/xlnx,versal-clk.yaml# + description: The clock controller is a hardware block of Xilinx versal + clock tree. It reads required input clock frequencies from the devicetree + and acts as clock provider for all clock consumers of PS clocks.list of + clock specifiers which are external input clocks to the given clock + controller. + type: object + + gpio: + $ref: /schemas/gpio/xlnx,zynqmp-gpio-modepin.yaml# + description: The gpio node describes connect to PS_MODE pins via firmware + interface. + type: object + + soc-nvmem: + $ref: /schemas/nvmem/xlnx,zynqmp-nvmem.yaml# + description: The ZynqMP MPSoC provides access to the hardware related data + like SOC revision, IDCODE and specific purpose efuses. + type: object + + pcap: + $ref: /schemas/fpga/xlnx,zynqmp-pcap-fpga.yaml + description: The ZynqMP SoC uses the PCAP (Processor Configuration Port) to + configure the Programmable Logic (PL). The configuration uses the + firmware interface. + type: object + + pinctrl: + $ref: /schemas/pinctrl/xlnx,zynqmp-pinctrl.yaml# + description: The pinctrl node provides access to pinconfig and pincontrol + functionality available in firmware. + type: object + + power-management: + $ref: /schemas/power/reset/xlnx,zynqmp-power.yaml# + description: The zynqmp-power node describes the power management + configurations. It will control remote suspend/shutdown interfaces. + type: object + + reset-controller: + $ref: /schemas/reset/xlnx,zynqmp-reset.yaml# + description: The reset-controller node describes connection to the reset + functionality via firmware interface. + type: object + + versal-fpga: $ref: /schemas/fpga/xlnx,versal-fpga.yaml# description: Compatible of the FPGA device. type: object @@ -53,15 +105,6 @@ properties: vector. type: object - clock-controller: - $ref: /schemas/clock/xlnx,versal-clk.yaml# - description: The clock controller is a hardware block of Xilinx versal - clock tree. It reads required input clock frequencies from the devicetree - and acts as clock provider for all clock consumers of PS clocks.list of - clock specifiers which are external input clocks to the given clock - controller. - type: object - required: - compatible @@ -73,7 +116,38 @@ examples: firmware { zynqmp_firmware: zynqmp-firmware { #power-domain-cells = <1>; + soc-nvmem { + compatible = "xlnx,zynqmp-nvmem-fw"; + nvmem-layout { + compatible = "fixed-layout"; + #address-cells = <1>; + #size-cells = <1>; + + soc_revision: soc-revision@0 { + reg = <0x0 0x4>; + }; + }; + }; + gpio { + compatible = "xlnx,zynqmp-gpio-modepin"; + gpio-controller; + #gpio-cells = <2>; + }; + pcap { + compatible = "xlnx,zynqmp-pcap-fpga"; }; + pinctrl { + compatible = "xlnx,zynqmp-pinctrl"; + }; + power-management { + compatible = "xlnx,zynqmp-power"; + interrupts = <0 35 4>; + }; + reset-controller { + compatible = "xlnx,zynqmp-reset"; + #reset-cells = <1>; + }; + }; }; sata { @@ -84,7 +158,7 @@ examples: compatible = "xlnx,versal-firmware"; method = "smc"; - versal_fpga: versal_fpga { + versal_fpga: versal-fpga { compatible = "xlnx,versal-fpga"; }; diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt deleted file mode 100644 index 528df8a0e6d849..00000000000000 --- a/Documentation/devicetree/bindings/fpga/fpga-region.txt +++ /dev/null @@ -1,479 +0,0 @@ -FPGA Region Device Tree Binding - -Alan Tull 2016 - - CONTENTS - - Introduction - - Terminology - - Sequence - - FPGA Region - - Supported Use Models - - Device Tree Examples - - Constraints - - -Introduction -============ - -FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in -the Device Tree. FPGA Regions provide a way to program FPGAs under device tree -control. - -This device tree binding document hits some of the high points of FPGA usage and -attempts to include terminology used by both major FPGA manufacturers. This -document isn't a replacement for any manufacturers specifications for FPGA -usage. - - -Terminology -=========== - -Full Reconfiguration - * The entire FPGA is programmed. - -Partial Reconfiguration (PR) - * A section of an FPGA is reprogrammed while the rest of the FPGA is not - affected. - * Not all FPGA's support PR. - -Partial Reconfiguration Region (PRR) - * Also called a "reconfigurable partition" - * A PRR is a specific section of an FPGA reserved for reconfiguration. - * A base (or static) FPGA image may create a set of PRR's that later may - be independently reprogrammed many times. - * The size and specific location of each PRR is fixed. - * The connections at the edge of each PRR are fixed. The image that is loaded - into a PRR must fit and must use a subset of the region's connections. - * The busses within the FPGA are split such that each region gets its own - branch that may be gated independently. - -Persona - * Also called a "partial bit stream" - * An FPGA image that is designed to be loaded into a PRR. There may be - any number of personas designed to fit into a PRR, but only one at at time - may be loaded. - * A persona may create more regions. - -FPGA Bridge - * FPGA Bridges gate bus signals between a host and FPGA. - * FPGA Bridges should be disabled while the FPGA is being programmed to - prevent spurious signals on the cpu bus and to the soft logic. - * FPGA bridges may be actual hardware or soft logic on an FPGA. - * During Full Reconfiguration, hardware bridges between the host and FPGA - will be disabled. - * During Partial Reconfiguration of a specific region, that region's bridge - will be used to gate the busses. Traffic to other regions is not affected. - * In some implementations, the FPGA Manager transparently handles gating the - buses, eliminating the need to show the hardware FPGA bridges in the - device tree. - * An FPGA image may create a set of reprogrammable regions, each having its - own bridge and its own split of the busses in the FPGA. - -FPGA Manager - * An FPGA Manager is a hardware block that programs an FPGA under the control - of a host processor. - -Base Image - * Also called the "static image" - * An FPGA image that is designed to do full reconfiguration of the FPGA. - * A base image may set up a set of partial reconfiguration regions that may - later be reprogrammed. - - ---------------- ---------------------------------- - | Host CPU | | FPGA | - | | | | - | ----| | ----------- -------- | - | | H | | |==>| Bridge0 |<==>| PRR0 | | - | | W | | | ----------- -------- | - | | | | | | - | | B |<=====>|<==| ----------- -------- | - | | R | | |==>| Bridge1 |<==>| PRR1 | | - | | I | | | ----------- -------- | - | | D | | | | - | | G | | | ----------- -------- | - | | E | | |==>| Bridge2 |<==>| PRR2 | | - | ----| | ----------- -------- | - | | | | - ---------------- ---------------------------------- - -Figure 1: An FPGA set up with a base image that created three regions. Each -region (PRR0-2) gets its own split of the busses that is independently gated by -a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be -reprogrammed independently while the rest of the system continues to function. - - -Sequence -======== - -When a DT overlay that targets an FPGA Region is applied, the FPGA Region will -do the following: - - 1. Disable appropriate FPGA bridges. - 2. Program the FPGA using the FPGA manager. - 3. Enable the FPGA bridges. - 4. The Device Tree overlay is accepted into the live tree. - 5. Child devices are populated. - -When the overlay is removed, the child nodes will be removed and the FPGA Region -will disable the bridges. - - -FPGA Region -=========== - -FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA -Region brings together the elements needed to program on a running system and -add the child devices: - - * FPGA Manager - * FPGA Bridges - * image-specific information needed to to the programming. - * child nodes - -The intended use is that a Device Tree overlay (DTO) can be used to reprogram an -FPGA while an operating system is running. - -An FPGA Region that exists in the live Device Tree reflects the current state. -If the live tree shows a "firmware-name" property or child nodes under an FPGA -Region, the FPGA already has been programmed. A DTO that targets an FPGA Region -and adds the "firmware-name" property is taken as a request to reprogram the -FPGA. After reprogramming is successful, the overlay is accepted into the live -tree. - -The base FPGA Region in the device tree represents the FPGA and supports full -reconfiguration. It must include a phandle to an FPGA Manager. The base -FPGA region will be the child of one of the hardware bridges (the bridge that -allows register access) between the cpu and the FPGA. If there are more than -one bridge to control during FPGA programming, the region will also contain a -list of phandles to the additional hardware FPGA Bridges. - -For partial reconfiguration (PR), each PR region will have an FPGA Region. -These FPGA regions are children of FPGA bridges which are then children of the -base FPGA region. The "Full Reconfiguration to add PRR's" example below shows -this. - -If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA -Manager specified by its ancestor FPGA Region. This supports both the case -where the same FPGA Manager is used for all of an FPGA as well the case where -a different FPGA Manager is used for each region. - -FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents -shutting down bridges that are upstream from the other active regions while one -region is getting reconfigured (see Figure 1 above). During PR, the FPGA's -hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges -within the static image of the FPGA. - -Required properties: -- compatible : should contain "fpga-region" -- fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA Regions - inherit this property from their ancestor regions. An fpga-mgr property - in a region will override any inherited FPGA manager. -- #address-cells, #size-cells, ranges : must be present to handle address space - mapping for child nodes. - -Optional properties: -- firmware-name : should contain the name of an FPGA image file located on the - firmware search path. If this property shows up in a live device tree - it indicates that the FPGA has already been programmed with this image. - If this property is in an overlay targeting an FPGA region, it is a - request to program the FPGA with that image. -- fpga-bridges : should contain a list of phandles to FPGA Bridges that must be - controlled during FPGA programming along with the parent FPGA bridge. - This property is optional if the FPGA Manager handles the bridges. - If the fpga-region is the child of an fpga-bridge, the list should not - contain the parent bridge. -- partial-fpga-config : boolean, set if partial reconfiguration is to be done, - otherwise full reconfiguration is done. -- external-fpga-config : boolean, set if the FPGA has already been configured - prior to OS boot up. -- encrypted-fpga-config : boolean, set if the bitstream is encrypted -- region-unfreeze-timeout-us : The maximum time in microseconds to wait for - bridges to successfully become enabled after the region has been - programmed. -- region-freeze-timeout-us : The maximum time in microseconds to wait for - bridges to successfully become disabled before the region has been - programmed. -- config-complete-timeout-us : The maximum time in microseconds time for the - FPGA to go to operating mode after the region has been programmed. -- child nodes : devices in the FPGA after programming. - -In the example below, when an overlay is applied targeting fpga-region0, -fpga_mgr is used to program the FPGA. Two bridges are controlled during -programming: the parent fpga_bridge0 and fpga_bridge1. Because the region is -the child of fpga_bridge0, only fpga_bridge1 needs to be specified in the -fpga-bridges property. During programming, these bridges are disabled, the -firmware specified in the overlay is loaded to the FPGA using the FPGA manager -specified in the region. If FPGA programming succeeds, the bridges are -reenabled and the overlay makes it into the live device tree. The child devices -are then populated. If FPGA programming fails, the bridges are left disabled -and the overlay is rejected. The overlay's ranges property maps the lwhps -bridge's region (0xff200000) and the hps bridge's region (0xc0000000) for use by -the two child devices. - -Example: -Base tree contains: - - fpga_mgr: fpga-mgr@ff706000 { - compatible = "altr,socfpga-fpga-mgr"; - reg = <0xff706000 0x1000 - 0xffb90000 0x20>; - interrupts = <0 175 4>; - }; - - fpga_bridge0: fpga-bridge@ff400000 { - compatible = "altr,socfpga-lwhps2fpga-bridge"; - reg = <0xff400000 0x100000>; - resets = <&rst LWHPS2FPGA_RESET>; - clocks = <&l4_main_clk>; - - #address-cells = <1>; - #size-cells = <1>; - ranges; - - fpga_region0: fpga-region0 { - compatible = "fpga-region"; - fpga-mgr = <&fpga_mgr>; - }; - }; - - fpga_bridge1: fpga-bridge@ff500000 { - compatible = "altr,socfpga-hps2fpga-bridge"; - reg = <0xff500000 0x10000>; - resets = <&rst HPS2FPGA_RESET>; - clocks = <&l4_main_clk>; - }; - -Overlay contains: - -/dts-v1/; -/plugin/; - -&fpga_region0 { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_system.rbf"; - fpga-bridges = <&fpga_bridge1>; - ranges = <0x20000 0xff200000 0x100000>, - <0x0 0xc0000000 0x20000000>; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - altr,ngpio = <4>; - #gpio-cells = <2>; - clocks = <2>; - gpio-controller; - }; - - onchip-memory { - device_type = "memory"; - compatible = "altr,onchipmem-15.1"; - reg = <0x0 0x10000>; - }; -}; - - -Supported Use Models -==================== - -In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and -a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some -uses are specific to an FPGA device. - - * No FPGA Bridges - In this case, the FPGA Manager which programs the FPGA also handles the - bridges behind the scenes. No FPGA Bridge devices are needed for full - reconfiguration. - - * Full reconfiguration with hardware bridges - In this case, there are hardware bridges between the processor and FPGA that - need to be controlled during full reconfiguration. Before the overlay is - applied, the live DT must include the FPGA Manager, FPGA Bridges, and a - FPGA Region. The FPGA Region is the child of the bridge that allows - register access to the FPGA. Additional bridges may be listed in a - fpga-bridges property in the FPGA region or in the device tree overlay. - - * Partial reconfiguration with bridges in the FPGA - In this case, the FPGA will have one or more PRR's that may be programmed - separately while the rest of the FPGA can remain active. To manage this, - bridges need to exist in the FPGA that can gate the buses going to each FPGA - region while the buses are enabled for other sections. Before any partial - reconfiguration can be done, a base FPGA image must be loaded which includes - PRR's with FPGA bridges. The device tree should have an FPGA region for each - PRR. - -Device Tree Examples -==================== - -The intention of this section is to give some simple examples, focusing on -the placement of the elements detailed above, especially: - * FPGA Manager - * FPGA Bridges - * FPGA Region - * ranges - * target-path or target - -For the purposes of this section, I'm dividing the Device Tree into two parts, -each with its own requirements. The two parts are: - * The live DT prior to the overlay being added - * The DT overlay - -The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA -Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle -to handle programming the FPGA. If the FPGA Region is the child of another FPGA -Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved, -they are specified in the FPGA Region by the "fpga-bridges" property. During -FPGA programming, the FPGA Region will disable the bridges that are in its -"fpga-bridges" list and will re-enable them after FPGA programming has -succeeded. - -The Device Tree Overlay will contain: - * "target-path" or "target" - The insertion point where the contents of the overlay will go into the - live tree. target-path is a full path, while target is a phandle. - * "ranges" - The address space mapping from processor to FPGA bus(ses). - * "firmware-name" - Specifies the name of the FPGA image file on the firmware search - path. The search path is described in the firmware class documentation. - * "partial-fpga-config" - This binding is a boolean and should be present if partial reconfiguration - is to be done. - * child nodes corresponding to hardware that will be loaded in this region of - the FPGA. - -Device Tree Example: Full Reconfiguration without Bridges -========================================================= - -Live Device Tree contains: - fpga_mgr0: fpga-mgr@f8007000 { - compatible = "xlnx,zynq-devcfg-1.0"; - reg = <0xf8007000 0x100>; - interrupt-parent = <&intc>; - interrupts = <0 8 4>; - clocks = <&clkc 12>; - clock-names = "ref_clk"; - syscon = <&slcr>; - }; - - fpga_region0: fpga-region0 { - compatible = "fpga-region"; - fpga-mgr = <&fpga_mgr0>; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - -DT Overlay contains: - -/dts-v1/; -/plugin/; - -&fpga_region0 { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "zynq-gpio.bin"; - - gpio1: gpio@40000000 { - compatible = "xlnx,xps-gpio-1.00.a"; - reg = <0x40000000 0x10000>; - gpio-controller; - #gpio-cells = <0x2>; - xlnx,gpio-width= <0x6>; - }; -}; - -Device Tree Example: Full Reconfiguration to add PRR's -====================================================== - -The base FPGA Region is specified similar to the first example above. - -This example programs the FPGA to have two regions that can later be partially -configured. Each region has its own bridge in the FPGA fabric. - -DT Overlay contains: - -/dts-v1/; -/plugin/; - -&fpga_region0 { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "base.rbf"; - - fpga-bridge@4400 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4400 0x10>; - - fpga_region1: fpga-region1 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; - - fpga-bridge@4420 { - compatible = "altr,freeze-bridge-controller"; - reg = <0x4420 0x10>; - - fpga_region2: fpga-region2 { - compatible = "fpga-region"; - #address-cells = <0x1>; - #size-cells = <0x1>; - ranges; - }; - }; -}; - -Device Tree Example: Partial Reconfiguration -============================================ - -This example reprograms one of the PRR's set up in the previous example. - -The sequence that occurs when this overlay is similar to the above, the only -differences are that the FPGA is partially reconfigured due to the -"partial-fpga-config" boolean and the only bridge that is controlled during -programming is the FPGA based bridge of fpga_region1. - -/dts-v1/; -/plugin/; - -&fpga_region1 { - #address-cells = <1>; - #size-cells = <1>; - - firmware-name = "soc_image2.rbf"; - partial-fpga-config; - - gpio@10040 { - compatible = "altr,pio-1.0"; - reg = <0x10040 0x20>; - clocks = <0x2>; - altr,ngpio = <0x4>; - #gpio-cells = <0x2>; - gpio-controller; - }; -}; - -Constraints -=========== - -It is beyond the scope of this document to fully describe all the FPGA design -constraints required to make partial reconfiguration work[1] [2] [3], but a few -deserve quick mention. - -A persona must have boundary connections that line up with those of the partition -or region it is designed to go into. - -During programming, transactions through those connections must be stopped and -the connections must be held at a fixed logic level. This can be achieved by -FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration. - --- -[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf -[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf -[3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.yaml b/Documentation/devicetree/bindings/fpga/fpga-region.yaml new file mode 100644 index 00000000000000..77554885a6c49e --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/fpga-region.yaml @@ -0,0 +1,358 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/fpga/fpga-region.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: FPGA Region + +maintainers: + - Michal Simek + +description: | + CONTENTS + - Introduction + - Terminology + - Sequence + - FPGA Region + - Supported Use Models + - Constraints + + + Introduction + ============ + + FPGA Regions represent FPGA's and partial reconfiguration regions of FPGA's in + the Device Tree. FPGA Regions provide a way to program FPGAs under device tree + control. + + The documentation hits some of the high points of FPGA usage and + attempts to include terminology used by both major FPGA manufacturers. This + document isn't a replacement for any manufacturers specifications for FPGA + usage. + + + Terminology + =========== + + Full Reconfiguration + * The entire FPGA is programmed. + + Partial Reconfiguration (PR) + * A section of an FPGA is reprogrammed while the rest of the FPGA is not + affected. + * Not all FPGA's support PR. + + Partial Reconfiguration Region (PRR) + * Also called a "reconfigurable partition" + * A PRR is a specific section of an FPGA reserved for reconfiguration. + * A base (or static) FPGA image may create a set of PRR's that later may + be independently reprogrammed many times. + * The size and specific location of each PRR is fixed. + * The connections at the edge of each PRR are fixed. The image that is loaded + into a PRR must fit and must use a subset of the region's connections. + * The busses within the FPGA are split such that each region gets its own + branch that may be gated independently. + + Persona + * Also called a "partial bit stream" + * An FPGA image that is designed to be loaded into a PRR. There may be + any number of personas designed to fit into a PRR, but only one at a time + may be loaded. + * A persona may create more regions. + + FPGA Bridge + * FPGA Bridges gate bus signals between a host and FPGA. + * FPGA Bridges should be disabled while the FPGA is being programmed to + prevent spurious signals on the cpu bus and to the soft logic. + * FPGA bridges may be actual hardware or soft logic on an FPGA. + * During Full Reconfiguration, hardware bridges between the host and FPGA + will be disabled. + * During Partial Reconfiguration of a specific region, that region's bridge + will be used to gate the busses. Traffic to other regions is not affected. + * In some implementations, the FPGA Manager transparently handles gating the + buses, eliminating the need to show the hardware FPGA bridges in the + device tree. + * An FPGA image may create a set of reprogrammable regions, each having its + own bridge and its own split of the busses in the FPGA. + + FPGA Manager + * An FPGA Manager is a hardware block that programs an FPGA under the control + of a host processor. + + Base Image + * Also called the "static image" + * An FPGA image that is designed to do full reconfiguration of the FPGA. + * A base image may set up a set of partial reconfiguration regions that may + later be reprogrammed. + + ---------------- ---------------------------------- + | Host CPU | | FPGA | + | | | | + | ----| | ----------- -------- | + | | H | | |==>| Bridge0 |<==>| PRR0 | | + | | W | | | ----------- -------- | + | | | | | | + | | B |<=====>|<==| ----------- -------- | + | | R | | |==>| Bridge1 |<==>| PRR1 | | + | | I | | | ----------- -------- | + | | D | | | | + | | G | | | ----------- -------- | + | | E | | |==>| Bridge2 |<==>| PRR2 | | + | ----| | ----------- -------- | + | | | | + ---------------- ---------------------------------- + + Figure 1: An FPGA set up with a base image that created three regions. Each + region (PRR0-2) gets its own split of the busses that is independently gated by + a soft logic bridge (Bridge0-2) in the FPGA. The contents of each PRR can be + reprogrammed independently while the rest of the system continues to function. + + + Sequence + ======== + + When a DT overlay that targets an FPGA Region is applied, the FPGA Region will + do the following: + + 1. Disable appropriate FPGA bridges. + 2. Program the FPGA using the FPGA manager. + 3. Enable the FPGA bridges. + 4. The Device Tree overlay is accepted into the live tree. + 5. Child devices are populated. + + When the overlay is removed, the child nodes will be removed and the FPGA Region + will disable the bridges. + + + FPGA Region + =========== + + FPGA Regions represent FPGA's and FPGA PR regions in the device tree. An FPGA + Region brings together the elements needed to program on a running system and + add the child devices: + + * FPGA Manager + * FPGA Bridges + * image-specific information needed to the programming. + * child nodes + + The intended use is that a Device Tree overlay (DTO) can be used to reprogram an + FPGA while an operating system is running. + + An FPGA Region that exists in the live Device Tree reflects the current state. + If the live tree shows a "firmware-name" property or child nodes under an FPGA + Region, the FPGA already has been programmed. A DTO that targets an FPGA Region + and adds the "firmware-name" property is taken as a request to reprogram the + FPGA. After reprogramming is successful, the overlay is accepted into the live + tree. + + The base FPGA Region in the device tree represents the FPGA and supports full + reconfiguration. It must include a phandle to an FPGA Manager. The base + FPGA region will be the child of one of the hardware bridges (the bridge that + allows register access) between the cpu and the FPGA. If there are more than + one bridge to control during FPGA programming, the region will also contain a + list of phandles to the additional hardware FPGA Bridges. + + For partial reconfiguration (PR), each PR region will have an FPGA Region. + These FPGA regions are children of FPGA bridges which are then children of the + base FPGA region. The "Full Reconfiguration to add PRR's" example below shows + this. + + If an FPGA Region does not specify an FPGA Manager, it will inherit the FPGA + Manager specified by its ancestor FPGA Region. This supports both the case + where the same FPGA Manager is used for all of an FPGA as well the case where + a different FPGA Manager is used for each region. + + FPGA Regions do not inherit their ancestor FPGA regions' bridges. This prevents + shutting down bridges that are upstream from the other active regions while one + region is getting reconfigured (see Figure 1 above). During PR, the FPGA's + hardware bridges remain enabled. The PR regions' bridges will be FPGA bridges + within the static image of the FPGA. + + + Supported Use Models + ==================== + + In all cases the live DT must have the FPGA Manager, FPGA Bridges (if any), and + a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. Some + uses are specific to an FPGA device. + + * No FPGA Bridges + In this case, the FPGA Manager which programs the FPGA also handles the + bridges behind the scenes. No FPGA Bridge devices are needed for full + reconfiguration. + + * Full reconfiguration with hardware bridges + In this case, there are hardware bridges between the processor and FPGA that + need to be controlled during full reconfiguration. Before the overlay is + applied, the live DT must include the FPGA Manager, FPGA Bridges, and a + FPGA Region. The FPGA Region is the child of the bridge that allows + register access to the FPGA. Additional bridges may be listed in a + fpga-bridges property in the FPGA region or in the device tree overlay. + + * Partial reconfiguration with bridges in the FPGA + In this case, the FPGA will have one or more PRR's that may be programmed + separately while the rest of the FPGA can remain active. To manage this, + bridges need to exist in the FPGA that can gate the buses going to each FPGA + region while the buses are enabled for other sections. Before any partial + reconfiguration can be done, a base FPGA image must be loaded which includes + PRR's with FPGA bridges. The device tree should have an FPGA region for each + PRR. + + Constraints + =========== + + It is beyond the scope of this document to fully describe all the FPGA design + constraints required to make partial reconfiguration work[1] [2] [3], but a few + deserve quick mention. + + A persona must have boundary connections that line up with those of the partition + or region it is designed to go into. + + During programming, transactions through those connections must be stopped and + the connections must be held at a fixed logic level. This can be achieved by + FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration. + + -- + [1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf + [2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf + [3] https://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf + +properties: + $nodename: + pattern: "^fpga-region(@.*|-([0-9]|[1-9][0-9]+))?$" + + compatible: + const: fpga-region + + reg: + maxItems: 1 + + ranges: true + "#address-cells": true + "#size-cells": true + + config-complete-timeout-us: + description: + The maximum time in microseconds time for the FPGA to go to operating + mode after the region has been programmed. + + encrypted-fpga-config: + type: boolean + description: + Set if the bitstream is encrypted. + + external-fpga-config: + type: boolean + description: + Set if the FPGA has already been configured prior to OS boot up. + + firmware-name: + maxItems: 1 + description: + Should contain the name of an FPGA image file located on the firmware + search path. If this property shows up in a live device tree it indicates + that the FPGA has already been programmed with this image. + If this property is in an overlay targeting an FPGA region, it is + a request to program the FPGA with that image. + + fpga-bridges: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: + Should contain a list of phandles to FPGA Bridges that must be + controlled during FPGA programming along with the parent FPGA bridge. + This property is optional if the FPGA Manager handles the bridges. + If the fpga-region is the child of an fpga-bridge, the list should not + contain the parent bridge. + + fpga-mgr: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Should contain a phandle to an FPGA Manager. Child FPGA Regions + inherit this property from their ancestor regions. An fpga-mgr property + in a region will override any inherited FPGA manager. + + partial-fpga-config: + type: boolean + description: + Set if partial reconfiguration is to be done, otherwise full + reconfiguration is done. + + region-freeze-timeout-us: + description: + The maximum time in microseconds to wait for bridges to successfully + become disabled before the region has been programmed. + + region-unfreeze-timeout-us: + description: + The maximum time in microseconds to wait for bridges to successfully + become enabled after the region has been programmed. + +required: + - compatible + - fpga-mgr + +additionalProperties: + type: object + +examples: + - | + /* + * Full Reconfiguration without Bridges with DT overlay + */ + fpga_region0: fpga-region@0 { + compatible = "fpga-region"; + reg = <0 0>; + #address-cells = <1>; + #size-cells = <1>; + fpga-mgr = <&fpga_mgr0>; + ranges = <0x10000000 0x20000000 0x10000000>; + + /* DT Overlay contains: &fpga_region0 */ + firmware-name = "zynq-gpio.bin"; + gpio@40000000 { + compatible = "xlnx,xps-gpio-1.00.a"; + reg = <0x40000000 0x10000>; + gpio-controller; + #gpio-cells = <2>; + }; + }; + + - | + /* + * Partial reconfiguration with bridge + */ + fpga_region1: fpga-region@0 { + compatible = "fpga-region"; + reg = <0 0>; + ranges; + #address-cells = <1>; + #size-cells = <1>; + fpga-mgr = <&fpga_mgr1>; + fpga-bridges = <&fpga_bridge1>; + partial-fpga-config; + + /* DT Overlay contains: &fpga_region1 */ + firmware-name = "zynq-gpio-partial.bin"; + clk: clock { + compatible = "fixed-factor-clock"; + clocks = <&parentclk>; + #clock-cells = <0>; + clock-div = <2>; + clock-mult = <1>; + }; + axi { + compatible = "simple-bus"; + #address-cells = <1>; + #size-cells = <1>; + ranges; + gpio@40000000 { + compatible = "xlnx,xps-gpio-1.00.a"; + reg = <0x40000000 0x10000>; + #gpio-cells = <2>; + gpio-controller; + clocks = <&clk>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml index 26f18834caa3ae..80833462f620f3 100644 --- a/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml +++ b/Documentation/devicetree/bindings/fpga/xlnx,versal-fpga.yaml @@ -26,7 +26,7 @@ additionalProperties: false examples: - | - versal_fpga: versal_fpga { + versal_fpga: versal-fpga { compatible = "xlnx,versal-fpga"; }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml index f1bd1e6b2e1f8d..33d4e4716516d5 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.yaml @@ -115,7 +115,7 @@ allOf: required: - reg -unevaluatedProperties: true +unevaluatedProperties: false examples: - | diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml index 452f8972a96590..6f73961001b75e 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml +++ b/Documentation/devicetree/bindings/gpio/gpio-pca9570.yaml @@ -28,6 +28,9 @@ properties: minItems: 4 maxItems: 8 + label: + description: A descriptive name for this device. + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml index 9cf6137dd52413..65155bb701a9fb 100644 --- a/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/mrvl-gpio.yaml @@ -9,7 +9,7 @@ title: Marvell PXA GPIO controller maintainers: - Linus Walleij - Bartosz Golaszewski - - Rob Herring + - Rob Herring allOf: - if: diff --git a/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml index aa424e2b95f87a..cc7a950a603099 100644 --- a/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/renesas,rcar-gpio.yaml @@ -53,6 +53,7 @@ properties: - renesas,gpio-r8a779a0 # R-Car V3U - renesas,gpio-r8a779f0 # R-Car S4-8 - renesas,gpio-r8a779g0 # R-Car V4H + - renesas,gpio-r8a779h0 # R-Car V4M - const: renesas,rcar-gen4-gpio # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml index b1fd632718d496..bb93baa888794b 100644 --- a/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml +++ b/Documentation/devicetree/bindings/gpio/xlnx,zynqmp-gpio-modepin.yaml @@ -12,7 +12,8 @@ description: PS_MODE). Every pin can be configured as input/output. maintainers: - - Piyush Mehta + - Mubin Sayyed + - Radhey Shyam Pandey properties: compatible: diff --git a/Documentation/devicetree/bindings/gpu/img,powervr.yaml b/Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml similarity index 91% rename from Documentation/devicetree/bindings/gpu/img,powervr.yaml rename to Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml index a13298f1a18275..256e252f8087fa 100644 --- a/Documentation/devicetree/bindings/gpu/img,powervr.yaml +++ b/Documentation/devicetree/bindings/gpu/img,powervr-rogue.yaml @@ -2,10 +2,10 @@ # Copyright (c) 2023 Imagination Technologies Ltd. %YAML 1.2 --- -$id: http://devicetree.org/schemas/gpu/img,powervr.yaml# +$id: http://devicetree.org/schemas/gpu/img,powervr-rogue.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Imagination Technologies PowerVR and IMG GPU +title: Imagination Technologies PowerVR and IMG Rogue GPUs maintainers: - Frank Binns diff --git a/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml b/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml new file mode 100644 index 00000000000000..f5898b04381cb6 --- /dev/null +++ b/Documentation/devicetree/bindings/gpu/img,powervr-sgx.yaml @@ -0,0 +1,138 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2023 Imagination Technologies Ltd. +# Copyright (C) 2024 Texas Instruments Incorporated - https://www.ti.com/ +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpu/img,powervr-sgx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Imagination Technologies PowerVR SGX GPUs + +maintainers: + - Frank Binns + +properties: + compatible: + oneOf: + - items: + - enum: + - ti,omap3430-gpu # Rev 121 + - ti,omap3630-gpu # Rev 125 + - const: img,powervr-sgx530 + - items: + - enum: + - ingenic,jz4780-gpu # Rev 130 + - ti,omap4430-gpu # Rev 120 + - const: img,powervr-sgx540 + - items: + - enum: + - allwinner,sun6i-a31-gpu # MP2 Rev 115 + - ti,omap4470-gpu # MP1 Rev 112 + - ti,omap5432-gpu # MP2 Rev 105 + - ti,am5728-gpu # MP2 Rev 116 + - ti,am6548-gpu # MP1 Rev 117 + - const: img,powervr-sgx544 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 1 + maxItems: 3 + + clock-names: + minItems: 1 + items: + - const: core + - const: mem + - const: sys + + power-domains: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + +allOf: + - if: + properties: + compatible: + contains: + const: ti,am6548-gpu + then: + required: + - power-domains + else: + properties: + power-domains: false + - if: + properties: + compatible: + contains: + enum: + - allwinner,sun6i-a31-gpu + - ingenic,jz4780-gpu + then: + required: + - clocks + - clock-names + else: + properties: + clocks: false + clock-names: false + - if: + properties: + compatible: + contains: + const: allwinner,sun6i-a31-gpu + then: + properties: + clocks: + minItems: 2 + maxItems: 2 + clock-names: + minItems: 2 + maxItems: 2 + - if: + properties: + compatible: + contains: + const: ingenic,jz4780-gpu + then: + properties: + clocks: + maxItems: 1 + clock-names: + maxItems: 1 + +additionalProperties: false + +examples: + - | + #include + #include + #include + + gpu@7000000 { + compatible = "ti,am6548-gpu", "img,powervr-sgx544"; + reg = <0x7000000 0x10000>; + interrupts = ; + power-domains = <&k3_pds 65 TI_SCI_PD_EXCLUSIVE>; + }; + + - | + #include + #include + + gpu: gpu@1c40000 { + compatible = "allwinner,sun6i-a31-gpu", "img,powervr-sgx544"; + reg = <0x01c40000 0x10000>; + interrupts = ; + clocks = <&ccu 1>, <&ccu 2>; + clock-names = "core", "mem"; + }; diff --git a/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml b/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml new file mode 100644 index 00000000000000..4854b95a93e341 --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/adi,ltc4282.yaml @@ -0,0 +1,159 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/adi,ltc4282.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C + +maintainers: + - Nuno Sa + +description: | + Analog Devices LTC4282 I2C High Current Hot Swap Controller over I2C. + + https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf + +properties: + compatible: + enum: + - adi,ltc4282 + + reg: + maxItems: 1 + + vdd-supply: true + + clocks: + maxItems: 1 + + '#clock-cells': + const: 0 + + adi,rsense-nano-ohms: + description: Value of the sense resistor. + + adi,vin-mode-microvolt: + description: + Selects operating range for the Undervoltage, Overvoltage and Foldback + pins. Also for the ADC. Should be set to the nominal input voltage. + enum: [3300000, 5000000, 12000000, 24000000] + default: 12000000 + + adi,fet-bad-timeout-ms: + description: + From the moment a FET bad conditions is present, this property selects the + wait time/timeout for a FET-bad fault to be signaled. Setting this to 0, + disables FET bad faults to be reported. + default: 255 + maximum: 255 + + adi,overvoltage-dividers: + description: | + Select which dividers to use for VDD Overvoltage detection. Note that + when the internal dividers are used the threshold is referenced to VDD. + The percentages in the datasheet are misleading since the actual values + to look for are in the "Absolute Maximum Ratings" table in the + "Comparator Inputs" section. In there there's a line for each of the 5%, + 10% and 15% settings with the actual min, typical and max tolerances. + $ref: /schemas/types.yaml#/definitions/string + enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent] + default: external + + adi,undervoltage-dividers: + description: | + Select which dividers to use for VDD Overvoltage detection. Note that + when the internal dividers are used the threshold is referenced to VDD. + The percentages in the datasheet are misleading since the actual values + to look for are in the "Absolute Maximum Ratings" table in the + "Comparator Inputs" section. In there there's a line for each of the 5%, + 10% and 15% settings with the actual min, typical and max tolerances. + $ref: /schemas/types.yaml#/definitions/string + enum: [external, vdd_5_percent, vdd_10_percent, vdd_15_percent] + default: external + + adi,current-limit-sense-microvolt: + description: + The current limit sense voltage of the chip is adjustable between + 12.5mV and 34.4mV in 3.1mV steps. This effectively limits the current + on the load. + enum: [12500, 15625, 18750, 21875, 25000, 28125, 31250, 34375] + default: 25000 + + adi,overcurrent-retry: + description: + If set, enables the chip to auto-retry 256 timer cycles after an + Overcurrent fault. + type: boolean + + adi,overvoltage-retry-disable: + description: + If set, disables the chip to auto-retry 50ms after an Overvoltage fault. + It's enabled by default. + type: boolean + + adi,undervoltage-retry-disable: + description: + If set, disables the chip to auto-retry 50ms after an Undervoltage fault. + It's enabled by default. + type: boolean + + adi,fault-log-enable: + description: + If set, enables the FAULT_LOG and ADC_ALERT_LOG registers to be written + to the EEPROM when a fault bit transitions high and hence, will be + available after a power cycle (the chip loads the contents of + the EE_FAULT_LOG register - the one in EEPROM - into FAULT_LOG at boot). + type: boolean + + adi,gpio1-mode: + description: Defines the function of the Pin. It can indicate that power is + good (PULL the pin low when power is not good) or that power is bad (Go + into high-z when power is not good). + $ref: /schemas/types.yaml#/definitions/string + enum: [power_bad, power_good] + default: power_good + + adi,gpio2-mode: + description: Defines the function of the Pin. It can be set as the input for + the ADC or indicating that the MOSFET is in stress (dissipating power). + $ref: /schemas/types.yaml#/definitions/string + enum: [adc_input, stress_fet] + default: adc_input + + adi,gpio3-monitor-enable: + description: If set, gpio3 is set as input for the ADC instead of gpio2. + type: boolean + +allOf: + - if: + required: + - adi,gpio3-monitor-enable + then: + properties: + adi,gpio2-mode: + const: stress_fet + +required: + - compatible + - reg + - adi,rsense-nano-ohms + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + hwmon@50 { + compatible = "adi,ltc4282"; + reg = <0x50>; + adi,rsense-nano-ohms = <500>; + + adi,gpio1-mode = "power_good"; + adi,gpio2-mode = "adc_input"; + }; + }; +... diff --git a/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml b/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml new file mode 100644 index 00000000000000..17351fdbefce6c --- /dev/null +++ b/Documentation/devicetree/bindings/hwmon/amphenol,chipcap2.yaml @@ -0,0 +1,77 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/hwmon/amphenol,chipcap2.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ChipCap 2 humidity and temperature iio sensor + +maintainers: + - Javier Carrasco + +description: | + Relative humidity and temperature sensor on I2C bus. + + Datasheets: + https://www.amphenol-sensors.com/en/telaire/humidity/527-humidity-sensors/3095-chipcap-2 + +properties: + compatible: + oneOf: + - const: amphenol,cc2d23 + - items: + - enum: + - amphenol,cc2d23s + - amphenol,cc2d25 + - amphenol,cc2d25s + - amphenol,cc2d33 + - amphenol,cc2d33s + - amphenol,cc2d35 + - amphenol,cc2d35s + - const: amphenol,cc2d23 + + reg: + maxItems: 1 + + interrupts: + items: + - description: measurement ready indicator + - description: low humidity alarm + - description: high humidity alarm + + interrupt-names: + items: + - const: ready + - const: low + - const: high + + vdd-supply: + description: + Dedicated, controllable supply-regulator to reset the device and + enter in command mode. + +required: + - compatible + - reg + - vdd-supply + +additionalProperties: false + +examples: + - | + #include + i2c { + #address-cells = <1>; + #size-cells = <0>; + + humidity@28 { + compatible = "amphenol,cc2d23s", "amphenol,cc2d23"; + reg = <0x28>; + interrupt-parent = <&gpio>; + interrupts = <4 IRQ_TYPE_EDGE_RISING>, + <5 IRQ_TYPE_EDGE_RISING>, + <6 IRQ_TYPE_EDGE_RISING>; + interrupt-names = "ready", "low", "high"; + vdd-supply = <®_vdd>; + }; + }; diff --git a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml index 378d1f6aeeb3f5..a099bb71415e01 100644 --- a/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml +++ b/Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml @@ -28,10 +28,17 @@ properties: - ti,ina231 - ti,ina237 - ti,ina238 + - ti,ina260 reg: maxItems: 1 + "#io-channel-cells": + const: 1 + + label: + description: A descriptive name for this device. + shunt-resistor: description: Shunt resistor value in micro-Ohm. @@ -77,6 +84,8 @@ examples: power-sensor@44 { compatible = "ti,ina220"; reg = <0x44>; + #io-channel-cells = <1>; + label = "vdd_3v0"; shunt-resistor = <1000>; vs-supply = <&vdd_3v0>; }; diff --git a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml index 2c08f2a7cf1ee2..b813f6d4810c9a 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-demux-pinctrl.yaml @@ -32,7 +32,6 @@ description: | +-------------------------------+ allOf: - - $ref: i2c-mux.yaml - $ref: /schemas/i2c/i2c-controller.yaml# properties: @@ -41,6 +40,8 @@ properties: i2c-parent: $ref: /schemas/types.yaml#/definitions/phandle-array + items: + maxItems: 1 description: List of phandles of I2C masters available for selection. The first one will be used as default. diff --git a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml index df9c57bca2a89c..cc8bba5537b94b 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-exynos5.yaml @@ -33,6 +33,7 @@ properties: - const: samsung,exynos7-hsi2c - items: - enum: + - google,gs101-hsi2c - samsung,exynos850-hsi2c - const: samsung,exynosautov9-hsi2c - const: samsung,exynos5-hsi2c # Exynos5250 and Exynos5420 diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml index 2d7bb998b0e9d2..9aa0585200c9cd 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-pca954x.yaml @@ -71,6 +71,23 @@ properties: description: A voltage regulator supplying power to the chip. On PCA9846 the regulator supplies power to VDD2 (core logic) and optionally to VDD1. + maxim,isolate-stuck-channel: + type: boolean + description: Allows to use non faulty channels while a stuck channel is + isolated from the upstream bus. If not set all channels are isolated from + the upstream bus until the fault is cleared. + + maxim,send-flush-out-sequence: + type: boolean + description: Send a flush-out sequence to stuck auxiliary buses + automatically after a stuck channel is being detected. + + maxim,preconnection-wiggle-test-enable: + type: boolean + description: Send a STOP condition to the auxiliary buses when the switch + register activates a channel to detect a stuck high fault. On fault the + channel is isolated from the upstream bus. + required: - compatible - reg @@ -95,6 +112,19 @@ allOf: "#interrupt-cells": false interrupt-controller: false + - if: + not: + properties: + compatible: + contains: + enum: + - maxim,max7357 + then: + properties: + maxim,isolate-stuck-channel: false + maxim,send-flush-out-sequence: false + maxim,preconnection-wiggle-test-enable: false + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml index 31386a8d768454..e89ee361741e8f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml +++ b/Documentation/devicetree/bindings/i2c/i2c-pxa.yaml @@ -7,7 +7,7 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Marvell MMP I2C controller maintainers: - - Rob Herring + - Rob Herring allOf: - $ref: /schemas/i2c/i2c-controller.yaml# diff --git a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml index c4ace5585e1e22..51b220da461b06 100644 --- a/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml +++ b/Documentation/devicetree/bindings/i2c/renesas,rcar-i2c.yaml @@ -53,6 +53,7 @@ properties: - renesas,i2c-r8a779a0 # R-Car V3U - renesas,i2c-r8a779f0 # R-Car S4-8 - renesas,i2c-r8a779g0 # R-Car V4H + - renesas,i2c-r8a779h0 # R-Car V4M - const: renesas,rcar-gen4-i2c # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml b/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml index fcc3dbff9c9a55..47be5d9a32d425 100644 --- a/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml +++ b/Documentation/devicetree/bindings/i3c/aspeed,ast2600-i3c.yaml @@ -57,7 +57,7 @@ examples: - | #include - i3c-master@2000 { + i3c@2000 { compatible = "aspeed,ast2600-i3c"; reg = <0x2000 0x1000>; #address-cells = <3>; diff --git a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml index cc40d25358ecfb..cad6d53d0e2e35 100644 --- a/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml +++ b/Documentation/devicetree/bindings/i3c/cdns,i3c-master.yaml @@ -41,7 +41,7 @@ unevaluatedProperties: false examples: - | - i3c-master@d040000 { + i3c@d040000 { compatible = "cdns,i3c-master"; clocks = <&coreclock>, <&i3csysclock>; clock-names = "pclk", "sysclk"; diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml index c816e295d5651f..c7900a1da8d932 100644 --- a/Documentation/devicetree/bindings/i3c/i3c.yaml +++ b/Documentation/devicetree/bindings/i3c/i3c.yaml @@ -17,7 +17,7 @@ description: | properties: $nodename: - pattern: "^i3c-master@[0-9a-f]+$" + pattern: "^i3c@[0-9a-f]+$" "#address-cells": const: 3 @@ -153,7 +153,7 @@ additionalProperties: true examples: - | - i3c-master@d040000 { + i3c@d040000 { compatible = "cdns,i3c-master"; clocks = <&coreclock>, <&i3csysclock>; clock-names = "pclk", "sysclk"; diff --git a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml index 5dda8cb44cdbc0..39bb1a1784c9bc 100644 --- a/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml +++ b/Documentation/devicetree/bindings/i3c/mipi-i3c-hci.yaml @@ -43,7 +43,7 @@ unevaluatedProperties: false examples: - | - i3c-master@a0000000 { + i3c@a0000000 { compatible = "mipi-i3c-hci"; reg = <0xa0000000 0x2000>; interrupts = <89>; diff --git a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml index 133855f11b4f5d..c56ff77677f170 100644 --- a/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml +++ b/Documentation/devicetree/bindings/i3c/silvaco,i3c-master.yaml @@ -48,7 +48,7 @@ unevaluatedProperties: false examples: - | - i3c-master@a0000000 { + i3c@a0000000 { compatible = "silvaco,i3c-master-v1"; clocks = <&zynqmp_clk 71>, <&fclk>, <&sclk>; clock-names = "pclk", "fast_clk", "slow_clk"; diff --git a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml index 7a76fd32962ac7..c0e805e531be23 100644 --- a/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml +++ b/Documentation/devicetree/bindings/i3c/snps,dw-i3c-master.yaml @@ -35,7 +35,7 @@ unevaluatedProperties: false examples: - | - i3c-master@2000 { + i3c@2000 { compatible = "snps,dw-i3c-master-1.00a"; #address-cells = <3>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml index 7aa748d6b7a027..eecd5fbab69581 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,ad9467.yaml @@ -44,6 +44,9 @@ properties: Pin that controls the powerdown mode of the device. maxItems: 1 + io-backends: + maxItems: 1 + reset-gpios: description: Reset pin for the device. @@ -68,6 +71,7 @@ examples: reg = <0>; clocks = <&adc_clk>; clock-names = "adc-clk"; + io-backends = <&iio_backend>; }; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml index 9996dd93f84b29..3d49d21ad33df2 100644 --- a/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml +++ b/Documentation/devicetree/bindings/iio/adc/adi,axi-adc.yaml @@ -39,12 +39,15 @@ properties: $ref: /schemas/types.yaml#/definitions/phandle description: A reference to a the actual ADC to which this FPGA ADC interfaces to. + deprecated: true + + '#io-backend-cells': + const: 0 required: - compatible - dmas - reg - - adi,adc-dev additionalProperties: false @@ -55,7 +58,6 @@ examples: reg = <0x44a00000 0x10000>; dmas = <&rx_dma 0>; dma-names = "rx"; - - adi,adc-dev = <&spi_adc>; + #io-backend-cells = <0>; }; ... diff --git a/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml b/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml index 88e008629ea89a..af2c3a67f8880e 100644 --- a/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml +++ b/Documentation/devicetree/bindings/iio/adc/richtek,rtq6056.yaml @@ -25,7 +25,14 @@ description: | properties: compatible: - const: richtek,rtq6056 + oneOf: + - enum: + - richtek,rtq6056 + - richtek,rtq6059 + - items: + - enum: + - richtek,rtq6053 + - const: richtek,rtq6056 reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml b/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml new file mode 100644 index 00000000000000..bf5a43a81d59c0 --- /dev/null +++ b/Documentation/devicetree/bindings/iio/adc/ti,ads1298.yaml @@ -0,0 +1,80 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/adc/ti,ads1298.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Texas Instruments' ads1298 medical ADC chips + +description: | + Datasheet at: https://www.ti.com/product/ADS1298 + Bindings for this chip aren't complete. + +maintainers: + - Mike Looijmans + +properties: + compatible: + enum: + - ti,ads1298 + + reg: + maxItems: 1 + + spi-cpha: true + + reset-gpios: + maxItems: 1 + + avdd-supply: + description: + Analog power supply, voltage between AVDD and AVSS. When providing a + symmetric +/- 2.5V, the regulator should report 5V. + + vref-supply: + description: + Optional reference voltage. If omitted, internal reference is used, + which is 2.4V when analog supply is below 4.4V, 4V otherwise. + + clocks: + description: Optional 2.048 MHz external source clock on CLK pin + maxItems: 1 + + interrupts: + description: Interrupt on DRDY pin, triggers on falling edge + maxItems: 1 + + label: true + +required: + - compatible + - reg + - avdd-supply + - interrupts + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +unevaluatedProperties: false + +examples: + - | + #include + #include + spi { + #address-cells = <1>; + #size-cells = <0>; + + adc@1 { + reg = <1>; + compatible = "ti,ads1298"; + label = "ads1298-1-ecg"; + avdd-supply = <®_iso_5v_a>; + clocks = <&clk_ads1298>; + interrupt-parent = <&gpio0>; + interrupts = <78 IRQ_TYPE_EDGE_FALLING>; + spi-max-frequency = <20000000>; + spi-cpha; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml b/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml index dddf97b50549f0..4151f99b42aa79 100644 --- a/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml +++ b/Documentation/devicetree/bindings/iio/afe/voltage-divider.yaml @@ -39,6 +39,17 @@ properties: description: | Channel node of a voltage io-channel. + '#io-channel-cells': + description: + In addition to consuming the measurement services of a voltage + output channel, the voltage divider can act as a provider of + measurement services to other devices. This is particularly + useful in scenarios wherein an ADC has an analog frontend, + such as a voltage divider, and then consuming its raw value + isn't interesting. In this case, the voltage before the divider + is desired. + const: 1 + output-ohms: description: Resistance Rout over which the output voltage is measured. See full-ohms. diff --git a/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml b/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml new file mode 100644 index 00000000000000..2bcf4bbc12e41f --- /dev/null +++ b/Documentation/devicetree/bindings/iio/frequency/adi,admfm2000.yaml @@ -0,0 +1,127 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright 2024 Analog Devices Inc. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/iio/frequency/adi,admfm2000.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ADMFM2000 Dual Microwave Down Converter + +maintainers: + - Kim Seer Paller + +description: + Dual microwave down converter module with input RF and LO frequency ranges + from 0.5 to 32 GHz and an output IF frequency range from 0.1 to 8 GHz. + It consists of a LNA, mixer, IF filter, DSA, and IF amplifier for each down + conversion path. + +properties: + compatible: + enum: + - adi,admfm2000 + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + "^channel@[0-1]$": + type: object + description: Represents a channel of the device. + + additionalProperties: false + + properties: + reg: + description: + The channel number. + minimum: 0 + maximum: 1 + + adi,mixer-mode: + description: + Enable mixer mode for the channel. It downconverts RF between 5 GHz + and 32 GHz to IF between 0.5 GHz and 8 GHz. If not present, the channel + is in direct IF mode which bypasses the mixer and downconverts RF + between 2 GHz and 8 GHz to IF between 0.5 GHz and 8 GHz. + type: boolean + + switch-gpios: + description: | + GPIOs to select the RF path for the channel. The same state of CTRL-A + and CTRL-B GPIOs is not permitted. + CTRL-A CTRL-B CH1 Status CH2 Status + 1 0 Direct IF mode Mixer mode + 0 1 Mixer mode Direct IF mode + + items: + - description: CTRL-A GPIO + - description: CTRL-B GPIO + + attenuation-gpios: + description: | + Choice of attenuation: + DSA-V4 DSA-V3 DSA-V2 DSA-V1 DSA-V0 + 1 1 1 1 1 0 dB + 1 1 1 1 0 -1 dB + 1 1 1 0 1 -2 dB + 1 1 0 1 1 -4 dB + 1 0 1 1 1 -8 dB + 0 1 1 1 1 -16 dB + 0 0 0 0 0 -31 dB + + items: + - description: DSA-V0 GPIO + - description: DSA-V1 GPIO + - description: DSA-V2 GPIO + - description: DSA-V3 GPIO + - description: DSA-V4 GPIO + + required: + - reg + - switch-gpios + - attenuation-gpios + +required: + - compatible + +additionalProperties: false + +examples: + - | + #include + converter { + compatible = "adi,admfm2000"; + + #address-cells = <1>; + #size-cells = <0>; + + channel@0 { + reg = <0>; + switch-gpios = <&gpio 1 GPIO_ACTIVE_LOW>, + <&gpio 2 GPIO_ACTIVE_HIGH>; + + attenuation-gpios = <&gpio 17 GPIO_ACTIVE_LOW>, + <&gpio 22 GPIO_ACTIVE_LOW>, + <&gpio 23 GPIO_ACTIVE_LOW>, + <&gpio 24 GPIO_ACTIVE_LOW>, + <&gpio 25 GPIO_ACTIVE_LOW>; + }; + + channel@1 { + reg = <1>; + adi,mixer-mode; + switch-gpios = <&gpio 3 GPIO_ACTIVE_LOW>, + <&gpio 4 GPIO_ACTIVE_HIGH>; + + attenuation-gpios = <&gpio 0 GPIO_ACTIVE_LOW>, + <&gpio 5 GPIO_ACTIVE_LOW>, + <&gpio 6 GPIO_ACTIVE_LOW>, + <&gpio 16 GPIO_ACTIVE_LOW>, + <&gpio 26 GPIO_ACTIVE_LOW>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml b/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml index 7f6d0f9edc75e3..8b5dedd1a598cf 100644 --- a/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml +++ b/Documentation/devicetree/bindings/iio/humidity/ti,hdc3020.yaml @@ -43,6 +43,7 @@ additionalProperties: false examples: - | + #include i2c { #address-cells = <1>; #size-cells = <0>; @@ -51,5 +52,7 @@ examples: compatible = "ti,hdc3021", "ti,hdc3020"; reg = <0x47>; vdd-supply = <&vcc_3v3>; + interrupt-parent = <&gpio3>; + interrupts = <23 IRQ_TYPE_EDGE_RISING>; }; }; diff --git a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml index 28b667a9cb76b6..c48a96d17f511f 100644 --- a/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml +++ b/Documentation/devicetree/bindings/iio/imu/st,lsm6dsx.yaml @@ -35,7 +35,9 @@ properties: - st,lsm6dsv - st,lsm6dso16is - items: - - const: st,asm330lhhx + - enum: + - st,asm330lhhx + - st,asm330lhhxg1 - const: st,lsm6dsr - items: - const: st,lsm6dstx diff --git a/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml b/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml index 0e8cd02759b368..062a038aa0ff52 100644 --- a/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml +++ b/Documentation/devicetree/bindings/iio/light/ams,as73211.yaml @@ -4,19 +4,22 @@ $id: http://devicetree.org/schemas/iio/light/ams,as73211.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: AMS AS73211 JENCOLOR(R) Digital XYZ Sensor +title: AMS AS73211 JENCOLOR(R) Digital XYZ Sensor and AMS AS7331 UV Sensor maintainers: - Christian Eggers description: | - XYZ True Color Sensor with I2C Interface + AMS AS73211 XYZ True Color Sensor with I2C Interface https://ams.com/documents/20143/36005/AS73211_DS000556_3-01.pdf/a65474c0-b302-c2fd-e30a-c98df87616df + AMS AS7331 UVA, UVB and UVC Sensor with I2C Interface + https://ams.com/documents/20143/9106314/AS7331_DS001047_4-00.pdf properties: compatible: enum: - ams,as73211 + - ams,as7331 reg: description: diff --git a/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml b/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml index 65a24ed67b3ccd..89977b9f01cfe1 100644 --- a/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/honeywell,hsc030pa.yaml @@ -99,6 +99,9 @@ required: - honeywell,transfer-function - honeywell,pressure-triplet +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml + additionalProperties: false dependentSchemas: diff --git a/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml index d9e903fbfd99ea..6994b30015bdb6 100644 --- a/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml +++ b/Documentation/devicetree/bindings/iio/pressure/honeywell,mprls0025pa.yaml @@ -8,25 +8,28 @@ title: Honeywell mprls0025pa pressure sensor maintainers: - Andreas Klinger + - Petre Rodan description: | Honeywell pressure sensor of model mprls0025pa. - This sensor has an I2C and SPI interface. Only the I2C interface is - implemented. + This sensor has an I2C and SPI interface. There are many models with different pressure ranges available. The vendor calls them "mpr series". All of them have the identical programming model and differ in the pressure range, unit and transfer function. - To support different models one need to specify the pressure range as well as - the transfer function. Pressure range needs to be converted from its unit to - pascal. + To support different models one need to specify its pressure triplet as well + as the transfer function. + + For custom silicon chips not covered by the Honeywell MPR series datasheet, + the pressure values can be specified manually via honeywell,pmin-pascal and + honeywell,pmax-pascal. + The minimal range value stands for the minimum pressure and the maximum value + also for the maximum pressure with linear relation inside the range. The transfer function defines the ranges of numerical values delivered by the - sensor. The minimal range value stands for the minimum pressure and the - maximum value also for the maximum pressure with linear relation inside the - range. + sensor. Specifications about the devices can be found at: https://prod-edam.honeywell.com/content/dam/honeywell-edam/sps/siot/en-us/ @@ -42,6 +45,10 @@ properties: maxItems: 1 interrupts: + description: + Optional interrupt for indicating End-of-conversion. + If not present, the driver loops for a while until the received status + byte indicates correct measurement. maxItems: 1 reset-gpios: @@ -50,14 +57,6 @@ properties: If not present the device is not reset during the probe. maxItems: 1 - honeywell,pmin-pascal: - description: - Minimum pressure value the sensor can measure in pascal. - - honeywell,pmax-pascal: - description: - Maximum pressure value the sensor can measure in pascal. - honeywell,transfer-function: description: | Transfer function which defines the range of valid values delivered by the @@ -65,19 +64,57 @@ properties: 1 - A, 10% to 90% of 2^24 (1677722 .. 15099494) 2 - B, 2.5% to 22.5% of 2^24 (419430 .. 3774874) 3 - C, 20% to 80% of 2^24 (3355443 .. 13421773) + enum: [1, 2, 3] $ref: /schemas/types.yaml#/definitions/uint32 + honeywell,pressure-triplet: + description: | + Case-sensitive five character string that defines pressure range, unit + and type as part of the device nomenclature. In the unlikely case of a + custom chip, unset and provide pmin-pascal and pmax-pascal instead. + enum: [0001BA, 01.6BA, 02.5BA, 0060MG, 0100MG, 0160MG, 0250MG, 0400MG, + 0600MG, 0001BG, 01.6BG, 02.5BG, 0100KA, 0160KA, 0250KA, 0006KG, + 0010KG, 0016KG, 0025KG, 0040KG, 0060KG, 0100KG, 0160KG, 0250KG, + 0015PA, 0025PA, 0030PA, 0001PG, 0005PG, 0015PG, 0030PG, 0300YG] + $ref: /schemas/types.yaml#/definitions/string + + honeywell,pmin-pascal: + description: + Minimum pressure value the sensor can measure in pascal. + + honeywell,pmax-pascal: + description: + Maximum pressure value the sensor can measure in pascal. + + spi-max-frequency: + maximum: 800000 + vdd-supply: description: provide VDD power to the sensor. required: - compatible - reg - - honeywell,pmin-pascal - - honeywell,pmax-pascal - honeywell,transfer-function - vdd-supply +oneOf: + - required: + - honeywell,pressure-triplet + - required: + - honeywell,pmin-pascal + - honeywell,pmax-pascal + +allOf: + - $ref: /schemas/spi/spi-peripheral-props.yaml + - if: + required: + - honeywell,pressure-triplet + then: + properties: + honeywell,pmin-pascal: false + honeywell,pmax-pascal: false + additionalProperties: false examples: @@ -93,10 +130,29 @@ examples: reg = <0x18>; reset-gpios = <&gpio3 19 GPIO_ACTIVE_HIGH>; interrupt-parent = <&gpio3>; - interrupts = <21 IRQ_TYPE_EDGE_FALLING>; - honeywell,pmin-pascal = <0>; - honeywell,pmax-pascal = <172369>; + interrupts = <21 IRQ_TYPE_EDGE_RISING>; + + honeywell,pressure-triplet = "0025PA"; + honeywell,transfer-function = <1>; + vdd-supply = <&vcc_3v3>; + }; + }; + - | + spi { + #address-cells = <1>; + #size-cells = <0>; + + pressure@0 { + compatible = "honeywell,mprls0025pa"; + reg = <0>; + spi-max-frequency = <800000>; + reset-gpios = <&gpio1 28 GPIO_ACTIVE_HIGH>; + interrupt-parent = <&gpio0>; + interrupts = <30 IRQ_TYPE_EDGE_RISING>; + + honeywell,pressure-triplet = "0015PA"; honeywell,transfer-function = <1>; vdd-supply = <&vcc_3v3>; }; }; +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml new file mode 100644 index 00000000000000..d90f045ac06c89 --- /dev/null +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix,gt9916.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/input/touchscreen/goodix,gt9916.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Goodix Berlin series touchscreen controller + +description: The Goodix Berlin series of touchscreen controllers + be connected to either I2C or SPI buses. + +maintainers: + - Neil Armstrong + +allOf: + - $ref: touchscreen.yaml# + - $ref: /schemas/spi/spi-peripheral-props.yaml# + +properties: + compatible: + enum: + - goodix,gt9916 + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + reset-gpios: + maxItems: 1 + + avdd-supply: + description: Analog power supply regulator on AVDD pin + + vddio-supply: + description: power supply regulator on VDDIO pin + + spi-max-frequency: true + touchscreen-inverted-x: true + touchscreen-inverted-y: true + touchscreen-size-x: true + touchscreen-size-y: true + touchscreen-swapped-x-y: true + +additionalProperties: false + +required: + - compatible + - reg + - interrupts + - avdd-supply + - touchscreen-size-x + - touchscreen-size-y + +examples: + - | + #include + #include + i2c { + #address-cells = <1>; + #size-cells = <0>; + touchscreen@5d { + compatible = "goodix,gt9916"; + reg = <0x5d>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>; + avdd-supply = <&ts_avdd>; + touchscreen-size-x = <1024>; + touchscreen-size-y = <768>; + }; + }; + - | + #include + #include + spi { + #address-cells = <1>; + #size-cells = <0>; + num-cs = <1>; + cs-gpios = <&gpio 2 GPIO_ACTIVE_HIGH>; + touchscreen@0 { + compatible = "goodix,gt9916"; + reg = <0>; + interrupt-parent = <&gpio>; + interrupts = <25 IRQ_TYPE_LEVEL_LOW>; + reset-gpios = <&gpio1 1 GPIO_ACTIVE_LOW>; + avdd-supply = <&ts_avdd>; + spi-max-frequency = <1000000>; + touchscreen-size-x = <1024>; + touchscreen-size-y = <768>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml index 3d016b87c8df86..2a2d86cfd10487 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/goodix.yaml @@ -37,8 +37,9 @@ properties: maxItems: 1 irq-gpios: - description: GPIO pin used for IRQ. The driver uses the interrupt gpio pin - as output to reset the device. + description: GPIO pin used for IRQ input. Additionally, this line is + sampled by the device on reset deassertion to select the I2C client + address, thus it can be driven by the host during the reset sequence. maxItems: 1 reset-gpios: diff --git a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml index 07f9dd6b1c9c44..90ebd4f8354c27 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/melfas,mms114.yaml @@ -17,13 +17,17 @@ properties: pattern: "^touchscreen(@.*)?$" compatible: - items: + oneOf: - enum: - melfas,mms114 - melfas,mms134s - melfas,mms136 - melfas,mms152 - melfas,mms345l + - items: + - enum: + - melfas,mms252 + - const: melfas,mms114 reg: description: I2C address diff --git a/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml b/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml index 95b554be25b407..5381a96f494998 100644 --- a/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml +++ b/Documentation/devicetree/bindings/input/touchscreen/silead,gsl1680.yaml @@ -31,7 +31,7 @@ properties: maxItems: 1 firmware-name: - $ref: /schemas/types.yaml#/definitions/string + maxItems: 1 description: > File basename for board specific firmware diff --git a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml index 08c1c6b9d7cf8d..5aaa92a7cef7c2 100644 --- a/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml +++ b/Documentation/devicetree/bindings/interconnect/qcom,rpm.yaml @@ -23,6 +23,9 @@ properties: compatible: enum: + - qcom,msm8909-bimc + - qcom,msm8909-pcnoc + - qcom,msm8909-snoc - qcom,msm8916-bimc - qcom,msm8916-pcnoc - qcom,msm8916-snoc diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml new file mode 100644 index 00000000000000..e1a379c052e44c --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/mediatek,mt6577-sysirq.yaml @@ -0,0 +1,85 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/interrupt-controller/mediatek,mt6577-sysirq.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MediaTek sysirq + +description: + MediaTek SOCs sysirq support controllable irq inverter for each GIC SPI + interrupt. + +maintainers: + - Matthias Brugger + +properties: + compatible: + oneOf: + - const: mediatek,mt6577-sysirq + - items: + - enum: + - mediatek,mt2701-sysirq + - mediatek,mt2712-sysirq + - mediatek,mt6580-sysirq + - mediatek,mt6582-sysirq + - mediatek,mt6589-sysirq + - mediatek,mt6592-sysirq + - mediatek,mt6755-sysirq + - mediatek,mt6765-sysirq + - mediatek,mt6779-sysirq + - mediatek,mt6795-sysirq + - mediatek,mt6797-sysirq + - mediatek,mt7622-sysirq + - mediatek,mt7623-sysirq + - mediatek,mt7629-sysirq + - mediatek,mt8127-sysirq + - mediatek,mt8135-sysirq + - mediatek,mt8173-sysirq + - mediatek,mt8183-sysirq + - mediatek,mt8365-sysirq + - mediatek,mt8516-sysirq + - const: mediatek,mt6577-sysirq + + reg: + minItems: 1 + maxItems: 2 + + interrupt-controller: true + + "#interrupt-cells": + $ref: "arm,gic.yaml#/properties/#interrupt-cells" + +required: + - reg + - interrupt-controller + - "#interrupt-cells" + +allOf: + - $ref: /schemas/interrupt-controller.yaml# + - if: + properties: + compatible: + contains: + const: mediatek,mt6797-sysirq + then: + properties: + reg: + minItems: 2 + else: + properties: + reg: + maxItems: 1 + +unevaluatedProperties: false + +examples: + - | + interrupt-controller@10200620 { + compatible = "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq"; + reg = <0x10220620 0x20>, + <0x10220690 0x10>; + interrupt-parent = <&gic>; + interrupt-controller; + #interrupt-cells = <3>; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt b/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt deleted file mode 100644 index 3ffc60184e445d..00000000000000 --- a/Documentation/devicetree/bindings/interrupt-controller/mediatek,sysirq.txt +++ /dev/null @@ -1,44 +0,0 @@ -MediaTek sysirq - -MediaTek SOCs sysirq support controllable irq inverter for each GIC SPI -interrupt. - -Required properties: -- compatible: should be - "mediatek,mt8516-sysirq", "mediatek,mt6577-sysirq": for MT8516 - "mediatek,mt8183-sysirq", "mediatek,mt6577-sysirq": for MT8183 - "mediatek,mt8173-sysirq", "mediatek,mt6577-sysirq": for MT8173 - "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,mt7629-sysirq", "mediatek,mt6577-sysirq": for MT7629 - "mediatek,mt6795-sysirq", "mediatek,mt6577-sysirq": for MT6795 - "mediatek,mt6797-sysirq", "mediatek,mt6577-sysirq": for MT6797 - "mediatek,mt6779-sysirq", "mediatek,mt6577-sysirq": for MT6779 - "mediatek,mt6765-sysirq", "mediatek,mt6577-sysirq": for MT6765 - "mediatek,mt6755-sysirq", "mediatek,mt6577-sysirq": for MT6755 - "mediatek,mt6592-sysirq", "mediatek,mt6577-sysirq": for MT6592 - "mediatek,mt6589-sysirq", "mediatek,mt6577-sysirq": for MT6589 - "mediatek,mt6582-sysirq", "mediatek,mt6577-sysirq": for MT6582 - "mediatek,mt6580-sysirq", "mediatek,mt6577-sysirq": for MT6580 - "mediatek,mt6577-sysirq": for MT6577 - "mediatek,mt2712-sysirq", "mediatek,mt6577-sysirq": for MT2712 - "mediatek,mt2701-sysirq", "mediatek,mt6577-sysirq": for MT2701 - "mediatek,mt8365-sysirq", "mediatek,mt6577-sysirq": for MT8365 -- interrupt-controller : Identifies the node as an interrupt controller -- #interrupt-cells : Use the same format as specified by GIC in arm,gic.txt. -- reg: Physical base address of the intpol registers and length of memory - mapped region. Could be multiple bases here. Ex: mt6797 needs 2 reg, others - need 1. - -Example: - sysirq: intpol-controller@10200620 { - compatible = "mediatek,mt6797-sysirq", - "mediatek,mt6577-sysirq"; - interrupt-controller; - #interrupt-cells = <3>; - interrupt-parent = <&gic>; - reg = <0 0x10220620 0 0x20>, - <0 0x10220690 0 0x10>; - }; diff --git a/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml new file mode 100644 index 00000000000000..b005065e0f48a7 --- /dev/null +++ b/Documentation/devicetree/bindings/leds/backlight/kinetic,ktd2801.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/leds/backlight/kinetic,ktd2801.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Kinetic Technologies KTD2801 one-wire backlight + +maintainers: + - Duje Mihanović + +description: | + The Kinetic Technologies KTD2801 is a LED backlight driver controlled + by a single GPIO line. The driver can be controlled with a PWM signal + or by pulsing the GPIO line to set the backlight level. This is called + "ExpressWire". + +allOf: + - $ref: common.yaml# + +properties: + compatible: + const: kinetic,ktd2801 + + ctrl-gpios: + maxItems: 1 + + default-brightness: true + max-brightness: true + +required: + - compatible + - ctrl-gpios + +additionalProperties: false + +examples: + - | + #include + + backlight { + compatible = "kinetic,ktd2801"; + ctrl-gpios = <&gpio 97 GPIO_ACTIVE_HIGH>; + max-brightness = <210>; + default-brightness = <100>; + }; diff --git a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml index 5f1849bdabba2f..a8490781011d1b 100644 --- a/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml +++ b/Documentation/devicetree/bindings/leds/backlight/qcom-wled.yaml @@ -7,8 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Qualcomm Technologies, Inc. WLED driver maintainers: - - Bjorn Andersson - - Kiran Gunda + - Bjorn Andersson + - Kiran Gunda description: | WLED (White Light Emitting Diode) driver is used for controlling display diff --git a/Documentation/devicetree/bindings/leds/common.yaml b/Documentation/devicetree/bindings/leds/common.yaml index 55a8d1385e2104..8a3c2398b10ce0 100644 --- a/Documentation/devicetree/bindings/leds/common.yaml +++ b/Documentation/devicetree/bindings/leds/common.yaml @@ -200,6 +200,18 @@ properties: #trigger-source-cells property in the source node. $ref: /schemas/types.yaml#/definitions/phandle-array + active-low: + type: boolean + description: + Makes LED active low. To turn the LED ON, line needs to be + set to low voltage instead of high. + + inactive-high-impedance: + type: boolean + description: + Set LED to high-impedance mode to turn the LED OFF. LED might also + describe this mode as tristate. + # Required properties for flash LED child nodes: flash-max-microamp: description: diff --git a/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml b/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml index 52252fb6bb321d..bb20394fca5c38 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml +++ b/Documentation/devicetree/bindings/leds/leds-bcm63138.yaml @@ -52,10 +52,6 @@ patternProperties: maxItems: 1 description: LED pin number - active-low: - type: boolean - description: Makes LED active low - required: - reg diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml index 51cc0d82c12eb8..f3a3ef99292995 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml +++ b/Documentation/devicetree/bindings/leds/leds-bcm6328.yaml @@ -78,10 +78,6 @@ patternProperties: - maximum: 23 description: LED pin number (only LEDs 0 to 23 are valid). - active-low: - type: boolean - description: Makes LED active low. - brcm,hardware-controlled: type: boolean description: Makes this LED hardware controlled. diff --git a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt index 6e51c6b91ee54c..211ffc3c4a2012 100644 --- a/Documentation/devicetree/bindings/leds/leds-bcm6358.txt +++ b/Documentation/devicetree/bindings/leds/leds-bcm6358.txt @@ -25,8 +25,6 @@ LED sub-node required properties: LED sub-node optional properties: - label : see Documentation/devicetree/bindings/leds/common.txt - - active-low : Boolean, makes LED active low. - Default : false - default-state : see Documentation/devicetree/bindings/leds/common.txt - linux,default-trigger : see diff --git a/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml b/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml index bd6ec04a87277f..5edfbe347341cd 100644 --- a/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml +++ b/Documentation/devicetree/bindings/leds/leds-pwm-multicolor.yaml @@ -41,10 +41,6 @@ properties: pwm-names: true - active-low: - description: For PWMs where the LED is wired to supply rather than ground. - type: boolean - color: true required: diff --git a/Documentation/devicetree/bindings/leds/leds-pwm.yaml b/Documentation/devicetree/bindings/leds/leds-pwm.yaml index 7de6da58be3c53..113b7c218303ad 100644 --- a/Documentation/devicetree/bindings/leds/leds-pwm.yaml +++ b/Documentation/devicetree/bindings/leds/leds-pwm.yaml @@ -34,11 +34,6 @@ patternProperties: Maximum brightness possible for the LED $ref: /schemas/types.yaml#/definitions/uint32 - active-low: - description: - For PWMs where the LED is wired to supply rather than ground. - type: boolean - required: - pwms - max-brightness diff --git a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml index ea84ad426df18e..6649ca2ec80502 100644 --- a/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml +++ b/Documentation/devicetree/bindings/leds/leds-qcom-lpg.yaml @@ -11,7 +11,7 @@ maintainers: description: > The Qualcomm Light Pulse Generator consists of three different hardware blocks; - a ramp generator with lookup table, the light pulse generator and a three + a ramp generator with lookup table (LUT), the light pulse generator and a three channel current sink. These blocks are found in a wide range of Qualcomm PMICs. properties: @@ -63,6 +63,29 @@ properties: - description: dtest line to attach - description: flags for the attachment + nvmem: + description: > + This property is required for PMICs that supports PPG, which is when a + PMIC stores LPG per-channel data and pattern LUT in SDAM modules instead + of in a LUT peripheral. For PMICs, such as PM8350C, per-channel data + and pattern LUT is separated into 2 SDAM modules. In that case, phandles + to both SDAM modules need to be specified. + minItems: 1 + maxItems: 2 + + nvmem-names: + minItems: 1 + items: + - const: lpg_chan_sdam + - const: lut_sdam + + qcom,pbs: + $ref: /schemas/types.yaml#/definitions/phandle + description: > + Phandle of the Qualcomm Programmable Boot Sequencer node (PBS). + PBS node is used to trigger LPG pattern sequences for PMICs that support + single SDAM PPG. + multi-led: type: object $ref: leds-class-multicolor.yaml# @@ -106,6 +129,32 @@ required: additionalProperties: false +allOf: + - if: + properties: + compatible: + contains: + const: qcom,pmi632-lpg + then: + properties: + nvmem: + maxItems: 1 + nvmem-names: + maxItems: 1 + - if: + properties: + compatible: + contains: + enum: + - qcom,pm8350c-pwm + - qcom,pm8550-pwm + then: + properties: + nvmem: + minItems: 2 + nvmem-names: + minItems: 2 + examples: - | #include @@ -191,4 +240,35 @@ examples: compatible = "qcom,pm8916-pwm"; #pwm-cells = <2>; }; + - | + #include + + led-controller { + compatible = "qcom,pmi632-lpg"; + #address-cells = <1>; + #size-cells = <0>; + #pwm-cells = <2>; + nvmem-names = "lpg_chan_sdam"; + nvmem = <&pmi632_sdam_7>; + qcom,pbs = <&pmi632_pbs_client3>; + + led@1 { + reg = <1>; + color = ; + label = "red"; + }; + + led@2 { + reg = <2>; + color = ; + label = "green"; + }; + + led@3 { + reg = <3>; + color = ; + label = "blue"; + }; + }; + ... diff --git a/Documentation/devicetree/bindings/media/cnm,wave521c.yaml b/Documentation/devicetree/bindings/media/cnm,wave521c.yaml index 6d5569e77b7a12..6a11c1d11fb5f9 100644 --- a/Documentation/devicetree/bindings/media/cnm,wave521c.yaml +++ b/Documentation/devicetree/bindings/media/cnm,wave521c.yaml @@ -17,7 +17,7 @@ properties: compatible: items: - enum: - - ti,k3-j721s2-wave521c + - ti,j721s2-wave521c - const: cnm,wave521c reg: @@ -53,7 +53,7 @@ additionalProperties: false examples: - | vpu: video-codec@12345678 { - compatible = "ti,k3-j721s2-wave521c", "cnm,wave521c"; + compatible = "ti,j721s2-wave521c", "cnm,wave521c"; reg = <0x12345678 0x1000>; clocks = <&clks 42>; interrupts = <42>; diff --git a/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml b/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml index e37317f810722d..c9673391afdbde 100644 --- a/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml +++ b/Documentation/devicetree/bindings/media/i2c/techwell,tw9900.yaml @@ -36,7 +36,7 @@ properties: properties: port@0: - $ref: /schemas/graph.yaml#/$defs/port-base + $ref: /schemas/graph.yaml#/properties/port description: Analog input port properties: diff --git a/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml index a2051b31fa29d3..b45743d0a9ec09 100644 --- a/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek,vcodec-encoder.yaml @@ -16,14 +16,18 @@ description: |+ properties: compatible: - enum: - - mediatek,mt8173-vcodec-enc-vp8 - - mediatek,mt8173-vcodec-enc - - mediatek,mt8183-vcodec-enc - - mediatek,mt8188-vcodec-enc - - mediatek,mt8192-vcodec-enc - - mediatek,mt8195-vcodec-enc - + oneOf: + - items: + - enum: + - mediatek,mt8173-vcodec-enc-vp8 + - mediatek,mt8173-vcodec-enc + - mediatek,mt8183-vcodec-enc + - mediatek,mt8188-vcodec-enc + - mediatek,mt8192-vcodec-enc + - mediatek,mt8195-vcodec-enc + - items: + - const: mediatek,mt8186-vcodec-enc + - const: mediatek,mt8183-vcodec-enc reg: maxItems: 1 @@ -109,10 +113,7 @@ allOf: properties: compatible: enum: - - mediatek,mt8173-vcodec-enc - - mediatek,mt8188-vcodec-enc - - mediatek,mt8192-vcodec-enc - - mediatek,mt8195-vcodec-enc + - mediatek,mt8173-vcodec-enc-vp8 then: properties: @@ -122,8 +123,8 @@ allOf: maxItems: 1 clock-names: items: - - const: venc_sel - else: # for vp8 hw encoder + - const: venc_lt_sel + else: properties: clock: items: @@ -131,7 +132,7 @@ allOf: maxItems: 1 clock-names: items: - - const: venc_lt_sel + - const: venc_sel additionalProperties: false diff --git a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml index 37800e1908cc93..83c020a673d6e6 100644 --- a/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml +++ b/Documentation/devicetree/bindings/media/mediatek-jpeg-encoder.yaml @@ -38,7 +38,8 @@ properties: maxItems: 1 iommus: - maxItems: 2 + minItems: 2 + maxItems: 4 description: | Points to the respective IOMMU block with master port as argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.yaml for details. diff --git a/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml new file mode 100644 index 00000000000000..b8611bc8756c48 --- /dev/null +++ b/Documentation/devicetree/bindings/media/st,stm32mp25-video-codec.yaml @@ -0,0 +1,49 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/media/st,stm32mp25-video-codec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: STMicroelectronics STM32MP25 VDEC video decoder & VENC video encoder + +maintainers: + - Hugues Fruchet + +description: + The STMicroelectronics STM32MP25 SOCs embeds a VDEC video hardware + decoder peripheral based on Verisilicon VC8000NanoD IP (former Hantro G1) + and a VENC video hardware encoder peripheral based on Verisilicon + VC8000NanoE IP (former Hantro H1). + +properties: + compatible: + enum: + - st,stm32mp25-vdec + - st,stm32mp25-venc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - interrupts + - clocks + +additionalProperties: false + +examples: + - | + #include + video-codec@580d0000 { + compatible = "st,stm32mp25-vdec"; + reg = <0x580d0000 0x3c8>; + interrupts = ; + clocks = <&ck_icn_p_vdec>; + }; diff --git a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.yaml b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.yaml index f54e553e6c0e6a..71896cb1069263 100644 --- a/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.yaml +++ b/Documentation/devicetree/bindings/memory-controllers/nvidia,tegra20-emc.yaml @@ -145,7 +145,7 @@ patternProperties: "^emc-table@[0-9]+$": $ref: "#/$defs/emc-table" - "^emc-tables@[a-z0-9-]+$": + "^emc-tables@[a-f0-9-]+$": type: object properties: reg: diff --git a/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml new file mode 100644 index 00000000000000..4aa36903e755bb --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/atmel,hlcdc.yaml @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mfd/atmel,hlcdc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel's HLCD Controller + +maintainers: + - Nicolas Ferre + - Alexandre Belloni + - Claudiu Beznea + +description: + The Atmel HLCDC (HLCD Controller) IP available on Atmel SoCs exposes two + subdevices, a PWM chip and a Display Controller. + +properties: + compatible: + enum: + - atmel,at91sam9n12-hlcdc + - atmel,at91sam9x5-hlcdc + - atmel,sama5d2-hlcdc + - atmel,sama5d3-hlcdc + - atmel,sama5d4-hlcdc + - microchip,sam9x60-hlcdc + - microchip,sam9x75-xlcdc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + clocks: + minItems: 3 + + clock-names: + items: + - const: periph_clk + - const: sys_clk + - const: slow_clk + - const: lvds_pll_clk + minItems: 3 + + display-controller: + $ref: /schemas/display/atmel/atmel,hlcdc-display-controller.yaml + + pwm: + $ref: /schemas/pwm/atmel,hlcdc-pwm.yaml + +required: + - compatible + - reg + - clocks + - clock-names + - interrupts + +additionalProperties: false + +examples: + - | + #include + #include + #include + + lcd_controller: lcd-controller@f0030000 { + compatible = "atmel,sama5d3-hlcdc"; + reg = <0xf0030000 0x2000>; + clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; + clock-names = "periph_clk", "sys_clk", "slow_clk"; + interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>; + + display-controller { + compatible = "atmel,hlcdc-display-controller"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>; + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + #address-cells = <1>; + #size-cells = <0>; + reg = <0>; + + hlcdc_panel_output: endpoint@0 { + reg = <0>; + remote-endpoint = <&panel_input>; + }; + }; + }; + + pwm { + compatible = "atmel,hlcdc-pwm"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_lcd_pwm>; + #pwm-cells = <3>; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt b/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt deleted file mode 100644 index 7de696eefaed4b..00000000000000 --- a/Documentation/devicetree/bindings/mfd/atmel-hlcdc.txt +++ /dev/null @@ -1,56 +0,0 @@ -Device-Tree bindings for Atmel's HLCDC (High LCD Controller) MFD driver - -Required properties: - - compatible: value should be one of the following: - "atmel,at91sam9n12-hlcdc" - "atmel,at91sam9x5-hlcdc" - "atmel,sama5d2-hlcdc" - "atmel,sama5d3-hlcdc" - "atmel,sama5d4-hlcdc" - "microchip,sam9x60-hlcdc" - "microchip,sam9x75-xlcdc" - - reg: base address and size of the HLCDC device registers. - - clock-names: the name of the 3 clocks requested by the HLCDC device. - Should contain "periph_clk", "sys_clk" and "slow_clk". - - clocks: should contain the 3 clocks requested by the HLCDC device. - - interrupts: should contain the description of the HLCDC interrupt line - -The HLCDC IP exposes two subdevices: - - a PWM chip: see ../pwm/atmel-hlcdc-pwm.txt - - a Display Controller: see ../display/atmel/hlcdc-dc.txt - -Example: - - hlcdc: hlcdc@f0030000 { - compatible = "atmel,sama5d3-hlcdc"; - reg = <0xf0030000 0x2000>; - clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; - clock-names = "periph_clk","sys_clk", "slow_clk"; - interrupts = <36 IRQ_TYPE_LEVEL_HIGH 0>; - - hlcdc-display-controller { - compatible = "atmel,hlcdc-display-controller"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_lcd_base &pinctrl_lcd_rgb888>; - #address-cells = <1>; - #size-cells = <0>; - - port@0 { - #address-cells = <1>; - #size-cells = <0>; - reg = <0>; - - hlcdc_panel_output: endpoint@0 { - reg = <0>; - remote-endpoint = <&panel_input>; - }; - }; - }; - - hlcdc_pwm: hlcdc-pwm { - compatible = "atmel,hlcdc-pwm"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_lcd_pwm>; - #pwm-cells = <3>; - }; - }; diff --git a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml index e1ca4f297c6d81..aac8819bd00ba4 100644 --- a/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml +++ b/Documentation/devicetree/bindings/mfd/google,cros-ec.yaml @@ -93,6 +93,11 @@ properties: '#size-cells': const: 0 + '#gpio-cells': + const: 2 + + gpio-controller: true + typec: $ref: /schemas/chrome/google,cros-ec-typec.yaml# @@ -275,6 +280,8 @@ examples: interrupts = <99 0>; interrupt-parent = <&gpio7>; spi-max-frequency = <5000000>; + #gpio-cells = <2>; + gpio-controller; proximity { compatible = "google,cros-ec-mkbp-proximity"; diff --git a/Documentation/devicetree/bindings/mfd/iqs62x.yaml b/Documentation/devicetree/bindings/mfd/iqs62x.yaml index 044cd7542c2bcf..f438c237496639 100644 --- a/Documentation/devicetree/bindings/mfd/iqs62x.yaml +++ b/Documentation/devicetree/bindings/mfd/iqs62x.yaml @@ -31,7 +31,7 @@ properties: maxItems: 1 firmware-name: - $ref: /schemas/types.yaml#/definitions/string + maxItems: 1 description: Specifies the name of the calibration and configuration file selected by the driver. If this property is omitted, the name is chosen based on the diff --git a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml index 798705ab6a4601..b97d77015335f1 100644 --- a/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml +++ b/Documentation/devicetree/bindings/mfd/qcom,tcsr.yaml @@ -19,6 +19,7 @@ properties: - enum: - qcom,msm8976-tcsr - qcom,msm8998-tcsr + - qcom,qcm2290-tcsr - qcom,qcs404-tcsr - qcom,sc7180-tcsr - qcom,sc7280-tcsr @@ -28,6 +29,7 @@ properties: - qcom,sdx55-tcsr - qcom,sdx65-tcsr - qcom,sm4450-tcsr + - qcom,sm6115-tcsr - qcom,sm8150-tcsr - qcom,sm8250-tcsr - qcom,sm8350-tcsr diff --git a/Documentation/devicetree/bindings/mfd/syscon.yaml b/Documentation/devicetree/bindings/mfd/syscon.yaml index 084b5c2a2a3c28..820c364c01f224 100644 --- a/Documentation/devicetree/bindings/mfd/syscon.yaml +++ b/Documentation/devicetree/bindings/mfd/syscon.yaml @@ -73,6 +73,8 @@ properties: - rockchip,rv1126-qos - starfive,jh7100-sysmain - ti,am654-dss-oldi-io-ctrl + - ti,am654-serdes-ctrl + - ti,j784s4-pcie-ctrl - const: syscon diff --git a/Documentation/devicetree/bindings/mips/cpus.yaml b/Documentation/devicetree/bindings/mips/cpus.yaml index cf382dea3922c9..a85137add66894 100644 --- a/Documentation/devicetree/bindings/mips/cpus.yaml +++ b/Documentation/devicetree/bindings/mips/cpus.yaml @@ -23,22 +23,23 @@ properties: - brcm,bmips4380 - brcm,bmips5000 - brcm,bmips5200 - - ingenic,xburst-mxu1.0 + - img,i6500 - ingenic,xburst-fpu1.0-mxu1.1 - ingenic,xburst-fpu2.0-mxu2.0 + - ingenic,xburst-mxu1.0 - ingenic,xburst2-fpu2.1-mxu2.1-smt - loongson,gs264 - mips,m14Kc - - mips,mips4Kc - - mips,mips4KEc - - mips,mips24Kc + - mips,mips1004Kc - mips,mips24KEc + - mips,mips24Kc + - mips,mips4KEc + - mips,mips4Kc - mips,mips74Kc - - mips,mips1004Kc - mti,interaptiv - - mti,mips24KEc - mti,mips14KEc - mti,mips14Kc + - mti,mips24KEc reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mips/mobileye.yaml b/Documentation/devicetree/bindings/mips/mobileye.yaml new file mode 100644 index 00000000000000..831975f6b479f6 --- /dev/null +++ b/Documentation/devicetree/bindings/mips/mobileye.yaml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +# Copyright 2023 Mobileye Vision Technologies Ltd. +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mips/mobileye.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mobileye SoC series + +maintainers: + - Vladimir Kondratiev + - Gregory CLEMENT + - Théo Lebrun + +description: + Boards with a Mobileye SoC shall have the following properties. + +properties: + $nodename: + const: '/' + + compatible: + oneOf: + - description: Boards with Mobileye EyeQ5 SoC + items: + - enum: + - mobileye,eyeq5-epm5 + - const: mobileye,eyeq5 + +additionalProperties: true + +... diff --git a/Documentation/devicetree/bindings/misc/qcom,fastrpc.yaml b/Documentation/devicetree/bindings/misc/qcom,fastrpc.yaml index 2dc3e245fa5d34..c27a8f33d8d769 100644 --- a/Documentation/devicetree/bindings/misc/qcom,fastrpc.yaml +++ b/Documentation/devicetree/bindings/misc/qcom,fastrpc.yaml @@ -77,6 +77,8 @@ patternProperties: reg: maxItems: 1 + dma-coherent: true + iommus: minItems: 1 maxItems: 3 diff --git a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt deleted file mode 100644 index e3289634fa30ea..00000000000000 --- a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt +++ /dev/null @@ -1,58 +0,0 @@ -* Xilinx SDFEC(16nm) IP * - -The Soft Decision Forward Error Correction (SDFEC) Engine is a Hard IP block -which provides high-throughput LDPC and Turbo Code implementations. -The LDPC decode & encode functionality is capable of covering a range of -customer specified Quasi-cyclic (QC) codes. The Turbo decode functionality -principally covers codes used by LTE. The FEC Engine offers significant -power and area savings versus implementations done in the FPGA fabric. - - -Required properties: -- compatible: Must be "xlnx,sd-fec-1.1" -- clock-names : List of input clock names from the following: - - "core_clk", Main processing clock for processing core (required) - - "s_axi_aclk", AXI4-Lite memory-mapped slave interface clock (required) - - "s_axis_din_aclk", DIN AXI4-Stream Slave interface clock (optional) - - "s_axis_din_words-aclk", DIN_WORDS AXI4-Stream Slave interface clock (optional) - - "s_axis_ctrl_aclk", Control input AXI4-Stream Slave interface clock (optional) - - "m_axis_dout_aclk", DOUT AXI4-Stream Master interface clock (optional) - - "m_axis_dout_words_aclk", DOUT_WORDS AXI4-Stream Master interface clock (optional) - - "m_axis_status_aclk", Status output AXI4-Stream Master interface clock (optional) -- clocks : Clock phandles (see clock_bindings.txt for details). -- reg: Should contain Xilinx SDFEC 16nm Hardened IP block registers - location and length. -- xlnx,sdfec-code : Should contain "ldpc" or "turbo" to describe the codes - being used. -- xlnx,sdfec-din-words : A value 0 indicates that the DIN_WORDS interface is - driven with a fixed value and is not present on the device, a value of 1 - configures the DIN_WORDS to be block based, while a value of 2 configures the - DIN_WORDS input to be supplied for each AXI transaction. -- xlnx,sdfec-din-width : Configures the DIN AXI stream where a value of 1 - configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width - of "4x128b". -- xlnx,sdfec-dout-words : A value 0 indicates that the DOUT_WORDS interface is - driven with a fixed value and is not present on the device, a value of 1 - configures the DOUT_WORDS to be block based, while a value of 2 configures the - DOUT_WORDS input to be supplied for each AXI transaction. -- xlnx,sdfec-dout-width : Configures the DOUT AXI stream where a value of 1 - configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width - of "4x128b". -Optional properties: -- interrupts: should contain SDFEC interrupt number - -Example ---------------------------------------- - sd_fec_0: sd-fec@a0040000 { - compatible = "xlnx,sd-fec-1.1"; - clock-names = "core_clk","s_axi_aclk","s_axis_ctrl_aclk","s_axis_din_aclk","m_axis_status_aclk","m_axis_dout_aclk"; - clocks = <&misc_clk_2>,<&misc_clk_0>,<&misc_clk_1>,<&misc_clk_1>,<&misc_clk_1>, <&misc_clk_1>; - reg = <0x0 0xa0040000 0x0 0x40000>; - interrupt-parent = <&axi_intc>; - interrupts = <1 0>; - xlnx,sdfec-code = "ldpc"; - xlnx,sdfec-din-words = <0>; - xlnx,sdfec-din-width = <2>; - xlnx,sdfec-dout-words = <0>; - xlnx,sdfec-dout-width = <1>; - }; diff --git a/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml new file mode 100644 index 00000000000000..9bd21033742657 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml @@ -0,0 +1,140 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/misc/xlnx,sd-fec.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Xilinx SDFEC(16nm) IP + +maintainers: + - Cvetic, Dragan + - Erim, Salih + +description: + The Soft Decision Forward Error Correction (SDFEC) Engine is a Hard IP block + which provides high-throughput LDPC and Turbo Code implementations. + The LDPC decode & encode functionality is capable of covering a range of + customer specified Quasi-cyclic (QC) codes. The Turbo decode functionality + principally covers codes used by LTE. The FEC Engine offers significant + power and area savings versus implementations done in the FPGA fabric. + +properties: + compatible: + const: xlnx,sd-fec-1.1 + + reg: + maxItems: 1 + + clocks: + minItems: 2 + maxItems: 8 + additionalItems: true + items: + - description: Main processing clock for processing core + - description: AXI4-Lite memory-mapped slave interface clock + - description: Control input AXI4-Stream Slave interface clock + - description: DIN AXI4-Stream Slave interface clock + - description: Status output AXI4-Stream Master interface clock + - description: DOUT AXI4-Stream Master interface clock + - description: DIN_WORDS AXI4-Stream Slave interface clock + - description: DOUT_WORDS AXI4-Stream Master interface clock + + clock-names: + allOf: + - minItems: 2 + maxItems: 8 + additionalItems: true + items: + - const: core_clk + - const: s_axi_aclk + - items: + enum: + - core_clk + - s_axi_aclk + - s_axis_ctrl_aclk + - s_axis_din_aclk + - m_axis_status_aclk + - m_axis_dout_aclk + - s_axis_din_words_aclk + - m_axis_dout_words_aclk + + interrupts: + maxItems: 1 + + xlnx,sdfec-code: + description: + The SD-FEC integrated block supports Low Density Parity Check (LDPC) + decoding and encoding and Turbo code decoding. The LDPC codes used are + highly configurable, and the specific code used can be specified on + a codeword-by-codeword basis. The Turbo code decoding is required by LTE + standard. + $ref: /schemas/types.yaml#/definitions/string + items: + enum: [ ldpc, turbo ] + + xlnx,sdfec-din-width: + description: + Configures the DIN AXI stream where a value of 1 + configures a width of "1x128b", 2 a width of "2x128b" and 4 configures a width + of "4x128b". + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 1, 2, 4 ] + + xlnx,sdfec-din-words: + description: + A value 0 indicates that the DIN_WORDS interface is + driven with a fixed value and is not present on the device, a value of 1 + configures the DIN_WORDS to be block based, while a value of 2 configures the + DIN_WORDS input to be supplied for each AXI transaction. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2 ] + + xlnx,sdfec-dout-width: + description: + Configures the DOUT AXI stream where a value of 1 configures a width of "1x128b", + 2 a width of "2x128b" and 4 configures a width of "4x128b". + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 1, 2, 4 ] + + xlnx,sdfec-dout-words: + description: + A value 0 indicates that the DOUT_WORDS interface is + driven with a fixed value and is not present on the device, a value of 1 + configures the DOUT_WORDS to be block based, while a value of 2 configures the + DOUT_WORDS input to be supplied for each AXI transaction. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [ 0, 1, 2 ] + +required: + - compatible + - reg + - clocks + - clock-names + - xlnx,sdfec-code + - xlnx,sdfec-din-width + - xlnx,sdfec-din-words + - xlnx,sdfec-dout-width + - xlnx,sdfec-dout-words + +additionalProperties: false + +examples: + - | + #include + + sd-fec@a0040000 { + compatible = "xlnx,sd-fec-1.1"; + reg = <0xa0040000 0x40000>; + clocks = <&misc_clk_2>, <&misc_clk_0>, <&misc_clk_1>, <&misc_clk_1>, + <&misc_clk_1>, <&misc_clk_1>; + clock-names = "core_clk", "s_axi_aclk", "s_axis_ctrl_aclk", + "s_axis_din_aclk", "m_axis_status_aclk", + "m_axis_dout_aclk"; + interrupts = <1 IRQ_TYPE_LEVEL_HIGH>; + xlnx,sdfec-code = "ldpc"; + xlnx,sdfec-din-width = <2>; + xlnx,sdfec-din-words = <0>; + xlnx,sdfec-dout-width = <1>; + xlnx,sdfec-dout-words = <0>; + }; + diff --git a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml index 82eb7a24c85782..3f6dcc77309259 100644 --- a/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml +++ b/Documentation/devicetree/bindings/mmc/fsl-imx-esdhc.yaml @@ -55,8 +55,9 @@ properties: - enum: - fsl,imx8mn-usdhc - fsl,imx8mp-usdhc - - fsl,imx93-usdhc - fsl,imx8ulp-usdhc + - fsl,imx93-usdhc + - fsl,imx95-usdhc - const: fsl,imx8mm-usdhc - items: - enum: @@ -162,6 +163,9 @@ properties: - const: ahb - const: per + iommus: + maxItems: 1 + power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml index f7a4c6bc70f6ca..29f2400247ebc6 100644 --- a/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml +++ b/Documentation/devicetree/bindings/mmc/renesas,sdhi.yaml @@ -67,6 +67,7 @@ properties: - renesas,sdhi-r8a779a0 # R-Car V3U - renesas,sdhi-r8a779f0 # R-Car S4-8 - renesas,sdhi-r8a779g0 # R-Car V4H + - renesas,sdhi-r8a779h0 # R-Car V4M - const: renesas,rcar-gen4-sdhi # R-Car Gen4 reg: diff --git a/Documentation/devicetree/bindings/mtd/mtd.yaml b/Documentation/devicetree/bindings/mtd/mtd.yaml index f322290ee5165f..ee442ecb11cd9c 100644 --- a/Documentation/devicetree/bindings/mtd/mtd.yaml +++ b/Documentation/devicetree/bindings/mtd/mtd.yaml @@ -10,6 +10,8 @@ maintainers: - Miquel Raynal - Richard Weinberger +select: false + properties: $nodename: pattern: "^(flash|.*sram|nand)(@.*)?$" diff --git a/Documentation/devicetree/bindings/mux/mux-controller.yaml b/Documentation/devicetree/bindings/mux/mux-controller.yaml index 8b943082a2416e..571ad9e13ecfb6 100644 --- a/Documentation/devicetree/bindings/mux/mux-controller.yaml +++ b/Documentation/devicetree/bindings/mux/mux-controller.yaml @@ -74,7 +74,7 @@ select: properties: $nodename: - pattern: '^mux-controller(@.*|-[0-9a-f]+)?$' + pattern: '^mux-controller(@.*|-([0-9]|[1-9][0-9]+))?$' '#mux-control-cells': enum: [ 0, 1 ] diff --git a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml index 4162469c3c08a5..f197d9b516bb2a 100644 --- a/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml +++ b/Documentation/devicetree/bindings/net/can/fsl,flexcan.yaml @@ -38,6 +38,9 @@ properties: - fsl,imx6ul-flexcan - fsl,imx6sx-flexcan - const: fsl,imx6q-flexcan + - items: + - const: fsl,imx95-flexcan + - const: fsl,imx93-flexcan - items: - enum: - fsl,ls1028ar1-flexcan diff --git a/Documentation/devicetree/bindings/net/can/microchip,mpfs-can.yaml b/Documentation/devicetree/bindings/net/can/microchip,mpfs-can.yaml index 45aa3de7cf014a..01e4d4a54df6a0 100644 --- a/Documentation/devicetree/bindings/net/can/microchip,mpfs-can.yaml +++ b/Documentation/devicetree/bindings/net/can/microchip,mpfs-can.yaml @@ -24,7 +24,9 @@ properties: maxItems: 1 clocks: - maxItems: 1 + items: + - description: AHB peripheral clock + - description: CAN bus clock required: - compatible @@ -39,7 +41,7 @@ examples: can@2010c000 { compatible = "microchip,mpfs-can"; reg = <0x2010c000 0x1000>; - clocks = <&clkcfg 17>; + clocks = <&clkcfg 17>, <&clkcfg 37>; interrupt-parent = <&plic>; interrupts = <56>; }; diff --git a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt index 170e23f0610db9..20c0572c985342 100644 --- a/Documentation/devicetree/bindings/net/can/tcan4x5x.txt +++ b/Documentation/devicetree/bindings/net/can/tcan4x5x.txt @@ -28,6 +28,8 @@ Optional properties: available with tcan4552/4553. - device-wake-gpios: Wake up GPIO to wake up the TCAN device. Not available with tcan4552/4553. + - wakeup-source: Leave the chip running when suspended, and configure + the RX interrupt to wake up the device. Example: tcan4x5x: tcan4x5x@0 { @@ -42,4 +44,5 @@ tcan4x5x: tcan4x5x@0 { device-state-gpios = <&gpio3 21 GPIO_ACTIVE_HIGH>; device-wake-gpios = <&gpio1 15 GPIO_ACTIVE_HIGH>; reset-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>; + wakeup-source; }; diff --git a/Documentation/devicetree/bindings/net/can/xilinx,can.yaml b/Documentation/devicetree/bindings/net/can/xilinx,can.yaml index 64d57c343e6f0a..8d4e5af6fd6c84 100644 --- a/Documentation/devicetree/bindings/net/can/xilinx,can.yaml +++ b/Documentation/devicetree/bindings/net/can/xilinx,can.yaml @@ -49,6 +49,10 @@ properties: resets: maxItems: 1 + xlnx,has-ecc: + $ref: /schemas/types.yaml#/definitions/flag + description: CAN TX_OL, TX_TL and RX FIFOs have ECC support(AXI CAN) + required: - compatible - reg @@ -137,6 +141,7 @@ examples: interrupts = ; tx-fifo-depth = <0x40>; rx-fifo-depth = <0x40>; + xlnx,has-ecc; }; - | diff --git a/Documentation/devicetree/bindings/net/dsa/ar9331.txt b/Documentation/devicetree/bindings/net/dsa/ar9331.txt deleted file mode 100644 index f824fdae0da20a..00000000000000 --- a/Documentation/devicetree/bindings/net/dsa/ar9331.txt +++ /dev/null @@ -1,147 +0,0 @@ -Atheros AR9331 built-in switch -============================= - -It is a switch built-in to Atheros AR9331 WiSoC and addressable over internal -MDIO bus. All PHYs are built-in as well. - -Required properties: - - - compatible: should be: "qca,ar9331-switch" - - reg: Address on the MII bus for the switch. - - resets : Must contain an entry for each entry in reset-names. - - reset-names : Must include the following entries: "switch" - - interrupt-parent: Phandle to the parent interrupt controller - - interrupts: IRQ line for the switch - - interrupt-controller: Indicates the switch is itself an interrupt - controller. This is used for the PHY interrupts. - - #interrupt-cells: must be 1 - - mdio: Container of PHY and devices on the switches MDIO bus. - -See Documentation/devicetree/bindings/net/dsa/dsa.txt for a list of additional -required and optional properties. -Examples: - -eth0: ethernet@19000000 { - compatible = "qca,ar9330-eth"; - reg = <0x19000000 0x200>; - interrupts = <4>; - - resets = <&rst 9>, <&rst 22>; - reset-names = "mac", "mdio"; - clocks = <&pll ATH79_CLK_AHB>, <&pll ATH79_CLK_AHB>; - clock-names = "eth", "mdio"; - - phy-mode = "mii"; - phy-handle = <&phy_port4>; -}; - -eth1: ethernet@1a000000 { - compatible = "qca,ar9330-eth"; - reg = <0x1a000000 0x200>; - interrupts = <5>; - resets = <&rst 13>, <&rst 23>; - reset-names = "mac", "mdio"; - clocks = <&pll ATH79_CLK_AHB>, <&pll ATH79_CLK_AHB>; - clock-names = "eth", "mdio"; - - phy-mode = "gmii"; - - fixed-link { - speed = <1000>; - full-duplex; - }; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - - switch10: switch@10 { - #address-cells = <1>; - #size-cells = <0>; - - compatible = "qca,ar9331-switch"; - reg = <0x10>; - resets = <&rst 8>; - reset-names = "switch"; - - interrupt-parent = <&miscintc>; - interrupts = <12>; - - interrupt-controller; - #interrupt-cells = <1>; - - ports { - #address-cells = <1>; - #size-cells = <0>; - - switch_port0: port@0 { - reg = <0x0>; - ethernet = <ð1>; - - phy-mode = "gmii"; - - fixed-link { - speed = <1000>; - full-duplex; - }; - }; - - switch_port1: port@1 { - reg = <0x1>; - phy-handle = <&phy_port0>; - phy-mode = "internal"; - }; - - switch_port2: port@2 { - reg = <0x2>; - phy-handle = <&phy_port1>; - phy-mode = "internal"; - }; - - switch_port3: port@3 { - reg = <0x3>; - phy-handle = <&phy_port2>; - phy-mode = "internal"; - }; - - switch_port4: port@4 { - reg = <0x4>; - phy-handle = <&phy_port3>; - phy-mode = "internal"; - }; - }; - - mdio { - #address-cells = <1>; - #size-cells = <0>; - - interrupt-parent = <&switch10>; - - phy_port0: phy@0 { - reg = <0x0>; - interrupts = <0>; - }; - - phy_port1: phy@1 { - reg = <0x1>; - interrupts = <0>; - }; - - phy_port2: phy@2 { - reg = <0x2>; - interrupts = <0>; - }; - - phy_port3: phy@3 { - reg = <0x3>; - interrupts = <0>; - }; - - phy_port4: phy@4 { - reg = <0x4>; - interrupts = <0>; - }; - }; - }; - }; -}; diff --git a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml index c963dc09e8e12a..52acc15ebcbf36 100644 --- a/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml +++ b/Documentation/devicetree/bindings/net/dsa/microchip,ksz.yaml @@ -31,6 +31,7 @@ properties: - microchip,ksz9893 - microchip,ksz9563 - microchip,ksz8563 + - microchip,ksz8567 reset-gpios: description: diff --git a/Documentation/devicetree/bindings/net/dsa/qca,ar9331.yaml b/Documentation/devicetree/bindings/net/dsa/qca,ar9331.yaml new file mode 100644 index 00000000000000..fd9ddc59d38c31 --- /dev/null +++ b/Documentation/devicetree/bindings/net/dsa/qca,ar9331.yaml @@ -0,0 +1,161 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/dsa/qca,ar9331.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Atheros AR9331 built-in switch + +maintainers: + - Oleksij Rempel + +description: + Qualcomm Atheros AR9331 is a switch built-in to Atheros AR9331 WiSoC and + addressable over internal MDIO bus. All PHYs are built-in as well. + +properties: + compatible: + const: qca,ar9331-switch + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + interrupt-controller: true + + '#interrupt-cells': + const: 1 + + mdio: + $ref: /schemas/net/mdio.yaml# + unevaluatedProperties: false + properties: + interrupt-parent: true + + patternProperties: + '(ethernet-)?phy@[0-4]+$': + type: object + unevaluatedProperties: false + + properties: + reg: true + interrupts: + maxItems: 1 + + resets: + maxItems: 1 + + reset-names: + items: + - const: switch + +required: + - compatible + - reg + - interrupts + - interrupt-controller + - '#interrupt-cells' + - mdio + - ports + - resets + - reset-names + +allOf: + - $ref: dsa.yaml#/$defs/ethernet-ports + +unevaluatedProperties: false + +examples: + - | + mdio { + #address-cells = <1>; + #size-cells = <0>; + + switch10: switch@10 { + compatible = "qca,ar9331-switch"; + reg = <0x10>; + + interrupt-parent = <&miscintc>; + interrupts = <12>; + interrupt-controller; + #interrupt-cells = <1>; + + resets = <&rst 8>; + reset-names = "switch"; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0x0>; + ethernet = <ð1>; + + phy-mode = "gmii"; + + fixed-link { + speed = <1000>; + full-duplex; + }; + }; + + port@1 { + reg = <0x1>; + phy-handle = <&phy_port0>; + phy-mode = "internal"; + }; + + port@2 { + reg = <0x2>; + phy-handle = <&phy_port1>; + phy-mode = "internal"; + }; + + port@3 { + reg = <0x3>; + phy-handle = <&phy_port2>; + phy-mode = "internal"; + }; + + port@4 { + reg = <0x4>; + phy-handle = <&phy_port3>; + phy-mode = "internal"; + }; + }; + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + interrupt-parent = <&switch10>; + + phy_port0: ethernet-phy@0 { + reg = <0x0>; + interrupts = <0>; + }; + + phy_port1: ethernet-phy@1 { + reg = <0x1>; + interrupts = <0>; + }; + + phy_port2: ethernet-phy@2 { + reg = <0x2>; + interrupts = <0>; + }; + + phy_port3: ethernet-phy@3 { + reg = <0x3>; + interrupts = <0>; + }; + + phy_port4: ethernet-phy@4 { + reg = <0x4>; + interrupts = <0>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/ethernet-phy-package.yaml b/Documentation/devicetree/bindings/net/ethernet-phy-package.yaml new file mode 100644 index 00000000000000..e567101e6f38b1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ethernet-phy-package.yaml @@ -0,0 +1,52 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ethernet-phy-package.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ethernet PHY Package Common Properties + +maintainers: + - Christian Marangi + +description: + PHY packages are multi-port Ethernet PHY of the same family + and each Ethernet PHY is affected by the global configuration + of the PHY package. + + Each reg of the PHYs defined in the PHY package node is + absolute and describe the real address of the Ethernet PHY on + the MDIO bus. + +properties: + $nodename: + pattern: "^ethernet-phy-package@[a-f0-9]+$" + + reg: + minimum: 0 + maximum: 31 + description: + The base ID number for the PHY package. + Commonly the ID of the first PHY in the PHY package. + + Some PHY in the PHY package might be not defined but + still occupy ID on the device (just not attached to + anything) hence the PHY package reg might correspond + to a not attached PHY (offset 0). + + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + +patternProperties: + ^ethernet-phy@[a-f0-9]+$: + $ref: ethernet-phy.yaml# + +required: + - reg + - '#address-cells' + - '#size-cells' + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/net/fsl,fec.yaml b/Documentation/devicetree/bindings/net/fsl,fec.yaml index 8948a11c994e48..5536c06139cae5 100644 --- a/Documentation/devicetree/bindings/net/fsl,fec.yaml +++ b/Documentation/devicetree/bindings/net/fsl,fec.yaml @@ -224,6 +224,9 @@ properties: Can be omitted thus no delay is observed. Delay is in range of 1ms to 1000ms. Other delays are invalid. + iommus: + maxItems: 1 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/marvell,prestera.yaml b/Documentation/devicetree/bindings/net/marvell,prestera.yaml index 5ea8b73663a50c..16ff892f7bbd0a 100644 --- a/Documentation/devicetree/bindings/net/marvell,prestera.yaml +++ b/Documentation/devicetree/bindings/net/marvell,prestera.yaml @@ -78,8 +78,8 @@ examples: pcie@0 { #address-cells = <3>; #size-cells = <2>; - ranges = <0x0 0x0 0x0 0x0 0x0 0x0>; - reg = <0x0 0x0 0x0 0x0 0x0 0x0>; + ranges = <0x02000000 0x0 0x100000 0x10000000 0x0 0x0>; + reg = <0x0 0x1000>; device_type = "pci"; switch@0,0 { diff --git a/Documentation/devicetree/bindings/net/nfc/ti,trf7970a.yaml b/Documentation/devicetree/bindings/net/nfc/ti,trf7970a.yaml index 9cc236ec42f232..d0332eb76ad263 100644 --- a/Documentation/devicetree/bindings/net/nfc/ti,trf7970a.yaml +++ b/Documentation/devicetree/bindings/net/nfc/ti,trf7970a.yaml @@ -73,7 +73,7 @@ examples: #include #include - i2c { + spi { #address-cells = <1>; #size-cells = <0>; diff --git a/Documentation/devicetree/bindings/net/qca,qca808x.yaml b/Documentation/devicetree/bindings/net/qca,qca808x.yaml new file mode 100644 index 00000000000000..e2552655902a38 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qca,qca808x.yaml @@ -0,0 +1,54 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/qca,qca808x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Atheros QCA808X PHY + +maintainers: + - Christian Marangi + +description: + QCA808X PHYs can have up to 3 LEDs attached. + All 3 LEDs are disabled by default. + 2 LEDs have dedicated pins with the 3rd LED having the + double function of Interrupt LEDs/GPIO or additional LED. + + By default this special PIN is set to LED function. + +allOf: + - $ref: ethernet-phy.yaml# + +properties: + compatible: + enum: + - ethernet-phy-id004d.d101 + +unevaluatedProperties: false + +examples: + - | + #include + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy@0 { + compatible = "ethernet-phy-id004d.d101"; + reg = <0>; + + leds { + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + color = ; + function = LED_FUNCTION_WAN; + default-state = "keep"; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/qcom,ethqos.yaml b/Documentation/devicetree/bindings/net/qcom,ethqos.yaml index 7bdb412a018553..69a337c7e345ea 100644 --- a/Documentation/devicetree/bindings/net/qcom,ethqos.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ethqos.yaml @@ -37,12 +37,14 @@ properties: items: - description: Combined signal for various interrupt events - description: The interrupt that occurs when Rx exits the LPI state + - description: The interrupt that occurs when HW safety error triggered interrupt-names: minItems: 1 items: - const: macirq - - const: eth_lpi + - enum: [eth_lpi, sfty] + - const: sfty clocks: maxItems: 4 @@ -89,8 +91,9 @@ examples: <&gcc GCC_ETH_PTP_CLK>, <&gcc GCC_ETH_RGMII_CLK>; interrupts = , - ; - interrupt-names = "macirq", "eth_lpi"; + , + ; + interrupt-names = "macirq", "eth_lpi", "sfty"; rx-fifo-depth = <4096>; tx-fifo-depth = <4096>; diff --git a/Documentation/devicetree/bindings/net/qcom,ipa.yaml b/Documentation/devicetree/bindings/net/qcom,ipa.yaml index c30218684cfe46..53cae71d99572c 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipa.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipa.yaml @@ -159,7 +159,7 @@ properties: when the AP (not the modem) performs early initialization. firmware-name: - $ref: /schemas/types.yaml#/definitions/string + maxItems: 1 description: If present, name (or relative path) of the file within the firmware search path containing the firmware image used when diff --git a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml index 3407e909e8a7ad..0029e197a8251e 100644 --- a/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml +++ b/Documentation/devicetree/bindings/net/qcom,ipq4019-mdio.yaml @@ -44,6 +44,21 @@ properties: items: - const: gcc_mdio_ahb_clk + clock-frequency: + description: + The MDIO bus clock that must be output by the MDIO bus hardware, if + absent, the default hardware values are used. + + MDC rate is feed by an external clock (fixed 100MHz) and is divider + internally. The default divider is /256 resulting in the default rate + applied of 390KHz. + + To follow 802.3 standard that instruct up to 2.5MHz by default, if + this property is not declared and the divider is set to /256, by + default 1.5625Mhz is select. + enum: [ 390625, 781250, 1562500, 3125000, 6250000, 12500000 ] + default: 1562500 + required: - compatible - reg diff --git a/Documentation/devicetree/bindings/net/qcom,qca807x.yaml b/Documentation/devicetree/bindings/net/qcom,qca807x.yaml new file mode 100644 index 00000000000000..7290024024f526 --- /dev/null +++ b/Documentation/devicetree/bindings/net/qcom,qca807x.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/qcom,qca807x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QCA807x Ethernet PHY + +maintainers: + - Christian Marangi + - Robert Marko + +description: | + Qualcomm QCA8072/5 Ethernet PHY is PHY package of 2 or 5 + IEEE 802.3 clause 22 compliant 10BASE-Te, 100BASE-TX and + 1000BASE-T PHY-s. + + They feature 2 SerDes, one for PSGMII or QSGMII connection with + MAC, while second one is SGMII for connection to MAC or fiber. + + Both models have a combo port that supports 1000BASE-X and + 100BASE-FX fiber. + + Each PHY inside of QCA807x series has 4 digitally controlled + output only pins that natively drive LED-s for up to 2 attached + LEDs. Some vendor also use these 4 output for GPIO usage without + attaching LEDs. + + Note that output pins can be set to drive LEDs OR GPIO, mixed + definition are not accepted. + +$ref: ethernet-phy-package.yaml# + +properties: + compatible: + enum: + - qcom,qca8072-package + - qcom,qca8075-package + + qcom,package-mode: + description: | + PHY package can be configured in 3 mode following this table: + + First Serdes mode Second Serdes mode + Option 1 PSGMII for copper Disabled + ports 0-4 + Option 2 PSGMII for copper 1000BASE-X / 100BASE-FX + ports 0-4 + Option 3 QSGMII for copper SGMII for + ports 0-3 copper port 4 + + PSGMII mode (option 1 or 2) is configured dynamically based on + the presence of a connected SFP device. + $ref: /schemas/types.yaml#/definitions/string + enum: + - qsgmii + - psgmii + default: psgmii + + qcom,tx-drive-strength-milliwatt: + description: set the TX Amplifier value in mv. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [140, 160, 180, 200, 220, + 240, 260, 280, 300, 320, + 400, 500, 600] + default: 600 + +patternProperties: + ^ethernet-phy@[a-f0-9]+$: + $ref: ethernet-phy.yaml# + + properties: + qcom,dac-full-amplitude: + description: + Set Analog MDI driver amplitude to FULL. + + With this not defined, amplitude is set to DSP. + (amplitude is adjusted based on cable length) + + With this enabled and qcom,dac-full-bias-current + and qcom,dac-disable-bias-current-tweak disabled, + bias current is half. + type: boolean + + qcom,dac-full-bias-current: + description: + Set Analog MDI driver bias current to FULL. + + With this not defined, bias current is set to DSP. + (bias current is adjusted based on cable length) + + Actual bias current might be different with + qcom,dac-disable-bias-current-tweak disabled. + type: boolean + + qcom,dac-disable-bias-current-tweak: + description: | + Set Analog MDI driver bias current to disable tweak + to bias current. + + With this not defined, bias current tweak are enabled + by default. + + With this enabled the following tweak are NOT applied: + - With both FULL amplitude and FULL bias current: bias current + is set to half. + - With only DSP amplitude: bias current is set to half and + is set to 1/4 with cable < 10m. + - With DSP bias current (included both DSP amplitude and + DSP bias current): bias current is half the detected current + with cable < 10m. + type: boolean + + gpio-controller: true + + '#gpio-cells': + const: 2 + + if: + required: + - gpio-controller + then: + properties: + leds: false + + unevaluatedProperties: false + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include + + mdio { + #address-cells = <1>; + #size-cells = <0>; + + ethernet-phy-package@0 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "qcom,qca8075-package"; + reg = <0>; + + qcom,package-mode = "qsgmii"; + + ethernet-phy@0 { + reg = <0>; + + leds { + #address-cells = <1>; + #size-cells = <0>; + + led@0 { + reg = <0>; + color = ; + function = LED_FUNCTION_LAN; + default-state = "keep"; + }; + }; + }; + + ethernet-phy@1 { + reg = <1>; + }; + + ethernet-phy@2 { + reg = <2>; + + gpio-controller; + #gpio-cells = <2>; + }; + + ethernet-phy@3 { + reg = <3>; + }; + + ethernet-phy@4 { + reg = <4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/net/snps,dwmac.yaml b/Documentation/devicetree/bindings/net/snps,dwmac.yaml index 5c2769dc689af7..6b0341a8e0ea5f 100644 --- a/Documentation/devicetree/bindings/net/snps,dwmac.yaml +++ b/Documentation/devicetree/bindings/net/snps,dwmac.yaml @@ -95,6 +95,7 @@ properties: - snps,dwmac-5.20 - snps,dwxgmac - snps,dwxgmac-2.10 + - starfive,jh7100-dwmac - starfive,jh7110-dwmac reg: @@ -107,13 +108,15 @@ properties: - description: Combined signal for various interrupt events - description: The interrupt to manage the remote wake-up packet detection - description: The interrupt that occurs when Rx exits the LPI state + - description: The interrupt that occurs when HW safety error triggered interrupt-names: minItems: 1 items: - const: macirq - - enum: [eth_wake_irq, eth_lpi] - - const: eth_lpi + - enum: [eth_wake_irq, eth_lpi, sfty] + - enum: [eth_wake_irq, eth_lpi, sfty] + - enum: [eth_wake_irq, eth_lpi, sfty] clocks: minItems: 1 @@ -144,10 +147,12 @@ properties: - description: AHB reset reset-names: - minItems: 1 - items: - - const: stmmaceth - - const: ahb + oneOf: + - items: + - enum: [stmmaceth, ahb] + - items: + - const: stmmaceth + - const: ahb power-domains: maxItems: 1 diff --git a/Documentation/devicetree/bindings/net/starfive,jh7110-dwmac.yaml b/Documentation/devicetree/bindings/net/starfive,jh7110-dwmac.yaml index 5e7cfbbebce6cc..0d1962980f57f5 100644 --- a/Documentation/devicetree/bindings/net/starfive,jh7110-dwmac.yaml +++ b/Documentation/devicetree/bindings/net/starfive,jh7110-dwmac.yaml @@ -16,16 +16,20 @@ select: compatible: contains: enum: + - starfive,jh7100-dwmac - starfive,jh7110-dwmac required: - compatible properties: compatible: - items: - - enum: - - starfive,jh7110-dwmac - - const: snps,dwmac-5.20 + oneOf: + - items: + - const: starfive,jh7100-dwmac + - const: snps,dwmac + - items: + - const: starfive,jh7110-dwmac + - const: snps,dwmac-5.20 reg: maxItems: 1 @@ -46,24 +50,6 @@ properties: - const: tx - const: gtx - interrupts: - minItems: 3 - maxItems: 3 - - interrupt-names: - minItems: 3 - maxItems: 3 - - resets: - items: - - description: MAC Reset signal. - - description: AHB Reset signal. - - reset-names: - items: - - const: stmmaceth - - const: ahb - starfive,tx-use-rgmii-clk: description: Tx clock is provided by external rgmii clock. @@ -94,6 +80,48 @@ required: allOf: - $ref: snps,dwmac.yaml# + - if: + properties: + compatible: + contains: + const: starfive,jh7100-dwmac + then: + properties: + interrupts: + minItems: 2 + maxItems: 2 + + interrupt-names: + minItems: 2 + maxItems: 2 + + resets: + maxItems: 1 + + reset-names: + const: ahb + + - if: + properties: + compatible: + contains: + const: starfive,jh7110-dwmac + then: + properties: + interrupts: + minItems: 3 + maxItems: 3 + + interrupt-names: + minItems: 3 + maxItems: 3 + + resets: + minItems: 2 + + reset-names: + minItems: 2 + unevaluatedProperties: false examples: diff --git a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml index f07ae3173b03d4..d5bd93ee4dbb16 100644 --- a/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml +++ b/Documentation/devicetree/bindings/net/ti,cpsw-switch.yaml @@ -7,8 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: TI SoC Ethernet Switch Controller (CPSW) maintainers: - - Grygorii Strashko - - Sekhar Nori + - Siddharth Vadapalli + - Ravi Gunasekaran + - Roger Quadros description: The 3-port switch gigabit ethernet subsystem provides ethernet packet diff --git a/Documentation/devicetree/bindings/net/ti,dp83822.yaml b/Documentation/devicetree/bindings/net/ti,dp83822.yaml index db74474207ed47..8f4350be689c57 100644 --- a/Documentation/devicetree/bindings/net/ti,dp83822.yaml +++ b/Documentation/devicetree/bindings/net/ti,dp83822.yaml @@ -62,6 +62,24 @@ properties: for the PHY. The internal delay for the PHY is fixed to 3.5ns relative to transmit data. + ti,cfg-dac-minus-one-bp: + description: | + DP83826 PHY only. + Sets the voltage ratio (with respect to the nominal value) + of the logical level -1 for the MLT-3 encoded TX data. + enum: [5000, 5625, 6250, 6875, 7500, 8125, 8750, 9375, 10000, + 10625, 11250, 11875, 12500, 13125, 13750, 14375, 15000] + default: 10000 + + ti,cfg-dac-plus-one-bp: + description: | + DP83826 PHY only. + Sets the voltage ratio (with respect to the nominal value) + of the logical level +1 for the MLT-3 encoded TX data. + enum: [5000, 5625, 6250, 6875, 7500, 8125, 8750, 9375, 10000, + 10625, 11250, 11875, 12500, 13125, 13750, 14375, 15000] + default: 10000 + required: - reg diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml index c9c25132d1544a..73ed5951d29695 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpsw-nuss.yaml @@ -7,8 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: The TI AM654x/J721E/AM642x SoC Gigabit Ethernet MAC (Media Access Controller) maintainers: - - Grygorii Strashko - - Sekhar Nori + - Siddharth Vadapalli + - Ravi Gunasekaran + - Roger Quadros description: The TI AM654x/J721E SoC Gigabit Ethernet MAC (CPSW2G NUSS) has two ports diff --git a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml index 3e910d3b24a08b..b1c875325776d4 100644 --- a/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml +++ b/Documentation/devicetree/bindings/net/ti,k3-am654-cpts.yaml @@ -7,8 +7,9 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: The TI AM654x/J721E Common Platform Time Sync (CPTS) module maintainers: - - Grygorii Strashko - - Sekhar Nori + - Siddharth Vadapalli + - Ravi Gunasekaran + - Roger Quadros description: |+ The TI AM654x/J721E CPTS module is used to facilitate host control of time diff --git a/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml b/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml index ac2381e6602790..8b3826243dddfc 100644 --- a/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml +++ b/Documentation/devicetree/bindings/nvmem/layouts/fixed-cell.yaml @@ -36,20 +36,18 @@ properties: allOf: - if: + properties: + compatible: + contains: + const: mac-base required: [ compatible ] then: - if: - properties: - compatible: - contains: - const: mac-base - then: - properties: - "#nvmem-cell-cells": - description: The first argument is a MAC address offset. - const: 1 - required: - - "#nvmem-cell-cells" + properties: + "#nvmem-cell-cells": + description: The first argument is a MAC address offset. + const: 1 + required: + - "#nvmem-cell-cells" required: - reg diff --git a/Documentation/devicetree/bindings/nvmem/nvmem-provider.yaml b/Documentation/devicetree/bindings/nvmem/nvmem-provider.yaml new file mode 100644 index 00000000000000..4009a9a03841ed --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/nvmem-provider.yaml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/nvmem-provider.yaml# +$schema: http://devicetree.org/meta-schemas/base.yaml# + +title: NVMEM (Non Volatile Memory) Provider + +maintainers: + - Srinivas Kandagatla + +select: true + +properties: + '#nvmem-cell-cells': + enum: [0, 1] + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt b/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt deleted file mode 100644 index 4881561b3a02ac..00000000000000 --- a/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.txt +++ /dev/null @@ -1,46 +0,0 @@ --------------------------------------------------------------------------- -= 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/nvmem/xlnx,zynqmp-nvmem.yaml b/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.yaml new file mode 100644 index 00000000000000..917c40d5c382f4 --- /dev/null +++ b/Documentation/devicetree/bindings/nvmem/xlnx,zynqmp-nvmem.yaml @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/nvmem/xlnx,zynqmp-nvmem.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Zynq UltraScale+ MPSoC Non Volatile Memory interface + +description: | + The ZynqMP MPSoC provides access to the hardware related data + like SOC revision, IDCODE and specific purpose efuses. + +maintainers: + - Kalyani Akula + - Praveen Teja Kundanala + +allOf: + - $ref: nvmem.yaml# + +properties: + compatible: + const: xlnx,zynqmp-nvmem-fw + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + nvmem { + compatible = "xlnx,zynqmp-nvmem-fw"; + nvmem-layout { + compatible = "fixed-layout"; + #address-cells = <1>; + #size-cells = <1>; + + soc_revision: soc-revision@0 { + reg = <0x0 0x4>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/perf/arm,coresight-pmu.yaml b/Documentation/devicetree/bindings/perf/arm,coresight-pmu.yaml new file mode 100644 index 00000000000000..985b62990f8027 --- /dev/null +++ b/Documentation/devicetree/bindings/perf/arm,coresight-pmu.yaml @@ -0,0 +1,39 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/perf/arm,coresight-pmu.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Arm Coresight Performance Monitoring Unit Architecture + +maintainers: + - Robin Murphy + +properties: + compatible: + const: arm,coresight-pmu + + reg: + items: + - description: Register page 0 + - description: Register page 1, if the PMU implements the dual-page extension + minItems: 1 + + interrupts: + items: + - description: Overflow interrupt + + cpus: + description: If the PMU is associated with a particular CPU or subset of CPUs, + array of phandles to the appropriate CPU node(s) + + reg-io-width: + description: Granularity at which PMU register accesses are single-copy atomic + default: 4 + enum: [4, 8] + +required: + - compatible + - reg + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/phy/mediatek,mt8365-csi-rx.yaml b/Documentation/devicetree/bindings/phy/mediatek,mt8365-csi-rx.yaml new file mode 100644 index 00000000000000..2127a5732f7346 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/mediatek,mt8365-csi-rx.yaml @@ -0,0 +1,79 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +# Copyright (c) 2023 MediaTek, BayLibre +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/mediatek,mt8365-csi-rx.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Mediatek Sensor Interface MIPI CSI CD-PHY + +maintainers: + - Julien Stephan + - Andy Hsieh + +description: + The SENINF CD-PHY is a set of CD-PHY connected to the SENINF CSI-2 + receivers. The number of PHYs depends on the SoC model. + Depending on the SoC model, each PHYs can be either CD-PHY or D-PHY only + capable. + +properties: + compatible: + enum: + - mediatek,mt8365-csi-rx + + reg: + maxItems: 1 + + num-lanes: + enum: [2, 3, 4] + + '#phy-cells': + enum: [0, 1] + description: | + If the PHY doesn't support mode selection then #phy-cells must be 0 and + PHY mode is described using phy-type property. + If the PHY supports mode selection, then #phy-cells must be 1 and mode + is set in the PHY cells. Supported modes are: + - PHY_TYPE_DPHY + - PHY_TYPE_CPHY + See include/dt-bindings/phy/phy.h for constants. + + phy-type: + description: + If the PHY doesn't support mode selection then this set the operating mode. + See include/dt-bindings/phy/phy.h for constants. + const: 10 + $ref: /schemas/types.yaml#/definitions/uint32 + +required: + - compatible + - reg + - num-lanes + - '#phy-cells' + +additionalProperties: false + +examples: + - | + #include + soc { + #address-cells = <2>; + #size-cells = <2>; + + csi0_rx: phy@11c10000 { + compatible = "mediatek,mt8365-csi-rx"; + reg = <0 0x11c10000 0 0x2000>; + num-lanes = <2>; + #phy-cells = <1>; + }; + + csi1_rx: phy@11c12000 { + compatible = "mediatek,mt8365-csi-rx"; + reg = <0 0x11c12000 0 0x2000>; + phy-type = ; + num-lanes = <2>; + #phy-cells = <0>; + }; + }; +... diff --git a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml index dfb31314face76..15dc8efe6ffe74 100644 --- a/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml +++ b/Documentation/devicetree/bindings/phy/phy-cadence-torrent.yaml @@ -20,6 +20,7 @@ properties: compatible: enum: - cdns,torrent-phy + - ti,j7200-serdes-10g - ti,j721e-serdes-10g '#address-cells': @@ -35,14 +36,18 @@ properties: minItems: 1 maxItems: 2 description: - PHY reference clock for 1 item. Must contain an entry in clock-names. - Optional Parent to enable output reference clock. + PHY input reference clocks - refclk (for PLL0) & pll1_refclk (for PLL1). + pll1_refclk is optional and used for multi-protocol configurations requiring + separate reference clock for each protocol. + Same refclk is used for both PLL0 and PLL1 if no separate pll1_refclk is used. + Optional parent clock (phy_en_refclk) to enable a reference clock output feature + on some platforms to output either derived or received reference clock. clock-names: minItems: 1 items: - const: refclk - - const: phy_en_refclk + - enum: [ pll1_refclk, phy_en_refclk ] reg: minItems: 1 diff --git a/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-usb3-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-usb3-phy.yaml new file mode 100644 index 00000000000000..f1f4e4f83352d7 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/qcom,msm8998-qmp-usb3-phy.yaml @@ -0,0 +1,184 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/qcom,msm8998-qmp-usb3-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm QMP PHY controller (USB, MSM8998) + +maintainers: + - Vinod Koul + +description: + The QMP PHY controller supports physical layer functionality for USB-C on + several Qualcomm chipsets. + +properties: + compatible: + enum: + - qcom,msm8998-qmp-usb3-phy + - qcom,qcm2290-qmp-usb3-phy + - qcom,sdm660-qmp-usb3-phy + - qcom,sm6115-qmp-usb3-phy + + reg: + maxItems: 1 + + clocks: + maxItems: 4 + + clock-names: + maxItems: 4 + + resets: + maxItems: 2 + + reset-names: + items: + - const: phy + - const: phy_phy + + vdda-phy-supply: true + + vdda-pll-supply: true + + "#clock-cells": + const: 0 + + clock-output-names: + maxItems: 1 + + "#phy-cells": + const: 0 + + orientation-switch: + description: + Flag the PHY as possible handler of USB Type-C orientation switching + type: boolean + + qcom,tcsr-reg: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + - items: + - description: phandle to TCSR hardware block + - description: offset of the VLS CLAMP register + description: Clamp register present in the TCSR + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: Output endpoint of the PHY + + port@1: + $ref: /schemas/graph.yaml#/properties/port + description: Incoming endpoint from the USB controller + +required: + - compatible + - reg + - clocks + - clock-names + - resets + - reset-names + - vdda-phy-supply + - vdda-pll-supply + - "#clock-cells" + - clock-output-names + - "#phy-cells" + - qcom,tcsr-reg + +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,msm8998-qmp-usb3-phy + - qcom,sdm660-qmp-usb3-phy + then: + properties: + clocks: + maxItems: 4 + clock-names: + items: + - const: aux + - const: ref + - const: cfg_ahb + - const: pipe + + - if: + properties: + compatible: + contains: + enum: + - qcom,qcm2290-qmp-usb3-phy + - qcom,sm6115-qmp-usb3-phy + then: + properties: + clocks: + maxItems: 4 + clock-names: + items: + - const: cfg_ahb + - const: ref + - const: com_aux + - const: pipe + +additionalProperties: false + +examples: + - | + #include + #include + + phy@c010000 { + compatible = "qcom,msm8998-qmp-usb3-phy"; + reg = <0x0c010000 0x1000>; + + clocks = <&gcc GCC_USB3_PHY_AUX_CLK>, + <&gcc GCC_USB3_CLKREF_CLK>, + <&gcc GCC_USB_PHY_CFG_AHB2PHY_CLK>, + <&gcc GCC_USB3_PHY_PIPE_CLK>; + clock-names = "aux", + "ref", + "cfg_ahb", + "pipe"; + clock-output-names = "usb3_phy_pipe_clk_src"; + #clock-cells = <0>; + #phy-cells = <0>; + + resets = <&gcc GCC_USB3_PHY_BCR>, + <&gcc GCC_USB3PHY_PHY_BCR>; + reset-names = "phy", + "phy_phy"; + + vdda-phy-supply = <&vreg_l1a_0p875>; + vdda-pll-supply = <&vreg_l2a_1p2>; + + orientation-switch; + + qcom,tcsr-reg = <&tcsr_regs_1 0x6b244>; + + ports { + #address-cells = <1>; + #size-cells = <0>; + + port@0 { + reg = <0>; + + endpoint { + remote-endpoint = <&pmic_typec_mux_in>; + }; + }; + + port@1 { + reg = <1>; + + endpoint { + remote-endpoint = <&usb_dwc3_ss>; + }; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml index 6c03f2d5fca3cc..ba966a78a1283f 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-pcie-phy.yaml @@ -38,6 +38,8 @@ properties: - qcom,sm8550-qmp-gen4x2-pcie-phy - qcom,sm8650-qmp-gen3x2-pcie-phy - qcom,sm8650-qmp-gen4x2-pcie-phy + - qcom,x1e80100-qmp-gen3x2-pcie-phy + - qcom,x1e80100-qmp-gen4x2-pcie-phy reg: minItems: 1 @@ -151,6 +153,8 @@ allOf: - qcom,sm8550-qmp-gen4x2-pcie-phy - qcom,sm8650-qmp-gen3x2-pcie-phy - qcom,sm8650-qmp-gen4x2-pcie-phy + - qcom,x1e80100-qmp-gen3x2-pcie-phy + - qcom,x1e80100-qmp-gen4x2-pcie-phy then: properties: clocks: @@ -194,6 +198,8 @@ allOf: enum: - qcom,sm8550-qmp-gen4x2-pcie-phy - qcom,sm8650-qmp-gen4x2-pcie-phy + - qcom,x1e80100-qmp-gen3x2-pcie-phy + - qcom,x1e80100-qmp-gen4x2-pcie-phy then: properties: resets: diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml index 8474eef8d0ff52..91a6cc38ff7ff5 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-ufs-phy.yaml @@ -19,6 +19,7 @@ properties: - qcom,msm8996-qmp-ufs-phy - qcom,msm8998-qmp-ufs-phy - qcom,sa8775p-qmp-ufs-phy + - qcom,sc7180-qmp-ufs-phy - qcom,sc7280-qmp-ufs-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8280xp-qmp-ufs-phy @@ -38,15 +39,12 @@ properties: maxItems: 1 clocks: - minItems: 1 + minItems: 2 maxItems: 3 clock-names: - minItems: 1 - items: - - const: ref - - const: ref_aux - - const: qref + minItems: 2 + maxItems: 3 power-domains: maxItems: 1 @@ -86,22 +84,9 @@ allOf: compatible: contains: enum: + - qcom,msm8998-qmp-ufs-phy - qcom,sa8775p-qmp-ufs-phy - qcom,sc7280-qmp-ufs-phy - - qcom,sm8450-qmp-ufs-phy - then: - properties: - clocks: - minItems: 3 - clock-names: - minItems: 3 - - - if: - properties: - compatible: - contains: - enum: - - qcom,msm8998-qmp-ufs-phy - qcom,sc8180x-qmp-ufs-phy - qcom,sc8280xp-qmp-ufs-phy - qcom,sdm845-qmp-ufs-phy @@ -112,14 +97,19 @@ allOf: - qcom,sm8150-qmp-ufs-phy - qcom,sm8250-qmp-ufs-phy - qcom,sm8350-qmp-ufs-phy + - qcom,sm8450-qmp-ufs-phy - qcom,sm8550-qmp-ufs-phy - qcom,sm8650-qmp-ufs-phy then: properties: clocks: - maxItems: 2 + minItems: 3 + maxItems: 3 clock-names: - maxItems: 2 + items: + - const: ref + - const: ref_aux + - const: qref - if: properties: @@ -130,22 +120,28 @@ allOf: then: properties: clocks: - maxItems: 1 + minItems: 2 + maxItems: 2 clock-names: - maxItems: 1 + items: + - const: ref + - const: qref additionalProperties: false examples: - | #include + #include ufs_mem_phy: phy@1d87000 { compatible = "qcom,sc8280xp-qmp-ufs-phy"; reg = <0x01d87000 0x1000>; - clocks = <&gcc GCC_UFS_REF_CLKREF_CLK>, <&gcc GCC_UFS_PHY_PHY_AUX_CLK>; - clock-names = "ref", "ref_aux"; + clocks = <&rpmhcc RPMH_CXO_CLK>, <&gcc GCC_UFS_PHY_PHY_AUX_CLK>, + <&gcc GCC_UFS_REF_CLKREF_CLK>; + + clock-names = "ref", "ref_aux", "qref"; power-domains = <&gcc UFS_PHY_GDSC>; diff --git a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml index 15d82c67f157b6..1e2d4ddc5391f1 100644 --- a/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml +++ b/Documentation/devicetree/bindings/phy/qcom,sc8280xp-qmp-usb3-uni-phy.yaml @@ -20,15 +20,12 @@ properties: - qcom,ipq8074-qmp-usb3-phy - qcom,ipq9574-qmp-usb3-phy - qcom,msm8996-qmp-usb3-phy - - qcom,msm8998-qmp-usb3-phy - - qcom,qcm2290-qmp-usb3-phy - qcom,sa8775p-qmp-usb3-uni-phy - qcom,sc8280xp-qmp-usb3-uni-phy - qcom,sdm845-qmp-usb3-uni-phy - qcom,sdx55-qmp-usb3-uni-phy - qcom,sdx65-qmp-usb3-uni-phy - qcom,sdx75-qmp-usb3-uni-phy - - qcom,sm6115-qmp-usb3-phy - qcom,sm8150-qmp-usb3-uni-phy - qcom,sm8250-qmp-usb3-uni-phy - qcom,sm8350-qmp-usb3-uni-phy @@ -93,7 +90,6 @@ allOf: - qcom,ipq8074-qmp-usb3-phy - qcom,ipq9574-qmp-usb3-phy - qcom,msm8996-qmp-usb3-phy - - qcom,msm8998-qmp-usb3-phy - qcom,sdx55-qmp-usb3-uni-phy - qcom,sdx65-qmp-usb3-uni-phy - qcom,sdx75-qmp-usb3-uni-phy @@ -108,24 +104,6 @@ allOf: - const: cfg_ahb - const: pipe - - if: - properties: - compatible: - contains: - enum: - - qcom,qcm2290-qmp-usb3-phy - - qcom,sm6115-qmp-usb3-phy - then: - properties: - clocks: - maxItems: 4 - clock-names: - items: - - const: cfg_ahb - - const: ref - - const: com_aux - - const: pipe - - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/phy/rockchip,rk3588-hdptx-phy.yaml b/Documentation/devicetree/bindings/phy/rockchip,rk3588-hdptx-phy.yaml new file mode 100644 index 00000000000000..54e822c715f3f4 --- /dev/null +++ b/Documentation/devicetree/bindings/phy/rockchip,rk3588-hdptx-phy.yaml @@ -0,0 +1,91 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/phy/rockchip,rk3588-hdptx-phy.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Rockchip SoC HDMI/eDP Transmitter Combo PHY + +maintainers: + - Cristian Ciocaltea + +properties: + compatible: + enum: + - rockchip,rk3588-hdptx-phy + + reg: + maxItems: 1 + + clocks: + items: + - description: Reference clock + - description: APB clock + + clock-names: + items: + - const: ref + - const: apb + + "#phy-cells": + const: 0 + + resets: + items: + - description: PHY reset line + - description: APB reset line + - description: INIT reset line + - description: CMN reset line + - description: LANE reset line + - description: ROPLL reset line + - description: LCPLL reset line + + reset-names: + items: + - const: phy + - const: apb + - const: init + - const: cmn + - const: lane + - const: ropll + - const: lcpll + + rockchip,grf: + $ref: /schemas/types.yaml#/definitions/phandle + description: Some PHY related data is accessed through GRF regs. + +required: + - compatible + - reg + - clocks + - clock-names + - "#phy-cells" + - resets + - reset-names + - rockchip,grf + +additionalProperties: false + +examples: + - | + #include + #include + + soc { + #address-cells = <2>; + #size-cells = <2>; + + phy@fed60000 { + compatible = "rockchip,rk3588-hdptx-phy"; + reg = <0x0 0xfed60000 0x0 0x2000>; + clocks = <&cru CLK_USB2PHY_HDPTXRXPHY_REF>, <&cru PCLK_HDPTX0>; + clock-names = "ref", "apb"; + #phy-cells = <0>; + resets = <&cru SRST_HDPTX0>, <&cru SRST_P_HDPTX0>, + <&cru SRST_HDPTX0_INIT>, <&cru SRST_HDPTX0_CMN>, + <&cru SRST_HDPTX0_LANE>, <&cru SRST_HDPTX0_ROPLL>, + <&cru SRST_HDPTX0_LCPLL>; + reset-names = "phy", "apb", "init", "cmn", "lane", "ropll", "lcpll"; + rockchip,grf = <&hdptxphy_grf>; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml index c7df4cd34197c2..d9e0b2c48e84ac 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-a1.yaml @@ -24,7 +24,7 @@ required: - compatible patternProperties: - "^bank@[0-9a-z]+$": + "^bank@[0-9a-f]+$": $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-gpio unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml index 0942ea60c6cd9b..108719bde0d05c 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-aobus.yaml @@ -21,7 +21,7 @@ required: - compatible patternProperties: - "^bank@[0-9a-z]+$": + "^bank@[0-9a-f]+$": $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-gpio unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml index e3c8bde3055940..dc277f2e2edf84 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson-pinctrl-g12a-periphs.yaml @@ -21,7 +21,7 @@ required: - compatible patternProperties: - "^bank@[0-9a-z]+$": + "^bank@[0-9a-f]+$": $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-gpio unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml index c1b03147e8eca8..add83c676327cc 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-aobus.yaml @@ -29,7 +29,7 @@ required: - compatible patternProperties: - "^bank@[0-9a-z]+$": + "^bank@[0-9a-f]+$": $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-gpio unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml index 4ec85b8248fa3e..412bbcc276f3b3 100644 --- a/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml +++ b/Documentation/devicetree/bindings/pinctrl/amlogic,meson8-pinctrl-cbus.yaml @@ -29,7 +29,7 @@ required: - compatible patternProperties: - "^bank@[0-9a-z]+$": + "^bank@[0-9a-f]+$": $ref: amlogic,meson-pinctrl-common.yaml#/$defs/meson-gpio unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml b/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml index bb61a30321a1c5..482acda88e7328 100644 --- a/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml +++ b/Documentation/devicetree/bindings/pinctrl/cirrus,madera.yaml @@ -93,7 +93,8 @@ properties: input-schmitt-disable: true - input-debounce: true + input-debounce: + maxItems: 1 output-low: true diff --git a/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml b/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml index 7f30ec2f1e5411..700ac86c26b69c 100644 --- a/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml +++ b/Documentation/devicetree/bindings/pinctrl/cypress,cy8c95x0.yaml @@ -45,7 +45,8 @@ properties: maxItems: 1 gpio-reserved-ranges: - maxItems: 1 + minItems: 1 + maxItems: 60 vdd-supply: description: @@ -85,6 +86,8 @@ patternProperties: bias-disable: true + input-enable: true + output-high: true output-low: true @@ -133,6 +136,23 @@ examples: interrupts = ; interrupt-controller; vdd-supply = <&p3v3>; - gpio-reserved-ranges = <5 1>; + gpio-reserved-ranges = <1 2>, <6 1>, <10 1>, <15 1>; + + pinctrl-0 = <&U62160_pins>, <&U62160_ipins>; + pinctrl-names = "default"; + + U62160_pins: cfg-pins { + pins = "gp03", "gp16", "gp20", "gp50", "gp51"; + function = "gpio"; + input-enable; + bias-pull-up; + }; + + U62160_ipins: icfg-pins { + pins = "gp04", "gp17", "gp21", "gp52", "gp53"; + function = "gpio"; + input-enable; + bias-pull-up; + }; }; }; diff --git a/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml index 3e8472898800c5..b55d9c3166598d 100644 --- a/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nuvoton,npcm845-pinctrl.yaml @@ -152,7 +152,6 @@ patternProperties: description: Debouncing periods in microseconds, one period per interrupt bank found in the controller - $ref: /schemas/types.yaml#/definitions/uint32-array minItems: 1 maxItems: 4 @@ -160,7 +159,6 @@ patternProperties: description: | 0: Low rate 1: High rate - $ref: /schemas/types.yaml#/definitions/uint32 enum: [0, 1] drive-strength: diff --git a/Documentation/devicetree/bindings/pinctrl/nuvoton,wpcm450-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/nuvoton,wpcm450-pinctrl.yaml index 7b7f840ffc4cf1..08442c880f0738 100644 --- a/Documentation/devicetree/bindings/pinctrl/nuvoton,wpcm450-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nuvoton,wpcm450-pinctrl.yaml @@ -103,7 +103,8 @@ patternProperties: items: pattern: "^gpio1?[0-9]{1,2}$" - input-debounce: true + input-debounce: + maxItems: 1 additionalProperties: false diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-aon.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-aon.yaml index f3deda9f7127fd..db8224dfba2c1b 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-aon.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-aon.yaml @@ -10,18 +10,21 @@ maintainers: - Thierry Reding - Jon Hunter -$ref: nvidia,tegra234-pinmux-common.yaml - properties: compatible: const: nvidia,tegra234-pinmux-aon + reg: + maxItems: 1 + patternProperties: "^pinmux(-[a-z0-9-]+)?$": type: object # pin groups additionalProperties: + $ref: nvidia,tegra234-pinmux-common.yaml + properties: nvidia,pins: items: diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-common.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-common.yaml index 4f9de78085e50f..8cf9e4c915ffa6 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-common.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux-common.yaml @@ -10,57 +10,43 @@ maintainers: - Thierry Reding - Jon Hunter -properties: - reg: - items: - - description: pinmux registers - -patternProperties: - "^pinmux(-[a-z0-9-]+)?$": - type: object - - # pin groups - additionalProperties: - $ref: nvidia,tegra-pinmux-common.yaml - # We would typically use unevaluatedProperties here but that has the - # downside that all the properties in the common bindings become valid - # for all chip generations. In this case, however, we want the per-SoC - # bindings to be able to override which of the common properties are - # allowed, since not all pinmux generations support the same sets of - # properties. This way, the common bindings define the format of the - # properties but the per-SoC bindings define which of them apply to a - # given chip. - additionalProperties: false - properties: - nvidia,function: - enum: [ gp, uartc, i2c8, spi2, i2c2, can1, can0, rsvd0, eth0, eth2, - eth1, dp, eth3, i2c4, i2c7, i2c9, eqos, pe2, pe1, pe0, pe3, - pe4, pe5, pe6, pe7, pe8, pe9, pe10, qspi0, qspi1, qpsi, - sdmmc1, sce, soc, gpio, hdmi, ufs0, spi3, spi1, uartb, uarte, - usb, extperiph2, extperiph1, i2c3, vi0, i2c5, uarta, uartd, - i2c1, i2s4, i2s6, aud, spi5, touch, uartj, rsvd1, wdt, tsc, - dmic3, led, vi0_alt, i2s5, nv, extperiph3, extperiph4, spi4, - ccla, i2s1, i2s2, i2s3, i2s8, rsvd2, dmic5, dca, displayb, - displaya, vi1, dcb, dmic1, dmic4, i2s7, dmic2, dspk0, rsvd3, - tsc_alt, istctrl, vi1_alt, dspk1, igpu ] +$ref: nvidia,tegra-pinmux-common.yaml - # out of the common properties, only these are allowed for Tegra234 - nvidia,pins: true - nvidia,pull: true - nvidia,tristate: true - nvidia,schmitt: true - nvidia,enable-input: true - nvidia,open-drain: true - nvidia,lock: true - nvidia,drive-type: true - nvidia,io-hv: true - - required: - - nvidia,pins +properties: + nvidia,function: + enum: [ gp, uartc, i2c8, spi2, i2c2, can1, can0, rsvd0, eth0, eth2, + eth1, dp, eth3, i2c4, i2c7, i2c9, eqos, pe2, pe1, pe0, pe3, + pe4, pe5, pe6, pe7, pe8, pe9, pe10, qspi0, qspi1, qpsi, + sdmmc1, sce, soc, gpio, hdmi, ufs0, spi3, spi1, uartb, uarte, + usb, extperiph2, extperiph1, i2c3, vi0, i2c5, uarta, uartd, + i2c1, i2s4, i2s6, aud, spi5, touch, uartj, rsvd1, wdt, tsc, + dmic3, led, vi0_alt, i2s5, nv, extperiph3, extperiph4, spi4, + ccla, i2s1, i2s2, i2s3, i2s8, rsvd2, dmic5, dca, displayb, + displaya, vi1, dcb, dmic1, dmic4, i2s7, dmic2, dspk0, rsvd3, + tsc_alt, istctrl, vi1_alt, dspk1, igpu ] + + # out of the common properties, only these are allowed for Tegra234 + nvidia,pins: true + nvidia,pull: true + nvidia,tristate: true + nvidia,schmitt: true + nvidia,enable-input: true + nvidia,open-drain: true + nvidia,lock: true + nvidia,drive-type: true + nvidia,io-hv: true required: - - compatible - - reg + - nvidia,pins + +# We would typically use unevaluatedProperties here but that has the +# downside that all the properties in the common bindings become valid +# for all chip generations. In this case, however, we want the per-SoC +# bindings to be able to override which of the common properties are +# allowed, since not all pinmux generations support the same sets of +# properties. This way, the common bindings define the format of the +# properties but the per-SoC bindings define which of them apply to a +# given chip. +additionalProperties: false -additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux.yaml b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux.yaml index 17b865ecfcdaa0..f5a3a881dec4f0 100644 --- a/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux.yaml +++ b/Documentation/devicetree/bindings/pinctrl/nvidia,tegra234-pinmux.yaml @@ -10,18 +10,21 @@ maintainers: - Thierry Reding - Jon Hunter -$ref: nvidia,tegra234-pinmux-common.yaml - properties: compatible: const: nvidia,tegra234-pinmux + reg: + maxItems: 1 + patternProperties: "^pinmux(-[a-z0-9-]+)?$": type: object # pin groups additionalProperties: + $ref: nvidia,tegra234-pinmux-common.yaml + properties: nvidia,pins: items: diff --git a/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml index be81ed22a036a3..d0af21a564b44f 100644 --- a/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml +++ b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml @@ -97,7 +97,7 @@ properties: description: disable schmitt-trigger mode input-debounce: - $ref: /schemas/types.yaml#/definitions/uint32 + $ref: /schemas/types.yaml#/definitions/uint32-array description: Takes the debounce time in usec as argument or 0 to disable debouncing diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml index 181cd1676c0a2a..5d84364d13589c 100644 --- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml +++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc.yaml @@ -46,6 +46,7 @@ properties: - renesas,pfc-r8a779a0 # R-Car V3U - renesas,pfc-r8a779f0 # R-Car S4-8 - renesas,pfc-r8a779g0 # R-Car V4H + - renesas,pfc-r8a779h0 # R-Car V4M - renesas,pfc-sh73a0 # SH-Mobile AG5 reg: diff --git a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/xlnx,pinctrl-zynq.yaml similarity index 98% rename from Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml rename to Documentation/devicetree/bindings/pinctrl/xlnx,pinctrl-zynq.yaml index d2676f92ef5bb8..de6c10ba36c4ec 100644 --- a/Documentation/devicetree/bindings/pinctrl/xlnx,zynq-pinctrl.yaml +++ b/Documentation/devicetree/bindings/pinctrl/xlnx,pinctrl-zynq.yaml @@ -1,7 +1,7 @@ # SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- -$id: http://devicetree.org/schemas/pinctrl/xlnx,zynq-pinctrl.yaml# +$id: http://devicetree.org/schemas/pinctrl/xlnx,pinctrl-zynq.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Xilinx Zynq Pinctrl @@ -28,7 +28,7 @@ description: | properties: compatible: - const: xlnx,zynq-pinctrl + const: xlnx,pinctrl-zynq reg: description: Specifies the base address and size of the SLCR space. @@ -181,7 +181,7 @@ examples: - | #include pinctrl0: pinctrl@700 { - compatible = "xlnx,zynq-pinctrl"; + compatible = "xlnx,pinctrl-zynq"; reg = <0x700 0x200>; syscon = <&slcr>; diff --git a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml index 2ff246cf8b81dd..929b7ef9c1bcda 100644 --- a/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml +++ b/Documentation/devicetree/bindings/power/qcom,rpmpd.yaml @@ -24,6 +24,8 @@ properties: - qcom,msm8917-rpmpd - qcom,msm8939-rpmpd - qcom,msm8953-rpmpd + - qcom,msm8974-rpmpd + - qcom,msm8974pro-pma8084-rpmpd - qcom,msm8976-rpmpd - qcom,msm8994-rpmpd - qcom,msm8996-rpmpd diff --git a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml index 0720b54881c2c8..e76fb273490ff5 100644 --- a/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml +++ b/Documentation/devicetree/bindings/power/renesas,rcar-sysc.yaml @@ -45,6 +45,7 @@ properties: - renesas,r8a779a0-sysc # R-Car V3U - renesas,r8a779f0-sysc # R-Car S4-8 - renesas,r8a779g0-sysc # R-Car V4H + - renesas,r8a779h0-sysc # R-Car V4M reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml new file mode 100644 index 00000000000000..0e92868a2b689c --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/atmel,hlcdc-pwm.yaml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/atmel,hlcdc-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel's HLCDC's PWM controller + +maintainers: + - Nicolas Ferre + - Alexandre Belloni + - Claudiu Beznea + +description: + The LCDC integrates a Pulse Width Modulation (PWM) Controller. This block + generates the LCD contrast control signal (LCD_PWM) that controls the + display's contrast by software. LCDC_PWM is an 8-bit PWM signal that can be + converted to an analog voltage with a simple passive filter. LCD display + panels have different backlight specifications in terms of minimum/maximum + values for PWM frequency. If the LCDC PWM frequency range does not match the + LCD display panel, it is possible to use the standalone PWM Controller to + drive the backlight. + +properties: + compatible: + const: atmel,hlcdc-pwm + + "#pwm-cells": + const: 3 + +required: + - compatible + - "#pwm-cells" + +additionalProperties: false diff --git a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt b/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt deleted file mode 100644 index afa501bf7f94b5..00000000000000 --- a/Documentation/devicetree/bindings/pwm/atmel-hlcdc-pwm.txt +++ /dev/null @@ -1,29 +0,0 @@ -Device-Tree bindings for Atmel's HLCDC (High-end LCD Controller) PWM driver - -The Atmel HLCDC PWM is subdevice of the HLCDC MFD device. -See ../mfd/atmel-hlcdc.txt for more details. - -Required properties: - - compatible: value should be one of the following: - "atmel,hlcdc-pwm" - - pinctr-names: the pin control state names. Should contain "default". - - pinctrl-0: should contain the pinctrl states described by pinctrl - default. - - #pwm-cells: should be set to 3. This PWM chip use the default 3 cells - bindings defined in pwm.yaml in this directory. - -Example: - - hlcdc: hlcdc@f0030000 { - compatible = "atmel,sama5d3-hlcdc"; - reg = <0xf0030000 0x2000>; - clocks = <&lcdc_clk>, <&lcdck>, <&clk32k>; - clock-names = "periph_clk","sys_clk", "slow_clk"; - - hlcdc_pwm: hlcdc-pwm { - compatible = "atmel,hlcdc-pwm"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_lcd_pwm>; - #pwm-cells = <3>; - }; - }; diff --git a/Documentation/devicetree/bindings/pwm/marvell,pxa-pwm.yaml b/Documentation/devicetree/bindings/pwm/marvell,pxa-pwm.yaml new file mode 100644 index 00000000000000..ba6325575ea040 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/marvell,pxa-pwm.yaml @@ -0,0 +1,51 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/marvell,pxa-pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Marvell PXA PWM + +maintainers: + - Duje Mihanović + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + enum: + - marvell,pxa250-pwm + - marvell,pxa270-pwm + - marvell,pxa168-pwm + - marvell,pxa910-pwm + + reg: + # Length should be 0x10 + maxItems: 1 + + "#pwm-cells": + # Used for specifying the period length in nanoseconds + const: 1 + + clocks: + maxItems: 1 + +required: + - compatible + - reg + - "#pwm-cells" + - clocks + +additionalProperties: false + +examples: + - | + #include + + pwm0: pwm@40b00000 { + compatible = "marvell,pxa250-pwm"; + reg = <0x40b00000 0x10>; + #pwm-cells = <1>; + clocks = <&clks CLK_PWM0>; + }; diff --git a/Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml b/Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml index 0fbe8a6469eb22..a5c30880161933 100644 --- a/Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml +++ b/Documentation/devicetree/bindings/pwm/mediatek,mt2712-pwm.yaml @@ -24,6 +24,7 @@ properties: - mediatek,mt7629-pwm - mediatek,mt7981-pwm - mediatek,mt7986-pwm + - mediatek,mt7988-pwm - mediatek,mt8183-pwm - mediatek,mt8365-pwm - mediatek,mt8516-pwm diff --git a/Documentation/devicetree/bindings/pwm/opencores,pwm.yaml b/Documentation/devicetree/bindings/pwm/opencores,pwm.yaml new file mode 100644 index 00000000000000..0b85dd861dfdb7 --- /dev/null +++ b/Documentation/devicetree/bindings/pwm/opencores,pwm.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/pwm/opencores,pwm.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: OpenCores PWM controller + +maintainers: + - William Qiu + +description: + The OpenCores PTC ip core contains a PWM controller. When operating in PWM + mode, the PTC core generates binary signal with user-programmable low and + high periods. All PTC counters and registers are 32-bit. + +allOf: + - $ref: pwm.yaml# + +properties: + compatible: + items: + - enum: + - starfive,jh7100-pwm + - starfive,jh7110-pwm + - const: opencores,pwm-v1 + + reg: + maxItems: 1 + + clocks: + maxItems: 1 + + resets: + maxItems: 1 + + "#pwm-cells": + const: 3 + +required: + - compatible + - reg + - clocks + +additionalProperties: false + +examples: + - | + pwm@12490000 { + compatible = "starfive,jh7110-pwm", "opencores,pwm-v1"; + reg = <0x12490000 0x10000>; + clocks = <&clkgen 181>; + resets = <&rstgen 109>; + #pwm-cells = <3>; + }; diff --git a/Documentation/devicetree/bindings/pwm/pxa-pwm.txt b/Documentation/devicetree/bindings/pwm/pxa-pwm.txt deleted file mode 100644 index 5ae9f1e3c33896..00000000000000 --- a/Documentation/devicetree/bindings/pwm/pxa-pwm.txt +++ /dev/null @@ -1,30 +0,0 @@ -Marvell PWM controller - -Required properties: -- compatible: should be one or more of: - - "marvell,pxa250-pwm" - - "marvell,pxa270-pwm" - - "marvell,pxa168-pwm" - - "marvell,pxa910-pwm" -- reg: Physical base address and length of the registers used by the PWM channel - Note that one device instance must be created for each PWM that is used, so the - length covers only the register window for one PWM output, not that of the - entire PWM controller. Currently length is 0x10 for all supported devices. -- #pwm-cells: Should be 1. This cell is used to specify the period in - nanoseconds. - -Example PWM device node: - -pwm0: pwm@40b00000 { - compatible = "marvell,pxa250-pwm"; - reg = <0x40b00000 0x10>; - #pwm-cells = <1>; -}; - -Example PWM client node: - -backlight { - compatible = "pwm-backlight"; - pwms = <&pwm0 5000000>; - ... -} diff --git a/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt b/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt deleted file mode 100644 index 451cc4e86b0189..00000000000000 --- a/Documentation/devicetree/bindings/regulator/mcp16502-regulator.txt +++ /dev/null @@ -1,144 +0,0 @@ -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; this - property is optional; -- 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. - -Regulators 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/microchip,mcp16502.yaml b/Documentation/devicetree/bindings/regulator/microchip,mcp16502.yaml new file mode 100644 index 00000000000000..1aca3646789eff --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/microchip,mcp16502.yaml @@ -0,0 +1,180 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/microchip,mcp16502.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: MCP16502 - High-Performance PMIC + +maintainers: + - Andrei Simion + +description: + The MCP16502 is an optimally integrated PMIC compatible + with Microchip's eMPUs(Embedded Microprocessor Units), + requiring Dynamic Voltage Scaling (DVS) with the use + of High-Performance mode (HPM). + +properties: + compatible: + const: microchip,mcp16502 + + lpm-gpios: + maxItems: 1 + description: GPIO for LPM pin. + Note that this GPIO must remain high during + suspend-to-ram, keeping the PMIC into HIBERNATE mode. + + reg: + maxItems: 1 + + regulators: + type: object + additionalProperties: false + description: List of regulators and its properties. + + patternProperties: + "^(VDD_(IO|CORE|DDR|OTHER)|LDO[1-2])$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + + properties: + regulator-initial-mode: + enum: [2, 4] + default: 2 + description: Initial operating mode + + regulator-allowed-modes: + items: + enum: [2, 4] + description: Supported modes + 2 - FPWM higher precision, higher consumption + 4 - AutoPFM lower precision, lower consumption + +required: + - compatible + - reg + - regulators + +additionalProperties: false + +examples: + - | + i2c { + #address-cells = <1>; + #size-cells = <0>; + + pmic@5b { + compatible = "microchip,mcp16502"; + reg = <0x5b>; + + regulators { + VDD_IO { + regulator-name = "VDD_IO"; + regulator-min-microvolt = <3300000>; + regulator-max-microvolt = <3300000>; + 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 = <1350000>; + regulator-max-microvolt = <1350000>; + 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 = <1150000>; + regulator-max-microvolt = <1150000>; + 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 = <1050000>; + regulator-max-microvolt = <1250000>; + 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 = <1800000>; + regulator-max-microvolt = <1800000>; + 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/qcom,usb-vbus-regulator.yaml b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml index 534f87e9871630..b828a69ccb8439 100644 --- a/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/qcom,usb-vbus-regulator.yaml @@ -19,8 +19,14 @@ allOf: properties: compatible: - enum: - - qcom,pm8150b-vbus-reg + oneOf: + - enum: + - qcom,pm8150b-vbus-reg + - items: + - enum: + - qcom,pm6150-vbus-reg + - qcom,pmi632-vbus-reg + - const: qcom,pm8150b-vbus-reg reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/regulator/ti,tps65132.yaml b/Documentation/devicetree/bindings/regulator/ti,tps65132.yaml new file mode 100644 index 00000000000000..6a6d1a3d6fa7e7 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/ti,tps65132.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/ti,tps65132.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: TI TPS65132 Dual Output Power Regulators + +maintainers: + - devicetree@vger.kernel.org + +description: | + The TPS65132 is designed to supply positive/negative driven applications. + + Datasheet is available at: + https://www.ti.com/lit/gpn/tps65132 + +properties: + compatible: + enum: + - ti,tps65132 + + reg: + maxItems: 1 + +patternProperties: + "^out[pn]$": + type: object + $ref: regulator.yaml# + unevaluatedProperties: false + description: + Properties for single regulator. + + properties: + enable-gpios: + maxItems: 1 + description: + GPIO specifier to enable the GPIO control (on/off) for regulator. + + active-discharge-gpios: + maxItems: 1 + description: + GPIO specifier to actively discharge the delay mechanism. + + ti,active-discharge-time-us: + description: Regulator active discharge time in microseconds. + + dependencies: + active-discharge-gpios: [ 'ti,active-discharge-time-us' ] + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include + + i2c { + #address-cells = <1>; + #size-cells = <0>; + + regulator@3e { + compatible = "ti,tps65132"; + reg = <0x3e>; + + outp { + regulator-name = "outp"; + regulator-boot-on; + regulator-always-on; + enable-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>; + }; + + outn { + regulator-name = "outn"; + regulator-boot-on; + regulator-always-on; + regulator-active-discharge = <0>; + enable-gpios = <&gpio 40 GPIO_ACTIVE_HIGH>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt b/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt deleted file mode 100644 index 3a3505520c692b..00000000000000 --- a/Documentation/devicetree/bindings/regulator/tps65132-regulator.txt +++ /dev/null @@ -1,46 +0,0 @@ -TPS65132 regulators - -Required properties: -- compatible: "ti,tps65132" -- reg: I2C slave address - -Optional Subnode: -Device supports two regulators OUTP and OUTN. A sub node within the - device node describe the properties of these regulators. The sub-node - names must be as follows: - -For regulator outp, the sub node name should be "outp". - -For regulator outn, the sub node name should be "outn". - --enable-gpios:(active high, output) Regulators are controlled by the input pins. - If it is connected to GPIO through host system then provide the - gpio number as per gpio.txt. --active-discharge-gpios: (active high, output) Some configurations use delay mechanisms - on the enable pin, to keep the regulator enabled for some time after - the enable signal goes low. This GPIO is used to actively discharge - the delay mechanism. Requires specification of ti,active-discharge-time-us --ti,active-discharge-time-us: how long the active discharge gpio should be - asserted for during active discharge, in microseconds. - -Each regulator is defined using the standard binding for regulators. - -Example: - - tps65132@3e { - compatible = "ti,tps65132"; - reg = <0x3e>; - - outp { - regulator-name = "outp"; - regulator-boot-on; - regulator-always-on; - enable-gpios = <&gpio 23 0>; - }; - - outn { - regulator-name = "outn"; - regulator-boot-on; - regulator-always-on; - regulator-active-discharge = <0>; - enable-gpios = <&gpio 40 0>; - }; - }; diff --git a/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml b/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml index 58120829fb06f5..5f63b6b9a8f5ac 100644 --- a/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml +++ b/Documentation/devicetree/bindings/remoteproc/qcom,sm8550-pas.yaml @@ -19,6 +19,9 @@ properties: - qcom,sm8550-adsp-pas - qcom,sm8550-cdsp-pas - qcom,sm8550-mpss-pas + - qcom,sm8650-adsp-pas + - qcom,sm8650-cdsp-pas + - qcom,sm8650-mpss-pas reg: maxItems: 1 @@ -49,6 +52,8 @@ properties: - description: Memory region for main Firmware authentication - description: Memory region for Devicetree Firmware authentication - description: DSM Memory region + - description: DSM Memory region 2 + - description: Memory region for Qlink Logging required: - compatible @@ -63,6 +68,7 @@ allOf: enum: - qcom,sm8550-adsp-pas - qcom,sm8550-cdsp-pas + - qcom,sm8650-adsp-pas then: properties: interrupts: @@ -71,7 +77,26 @@ allOf: maxItems: 5 memory-region: maxItems: 2 - else: + - if: + properties: + compatible: + enum: + - qcom,sm8650-cdsp-pas + then: + properties: + interrupts: + maxItems: 5 + interrupt-names: + maxItems: 5 + memory-region: + minItems: 3 + maxItems: 3 + - if: + properties: + compatible: + enum: + - qcom,sm8550-mpss-pas + then: properties: interrupts: minItems: 6 @@ -79,12 +104,28 @@ allOf: minItems: 6 memory-region: minItems: 3 + maxItems: 3 + - if: + properties: + compatible: + enum: + - qcom,sm8650-mpss-pas + then: + properties: + interrupts: + minItems: 6 + interrupt-names: + minItems: 6 + memory-region: + minItems: 5 + maxItems: 5 - if: properties: compatible: enum: - qcom,sm8550-adsp-pas + - qcom,sm8650-adsp-pas then: properties: power-domains: @@ -101,6 +142,7 @@ allOf: compatible: enum: - qcom,sm8550-mpss-pas + - qcom,sm8650-mpss-pas then: properties: power-domains: @@ -116,6 +158,7 @@ allOf: compatible: enum: - qcom,sm8550-cdsp-pas + - qcom,sm8650-cdsp-pas then: properties: power-domains: diff --git a/Documentation/devicetree/bindings/reset/renesas,rst.yaml b/Documentation/devicetree/bindings/reset/renesas,rst.yaml index e7e4872477517b..58b4a45d338006 100644 --- a/Documentation/devicetree/bindings/reset/renesas,rst.yaml +++ b/Documentation/devicetree/bindings/reset/renesas,rst.yaml @@ -50,6 +50,7 @@ properties: - renesas,r8a779a0-rst # R-Car V3U - renesas,r8a779f0-rst # R-Car S4-8 - renesas,r8a779g0-rst # R-Car V4H + - renesas,r8a779h0-rst # R-Car V4M reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml index 49db6680142970..1f1b42dde94d50 100644 --- a/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml +++ b/Documentation/devicetree/bindings/reset/xlnx,zynqmp-reset.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Zynq UltraScale+ MPSoC and Versal reset maintainers: - - Piyush Mehta + - Mubin Sayyed + - Radhey Shyam Pandey description: | The Zynq UltraScale+ MPSoC and Versal has several different resets. diff --git a/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml index a16c355dcd1132..fcf52d2cac9ec0 100644 --- a/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml +++ b/Documentation/devicetree/bindings/rtc/sa1100-rtc.yaml @@ -12,7 +12,7 @@ allOf: maintainers: - Alessandro Zummo - Alexandre Belloni - - Rob Herring + - Rob Herring properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/cdns,uart.yaml b/Documentation/devicetree/bindings/serial/cdns,uart.yaml index e35ad1109efc8b..2129247d7c816d 100644 --- a/Documentation/devicetree/bindings/serial/cdns,uart.yaml +++ b/Documentation/devicetree/bindings/serial/cdns,uart.yaml @@ -55,6 +55,7 @@ required: allOf: - $ref: serial.yaml# + - $ref: rs485.yaml# - if: properties: compatible: diff --git a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml index 3a5b59f5d3e35d..3f9ace89dee902 100644 --- a/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml +++ b/Documentation/devicetree/bindings/serial/fsl-lpuart.yaml @@ -30,6 +30,7 @@ properties: - items: - enum: - fsl,imx93-lpuart + - fsl,imx95-lpuart - const: fsl,imx8ulp-lpuart - const: fsl,imx7ulp-lpuart - items: diff --git a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml index 2046e2dc0a3d19..9480ed30915c9c 100644 --- a/Documentation/devicetree/bindings/serial/renesas,hscif.yaml +++ b/Documentation/devicetree/bindings/serial/renesas,hscif.yaml @@ -59,6 +59,7 @@ properties: - renesas,hscif-r8a779a0 # R-Car V3U - renesas,hscif-r8a779f0 # R-Car S4-8 - renesas,hscif-r8a779g0 # R-Car V4H + - renesas,hscif-r8a779h0 # R-Car V4M - const: renesas,rcar-gen4-hscif # R-Car Gen4 - const: renesas,hscif # generic HSCIF compatible UART diff --git a/Documentation/devicetree/bindings/serial/samsung_uart.yaml b/Documentation/devicetree/bindings/serial/samsung_uart.yaml index 133259ed3a34c5..0f0131026911cd 100644 --- a/Documentation/devicetree/bindings/serial/samsung_uart.yaml +++ b/Documentation/devicetree/bindings/serial/samsung_uart.yaml @@ -143,6 +143,8 @@ allOf: then: required: - samsung,uart-fifosize + properties: + reg-io-width: false unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/serial/serial.yaml b/Documentation/devicetree/bindings/serial/serial.yaml index 65804ca274ae75..ffc9198ae21469 100644 --- a/Documentation/devicetree/bindings/serial/serial.yaml +++ b/Documentation/devicetree/bindings/serial/serial.yaml @@ -88,7 +88,7 @@ properties: TX FIFO threshold configuration (in bytes). patternProperties: - "^(bluetooth|bluetooth-gnss|gnss|gps|mcu)$": + "^(bluetooth|bluetooth-gnss|gnss|gps|mcu|onewire)$": if: type: object then: diff --git a/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml index 1be4ce2a45e8e6..bd1cdaa4f54b07 100644 --- a/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml +++ b/Documentation/devicetree/bindings/soc/imx/fsl,imx8mp-hdmi-blk-ctrl.yaml @@ -27,8 +27,8 @@ properties: const: 1 power-domains: - minItems: 8 - maxItems: 8 + minItems: 10 + maxItems: 10 power-domain-names: items: @@ -40,10 +40,12 @@ properties: - const: trng - const: hdmi-tx - const: hdmi-tx-phy + - const: hdcp + - const: hrv clocks: - minItems: 4 - maxItems: 4 + minItems: 5 + maxItems: 5 clock-names: items: @@ -51,6 +53,7 @@ properties: - const: axi - const: ref_266m - const: ref_24m + - const: fdcc interconnects: maxItems: 3 @@ -82,12 +85,15 @@ examples: clocks = <&clk IMX8MP_CLK_HDMI_APB>, <&clk IMX8MP_CLK_HDMI_ROOT>, <&clk IMX8MP_CLK_HDMI_REF_266M>, - <&clk IMX8MP_CLK_HDMI_24M>; - clock-names = "apb", "axi", "ref_266m", "ref_24m"; + <&clk IMX8MP_CLK_HDMI_24M>, + <&clk IMX8MP_CLK_HDMI_FDCC_TST>; + clock-names = "apb", "axi", "ref_266m", "ref_24m", "fdcc"; power-domains = <&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>, <&pgc_hdmimix>, - <&pgc_hdmimix>, <&pgc_hdmi_phy>; + <&pgc_hdmimix>, <&pgc_hdmi_phy>, + <&pgc_hdmimix>, <&pgc_hdmimix>; power-domain-names = "bus", "irqsteer", "lcdif", "pai", "pvi", "trng", - "hdmi-tx", "hdmi-tx-phy"; + "hdmi-tx", "hdmi-tx-phy", + "hdcp", "hrv"; #power-domain-cells = <1>; }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pbs.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pbs.yaml new file mode 100644 index 00000000000000..b502ca72266a78 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pbs.yaml @@ -0,0 +1,46 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/qcom/qcom,pbs.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm Technologies, Inc. Programmable Boot Sequencer + +maintainers: + - Anjelique Melendez + +description: | + The Qualcomm Technologies, Inc. Programmable Boot Sequencer (PBS) + supports triggering power up and power down sequences for clients + upon request. + +properties: + compatible: + items: + - enum: + - qcom,pmi632-pbs + - const: qcom,pbs + + reg: + maxItems: 1 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + #include + + pmic@0 { + reg = <0x0 SPMI_USID>; + #address-cells = <1>; + #size-cells = <0>; + + pbs@7400 { + compatible = "qcom,pmi632-pbs", "qcom,pbs"; + reg = <0x7400>; + }; + }; diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml index 61df97ffe1e409..4310bae6c58ef3 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,pmic-glink.yaml @@ -23,6 +23,7 @@ properties: oneOf: - items: - enum: + - qcom,qcm6490-pmic-glink - qcom,sc8180x-pmic-glink - qcom,sc8280xp-pmic-glink - qcom,sm8350-pmic-glink @@ -32,6 +33,7 @@ properties: - items: - enum: - qcom,sm8650-pmic-glink + - qcom,x1e80100-pmic-glink - const: qcom,sm8550-pmic-glink - const: qcom,pmic-glink @@ -65,6 +67,7 @@ allOf: enum: - qcom,sm8450-pmic-glink - qcom,sm8550-pmic-glink + - qcom,x1e80100-pmic-glink then: properties: orientation-gpios: false diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,rpm-master-stats.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,rpm-master-stats.yaml index 031800985b5ebf..9410404f87f1af 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,rpm-master-stats.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,rpm-master-stats.yaml @@ -35,6 +35,8 @@ properties: description: Phandle to an RPM MSG RAM slice containing the master stats minItems: 1 maxItems: 5 + items: + maxItems: 1 qcom,master-names: $ref: /schemas/types.yaml#/definitions/string-array diff --git a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml b/Documentation/devicetree/bindings/soc/qcom/qcom,saw2.yaml similarity index 53% rename from Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml rename to Documentation/devicetree/bindings/soc/qcom/qcom,saw2.yaml index 20c8cd38ff0d3e..ca4bce81727381 100644 --- a/Documentation/devicetree/bindings/soc/qcom/qcom,spm.yaml +++ b/Documentation/devicetree/bindings/soc/qcom/qcom,saw2.yaml @@ -1,23 +1,33 @@ # SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) %YAML 1.2 --- -$id: http://devicetree.org/schemas/soc/qcom/qcom,spm.yaml# +$id: http://devicetree.org/schemas/soc/qcom/qcom,saw2.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Qualcomm Subsystem Power Manager +title: Qualcomm Subsystem Power Manager / SPM AVS Wrapper 2 (SAW2) maintainers: - Andy Gross - Bjorn Andersson description: | - This binding describes the Qualcomm Subsystem Power Manager, used to control - the peripheral logic surrounding the application cores in Qualcomm platforms. + The Qualcomm Subsystem Power Manager is used to control the peripheral logic + surrounding the application cores in Qualcomm platforms. + + The SAW2 is a wrapper around the Subsystem Power Manager (SPM) and the + Adaptive Voltage Scaling (AVS) hardware. The SPM is a programmable + power-controller that transitions a piece of hardware (like a processor or + subsystem) into and out of low power modes via a direct connection to + the PMIC. It can also be wired up to interact with other processors in the + system, notifying them when a low power state is entered or exited. properties: compatible: items: - enum: + - qcom,ipq4019-saw2-cpu + - qcom,ipq4019-saw2-l2 + - qcom,ipq8064-saw2-cpu - qcom,sdm660-gold-saw2-v4.1-l2 - qcom,sdm660-silver-saw2-v4.1-l2 - qcom,msm8998-gold-saw2-v4.1-l2 @@ -26,16 +36,27 @@ properties: - qcom,msm8916-saw2-v3.0-cpu - qcom,msm8939-saw2-v3.0-cpu - qcom,msm8226-saw2-v2.1-cpu + - qcom,msm8226-saw2-v2.1-l2 + - qcom,msm8960-saw2-cpu - qcom,msm8974-saw2-v2.1-cpu + - qcom,msm8974-saw2-v2.1-l2 - qcom,msm8976-gold-saw2-v2.3-l2 - qcom,msm8976-silver-saw2-v2.3-l2 - qcom,apq8084-saw2-v2.1-cpu + - qcom,apq8084-saw2-v2.1-l2 - qcom,apq8064-saw2-v1.1-cpu - const: qcom,saw2 reg: - description: Base address and size of the SPM register region - maxItems: 1 + items: + - description: Base address and size of the SPM register region + - description: Base address and size of the alias register region + minItems: 1 + + regulator: + $ref: /schemas/regulator/regulator.yaml# + description: Indicates that this SPM device acts as a regulator device + device for the core (CPU or Cache) the SPM is attached to. required: - compatible @@ -82,4 +103,17 @@ examples: reg = <0x17912000 0x1000>; }; + - | + /* + * Example 3: SAW2 with the bundled regulator definition. + */ + power-manager@2089000 { + compatible = "qcom,apq8064-saw2-v1.1-cpu", "qcom,saw2"; + reg = <0x02089000 0x1000>, <0x02009000 0x1000>; + + regulator { + regulator-min-microvolt = <850000>; + regulator-max-microvolt = <1300000>; + }; + }; ... diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml new file mode 100644 index 00000000000000..a5fcd471983df0 --- /dev/null +++ b/Documentation/devicetree/bindings/soc/renesas/renesas-soc.yaml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/soc/renesas/renesas-soc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Renesas SoC compatibles naming convention + +maintainers: + - Geert Uytterhoeven + - Niklas Söderlund + +description: | + Guidelines for new compatibles for SoC blocks/components. + When adding new compatibles in new bindings, use the format:: + renesas,SoC-IP + + For example:: + renesas,r8a77965-csi2 + + When adding new compatibles to existing bindings, use the format in the + existing binding, even if it contradicts the above. + +select: + properties: + compatible: + contains: + pattern: "^renesas,.+-.+$" + required: + - compatible + +properties: + compatible: + minItems: 1 + maxItems: 4 + items: + anyOf: + # Preferred naming style for compatibles of SoC components + - pattern: "^renesas,(emev2|r(7s|8a|9a)[a-z0-9]+|rcar|rmobile|rz[a-z0-9]*|sh(7[a-z0-9]+)?|mobile)-[a-z0-9-]+$" + - pattern: "^renesas,(condor|falcon|gr-peach|salvator|sk-rz|smar(c(2)?)?|spider|white-hawk)(.*)?$" + + # Legacy compatibles + # + # New compatibles are not allowed. + - pattern: "^renesas,(can|cpg|dmac|du|(g)?ether(avb)?|gpio|hscif|(r)?i[i2]c|imr|intc|ipmmu|irqc|jpu|mmcif|msiof|mtu2|pci(e)?|pfc|pwm|[rq]spi|rcar_sound|sata|scif[ab]*|sdhi|thermal|tmu|tpu|usb(2|hs)?|vin|xhci)-[a-z0-9-]+$" + - pattern: "^renesas,(d|s)?bsc(3)?-(r8a73a4|r8a7740|sh73a0)$" + - pattern: "^renesas,em-(gio|sti|uart)$" + - pattern: "^renesas,fsi2-(r8a7740|sh73a0)$" + - pattern: "^renesas,hspi-r8a777[89]$" + - pattern: "^renesas,sysc-(r8a73a4|r8a7740|rmobile|sh73a0)$" + - enum: + - renesas,imr-lx4 + - renesas,mtu2-r7s72100 + + # None SoC component compatibles + # + # Compatibles with the Renesas vendor prefix that do not relate to any SoC + # component are OK. New compatibles are allowed. + - enum: + - renesas,smp-sram + + # Do not fail compatibles not matching the select pattern + # + # Some SoC components in addition to a Renesas compatible list + # compatibles not related to Renesas. The select pattern for this + # schema hits all compatibles that have at lest one Renesas compatible + # and try to validate all values in that compatible array, allow all + # that don't match the schema select pattern. For example, + # + # compatible = "renesas,r9a07g044-mali", "arm,mali-bifrost"; + - pattern: "^(?!renesas,.+-.+).+$" + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml index 16ca3ff7b1aea1..c1ce4da2dc325e 100644 --- a/Documentation/devicetree/bindings/soc/renesas/renesas.yaml +++ b/Documentation/devicetree/bindings/soc/renesas/renesas.yaml @@ -348,12 +348,25 @@ properties: - renesas,white-hawk-cpu # White Hawk CPU board (RTP8A779G0ASKB0FC0SA000) - const: renesas,r8a779g0 + - description: R-Car V4H (R8A779G2) + items: + - enum: + - renesas,white-hawk-single # White Hawk Single board (RTP8A779G2ASKB0F10SA001) + - const: renesas,r8a779g2 + - const: renesas,r8a779g0 + - items: - enum: - renesas,white-hawk-breakout # White Hawk BreakOut board (RTP8A779G0ASKB0SB0SA000) - const: renesas,white-hawk-cpu - const: renesas,r8a779g0 + - description: R-Car V4M (R8A779H0) + items: + - enum: + - renesas,gray-hawk-single # Gray Hawk Single board (RTP8A779H0ASKB0F10S) + - const: renesas,r8a779h0 + - description: R-Car H3e (R8A779M0) items: - enum: @@ -475,12 +488,6 @@ properties: - renesas,r9a07g054l2 # Dual Cortex-A55 RZ/V2L - const: renesas,r9a07g054 - - description: RZ/V2M (R9A09G011) - items: - - enum: - - renesas,rzv2mevk2 # RZ/V2M Eval Board v2.0 - - const: renesas,r9a09g011 - - description: RZ/G3S (R9A08G045) items: - enum: @@ -500,6 +507,12 @@ properties: - const: renesas,r9a08g045s33 # PCIe support - const: renesas,r9a08g045 + - description: RZ/V2M (R9A09G011) + items: + - enum: + - renesas,rzv2mevk2 # RZ/V2M Eval Board v2.0 + - const: renesas,r9a09g011 + additionalProperties: true ... diff --git a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml index 9793ea6f0fe65d..0b87c266760c6e 100644 --- a/Documentation/devicetree/bindings/soc/rockchip/grf.yaml +++ b/Documentation/devicetree/bindings/soc/rockchip/grf.yaml @@ -22,12 +22,15 @@ properties: - rockchip,rk3568-usb2phy-grf - rockchip,rk3588-bigcore0-grf - rockchip,rk3588-bigcore1-grf + - rockchip,rk3588-hdptxphy-grf - rockchip,rk3588-ioc - rockchip,rk3588-php-grf - rockchip,rk3588-pipe-phy-grf - rockchip,rk3588-sys-grf - rockchip,rk3588-pcie3-phy-grf - rockchip,rk3588-pcie3-pipe-grf + - rockchip,rk3588-usb-grf + - rockchip,rk3588-usbdpphy-grf - rockchip,rk3588-vo-grf - rockchip,rk3588-vop-grf - rockchip,rv1108-usbgrf @@ -66,6 +69,9 @@ properties: reg: maxItems: 1 + clocks: + maxItems: 1 + "#address-cells": const: 1 @@ -248,6 +254,22 @@ allOf: unevaluatedProperties: false + - if: + properties: + compatible: + contains: + enum: + - rockchip,rk3588-vo-grf + + then: + required: + - clocks + + else: + properties: + clocks: false + + examples: - | #include diff --git a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml index 1794e3799f2110..c0c6ce8fc7863e 100644 --- a/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml +++ b/Documentation/devicetree/bindings/soc/samsung/samsung,exynos-sysreg.yaml @@ -72,6 +72,8 @@ allOf: compatible: contains: enum: + - google,gs101-peric0-sysreg + - google,gs101-peric1-sysreg - samsung,exynos850-cmgp-sysreg - samsung,exynos850-peri-sysreg - samsung,exynos850-sysreg diff --git a/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml b/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml index d4c0fe1fe43580..131aba5ed9f48f 100644 --- a/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml +++ b/Documentation/devicetree/bindings/soc/xilinx/xilinx.yaml @@ -117,20 +117,70 @@ properties: - const: xlnx,zynqmp - description: Xilinx Kria SOMs + minItems: 3 items: - - const: xlnx,zynqmp-sm-k26-rev1 - - const: xlnx,zynqmp-sm-k26-revB - - const: xlnx,zynqmp-sm-k26-revA - - const: xlnx,zynqmp-sm-k26 - - const: xlnx,zynqmp + enum: + - xlnx,zynqmp-sm-k26-rev2 + - xlnx,zynqmp-sm-k26-rev1 + - xlnx,zynqmp-sm-k26-revB + - xlnx,zynqmp-sm-k26-revA + - xlnx,zynqmp-sm-k26 + - xlnx,zynqmp + allOf: + - contains: + const: xlnx,zynqmp + - contains: + const: xlnx,zynqmp-sm-k26 - description: Xilinx Kria SOMs (starter) + minItems: 3 items: - - const: xlnx,zynqmp-smk-k26-rev1 - - const: xlnx,zynqmp-smk-k26-revB - - const: xlnx,zynqmp-smk-k26-revA - - const: xlnx,zynqmp-smk-k26 - - const: xlnx,zynqmp + enum: + - xlnx,zynqmp-smk-k26-rev2 + - xlnx,zynqmp-smk-k26-rev1 + - xlnx,zynqmp-smk-k26-revB + - xlnx,zynqmp-smk-k26-revA + - xlnx,zynqmp-smk-k26 + - xlnx,zynqmp + allOf: + - contains: + const: xlnx,zynqmp + - contains: + const: xlnx,zynqmp-smk-k26 + + - description: Xilinx Kria SOM KV260 revA/Y/Z + minItems: 3 + items: + enum: + - xlnx,zynqmp-sk-kv260-revA + - xlnx,zynqmp-sk-kv260-revY + - xlnx,zynqmp-sk-kv260-revZ + - xlnx,zynqmp-sk-kv260 + - xlnx,zynqmp + allOf: + - contains: + const: xlnx,zynqmp-sk-kv260-revA + - contains: + const: xlnx,zynqmp-sk-kv260 + - contains: + const: xlnx,zynqmp + + - description: Xilinx Kria SOM KV260 rev2/1/B + minItems: 3 + items: + enum: + - xlnx,zynqmp-sk-kv260-rev2 + - xlnx,zynqmp-sk-kv260-rev1 + - xlnx,zynqmp-sk-kv260-revB + - xlnx,zynqmp-sk-kv260 + - xlnx,zynqmp + allOf: + - contains: + const: xlnx,zynqmp-sk-kv260-revB + - contains: + const: xlnx,zynqmp-sk-kv260 + - contains: + const: xlnx,zynqmp - description: AMD MicroBlaze V (QEMU) items: diff --git a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml index 8108c564dd78a8..aa32dc950e72cc 100644 --- a/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml +++ b/Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-spdif.yaml @@ -22,6 +22,7 @@ properties: - const: allwinner,sun6i-a31-spdif - const: allwinner,sun8i-h3-spdif - const: allwinner,sun50i-h6-spdif + - const: allwinner,sun50i-h616-spdif - items: - const: allwinner,sun8i-a83t-spdif - const: allwinner,sun8i-h3-spdif @@ -62,6 +63,8 @@ allOf: enum: - allwinner,sun6i-a31-spdif - allwinner,sun8i-h3-spdif + - allwinner,sun50i-h6-spdif + - allwinner,sun50i-h616-spdif then: required: @@ -73,7 +76,7 @@ allOf: contains: enum: - allwinner,sun8i-h3-spdif - - allwinner,sun50i-h6-spdif + - allwinner,sun50i-h616-spdif then: properties: diff --git a/Documentation/devicetree/bindings/sound/atmel,asoc-wm8904.yaml b/Documentation/devicetree/bindings/sound/atmel,asoc-wm8904.yaml new file mode 100644 index 00000000000000..89a67f8e33b6bb --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel,asoc-wm8904.yaml @@ -0,0 +1,84 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/atmel,asoc-wm8904.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel wm8904 audio codec complex + +maintainers: + - Dharma Balasubiramani + +description: + The ASoC audio complex configuration for Atmel with WM8904 audio codec. + +properties: + compatible: + const: atmel,asoc-wm8904 + + atmel,model: + $ref: /schemas/types.yaml#/definitions/string + description: The user-visible name of this sound complex. + + atmel,ssc-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the SSC controller. + + atmel,audio-codec: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the WM8731 audio codec. + + atmel,audio-routing: + description: + 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. + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + items: + enum: + # Board Connectors + - Headphone Jack + - Line In Jack + - Mic + # WM8904 CODEC Pins + - IN1L + - IN1R + - IN2L + - IN2R + - IN3L + - IN3R + - HPOUTL + - HPOUTR + - LINEOUTL + - LINEOUTR + - MICBIAS + +required: + - compatible + - atmel,model + - atmel,audio-routing + - atmel,ssc-controller + - atmel,audio-codec + +additionalProperties: false + +examples: + - | + sound { + compatible = "atmel,asoc-wm8904"; + pinctrl-names = "default"; + pinctrl-0 = <&pinctrl_pck0_as_mck>; + + atmel,model = "wm8904 @ AT91SAM9N12EK"; + + atmel,audio-routing = + "Headphone Jack", "HPOUTL", + "Headphone Jack", "HPOUTR", + "IN2L", "Line In Jack", + "IN2R", "Line In Jack", + "Mic", "MICBIAS", + "IN1L", "Mic"; + + atmel,ssc-controller = <&ssc0>; + atmel,audio-codec = <&wm8904>; + }; diff --git a/Documentation/devicetree/bindings/sound/atmel,sam9x5-wm8731-audio.yaml b/Documentation/devicetree/bindings/sound/atmel,sam9x5-wm8731-audio.yaml new file mode 100644 index 00000000000000..33717b728f636a --- /dev/null +++ b/Documentation/devicetree/bindings/sound/atmel,sam9x5-wm8731-audio.yaml @@ -0,0 +1,76 @@ +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/atmel,sam9x5-wm8731-audio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Atmel at91sam9x5ek wm8731 audio complex + +maintainers: + - Dharma Balasubiramani + +description: + The audio complex configuration for Atmel at91sam9x5ek with WM8731 audio codec. + +properties: + compatible: + const: atmel,sam9x5-wm8731-audio + + atmel,model: + $ref: /schemas/types.yaml#/definitions/string + description: The user-visible name of this sound complex. + + atmel,ssc-controller: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the SSC controller. + + atmel,audio-codec: + $ref: /schemas/types.yaml#/definitions/phandle + description: The phandle of the WM8731 audio codec. + + atmel,audio-routing: + description: + 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. + $ref: /schemas/types.yaml#/definitions/non-unique-string-array + items: + enum: + # Board Connectors + - Headphone Jack + - Line In Jack + + # CODEC Pins + - LOUT + - ROUT + - LHPOUT + - RHPOUT + - LLINEIN + - RLINEIN + - MICIN + +required: + - compatible + - atmel,model + - atmel,ssc-controller + - atmel,audio-codec + - atmel,audio-routing + +additionalProperties: false + +examples: + - | + sound { + compatible = "atmel,sam9x5-wm8731-audio"; + + atmel,model = "wm8731 @ AT91SAM9X5EK"; + + atmel,audio-routing = + "Headphone Jack", "RHPOUT", + "Headphone Jack", "LHPOUT", + "LLINEIN", "Line In Jack", + "RLINEIN", "Line In Jack"; + + atmel,ssc-controller = <&ssc0>; + atmel,audio-codec = <&wm8731>; + }; diff --git a/Documentation/devicetree/bindings/sound/atmel-sam9x5-wm8731-audio.txt b/Documentation/devicetree/bindings/sound/atmel-sam9x5-wm8731-audio.txt deleted file mode 100644 index 8facbce53db86a..00000000000000 --- a/Documentation/devicetree/bindings/sound/atmel-sam9x5-wm8731-audio.txt +++ /dev/null @@ -1,35 +0,0 @@ -* Atmel at91sam9x5ek wm8731 audio complex - -Required properties: - - compatible: "atmel,sam9x5-wm8731-audio" - - atmel,model: The user-visible name of this sound complex. - - atmel,ssc-controller: The phandle of the SSC controller - - atmel,audio-codec: The phandle of the WM8731 audio codec - - atmel,audio-routing: A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. - -Available audio endpoints for the audio-routing table: - -Board connectors: - * Headphone Jack - * Line In Jack - -wm8731 pins: -cf Documentation/devicetree/bindings/sound/wlf,wm8731.yaml - -Example: -sound { - compatible = "atmel,sam9x5-wm8731-audio"; - - atmel,model = "wm8731 @ AT91SAM9X5EK"; - - atmel,audio-routing = - "Headphone Jack", "RHPOUT", - "Headphone Jack", "LHPOUT", - "LLINEIN", "Line In Jack", - "RLINEIN", "Line In Jack"; - - atmel,ssc-controller = <&ssc0>; - atmel,audio-codec = <&wm8731>; -}; diff --git a/Documentation/devicetree/bindings/sound/atmel-wm8904.txt b/Documentation/devicetree/bindings/sound/atmel-wm8904.txt deleted file mode 100644 index 8bbe50c884b696..00000000000000 --- a/Documentation/devicetree/bindings/sound/atmel-wm8904.txt +++ /dev/null @@ -1,55 +0,0 @@ -Atmel ASoC driver with wm8904 audio codec complex - -Required properties: - - compatible: "atmel,asoc-wm8904" - - atmel,model: The user-visible name of this sound complex. - - atmel,audio-routing: A list of the connections between audio components. - Each entry is a pair of strings, the first being the connection's sink, - the second being the connection's source. Valid names for sources and - sinks are the WM8904's pins, and the jacks on the board: - - WM8904 pins: - - * IN1L - * IN1R - * IN2L - * IN2R - * IN3L - * IN3R - * HPOUTL - * HPOUTR - * LINEOUTL - * LINEOUTR - * MICBIAS - - Board connectors: - - * Headphone Jack - * Line In Jack - * Mic - - - atmel,ssc-controller: The phandle of the SSC controller - - atmel,audio-codec: The phandle of the WM8904 audio codec - -Optional properties: - - pinctrl-names, pinctrl-0: Please refer to pinctrl-bindings.txt - -Example: -sound { - compatible = "atmel,asoc-wm8904"; - pinctrl-names = "default"; - pinctrl-0 = <&pinctrl_pck0_as_mck>; - - atmel,model = "wm8904 @ AT91SAM9N12EK"; - - atmel,audio-routing = - "Headphone Jack", "HPOUTL", - "Headphone Jack", "HPOUTR", - "IN2L", "Line In Jack", - "IN2R", "Line In Jack", - "Mic", "MICBIAS", - "IN1L", "Mic"; - - atmel,ssc-controller = <&ssc0>; - atmel,audio-codec = <&wm8904>; -}; diff --git a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml index b13c08de505e41..28b27e7e45de6b 100644 --- a/Documentation/devicetree/bindings/sound/audio-graph-port.yaml +++ b/Documentation/devicetree/bindings/sound/audio-graph-port.yaml @@ -51,7 +51,7 @@ definitions: - $ref: /schemas/types.yaml#/definitions/phandle clocks: description: Indicates system clock - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 system-clock-frequency: $ref: simple-card.yaml#/definitions/system-clock-frequency system-clock-direction-out: diff --git a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml index 4c9acb8d4c4c61..70f6c62aedca84 100644 --- a/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml +++ b/Documentation/devicetree/bindings/sound/cirrus,cs35l45.yaml @@ -25,6 +25,9 @@ properties: reg: maxItems: 1 + interrupts: + maxItems: 1 + '#sound-dai-cells': const: 1 diff --git a/Documentation/devicetree/bindings/sound/fsl,asrc.txt b/Documentation/devicetree/bindings/sound/fsl,asrc.txt deleted file mode 100644 index 998b4c8a7f78af..00000000000000 --- a/Documentation/devicetree/bindings/sound/fsl,asrc.txt +++ /dev/null @@ -1,80 +0,0 @@ -Freescale Asynchronous Sample Rate Converter (ASRC) Controller - -The Asynchronous Sample Rate Converter (ASRC) converts the sampling rate of a -signal associated with an input clock into a signal associated with a different -output clock. The driver currently works as a Front End of DPCM with other Back -Ends Audio controller such as ESAI, SSI and SAI. It has three pairs to support -three substreams within totally 10 channels. - -Required properties: - - - compatible : Compatible list, should contain one of the following - compatibles: - "fsl,imx35-asrc", - "fsl,imx53-asrc", - "fsl,imx8qm-asrc", - "fsl,imx8qxp-asrc", - - - reg : Offset and length of the register set for the device. - - - interrupts : Contains the spdif interrupt. - - - dmas : Generic dma devicetree binding as described in - Documentation/devicetree/bindings/dma/dma.txt. - - - dma-names : Contains "rxa", "rxb", "rxc", "txa", "txb" and "txc". - - - clocks : Contains an entry for each entry in clock-names. - - - clock-names : Contains the following entries - "mem" Peripheral access clock to access registers. - "ipg" Peripheral clock to driver module. - "asrck_<0-f>" Clock sources for input and output clock. - "spba" The spba clock is required when ASRC is placed as a - bus slave of the Shared Peripheral Bus and when two - or more bus masters (CPU, DMA or DSP) try to access - it. This property is optional depending on the SoC - design. - - - fsl,asrc-rate : Defines a mutual sample rate used by DPCM Back Ends. - - - fsl,asrc-width : Defines a mutual sample width used by DPCM Back Ends. - - - fsl,asrc-clk-map : Defines clock map used in driver. which is required - by imx8qm/imx8qxp platform - <0> - select the map for asrc0 in imx8qm/imx8qxp - <1> - select the map for asrc1 in imx8qm/imx8qxp - -Optional properties: - - - big-endian : If this property is absent, the little endian mode - will be in use as default. Otherwise, the big endian - mode will be in use for all the device registers. - - - fsl,asrc-format : Defines a mutual sample format used by DPCM Back - Ends, which can replace the fsl,asrc-width. - The value is 2 (S16_LE), or 6 (S24_LE). - -Example: - -asrc: asrc@2034000 { - compatible = "fsl,imx53-asrc"; - reg = <0x02034000 0x4000>; - interrupts = <0 50 IRQ_TYPE_LEVEL_HIGH>; - clocks = <&clks 107>, <&clks 107>, <&clks 0>, - <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, - <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, - <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, - <&clks 107>, <&clks 0>, <&clks 0>; - clock-names = "mem", "ipg", "asrck0", - "asrck_1", "asrck_2", "asrck_3", "asrck_4", - "asrck_5", "asrck_6", "asrck_7", "asrck_8", - "asrck_9", "asrck_a", "asrck_b", "asrck_c", - "asrck_d", "asrck_e", "asrck_f"; - dmas = <&sdma 17 23 1>, <&sdma 18 23 1>, <&sdma 19 23 1>, - <&sdma 20 23 1>, <&sdma 21 23 1>, <&sdma 22 23 1>; - dma-names = "rxa", "rxb", "rxc", - "txa", "txb", "txc"; - fsl,asrc-rate = <48000>; - fsl,asrc-width = <16>; -}; diff --git a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml index a680d7aff2373c..0782f3f9947f85 100644 --- a/Documentation/devicetree/bindings/sound/fsl,easrc.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,easrc.yaml @@ -51,8 +51,8 @@ properties: - const: ctx3_tx firmware-name: - $ref: /schemas/types.yaml#/definitions/string - const: imx/easrc/easrc-imx8mn.bin + items: + - const: imx/easrc/easrc-imx8mn.bin description: The coefficient table for the filters fsl,asrc-rate: diff --git a/Documentation/devicetree/bindings/sound/fsl,imx-asrc.yaml b/Documentation/devicetree/bindings/sound/fsl,imx-asrc.yaml new file mode 100644 index 00000000000000..bfef2fcb75b145 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/fsl,imx-asrc.yaml @@ -0,0 +1,162 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/fsl,imx-asrc.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Freescale Asynchronous Sample Rate Converter (ASRC) Controller + +description: + The Asynchronous Sample Rate Converter (ASRC) converts the sampling rate of + a signal associated with an input clock into a signal associated with a + different output clock. The driver currently works as a Front End of DPCM + with other Back Ends Audio controller such as ESAI, SSI and SAI. It has + three pairs to support three substreams within totally 10 channels. + +maintainers: + - Shawn Guo + - Sascha Hauer + +properties: + compatible: + oneOf: + - enum: + - fsl,imx35-asrc + - fsl,imx53-asrc + - fsl,imx8qm-asrc + - fsl,imx8qxp-asrc + - items: + - enum: + - fsl,imx6sx-asrc + - fsl,imx6ul-asrc + - const: fsl,imx53-asrc + + reg: + maxItems: 1 + + interrupts: + maxItems: 1 + + dmas: + maxItems: 6 + + dma-names: + items: + - const: rxa + - const: rxb + - const: rxc + - const: txa + - const: txb + - const: txc + + clocks: + maxItems: 19 + + clock-names: + items: + - const: mem + - const: ipg + - const: asrck_0 + - const: asrck_1 + - const: asrck_2 + - const: asrck_3 + - const: asrck_4 + - const: asrck_5 + - const: asrck_6 + - const: asrck_7 + - const: asrck_8 + - const: asrck_9 + - const: asrck_a + - const: asrck_b + - const: asrck_c + - const: asrck_d + - const: asrck_e + - const: asrck_f + - const: spba + + fsl,asrc-rate: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mutual sample rate used by DPCM Back Ends + + fsl,asrc-width: + $ref: /schemas/types.yaml#/definitions/uint32 + description: The mutual sample width used by DPCM Back Ends + enum: [16, 24] + + fsl,asrc-clk-map: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Defines clock map used in driver + <0> - select the map for asrc0 in imx8qm/imx8qxp + <1> - select the map for asrc1 in imx8qm/imx8qxp + enum: [0, 1] + + big-endian: + type: boolean + description: + If this property is absent, the little endian mode will be in use as + default. Otherwise, the big endian mode will be in use for all the + device registers. + + fsl,asrc-format: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Defines a mutual sample format used by DPCM Back Ends, which can + replace the fsl,asrc-width. The value is 2 (S16_LE), or 6 (S24_LE). + enum: [2, 6] + +required: + - compatible + - reg + - interrupts + - dmas + - dma-names + - clocks + - clock-names + - fsl,asrc-rate + - fsl,asrc-width + +allOf: + - if: + properties: + compatible: + contains: + enum: + - fsl,imx8qm-asrc + - fsl,imx8qxp-asrc + then: + required: + - fsl,asrc-clk-map + else: + properties: + fsl,asrc-clk-map: false + +additionalProperties: false + +examples: + - | + #include + #include + asrc: asrc@2034000 { + compatible = "fsl,imx53-asrc"; + reg = <0x02034000 0x4000>; + interrupts = <0 50 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&clks IMX6QDL_CLK_ASRC_IPG>, + <&clks IMX6QDL_CLK_ASRC_MEM>, <&clks 0>, + <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, + <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, + <&clks 0>, <&clks 0>, <&clks 0>, <&clks 0>, + <&clks IMX6QDL_CLK_ASRC>, <&clks 0>, <&clks 0>, + <&clks IMX6QDL_CLK_SPBA>; + clock-names = "mem", "ipg", "asrck_0", + "asrck_1", "asrck_2", "asrck_3", "asrck_4", + "asrck_5", "asrck_6", "asrck_7", "asrck_8", + "asrck_9", "asrck_a", "asrck_b", "asrck_c", + "asrck_d", "asrck_e", "asrck_f", "spba"; + dmas = <&sdma 17 23 1>, <&sdma 18 23 1>, <&sdma 19 23 1>, + <&sdma 20 23 1>, <&sdma 21 23 1>, <&sdma 22 23 1>; + dma-names = "rxa", "rxb", "rxc", + "txa", "txb", "txc"; + fsl,asrc-rate = <48000>; + fsl,asrc-width = <16>; + }; diff --git a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml index b7e60583563918..c1e9803fc113c0 100644 --- a/Documentation/devicetree/bindings/sound/fsl,micfil.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,micfil.yaml @@ -15,10 +15,16 @@ description: | properties: compatible: - enum: - - fsl,imx8mm-micfil - - fsl,imx8mp-micfil - - fsl,imx93-micfil + oneOf: + - items: + - enum: + - fsl,imx95-micfil + - const: fsl,imx93-micfil + + - enum: + - fsl,imx8mm-micfil + - fsl,imx8mp-micfil + - fsl,imx93-micfil reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/sound/fsl,sai.yaml b/Documentation/devicetree/bindings/sound/fsl,sai.yaml index 088c26b001cc02..2456d958adeef6 100644 --- a/Documentation/devicetree/bindings/sound/fsl,sai.yaml +++ b/Documentation/devicetree/bindings/sound/fsl,sai.yaml @@ -39,6 +39,7 @@ properties: - fsl,imx8qm-sai - fsl,imx8ulp-sai - fsl,imx93-sai + - fsl,imx95-sai - fsl,vf610-sai reg: @@ -75,12 +76,17 @@ properties: - const: pll11k minItems: 4 + power-domains: + maxItems: 1 + dmas: + minItems: 1 items: - description: DMA controller phandle and request line for RX - description: DMA controller phandle and request line for TX dma-names: + minItems: 1 items: - const: rx - const: tx diff --git a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml index ec4b6e547ca6ef..cdcd7c6f21eb24 100644 --- a/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml +++ b/Documentation/devicetree/bindings/sound/google,sc7280-herobrine.yaml @@ -7,7 +7,6 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Google SC7280-Herobrine ASoC sound card driver maintainers: - - Srinivasa Rao Mandadapu - Judy Hsiao description: diff --git a/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml b/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml index 66993d378aaf59..5e11ce2c13aca1 100644 --- a/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml +++ b/Documentation/devicetree/bindings/sound/infineon,peb2466.yaml @@ -51,7 +51,7 @@ properties: maxItems: 1 firmware-name: - $ref: /schemas/types.yaml#/definitions/string + maxItems: 1 description: Filters coefficients file to load. If this property is omitted, internal filters are disabled. diff --git a/Documentation/devicetree/bindings/sound/qcom,q6usb.yaml b/Documentation/devicetree/bindings/sound/qcom,q6usb.yaml new file mode 100644 index 00000000000000..37161d2aa96e18 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,q6usb.yaml @@ -0,0 +1,55 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,q6usb.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm ASoC DPCM USB backend DAI + +maintainers: + - Wesley Cheng + +description: + The USB port is a supported AFE path on the Q6 DSP. This ASoC DPCM + backend DAI will communicate the required settings to initialize the + XHCI host controller properly for enabling the offloaded audio stream. + Parameters defined under this node will carry settings, which will be + passed along during the QMI stream enable request and configuration of + the XHCI host controller. + +allOf: + - $ref: dai-common.yaml# + +properties: + compatible: + enum: + - qcom,q6usb + + iommus: + maxItems: 1 + + "#sound-dai-cells": + const: 1 + + qcom,usb-audio-intr-idx: + description: + Desired XHCI interrupter number to use. Depending on the audio DSP + on the platform, it will operate on a specific XHCI interrupter. + $ref: /schemas/types.yaml#/definitions/uint16 + maximum: 8 + +required: + - compatible + - "#sound-dai-cells" + - qcom,usb-audio-intr-idx + +additionalProperties: false + +examples: + - | + dais { + compatible = "qcom,q6usb"; + #sound-dai-cells = <1>; + iommus = <&apps_smmu 0x180f 0x0>; + qcom,usb-audio-intr-idx = /bits/ 16 <2>; + }; diff --git a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml index 6f419747273e37..49e4f5bbe9ddca 100644 --- a/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,sm8250.yaml @@ -107,7 +107,7 @@ patternProperties: properties: sound-dai: minItems: 1 - maxItems: 4 + maxItems: 8 required: - link-name @@ -227,6 +227,21 @@ examples: sound-dai = <&vamacro 0>; }; }; + + usb-dai-link { + link-name = "USB Playback"; + cpu { + sound-dai = <&q6afedai USB_RX>; + }; + + codec { + sound-dai = <&usbdai USB_RX>; + }; + + platform { + sound-dai = <&q6routing>; + }; + }; }; - | diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml index adbfa67f88ed93..cf6c3787adfeff 100644 --- a/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml +++ b/Documentation/devicetree/bindings/sound/qcom,wcd938x.yaml @@ -15,6 +15,7 @@ description: | allOf: - $ref: dai-common.yaml# + - $ref: qcom,wcd93xx-common.yaml# properties: compatible: @@ -22,92 +23,12 @@ properties: - qcom,wcd9380-codec - qcom,wcd9385-codec - reset-gpios: - description: GPIO spec for reset line to use - maxItems: 1 - us-euro-gpios: description: GPIO spec for swapping gnd and mic segments maxItems: 1 - vdd-buck-supply: - description: A reference to the 1.8V buck supply - - vdd-rxtx-supply: - description: A reference to the 1.8V rx supply - - vdd-io-supply: - description: A reference to the 1.8V I/O supply - - vdd-mic-bias-supply: - description: A reference to the 3.8V mic bias supply - - qcom,tx-device: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: A reference to Soundwire tx device phandle - - qcom,rx-device: - $ref: /schemas/types.yaml#/definitions/phandle-array - description: A reference to Soundwire rx device phandle - - qcom,micbias1-microvolt: - description: micbias1 voltage - minimum: 1800000 - maximum: 2850000 - - qcom,micbias2-microvolt: - description: micbias2 voltage - minimum: 1800000 - maximum: 2850000 - - qcom,micbias3-microvolt: - description: micbias3 voltage - minimum: 1800000 - maximum: 2850000 - - qcom,micbias4-microvolt: - description: micbias4 voltage - minimum: 1800000 - maximum: 2850000 - - qcom,hphl-jack-type-normally-closed: - description: Indicates that HPHL jack switch type is normally closed - type: boolean - - qcom,ground-jack-type-normally-closed: - description: Indicates that Headset Ground switch type is normally closed - type: boolean - - qcom,mbhc-headset-vthreshold-microvolt: - description: Voltage threshold value for headset detection - minimum: 0 - maximum: 2850000 - - qcom,mbhc-headphone-vthreshold-microvolt: - description: Voltage threshold value for headphone detection - minimum: 0 - maximum: 2850000 - - qcom,mbhc-buttons-vthreshold-microvolt: - description: - Array of 8 Voltage threshold values corresponding to headset - button0 - button7 - minItems: 8 - maxItems: 8 - - '#sound-dai-cells': - const: 1 - required: - compatible - - reset-gpios - - qcom,tx-device - - qcom,rx-device - - qcom,micbias1-microvolt - - qcom,micbias2-microvolt - - qcom,micbias3-microvolt - - qcom,micbias4-microvolt - - "#sound-dai-cells" unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd939x-sdw.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd939x-sdw.yaml new file mode 100644 index 00000000000000..67ed7701b5d67c --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,wcd939x-sdw.yaml @@ -0,0 +1,69 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,wcd939x-sdw.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm SoundWire devices on WCD9390/WCD9395 + +maintainers: + - Srinivas Kandagatla + +description: | + Qualcomm WCD9390/WCD9395 Codec is a standalone Hi-Fi audio codec IC. + It has RX and TX Soundwire devices. This bindings is for the devices. + +properties: + compatible: + const: sdw20217010e00 + + reg: + maxItems: 1 + + qcom,tx-port-mapping: + description: | + Specifies static port mapping between device and host tx ports. + In the order of the device port index. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 4 + maxItems: 4 + + qcom,rx-port-mapping: + description: | + Specifies static port mapping between device and host rx ports. + In the order of device port index. + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 6 + maxItems: 6 + +required: + - compatible + - reg + +additionalProperties: false + +examples: + - | + soundwire@3210000 { + #address-cells = <2>; + #size-cells = <0>; + reg = <0x03210000 0x2000>; + wcd938x_rx: codec@0,4 { + compatible = "sdw20217010e00"; + reg = <0 4>; + qcom,rx-port-mapping = <1 2 3 4 5 6>; + }; + }; + + soundwire@3230000 { + #address-cells = <2>; + #size-cells = <0>; + reg = <0x03230000 0x2000>; + wcd938x_tx: codec@0,3 { + compatible = "sdw20217010e00"; + reg = <0 3>; + qcom,tx-port-mapping = <2 3 4 5>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd939x.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd939x.yaml new file mode 100644 index 00000000000000..6e76f6a8634f07 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,wcd939x.yaml @@ -0,0 +1,96 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,wcd939x.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Qualcomm WCD9380/WCD9385 Audio Codec + +maintainers: + - Srinivas Kandagatla + +description: | + Qualcomm WCD9390/WCD9395 Codec is a standalone Hi-Fi audio codec IC. + It has RX and TX Soundwire devices. + The WCD9390/WCD9395 IC has a functionally separate USB-C Mux subsystem + accessible over an I2C interface. + The Audio Headphone and Microphone data path between the Codec and the USB-C Mux + subsystems are external to the IC, thus requiring DT port-endpoint graph description + to handle USB-C altmode & orientation switching for Audio Accessory Mode. + +allOf: + - $ref: dai-common.yaml# + - $ref: qcom,wcd93xx-common.yaml# + +properties: + compatible: + oneOf: + - const: qcom,wcd9390-codec + - items: + - const: qcom,wcd9395-codec + - const: qcom,wcd9390-codec + + mode-switch: + description: Flag the port as possible handler of altmode switching + type: boolean + + orientation-switch: + description: Flag the port as possible handler of orientation switching + type: boolean + + port: + $ref: /schemas/graph.yaml#/properties/port + description: + A port node to link the WCD939x Codec node to USB MUX subsystems for the + purpose of handling altmode muxing and orientation switching to detect and + enable Audio Accessory Mode. + +required: + - compatible + +unevaluatedProperties: false + +examples: + - | + #include + codec { + compatible = "qcom,wcd9390-codec"; + reset-gpios = <&tlmm 32 IRQ_TYPE_NONE>; + #sound-dai-cells = <1>; + qcom,tx-device = <&wcd939x_tx>; + qcom,rx-device = <&wcd939x_rx>; + qcom,micbias1-microvolt = <1800000>; + qcom,micbias2-microvolt = <1800000>; + qcom,micbias3-microvolt = <1800000>; + qcom,micbias4-microvolt = <1800000>; + qcom,hphl-jack-type-normally-closed; + qcom,ground-jack-type-normally-closed; + qcom,mbhc-buttons-vthreshold-microvolt = <75000 150000 237000 500000 500000 500000 500000 500000>; + qcom,mbhc-headphone-vthreshold-microvolt = <50000>; + }; + + /* ... */ + + soundwire@3210000 { + #address-cells = <2>; + #size-cells = <0>; + reg = <0x03210000 0x2000>; + wcd939x_rx: codec@0,4 { + compatible = "sdw20217010e00"; + reg = <0 4>; + qcom,rx-port-mapping = <1 2 3 4 5 6>; + }; + }; + + soundwire@3230000 { + #address-cells = <2>; + #size-cells = <0>; + reg = <0x03230000 0x2000>; + wcd938x_tx: codec@0,3 { + compatible = "sdw20217010e00"; + reg = <0 3>; + qcom,tx-port-mapping = <2 3 4 5>; + }; + }; + +... diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd93xx-common.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd93xx-common.yaml new file mode 100644 index 00000000000000..f78ba148ad25ff --- /dev/null +++ b/Documentation/devicetree/bindings/sound/qcom,wcd93xx-common.yaml @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/sound/qcom,wcd93xx-common.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Common properties for Qualcomm WCD93xx Audio Codec + +maintainers: + - Srinivas Kandagatla + +properties: + reset-gpios: + description: GPIO spec for reset line to use + maxItems: 1 + + vdd-buck-supply: + description: A reference to the 1.8V buck supply + + vdd-rxtx-supply: + description: A reference to the 1.8V rx supply + + vdd-io-supply: + description: A reference to the 1.8V I/O supply + + vdd-mic-bias-supply: + description: A reference to the 3.8V mic bias supply + + qcom,tx-device: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: A reference to Soundwire tx device phandle + + qcom,rx-device: + $ref: /schemas/types.yaml#/definitions/phandle-array + description: A reference to Soundwire rx device phandle + + qcom,micbias1-microvolt: + description: micbias1 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias2-microvolt: + description: micbias2 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias3-microvolt: + description: micbias3 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,micbias4-microvolt: + description: micbias4 voltage + minimum: 1800000 + maximum: 2850000 + + qcom,hphl-jack-type-normally-closed: + description: Indicates that HPHL jack switch type is normally closed + type: boolean + + qcom,ground-jack-type-normally-closed: + description: Indicates that Headset Ground switch type is normally closed + type: boolean + + qcom,mbhc-headset-vthreshold-microvolt: + description: Voltage threshold value for headset detection + minimum: 0 + maximum: 2850000 + + qcom,mbhc-headphone-vthreshold-microvolt: + description: Voltage threshold value for headphone detection + minimum: 0 + maximum: 2850000 + + qcom,mbhc-buttons-vthreshold-microvolt: + description: + Array of 8 Voltage threshold values corresponding to headset + button0 - button7 + minItems: 8 + maxItems: 8 + + '#sound-dai-cells': + const: 1 + +required: + - reset-gpios + - qcom,tx-device + - qcom,rx-device + - qcom,micbias1-microvolt + - qcom,micbias2-microvolt + - qcom,micbias3-microvolt + - qcom,micbias4-microvolt + - "#sound-dai-cells" + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/sound/samsung,tm2.yaml b/Documentation/devicetree/bindings/sound/samsung,tm2.yaml index 76059259914346..cbc7ba37362a93 100644 --- a/Documentation/devicetree/bindings/sound/samsung,tm2.yaml +++ b/Documentation/devicetree/bindings/sound/samsung,tm2.yaml @@ -25,8 +25,11 @@ properties: description: Phandles to the codecs. $ref: /schemas/types.yaml#/definitions/phandle-array items: - - description: Phandle to the WM5110 audio codec. - - description: Phandle to the HDMI transmitter node. + - items: + - description: Phandle to the WM5110 audio codec. + - items: + - description: Phandle to the HDMI transmitter node. + samsung,audio-routing: description: | diff --git a/Documentation/devicetree/bindings/spi/samsung,spi.yaml b/Documentation/devicetree/bindings/spi/samsung,spi.yaml index 79da99ca0e53e6..2f0a0835ecfb35 100644 --- a/Documentation/devicetree/bindings/spi/samsung,spi.yaml +++ b/Documentation/devicetree/bindings/spi/samsung,spi.yaml @@ -17,11 +17,13 @@ properties: compatible: oneOf: - enum: + - google,gs101-spi - samsung,s3c2443-spi # for S3C2443, S3C2416 and S3C2450 - samsung,s3c6410-spi - samsung,s5pv210-spi # for S5PV210 and S5PC110 - samsung,exynos4210-spi - samsung,exynos5433-spi + - samsung,exynos850-spi - samsung,exynosautov9-spi - tesla,fsd-spi - const: samsung,exynos7-spi diff --git a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml index 727c5346b8ceda..2ff17424479570 100644 --- a/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-fsl-lpspi.yaml @@ -22,6 +22,7 @@ properties: - enum: - fsl,imx8ulp-spi - fsl,imx93-spi + - fsl,imx95-spi - const: fsl,imx7ulp-spi reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml index 7fd59114548001..4a5f41bde00f3c 100644 --- a/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml +++ b/Documentation/devicetree/bindings/spi/spi-nxp-fspi.yaml @@ -15,12 +15,18 @@ allOf: properties: compatible: - enum: - - nxp,imx8dxl-fspi - - nxp,imx8mm-fspi - - nxp,imx8mp-fspi - - nxp,imx8qxp-fspi - - nxp,lx2160a-fspi + oneOf: + - enum: + - nxp,imx8dxl-fspi + - nxp,imx8mm-fspi + - nxp,imx8mp-fspi + - nxp,imx8qxp-fspi + - nxp,lx2160a-fspi + - items: + - enum: + - nxp,imx93-fspi + - nxp,imx95-fspi + - const: nxp,imx8mm-fspi reg: items: diff --git a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml index a1c96985951ff2..cf07b8f787a6ed 100644 --- a/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml +++ b/Documentation/devicetree/bindings/sram/allwinner,sun4i-a10-system-control.yaml @@ -56,7 +56,7 @@ properties: ranges: true patternProperties: - "^sram@[a-z0-9]+": + "^sram@[a-f0-9]+": $ref: /schemas/sram/sram.yaml# unevaluatedProperties: false diff --git a/Documentation/devicetree/bindings/submitting-patches.rst b/Documentation/devicetree/bindings/submitting-patches.rst index 36a17b250ccc75..a64f21a5f299a6 100644 --- a/Documentation/devicetree/bindings/submitting-patches.rst +++ b/Documentation/devicetree/bindings/submitting-patches.rst @@ -15,6 +15,11 @@ I. For patch submitters "dt-bindings: : ..." + Few subsystems, like ASoC, media, regulators and SPI, expect reverse order + of the prefixes:: + + ": dt-bindings: ..." + The 80 characters of the subject are precious. It is recommended to not use "Documentation" or "doc" because that is implied. All bindings are docs. Repeating "binding" again should also be avoided. @@ -42,28 +47,18 @@ I. For patch submitters the code implementing the binding. 6) Any compatible strings used in a chip or board DTS file must be - previously documented in the corresponding DT binding text file + previously documented in the corresponding DT binding file in Documentation/devicetree/bindings. This rule applies even if the Linux device driver does not yet match on the compatible string. [ checkpatch will emit warnings if this step is not followed as of commit bff5da4335256513497cc8c79f9a9d1665e09864 ("checkpatch: add DT compatible string documentation checks"). ] - 7) The wildcard "" may be used in compatible strings, as in - the following example: - - - compatible: Must contain '"nvidia,-pcie", - "nvidia,tegra20-pcie"' where is tegra30, tegra132, ... - - As in the above example, the known values of "" should be - documented if it is used. - - 8) If a documented compatible string is not yet matched by the + 7) If a documented compatible string is not yet matched by the driver, the documentation should also include a compatible - string that is matched by the driver (as in the "nvidia,tegra20-pcie" - example above). + string that is matched by the driver. - 9) Bindings are actively used by multiple projects other than the Linux + 8) Bindings are actively used by multiple projects other than the Linux Kernel, extra care and consideration may need to be taken when making changes to existing bindings. diff --git a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml index 1ee4aab695d384..fe6bc4173789da 100644 --- a/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml +++ b/Documentation/devicetree/bindings/timer/mrvl,mmp-timer.yaml @@ -9,7 +9,7 @@ title: Marvell MMP Timer maintainers: - Daniel Lezcano - Thomas Gleixner - - Rob Herring + - Rob Herring properties: $nodename: diff --git a/Documentation/devicetree/bindings/timer/nxp,sysctr-timer.yaml b/Documentation/devicetree/bindings/timer/nxp,sysctr-timer.yaml index 2b9653dafab8f3..891cca00952815 100644 --- a/Documentation/devicetree/bindings/timer/nxp,sysctr-timer.yaml +++ b/Documentation/devicetree/bindings/timer/nxp,sysctr-timer.yaml @@ -18,7 +18,9 @@ description: | properties: compatible: - const: nxp,sysctr-timer + enum: + - nxp,imx95-sysctr-timer + - nxp,sysctr-timer reg: maxItems: 1 diff --git a/Documentation/devicetree/bindings/timer/renesas,ostm.yaml b/Documentation/devicetree/bindings/timer/renesas,ostm.yaml index 7207929e5cd6a7..8b06a681764e3b 100644 --- a/Documentation/devicetree/bindings/timer/renesas,ostm.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,ostm.yaml @@ -23,7 +23,7 @@ properties: - enum: - renesas,r7s72100-ostm # RZ/A1H - renesas,r7s9210-ostm # RZ/A2M - - renesas,r9a07g043-ostm # RZ/G2UL + - renesas,r9a07g043-ostm # RZ/G2UL and RZ/Five - renesas,r9a07g044-ostm # RZ/G2{L,LC} - renesas,r9a07g054-ostm # RZ/V2L - const: renesas,ostm # Generic diff --git a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml index a67e427a9e7e22..84bbe15028a1de 100644 --- a/Documentation/devicetree/bindings/timer/renesas,tmu.yaml +++ b/Documentation/devicetree/bindings/timer/renesas,tmu.yaml @@ -46,7 +46,19 @@ properties: interrupts: minItems: 2 - maxItems: 3 + items: + - description: Underflow interrupt, channel 0 + - description: Underflow interrupt, channel 1 + - description: Underflow interrupt, channel 2 + - description: Input capture interrupt, channel 2 + + interrupt-names: + minItems: 2 + items: + - const: tuni0 + - const: tuni1 + - const: tuni2 + - const: ticpi2 clocks: maxItems: 1 @@ -100,7 +112,9 @@ examples: reg = <0xffd80000 0x30>; interrupts = , , - ; + , + ; + interrupt-names = "tuni0", "tuni1", "tuni2", "ticpi2"; clocks = <&mstp0_clks R8A7779_CLK_TMU0>; clock-names = "fck"; power-domains = <&sysc R8A7779_PD_ALWAYS_ON>; diff --git a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.yaml b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.yaml index 829bd2227f7c9c..774b7992a0cafc 100644 --- a/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.yaml +++ b/Documentation/devicetree/bindings/timer/samsung,exynos4210-mct.yaml @@ -26,6 +26,7 @@ properties: - items: - enum: - axis,artpec8-mct + - google,gs101-mct - samsung,exynos3250-mct - samsung,exynos5250-mct - samsung,exynos5260-mct @@ -127,6 +128,7 @@ allOf: contains: enum: - axis,artpec8-mct + - google,gs101-mct - samsung,exynos5260-mct - samsung,exynos5420-mct - samsung,exynos5433-mct diff --git a/Documentation/devicetree/bindings/tpm/tcg,tpm_tis-spi.yaml b/Documentation/devicetree/bindings/tpm/tcg,tpm_tis-spi.yaml index c3413b47ac3df9..6cb2de7cb5688e 100644 --- a/Documentation/devicetree/bindings/tpm/tcg,tpm_tis-spi.yaml +++ b/Documentation/devicetree/bindings/tpm/tcg,tpm_tis-spi.yaml @@ -20,6 +20,7 @@ properties: compatible: items: - enum: + - atmel,attpm20p - infineon,slb9670 - st,st33htpm-spi - st,st33zp24-spi diff --git a/Documentation/devicetree/bindings/tpm/tpm-common.yaml b/Documentation/devicetree/bindings/tpm/tpm-common.yaml index 90390624a8be5e..3c1241b2a43f99 100644 --- a/Documentation/devicetree/bindings/tpm/tpm-common.yaml +++ b/Documentation/devicetree/bindings/tpm/tpm-common.yaml @@ -42,7 +42,7 @@ properties: resets: description: Reset controller to reset the TPM - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 reset-gpios: description: Output GPIO pin to reset the TPM diff --git a/Documentation/devicetree/bindings/trivial-devices.yaml b/Documentation/devicetree/bindings/trivial-devices.yaml index 79dcd92c4a4345..9cdd5a53412045 100644 --- a/Documentation/devicetree/bindings/trivial-devices.yaml +++ b/Documentation/devicetree/bindings/trivial-devices.yaml @@ -28,6 +28,7 @@ properties: compatible: items: + # Entries are sorted alphanumerically by the compatible - enum: # Acbel fsg032 power supply - acbel,fsg032 @@ -47,14 +48,16 @@ properties: - adi,lt7182s # AMS iAQ-Core VOC Sensor - ams,iaq-core + # Temperature monitoring of Astera Labs PT5161L PCIe retimer + - asteralabs,pt5161l # i2c serial eeprom (24cxx) - at,24c08 + # i2c h/w elliptic curve crypto module + - atmel,atecc508a # ATSHA204 - i2c h/w symmetric crypto module - atmel,atsha204 # ATSHA204A - i2c h/w symmetric crypto module - atmel,atsha204a - # i2c h/w elliptic curve crypto module - - atmel,atecc508a # BPA-RS600: Power Supply - blutek,bpa-rs600 # Bosch Sensortec pressure, temperature, humididty and VOC sensor @@ -115,20 +118,6 @@ properties: - fsl,mpl3115 # MPR121: Proximity Capacitive Touch Sensor Controller - fsl,mpr121 - # Monolithic Power Systems Inc. multi-phase controller mp2856 - - mps,mp2856 - # Monolithic Power Systems Inc. multi-phase controller mp2857 - - mps,mp2857 - # Monolithic Power Systems Inc. multi-phase controller mp2888 - - mps,mp2888 - # Monolithic Power Systems Inc. multi-phase controller mp2971 - - mps,mp2971 - # Monolithic Power Systems Inc. multi-phase controller mp2973 - - mps,mp2973 - # Monolithic Power Systems Inc. multi-phase controller mp2975 - - mps,mp2975 - # Monolithic Power Systems Inc. multi-phase hot-swap controller mp5990 - - mps,mp5990 # Honeywell Humidicon HIH-6130 humidity/temperature sensor - honeywell,hi6130 # IBM Common Form Factor Power Supply Versions (all versions) @@ -137,6 +126,8 @@ properties: - ibm,cffps1 # IBM Common Form Factor Power Supply Versions 2 - ibm,cffps2 + # Infineon barometric pressure and temperature sensor + - infineon,dps310 # Infineon IR36021 digital POL buck controller - infineon,ir36021 # Infineon IR38060 Voltage Regulator @@ -195,6 +186,8 @@ properties: - maxim,max1237 # Temperature Sensor, I2C interface - maxim,max1619 + # 3-Channel Remote Temperature Sensor + - maxim,max31730 # 10-bit 10 kOhm linear programmable voltage divider - maxim,max5481 # 10-bit 50 kOhm linear programmable voltage divider @@ -207,8 +200,6 @@ properties: - maxim,max6621 # 9-Bit/12-Bit Temperature Sensors with I²C-Compatible Serial Interface - maxim,max6625 - # 3-Channel Remote Temperature Sensor - - maxim,max31730 # mCube 3-axis 8-bit digital accelerometer - mcube,mc3230 # Measurement Specialities I2C temperature and humidity sensor @@ -239,8 +230,6 @@ properties: - memsic,mxc6655 # Menlo on-board CPLD trivial SPI device - menlo,m53cpld - # Micron SPI NOR Authenta - - micron,spi-authenta # Microchip differential I2C ADC, 1 Channel, 18 bit - microchip,mcp3421 # Microchip differential I2C ADC, 2 Channel, 18 bit @@ -257,40 +246,58 @@ properties: - microchip,mcp3427 # Microchip differential I2C ADC, 4 Channel, 16 bit - microchip,mcp3428 - # 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,mcp4017-502 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4017-503 # 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,mcp4018-502 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4018-503 # 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 POT (5k) + - microchip,mcp4019-502 + # Microchip 7-bit Single I2C Digital POT (50k) + - microchip,mcp4019-503 # PWM Fan Speed Controller With Fan Fault Detection - microchip,tc654 # PWM Fan Speed Controller With Fan Fault Detection - microchip,tc655 + # Micron SPI NOR Authenta + - micron,spi-authenta # 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 + # Monolithic Power Systems Inc. multi-phase controller mp2856 + - mps,mp2856 + # Monolithic Power Systems Inc. multi-phase controller mp2857 + - mps,mp2857 + # Monolithic Power Systems Inc. multi-phase controller mp2888 + - mps,mp2888 + # Monolithic Power Systems Inc. multi-phase controller mp2971 + - mps,mp2971 + # Monolithic Power Systems Inc. multi-phase controller mp2973 + - mps,mp2973 + # Monolithic Power Systems Inc. multi-phase controller mp2975 + - mps,mp2975 + # Monolithic Power Systems Inc. multi-phase hot-swap controller mp5990 + - mps,mp5990 + # Monolithic Power Systems Inc. synchronous step-down converter mpq8785 + - mps,mpq8785 # Temperature sensor with integrated fan control - national,lm63 # Serial Interface ACPI-Compatible Microprocessor System Hardware Monitor @@ -321,12 +328,12 @@ properties: - samsung,exynos-sataphy-i2c # Semtech sx1301 baseband processor - semtech,sx1301 - # Sensirion low power multi-pixel gas sensor with I2C interface - - sensirion,sgpc3 # Sensirion multi-pixel gas sensor with I2C interface - sensirion,sgp30 # Sensirion gas sensor with I2C interface - sensirion,sgp40 + # Sensirion low power multi-pixel gas sensor with I2C interface + - sensirion,sgpc3 # Sensirion temperature & humidity sensor with I2C interface - sensirion,sht4x # Sensortek 3 axis accelerometer @@ -372,8 +379,6 @@ properties: - ti,lm74 # 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,tmp103 # Thermometer with SPI interface @@ -395,10 +400,12 @@ properties: - ti,tps544b25 - ti,tps544c20 - ti,tps544c25 - # Winbond/Nuvoton H/W Monitor - - winbond,w83793 + # I2C Touch-Screen Controller + - ti,tsc2003 # Vicor Corporation Digital Supervisor - vicor,pli1209bc + # Winbond/Nuvoton H/W Monitor + - winbond,w83793 required: - compatible diff --git a/Documentation/devicetree/bindings/ufs/samsung,exynos-ufs.yaml b/Documentation/devicetree/bindings/ufs/samsung,exynos-ufs.yaml index 88cc1e3a0c887c..b2b509b3944d85 100644 --- a/Documentation/devicetree/bindings/ufs/samsung,exynos-ufs.yaml +++ b/Documentation/devicetree/bindings/ufs/samsung,exynos-ufs.yaml @@ -55,9 +55,12 @@ properties: samsung,sysreg: $ref: /schemas/types.yaml#/definitions/phandle-array - description: Should be phandle/offset pair. The phandle to the syscon node - which indicates the FSYSx sysreg interface and the offset of - the control register for UFS io coherency setting. + items: + - items: + - description: phandle to FSYSx sysreg node + - description: offset of the control register for UFS io coherency setting + description: + Phandle and offset to the FSYSx sysreg for UFS io coherency setting. dma-coherent: true diff --git a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml index b7e664f7395b33..3b56e0edb1c676 100644 --- a/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml +++ b/Documentation/devicetree/bindings/usb/ci-hdrc-usb2.yaml @@ -313,7 +313,7 @@ properties: usb-phy: description: phandle for the PHY device. Use "phys" instead. - $ref: /schemas/types.yaml#/definitions/phandle + maxItems: 1 deprecated: true fsl,usbphy: diff --git a/Documentation/devicetree/bindings/usb/cypress,hx3.yaml b/Documentation/devicetree/bindings/usb/cypress,hx3.yaml index 47add0d85fb891..28096619a88271 100644 --- a/Documentation/devicetree/bindings/usb/cypress,hx3.yaml +++ b/Documentation/devicetree/bindings/usb/cypress,hx3.yaml @@ -1,4 +1,4 @@ -# SPDX-License-Identifier: GPL-2.0-only or BSD-2-Clause +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause %YAML 1.2 --- $id: http://devicetree.org/schemas/usb/cypress,hx3.yaml# diff --git a/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml b/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml index bb373eb025a5f9..00f87a558c7dd3 100644 --- a/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml +++ b/Documentation/devicetree/bindings/usb/dwc3-xilinx.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Xilinx SuperSpeed DWC3 USB SoC controller maintainers: - - Piyush Mehta + - Mubin Sayyed + - Radhey Shyam Pandey properties: compatible: diff --git a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml index f9410eb76a621a..8b25b9a01ced35 100644 --- a/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml +++ b/Documentation/devicetree/bindings/usb/fcs,fsa4480.yaml @@ -27,13 +27,8 @@ properties: vcc-supply: description: power supply (2.7V-5.5V) - mode-switch: - description: Flag the port as possible handle of altmode switching - type: boolean - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean + mode-switch: true + orientation-switch: true port: $ref: /schemas/graph.yaml#/$defs/port-base @@ -79,6 +74,9 @@ required: - reg - port +allOf: + - $ref: usb-switch.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/generic-ehci.yaml b/Documentation/devicetree/bindings/usb/generic-ehci.yaml index 87986c45be88ef..2ed178f16a7822 100644 --- a/Documentation/devicetree/bindings/usb/generic-ehci.yaml +++ b/Documentation/devicetree/bindings/usb/generic-ehci.yaml @@ -77,6 +77,7 @@ properties: - const: usb-ehci - enum: - generic-ehci + - marvell,ac5-ehci - marvell,armada-3700-ehci - marvell,orion-ehci - nuvoton,npcm750-ehci diff --git a/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml index d3b2b666ec2a4c..88e1607cf053ac 100644 --- a/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml +++ b/Documentation/devicetree/bindings/usb/gpio-sbu-mux.yaml @@ -33,13 +33,8 @@ properties: vcc-supply: description: power supply - mode-switch: - description: Flag the port as possible handle of altmode switching - type: boolean - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean + mode-switch: true + orientation-switch: true port: $ref: /schemas/graph.yaml#/properties/port @@ -54,6 +49,9 @@ required: - orientation-switch - port +allOf: + - $ref: usb-switch.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/ite,it5205.yaml b/Documentation/devicetree/bindings/usb/ite,it5205.yaml new file mode 100644 index 00000000000000..36ec4251b5f208 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/ite,it5205.yaml @@ -0,0 +1,72 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/ite,it5205.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ITE IT5202 Type-C USB Alternate Mode Passive MUX + +maintainers: + - AngeloGioacchino Del Regno + - Tianping Fang + +properties: + compatible: + const: ite,it5205 + + reg: + maxItems: 1 + + vcc-supply: + description: Power supply for VCC pin (3.3V) + + mode-switch: + description: Flag the port as possible handle of altmode switching + type: boolean + + orientation-switch: + description: Flag the port as possible handler of orientation switching + type: boolean + + ite,ovp-enable: + description: Enable Over Voltage Protection functionality + type: boolean + + port: + $ref: /schemas/graph.yaml#/properties/port + description: + A port node to link the IT5205 to a TypeC controller for the purpose of + handling altmode muxing and orientation switching. + +required: + - compatible + - reg + - orientation-switch + - port + +additionalProperties: false + +examples: + - | + #include + i2c2 { + #address-cells = <1>; + #size-cells = <0>; + + typec-mux@48 { + compatible = "ite,it5205"; + reg = <0x48>; + + mode-switch; + orientation-switch; + + vcc-supply = <&mt6359_vibr_ldo_reg>; + + port { + it5205_usbss_sbu: endpoint { + remote-endpoint = <&typec_controller>; + }; + }; + }; + }; +... diff --git a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml index a59d91243ac836..d4e187c78a0b52 100644 --- a/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml +++ b/Documentation/devicetree/bindings/usb/mediatek,mtu3.yaml @@ -185,7 +185,10 @@ properties: 2 - used by mt2712 etc, revision 2 with following IPM rule; 101 - used by mt8183, specific 1.01; 102 - used by mt8192, specific 1.02; - enum: [1, 2, 101, 102] + 103 - used by mt8195, IP0, specific 1.03; + 105 - used by mt8195, IP2, specific 1.05; + 106 - used by mt8195, IP3, specific 1.06; + enum: [1, 2, 101, 102, 103, 105, 106] mediatek,u3p-dis-msk: $ref: /schemas/types.yaml#/definitions/uint32 diff --git a/Documentation/devicetree/bindings/usb/microchip,usb5744.yaml b/Documentation/devicetree/bindings/usb/microchip,usb5744.yaml index 6d4cfd943f5847..e2a72deae77601 100644 --- a/Documentation/devicetree/bindings/usb/microchip,usb5744.yaml +++ b/Documentation/devicetree/bindings/usb/microchip,usb5744.yaml @@ -16,8 +16,9 @@ description: USB 2.0 traffic. maintainers: - - Piyush Mehta - Michal Simek + - Mubin Sayyed + - Radhey Shyam Pandey properties: compatible: @@ -71,8 +72,6 @@ allOf: i2c-bus: false else: $ref: /schemas/usb/usb-device.yaml - required: - - peer-hub additionalProperties: false diff --git a/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml b/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml index eee548ac1abea3..d805dde80796f3 100644 --- a/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml +++ b/Documentation/devicetree/bindings/usb/nxp,ptn36502.yaml @@ -20,13 +20,8 @@ properties: vdd18-supply: description: Power supply for VDD18 pin - retimer-switch: - description: Flag the port as possible handle of SuperSpeed signals retiming - type: boolean - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean + orientation-switch: true + retimer-switch: true ports: $ref: /schemas/graph.yaml#/properties/ports @@ -49,6 +44,9 @@ required: - compatible - reg +allOf: + - $ref: usb-switch.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/onnn,nb7vpq904m.yaml b/Documentation/devicetree/bindings/usb/onnn,nb7vpq904m.yaml index c0201da002f629..589914d22bf250 100644 --- a/Documentation/devicetree/bindings/usb/onnn,nb7vpq904m.yaml +++ b/Documentation/devicetree/bindings/usb/onnn,nb7vpq904m.yaml @@ -21,14 +21,8 @@ properties: description: power supply (1.8V) enable-gpios: true - - retimer-switch: - description: Flag the port as possible handle of SuperSpeed signals retiming - type: boolean - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean + orientation-switch: true + retimer-switch: true ports: $ref: /schemas/graph.yaml#/properties/ports @@ -95,6 +89,9 @@ required: - compatible - reg +allOf: + - $ref: usb-switch.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/qcom,pmic-typec.yaml b/Documentation/devicetree/bindings/usb/qcom,pmic-typec.yaml index 55df3129a0bc73..6c0c6b3376930f 100644 --- a/Documentation/devicetree/bindings/usb/qcom,pmic-typec.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,pmic-typec.yaml @@ -15,6 +15,7 @@ description: properties: compatible: enum: + - qcom,pmi632-typec - qcom,pm8150b-typec connector: @@ -24,9 +25,11 @@ properties: reg: description: Type-C port and pdphy SPMI register base offsets + minItems: 1 maxItems: 2 interrupts: + minItems: 8 items: - description: Type-C CC attach notification, VBUS error, tCCDebounce done - description: Type-C VCONN powered @@ -46,6 +49,7 @@ properties: - description: Power Domain Fast Role Swap event interrupt-names: + minItems: 8 items: - const: or-rid-detect-change - const: vpd-detect @@ -81,7 +85,33 @@ required: - interrupts - interrupt-names - vdd-vbus-supply - - vdd-pdphy-supply + +allOf: + - if: + properties: + compatible: + contains: + enum: + - qcom,pmi632-typec + then: + properties: + reg: + maxItems: 1 + interrupts: + maxItems: 8 + interrupt-names: + maxItems: 8 + vdd-pdphy-supply: false + else: + properties: + reg: + maxItems: 2 + interrupts: + minItems: 16 + interrupt-names: + maxItems: 16 + required: + - vdd-pdphy-supply additionalProperties: false diff --git a/Documentation/devicetree/bindings/usb/qcom,wcd939x-usbss.yaml b/Documentation/devicetree/bindings/usb/qcom,wcd939x-usbss.yaml index 7ddfd3313a1858..96346723f3e9c9 100644 --- a/Documentation/devicetree/bindings/usb/qcom,wcd939x-usbss.yaml +++ b/Documentation/devicetree/bindings/usb/qcom,wcd939x-usbss.yaml @@ -35,13 +35,8 @@ properties: vdd-supply: description: USBSS VDD power supply - mode-switch: - description: Flag the port as possible handle of altmode switching - type: boolean - - orientation-switch: - description: Flag the port as possible handler of orientation switching - type: boolean + mode-switch: true + orientation-switch: true ports: $ref: /schemas/graph.yaml#/properties/ports @@ -63,6 +58,9 @@ required: - reg - ports +allOf: + - $ref: usb-switch.yaml# + additionalProperties: false examples: diff --git a/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml b/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml index fec5651f560296..f6e6d084d1c5a7 100644 --- a/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml +++ b/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml @@ -14,7 +14,10 @@ properties: const: ti,am62-usb reg: - maxItems: 1 + minItems: 1 + items: + - description: USB CFG register space + - description: USB PHY2 register space ranges: true @@ -82,7 +85,8 @@ examples: usbss1: usb@f910000 { compatible = "ti,am62-usb"; - reg = <0x00 0x0f910000 0x00 0x800>; + reg = <0x00 0x0f910000 0x00 0x800>, + <0x00 0x0f918000 0x00 0x400>; clocks = <&k3_clks 162 3>; clock-names = "ref"; ti,syscon-phy-pll-refclk = <&wkup_conf 0x4018>; diff --git a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml index 6734f4d3aa789f..9b3ea23654af6e 100644 --- a/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml +++ b/Documentation/devicetree/bindings/usb/usb-nop-xceiv.yaml @@ -37,10 +37,11 @@ properties: description: Should specify the GPIO detecting a VBus insertion maxItems: 1 - vbus-regulator: - description: Should specify the regulator supplying current drawn from - the VBus line. - $ref: /schemas/types.yaml#/definitions/phandle + vbus-supply: + description: regulator supplying VBUS. It will be enabled and disabled + dynamically in OTG mode. If the regulator is controlled by a + GPIO line, this should be modeled as a regulator-fixed and + referenced by this supply. wakeup-source: description: @@ -65,7 +66,7 @@ examples: vcc-supply = <&hsusb1_vcc_regulator>; reset-gpios = <&gpio1 7 GPIO_ACTIVE_LOW>; vbus-detect-gpio = <&gpio2 13 GPIO_ACTIVE_HIGH>; - vbus-regulator = <&vbus_regulator>; + vbus-supply = <&vbus_regulator>; #phy-cells = <0>; }; diff --git a/Documentation/devicetree/bindings/usb/usb-switch.yaml b/Documentation/devicetree/bindings/usb/usb-switch.yaml new file mode 100644 index 00000000000000..da76118e73a53c --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-switch.yaml @@ -0,0 +1,67 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/usb/usb-switch.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: USB Orientation and Mode Switches Common Properties + +maintainers: + - Greg Kroah-Hartman + +description: + Common properties for devices handling USB mode and orientation switching. + +properties: + mode-switch: + description: Possible handler of altmode switching + type: boolean + + orientation-switch: + description: Possible handler of orientation switching + type: boolean + + retimer-switch: + description: Possible handler of SuperSpeed signals retiming + type: boolean + + port: + $ref: /schemas/graph.yaml#/properties/port + description: + A port node to link the device to a TypeC controller for the purpose of + handling altmode muxing and orientation switching. + + ports: + $ref: /schemas/graph.yaml#/properties/ports + properties: + port@0: + $ref: /schemas/graph.yaml#/properties/port + description: + Super Speed (SS) Output endpoint to the Type-C connector + + port@1: + $ref: /schemas/graph.yaml#/$defs/port-base + description: + Super Speed (SS) Input endpoint from the Super-Speed PHY + unevaluatedProperties: false + + properties: + endpoint: + $ref: /schemas/graph.yaml#/$defs/endpoint-base + unevaluatedProperties: false + properties: + data-lanes: + $ref: /schemas/types.yaml#/definitions/uint32-array + minItems: 1 + maxItems: 8 + uniqueItems: true + items: + maximum: 8 + +oneOf: + - required: + - port + - required: + - ports + +additionalProperties: true diff --git a/Documentation/devicetree/bindings/usb/usb.yaml b/Documentation/devicetree/bindings/usb/usb.yaml index 326b14f05d1c41..1761b7aa92f052 100644 --- a/Documentation/devicetree/bindings/usb/usb.yaml +++ b/Documentation/devicetree/bindings/usb/usb.yaml @@ -25,6 +25,8 @@ properties: usb-phy: $ref: /schemas/types.yaml#/definitions/phandle-array + items: + maxItems: 1 description: List of all the USB PHYs on this HCD to be accepted by the legacy USB Physical Layer subsystem. diff --git a/Documentation/devicetree/bindings/usb/xlnx,usb2.yaml b/Documentation/devicetree/bindings/usb/xlnx,usb2.yaml index 868dffe314bcba..a7f75fe366652b 100644 --- a/Documentation/devicetree/bindings/usb/xlnx,usb2.yaml +++ b/Documentation/devicetree/bindings/usb/xlnx,usb2.yaml @@ -7,7 +7,8 @@ $schema: http://devicetree.org/meta-schemas/core.yaml# title: Xilinx udc controller maintainers: - - Piyush Mehta + - Mubin Sayyed + - Radhey Shyam Pandey properties: compatible: diff --git a/Documentation/devicetree/bindings/vendor-prefixes.yaml b/Documentation/devicetree/bindings/vendor-prefixes.yaml index 1a0dc04f1db478..280e22f51953fc 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.yaml +++ b/Documentation/devicetree/bindings/vendor-prefixes.yaml @@ -39,6 +39,8 @@ patternProperties: description: ShenZhen Asia Better Technology Ltd. "^acbel,.*": description: Acbel Polytech Inc. + "^acelink,.*": + description: Acelink Technology Co., Ltd. "^acer,.*": description: Acer Inc. "^acme,.*": @@ -61,6 +63,8 @@ patternProperties: description: Analog Devices, Inc. "^adieng,.*": description: ADI Engineering, Inc. + "^admatec,.*": + description: admatec GmbH "^advantech,.*": description: Advantech Corporation "^aeroflexgaisler,.*": @@ -107,6 +111,8 @@ patternProperties: description: Amlogic, Inc. "^ampere,.*": description: Ampere Computing LLC + "^amphenol,.*": + description: Amphenol Advanced Sensors "^ampire,.*": description: Ampire Co., Ltd. "^ams,.*": @@ -159,6 +165,8 @@ patternProperties: description: ASPEED Technology Inc. "^asrock,.*": description: ASRock Inc. + "^asteralabs,.*": + description: Astera Labs, Inc. "^asus,.*": description: AsusTek Computer Inc. "^atheros,.*": @@ -500,6 +508,8 @@ patternProperties: description: FocalTech Systems Co.,Ltd "^forlinx,.*": description: Baoding Forlinx Embedded Technology Co., Ltd. + "^freebox,.*": + description: Freebox SAS "^freecom,.*": description: Freecom Gmbh "^frida,.*": @@ -719,6 +729,8 @@ patternProperties: description: JetHome (IP Sokolov P.A.) "^jianda,.*": description: Jiandangjing Technology Co., Ltd. + "^jide,.*": + description: Jide Tech "^joz,.*": description: JOZ BV "^kam,.*": @@ -911,6 +923,8 @@ patternProperties: description: Miyoo "^mntre,.*": description: MNT Research GmbH + "^mobileye,.*": + description: Mobileye Vision Technologies Ltd. "^modtronix,.*": description: Modtronix Engineering "^moortec,.*": @@ -1297,6 +1311,8 @@ patternProperties: description: Skyworks Solutions, Inc. "^smartlabs,.*": description: SmartLabs LLC + "^smartrg,.*": + description: SmartRG, Inc. "^smi,.*": description: Silicon Motion Technology Corporation "^smsc,.*": diff --git a/Documentation/devicetree/bindings/w1/w1-uart.yaml b/Documentation/devicetree/bindings/w1/w1-uart.yaml new file mode 100644 index 00000000000000..bd7c62d780b82d --- /dev/null +++ b/Documentation/devicetree/bindings/w1/w1-uart.yaml @@ -0,0 +1,59 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/w1/w1-uart.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: UART 1-Wire Bus + +maintainers: + - Christoph Winklhofer + +description: | + UART 1-wire bus. Utilizes the UART interface via the Serial Device Bus + to create the 1-Wire timing patterns. + + The UART peripheral must support full-duplex and operate in open-drain + mode. The timing patterns are generated by a specific combination of + baud-rate and transmitted byte, which corresponds to a 1-Wire read bit, + write bit or reset pulse. + + The default baud-rate for reset and presence detection is 9600 and for + a 1-Wire read or write operation 115200. In case the actual baud-rate + is different from the requested one, the transmitted byte is adapted + to generate the 1-Wire timing patterns. + + https://www.analog.com/en/technical-articles/using-a-uart-to-implement-a-1wire-bus-master.html + +properties: + compatible: + const: w1-uart + + reset-bps: + default: 9600 + description: + The baud rate for the 1-Wire reset and presence detect. + + write-0-bps: + default: 115200 + description: + The baud rate for the 1-Wire write-0 cycle. + + write-1-bps: + default: 115200 + description: + The baud rate for the 1-Wire write-1 and read cycle. + +required: + - compatible + +additionalProperties: + type: object + +examples: + - | + serial { + onewire { + compatible = "w1-uart"; + }; + }; diff --git a/Documentation/devicetree/bindings/writing-schema.rst b/Documentation/devicetree/bindings/writing-schema.rst index 0a6cf19a14599b..7e71cdd1d6ded6 100644 --- a/Documentation/devicetree/bindings/writing-schema.rst +++ b/Documentation/devicetree/bindings/writing-schema.rst @@ -31,7 +31,7 @@ $schema Indicates the meta-schema the schema file adheres to. title - A one-line description on the contents of the binding schema. + A one-line description of the hardware being described in the binding schema. maintainers A DT specific property. Contains a list of email address(es) @@ -39,7 +39,7 @@ maintainers description Optional. A multi-line text block containing any detailed - information about this binding. It should contain things such as what the block + information about this hardware. It should contain things such as what the block or device does, standards the device conforms to, and links to datasheets for more information. @@ -71,9 +71,31 @@ required A list of DT properties from the 'properties' section that must always be present. +additionalProperties / unevaluatedProperties + Keywords controlling how schema will validate properties not matched by this + schema's 'properties' or 'patternProperties'. Each schema is supposed to + have exactly one of these keywords in top-level part, so either + additionalProperties or unevaluatedProperties. Nested nodes, so properties + being objects, are supposed to have one as well. + + * additionalProperties: false + Most common case, where no additional schema is referenced or if this + binding allows subset of properties from other referenced schemas. + + * unevaluatedProperties: false + Used when this binding references other schema whose all properties + should be allowed. + + * additionalProperties: true + Rare case, used for schemas implementing common set of properties. Such + schemas are supposed to be referenced by other schemas, which then use + 'unevaluatedProperties: false'. Typically bus or common-part schemas. + 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. + Optional. A list of one or more DTS hunks implementing this binding only. + Example should not contain unrelated device nodes, e.g. consumer nodes in a + provider binding, other nodes referenced by phandle. + Note: YAML doesn't allow leading tabs, so spaces must be used instead. Unless noted otherwise, all properties are required. diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 6ad72ac6861bdf..d6f7efefea4212 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -341,6 +341,51 @@ Typedefs with function prototypes can also be documented:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Object-like macro documentation +------------------------------- + +Object-like macros are distinct from function-like macros. They are +differentiated by whether the macro name is immediately followed by a +left parenthesis ('(') for function-like macros or not followed by one +for object-like macros. + +Function-like macros are handled like functions by ``scripts/kernel-doc``. +They may have a parameter list. Object-like macros have do not have a +parameter list. + +The general format of an object-like macro kernel-doc comment is:: + + /** + * define object_name - Brief description. + * + * Description of the object. + */ + +Example:: + + /** + * define MAX_ERRNO - maximum errno value that is supported + * + * Kernel pointers have redundant information, so we can use a + * scheme where we can return either an error code or a normal + * pointer with the same return value. + */ + #define MAX_ERRNO 4095 + +Example:: + + /** + * define DRM_GEM_VRAM_PLANE_HELPER_FUNCS - \ + * Initializes struct drm_plane_helper_funcs for VRAM handling + * + * This macro initializes struct drm_plane_helper_funcs to use the + * respective helper functions. + */ + #define DRM_GEM_VRAM_PLANE_HELPER_FUNCS \ + .prepare_fb = drm_gem_vram_plane_helper_prepare_fb, \ + .cleanup_fb = drm_gem_vram_plane_helper_cleanup_fb + + Highlights and cross-references ------------------------------- diff --git a/Documentation/doc-guide/maintainer-profile.rst b/Documentation/doc-guide/maintainer-profile.rst index 755d39f0d40753..db3636d0d71d6a 100644 --- a/Documentation/doc-guide/maintainer-profile.rst +++ b/Documentation/doc-guide/maintainer-profile.rst @@ -27,6 +27,13 @@ documentation and ensure that no new errors or warnings have been introduced. Generating HTML documents and looking at the result will help to avoid unsightly misunderstandings about how things will be rendered. +All new documentation (including additions to existing documents) should +ideally justify who the intended target audience is somewhere in the +changelog; this way, we ensure that the documentation ends up in the correct +place. Some possible categories are: kernel developers (experts or +beginners), userspace programmers, end users and/or system administrators, +and distributors. + Key cycle dates --------------- diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst index 3d125fb4139d24..709e19821a16bf 100644 --- a/Documentation/doc-guide/sphinx.rst +++ b/Documentation/doc-guide/sphinx.rst @@ -63,8 +63,7 @@ Image output ------------ The kernel documentation build system contains an extension that -handles images on both GraphViz and SVG formats (see -:ref:`sphinx_kfigure`). +handles images in both GraphViz and SVG formats (see :ref:`sphinx_kfigure`). For it to work, you need to install both GraphViz and ImageMagick packages. If those packages are not installed, the build system will @@ -108,7 +107,7 @@ further info. Checking for Sphinx dependencies -------------------------------- -There's a script that automatically check for Sphinx dependencies. If it can +There's a script that automatically checks for Sphinx dependencies. If it can recognize your distribution, it will also give a hint about the install command line options for your distro:: @@ -283,7 +282,7 @@ Here are some specific guidelines for the kernel documentation: from highlighting. For a short snippet of code embedded in the text, use \`\`. -the C domain +The C domain ------------ The **Sphinx C Domain** (name c) is suited for documentation of C API. E.g. a diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index d55384b106bd4e..5c7e8194bef92b 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -517,6 +517,3 @@ Public Functions Provided .. kernel-doc:: arch/x86/include/asm/io.h :internal: - -.. kernel-doc:: lib/pci_iomap.c - :export: diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index c5f99d834ec56a..7be8b8dd5f00ad 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -420,6 +420,7 @@ POWER devm_reboot_mode_unregister() PWM + devm_pwmchip_alloc() devm_pwmchip_add() devm_pwm_get() devm_fwnode_pwm_get() @@ -462,7 +463,7 @@ SLAVE DMA ENGINE SPI devm_spi_alloc_master() devm_spi_alloc_slave() - devm_spi_register_master() + devm_spi_register_controller() WATCHDOG devm_watchdog_register_device() diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index 49c0a951265320..8d2b79f696c1fb 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -24,7 +24,8 @@ How to support a new FPGA device -------------------------------- To add another FPGA manager, write a driver that implements a set of ops. The -probe function calls fpga_mgr_register() or fpga_mgr_register_full(), such as:: +probe function calls ``fpga_mgr_register()`` or ``fpga_mgr_register_full()``, +such as:: static const struct fpga_manager_ops socfpga_fpga_ops = { .write_init = socfpga_fpga_ops_configure_init, @@ -69,10 +70,11 @@ probe function calls fpga_mgr_register() or fpga_mgr_register_full(), such as:: } Alternatively, the probe function could call one of the resource managed -register functions, devm_fpga_mgr_register() or devm_fpga_mgr_register_full(). -When these functions are used, the parameter syntax is the same, but the call -to fpga_mgr_unregister() should be removed. In the above example, the -socfpga_fpga_remove() function would not be required. +register functions, ``devm_fpga_mgr_register()`` or +``devm_fpga_mgr_register_full()``. When these functions are used, the +parameter syntax is the same, but the call to ``fpga_mgr_unregister()`` should be +removed. In the above example, the ``socfpga_fpga_remove()`` function would not be +required. The ops will implement whatever device specific register writes are needed to do the programming sequence for this particular FPGA. These ops return 0 for @@ -125,15 +127,19 @@ API for implementing a new FPGA Manager driver * struct fpga_manager - the FPGA manager struct * struct fpga_manager_ops - Low level FPGA manager driver ops * struct fpga_manager_info - Parameter structure for fpga_mgr_register_full() -* fpga_mgr_register_full() - Create and register an FPGA manager using the +* __fpga_mgr_register_full() - Create and register an FPGA manager using the fpga_mgr_info structure to provide the full flexibility of options -* fpga_mgr_register() - Create and register an FPGA manager using standard +* __fpga_mgr_register() - Create and register an FPGA manager using standard arguments -* devm_fpga_mgr_register_full() - Resource managed version of - fpga_mgr_register_full() -* devm_fpga_mgr_register() - Resource managed version of fpga_mgr_register() +* __devm_fpga_mgr_register_full() - Resource managed version of + __fpga_mgr_register_full() +* __devm_fpga_mgr_register() - Resource managed version of __fpga_mgr_register() * fpga_mgr_unregister() - Unregister an FPGA manager +Helper macros ``fpga_mgr_register_full()``, ``fpga_mgr_register()``, +``devm_fpga_mgr_register_full()``, and ``devm_fpga_mgr_register()`` are available +to ease the registration. + .. kernel-doc:: include/linux/fpga/fpga-mgr.h :functions: fpga_mgr_states @@ -147,16 +153,16 @@ API for implementing a new FPGA Manager driver :functions: fpga_manager_info .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_register_full + :functions: __fpga_mgr_register_full .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_register + :functions: __fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: devm_fpga_mgr_register_full + :functions: __devm_fpga_mgr_register_full .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: devm_fpga_mgr_register + :functions: __devm_fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_unregister diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 3e588b9d678cf9..ab56ab0dd7a693 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -222,9 +222,9 @@ Use the following calls to access GPIOs from an atomic context:: int gpiod_get_value(const struct gpio_desc *desc); void gpiod_set_value(struct gpio_desc *desc, int value); -The values are boolean, zero for low, nonzero for high. When reading the value -of an output pin, the value returned should be what's seen on the pin. That -won't always match the specified output value, because of issues including +The values are boolean, zero for inactive, nonzero for active. When reading the +value of an output pin, the value returned should be what's seen on the pin. +That won't always match the specified output value, because of issues including open-drain signaling and output latencies. The get/set calls do not return errors because "invalid GPIO" should have been @@ -277,11 +277,11 @@ switch their output to a high impedance value. The consumer should not need to care. (For details read about open drain in driver.rst.) With this, all the gpiod_set_(array)_value_xxx() functions interpret the -parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line +parameter "value" as "active" ("1") or "inactive" ("0"). The physical line level will be driven accordingly. As an example, if the active low property for a dedicated GPIO is set, and the -gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level +gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level will be driven low. To summarize:: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index eba851605388e8..f10decc2c14b65 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -9,110 +9,141 @@ of device drivers. This document is an only somewhat organized collection of some of those interfaces — it will hopefully get better over time! The available subsections can be seen below. + +General information for driver authors +====================================== + +This section contains documentation that should, at some point or other, be +of interest to most developers working on device drivers. + .. toctree:: - :caption: Table of contents - :maxdepth: 2 + :maxdepth: 1 - driver-model/index basics + driver-model/index + device_link infrastructure ioctl - early-userspace/index pm/index - clk + +Useful support libraries +======================== + +This section contains documentation that should, at some point or other, be +of interest to most developers working on device drivers. + +.. toctree:: + :maxdepth: 1 + + early-userspace/index + connector device-io + devfreq dma-buf - device_link component - message-based - infiniband - aperture - frame-buffer - regulator - reset - iio/index - input - usb/index - firewire - pci/index + io-mapping + io_ordering + uio-howto + vfio-mediated-device + vfio + vfio-pci-device-specific-driver-acceptance + +Bus-level documentation +======================= + +.. toctree:: + :maxdepth: 1 + + auxiliary_bus cxl/index - spi - i2c - ipmb - ipmi + eisa + firewire i3c/index - interconnect - devfreq - hsi - edac - scsi - libata - target - mailbox - mtdnand - miscellaneous - mei/index - mtd/index - mmc/index - nvdimm/index - w1 + isa + men-chameleon-bus + pci/index rapidio/index - s390-drivers + slimbus + usb/index + virtio/index vme + w1 + xillybus + + +Subsystem-specific APIs +======================= + +.. toctree:: + :maxdepth: 1 + 80211/index - uio-howto + acpi/index + backlight/lp855x-driver.rst + clk + console + crypto/index + dmaengine/index + dpll + edac firmware/index - pin-control + fpga/index + frame-buffer + aperture + generic-counter gpio/index + hsi + hte/index + i2c + iio/index + infiniband + input + interconnect + ipmb + ipmi + libata + mailbox md/index media/index + mei/index + memory-devices/index + message-based misc_devices + miscellaneous + mmc/index + mtd/index + mtdnand nfc/index - dmaengine/index - slimbus - soundwire/index - thermal/index - fpga/index - acpi/index - auxiliary_bus - backlight/lp855x-driver.rst - connector - console - eisa - isa - io-mapping - io_ordering - generic-counter - memory-devices/index - men-chameleon-bus ntb + nvdimm/index nvmem parport-lowlevel + phy/index + pin-control + pldmfw/index pps ptp - phy/index pwm - pldmfw/index + regulator + reset rfkill + s390-drivers + scsi serial/index sm501 + soundwire/index + spi surface_aggregator/index switchtec sync_file + target + tee + thermal/index tty/index - vfio-mediated-device - vfio - vfio-pci-device-specific-driver-acceptance - virtio/index + wbrf + wmi xilinx/index - xillybus zorro - hte/index - wmi - dpll - wbrf - crypto/index - tee .. only:: subproject and html diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst index 776eec72bc80a1..5d4451339b7fbc 100644 --- a/Documentation/driver-api/media/drivers/ccs/ccs.rst +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -2,59 +2,16 @@ .. include:: +.. _media-ccs-driver: + MIPI CCS camera sensor driver ============================= The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS `_ compliant -camera sensors. It exposes three sub-devices representing the pixel array, -the binner and the scaler. - -As the capabilities of individual devices vary, the driver exposes -interfaces based on the capabilities that exist in hardware. - -Pixel Array sub-device ----------------------- - -The pixel array sub-device represents the camera sensor's pixel matrix, as well -as analogue crop functionality present in many compliant devices. The analogue -crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the -entity. The size of the pixel matrix can be obtained by getting the -``V4L2_SEL_TGT_NATIVE_SIZE`` target. - -Binner ------- - -The binner sub-device represents the binning functionality on the sensor. For -that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the -sink pad (0). - -Additionally, if a device has no scaler or digital crop functionality, the -source pad (1) exposes another digital crop selection rectangle that can only -crop at the end of the lines and frames. - -Scaler ------- - -The scaler sub-device represents the digital crop and scaling functionality of -the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to -configure the digital crop on the sink pad (0) when digital crop is supported. -Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the -sink pad (0) as well. - -Additionally, if the scaler sub-device exists, its source pad (1) exposes -another digital crop selection rectangle that can only crop at the end of the -lines and frames. - -Digital and analogue crop -------------------------- - -Digital crop functionality is referred to as cropping that effectively works by -dropping some data on the floor. Analogue crop, on the other hand, means that -the cropped information is never retrieved. In case of camera sensors, the -analogue data is never read from the pixel matrix that are outside the -configured selection rectangle that designates crop. The difference has an -effect in device timing and likely also in power consumption. +camera sensors. + +Also see :ref:`the CCS driver UAPI documentation `. CCS static data --------------- diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 1db2ba27c54c3d..13aec460e802f6 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -229,7 +229,7 @@ Asynchronous sub-device notifier for sub-devices ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A driver that registers an asynchronous sub-device may also register an -asynchronous notifier. This is called an asynchronous sub-device notifier andthe +asynchronous notifier. This is called an asynchronous sub-device notifier and the process is similar to that of a bridge driver apart from that the notifier is initialised using :c:func:`v4l2_async_subdev_nf_init` instead. A sub-device notifier may complete only after the V4L2 device becomes available, i.e. there's diff --git a/Documentation/driver-api/pci/pci.rst b/Documentation/driver-api/pci/pci.rst index 4843cfad4f60bb..aa40b1cc243b84 100644 --- a/Documentation/driver-api/pci/pci.rst +++ b/Documentation/driver-api/pci/pci.rst @@ -4,6 +4,12 @@ PCI Support Library .. kernel-doc:: drivers/pci/pci.c :export: +.. kernel-doc:: drivers/pci/iomap.c + :export: + +.. kernel-doc:: drivers/pci/devres.c + :export: + .. kernel-doc:: drivers/pci/pci-driver.c :export: diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index 3c28ccc4b61133..b41b1c56477f3d 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -143,11 +143,12 @@ to implement the pwm_*() functions itself. This means that it's impossible to have multiple PWM drivers in the system. For this reason it's mandatory for new drivers to use the generic PWM framework. -A new PWM controller/chip can be added using pwmchip_add() and removed -again with pwmchip_remove(). pwmchip_add() takes a filled in struct -pwm_chip as argument which provides a description of the PWM chip, the -number of PWM devices provided by the chip and the chip-specific -implementation of the supported PWM operations to the framework. +A new PWM controller/chip can be allocated using pwmchip_alloc(), then +registered using pwmchip_add() and removed again with pwmchip_remove(). To undo +pwmchip_alloc() use pwmchip_put(). pwmchip_add() takes a filled in struct +pwm_chip as argument which provides a description of the PWM chip, the number +of PWM devices provided by the chip and the chip-specific implementation of the +supported PWM operations to the framework. When implementing polarity support in a PWM driver, make sure to respect the signal conventions in the PWM framework. By definition, normal polarity diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst index b432a2de45d37b..2a794484f62c97 100644 --- a/Documentation/driver-api/soundwire/stream.rst +++ b/Documentation/driver-api/soundwire/stream.rst @@ -324,12 +324,12 @@ framework, this stream state is linked to .hw_params() operation. int sdw_stream_add_master(struct sdw_bus * bus, struct sdw_stream_config * stream_config, - struct sdw_ports_config * ports_config, + const struct sdw_ports_config * ports_config, struct sdw_stream_runtime * stream); int sdw_stream_add_slave(struct sdw_slave * slave, struct sdw_stream_config * stream_config, - struct sdw_ports_config * ports_config, + const struct sdw_ports_config * ports_config, struct sdw_stream_runtime * stream); diff --git a/Documentation/driver-api/tty/console.rst b/Documentation/driver-api/tty/console.rst new file mode 100644 index 00000000000000..4348e36cd33b34 --- /dev/null +++ b/Documentation/driver-api/tty/console.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +Console +======= + +.. contents:: :local: + +Struct Console +============== + +.. kernel-doc:: include/linux/console.h + :identifiers: console cons_flags + +Internals +--------- + +.. kernel-doc:: include/linux/console.h + :identifiers: nbcon_state nbcon_prio nbcon_context nbcon_write_context + +Struct Consw +============ + +.. kernel-doc:: include/linux/console.h + :identifiers: consw + +Console functions +================= + +.. kernel-doc:: include/linux/console.h + :identifiers: console_srcu_read_flags console_srcu_write_flags + console_is_registered for_each_console_srcu for_each_console + +.. kernel-doc:: drivers/tty/vt/selection.c + :export: +.. kernel-doc:: drivers/tty/vt/vt.c + :export: + +Internals +--------- + +.. kernel-doc:: drivers/tty/vt/selection.c + :internal: +.. kernel-doc:: drivers/tty/vt/vt.c + :internal: diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst index b490da11f257fc..c1ffe3d1ec4699 100644 --- a/Documentation/driver-api/tty/index.rst +++ b/Documentation/driver-api/tty/index.rst @@ -38,6 +38,7 @@ In-detail description of the named TTY structures is in separate documents: tty_buffer tty_ioctl tty_internals + console Writing TTY Driver ================== diff --git a/Documentation/fault-injection/index.rst b/Documentation/fault-injection/index.rst index 8408a8a91b3411..a6ea1d1902225c 100644 --- a/Documentation/fault-injection/index.rst +++ b/Documentation/fault-injection/index.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 =============== -fault-injection +Fault-injection =============== .. toctree:: diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst index d32c6209685d64..32cbfa864f389b 100644 --- a/Documentation/filesystems/f2fs.rst +++ b/Documentation/filesystems/f2fs.rst @@ -184,29 +184,30 @@ fault_type=%d Support configuring fault injection type, should be enabled with fault_injection option, fault type value is shown below, it supports single or combined type. - =================== =========== - Type_Name Type_Value - =================== =========== - FAULT_KMALLOC 0x000000001 - FAULT_KVMALLOC 0x000000002 - FAULT_PAGE_ALLOC 0x000000004 - FAULT_PAGE_GET 0x000000008 - FAULT_ALLOC_BIO 0x000000010 (obsolete) - FAULT_ALLOC_NID 0x000000020 - FAULT_ORPHAN 0x000000040 - FAULT_BLOCK 0x000000080 - FAULT_DIR_DEPTH 0x000000100 - FAULT_EVICT_INODE 0x000000200 - FAULT_TRUNCATE 0x000000400 - FAULT_READ_IO 0x000000800 - FAULT_CHECKPOINT 0x000001000 - FAULT_DISCARD 0x000002000 - FAULT_WRITE_IO 0x000004000 - FAULT_SLAB_ALLOC 0x000008000 - FAULT_DQUOT_INIT 0x000010000 - FAULT_LOCK_OP 0x000020000 - FAULT_BLKADDR 0x000040000 - =================== =========== + =========================== =========== + Type_Name Type_Value + =========================== =========== + FAULT_KMALLOC 0x000000001 + FAULT_KVMALLOC 0x000000002 + FAULT_PAGE_ALLOC 0x000000004 + FAULT_PAGE_GET 0x000000008 + FAULT_ALLOC_BIO 0x000000010 (obsolete) + FAULT_ALLOC_NID 0x000000020 + FAULT_ORPHAN 0x000000040 + FAULT_BLOCK 0x000000080 + FAULT_DIR_DEPTH 0x000000100 + FAULT_EVICT_INODE 0x000000200 + FAULT_TRUNCATE 0x000000400 + FAULT_READ_IO 0x000000800 + FAULT_CHECKPOINT 0x000001000 + FAULT_DISCARD 0x000002000 + FAULT_WRITE_IO 0x000004000 + FAULT_SLAB_ALLOC 0x000008000 + FAULT_DQUOT_INIT 0x000010000 + FAULT_LOCK_OP 0x000020000 + FAULT_BLKADDR_VALIDITY 0x000040000 + FAULT_BLKADDR_CONSISTENCE 0x000080000 + =========================== =========== mode=%s Control block allocation mode which supports "adaptive" and "lfs". In "lfs" mode, there should be no random writes towards main area. diff --git a/Documentation/filesystems/files.rst b/Documentation/filesystems/files.rst index 9e38e4c221ca5d..eb770f891b275f 100644 --- a/Documentation/filesystems/files.rst +++ b/Documentation/filesystems/files.rst @@ -116,7 +116,7 @@ before and after the reference count increment. This pattern can be seen in get_file_rcu() and __files_get_rcu(). In addition, it isn't possible to access or check fields in struct file -without first aqcuiring a reference on it under rcu lookup. Not doing +without first acquiring a reference on it under rcu lookup. Not doing that was always very dodgy and it was only usable for non-pointer data in struct file. With SLAB_TYPESAFE_BY_RCU it is necessary that callers either first acquire a reference or they must hold the files_lock of the diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index e18bc5ae3b35f8..0ea1e44fa02823 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -98,7 +98,6 @@ Documentation for filesystem implementations. isofs nilfs2 nfs/index - ntfs ntfs3 ocfs2 ocfs2-online-filecheck diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index d5bf4b6b7509b0..e664061ed55dc1 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -29,7 +29,7 @@ prototypes:: char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); struct vfsmount *(*d_automount)(struct path *path); int (*d_manage)(const struct path *, bool); - struct dentry *(*d_real)(struct dentry *, const struct inode *); + struct dentry *(*d_real)(struct dentry *, enum d_real_type type); locking rules: diff --git a/Documentation/filesystems/ntfs.rst b/Documentation/filesystems/ntfs.rst deleted file mode 100644 index 5bb093a26485e0..00000000000000 --- a/Documentation/filesystems/ntfs.rst +++ /dev/null @@ -1,466 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================================ -The Linux NTFS filesystem driver -================================ - - -.. Table of contents - - - Overview - - Web site - - Features - - Supported mount options - - Known bugs and (mis-)features - - Using NTFS volume and stripe sets - - The Device-Mapper driver - - The Software RAID / MD driver - - Limitations when using the MD driver - - -Overview -======== - -Linux-NTFS comes with a number of user-space programs known as ntfsprogs. -These include mkntfs, a full-featured ntfs filesystem format utility, -ntfsundelete used for recovering files that were unintentionally deleted -from an NTFS volume and ntfsresize which is used to resize an NTFS partition. -See the web site for more information. - -To mount an NTFS 1.2/3.x (Windows NT4/2000/XP/2003) volume, use the file -system type 'ntfs'. The driver currently supports read-only mode (with no -fault-tolerance, encryption or journalling) and very limited, but safe, write -support. - -For fault tolerance and raid support (i.e. volume and stripe sets), you can -use the kernel's Software RAID / MD driver. See section "Using Software RAID -with NTFS" for details. - - -Web site -======== - -There is plenty of additional information on the linux-ntfs web site -at http://www.linux-ntfs.org/ - -The web site has a lot of additional information, such as a comprehensive -FAQ, documentation on the NTFS on-disk format, information on the Linux-NTFS -userspace utilities, etc. - - -Features -======== - -- This is a complete rewrite of the NTFS driver that used to be in the 2.4 and - earlier kernels. This new driver implements NTFS read support and is - functionally equivalent to the old ntfs driver and it also implements limited - write support. The biggest limitation at present is that files/directories - cannot be created or deleted. See below for the list of write features that - are so far supported. Another limitation is that writing to compressed files - is not implemented at all. Also, neither read nor write access to encrypted - files is so far implemented. -- The new driver has full support for sparse files on NTFS 3.x volumes which - the old driver isn't happy with. -- The new driver supports execution of binaries due to mmap() now being - supported. -- The new driver supports loopback mounting of files on NTFS which is used by - some Linux distributions to enable the user to run Linux from an NTFS - partition by creating a large file while in Windows and then loopback - mounting the file while in Linux and creating a Linux filesystem on it that - is used to install Linux on it. -- A comparison of the two drivers using:: - - time find . -type f -exec md5sum "{}" \; - - run three times in sequence with each driver (after a reboot) on a 1.4GiB - NTFS partition, showed the new driver to be 20% faster in total time elapsed - (from 9:43 minutes on average down to 7:53). The time spent in user space - was unchanged but the time spent in the kernel was decreased by a factor of - 2.5 (from 85 CPU seconds down to 33). -- The driver does not support short file names in general. For backwards - compatibility, we implement access to files using their short file names if - they exist. The driver will not create short file names however, and a - rename will discard any existing short file name. -- The new driver supports exporting of mounted NTFS volumes via NFS. -- The new driver supports async io (aio). -- The new driver supports fsync(2), fdatasync(2), and msync(2). -- The new driver supports readv(2) and writev(2). -- The new driver supports access time updates (including mtime and ctime). -- The new driver supports truncate(2) and open(2) with O_TRUNC. But at present - only very limited support for highly fragmented files, i.e. ones which have - their data attribute split across multiple extents, is included. Another - limitation is that at present truncate(2) will never create sparse files, - since to mark a file sparse we need to modify the directory entry for the - file and we do not implement directory modifications yet. -- The new driver supports write(2) which can both overwrite existing data and - extend the file size so that you can write beyond the existing data. Also, - writing into sparse regions is supported and the holes are filled in with - clusters. But at present only limited support for highly fragmented files, - i.e. ones which have their data attribute split across multiple extents, is - included. Another limitation is that write(2) will never create sparse - files, since to mark a file sparse we need to modify the directory entry for - the file and we do not implement directory modifications yet. - -Supported mount options -======================= - -In addition to the generic mount options described by the manual page for the -mount command (man 8 mount, also see man 5 fstab), the NTFS driver supports the -following mount options: - -======================= ======================================================= -iocharset=name Deprecated option. Still supported but please use - nls=name in the future. See description for nls=name. - -nls=name Character set to use when returning file names. - Unlike VFAT, NTFS suppresses names that contain - unconvertible characters. Note that most character - sets contain insufficient characters to represent all - possible Unicode characters that can exist on NTFS. - To be sure you are not missing any files, you are - advised to use nls=utf8 which is capable of - representing all Unicode characters. - -utf8= Option no longer supported. Currently mapped to - nls=utf8 but please use nls=utf8 in the future and - make sure utf8 is compiled either as module or into - the kernel. See description for nls=name. - -uid= -gid= -umask= Provide default owner, group, and access mode mask. - These options work as documented in mount(8). By - default, the files/directories are owned by root and - he/she has read and write permissions, as well as - browse permission for directories. No one else has any - access permissions. I.e. the mode on all files is by - default rw------- and for directories rwx------, a - consequence of the default fmask=0177 and dmask=0077. - Using a umask of zero will grant all permissions to - everyone, i.e. all files and directories will have mode - rwxrwxrwx. - -fmask= -dmask= Instead of specifying umask which applies both to - files and directories, fmask applies only to files and - dmask only to directories. - -sloppy= If sloppy is specified, ignore unknown mount options. - Otherwise the default behaviour is to abort mount if - any unknown options are found. - -show_sys_files= If show_sys_files is specified, show the system files - in directory listings. Otherwise the default behaviour - is to hide the system files. - Note that even when show_sys_files is specified, "$MFT" - will not be visible due to bugs/mis-features in glibc. - Further, note that irrespective of show_sys_files, all - files are accessible by name, i.e. you can always do - "ls -l \$UpCase" for example to specifically show the - system file containing the Unicode upcase table. - -case_sensitive= If case_sensitive is specified, treat all file names as - case sensitive and create file names in the POSIX - namespace. Otherwise the default behaviour is to treat - file names as case insensitive and to create file names - in the WIN32/LONG name space. Note, the Linux NTFS - driver will never create short file names and will - remove them on rename/delete of the corresponding long - file name. - Note that files remain accessible via their short file - name, if it exists. If case_sensitive, you will need - to provide the correct case of the short file name. - -disable_sparse= If disable_sparse is specified, creation of sparse - regions, i.e. holes, inside files is disabled for the - volume (for the duration of this mount only). By - default, creation of sparse regions is enabled, which - is consistent with the behaviour of traditional Unix - filesystems. - -errors=opt What to do when critical filesystem errors are found. - Following values can be used for "opt": - - ======== ========================================= - continue DEFAULT, try to clean-up as much as - possible, e.g. marking a corrupt inode as - bad so it is no longer accessed, and then - continue. - recover At present only supported is recovery of - the boot sector from the backup copy. - If read-only mount, the recovery is done - in memory only and not written to disk. - ======== ========================================= - - Note that the options are additive, i.e. specifying:: - - errors=continue,errors=recover - - means the driver will attempt to recover and if that - fails it will clean-up as much as possible and - continue. - -mft_zone_multiplier= Set the MFT zone multiplier for the volume (this - setting is not persistent across mounts and can be - changed from mount to mount but cannot be changed on - remount). Values of 1 to 4 are allowed, 1 being the - default. The MFT zone multiplier determines how much - space is reserved for the MFT on the volume. If all - other space is used up, then the MFT zone will be - shrunk dynamically, so this has no impact on the - amount of free space. However, it can have an impact - on performance by affecting fragmentation of the MFT. - In general use the default. If you have a lot of small - files then use a higher value. The values have the - following meaning: - - ===== ================================= - Value MFT zone size (% of volume size) - ===== ================================= - 1 12.5% - 2 25% - 3 37.5% - 4 50% - ===== ================================= - - Note this option is irrelevant for read-only mounts. -======================= ======================================================= - - -Known bugs and (mis-)features -============================= - -- The link count on each directory inode entry is set to 1, due to Linux not - supporting directory hard links. This may well confuse some user space - applications, since the directory names will have the same inode numbers. - This also speeds up ntfs_read_inode() immensely. And we haven't found any - problems with this approach so far. If you find a problem with this, please - let us know. - - -Please send bug reports/comments/feedback/abuse to the Linux-NTFS development -list at sourceforge: linux-ntfs-dev@lists.sourceforge.net - - -Using NTFS volume and stripe sets -================================= - -For support of volume and stripe sets, you can either use the kernel's -Device-Mapper driver or the kernel's Software RAID / MD driver. The former is -the recommended one to use for linear raid. But the latter is required for -raid level 5. For striping and mirroring, either driver should work fine. - - -The Device-Mapper driver ------------------------- - -You will need to create a table of the components of the volume/stripe set and -how they fit together and load this into the kernel using the dmsetup utility -(see man 8 dmsetup). - -Linear volume sets, i.e. linear raid, has been tested and works fine. Even -though untested, there is no reason why stripe sets, i.e. raid level 0, and -mirrors, i.e. raid level 1 should not work, too. Stripes with parity, i.e. -raid level 5, unfortunately cannot work yet because the current version of the -Device-Mapper driver does not support raid level 5. You may be able to use the -Software RAID / MD driver for raid level 5, see the next section for details. - -To create the table describing your volume you will need to know each of its -components and their sizes in sectors, i.e. multiples of 512-byte blocks. - -For NT4 fault tolerant volumes you can obtain the sizes using fdisk. So for -example if one of your partitions is /dev/hda2 you would do:: - - $ fdisk -ul /dev/hda - - Disk /dev/hda: 81.9 GB, 81964302336 bytes - 255 heads, 63 sectors/track, 9964 cylinders, total 160086528 sectors - Units = sectors of 1 * 512 = 512 bytes - - Device Boot Start End Blocks Id System - /dev/hda1 * 63 4209029 2104483+ 83 Linux - /dev/hda2 4209030 37768814 16779892+ 86 NTFS - /dev/hda3 37768815 46170809 4200997+ 83 Linux - -And you would know that /dev/hda2 has a size of 37768814 - 4209030 + 1 = -33559785 sectors. - -For Win2k and later dynamic disks, you can for example use the ldminfo utility -which is part of the Linux LDM tools (the latest version at the time of -writing is linux-ldm-0.0.8.tar.bz2). You can download it from: - - http://www.linux-ntfs.org/ - -Simply extract the downloaded archive (tar xvjf linux-ldm-0.0.8.tar.bz2), go -into it (cd linux-ldm-0.0.8) and change to the test directory (cd test). You -will find the precompiled (i386) ldminfo utility there. NOTE: You will not be -able to compile this yourself easily so use the binary version! - -Then you would use ldminfo in dump mode to obtain the necessary information:: - - $ ./ldminfo --dump /dev/hda - -This would dump the LDM database found on /dev/hda which describes all of your -dynamic disks and all the volumes on them. At the bottom you will see the -VOLUME DEFINITIONS section which is all you really need. You may need to look -further above to determine which of the disks in the volume definitions is -which device in Linux. Hint: Run ldminfo on each of your dynamic disks and -look at the Disk Id close to the top of the output for each (the PRIVATE HEADER -section). You can then find these Disk Ids in the VBLK DATABASE section in the - components where you will get the LDM Name for the disk that is found in -the VOLUME DEFINITIONS section. - -Note you will also need to enable the LDM driver in the Linux kernel. If your -distribution did not enable it, you will need to recompile the kernel with it -enabled. This will create the LDM partitions on each device at boot time. You -would then use those devices (for /dev/hda they would be /dev/hda1, 2, 3, etc) -in the Device-Mapper table. - -You can also bypass using the LDM driver by using the main device (e.g. -/dev/hda) and then using the offsets of the LDM partitions into this device as -the "Start sector of device" when creating the table. Once again ldminfo would -give you the correct information to do this. - -Assuming you know all your devices and their sizes things are easy. - -For a linear raid the table would look like this (note all values are in -512-byte sectors):: - - # Offset into Size of this Raid type Device Start sector - # volume device of device - 0 1028161 linear /dev/hda1 0 - 1028161 3903762 linear /dev/hdb2 0 - 4931923 2103211 linear /dev/hdc1 0 - -For a striped volume, i.e. raid level 0, you will need to know the chunk size -you used when creating the volume. Windows uses 64kiB as the default, so it -will probably be this unless you changes the defaults when creating the array. - -For a raid level 0 the table would look like this (note all values are in -512-byte sectors):: - - # Offset Size Raid Number Chunk 1st Start 2nd Start - # into of the type of size Device in Device in - # volume volume stripes device device - 0 2056320 striped 2 128 /dev/hda1 0 /dev/hdb1 0 - -If there are more than two devices, just add each of them to the end of the -line. - -Finally, for a mirrored volume, i.e. raid level 1, the table would look like -this (note all values are in 512-byte sectors):: - - # Ofs Size Raid Log Number Region Should Number Source Start Target Start - # in of the type type of log size sync? of Device in Device in - # vol volume params mirrors Device Device - 0 2056320 mirror core 2 16 nosync 2 /dev/hda1 0 /dev/hdb1 0 - -If you are mirroring to multiple devices you can specify further targets at the -end of the line. - -Note the "Should sync?" parameter "nosync" means that the two mirrors are -already in sync which will be the case on a clean shutdown of Windows. If the -mirrors are not clean, you can specify the "sync" option instead of "nosync" -and the Device-Mapper driver will then copy the entirety of the "Source Device" -to the "Target Device" or if you specified multiple target devices to all of -them. - -Once you have your table, save it in a file somewhere (e.g. /etc/ntfsvolume1), -and hand it over to dmsetup to work with, like so:: - - $ dmsetup create myvolume1 /etc/ntfsvolume1 - -You can obviously replace "myvolume1" with whatever name you like. - -If it all worked, you will now have the device /dev/device-mapper/myvolume1 -which you can then just use as an argument to the mount command as usual to -mount the ntfs volume. For example:: - - $ mount -t ntfs -o ro /dev/device-mapper/myvolume1 /mnt/myvol1 - -(You need to create the directory /mnt/myvol1 first and of course you can use -anything you like instead of /mnt/myvol1 as long as it is an existing -directory.) - -It is advisable to do the mount read-only to see if the volume has been setup -correctly to avoid the possibility of causing damage to the data on the ntfs -volume. - - -The Software RAID / MD driver ------------------------------ - -An alternative to using the Device-Mapper driver is to use the kernel's -Software RAID / MD driver. For which you need to set up your /etc/raidtab -appropriately (see man 5 raidtab). - -Linear volume sets, i.e. linear raid, as well as stripe sets, i.e. raid level -0, have been tested and work fine (though see section "Limitations when using -the MD driver with NTFS volumes" especially if you want to use linear raid). -Even though untested, there is no reason why mirrors, i.e. raid level 1, and -stripes with parity, i.e. raid level 5, should not work, too. - -You have to use the "persistent-superblock 0" option for each raid-disk in the -NTFS volume/stripe you are configuring in /etc/raidtab as the persistent -superblock used by the MD driver would damage the NTFS volume. - -Windows by default uses a stripe chunk size of 64k, so you probably want the -"chunk-size 64k" option for each raid-disk, too. - -For example, if you have a stripe set consisting of two partitions /dev/hda5 -and /dev/hdb1 your /etc/raidtab would look like this:: - - raiddev /dev/md0 - raid-level 0 - nr-raid-disks 2 - nr-spare-disks 0 - persistent-superblock 0 - chunk-size 64k - device /dev/hda5 - raid-disk 0 - device /dev/hdb1 - raid-disk 1 - -For linear raid, just change the raid-level above to "raid-level linear", for -mirrors, change it to "raid-level 1", and for stripe sets with parity, change -it to "raid-level 5". - -Note for stripe sets with parity you will also need to tell the MD driver -which parity algorithm to use by specifying the option "parity-algorithm -which", where you need to replace "which" with the name of the algorithm to -use (see man 5 raidtab for available algorithms) and you will have to try the -different available algorithms until you find one that works. Make sure you -are working read-only when playing with this as you may damage your data -otherwise. If you find which algorithm works please let us know (email the -linux-ntfs developers list linux-ntfs-dev@lists.sourceforge.net or drop in on -IRC in channel #ntfs on the irc.freenode.net network) so we can update this -documentation. - -Once the raidtab is setup, run for example raid0run -a to start all devices or -raid0run /dev/md0 to start a particular md device, in this case /dev/md0. - -Then just use the mount command as usual to mount the ntfs volume using for -example:: - - mount -t ntfs -o ro /dev/md0 /mnt/myntfsvolume - -It is advisable to do the mount read-only to see if the md volume has been -setup correctly to avoid the possibility of causing damage to the data on the -ntfs volume. - - -Limitations when using the Software RAID / MD driver ------------------------------------------------------ - -Using the md driver will not work properly if any of your NTFS partitions have -an odd number of sectors. This is especially important for linear raid as all -data after the first partition with an odd number of sectors will be offset by -one or more sectors so if you mount such a partition with write support you -will cause massive damage to the data on the volume which will only become -apparent when you try to use the volume again under Windows. - -So when using linear raid, make sure that all your partitions have an even -number of sectors BEFORE attempting to use it. You have been warned! - -Even better is to simply use the Device-Mapper for linear raid and then you do -not have this problem with odd numbers of sectors. diff --git a/Documentation/filesystems/overlayfs.rst b/Documentation/filesystems/overlayfs.rst index 1c244866041a3c..16551440144183 100644 --- a/Documentation/filesystems/overlayfs.rst +++ b/Documentation/filesystems/overlayfs.rst @@ -145,7 +145,9 @@ filesystem, an overlay filesystem needs to record in the upper filesystem that files have been removed. This is done using whiteouts and opaque directories (non-directories are always opaque). -A whiteout is created as a character device with 0/0 device number. +A whiteout is created as a character device with 0/0 device number or +as a zero-size regular file with the xattr "trusted.overlay.whiteout". + When a whiteout is found in the upper level of a merged directory, any matching name in the lower level is ignored, and the whiteout itself is also hidden. @@ -154,6 +156,13 @@ A directory is made opaque by setting the xattr "trusted.overlay.opaque" to "y". Where the upper filesystem contains an opaque directory, any directory in the lower filesystem with the same name is ignored. +An opaque directory should not conntain any whiteouts, because they do not +serve any purpose. A merge directory containing regular files with the xattr +"trusted.overlay.whiteout", should be additionally marked by setting the xattr +"trusted.overlay.opaque" to "x" on the merge directory itself. +This is needed to avoid the overhead of checking the "trusted.overlay.whiteout" +on all entries during readdir in the common case. + readdir ------- @@ -534,8 +543,9 @@ A lower dir with a regular whiteout will always be handled by the overlayfs mount, so to support storing an effective whiteout file in an overlayfs mount an alternative form of whiteout is supported. This form is a regular, zero-size file with the "overlay.whiteout" xattr set, inside a directory with the -"overlay.whiteouts" xattr set. Such whiteouts are never created by overlayfs, -but can be used by userspace tools (like containers) that generate lower layers. +"overlay.opaque" xattr set to "x" (see `whiteouts and opaque directories`_). +These alternative whiteouts are never created by overlayfs, but can be used by +userspace tools (like containers) that generate lower layers. These alternative whiteouts can be escaped using the standard xattr escape mechanism in order to properly nest to any depth. diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 104c6d047d9b57..c6a6b9df210497 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -1899,8 +1899,8 @@ For more information on mount propagation see: These files provide a method to access a task's comm value. It also allows for a task to set its own or one of its thread siblings comm value. The comm value is limited in size compared to the cmdline value, so writing anything longer -then the kernel's TASK_COMM_LEN (currently 16 chars) will result in a truncated -comm value. +then the kernel's TASK_COMM_LEN (currently 16 chars, including the NUL +terminator) will result in a truncated comm value. 3.7 /proc//task//children - Information about task children diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index eebcc0f9e2bcd1..6e903a903f8f69 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -1264,7 +1264,7 @@ defined: char *(*d_dname)(struct dentry *, char *, int); struct vfsmount *(*d_automount)(struct path *); int (*d_manage)(const struct path *, bool); - struct dentry *(*d_real)(struct dentry *, const struct inode *); + struct dentry *(*d_real)(struct dentry *, enum d_real_type type); }; ``d_revalidate`` @@ -1419,16 +1419,14 @@ defined: the dentry being transited from. ``d_real`` - overlay/union type filesystems implement this method to return - one of the underlying dentries hidden by the overlay. It is - used in two different modes: + overlay/union type filesystems implement this method to return one + of the underlying dentries of a regular file hidden by the overlay. - Called from file_dentry() it returns the real dentry matching - the inode argument. The real dentry may be from a lower layer - already copied up, but still referenced from the file. This - mode is selected with a non-NULL inode argument. + The 'type' argument takes the values D_REAL_DATA or D_REAL_METADATA + for returning the real underlying dentry that refers to the inode + hosting the file's data or metadata respectively. - With NULL inode the topmost real underlying dentry is returned. + For non-regular files, the 'dentry' argument is returned. Each dentry has a pointer to its parent dentry, as well as a hash list of child dentries. Child dentries are basically like files in a diff --git a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv index 882d2518f8ed26..3825f00ca9fe84 100644 --- a/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv +++ b/Documentation/gpu/amdgpu/dgpu-asic-info-table.csv @@ -16,6 +16,7 @@ Radeon (RX|TM) (PRO|WX) Vega /MI25 /V320 /V340L /8200 /9100 /SSG MxGPU, VEGA10, AMD Radeon (Pro) VII /MI50 /MI60, VEGA20, DCE 12, 9.4.0, VCE 4.1.0 / UVD 7.2.0, 4.2.0 MI100, ARCTURUS, *, 9.4.1, VCN 2.5.0, 4.2.2 MI200, ALDEBARAN, *, 9.4.2, VCN 2.6.0, 4.4.0 +MI300, AQUA_VANGARAM, *, 9.4.3, VCN 4.0.3, 4.4.2 AMD Radeon (RX|Pro) 5600(M|XT) /5700 (M|XT|XTB) /W5700, NAVI10, DCN 2.0.0, 10.1.10, VCN 2.0.0, 5.0.0 AMD Radeon (Pro) 5300 /5500XTB/5500(XT|M) /W5500M /W5500, NAVI14, DCN 2.0.0, 10.1.1, VCN 2.0.2, 5.0.2 AMD Radeon RX 6800(XT) /6900(XT) /W6800, SIENNA_CICHLID, DCN 3.0.0, 10.3.0, VCN 3.0.0, 5.2.0 @@ -23,4 +24,5 @@ AMD Radeon RX 6700 XT / 6800M / 6700M, NAVY_FLOUNDER, DCN 3.0.0, 10.3.2, VCN 3.0 AMD Radeon RX 6600(XT) /6600M /W6600 /W6600M, DIMGREY_CAVEFISH, DCN 3.0.2, 10.3.4, VCN 3.0.16, 5.2.4 AMD Radeon RX 6500M /6300M /W6500M /W6300M, BEIGE_GOBY, DCN 3.0.3, 10.3.5, VCN 3.0.33, 5.2.5 AMD Radeon RX 7900 XT /XTX, , DCN 3.2.0, 11.0.0, VCN 4.0.0, 6.0.0 +AMD Radeon RX 7800 XT, , DCN 3.2.0, 11.0.3, VCN 4.0.0, 6.0.3 AMD Radeon RX 7600M (XT) /7700S /7600S, , DCN 3.2.1, 11.0.2, VCN 4.0.4, 6.0.2 diff --git a/Documentation/gpu/amdgpu/display/dcn-blocks.rst b/Documentation/gpu/amdgpu/display/dcn-blocks.rst new file mode 100644 index 00000000000000..a3fbd3ea028bba --- /dev/null +++ b/Documentation/gpu/amdgpu/display/dcn-blocks.rst @@ -0,0 +1,78 @@ +========== +DCN Blocks +========== + +In this section, you will find some extra details about some of the DCN blocks +and the code documentation when it is automatically generated. + +DCHUBBUB +-------- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :internal: + +HUBP +---- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :internal: + +DPP +--- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/hubp.h + :internal: + +MPC +--- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h + :internal: + +OPP +--- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/opp.h + :internal: + +DIO +--- + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h + :doc: overview + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h + :export: + +.. kernel-doc:: drivers/gpu/drm/amd/display/dc/link/hwss/link_hwss_dio.h + :internal: diff --git a/Documentation/gpu/amdgpu/display/display-contributing.rst b/Documentation/gpu/amdgpu/display/display-contributing.rst new file mode 100644 index 00000000000000..fdb2bea01d53a8 --- /dev/null +++ b/Documentation/gpu/amdgpu/display/display-contributing.rst @@ -0,0 +1,168 @@ +.. _display_todos: + +============================== +AMDGPU - Display Contributions +============================== + +First of all, if you are here, you probably want to give some technical +contribution to the display code, and for that, we say thank you :) + +This page summarizes some of the issues you can help with; keep in mind that +this is a static page, and it is always a good idea to try to reach developers +in the amdgfx or some of the maintainers. Finally, this page follows the DRM +way of creating a TODO list; for more information, check +'Documentation/gpu/todo.rst'. + +Gitlab issues +============= + +Users can report issues associated with AMD GPUs at: + +- https://gitlab.freedesktop.org/drm/amd + +Usually, we try to add a proper label to all new tickets to make it easy to +filter issues. If you can reproduce any problem, you could help by adding more +information or fixing the issue. + +Level: diverse + +IGT +=== + +`IGT`_ provides many integration tests that can be run on your GPU. We always +want to pass a large set of tests to increase the test coverage in our CI. If +you wish to contribute to the display code but are unsure where a good place +is, we recommend you run all IGT tests and try to fix any failure you see in +your hardware. Keep in mind that this failure can be an IGT problem or a kernel +issue; it is necessary to analyze case-by-case. + +Level: diverse + +.. _IGT: https://gitlab.freedesktop.org/drm/igt-gpu-tools + +Compilation +=========== + +Fix compilation warnings +------------------------ + +Enable the W1 or W2 warning level in the kernel compilation and try to fix the +issues on the display side. + +Level: Starter + +Fix compilation issues when using um architecture +------------------------------------------------- + +Linux has a User-mode Linux (UML) feature, and the kernel can be compiled to +the **um** architecture. Compiling for **um** can bring multiple advantages +from the test perspective. We currently have some compilation issues in this +area that we need to fix. + +Level: Intermediate + +Code Refactor +============= + +Add prefix to DC functions to improve the debug with ftrace +----------------------------------------------------------- + +The Ftrace debug feature (check 'Documentation/trace/ftrace.rst') is a +fantastic way to check the code path when developers try to make sense of a +bug. Ftrace provides a filter mechanism that can be useful when the developer +has some hunch of which part of the code can cause the issue; for this reason, +if a set of functions has a proper prefix, it becomes easy to create a good +filter. Additionally, prefixes can improve stack trace readability. + +The DC code does not follow some prefix rules, which makes the Ftrace filter +more complicated and reduces the readability of the stack trace. If you want +something simple to start contributing to the display, you can make patches for +adding prefixes to DC functions. To create those prefixes, use part of the file +name as a prefix for all functions in the target file. Check the +'amdgpu_dm_crtc.c` and `amdgpu_dm_plane.c` for some references. However, we +strongly advise not to send huge patches changing these prefixes; otherwise, it +will be hard to review and test, which can generate second thoughts from +maintainers. Try small steps; in case of double, you can ask before you put in +effort. We recommend first looking at folders like dceXYZ, dcnXYZ, basics, +bios, core, clk_mgr, hwss, resource, and irq. + +Level: Starter + +Reduce code duplication +----------------------- + +AMD has an extensive portfolio with various dGPUs and APUs that amdgpu +supports. To maintain the new hardware release cadence, DCE/DCN was designed in +a modular design, making the bring-up for new hardware fast. Over the years, +amdgpu accumulated some technical debt in the code duplication area. For this +task, it would be a good idea to find a tool that can discover code duplication +(including patterns) and use it as guidance to reduce duplications. + +Level: Intermediate + +Make atomic_commit_[check|tail] more readable +--------------------------------------------- + +The functions responsible for atomic commit and tail are intricate and +extensive. In particular `amdgpu_dm_atomic_commit_tail` is a long function and +could benefit from being split into smaller helpers. Improvements in this area +are more than welcome, but keep in mind that changes in this area will affect +all ASICs, meaning that refactoring requires a comprehensive verification; in +other words, this effort can take some time for validation. + +Level: Advanced + +Documentation +============= + +Expand kernel-doc +----------------- + +Many DC functions do not have a proper kernel-doc; understanding a function and +adding documentation is a great way to learn more about the amdgpu driver and +also leave an outstanding contribution to the entire community. + +Level: Starter + +Beyond AMDGPU +============= + +AMDGPU provides features that are not yet enabled in the userspace. This +section highlights some of the coolest display features, which could be enabled +with the userspace developer helper. + +Enable underlay +--------------- + +AMD display has this feature called underlay (which you can read more about at +'Documentation/GPU/amdgpu/display/mpo-overview.rst') which is intended to +save power when playing a video. The basic idea is to put a video in the +underlay plane at the bottom and the desktop in the plane above it with a hole +in the video area. This feature is enabled in ChromeOS, and from our data +measurement, it can save power. + +Level: Unknown + +Adaptive Backlight Modulation (ABM) +----------------------------------- + +ABM is a feature that adjusts the display panel's backlight level and pixel +values depending on the displayed image. This power-saving feature can be very +useful when the system starts to run off battery; since this will impact the +display output fidelity, it would be good if this option was something that +users could turn on or off. + +Level: Unknown + + +HDR & Color management & VRR +---------------------------- + +HDR, Color Management, and VRR are huge topics and it's hard to put these into +concise ToDos. If you are interested in this topic, we recommend checking some +blog posts from the community developers to better understand some of the +specific challenges and people working on the subject. If anyone wants to work +on some particular part, we can try to help with some basic guidance. Finally, +keep in mind that we already have some kernel-doc in place for those areas. + +Level: Unknown diff --git a/Documentation/gpu/amdgpu/display/display-manager.rst b/Documentation/gpu/amdgpu/display/display-manager.rst index be2651ecdd7f2a..67a811e6891fb3 100644 --- a/Documentation/gpu/amdgpu/display/display-manager.rst +++ b/Documentation/gpu/amdgpu/display/display-manager.rst @@ -131,9 +131,6 @@ The DRM blend mode and its elements are then mapped by AMDGPU display manager (DM) to program the blending configuration of the Multiple Pipe/Plane Combined (MPC), as follows: -.. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h - :doc: mpc-overview - .. kernel-doc:: drivers/gpu/drm/amd/display/dc/inc/hw/mpc.h :functions: mpcc_blnd_cfg diff --git a/Documentation/gpu/amdgpu/display/index.rst b/Documentation/gpu/amdgpu/display/index.rst index f8a4f53d70d8c6..f0c342e00a392b 100644 --- a/Documentation/gpu/amdgpu/display/index.rst +++ b/Documentation/gpu/amdgpu/display/index.rst @@ -7,18 +7,80 @@ drm/amd/display - Display Core (DC) AMD display engine is partially shared with other operating systems; for this reason, our Display Core Driver is divided into two pieces: -1. **Display Core (DC)** contains the OS-agnostic components. Things like +#. **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. +#. **Display Manager (DM)** contains the OS-dependent components. Hooks to the + amdgpu base driver and DRM are implemented here. For example, you can check + display/amdgpu_dm/ folder. + +------------------ +DC Code validation +------------------ + +Maintaining the same code base across multiple OSes requires a lot of +synchronization effort between repositories and exhaustive validation. In the +DC case, we maintain a tree to centralize code from different parts. The shared +repository has integration tests with our Internal Linux CI farm, and we run a +comprehensive set of IGT tests in various AMD GPUs/APUs (mostly recent dGPUs +and APUs). Our CI also checks ARM64/32, PPC64/32, and x86_64/32 compilation +with DCN enabled and disabled. + +When we upstream a new feature or some patches, we pack them in a patchset with +the prefix **DC Patches for **, which is created based on the latest +`amd-staging-drm-next `_. All of +those patches are under a DC version tested as follows: + +* Ensure that every patch compiles and the entire series pass our set of IGT + test in different hardware. +* Prepare a branch with those patches for our validation team. If there is an + error, a developer will debug as fast as possible; usually, a simple bisect + in the series is enough to point to a bad change, and two possible actions + emerge: fix the issue or drop the patch. If it is not an easy fix, the bad + patch is dropped. +* Finally, developers wait a few days for community feedback before we merge + the series. + +It is good to stress that the test phase is something that we take extremely +seriously, and we never merge anything that fails our validation. Follows an +overview of our test set: + +#. Manual test + * Multiple Hotplugs with DP and HDMI. + * Stress test with multiple display configuration changes via the user interface. + * Validate VRR behaviour. + * Check PSR. + * Validate MPO when playing video. + * Test more than two displays connected at the same time. + * Check suspend/resume. + * Validate FPO. + * Check MST. +#. Automated test + * IGT tests in a farm with GPUs and APUs that support DCN and DCE. + * Compilation validation with the latest GCC and Clang from LTS distro. + * Cross-compilation for PowerPC 64/32, ARM 64/32, and x86 32. + +In terms of test setup for CI and manual tests, we usually use: + +#. The latest Ubuntu LTS. +#. In terms of userspace, we only use fully updated open-source components + provided by the distribution official package manager. +#. Regarding IGT, we use the latest code from the upstream. +#. Most of the manual tests are conducted in the GNome but we also use KDE. + +Notice that someone from our test team will always reply to the cover letter +with the test report. + +-------------- +DC Information +-------------- The display pipe is responsible for "scanning out" a rendered frame from the GPU memory (also called VRAM, FrameBuffer, etc.) to a display. In other words, it would: -1. Read frame information from memory; -2. Perform required transformation; -3. Send pixel data to sink devices. +#. Read frame information from memory; +#. Perform required transformation; +#. Send pixel data to sink devices. If you want to learn more about our driver details, take a look at the below table of content: @@ -26,7 +88,9 @@ table of content: .. toctree:: display-manager.rst - dc-debug.rst dcn-overview.rst + dcn-blocks.rst mpo-overview.rst + dc-debug.rst + display-contributing.rst dc-glossary.rst diff --git a/Documentation/gpu/drm-internals.rst b/Documentation/gpu/drm-internals.rst index 5fd20a306718cd..335de7fcddeecc 100644 --- a/Documentation/gpu/drm-internals.rst +++ b/Documentation/gpu/drm-internals.rst @@ -153,18 +153,6 @@ Managed Resources .. kernel-doc:: include/drm/drm_managed.h :internal: -Bus-specific Device Registration and PCI Support ------------------------------------------------- - -A number of functions are provided to help with device registration. The -functions deal with PCI and platform devices respectively and are only -provided for historical reasons. These are all deprecated and shouldn't -be used in new drivers. Besides that there's a few helpers for pci -drivers. - -.. kernel-doc:: drivers/gpu/drm/drm_pci.c - :export: - Open/Close, File Operations and IOCTLs ====================================== diff --git a/Documentation/gpu/drm-usage-stats.rst b/Documentation/gpu/drm-usage-stats.rst index 7aca5c7a7b1da6..6dc299343b485b 100644 --- a/Documentation/gpu/drm-usage-stats.rst +++ b/Documentation/gpu/drm-usage-stats.rst @@ -138,7 +138,7 @@ indicating kibi- or mebi-bytes. - drm-shared-: [KiB|MiB] -The total size of buffers that are shared with another file (ie. have more +The total size of buffers that are shared with another file (e.g., have more than a single handle). - drm-total-: [KiB|MiB] diff --git a/Documentation/gpu/introduction.rst b/Documentation/gpu/introduction.rst index f05eccd2c07c8a..b7c0baf97dbee2 100644 --- a/Documentation/gpu/introduction.rst +++ b/Documentation/gpu/introduction.rst @@ -164,6 +164,8 @@ Conference talks Slides and articles ------------------- +* `The Linux graphics stack in a nutshell, part 1 `_ - Thomas Zimmermann (2023) +* `The Linux graphics stack in a nutshell, part 2 `_ - Thomas Zimmermann (2023) * `Understanding the Linux Graphics Stack `_ - Bootlin (2022) * `DRM KMS overview `_ - STMicroelectronics (2021) * `Linux graphic stack `_ - Nathan Gauër (2017) diff --git a/Documentation/gpu/rfc/index.rst b/Documentation/gpu/rfc/index.rst index e4f7b005138d06..476719771eef38 100644 --- a/Documentation/gpu/rfc/index.rst +++ b/Documentation/gpu/rfc/index.rst @@ -31,7 +31,3 @@ host such documentation: .. toctree:: i915_vm_bind.rst - -.. toctree:: - - xe.rst diff --git a/Documentation/gpu/rfc/xe.rst b/Documentation/gpu/rfc/xe.rst deleted file mode 100644 index 97cf87578f973b..00000000000000 --- a/Documentation/gpu/rfc/xe.rst +++ /dev/null @@ -1,234 +0,0 @@ -========================== -Xe – Merge Acceptance Plan -========================== -Xe is a new driver for Intel GPUs that supports both integrated and -discrete platforms starting with Tiger Lake (first Intel Xe Architecture). - -This document aims to establish a merge plan for the Xe, by writing down clear -pre-merge goals, in order to avoid unnecessary delays. - -Xe – Overview -============= -The main motivation of Xe is to have a fresh base to work from that is -unencumbered by older platforms, whilst also taking the opportunity to -rearchitect our driver to increase sharing across the drm subsystem, both -leveraging and allowing us to contribute more towards other shared components -like TTM and drm/scheduler. - -This is also an opportunity to start from the beginning with a clean uAPI that is -extensible by design and already aligned with the modern userspace needs. For -this reason, the memory model is solely based on GPU Virtual Address space -bind/unbind (‘VM_BIND’) of GEM buffer objects (BOs) and execution only supporting -explicit synchronization. With persistent mapping across the execution, the -userspace does not need to provide a list of all required mappings during each -submission. - -The new driver leverages a lot from i915. As for display, the intent is to share -the display code with the i915 driver so that there is maximum reuse there. - -As for the power management area, the goal is to have a much-simplified support -for the system suspend states (S-states), PCI device suspend states (D-states), -GPU/Render suspend states (R-states) and frequency management. It should leverage -as much as possible all the existent PCI-subsystem infrastructure (pm and -runtime_pm) and underlying firmware components such PCODE and GuC for the power -states and frequency decisions. - -Repository: - -https://gitlab.freedesktop.org/drm/xe/kernel (branch drm-xe-next) - -Xe – Platforms -============== -Currently, Xe is already functional and has experimental support for multiple -platforms starting from Tiger Lake, with initial support in userspace implemented -in Mesa (for Iris and Anv, our OpenGL and Vulkan drivers), as well as in NEO -(for OpenCL and Level0). - -During a transition period, platforms will be supported by both Xe and i915. -However, the force_probe mechanism existent in both drivers will allow only one -official and by-default probe at a given time. - -For instance, in order to probe a DG2 which PCI ID is 0x5690 by Xe instead of -i915, the following set of parameters need to be used: - -``` -i915.force_probe=!5690 xe.force_probe=5690 -``` - -In both drivers, the ‘.require_force_probe’ protection forces the user to use the -force_probe parameter while the driver is under development. This protection is -only removed when the support for the platform and the uAPI are stable. Stability -which needs to be demonstrated by CI results. - -In order to avoid user space regressions, i915 will continue to support all the -current platforms that are already out of this protection. Xe support will be -forever experimental and dependent on the usage of force_probe for these -platforms. - -When the time comes for Xe, the protection will be lifted on Xe and kept in i915. - -Xe – Pre-Merge Goals - Work-in-Progress -======================================= - -Display integration with i915 ------------------------------ -In order to share the display code with the i915 driver so that there is maximum -reuse, the i915/display/ code is built twice, once for i915.ko and then for -xe.ko. Currently, the i915/display code in Xe tree is polluted with many 'ifdefs' -depending on the build target. The goal is to refactor both Xe and i915/display -code simultaneously in order to get a clean result before they land upstream, so -that display can already be part of the initial pull request towards drm-next. - -However, display code should not gate the acceptance of Xe in upstream. Xe -patches will be refactored in a way that display code can be removed, if needed, -from the first pull request of Xe towards drm-next. The expectation is that when -both drivers are part of the drm-tip, the introduction of cleaner patches will be -easier and speed up. - -Xe – uAPI high level overview -============================= - -...Warning: To be done in follow up patches after/when/where the main consensus in various items are individually reached. - -Xe – Pre-Merge Goals - Completed -================================ - -Drm_exec --------- -Helper to make dma_resv locking for a big number of buffers is getting removed in -the drm_exec series proposed in https://patchwork.freedesktop.org/patch/524376/ -If that happens, Xe needs to change and incorporate the changes in the driver. -The goal is to engage with the Community to understand if the best approach is to -move that to the drivers that are using it or if we should keep the helpers in -place waiting for Xe to get merged. - -This item ties into the GPUVA, VM_BIND, and even long-running compute support. - -As a key measurable result, we need to have a community consensus documented in -this document and the Xe driver prepared for the changes, if necessary. - -Userptr integration and vm_bind -------------------------------- -Different drivers implement different ways of dealing with execution of userptr. -With multiple drivers currently introducing support to VM_BIND, the goal is to -aim for a DRM consensus on what’s the best way to have that support. To some -extent this is already getting addressed itself with the GPUVA where likely the -userptr will be a GPUVA with a NULL GEM call VM bind directly on the userptr. -However, there are more aspects around the rules for that and the usage of -mmu_notifiers, locking and other aspects. - -This task here has the goal of introducing a documentation of the basic rules. - -The documentation *needs* to first live in this document (API session below) and -then moved to another more specific document or at Xe level or at DRM level. - -Documentation should include: - - * The userptr part of the VM_BIND api. - - * Locking, including the page-faulting case. - - * O(1) complexity under VM_BIND. - -The document is now included in the drm documentation :doc:`here `. - -Some parts of userptr like mmu_notifiers should become GPUVA or DRM helpers when -the second driver supporting VM_BIND+userptr appears. Details to be defined when -the time comes. - -The DRM GPUVM helpers do not yet include the userptr parts, but discussions -about implementing them are ongoing. - -ASYNC VM_BIND -------------- -Although having a common DRM level IOCTL for VM_BIND is not a requirement to get -Xe merged, it is mandatory to have a consensus with other drivers and Mesa. -It needs to be clear how to handle async VM_BIND and interactions with userspace -memory fences. Ideally with helper support so people don't get it wrong in all -possible ways. - -As a key measurable result, the benefits of ASYNC VM_BIND and a discussion of -various flavors, error handling and sample API suggestions are documented in -:doc:`The ASYNC VM_BIND document `. - -Drm_scheduler -------------- -Xe primarily uses Firmware based scheduling (GuC FW). However, it will use -drm_scheduler as the scheduler ‘frontend’ for userspace submission in order to -resolve syncobj and dma-buf implicit sync dependencies. However, drm_scheduler is -not yet prepared to handle the 1-to-1 relationship between drm_gpu_scheduler and -drm_sched_entity. - -Deeper changes to drm_scheduler should *not* be required to get Xe accepted, but -some consensus needs to be reached between Xe and other community drivers that -could also benefit from this work, for coupling FW based/assisted submission such -as the ARM’s new Mali GPU driver, and others. - -As a key measurable result, the patch series introducing Xe itself shall not -depend on any other patch touching drm_scheduler itself that was not yet merged -through drm-misc. This, by itself, already includes the reach of an agreement for -uniform 1 to 1 relationship implementation / usage across drivers. - -Long running compute: minimal data structure/scaffolding --------------------------------------------------------- -The generic scheduler code needs to include the handling of endless compute -contexts, with the minimal scaffolding for preempt-ctx fences (probably on the -drm_sched_entity) and making sure drm_scheduler can cope with the lack of job -completion fence. - -The goal is to achieve a consensus ahead of Xe initial pull-request, ideally with -this minimal drm/scheduler work, if needed, merged to drm-misc in a way that any -drm driver, including Xe, could re-use and add their own individual needs on top -in a next stage. However, this should not block the initial merge. - -Dev_coredump ------------- - -Xe needs to align with other drivers on the way that the error states are -dumped, avoiding a Xe only error_state solution. The goal is to use devcoredump -infrastructure to report error states, since it produces a standardized way -by exposing a virtual and temporary /sys/class/devcoredump device. - -As the key measurable result, Xe driver needs to provide GPU snapshots captured -at hang time through devcoredump, but without depending on any core modification -of devcoredump infrastructure itself. - -Later, when we are in-tree, the goal is to collaborate with devcoredump -infrastructure with overall possible improvements, like multiple file support -for better organization of the dumps, snapshot support, dmesg extra print, -and whatever may make sense and help the overall infrastructure. - -DRM_VM_BIND ------------ -Nouveau, and Xe are all implementing ‘VM_BIND’ and new ‘Exec’ uAPIs in order to -fulfill the needs of the modern uAPI. Xe merge should *not* be blocked on the -development of a common new drm_infrastructure. However, the Xe team needs to -engage with the community to explore the options of a common API. - -As a key measurable result, the DRM_VM_BIND needs to be documented in this file -below, or this entire block deleted if the consensus is for independent drivers -vm_bind ioctls. - -Although having a common DRM level IOCTL for VM_BIND is not a requirement to get -Xe merged, it is mandatory to enforce the overall locking scheme for all major -structs and list (so vm and vma). So, a consensus is needed, and possibly some -common helpers. If helpers are needed, they should be also documented in this -document. - -GPU VA ------- -Two main goals of Xe are meeting together here: - -1) Have an uAPI that aligns with modern UMD needs. - -2) Early upstream engagement. - -RedHat engineers working on Nouveau proposed a new DRM feature to handle keeping -track of GPU virtual address mappings. This is still not merged upstream, but -this aligns very well with our goals and with our VM_BIND. The engagement with -upstream and the port of Xe towards GPUVA is already ongoing. - -As a key measurable result, Xe needs to be aligned with the GPU VA and working in -our tree. Missing Nouveau patches should *not* block Xe and any needed GPUVA -related patch should be independent and present on dri-devel or acked by -maintainers to go along with the first Xe pull request towards drm-next. diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 41a264bf84ce02..fb9ad120b14147 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -120,6 +120,29 @@ Contact: Daniel Vetter, respective driver maintainers Level: Advanced +Rename drm_atomic_state +----------------------- + +The KMS framework uses two slightly different definitions for the ``state`` +concept. For a given object (plane, CRTC, encoder, etc., so +``drm_$OBJECT_state``), the state is the entire state of that object. However, +at the device level, ``drm_atomic_state`` refers to a state update for a +limited number of objects. + +The state isn't the entire device state, but only the full state of some +objects in that device. This is confusing to newcomers, and +``drm_atomic_state`` should be renamed to something clearer like +``drm_atomic_commit``. + +In addition to renaming the structure itself, it would also imply renaming some +related functions (``drm_atomic_state_alloc``, ``drm_atomic_state_get``, +``drm_atomic_state_put``, ``drm_atomic_state_init``, +``__drm_atomic_state_free``, etc.). + +Contact: Maxime Ripard + +Level: Advanced + Fallout from atomic KMS ----------------------- diff --git a/Documentation/hwmon/asus_rog_ryujin.rst b/Documentation/hwmon/asus_rog_ryujin.rst new file mode 100644 index 00000000000000..9f77da07002218 --- /dev/null +++ b/Documentation/hwmon/asus_rog_ryujin.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver asus_rog_ryujin +============================= + +Supported devices: + +* ASUS ROG RYUJIN II 360 + +Author: Aleksa Savic + +Description +----------- + +This driver enables hardware monitoring support for the listed ASUS ROG RYUJIN +all-in-one CPU liquid coolers. Available sensors are pump, internal and external +(controller) fan speed in RPM, their duties in PWM, as well as coolant temperature. + +Attaching external fans to the controller is optional and allows them to be +controlled from the device. If not connected, the fan-related sensors will +report zeroes. The controller is a separate hardware unit that comes bundled +with the AIO and connects to it to allow fan control. + +The addressable LCD screen is not supported in this driver and should +be controlled through userspace tools. + +Usage notes +----------- + +As these are USB HIDs, the driver can be loaded automatically by the kernel and +supports hot swapping. + +Sysfs entries +------------- + +=========== ============================================= +fan1_input Pump speed (in rpm) +fan2_input Internal fan speed (in rpm) +fan3_input External (controller) fan 1 speed (in rpm) +fan4_input External (controller) fan 2 speed (in rpm) +fan5_input External (controller) fan 3 speed (in rpm) +fan6_input External (controller) fan 4 speed (in rpm) +temp1_input Coolant temperature (in millidegrees Celsius) +pwm1 Pump duty +pwm2 Internal fan duty +pwm3 External (controller) fan duty +=========== ============================================= diff --git a/Documentation/hwmon/chipcap2.rst b/Documentation/hwmon/chipcap2.rst new file mode 100644 index 00000000000000..dc165becc64cff --- /dev/null +++ b/Documentation/hwmon/chipcap2.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver ChipCap2 +====================== + +Supported chips: + + * Amphenol CC2D23, CC2D23S, CC2D25, CC2D25S, CC2D33, CC2D33S, CC2D35, CC2D35S + + Prefix: 'chipcap2' + + Addresses scanned: - + + Datasheet: https://www.amphenol-sensors.com/en/telaire/humidity/527-humidity-sensors/3095-chipcap-2 + +Author: + + - Javier Carrasco + +Description +----------- + +This driver implements support for the Amphenol ChipCap 2, a humidity and +temperature chip family. Temperature is measured in milli degrees celsius, +relative humidity is expressed as a per cent mille. The measurement ranges +are the following: + + - Relative humidity: 0 to 100000 pcm (14-bit resolution) + - Temperature: -40000 to +125000 m°C (14-bit resolution) + +The device communicates with the I2C protocol and uses the I2C address 0x28 +by default. + +Depending on the hardware configuration, up to two humidity alarms to control +minimum and maximum values are provided. Their thresholds and hystersis can be +configured via sysfs. + +Thresholds and hysteris must be provided as a per cent mille. These values +might be truncated to match the 14-bit device resolution (6.1 pcm/LSB) + +Known Issues +------------ + +The driver does not support I2C address and command window length modification. + +sysfs-Interface +--------------- + +The following list includes the sysfs attributes that the driver always provides, +their permissions and a short description: + +=============================== ======= ======================================== +Name Perm Description +=============================== ======= ======================================== +temp1_input: RO temperature input +humidity1_input: RO humidity input +=============================== ======= ======================================== + +The following list includes the sysfs attributes that the driver may provide +depending on the hardware configuration: + +=============================== ======= ======================================== +Name Perm Description +=============================== ======= ======================================== +humidity1_min: RW humidity low limit. Measurements under + this limit trigger a humidity low alarm +humidity1_max: RW humidity high limit. Measurements above + this limit trigger a humidity high alarm +humidity1_min_hyst: RW humidity low hystersis +humidity1_max_hyst: RW humidity high hystersis +humidity1_min_alarm: RO humidity low alarm indicator +humidity1_max_alarm: RO humidity high alarm indicator +=============================== ======= ======================================== diff --git a/Documentation/hwmon/emc2305.rst b/Documentation/hwmon/emc2305.rst index 2403dbaf272891..d0bfffe463587b 100644 --- a/Documentation/hwmon/emc2305.rst +++ b/Documentation/hwmon/emc2305.rst @@ -6,7 +6,6 @@ Kernel driver emc2305 Supported chips: Microchip EMC2305, EMC2303, EMC2302, EMC2301 - Addresses scanned: I2C 0x27, 0x2c, 0x2d, 0x2e, 0x2f, 0x4c, 0x4d Prefixes: 'emc2305' Datasheet: Publicly available at the Microchip website : diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index c7ed1f73ac0661..c4af2a894c42dd 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -46,11 +46,13 @@ Hardware Monitoring Kernel Drivers asc7621 aspeed-pwm-tacho asus_ec_sensors + asus_rog_ryujin asus_wmi_sensors bcm54140 bel-pfe bpa-rs600 bt1-pvt + chipcap2 coretemp corsair-cpro corsair-psu @@ -129,6 +131,7 @@ Hardware Monitoring Kernel Drivers ltc4245 ltc4260 ltc4261 + ltc4282 ltc4286 max127 max15301 @@ -163,6 +166,7 @@ Hardware Monitoring Kernel Drivers mp2975 mp5023 mp5990 + mpq8785 nct6683 nct6775 nct7802 @@ -171,6 +175,7 @@ Hardware Monitoring Kernel Drivers nsa320 ntc_thermistor nzxt-kraken2 + nzxt-kraken3 nzxt-smart2 occ oxp-sensors @@ -185,6 +190,7 @@ Hardware Monitoring Kernel Drivers pmbus powerz powr1220 + pt5161l pxe1610 pwm-fan q54sj108a2 @@ -208,6 +214,7 @@ Hardware Monitoring Kernel Drivers smsc47m1 sparx5-temp stpddc60 + surface_fan sy7636a-hwmon tc654 tc74 diff --git a/Documentation/hwmon/ltc4282.rst b/Documentation/hwmon/ltc4282.rst new file mode 100644 index 00000000000000..a87ec3564998fe --- /dev/null +++ b/Documentation/hwmon/ltc4282.rst @@ -0,0 +1,133 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel drivers ltc4282 +========================================== + +Supported chips: + + * Analog Devices LTC4282 + + Prefix: 'ltc4282' + + Addresses scanned: - I2C 0x40 - 0x5A (7-bit) + Addresses scanned: - I2C 0x80 - 0xB4 with a step of 2 (8-bit) + + Datasheet: + + https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf + +Author: Nuno Sá + +Description +___________ + +The LTC4282 hot swap controller allows a board to be safely inserted and removed +from a live backplane. Using one or more external N-channel pass transistors, +board supply voltage and inrush current are ramped up at an adjustable rate. An +I2C interface and onboard ADC allows for monitoring of board current, voltage, +power, energy and fault status. The device features analog foldback current +limiting and supply monitoring for applications from 2.9V to 33V. Dual 12V gate +drive allows high power applications to either share safe operating area across +parallel MOSFETs or support a 2-stage start-up that first charges the load +capacitance followed by enabling a low on-resistance path to the load. The +LTC4282 is well suited to high power applications because the precise monitoring +capability and accurate current limiting reduce the extremes in which both loads +and power supplies must safely operate. Non-volatile configuration allows for +flexibility in the autonomous generation of alerts and response to faults. + +Sysfs entries +_____________ + +The following attributes are supported. Limits are read-write and all the other +attributes are read-only. Note that in0 and in1 are mutually exclusive. Enabling +one disables the other and disabling one enables the other. + +======================= ========================================== +in0_input Output voltage (mV). +in0_min Undervoltage threshold +in0_max Overvoltage threshold +in0_lowest Lowest measured voltage +in0_highest Highest measured voltage +in0_reset_history Write 1 to reset in0 history. + Also clears fet bad and short fault logs. +in0_min_alarm Undervoltage alarm +in0_max_alarm Overvoltage alarm +in0_enable Enable/Disable VSOURCE monitoring +in0_fault Failure in the MOSFETs. Either bad or shorted FET. +in0_label Channel label (VSOURCE) + +in1_input Input voltage (mV). +in1_min Undervoltage threshold +in1_max Overvoltage threshold +in1_lowest Lowest measured voltage +in1_highest Highest measured voltage +in1_reset_history Write 1 to reset in1 history. + Also clears over/undervoltage fault logs. +in1_min_alarm Undervoltage alarm +in1_max_alarm Overvoltage alarm +in1_lcrit_alarm Critical Undervoltage alarm +in1_crit_alarm Critical Overvoltage alarm +in1_enable Enable/Disable VDD monitoring +in1_label Channel label (VDD) + +in2_input GPIO voltage (mV) +in2_min Undervoltage threshold +in2_max Overvoltage threshold +in2_lowest Lowest measured voltage +in2_highest Highest measured voltage +in2_reset_history Write 1 to reset in2 history +in2_min_alarm Undervoltage alarm +in2_max_alarm Overvoltage alarm +in2_label Channel label (VGPIO) + +curr1_input Sense current (mA) +curr1_min Undercurrent threshold +curr1_max Overcurrent threshold +curr1_lowest Lowest measured current +curr1_highest Highest measured current +curr1_reset_history Write 1 to reset curr1 history. + Also clears overcurrent fault logs. +curr1_min_alarm Undercurrent alarm +curr1_max_alarm Overcurrent alarm +curr1_crit_alarm Critical Overcurrent alarm +curr1_label Channel label (ISENSE) + +power1_input Power (in uW) +power1_min Low power threshold +power1_max High power threshold +power1_input_lowest Historical minimum power use +power1_input_highest Historical maximum power use +power1_reset_history Write 1 to reset power1 history. + Also clears power bad fault logs. +power1_min_alarm Low power alarm +power1_max_alarm High power alarm +power1_label Channel label (Power) + +energy1_input Measured energy over time (in microJoule) +energy1_enable Enable/Disable Energy accumulation +======================= ========================================== + +DebugFs entries +_______________ + +The chip also has a fault log register where failures can be logged. Hence, +as these are logging events, we give access to them in debugfs. Note that +even if some failure is detected in these logs, it does necessarily mean +that the failure is still present. As mentioned in the proper Sysfs entries, +these logs can be cleared by writing in the proper reset_history attribute. + +.. warning:: The debugfs interface is subject to change without notice + and is only available when the kernel is compiled with + ``CONFIG_DEBUG_FS`` defined. + +``/sys/kernel/debug/ltc4282-hwmon[X]/`` +contains the following attributes: + +======================= ========================================== +power1_bad_fault_log Set to 1 by a power1 bad fault occurring. +in0_fet_short_fault_log Set to 1 when the ADC detects a FET-short fault. +in0_fet_bad_fault_log Set to 1 when a FET-BAD fault occurs. +in1_crit_fault_log Set to 1 by a VDD overvoltage fault occurring. +in1_lcrit_fault_log Set to 1 by a VDD undervoltage fault occurring. +curr1_crit_fault_log Set to 1 by an overcurrent fault occurring. +======================= ========================================== diff --git a/Documentation/hwmon/max6620.rst b/Documentation/hwmon/max6620.rst index 84c1c44d3de4de..d70173bf0242c1 100644 --- a/Documentation/hwmon/max6620.rst +++ b/Documentation/hwmon/max6620.rst @@ -11,7 +11,7 @@ Supported chips: Addresses scanned: none - Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6620.pdf + Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/max6620.pdf Authors: - L\. Grunenberg diff --git a/Documentation/hwmon/mpq8785.rst b/Documentation/hwmon/mpq8785.rst new file mode 100644 index 00000000000000..bf8176b8708687 --- /dev/null +++ b/Documentation/hwmon/mpq8785.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +Kernel driver mpq8785 +======================= + +Supported chips: + + * MPS MPQ8785 + + Prefix: 'mpq8785' + +Author: Charles Hsu + +Description +----------- + +The MPQ8785 is a fully integrated, PMBus-compatible, high-frequency, synchronous +buck converter. The MPQ8785 offers a very compact solution that achieves up to +40A output current per phase, with excellent load and line regulation over a +wide input supply range. The MPQ8785 operates at high efficiency over a wide +output current load range. + +The PMBus interface provides converter configurations and key parameters +monitoring. + +The MPQ8785 adopts MPS's proprietary multi-phase digital constant-on-time (MCOT) +control, which provides fast transient response and eases loop stabilization. +The MCOT scheme also allows multiple MPQ8785 devices to be connected in parallel +with excellent current sharing and phase interleaving for high-current +applications. + +Fully integrated protection features include over-current protection (OCP), +over-voltage protection (OVP), under-voltage protection (UVP), and +over-temperature protection (OTP). + +The MPQ8785 requires a minimal number of readily available, standard external +components, and is available in a TLGA (5mmx6mm) package. + +Device compliant with: + +- PMBus rev 1.3 interface. + +The driver exports the following attributes via the 'sysfs' files +for input voltage: + +**in1_input** + +**in1_label** + +**in1_max** + +**in1_max_alarm** + +**in1_min** + +**in1_min_alarm** + +**in1_crit** + +**in1_crit_alarm** + +The driver provides the following attributes for output voltage: + +**in2_input** + +**in2_label** + +**in2_alarm** + +The driver provides the following attributes for output current: + +**curr1_input** + +**curr1_label** + +**curr1_max** + +**curr1_max_alarm** + +**curr1_crit** + +**curr1_crit_alarm** + +The driver provides the following attributes for temperature: + +**temp1_input** + +**temp1_max** + +**temp1_max_alarm** + +**temp1_crit** + +**temp1_crit_alarm** diff --git a/Documentation/hwmon/nct6683.rst b/Documentation/hwmon/nct6683.rst index 3e7f6ee779c2f9..2a7a78eb1b4688 100644 --- a/Documentation/hwmon/nct6683.rst +++ b/Documentation/hwmon/nct6683.rst @@ -64,4 +64,5 @@ Intel DB85FL NCT6683D EC firmware version 1.0 build 04/03/13 ASRock X570 NCT6683D EC firmware version 1.0 build 06/28/19 ASRock X670E NCT6686D EC firmware version 1.0 build 05/19/22 MSI B550 NCT6687D EC firmware version 1.0 build 05/07/20 +MSI X670-P NCT6687D EC firmware version 0.0 build 09/27/22 =============== =============================================== diff --git a/Documentation/hwmon/nzxt-kraken3.rst b/Documentation/hwmon/nzxt-kraken3.rst new file mode 100644 index 00000000000000..90fd9dec15ff22 --- /dev/null +++ b/Documentation/hwmon/nzxt-kraken3.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver nzxt-kraken3 +========================== + +Supported devices: + +* NZXT Kraken X53 +* NZXT Kraken X63 +* NZXT Kraken X73 +* NZXT Kraken Z53 +* NZXT Kraken Z63 +* NZXT Kraken Z73 + +Author: Jonas Malaco, Aleksa Savic + +Description +----------- + +This driver enables hardware monitoring support for NZXT Kraken X53/X63/X73 and +Z53/Z63/Z73 all-in-one CPU liquid coolers. All models expose liquid temperature +and pump speed (in RPM), as well as PWM control (either as a fixed value +or through a temp-PWM curve). The Z-series models additionally expose the speed +and duty of an optionally connected fan, with the same PWM control capabilities. + +Pump and fan duty control mode can be set through pwm[1-2]_enable, where 1 is +for the manual control mode and 2 is for the liquid temp to PWM curve mode. +Writing a 0 disables control of the channel through the driver after setting its +duty to 100%. + +The temperature of the curves relates to the fixed [20-59] range, correlating to +the detected liquid temperature. Only PWM values (ranging from 0-255) can be set. +If in curve mode, setting point values should be done in moderation - the devices +require complete curves to be sent for each change; they can lock up or discard +the changes if they are too numerous at once. Suggestion is to set them while +in an another mode, and then apply them by switching to curve. + +The devices can report if they are faulty. The driver supports that situation +and will issue a warning. This can also happen when the USB cable is connected, +but SATA power is not. + +The addressable RGB LEDs and LCD screen (only on Z-series models) are not +supported in this driver, but can be controlled through existing userspace tools, +such as `liquidctl`_. + +.. _liquidctl: https://github.com/liquidctl/liquidctl + +Usage Notes +----------- + +As these are USB HIDs, the driver can be loaded automatically by the kernel and +supports hot swapping. + +Possible pwm_enable values are: + +====== ========================================================================== +0 Set fan to 100% +1 Direct PWM mode (applies value in corresponding PWM entry) +2 Curve control mode (applies the temp-PWM duty curve based on coolant temp) +====== ========================================================================== + +Sysfs entries +------------- + +============================== ================================================================ +fan1_input Pump speed (in rpm) +fan2_input Fan speed (in rpm) +temp1_input Coolant temperature (in millidegrees Celsius) +pwm1 Pump duty (value between 0-255) +pwm1_enable Pump duty control mode (0: disabled, 1: manual, 2: curve) +pwm2 Fan duty (value between 0-255) +pwm2_enable Fan duty control mode (0: disabled, 1: manual, 2: curve) +temp[1-2]_auto_point[1-40]_pwm Temp-PWM duty curves (for pump and fan), related to coolant temp +============================== ================================================================ diff --git a/Documentation/hwmon/oxp-sensors.rst b/Documentation/hwmon/oxp-sensors.rst index 3adeb7406243fb..55b1ef61625ebc 100644 --- a/Documentation/hwmon/oxp-sensors.rst +++ b/Documentation/hwmon/oxp-sensors.rst @@ -33,6 +33,7 @@ Currently the driver supports the following handhelds: - AOK ZOE A1 PRO - Aya Neo 2 - Aya Neo AIR + - Aya Neo AIR Plus (Mendocino) - Aya Neo AIR Pro - Aya Neo Geek - OneXPlayer AMD diff --git a/Documentation/hwmon/pt5161l.rst b/Documentation/hwmon/pt5161l.rst new file mode 100644 index 00000000000000..1b97336991ea5f --- /dev/null +++ b/Documentation/hwmon/pt5161l.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver pt5161l +===================== + +Supported chips: + + * Astera Labs PT5161L + + Prefix: 'pt5161l' + + Addresses scanned: I2C 0x20 - 0x27 + + Datasheet: Not publicly available. + +Authors: Cosmo Chou + +Description +----------- + +This driver implements support for temperature monitoring of Astera Labs +PT5161L series PCIe retimer chips. + +This driver implementation originates from the CSDK available at +https://github.com/facebook/openbmc/tree/helium/common/recipes-lib/retimer-v2.14 +The communication protocol utilized is based on the I2C/SMBus standard. + +Sysfs entries +---------------- + +================ ============================================== +temp1_input Measured temperature (in millidegrees Celsius) +================ ============================================== + +Debugfs entries +---------------- + +================ =============================== +fw_load_status Firmware load status +fw_ver Firmware version of the retimer +heartbeat_status Heartbeat status +================ =============================== diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst index 957c854f5d088c..9585fa7c5a5d87 100644 --- a/Documentation/hwmon/sht3x.rst +++ b/Documentation/hwmon/sht3x.rst @@ -65,6 +65,10 @@ When the temperature and humidity readings move back between the hysteresis values, the alert bit is set to 0 and the alert pin on the sensor is set to low. +The serial number exposed to debugfs allows for unique identification of the +sensors. For sts32, sts33 and sht33, the manufacturer provides calibration +certificates through an API. + sysfs-Interface --------------- @@ -99,3 +103,10 @@ repeatability: write or read repeatability, higher repeatability means - 1: medium repeatability - 2: high repeatability =================== ============================================================ + +debugfs-Interface +----------------- + +=================== ============================================================ +serial_number: unique serial number of the sensor in decimal +=================== ============================================================ diff --git a/Documentation/hwmon/surface_fan.rst b/Documentation/hwmon/surface_fan.rst new file mode 100644 index 00000000000000..07942574c4f0cf --- /dev/null +++ b/Documentation/hwmon/surface_fan.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Kernel driver surface_fan +========================= + +Supported Devices: + + * Microsoft Surface Pro 9 + +Author: Ivor Wanders + +Description +----------- + +This provides monitoring of the fan found in some Microsoft Surface Pro devices, +like the Surface Pro 9. The fan is always controlled by the onboard controller. + +Sysfs interface +--------------- + +======================= ======= ========================================= +Name Perm Description +======================= ======= ========================================= +``fan1_input`` RO Current fan speed in RPM. +======================= ======= ========================================= diff --git a/Documentation/index.rst b/Documentation/index.rst index 36e61783437c10..9dfdc826618c08 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -113,7 +113,6 @@ to ReStructured Text format, or are simply too old. :maxdepth: 1 staging/index - RAS/ras Translations diff --git a/Documentation/kbuild/Kconfig.recursion-issue-01 b/Documentation/kbuild/Kconfig.recursion-issue-01 index e8877db0461fb4..ac49836d8ecf89 100644 --- a/Documentation/kbuild/Kconfig.recursion-issue-01 +++ b/Documentation/kbuild/Kconfig.recursion-issue-01 @@ -16,13 +16,13 @@ # that are possible for CORE. So for example if CORE_BELL_A_ADVANCED is 'y', # CORE must be 'y' too. # -# * What influences CORE_BELL_A_ADVANCED ? +# * What influences CORE_BELL_A_ADVANCED? # # As the name implies CORE_BELL_A_ADVANCED is an advanced feature of # CORE_BELL_A so naturally it depends on CORE_BELL_A. So if CORE_BELL_A is 'y' # we know CORE_BELL_A_ADVANCED can be 'y' too. # -# * What influences CORE_BELL_A ? +# * What influences CORE_BELL_A? # # CORE_BELL_A depends on CORE, so CORE influences CORE_BELL_A. # @@ -34,7 +34,7 @@ # the "recursive dependency detected" error. # # Reading the Documentation/kbuild/Kconfig.recursion-issue-01 file it may be -# obvious that an easy to solution to this problem should just be the removal +# obvious that an easy solution to this problem should just be the removal # of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already # since CORE_BELL_A depends on CORE. Recursive dependency issues are not always # so trivial to resolve, we provide another example below of practical diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index c946eb44bd138e..fc4e845bc249ba 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -1,10 +1,10 @@ -=================== -Kconfig make config -=================== +================================= +Configuration targets and editors +================================= -This file contains some assistance for using `make *config`. +This file contains some assistance for using ``make *config``. -Use "make help" to list all of the possible configuration targets. +Use ``make help`` to list all of the possible configuration targets. The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf') programs also have embedded help text. Be sure to check that for @@ -12,8 +12,9 @@ navigation, search, and other general help text. The gconfig ('gconf') program has limited help text. + General -------- +======= New kernel releases often introduce new config symbols. Often more important, new kernel releases may rename config symbols. When @@ -24,118 +25,102 @@ symbols have been introduced. To see a list of new config symbols, use:: - cp user/some/old.config .config - make listnewconfig + cp user/some/old.config .config + make listnewconfig and the config program will list any new symbols, one per line. Alternatively, you can use the brute force method:: - make oldconfig - scripts/diffconfig .config.old .config | less - ----------------------------------------------------------------------- - -Environment variables for `*config` + make oldconfig + scripts/diffconfig .config.old .config | less -KCONFIG_CONFIG --------------- -This environment variable can be used to specify a default kernel config -file name to override the default name of ".config". -KCONFIG_DEFCONFIG_LIST ----------------------- +Environment variables +===================== -This environment variable specifies a list of config files which can be used -as a base configuration in case the .config does not exist yet. Entries in -the list are separated with whitespaces to each other, and the first one -that exists is used. +Environment variables for ``*config``: -KCONFIG_OVERWRITECONFIG ------------------------ -If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not -break symlinks when .config is a symlink to somewhere else. +``KCONFIG_CONFIG`` + This environment variable can be used to specify a default kernel config + file name to override the default name of ".config". -KCONFIG_WARN_UNKNOWN_SYMBOLS ----------------------------- -This environment variable makes Kconfig warn about all unrecognized -symbols in the config input. +``KCONFIG_DEFCONFIG_LIST`` + This environment variable specifies a list of config files which can be + used as a base configuration in case the .config does not exist yet. + Entries in the list are separated with whitespaces to each other, and + the first one that exists is used. -KCONFIG_WERROR --------------- -If set, Kconfig treats warnings as errors. +``KCONFIG_OVERWRITECONFIG`` + If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not + break symlinks when .config is a symlink to somewhere else. -`CONFIG_` ---------- -If you set `CONFIG_` in the environment, Kconfig will prefix all symbols -with its value when saving the configuration, instead of using the default, -`CONFIG_`. +``KCONFIG_WARN_UNKNOWN_SYMBOLS`` + This environment variable makes Kconfig warn about all unrecognized + symbols in the config input. ----------------------------------------------------------------------- +``KCONFIG_WERROR`` + If set, Kconfig treats warnings as errors. -Environment variables for '{allyes/allmod/allno/rand}config' +``CONFIG_`` + If you set ``CONFIG_`` in the environment, Kconfig will prefix all symbols + with its value when saving the configuration, instead of using the + default, ``CONFIG_``. -KCONFIG_ALLCONFIG ------------------ -(partially based on lkml email from/by Rob Landley, re: miniconfig) +Environment variables for ``{allyes/allmod/allno/rand}config``: --------------------------------------------------- +``KCONFIG_ALLCONFIG`` + The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also + use the environment variable KCONFIG_ALLCONFIG as a flag or a filename + that contains config symbols that the user requires to be set to a + specific value. If KCONFIG_ALLCONFIG is used without a filename where + KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", ``make *config`` + checks for a file named "all{yes/mod/no/def/random}.config" + (corresponding to the ``*config`` command that was used) for symbol values + that are to be forced. If this file is not found, it checks for a + file named "all.config" to contain forced values. -The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also -use the environment variable KCONFIG_ALLCONFIG as a flag or a filename -that contains config symbols that the user requires to be set to a -specific value. If KCONFIG_ALLCONFIG is used without a filename where -KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", `make *config` -checks for a file named "all{yes/mod/no/def/random}.config" -(corresponding to the `*config` command that was used) for symbol values -that are to be forced. If this file is not found, it checks for a -file named "all.config" to contain forced values. + This enables you to create "miniature" config (miniconfig) or custom + config files containing just the config symbols that you are interested + in. Then the kernel config system generates the full .config file, + including symbols of your miniconfig file. -This enables you to create "miniature" config (miniconfig) or custom -config files containing just the config symbols that you are interested -in. Then the kernel config system generates the full .config file, -including symbols of your miniconfig file. - -This 'KCONFIG_ALLCONFIG' file is a config file which contains -(usually a subset of all) preset config symbols. These variable -settings are still subject to normal dependency checks. - -Examples:: + This ``KCONFIG_ALLCONFIG`` file is a config file which contains + (usually a subset of all) preset config symbols. These variable + settings are still subject to normal dependency checks. - KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig + Examples:: -or:: + KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig - KCONFIG_ALLCONFIG=mini.config make allnoconfig + or:: -or:: + KCONFIG_ALLCONFIG=mini.config make allnoconfig - make KCONFIG_ALLCONFIG=mini.config allnoconfig + or:: -These examples will disable most options (allnoconfig) but enable or -disable the options that are explicitly listed in the specified -mini-config files. + make KCONFIG_ALLCONFIG=mini.config allnoconfig ----------------------------------------------------------------------- + These examples will disable most options (allnoconfig) but enable or + disable the options that are explicitly listed in the specified + mini-config files. -Environment variables for 'randconfig' +Environment variables for ``randconfig``: -KCONFIG_SEED ------------- -You can set this to the integer value used to seed the RNG, if you want -to somehow debug the behaviour of the kconfig parser/frontends. -If not set, the current time will be used. +``KCONFIG_SEED`` + You can set this to the integer value used to seed the RNG, if you want + to somehow debug the behaviour of the kconfig parser/frontends. + If not set, the current time will be used. -KCONFIG_PROBABILITY -------------------- -This variable can be used to skew the probabilities. This variable can -be unset or empty, or set to three different formats: +``KCONFIG_PROBABILITY`` + This variable can be used to skew the probabilities. This variable can + be unset or empty, or set to three different formats: ======================= ================== ===================== - KCONFIG_PROBABILITY y:n split y:m:n split + KCONFIG_PROBABILITY y:n split y:m:n split ======================= ================== ===================== - unset or empty 50 : 50 33 : 33 : 34 - N N : 100-N N/2 : N/2 : 100-N + unset or empty 50 : 50 33 : 33 : 34 + N N : 100-N N/2 : N/2 : 100-N [1] N:M N+M : 100-(N+M) N : M : 100-(N+M) [2] N:M:L N : 100-N M : L : 100-(M+L) ======================= ================== ===================== @@ -149,112 +134,98 @@ that: Examples:: - KCONFIG_PROBABILITY=10 - 10% of booleans will be set to 'y', 90% to 'n' - 5% of tristates will be set to 'y', 5% to 'm', 90% to 'n' - KCONFIG_PROBABILITY=15:25 - 40% of booleans will be set to 'y', 60% to 'n' - 15% of tristates will be set to 'y', 25% to 'm', 60% to 'n' - KCONFIG_PROBABILITY=10:15:15 - 10% of booleans will be set to 'y', 90% to 'n' - 15% of tristates will be set to 'y', 15% to 'm', 70% to 'n' + KCONFIG_PROBABILITY=10 + 10% of booleans will be set to 'y', 90% to 'n' + 5% of tristates will be set to 'y', 5% to 'm', 90% to 'n' + KCONFIG_PROBABILITY=15:25 + 40% of booleans will be set to 'y', 60% to 'n' + 15% of tristates will be set to 'y', 25% to 'm', 60% to 'n' + KCONFIG_PROBABILITY=10:15:15 + 10% of booleans will be set to 'y', 90% to 'n' + 15% of tristates will be set to 'y', 15% to 'm', 70% to 'n' ----------------------------------------------------------------------- +Environment variables for ``syncconfig``: -Environment variables for 'syncconfig' +``KCONFIG_NOSILENTUPDATE`` + If this variable has a non-blank value, it prevents silent kernel + config updates (requires explicit updates). -KCONFIG_NOSILENTUPDATE ----------------------- -If this variable has a non-blank value, it prevents silent kernel -config updates (requires explicit updates). +``KCONFIG_AUTOCONFIG`` + This environment variable can be set to specify the path & name of the + "auto.conf" file. Its default value is "include/config/auto.conf". -KCONFIG_AUTOCONFIG ------------------- -This environment variable can be set to specify the path & name of the -"auto.conf" file. Its default value is "include/config/auto.conf". +``KCONFIG_AUTOHEADER`` + This environment variable can be set to specify the path & name of the + "autoconf.h" (header) file. + Its default value is "include/generated/autoconf.h". -KCONFIG_AUTOHEADER ------------------- -This environment variable can be set to specify the path & name of the -"autoconf.h" (header) file. -Its default value is "include/generated/autoconf.h". - - ----------------------------------------------------------------------- menuconfig ----------- - -SEARCHING for CONFIG symbols +========== Searching in menuconfig: - The Search function searches for kernel configuration symbol - names, so you have to know something close to what you are - looking for. + The Search function searches for kernel configuration symbol + names, so you have to know something close to what you are + looking for. - Example:: + Example:: - /hotplug - This lists all config symbols that contain "hotplug", - e.g., HOTPLUG_CPU, MEMORY_HOTPLUG. + /hotplug + This lists all config symbols that contain "hotplug", + e.g., HOTPLUG_CPU, MEMORY_HOTPLUG. - For search help, enter / followed by TAB-TAB (to highlight - ) and Enter. This will tell you that you can also use - regular expressions (regexes) in the search string, so if you - are not interested in MEMORY_HOTPLUG, you could try:: + For search help, enter / followed by TAB-TAB (to highlight + ) and Enter. This will tell you that you can also use + regular expressions (regexes) in the search string, so if you + are not interested in MEMORY_HOTPLUG, you could try:: - /^hotplug + /^hotplug - When searching, symbols are sorted thus: + When searching, symbols are sorted thus: - - first, exact matches, sorted alphabetically (an exact match - is when the search matches the complete symbol name); - - then, other matches, sorted alphabetically. + - first, exact matches, sorted alphabetically (an exact match + is when the search matches the complete symbol name); + - then, other matches, sorted alphabetically. - For example: ^ATH.K matches: + For example, ^ATH.K matches: - ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG - [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...] + ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG + [...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...] - of which only ATH5K and ATH9K match exactly and so are sorted - first (and in alphabetical order), then come all other symbols, - sorted in alphabetical order. + of which only ATH5K and ATH9K match exactly and so are sorted + first (and in alphabetical order), then come all other symbols, + sorted in alphabetical order. - In this menu, pressing the key in the (#) prefix will jump - directly to that location. You will be returned to the current - search results after exiting this new menu. + In this menu, pressing the key in the (#) prefix will jump + directly to that location. You will be returned to the current + search results after exiting this new menu. ----------------------------------------------------------------------- +User interface options for 'menuconfig': -User interface options for 'menuconfig' +``MENUCONFIG_COLOR`` + It is possible to select different color themes using the variable + MENUCONFIG_COLOR. To select a theme use:: -MENUCONFIG_COLOR ----------------- -It is possible to select different color themes using the variable -MENUCONFIG_COLOR. To select a theme use:: + make MENUCONFIG_COLOR= menuconfig - make MENUCONFIG_COLOR= menuconfig + Available themes are:: -Available themes are:: + - mono => selects colors suitable for monochrome displays + - blackbg => selects a color scheme with black background + - classic => theme with blue background. The classic look + - bluetitle => a LCD friendly version of classic. (default) - - mono => selects colors suitable for monochrome displays - - blackbg => selects a color scheme with black background - - classic => theme with blue background. The classic look - - bluetitle => a LCD friendly version of classic. (default) +``MENUCONFIG_MODE`` + This mode shows all sub-menus in one large tree. -MENUCONFIG_MODE ---------------- -This mode shows all sub-menus in one large tree. + Example:: -Example:: + make MENUCONFIG_MODE=single_menu menuconfig - make MENUCONFIG_MODE=single_menu menuconfig - ----------------------------------------------------------------------- nconfig -------- +======= nconfig is an alternate text-based configurator. It lists function keys across the bottom of the terminal (window) that execute commands. @@ -266,61 +237,59 @@ Use F1 for Global help or F3 for the Short help menu. Searching in nconfig: - You can search either in the menu entry "prompt" strings - or in the configuration symbols. + You can search either in the menu entry "prompt" strings + or in the configuration symbols. + + Use / to begin a search through the menu entries. This does + not support regular expressions. Use or for + Next hit and Previous hit, respectively. Use to + terminate the search mode. - Use / to begin a search through the menu entries. This does - not support regular expressions. Use or for - Next hit and Previous hit, respectively. Use to - terminate the search mode. + F8 (SymSearch) searches the configuration symbols for the + given string or regular expression (regex). - F8 (SymSearch) searches the configuration symbols for the - given string or regular expression (regex). + In the SymSearch, pressing the key in the (#) prefix will + jump directly to that location. You will be returned to the + current search results after exiting this new menu. - In the SymSearch, pressing the key in the (#) prefix will - jump directly to that location. You will be returned to the - current search results after exiting this new menu. +Environment variables: -NCONFIG_MODE ------------- -This mode shows all sub-menus in one large tree. +``NCONFIG_MODE`` + This mode shows all sub-menus in one large tree. -Example:: + Example:: - make NCONFIG_MODE=single_menu nconfig + make NCONFIG_MODE=single_menu nconfig ----------------------------------------------------------------------- xconfig -------- +======= Searching in xconfig: - The Search function searches for kernel configuration symbol - names, so you have to know something close to what you are - looking for. - - Example:: + The Search function searches for kernel configuration symbol + names, so you have to know something close to what you are + looking for. - Ctrl-F hotplug + Example:: - or:: + Ctrl-F hotplug - Menu: File, Search, hotplug + or:: - lists all config symbol entries that contain "hotplug" in - the symbol name. In this Search dialog, you may change the - config setting for any of the entries that are not grayed out. - You can also enter a different search string without having - to return to the main menu. + Menu: File, Search, hotplug + lists all config symbol entries that contain "hotplug" in + the symbol name. In this Search dialog, you may change the + config setting for any of the entries that are not grayed out. + You can also enter a different search string without having + to return to the main menu. ----------------------------------------------------------------------- gconfig -------- +======= Searching in gconfig: - There is no search command in gconfig. However, gconfig does - have several different viewing choices, modes, and options. + There is no search command in gconfig. However, gconfig does + have several different viewing choices, modes, and options. diff --git a/Documentation/litmus-tests/README b/Documentation/litmus-tests/README index 658d37860d3974..6c666f3422ea3a 100644 --- a/Documentation/litmus-tests/README +++ b/Documentation/litmus-tests/README @@ -21,6 +21,51 @@ Atomic-RMW-ops-are-atomic-WRT-atomic_set.litmus Test that atomic_set() cannot break the atomicity of atomic RMWs. NOTE: Require herd7 7.56 or later which supports "(void)expr". +cmpxchg-fail-ordered-1.litmus + Demonstrate that a failing cmpxchg() operation acts as a full barrier + when followed by smp_mb__after_atomic(). + +cmpxchg-fail-ordered-2.litmus + Demonstrate that a failing cmpxchg() operation acts as an acquire + operation when followed by smp_mb__after_atomic(). + +cmpxchg-fail-unordered-1.litmus + Demonstrate that a failing cmpxchg() operation does not act as a + full barrier. + +cmpxchg-fail-unordered-2.litmus + Demonstrate that a failing cmpxchg() operation does not act as an + acquire operation. + + +locking (/locking directory) +---------------------------- + +DCL-broken.litmus + Demonstrates that double-checked locking needs more than just + the obvious lock acquisitions and releases. + +DCL-fixed.litmus + Demonstrates corrected double-checked locking that uses + smp_store_release() and smp_load_acquire() in addition to the + obvious lock acquisitions and releases. + +RM-broken.litmus + Demonstrates problems with "roach motel" locking, where code is + freely moved into lock-based critical sections. This example also + shows how to use the "filter" clause to discard executions that + would be excluded by other code not modeled in the litmus test. + Note also that this "roach motel" optimization is emulated by + physically moving P1()'s two reads from x under the lock. + + What is a roach motel? This is from an old advertisement for + a cockroach trap, much later featured in one of the "Men in + Black" movies. "The roaches check in. They don't check out." + +RM-fixed.litmus + The counterpart to RM-broken.litmus, showing P0()'s two loads from + x safely outside of the critical section. + RCU (/rcu directory) -------------------- diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus new file mode 100644 index 00000000000000..3df1d140b189bb --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-1.litmus @@ -0,0 +1,34 @@ +C cmpxchg-fail-ordered-1 + +(* + * Result: Never + * + * Demonstrate that a failing cmpxchg() operation will act as a full + * barrier when followed by smp_mb__after_atomic(). + *) + +{} + +P0(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(z, 1, 0); + smp_mb__after_atomic(); + r0 = READ_ONCE(*y); +} + +P1(int *x, int *y, int *z) +{ + int r0; + + WRITE_ONCE(*y, 1); + r1 = cmpxchg(z, 1, 0); + smp_mb__after_atomic(); + r0 = READ_ONCE(*x); +} + +locations[0:r1;1:r1] +exists (0:r0=0 /\ 1:r0=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus new file mode 100644 index 00000000000000..54146044a16f6d --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-ordered-2.litmus @@ -0,0 +1,30 @@ +C cmpxchg-fail-ordered-2 + +(* + * Result: Never + * + * Demonstrate use of smp_mb__after_atomic() to make a failing cmpxchg + * operation have acquire ordering. + *) + +{} + +P0(int *x, int *y) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(y, 0, 1); +} + +P1(int *x, int *y) +{ + int r0; + + r1 = cmpxchg(y, 0, 1); + smp_mb__after_atomic(); + r2 = READ_ONCE(*x); +} + +exists (0:r1=0 /\ 1:r1=1 /\ 1:r2=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus new file mode 100644 index 00000000000000..a727ce23b1a6ea --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-1.litmus @@ -0,0 +1,33 @@ +C cmpxchg-fail-unordered-1 + +(* + * Result: Sometimes + * + * Demonstrate that a failing cmpxchg() operation does not act as a + * full barrier. (In contrast, a successful cmpxchg() does act as a + * full barrier.) + *) + +{} + +P0(int *x, int *y, int *z) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(z, 1, 0); + r0 = READ_ONCE(*y); +} + +P1(int *x, int *y, int *z) +{ + int r0; + + WRITE_ONCE(*y, 1); + r1 = cmpxchg(z, 1, 0); + r0 = READ_ONCE(*x); +} + +locations[0:r1;1:r1] +exists (0:r0=0 /\ 1:r0=0) diff --git a/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus new file mode 100644 index 00000000000000..a245bac55b578d --- /dev/null +++ b/Documentation/litmus-tests/atomic/cmpxchg-fail-unordered-2.litmus @@ -0,0 +1,30 @@ +C cmpxchg-fail-unordered-2 + +(* + * Result: Sometimes + * + * Demonstrate that a failing cmpxchg() operation does not act as either + * an acquire release operation. (In contrast, a successful cmpxchg() + * does act as both an acquire and a release operation.) + *) + +{} + +P0(int *x, int *y) +{ + int r0; + int r1; + + WRITE_ONCE(*x, 1); + r1 = cmpxchg(y, 0, 1); +} + +P1(int *x, int *y) +{ + int r0; + + r1 = cmpxchg(y, 0, 1); + r2 = READ_ONCE(*x); +} + +exists (0:r1=0 /\ 1:r1=1 /\ 1:r2=0) diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 18cee1edaecb6f..b49fb6dc4d0cda 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -102,7 +102,10 @@ to do something different in the near future. ../doc-guide/maintainer-profile ../nvdimm/maintainer-entry-profile ../arch/riscv/patch-acceptance + ../process/maintainer-soc + ../process/maintainer-soc-clean-dts ../driver-api/media/maintainer-entry-profile + ../process/maintainer-netdev ../driver-api/vfio-pci-device-specific-driver-acceptance ../nvme/feature-and-quirk-policy ../filesystems/xfs/xfs-maintainer-entry-profile diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst index 8c8a289d69a367..698e6630f3a7b3 100644 --- a/Documentation/misc-devices/xilinx_sdfec.rst +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -29,7 +29,7 @@ follows: - Does not support shared LDPC code table wraparound The device tree entry is described in: -`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt `_ +`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.yaml `_ Modes of Operation diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index 1bb69524a62ea6..8c89d26f0baa1f 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -31,6 +31,8 @@ DAMON subsystem is configured with three layers including interfaces for the user space, on top of the core layer. +.. _damon_design_configurable_operations_set: + Configurable Operations Set --------------------------- @@ -63,6 +65,8 @@ modules that built on top of the core layer using the API, which can be easily used by the user space end users. +.. _damon_operations_set: + Operations Set Layer ==================== @@ -71,16 +75,26 @@ The monitoring operations are defined in two parts: 1. Identification of the monitoring target address range for the address space. 2. Access check of specific address range in the target space. -DAMON currently provides the implementations of the operations for the physical -and virtual address spaces. Below two subsections describe how those work. +DAMON currently provides below three operation sets. Below two subsections +describe how those work. + + - vaddr: Monitor virtual address spaces of specific processes + - fvaddr: Monitor fixed virtual address ranges + - paddr: Monitor the physical address space of the system + .. _damon_design_vaddr_target_regions_construction: + VMA-based Target Address Range Construction ------------------------------------------- -This is only for the virtual address space monitoring operations -implementation. That for the physical address space simply asks users to -manually set the monitoring target address ranges. +A mechanism of ``vaddr`` DAMON operations set that automatically initializes +and updates the monitoring target address regions so that entire memory +mappings of the target processes can be covered. + +This mechanism is only for the ``vaddr`` operations set. In cases of +``fvaddr`` and ``paddr`` operation sets, users are asked to manually set the +monitoring target address ranges. Only small parts in the super-huge virtual address space of the processes are mapped to the physical memory and accessed. Thus, tracking the unmapped @@ -294,9 +308,29 @@ not mandated to support all actions of the list. Hence, the availability of specific DAMOS action depends on what operations set is selected to be used together. -Applying an action to a region is considered as changing the region's -characteristics. Hence, DAMOS resets the age of regions when an action is -applied to those. +The list of the supported actions, their meaning, and DAMON operations sets +that supports each action are as below. + + - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. + Supported by ``vaddr``, ``fvaddr`` and ``paddr`` operations set. + - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. + Supported by ``vaddr`` and ``fvaddr`` operations set. + - ``lru_prio``: Prioritize the region on its LRU lists. + Supported by ``paddr`` operations set. + - ``lru_deprio``: Deprioritize the region on its LRU lists. + Supported by ``paddr`` operations set. + - ``stat``: Do nothing but count the statistics. + Supported by all operations sets. + +Applying the actions except ``stat`` to a region is considered as changing the +region's characteristics. Hence, DAMOS resets the age of regions when any such +actions are applied to those. .. _damon_design_damos_access_pattern: @@ -364,12 +398,28 @@ Aim-oriented Feedback-driven Auto-tuning ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Automatic feedback-driven quota tuning. Instead of setting the absolute quota -value, users can repeatedly provide numbers representing how much of their goal -for the scheme is achieved as feedback. DAMOS then automatically tunes the +value, users can specify the metric of their interest, and what target value +they want the metric value to be. DAMOS then automatically tunes the aggressiveness (the quota) of the corresponding scheme. For example, if DAMOS is under achieving the goal, DAMOS automatically increases the quota. If DAMOS is over achieving the goal, it decreases the quota. +The goal can be specified with three parameters, namely ``target_metric``, +``target_value``, and ``current_value``. The auto-tuning mechanism tries to +make ``current_value`` of ``target_metric`` be same to ``target_value``. +Currently, two ``target_metric`` are provided. + +- ``user_input``: User-provided value. Users could use any metric that they + has interest in for the value. Use space main workload's latency or + throughput, system metrics like free memory ratio or memory pressure stall + time (PSI) could be examples. Note that users should explicitly set + ``current_value`` on their own in this case. In other words, users should + repeatedly provide the feedback. +- ``some_mem_psi_us``: System-wide ``some`` memory pressure stall information + in microseconds that measured from last quota reset to next quota reset. + DAMOS does the measurement on its own, so only ``target_value`` need to be + set by users at the initial time. In other words, DAMOS does self-feedback. + .. _damon_design_damos_watermarks: diff --git a/Documentation/mm/damon/maintainer-profile.rst b/Documentation/mm/damon/maintainer-profile.rst index a84c14e5905307..5a306e4de22e50 100644 --- a/Documentation/mm/damon/maintainer-profile.rst +++ b/Documentation/mm/damon/maintainer-profile.rst @@ -21,8 +21,8 @@ be queued in mm-stable [3]_ , and finally pull-requested to the mainline by the memory management subsystem maintainer. Note again the patches for review should be made against the mm-unstable -tree[1] whenever possible. damon/next is only for preview of others' works in -progress. +tree [1]_ whenever possible. damon/next is only for preview of others' works +in progress. Submit checklist addendum ------------------------- @@ -41,8 +41,8 @@ Further doing below and putting the results will be helpful. Key cycle dates --------------- -Patches can be sent anytime. Key cycle dates of the mm-unstable[1] and -mm-stable[3] trees depend on the memory management subsystem maintainer. +Patches can be sent anytime. Key cycle dates of the mm-unstable [1]_ and +mm-stable [3]_ trees depend on the memory management subsystem maintainer. Review cadence -------------- diff --git a/Documentation/mm/page_owner.rst b/Documentation/mm/page_owner.rst index 62e3f7ab23cc18..0d0334cd51798b 100644 --- a/Documentation/mm/page_owner.rst +++ b/Documentation/mm/page_owner.rst @@ -24,6 +24,11 @@ fragmentation statistics can be obtained through gfp flag information of each page. It is already implemented and activated if page owner is enabled. Other usages are more than welcome. +It can also be used to show all the stacks and their outstanding +allocations, which gives us a quick overview of where the memory is going +without the need to screen through all the pages and match the allocation +and free operation. + page owner is disabled by default. So, if you'd like to use it, you need to add "page_owner=on" to your boot cmdline. If the kernel is built with page owner and page owner is disabled in runtime due to not enabling @@ -68,6 +73,46 @@ Usage 4) Analyze information from page owner:: + cat /sys/kernel/debug/page_owner_stacks/show_stacks > stacks.txt + cat stacks.txt + prep_new_page+0xa9/0x120 + get_page_from_freelist+0x7e6/0x2140 + __alloc_pages+0x18a/0x370 + new_slab+0xc8/0x580 + ___slab_alloc+0x1f2/0xaf0 + __slab_alloc.isra.86+0x22/0x40 + kmem_cache_alloc+0x31b/0x350 + __khugepaged_enter+0x39/0x100 + dup_mmap+0x1c7/0x5ce + copy_process+0x1afe/0x1c90 + kernel_clone+0x9a/0x3c0 + __do_sys_clone+0x66/0x90 + do_syscall_64+0x7f/0x160 + entry_SYSCALL_64_after_hwframe+0x6c/0x74 + stack_count: 234 + ... + ... + echo 7000 > /sys/kernel/debug/page_owner_stacks/count_threshold + cat /sys/kernel/debug/page_owner_stacks/show_stacks> stacks_7000.txt + cat stacks_7000.txt + prep_new_page+0xa9/0x120 + get_page_from_freelist+0x7e6/0x2140 + __alloc_pages+0x18a/0x370 + alloc_pages_mpol+0xdf/0x1e0 + folio_alloc+0x14/0x50 + filemap_alloc_folio+0xb0/0x100 + page_cache_ra_unbounded+0x97/0x180 + filemap_fault+0x4b4/0x1200 + __do_fault+0x2d/0x110 + do_pte_missing+0x4b0/0xa30 + __handle_mm_fault+0x7fa/0xb70 + handle_mm_fault+0x125/0x300 + do_user_addr_fault+0x3c9/0x840 + exc_page_fault+0x68/0x150 + asm_exc_page_fault+0x22/0x30 + stack_count: 8248 + ... + cat /sys/kernel/debug/page_owner > page_owner_full.txt ./page_owner_sort page_owner_full.txt sorted_page_owner.txt diff --git a/Documentation/mm/slub.rst b/Documentation/mm/slub.rst index be75971532f57d..b517ee28a9552d 100644 --- a/Documentation/mm/slub.rst +++ b/Documentation/mm/slub.rst @@ -9,7 +9,7 @@ SLUB can enable debugging only for selected slabs in order to avoid an impact on overall system performance which may make a bug more difficult to find. -In order to switch debugging on one can add an option ``slub_debug`` +In order to switch debugging on one can add an option ``slab_debug`` to the kernel command line. That will enable full debugging for all slabs. @@ -26,16 +26,16 @@ be enabled on the command line. F.e. no tracking information will be available without debugging on and validation can only partially be performed if debugging was not switched on. -Some more sophisticated uses of slub_debug: +Some more sophisticated uses of slab_debug: ------------------------------------------- -Parameters may be given to ``slub_debug``. If none is specified then full +Parameters may be given to ``slab_debug``. If none is specified then full debugging is enabled. Format: -slub_debug= +slab_debug= Enable options for all slabs -slub_debug=,,,... +slab_debug=,,,... Enable options only for select slabs (no spaces after a comma) @@ -60,23 +60,23 @@ Possible debug options are:: F.e. in order to boot just with sanity checks and red zoning one would specify:: - slub_debug=FZ + slab_debug=FZ Trying to find an issue in the dentry cache? Try:: - slub_debug=,dentry + slab_debug=,dentry 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 + slab_debug=P,kmalloc-*,dentry Red zoning and tracking may realign the slab. We can just apply sanity checks to the dentry cache with:: - slub_debug=F,dentry + slab_debug=F,dentry Debugging options may require the minimum possible slab order to increase as a result of storing the metadata (for example, caches with PAGE_SIZE object @@ -84,20 +84,20 @@ sizes). This has a higher liklihood of resulting in slab allocation errors in low memory situations or if there's high fragmentation of memory. To switch off debugging for such caches by default, use:: - slub_debug=O + slab_debug=O You can apply different options to different list of slab names, using blocks of options. This will enable red zoning for dentry and user tracking for kmalloc. All other slabs will not get any debugging enabled:: - slub_debug=Z,dentry;U,kmalloc-* + slab_debug=Z,dentry;U,kmalloc-* You can also enable options (e.g. sanity checks and poisoning) for all caches except some that are deemed too performance critical and don't need to be debugged by specifying global debug options followed by a list of slab names with "-" as options:: - slub_debug=FZ;-,zs_handle,zspage + slab_debug=FZ;-,zs_handle,zspage The state of each debug option for a slab can be found in the respective files under:: @@ -105,7 +105,7 @@ under:: /sys/kernel/slab// If the file contains 1, the option is enabled, 0 means disabled. The debug -options from the ``slub_debug`` parameter translate to the following files:: +options from the ``slab_debug`` parameter translate to the following files:: F sanity_checks Z red_zone @@ -129,7 +129,7 @@ in order to reduce overhead and increase cache hotness of objects. Slab validation =============== -SLUB can validate all object if the kernel was booted with slub_debug. In +SLUB can validate all object if the kernel was booted with slab_debug. In order to do so you must have the ``slabinfo`` tool. Then you can do :: @@ -150,29 +150,29 @@ list_lock once in a while to deal with partial slabs. That overhead is governed by the order of the allocation for each slab. The allocations can be influenced by kernel parameters: -.. slub_min_objects=x (default 4) -.. slub_min_order=x (default 0) -.. slub_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER)) +.. slab_min_objects=x (default: automatically scaled by number of cpus) +.. slab_min_order=x (default 0) +.. slab_max_order=x (default 3 (PAGE_ALLOC_COSTLY_ORDER)) -``slub_min_objects`` +``slab_min_objects`` allows to specify how many objects must at least fit into one slab in order for the allocation order to be acceptable. In general slub will be able to perform this number of allocations on a slab without consulting centralized resources (list_lock) where contention may occur. -``slub_min_order`` +``slab_min_order`` specifies a minimum order of slabs. A similar effect like - ``slub_min_objects``. + ``slab_min_objects``. -``slub_max_order`` - specified the order at which ``slub_min_objects`` should no +``slab_max_order`` + specified the order at which ``slab_min_objects`` should no longer be checked. This is useful to avoid SLUB trying to - generate super large order pages to fit ``slub_min_objects`` + generate super large order pages to fit ``slab_min_objects`` of a slab cache with large object sizes into one high order page. Setting command line parameter ``debug_guardpage_minorder=N`` (N > 0), forces setting - ``slub_max_order`` to 0, what cause minimum possible order of + ``slab_max_order`` to 0, what cause minimum possible order of slabs allocation. SLUB Debug output @@ -219,7 +219,7 @@ Here is a sample of slub debug output:: FIX kmalloc-8: Restoring Redzone 0xc90f6d28-0xc90f6d2b=0xcc If SLUB encounters a corrupted object (full detection requires the kernel -to be booted with slub_debug) then the following output will be dumped +to be booted with slab_debug) then the following output will be dumped into the syslog: 1. Description of the problem encountered @@ -239,7 +239,7 @@ into the syslog: pid= (Object allocation / free information is only available if SLAB_STORE_USER is - set for the slab. slub_debug sets that option) + set for the slab. slab_debug sets that option) 2. The object contents if an object was involved. @@ -262,7 +262,7 @@ into the syslog: the object boundary. (Redzone information is only available if SLAB_RED_ZONE is set. - slub_debug sets that option) + slab_debug sets that option) Padding
: Unused data to fill up the space in order to get the next object @@ -296,7 +296,7 @@ Emergency operations Minimal debugging (sanity checks alone) can be enabled by booting with:: - slub_debug=F + slab_debug=F This will be generally be enough to enable the resiliency features of slub which will keep the system running even if a bad kernel component will @@ -311,13 +311,13 @@ and enabling debugging only for that cache I.e.:: - slub_debug=F,dentry + slab_debug=F,dentry If the corruption occurs by writing after the end of the object then it may be advisable to enable a Redzone to avoid corrupting the beginning of other objects:: - slub_debug=FZ,dentry + slab_debug=FZ,dentry Extended slabinfo mode and plotting =================================== diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml index 04b92f1a5cd6ef..ac4e05415f2f5e 100644 --- a/Documentation/netlink/netlink-raw.yaml +++ b/Documentation/netlink/netlink-raw.yaml @@ -152,14 +152,23 @@ properties: the right formatting mechanism when displaying values of this type. enum: [ hex, mac, fddi, ipv4, ipv6, uuid ] + struct: + description: Name of the nested struct type. + type: string if: properties: type: - oneOf: - - const: binary - - const: pad + const: pad then: required: [ len ] + if: + properties: + type: + const: binary + then: + oneOf: + - required: [ len ] + - required: [ struct ] # End genetlink-legacy attribute-sets: diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml index b14aed18065f43..8dc1df5cfae746 100644 --- a/Documentation/netlink/specs/dpll.yaml +++ b/Documentation/netlink/specs/dpll.yaml @@ -51,6 +51,40 @@ definitions: if dpll lock-state was not DPLL_LOCK_STATUS_LOCKED_HO_ACQ, the dpll's lock-state shall remain DPLL_LOCK_STATUS_UNLOCKED) render-max: true + - + type: enum + name: lock-status-error + doc: | + if previous status change was done due to a failure, this provides + information of dpll device lock status error. + Valid values for DPLL_A_LOCK_STATUS_ERROR attribute + entries: + - + name: none + doc: | + dpll device lock status was changed without any error + value: 1 + - + name: undefined + doc: | + dpll device lock status was changed due to undefined error. + Driver fills this value up in case it is not able + to obtain suitable exact error type. + - + name: media-down + doc: | + dpll device lock status was changed because of associated + media got down. + This may happen for example if dpll device was previously + locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT. + - + name: fractional-frequency-offset-too-high + doc: | + the FFO (Fractional Frequency Offset) between the RX and TX + symbol rate on the media got too high. + This may happen for example if dpll device was previously + locked on an input pin of type PIN_TYPE_SYNCE_ETH_PORT. + render-max: true - type: const name: temp-divider @@ -214,6 +248,10 @@ attribute-sets: name: type type: u32 enum: type + - + name: lock-status-error + type: u32 + enum: lock-status-error - name: pin enum-name: dpll_a_pin @@ -379,13 +417,12 @@ operations: - mode - mode-supported - lock-status + - lock-status-error - temp - clock-id - type dump: - pre: dpll-lock-dumpit - post: dpll-unlock-dumpit reply: *dev-attrs - @@ -473,8 +510,6 @@ operations: - fractional-frequency-offset dump: - pre: dpll-lock-dumpit - post: dpll-unlock-dumpit request: attributes: - id diff --git a/Documentation/netlink/specs/rt_link.yaml b/Documentation/netlink/specs/rt_link.yaml index 1ad01d52a8638d..8e4d19adee8cd1 100644 --- a/Documentation/netlink/specs/rt_link.yaml +++ b/Documentation/netlink/specs/rt_link.yaml @@ -942,6 +942,10 @@ attribute-sets: - name: gro-ipv4-max-size type: u32 + - + name: dpll-pin + type: nest + nested-attributes: link-dpll-pin-attrs - name: af-spec-attrs attributes: @@ -1627,6 +1631,12 @@ attribute-sets: - name: used type: u8 + - + name: link-dpll-pin-attrs + attributes: + - + name: id + type: u32 sub-messages: - diff --git a/Documentation/netlink/specs/tc.yaml b/Documentation/netlink/specs/tc.yaml index 4346fa402fc91d..324fa182cd1491 100644 --- a/Documentation/netlink/specs/tc.yaml +++ b/Documentation/netlink/specs/tc.yaml @@ -48,21 +48,28 @@ definitions: - name: bytes type: u64 + doc: Number of enqueued bytes - name: packets type: u32 + doc: Number of enqueued packets - name: drops type: u32 + doc: Packets dropped because of lack of resources - name: overlimits type: u32 + doc: | + Number of throttle events when this flow goes out of allocated bandwidth - name: bps type: u32 + doc: Current flow byte rate - name: pps type: u32 + doc: Current flow packet rate - name: qlen type: u32 @@ -112,6 +119,7 @@ definitions: - name: limit type: u32 + doc: Queue length; bytes for bfifo, packets for pfifo - name: tc-htb-opt type: struct @@ -119,11 +127,11 @@ definitions: - name: rate type: binary - len: 12 + struct: tc-ratespec - name: ceil type: binary - len: 12 + struct: tc-ratespec - name: buffer type: u32 @@ -149,15 +157,19 @@ definitions: - name: rate2quantum type: u32 + doc: bps->quantum divisor - name: defcls type: u32 + doc: Default class number - name: debug type: u32 + doc: Debug flags - name: direct-pkts type: u32 + doc: Count of non shaped packets - name: tc-gred-qopt type: struct @@ -165,15 +177,19 @@ definitions: - name: limit type: u32 + doc: HARD maximal queue length in bytes - name: qth-min type: u32 + doc: Min average length threshold in bytes - name: qth-max type: u32 + doc: Max average length threshold in bytes - name: DP type: u32 + doc: Up to 2^32 DPs - name: backlog type: u32 @@ -195,15 +211,19 @@ definitions: - name: Wlog type: u8 + doc: log(W) - name: Plog type: u8 + doc: log(P_max / (qth-max - qth-min)) - name: Scell_log type: u8 + doc: cell size for idle damping - name: prio type: u8 + doc: Priority of this VQ - name: packets type: u32 @@ -266,9 +286,11 @@ definitions: - name: bands type: u16 + doc: Number of bands - name: max-bands type: u16 + doc: Maximum number of queues - name: tc-netem-qopt type: struct @@ -276,21 +298,138 @@ definitions: - name: latency type: u32 + doc: Added delay in microseconds - name: limit type: u32 + doc: Fifo limit in packets - name: loss type: u32 + doc: Random packet loss (0=none, ~0=100%) - name: gap type: u32 + doc: Re-ordering gap (0 for none) - name: duplicate type: u32 + doc: Random packet duplication (0=none, ~0=100%) - name: jitter type: u32 + doc: Random jitter latency in microseconds + - + name: tc-netem-gimodel + doc: State transition probabilities for 4 state model + type: struct + members: + - + name: p13 + type: u32 + - + name: p31 + type: u32 + - + name: p32 + type: u32 + - + name: p14 + type: u32 + - + name: p23 + type: u32 + - + name: tc-netem-gemodel + doc: Gilbert-Elliot models + type: struct + members: + - + name: p + type: u32 + - + name: r + type: u32 + - + name: h + type: u32 + - + name: k1 + type: u32 + - + name: tc-netem-corr + type: struct + members: + - + name: delay-corr + type: u32 + doc: Delay correlation + - + name: loss-corr + type: u32 + doc: Packet loss correlation + - + name: dup-corr + type: u32 + doc: Duplicate correlation + - + name: tc-netem-reorder + type: struct + members: + - + name: probability + type: u32 + - + name: correlation + type: u32 + - + name: tc-netem-corrupt + type: struct + members: + - + name: probability + type: u32 + - + name: correlation + type: u32 + - + name: tc-netem-rate + type: struct + members: + - + name: rate + type: u32 + - + name: packet-overhead + type: s32 + - + name: cell-size + type: u32 + - + name: cell-overhead + type: s32 + - + name: tc-netem-slot + type: struct + members: + - + name: min-delay + type: s64 + - + name: max-delay + type: s64 + - + name: max-packets + type: s32 + - + name: max-bytes + type: s32 + - + name: dist-delay + type: s64 + - + name: dist-jitter + type: s64 - name: tc-plug-qopt type: struct @@ -307,11 +446,13 @@ definitions: members: - name: bands - type: u16 + type: u32 + doc: Number of bands - name: priomap type: binary len: 16 + doc: Map of logical priority -> PRIO band - name: tc-red-qopt type: struct @@ -319,21 +460,27 @@ definitions: - name: limit type: u32 + doc: Hard queue length in packets - name: qth-min type: u32 + doc: Min average threshold in packets - name: qth-max type: u32 + doc: Max average threshold in packets - name: Wlog type: u8 + doc: log(W) - name: Plog type: u8 + doc: log(P_max / (qth-max - qth-min)) - name: Scell-log type: u8 + doc: Cell size for idle damping - name: flags type: u8 @@ -369,71 +516,128 @@ definitions: name: penalty-burst type: u32 - - name: tc-sfq-qopt-v1 # TODO nested structs + name: tc-sfq-qopt type: struct members: - name: quantum type: u32 + doc: Bytes per round allocated to flow - name: perturb-period type: s32 + doc: Period of hash perturbation - name: limit type: u32 + doc: Maximal packets in queue - name: divisor type: u32 + doc: Hash divisor - name: flows type: u32 + doc: Maximal number of flows + - + name: tc-sfqred-stats + type: struct + members: + - + name: prob-drop + type: u32 + doc: Early drops, below max threshold + - + name: forced-drop + type: u32 + doc: Early drops, after max threshold + - + name: prob-mark + type: u32 + doc: Marked packets, below max threshold + - + name: forced-mark + type: u32 + doc: Marked packets, after max threshold + - + name: prob-mark-head + type: u32 + doc: Marked packets, below max threshold + - + name: forced-mark-head + type: u32 + doc: Marked packets, after max threshold + - + name: tc-sfq-qopt-v1 + type: struct + members: + - + name: v0 + type: binary + struct: tc-sfq-qopt - name: depth type: u32 + doc: Maximum number of packets per flow - name: headdrop type: u32 - name: limit type: u32 + doc: HARD maximal flow queue length in bytes - name: qth-min type: u32 + doc: Min average length threshold in bytes - - name: qth-mac + name: qth-max type: u32 + doc: Max average length threshold in bytes - name: Wlog type: u8 + doc: log(W) - name: Plog type: u8 + doc: log(P_max / (qth-max - qth-min)) - name: Scell-log type: u8 + doc: Cell size for idle damping - name: flags type: u8 - name: max-P type: u32 + doc: probabilty, high resolution - - name: prob-drop - type: u32 + name: stats + type: binary + struct: tc-sfqred-stats + - + name: tc-ratespec + type: struct + members: - - name: forced-drop - type: u32 + name: cell-log + type: u8 - - name: prob-mark - type: u32 + name: linklayer + type: u8 - - name: forced-mark - type: u32 + name: overhead + type: u8 - - name: prob-mark-head - type: u32 + name: cell-align + type: u8 - - name: forced-mark-head + name: mpu + type: u8 + - + name: rate type: u32 - name: tc-tbf-qopt @@ -441,12 +645,12 @@ definitions: members: - name: rate - type: binary # TODO nested struct tc_ratespec - len: 12 + type: binary + struct: tc-ratespec - name: peakrate - type: binary # TODO nested struct tc_ratespec - len: 12 + type: binary + struct: tc-ratespec - name: limit type: u32 @@ -491,67 +695,1299 @@ definitions: - name: interval type: s8 + doc: Sampling period + - + name: ewma-log + type: u8 + doc: The log() of measurement window weight + - + name: tc-choke-xstats + type: struct + members: + - + name: early + type: u32 + doc: Early drops + - + name: pdrop + type: u32 + doc: Drops due to queue limits + - + name: other + type: u32 + doc: Drops due to drop() calls + - + name: marked + type: u32 + doc: Marked packets + - + name: matched + type: u32 + doc: Drops due to flow match + - + name: tc-codel-xstats + type: struct + members: + - + name: maxpacket + type: u32 + doc: Largest packet we've seen so far + - + name: count + type: u32 + doc: How many drops we've done since the last time we entered dropping state + - + name: lastcount + type: u32 + doc: Count at entry to dropping state + - + name: ldelay + type: u32 + doc: in-queue delay seen by most recently dequeued packet + - + name: drop-next + type: s32 + doc: Time to drop next packet + - + name: drop-overlimit + type: u32 + doc: Number of times max qdisc packet limit was hit + - + name: ecn-mark + type: u32 + doc: Number of packets we've ECN marked instead of dropped + - + name: dropping + type: u32 + doc: Are we in a dropping state? + - + name: ce-mark + type: u32 + doc: Number of CE marked packets because of ce-threshold + - + name: tc-fq-codel-xstats + type: struct + members: + - + name: type + type: u32 + - + name: maxpacket + type: u32 + doc: Largest packet we've seen so far + - + name: drop-overlimit + type: u32 + doc: Number of times max qdisc packet limit was hit + - + name: ecn-mark + type: u32 + doc: Number of packets we ECN marked instead of being dropped + - + name: new-flow-count + type: u32 + doc: Number of times packets created a new flow + - + name: new-flows-len + type: u32 + doc: Count of flows in new list + - + name: old-flows-len + type: u32 + doc: Count of flows in old list + - + name: ce-mark + type: u32 + doc: Packets above ce-threshold + - + name: memory-usage + type: u32 + doc: Memory usage in bytes + - + name: drop-overmemory + type: u32 + - + name: tc-fq-pie-xstats + type: struct + members: + - + name: packets-in + type: u32 + doc: Total number of packets enqueued + - + name: dropped + type: u32 + doc: Packets dropped due to fq_pie_action + - + name: overlimit + type: u32 + doc: Dropped due to lack of space in queue + - + name: overmemory + type: u32 + doc: Dropped due to lack of memory in queue + - + name: ecn-mark + type: u32 + doc: Packets marked with ecn + - + name: new-flow-count + type: u32 + doc: Count of new flows created by packets + - + name: new-flows-len + type: u32 + doc: Count of flows in new list + - + name: old-flows-len + type: u32 + doc: Count of flows in old list + - + name: memory-usage + type: u32 + doc: Total memory across all queues + - + name: tc-fq-qd-stats + type: struct + members: + - + name: gc-flows + type: u64 + - + name: highprio-packets + type: u64 + doc: obsolete + - + name: tcp-retrans + type: u64 + doc: obsolete + - + name: throttled + type: u64 + - + name: flows-plimit + type: u64 + - + name: pkts-too-long + type: u64 + - + name: allocation-errors + type: u64 + - + name: time-next-delayed-flow + type: s64 + - + name: flows + type: u32 + - + name: inactive-flows + type: u32 + - + name: throttled-flows + type: u32 + - + name: unthrottle-latency-ns + type: u32 + - + name: ce-mark + type: u64 + doc: Packets above ce-threshold + - + name: horizon-drops + type: u64 + - + name: horizon-caps + type: u64 + - + name: fastpath-packets + type: u64 + - + name: band-drops + type: binary + len: 24 + - + name: band-pkt-count + type: binary + len: 12 + - + name: pad + type: pad + len: 4 + - + name: tc-hhf-xstats + type: struct + members: + - + name: drop-overlimit + type: u32 + doc: Number of times max qdisc packet limit was hit + - + name: hh-overlimit + type: u32 + doc: Number of times max heavy-hitters was hit + - + name: hh-tot-count + type: u32 + doc: Number of captured heavy-hitters so far + - + name: hh-cur-count + type: u32 + doc: Number of current heavy-hitters + - + name: tc-pie-xstats + type: struct + members: + - + name: prob + type: u64 + doc: Current probability + - + name: delay + type: u32 + doc: Current delay in ms + - + name: avg-dq-rate + type: u32 + doc: Current average dq rate in bits/pie-time + - + name: dq-rate-estimating + type: u32 + doc: Is avg-dq-rate being calculated? + - + name: packets-in + type: u32 + doc: Total number of packets enqueued + - + name: dropped + type: u32 + doc: Packets dropped due to pie action + - + name: overlimit + type: u32 + doc: Dropped due to lack of space in queue + - + name: maxq + type: u32 + doc: Maximum queue size + - + name: ecn-mark + type: u32 + doc: Packets marked with ecn + - + name: tc-red-xstats + type: struct + members: + - + name: early + type: u32 + doc: Early drops + - + name: pdrop + type: u32 + doc: Drops due to queue limits + - + name: other + type: u32 + doc: Drops due to drop() calls + - + name: marked + type: u32 + doc: Marked packets + - + name: tc-sfb-xstats + type: struct + members: + - + name: earlydrop + type: u32 + - + name: penaltydrop + type: u32 + - + name: bucketdrop + type: u32 + - + name: queuedrop + type: u32 + - + name: childdrop + type: u32 + doc: drops in child qdisc + - + name: marked + type: u32 + - + name: maxqlen + type: u32 + - + name: maxprob + type: u32 + - + name: avgprob + type: u32 + - + name: tc-sfq-xstats + type: struct + members: + - + name: allot + type: s32 + - + name: gnet-stats-basic + type: struct + members: + - + name: bytes + type: u64 + - + name: packets + type: u32 + - + name: gnet-stats-rate-est + type: struct + members: + - + name: bps + type: u32 + - + name: pps + type: u32 + - + name: gnet-stats-rate-est64 + type: struct + members: + - + name: bps + type: u64 + - + name: pps + type: u64 + - + name: gnet-stats-queue + type: struct + members: + - + name: qlen + type: u32 + - + name: backlog + type: u32 + - + name: drops + type: u32 + - + name: requeues + type: u32 + - + name: overlimits + type: u32 + - + name: tc-u32-key + type: struct + members: + - + name: mask + type: u32 + byte-order: big-endian + - + name: val + type: u32 + byte-order: big-endian + - + name: "off" + type: s32 + - + name: offmask + type: s32 + - + name: tc-u32-sel + type: struct + members: + - + name: flags + type: u8 + - + name: offshift + type: u8 + - + name: nkeys + type: u8 + - + name: offmask + type: u16 + byte-order: big-endian + - + name: "off" + type: u16 + - + name: offoff + type: s16 + - + name: hoff + type: s16 + - + name: hmask + type: u32 + byte-order: big-endian + - + name: keys + type: binary + struct: tc-u32-key # TODO: array + - + name: tc-u32-pcnt + type: struct + members: + - + name: rcnt + type: u64 + - + name: rhit + type: u64 + - + name: kcnts + type: u64 # TODO: array + - + name: tcf-t + type: struct + members: + - + name: install + type: u64 + - + name: lastuse + type: u64 + - + name: expires + type: u64 + - + name: firstuse + type: u64 + - + name: tc-gen + type: struct + members: + - + name: index + type: u32 + - + name: capab + type: u32 + - + name: action + type: s32 + - + name: refcnt + type: s32 + - + name: bindcnt + type: s32 + - + name: tc-gact-p + type: struct + members: + - + name: ptype + type: u16 + - + name: pval + type: u16 + - + name: paction + type: s32 + - + name: tcf-ematch-tree-hdr + type: struct + members: + - + name: nmatches + type: u16 + - + name: progid + type: u16 + - + name: tc-basic-pcnt + type: struct + members: + - + name: rcnt + type: u64 + - + name: rhit + type: u64 + - + name: tc-matchall-pcnt + type: struct + members: + - + name: rhit + type: u64 + - + name: tc-mpls + type: struct + members: + - + name: index + type: u32 + - + name: capab + type: u32 + - + name: action + type: s32 + - + name: refcnt + type: s32 + - + name: bindcnt + type: s32 + - + name: m-action + type: s32 + - + name: tc-police + type: struct + members: + - + name: index + type: u32 + - + name: action + type: s32 + - + name: limit + type: u32 + - + name: burst + type: u32 + - + name: mtu + type: u32 + - + name: rate + type: binary + struct: tc-ratespec + - + name: peakrate + type: binary + struct: tc-ratespec + - + name: refcnt + type: s32 + - + name: bindcnt + type: s32 + - + name: capab + type: u32 + - + name: tc-pedit-sel + type: struct + members: + - + name: index + type: u32 + - + name: capab + type: u32 + - + name: action + type: s32 + - + name: refcnt + type: s32 + - + name: bindcnt + type: s32 + - + name: nkeys + type: u8 + - + name: flags + type: u8 + - + name: keys + type: binary + struct: tc-pedit-key # TODO: array + - + name: tc-pedit-key + type: struct + members: + - + name: mask + type: u32 + - + name: val + type: u32 + - + name: "off" + type: u32 + - + name: at + type: u32 + - + name: offmask + type: u32 + - + name: shift + type: u32 + - + name: tc-vlan + type: struct + members: + - + name: index + type: u32 + - + name: capab + type: u32 + - + name: action + type: s32 + - + name: refcnt + type: s32 + - + name: bindcnt + type: s32 + - + name: v-action + type: s32 +attribute-sets: + - + name: tc-attrs + attributes: + - + name: kind + type: string + - + name: options + type: sub-message + sub-message: tc-options-msg + selector: kind + - + name: stats + type: binary + struct: tc-stats + - + name: xstats + type: sub-message + sub-message: tca-stats-app-msg + selector: kind + - + name: rate + type: binary + struct: gnet-estimator + - + name: fcnt + type: u32 + - + name: stats2 + type: nest + nested-attributes: tca-stats-attrs + - + name: stab + type: nest + nested-attributes: tca-stab-attrs + - + name: pad + type: pad + - + name: dump-invisible + type: flag + - + name: chain + type: u32 + - + name: hw-offload + type: u8 + - + name: ingress-block + type: u32 + - + name: egress-block + type: u32 + - + name: dump-flags + type: bitfield32 + - + name: ext-warn-msg + type: string + - + name: tc-act-attrs + attributes: + - + name: kind + type: string + - + name: options + type: sub-message + sub-message: tc-act-options-msg + selector: kind + - + name: index + type: u32 + - + name: stats + type: nest + nested-attributes: tc-act-stats-attrs + - + name: pad + type: pad + - + name: cookie + type: binary + - + name: flags + type: bitfield32 + - + name: hw-stats + type: bitfield32 + - + name: used-hw-stats + type: bitfield32 + - + name: in-hw-count + type: u32 + - + name: tc-act-stats-attrs + attributes: + - + name: basic + type: binary + struct: gnet-stats-basic + - + name: rate-est + type: binary + struct: gnet-stats-rate-est + - + name: queue + type: binary + struct: gnet-stats-queue + - + name: app + type: binary + - + name: rate-est64 + type: binary + struct: gnet-stats-rate-est64 + - + name: pad + type: pad + - + name: basic-hw + type: binary + struct: gnet-stats-basic + - + name: pkt64 + type: u64 + - + name: tc-act-bpf-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: ops-len + type: u16 + - + name: ops + type: binary + - + name: fd + type: u32 + - + name: name + type: string + - + name: pad + type: pad + - + name: tag + type: binary + - + name: id + type: binary + - + name: tc-act-connmark-attrs + attributes: + - + name: parms + type: binary + - + name: tm + type: binary + struct: tcf-t + - + name: pad + type: pad + - + name: tc-act-csum-attrs + attributes: + - + name: parms + type: binary + - + name: tm + type: binary + struct: tcf-t + - + name: pad + type: pad + - + name: tc-act-ct-attrs + attributes: + - + name: parms + type: binary + - + name: tm + type: binary + struct: tcf-t + - + name: action + type: u16 + - + name: zone + type: u16 + - + name: mark + type: u32 + - + name: mark-mask + type: u32 + - + name: labels + type: binary + - + name: labels-mask + type: binary + - + name: nat-ipv4-min + type: u32 + byte-order: big-endian + - + name: nat-ipv4-max + type: u32 + byte-order: big-endian + - + name: nat-ipv6-min + type: binary + - + name: nat-ipv6-max + type: binary + - + name: nat-port-min + type: u16 + byte-order: big-endian + - + name: nat-port-max + type: u16 + byte-order: big-endian + - + name: pad + type: pad + - + name: helper-name + type: string + - + name: helper-family + type: u8 + - + name: helper-proto + type: u8 + - + name: tc-act-ctinfo-attrs + attributes: + - + name: pad + type: pad + - + name: tm + type: binary + struct: tcf-t + - + name: act + type: binary + - + name: zone + type: u16 + - + name: parms-dscp-mask + type: u32 + - + name: parms-dscp-statemask + type: u32 + - + name: parms-cpmark-mask + type: u32 + - + name: stats-dscp-set + type: u64 + - + name: stats-dscp-error + type: u64 + - + name: stats-cpmark-set + type: u64 + - + name: tc-act-gate-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: pad + type: pad + - + name: priority + type: s32 + - + name: entry-list + type: binary + - + name: base-time + type: u64 + - + name: cycle-time + type: u64 + - + name: cycle-time-ext + type: u64 + - + name: flags + type: u32 + - + name: clockid + type: s32 + - + name: tc-act-ife-attrs + attributes: + - + name: parms + type: binary + - + name: tm + type: binary + struct: tcf-t + - + name: dmac + type: binary + - + name: smac + type: binary + - + name: type + type: u16 + - + name: metalst + type: binary + - + name: pad + type: pad + - + name: tc-act-mirred-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: pad + type: pad + - + name: blockid + type: binary + - + name: tc-act-mpls-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + struct: tc-mpls + - + name: pad + type: pad + - + name: proto + type: u16 + byte-order: big-endian + - + name: label + type: u32 + - + name: tc + type: u8 + - + name: ttl + type: u8 + - + name: bos + type: u8 + - + name: tc-act-nat-attrs + attributes: + - + name: parms + type: binary + - + name: tm + type: binary + struct: tcf-t + - + name: pad + type: pad + - + name: tc-act-pedit-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + struct: tc-pedit-sel + - + name: pad + type: pad + - + name: parms-ex + type: binary + - + name: keys-ex + type: binary + - + name: key-ex + type: binary + - + name: tc-act-simple-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: data + type: binary + - + name: pad + type: pad + - + name: tc-act-skbedit-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: priority + type: u32 + - + name: queue-mapping + type: u16 + - + name: mark + type: u32 + - + name: pad + type: pad + - + name: ptype + type: u16 + - + name: mask + type: u32 + - + name: flags + type: u64 + - + name: queue-mapping-max + type: u16 + - + name: tc-act-skbmod-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: dmac + type: binary + - + name: smac + type: binary + - + name: etype + type: binary + - + name: pad + type: pad + - + name: tc-act-tunnel-key-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + - + name: enc-ipv4-src + type: u32 + byte-order: big-endian + - + name: enc-ipv4-dst + type: u32 + byte-order: big-endian + - + name: enc-ipv6-src + type: binary + - + name: enc-ipv6-dst + type: binary + - + name: enc-key-id + type: u64 + byte-order: big-endian + - + name: pad + type: pad + - + name: enc-dst-port + type: u16 + byte-order: big-endian + - + name: no-csum + type: u8 + - + name: enc-opts + type: binary + - + name: enc-tos + type: u8 + - + name: enc-ttl + type: u8 + - + name: no-frag + type: flag + - + name: tc-act-vlan-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + struct: tc-vlan - - name: ewma-log - type: u8 -attribute-sets: - - - name: tc-attrs - attributes: + name: push-vlan-id + type: u16 - - name: kind - type: string + name: push-vlan-protocol + type: u16 - - name: options - type: sub-message - sub-message: tc-options-msg - selector: kind + name: pad + type: pad - - name: stats - type: binary - struct: tc-stats + name: push-vlan-priority + type: u8 - - name: xstats + name: push-eth-dst type: binary - - name: rate + name: push-eth-src type: binary - struct: gnet-estimator + - + name: tc-basic-attrs + attributes: - - name: fcnt + name: classid type: u32 - - name: stats2 + name: ematches type: nest - nested-attributes: tca-stats-attrs + nested-attributes: tc-ematch-attrs - - name: stab + name: act + type: array-nest + nested-attributes: tc-act-attrs + - + name: police type: nest - nested-attributes: tca-stab-attrs + nested-attributes: tc-police-attrs + - + name: pcnt + type: binary + struct: tc-basic-pcnt - name: pad type: pad + - + name: tc-bpf-attrs + attributes: - - name: dump-invisible - type: flag + name: act + type: nest + nested-attributes: tc-act-attrs - - name: chain + name: police + type: nest + nested-attributes: tc-police-attrs + - + name: classid type: u32 - - name: hw-offload - type: u8 + name: ops-len + type: u16 - - name: ingress-block + name: ops + type: binary + - + name: fd type: u32 - - name: egress-block + name: name + type: string + - + name: flags type: u32 - - name: dump-flags - type: bitfield32 + name: flags-gen + type: u32 - - name: ext-warn-msg - type: string + name: tag + type: binary + - + name: id + type: u32 - name: tc-cake-attrs attributes: @@ -641,7 +2077,8 @@ attribute-sets: type: u32 - name: tin-stats - type: binary + type: array-nest + nested-attributes: tc-cake-tin-stats-attrs - name: deficit type: s32 @@ -660,6 +2097,84 @@ attribute-sets: - name: blue-timer-us type: s32 + - + name: tc-cake-tin-stats-attrs + attributes: + - + name: pad + type: pad + - + name: sent-packets + type: u32 + - + name: sent-bytes64 + type: u64 + - + name: dropped-packets + type: u32 + - + name: dropped-bytes64 + type: u64 + - + name: acks-dropped-packets + type: u32 + - + name: acks-dropped-bytes64 + type: u64 + - + name: ecn-marked-packets + type: u32 + - + name: ecn-marked-bytes64 + type: u64 + - + name: backlog-packets + type: u32 + - + name: backlog-bytes + type: u32 + - + name: threshold-rate64 + type: u64 + - + name: target-us + type: u32 + - + name: interval-us + type: u32 + - + name: way-indirect-hits + type: u32 + - + name: way-misses + type: u32 + - + name: way-collisions + type: u32 + - + name: peak-delay-us + type: u32 + - + name: avg-delay-us + type: u32 + - + name: base-delay-us + type: u32 + - + name: sparse-flows + type: u32 + - + name: bulk-flows + type: u32 + - + name: unresponsive-flows + type: u32 + - + name: max-skblen + type: u32 + - + name: flow-quantum + type: u32 - name: tc-cbs-attrs attributes: @@ -667,6 +2182,20 @@ attribute-sets: name: parms type: binary struct: tc-cbs-qopt + - + name: tc-cgroup-attrs + attributes: + - + name: act + type: nest + nested-attributes: tc-act-attrs + - + name: police + type: nest + nested-attributes: tc-police-attrs + - + name: ematches + type: binary - name: tc-choke-attrs attributes: @@ -677,6 +2206,9 @@ attribute-sets: - name: stab type: binary + checks: + min-len: 256 + max-len: 256 - name: max-p type: u32 @@ -704,6 +2236,56 @@ attribute-sets: - name: quantum type: u32 + - + name: tc-ematch-attrs + attributes: + - + name: tree-hdr + type: binary + struct: tcf-ematch-tree-hdr + - + name: tree-list + type: binary + - + name: tc-flow-attrs + attributes: + - + name: keys + type: u32 + - + name: mode + type: u32 + - + name: baseclass + type: u32 + - + name: rshift + type: u32 + - + name: addend + type: u32 + - + name: mask + type: u32 + - + name: xor + type: u32 + - + name: divisor + type: u32 + - + name: act + type: binary + - + name: police + type: nest + nested-attributes: tc-police-attrs + - + name: ematches + type: binary + - + name: perturb + type: u32 - name: tc-flower-attrs attributes: @@ -953,15 +2535,19 @@ attribute-sets: - name: key-arp-sha type: binary + display-hint: mac - name: key-arp-sha-mask type: binary + display-hint: mac - name: key-arp-tha type: binary + display-hint: mac - name: key-arp-tha-mask type: binary + display-hint: mac - name: key-mpls-ttl type: u8 @@ -1020,10 +2606,12 @@ attribute-sets: type: u8 - name: key-enc-opts - type: binary + type: nest + nested-attributes: tc-flower-key-enc-opts-attrs - name: key-enc-opts-mask - type: binary + type: nest + nested-attributes: tc-flower-key-enc-opts-attrs - name: in-hw-count type: u32 @@ -1056,41 +2644,165 @@ attribute-sets: name: key-ct-zone-mask type: u16 - - name: key-ct-mark - type: u32 + name: key-ct-mark + type: u32 + - + name: key-ct-mark-mask + type: u32 + - + name: key-ct-labels + type: binary + - + name: key-ct-labels-mask + type: binary + - + name: key-mpls-opts + type: nest + nested-attributes: tc-flower-key-mpls-opt-attrs + - + name: key-hash + type: u32 + - + name: key-hash-mask + type: u32 + - + name: key-num-of-vlans + type: u8 + - + name: key-pppoe-sid + type: u16 + byte-order: big-endian + - + name: key-ppp-proto + type: u16 + byte-order: big-endian + - + name: key-l2-tpv3-sid + type: u32 + byte-order: big-endian + - + name: l2-miss + type: u8 + - + name: key-cfm + type: nest + nested-attributes: tc-flower-key-cfm-attrs + - + name: key-spi + type: u32 + byte-order: big-endian + - + name: key-spi-mask + type: u32 + byte-order: big-endian + - + name: tc-flower-key-enc-opts-attrs + attributes: + - + name: geneve + type: nest + nested-attributes: tc-flower-key-enc-opt-geneve-attrs + - + name: vxlan + type: nest + nested-attributes: tc-flower-key-enc-opt-vxlan-attrs + - + name: erspan + type: nest + nested-attributes: tc-flower-key-enc-opt-erspan-attrs + - + name: gtp + type: nest + nested-attributes: tc-flower-key-enc-opt-gtp-attrs + - + name: tc-flower-key-enc-opt-geneve-attrs + attributes: + - + name: class + type: u16 + - + name: type + type: u8 + - + name: data + type: binary + - + name: tc-flower-key-enc-opt-vxlan-attrs + attributes: + - + name: gbp + type: u32 + - + name: tc-flower-key-enc-opt-erspan-attrs + attributes: + - + name: ver + type: u8 + - + name: index + type: u32 + - + name: dir + type: u8 + - + name: hwid + type: u8 + - + name: tc-flower-key-enc-opt-gtp-attrs + attributes: + - + name: pdu-type + type: u8 + - + name: qfi + type: u8 + - + name: tc-flower-key-mpls-opt-attrs + attributes: - - name: key-ct-mark-mask - type: u32 + name: lse-depth + type: u8 - - name: key-ct-labels - type: binary + name: lse-ttl + type: u8 - - name: key-ct-labels-mask - type: binary + name: lse-bos + type: u8 - - name: key-mpls-opts - type: binary + name: lse-tc + type: u8 - - name: key-hash + name: lse-label type: u32 + - + name: tc-flower-key-cfm-attrs + attributes: - - name: key-hash-mask - type: u32 + name: md-level + type: u8 - - name: key-num-of-vlans + name: opcode type: u8 + - + name: tc-fw-attrs + attributes: - - name: key-pppoe-sid - type: u16 - byte-order: big-endian + name: classid + type: u32 - - name: key-ppp-proto - type: u16 - byte-order: big-endian + name: police + type: nest + nested-attributes: tc-police-attrs - - name: key-l2-tpv3-sid + name: indev + type: string + - + name: act + type: array-nest + nested-attributes: tc-act-attrs + - + name: mask type: u32 - byte-order: big-endian - name: tc-gred-attrs attributes: @@ -1135,7 +2847,7 @@ attribute-sets: type: u32 - name: stat-bytes - type: u32 + type: u64 - name: stat-packets type: u32 @@ -1232,40 +2944,25 @@ attribute-sets: name: offload type: flag - - name: tc-act-attrs + name: tc-matchall-attrs attributes: - - name: kind - type: string + name: classid + type: u32 - - name: options - type: sub-message - sub-message: tc-act-options-msg - selector: kind + name: act + type: array-nest + nested-attributes: tc-act-attrs - - name: index + name: flags type: u32 - - name: stats + name: pcnt type: binary + struct: tc-matchall-pcnt - name: pad type: pad - - - name: cookie - type: binary - - - name: flags - type: bitfield32 - - - name: hw-stats - type: bitfield32 - - - name: used-hw-stats - type: bitfield32 - - - name: in-hw-count - type: u32 - name: tc-etf-attrs attributes: @@ -1304,48 +3001,71 @@ attribute-sets: - name: plimit type: u32 + doc: Limit of total number of packets in queue - name: flow-plimit type: u32 + doc: Limit of packets per flow - name: quantum type: u32 + doc: RR quantum - name: initial-quantum type: u32 + doc: RR quantum for new flow - name: rate-enable type: u32 + doc: Enable / disable rate limiting - name: flow-default-rate type: u32 + doc: Obsolete, do not use - name: flow-max-rate type: u32 + doc: Per flow max rate - name: buckets-log type: u32 + doc: log2(number of buckets) - name: flow-refill-delay type: u32 + doc: Flow credit refill delay in usec - name: orphan-mask type: u32 + doc: Mask applied to orphaned skb hashes - name: low-rate-threshold type: u32 + doc: Per packet delay under this rate - name: ce-threshold type: u32 + doc: DCTCP-like CE marking threshold - name: timer-slack type: u32 - name: horizon type: u32 + doc: Time horizon in usec - name: horizon-drop type: u8 + doc: Drop packets beyond horizon, or cap their EDT + - + name: priomap + type: binary + struct: tc-prio-qopt + - + name: weights + type: binary + sub-type: s32 + doc: Weights for each band - name: tc-fq-codel-attrs attributes: @@ -1427,6 +3147,7 @@ attribute-sets: - name: corr type: binary + struct: tc-netem-corr - name: delay-dist type: binary @@ -1434,15 +3155,19 @@ attribute-sets: - name: reorder type: binary + struct: tc-netem-reorder - name: corrupt type: binary + struct: tc-netem-corrupt - name: loss - type: binary + type: nest + nested-attributes: tc-netem-loss-attrs - name: rate type: binary + struct: tc-netem-rate - name: ecn type: u32 @@ -1461,10 +3186,27 @@ attribute-sets: - name: slot type: binary + struct: tc-netem-slot - name: slot-dist type: binary sub-type: s16 + - + name: prng-seed + type: u64 + - + name: tc-netem-loss-attrs + attributes: + - + name: gi + type: binary + doc: General Intuitive - 4 state model + struct: tc-netem-gimodel + - + name: ge + type: binary + doc: Gilbert Elliot models + struct: tc-netem-gemodel - name: tc-pie-attrs attributes: @@ -1492,6 +3234,44 @@ attribute-sets: - name: dq-rate-estimator type: u32 + - + name: tc-police-attrs + attributes: + - + name: tbf + type: binary + struct: tc-police + - + name: rate + type: binary + - + name: peakrate + type: binary + - + name: avrate + type: u32 + - + name: result + type: u32 + - + name: tm + type: binary + struct: tcf-t + - + name: pad + type: pad + - + name: rate64 + type: u64 + - + name: peakrate64 + type: u64 + - + name: pktrate64 + type: u64 + - + name: pktburst64 + type: u64 - name: tc-qfq-attrs attributes: @@ -1516,13 +3296,36 @@ attribute-sets: type: u32 - name: flags - type: binary + type: bitfield32 - name: early-drop-block type: u32 - name: mark-block type: u32 + - + name: tc-route-attrs + attributes: + - + name: classid + type: u32 + - + name: to + type: u32 + - + name: from + type: u32 + - + name: iif + type: u32 + - + name: police + type: nest + nested-attributes: tc-police-attrs + - + name: act + type: array-nest + nested-attributes: tc-act-attrs - name: tc-taprio-attrs attributes: @@ -1573,6 +3376,7 @@ attribute-sets: name: entry type: nest nested-attributes: tc-taprio-sched-entry + multi-attr: true - name: tc-taprio-sched-entry attributes: @@ -1629,17 +3433,43 @@ attribute-sets: name: pad type: pad - - name: tca-gact-attrs + name: tc-act-sample-attrs + attributes: + - + name: tm + type: binary + struct: tcf-t + - + name: parms + type: binary + struct: tc-gen + - + name: rate + type: u32 + - + name: trunc-size + type: u32 + - + name: psample-group + type: u32 + - + name: pad + type: pad + - + name: tc-act-gact-attrs attributes: - name: tm type: binary + struct: tcf-t - name: parms type: binary + struct: tc-gen - name: prob type: binary + struct: tc-gact-p - name: pad type: pad @@ -1659,34 +3489,89 @@ attribute-sets: - name: basic type: binary + struct: gnet-stats-basic - name: rate-est type: binary + struct: gnet-stats-rate-est - name: queue type: binary + struct: gnet-stats-queue - name: app - type: binary # TODO sub-message needs 2+ level deep lookup + type: sub-message sub-message: tca-stats-app-msg selector: kind - name: rate-est64 type: binary + struct: gnet-stats-rate-est64 - name: pad type: pad - name: basic-hw type: binary + struct: gnet-stats-basic - name: pkt64 + type: u64 + - + name: tc-u32-attrs + attributes: + - + name: classid + type: u32 + - + name: hash + type: u32 + - + name: link + type: u32 + - + name: divisor + type: u32 + - + name: sel + type: binary + struct: tc-u32-sel + - + name: police + type: nest + nested-attributes: tc-police-attrs + - + name: act + type: array-nest + nested-attributes: tc-act-attrs + - + name: indev + type: string + - + name: pcnt + type: binary + struct: tc-u32-pcnt + - + name: mark type: binary + struct: tc-u32-mark + - + name: flags + type: u32 + - + name: pad + type: pad sub-messages: - name: tc-options-msg formats: + - + value: basic + attribute-set: tc-basic-attrs + - + value: bpf + attribute-set: tc-bpf-attrs - value: bfifo fixed-header: tc-fifo-qopt @@ -1696,6 +3581,9 @@ sub-messages: - value: cbs attribute-set: tc-cbs-attrs + - + value: cgroup + attribute-set: tc-cgroup-attrs - value: choke attribute-set: tc-choke-attrs @@ -1713,6 +3601,12 @@ sub-messages: - value: ets attribute-set: tc-ets-attrs + - + value: flow + attribute-set: tc-flow-attrs + - + value: flower + attribute-set: tc-flower-attrs - value: fq attribute-set: tc-fq-attrs @@ -1723,8 +3617,8 @@ sub-messages: value: fq_pie attribute-set: tc-fq-pie-attrs - - value: flower - attribute-set: tc-flower-attrs + value: fw + attribute-set: tc-fw-attrs - value: gred attribute-set: tc-gred-attrs @@ -1739,6 +3633,9 @@ sub-messages: attribute-set: tc-htb-attrs - value: ingress # no content + - + value: matchall + attribute-set: tc-matchall-attrs - value: mq # no content - @@ -1775,6 +3672,9 @@ sub-messages: - value: red attribute-set: tc-red-attrs + - + value: route + attribute-set: tc-route-attrs - value: sfb fixed-header: tc-sfb-qopt @@ -1787,88 +3687,105 @@ sub-messages: - value: tbf attribute-set: tc-tbf-attrs - - - name: tc-act-options-msg - formats: - - value: gact - attribute-set: tca-gact-attrs + value: u32 + attribute-set: tc-u32-attrs - - name: tca-stats-app-msg + name: tc-act-options-msg formats: - - value: bfifo - - - value: blackhole + value: bpf + attribute-set: tc-act-bpf-attrs - - value: cake - attribute-set: tc-cake-stats-attrs + value: connmark + attribute-set: tc-act-connmark-attrs - - value: cbs + value: csum + attribute-set: tc-act-csum-attrs - - value: choke + value: ct + attribute-set: tc-act-ct-attrs - - value: clsact + value: ctinfo + attribute-set: tc-act-ctinfo-attrs - - value: codel + value: gact + attribute-set: tc-act-gact-attrs - - value: drr + value: gate + attribute-set: tc-act-gate-attrs - - value: etf + value: ife + attribute-set: tc-act-ife-attrs - - value: ets + value: mirred + attribute-set: tc-act-mirred-attrs - - value: fq + value: mpls + attribute-set: tc-act-mpls-attrs - - value: fq_codel + value: nat + attribute-set: tc-act-nat-attrs - - value: fq_pie + value: pedit + attribute-set: tc-act-pedit-attrs - - value: flower + value: police + attribute-set: tc-act-police-attrs - - value: gred + value: sample + attribute-set: tc-act-sample-attrs - - value: hfsc + value: simple + attribute-set: tc-act-simple-attrs - - value: hhf + value: skbedit + attribute-set: tc-act-skbedit-attrs - - value: htb + value: skbmod + attribute-set: tc-act-skbmod-attrs - - value: ingress + value: tunnel_key + attribute-set: tc-act-tunnel-key-attrs - - value: mq + value: vlan + attribute-set: tc-act-vlan-attrs + - + name: tca-stats-app-msg + formats: - - value: mqprio + value: cake + attribute-set: tc-cake-stats-attrs - - value: multiq + value: choke + fixed-header: tc-choke-xstats - - value: netem + value: codel + fixed-header: tc-codel-xstats - - value: noqueue + value: fq + fixed-header: tc-fq-qd-stats - - value: pfifo + value: fq_codel + fixed-header: tc-fq-codel-xstats - - value: pfifo_fast + value: fq_pie + fixed-header: tc-fq-pie-xstats - - value: pfifo_head_drop + value: hhf + fixed-header: tc-hhf-xstats - value: pie - - - value: plug - - - value: prio - - - value: qfq + fixed-header: tc-pie-xstats - value: red + fixed-header: tc-red-xstats - value: sfb + fixed-header: tc-sfb-xstats - value: sfq - - - value: taprio - - - value: tbf + fixed-header: tc-sfq-xstats operations: enum-model: directional diff --git a/Documentation/networking/af_xdp.rst b/Documentation/networking/af_xdp.rst index dceeb0d763aa23..72da7057e4cf96 100644 --- a/Documentation/networking/af_xdp.rst +++ b/Documentation/networking/af_xdp.rst @@ -329,23 +329,24 @@ XDP_SHARED_UMEM option and provide the initial socket's fd in the sxdp_shared_umem_fd field as you registered the UMEM on that socket. These two sockets will now share one and the same UMEM. -There is no need to supply an XDP program like the one in the previous -case where sockets were bound to the same queue id and -device. Instead, use the NIC's packet steering capabilities to steer -the packets to the right queue. In the previous example, there is only -one queue shared among sockets, so the NIC cannot do this steering. It -can only steer between queues. - -In libbpf, you need to use the xsk_socket__create_shared() API as it -takes a reference to a FILL ring and a COMPLETION ring that will be -created for you and bound to the shared UMEM. You can use this -function for all the sockets you create, or you can use it for the -second and following ones and use xsk_socket__create() for the first -one. Both methods yield the same result. +In this case, it is possible to use the NIC's packet steering +capabilities to steer the packets to the right queue. This is not +possible in the previous example as there is only one queue shared +among sockets, so the NIC cannot do this steering as it can only steer +between queues. + +In libxdp (or libbpf prior to version 1.0), you need to use the +xsk_socket__create_shared() API as it takes a reference to a FILL ring +and a COMPLETION ring that will be created for you and bound to the +shared UMEM. You can use this function for all the sockets you create, +or you can use it for the second and following ones and use +xsk_socket__create() for the first one. Both methods yield the same +result. Note that a UMEM can be shared between sockets on the same queue id and device, as well as between queues on the same device and between -devices at the same time. +devices at the same time. It is also possible to redirect to any +socket as long as it is bound to the same umem with XDP_SHARED_UMEM. XDP_USE_NEED_WAKEUP bind flag ----------------------------- @@ -822,6 +823,10 @@ A: The short answer is no, that is not supported at the moment. The switch, or other distribution mechanism, in your NIC to direct traffic to the correct queue id and socket. + Note that if you are using the XDP_SHARED_UMEM option, it is + possible to switch traffic between any socket bound to the same + umem. + Q: My packets are sometimes corrupted. What is wrong? A: Care has to be taken not to feed the same buffer in the UMEM into diff --git a/Documentation/networking/bonding.rst b/Documentation/networking/bonding.rst index f7a73421eb76a1..e774b48de9f511 100644 --- a/Documentation/networking/bonding.rst +++ b/Documentation/networking/bonding.rst @@ -444,6 +444,18 @@ arp_missed_max The default value is 2, and the allowable range is 1 - 255. +coupled_control + + Specifies whether the LACP state machine's MUX in the 802.3ad mode + should have separate Collecting and Distributing states. + + This is by implementing the independent control state machine per + IEEE 802.1AX-2008 5.4.15 in addition to the existing coupled control + state machine. + + The default value is 1. This setting does not separate the Collecting + and Distributing states, maintaining the bond in coupled control. + downdelay Specifies the time, in milliseconds, to wait before disabling diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst index ba14e7b07869c9..ef8b73e157b268 100644 --- a/Documentation/networking/bridge.rst +++ b/Documentation/networking/bridge.rst @@ -324,7 +324,7 @@ Contact Info The code is currently maintained by Roopa Prabhu and Nikolay Aleksandrov . Bridge bugs and enhancements are discussed on the linux-netdev mailing list netdev@vger.kernel.org and -bridge@lists.linux-foundation.org. +bridge@lists.linux.dev. The list is open to anyone interested: http://vger.kernel.org/vger-lists.html#netdev diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst index d7e1ada905b2d3..62519d38c58bad 100644 --- a/Documentation/networking/can.rst +++ b/Documentation/networking/can.rst @@ -444,6 +444,24 @@ definitions are specified for CAN specific MTUs in include/linux/can.h: #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame +Returned Message Flags +---------------------- + +When using the system call recvmsg(2) on a RAW or a BCM socket, the +msg->msg_flags field may contain the following flags: + +MSG_DONTROUTE: + set when the received frame was created on the local host. + +MSG_CONFIRM: + set when the frame was sent via the socket it is received on. + This flag can be interpreted as a 'transmission confirmation' when the + CAN driver supports the echo of frames on driver level, see + :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`. + (Note: In order to receive such messages on a RAW socket, + CAN_RAW_RECV_OWN_MSGS must be set.) + + .. _socketcan-raw-sockets: RAW Protocol Sockets with can_filters (SOCK_RAW) @@ -693,22 +711,6 @@ where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or CAN ID ranges from the incoming traffic. -RAW Socket Returned Message Flags -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When using recvmsg() call, the msg->msg_flags may contain following flags: - -MSG_DONTROUTE: - set when the received frame was created on the local host. - -MSG_CONFIRM: - set when the frame was sent via the socket it is received on. - This flag can be interpreted as a 'transmission confirmation' when the - CAN driver supports the echo of frames on driver level, see - :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`. - In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set. - - Broadcast Manager Protocol Sockets (SOCK_DGRAM) ----------------------------------------------- diff --git a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst index b842bcb14255b5..a4c7d0c65fd7e5 100644 --- a/Documentation/networking/device_drivers/ethernet/amazon/ena.rst +++ b/Documentation/networking/device_drivers/ethernet/amazon/ena.rst @@ -211,10 +211,16 @@ Documentation/networking/net_dim.rst RX copybreak ============ + The rx_copybreak is initialized by default to ENA_DEFAULT_RX_COPYBREAK and can be configured by the ETHTOOL_STUNABLE command of the SIOCETHTOOL ioctl. +This option controls the maximum packet length for which the RX +descriptor it was received on would be recycled. When a packet smaller +than RX copybreak bytes is received, it is copied into a new memory +buffer and the RX descriptor is returned to HW. + Statistics ========== diff --git a/Documentation/networking/device_drivers/ethernet/index.rst b/Documentation/networking/device_drivers/ethernet/index.rst index 43de285b8a923a..6932d8c043c2c1 100644 --- a/Documentation/networking/device_drivers/ethernet/index.rst +++ b/Documentation/networking/device_drivers/ethernet/index.rst @@ -42,6 +42,7 @@ Contents: intel/ice marvell/octeontx2 marvell/octeon_ep + marvell/octeon_ep_vf mellanox/mlx5/index microsoft/netvsc neterion/s2io diff --git a/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep_vf.rst b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep_vf.rst new file mode 100644 index 00000000000000..603133d0b92f88 --- /dev/null +++ b/Documentation/networking/device_drivers/ethernet/marvell/octeon_ep_vf.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======================================================================= +Linux kernel networking driver for Marvell's Octeon PCI Endpoint NIC VF +======================================================================= + +Network driver for Marvell's Octeon PCI EndPoint NIC VF. +Copyright (c) 2020 Marvell International Ltd. + +Overview +======== +This driver implements networking functionality of Marvell's Octeon PCI +EndPoint NIC VF. + +Supported Devices +================= +Currently, this driver support following devices: + * Network controller: Cavium, Inc. Device b203 + * Network controller: Cavium, Inc. Device b403 + * Network controller: Cavium, Inc. Device b103 + * Network controller: Cavium, Inc. Device b903 + * Network controller: Cavium, Inc. Device ba03 + * Network controller: Cavium, Inc. Device bc03 + * Network controller: Cavium, Inc. Device bd03 diff --git a/Documentation/networking/device_drivers/wwan/t7xx.rst b/Documentation/networking/device_drivers/wwan/t7xx.rst index dd5b731957ca40..f346f5f85f154e 100644 --- a/Documentation/networking/device_drivers/wwan/t7xx.rst +++ b/Documentation/networking/device_drivers/wwan/t7xx.rst @@ -39,6 +39,34 @@ command and receive response: - open the AT control channel using a UART tool or a special user tool +Sysfs +===== +The driver provides sysfs interfaces to userspace. + +t7xx_mode +--------- +The sysfs interface provides userspace with access to the device mode, this interface +supports read and write operations. + +Device mode: + +- ``unknown`` represents that device in unknown status +- ``ready`` represents that device in ready status +- ``reset`` represents that device in reset status +- ``fastboot_switching`` represents that device in fastboot switching status +- ``fastboot_download`` represents that device in fastboot download status +- ``fastboot_dump`` represents that device in fastboot dump status + +Read from userspace to get the current device mode. + +:: + $ cat /sys/bus/pci/devices/${bdf}/t7xx_mode + +Write from userspace to set the device mode. + +:: + $ echo fastboot_switching > /sys/bus/pci/devices/${bdf}/t7xx_mode + Management application development ================================== The driver and userspace interfaces are described below. The MBIM protocol is @@ -97,6 +125,20 @@ The driver exposes an AT port by implementing AT WWAN Port. The userspace end of the control port is a /dev/wwan0at0 character device. Application shall use this interface to issue AT commands. +fastboot port userspace ABI +--------------------------- + +/dev/wwan0fastboot0 character device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The driver exposes a fastboot protocol interface by implementing +fastboot WWAN Port. The userspace end of the fastboot channel pipe is a +/dev/wwan0fastboot0 character device. Application shall use this interface for +fastboot protocol communication. + +Please note that driver needs to be reloaded to export /dev/wwan0fastboot0 +port, because device needs a cold reset after enter ``fastboot_switching`` +mode. + The MediaTek's T700 modem supports the 3GPP TS 27.007 [4] specification. References @@ -118,3 +160,7 @@ speak the Mobile Interface Broadband Model (MBIM) protocol"* [4] *Specification # 27.007 - 3GPP* - https://www.3gpp.org/DynaReport/27007.htm + +[5] *fastboot "a mechanism for communicating with bootloaders"* + +- https://android.googlesource.com/platform/system/core/+/refs/heads/main/fastboot/README.md diff --git a/Documentation/networking/devlink/devlink-port.rst b/Documentation/networking/devlink/devlink-port.rst index e33ad2401ad70c..562f46b4127449 100644 --- a/Documentation/networking/devlink/devlink-port.rst +++ b/Documentation/networking/devlink/devlink-port.rst @@ -126,7 +126,7 @@ Users may also set the RoCE capability of the function using `devlink port function set roce` command. Users may also set the function as migratable using -'devlink port function set migratable' command. +`devlink port function set migratable` command. Users may also set the IPsec crypto capability of the function using `devlink port function set ipsec_crypto` command. diff --git a/Documentation/networking/devlink/mlx5.rst b/Documentation/networking/devlink/mlx5.rst index 702f204a3dbd35..456985407475f1 100644 --- a/Documentation/networking/devlink/mlx5.rst +++ b/Documentation/networking/devlink/mlx5.rst @@ -97,6 +97,10 @@ parameters. When metadata is disabled, the above use cases will fail to initialize if users try to enable them. + + Note: Setting this parameter does not take effect immediately. Setting + must happen in legacy mode and eswitch port metadata takes effect after + enabling switchdev mode. * - ``hairpin_num_queues`` - u32 - driverinit @@ -246,7 +250,7 @@ them in realtime. Description of the vnic counters: -- total_q_under_processor_handle +- total_error_queues number of queues in an error state due to an async error or errored command. - send_queue_priority_update_flow @@ -255,7 +259,8 @@ Description of the vnic counters: number of times CQ entered an error state due to an overflow. - async_eq_overrun number of times an EQ mapped to async events was overrun. - comp_eq_overrun number of times an EQ mapped to completion events was +- comp_eq_overrun + number of times an EQ mapped to completion events was overrun. - quota_exceeded_command number of commands issued and failed due to quota exceeded. diff --git a/Documentation/networking/ip-sysctl.rst b/Documentation/networking/ip-sysctl.rst index 7afff42612e949..bd50df6a5a42e6 100644 --- a/Documentation/networking/ip-sysctl.rst +++ b/Documentation/networking/ip-sysctl.rst @@ -2503,7 +2503,7 @@ use_tempaddr - INTEGER temp_valid_lft - INTEGER valid lifetime (in seconds) for temporary addresses. If less than the - minimum required lifetime (typically 5 seconds), temporary addresses + minimum required lifetime (typically 5-7 seconds), temporary addresses will not be created. Default: 172800 (2 days) @@ -2511,7 +2511,7 @@ temp_valid_lft - INTEGER temp_prefered_lft - INTEGER Preferred lifetime (in seconds) for temporary addresses. If temp_prefered_lft is less than the minimum required lifetime (typically - 5 seconds), temporary addresses will not be created. If + 5-7 seconds), the preferred lifetime is the minimum required. If temp_prefered_lft is greater than temp_valid_lft, the preferred lifetime is temp_valid_lft. @@ -2535,6 +2535,16 @@ max_desync_factor - INTEGER Default: 600 +regen_min_advance - INTEGER + How far in advance (in seconds), at minimum, to create a new temporary + address before the current one is deprecated. This value is added to + the amount of time that may be required for duplicate address detection + to determine when to create a new address. Linux permits setting this + value to less than the default of 2 seconds, but a value less than 2 + does not conform to RFC 8981. + + Default: 2 + regen_max_retry - INTEGER Number of attempts before give up attempting to generate valid temporary addresses. diff --git a/Documentation/networking/net_cachelines/net_device.rst b/Documentation/networking/net_cachelines/net_device.rst index e75a53593bb960..dceb49d56a9115 100644 --- a/Documentation/networking/net_cachelines/net_device.rst +++ b/Documentation/networking/net_cachelines/net_device.rst @@ -136,8 +136,8 @@ struct_netpoll_info* npinfo - possible_net_t nd_net - read_mostly (dev_net)napi_busy_loop,tcp_v(4/6)_rcv,ip(v6)_rcv,ip(6)_input,ip(6)_input_finish void* ml_priv enum_netdev_ml_priv_type ml_priv_type -struct_pcpu_lstats__percpu* lstats -struct_pcpu_sw_netstats__percpu* tstats +struct_pcpu_lstats__percpu* lstats read_mostly dev_lstats_add() +struct_pcpu_sw_netstats__percpu* tstats read_mostly dev_sw_netstats_tx_add() struct_pcpu_dstats__percpu* dstats struct_garp_port* garp_port struct_mrp_port* mrp_port diff --git a/Documentation/networking/net_cachelines/tcp_sock.rst b/Documentation/networking/net_cachelines/tcp_sock.rst index 97d7a5c8e01c02..1c154cbd18487e 100644 --- a/Documentation/networking/net_cachelines/tcp_sock.rst +++ b/Documentation/networking/net_cachelines/tcp_sock.rst @@ -38,13 +38,13 @@ u32 max_window read_mostly - u32 mss_cache read_mostly read_mostly tcp_rate_check_app_limited,tcp_current_mss,tcp_sync_mss,tcp_sndbuf_expand,tcp_tso_should_defer(tx);tcp_update_pacing_rate,tcp_clean_rtx_queue(rx) u32 window_clamp read_mostly read_write tcp_rcv_space_adjust,__tcp_select_window u32 rcv_ssthresh read_mostly - __tcp_select_window -u82 scaling_ratio +u8 scaling_ratio read_mostly read_mostly tcp_win_from_space struct tcp_rack u16 advmss - read_mostly tcp_rcv_space_adjust u8 compressed_ack u8:2 dup_ack_counter u8:1 tlp_retrans -u8:1 tcp_usec_ts +u8:1 tcp_usec_ts read_mostly read_mostly u32 chrono_start read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) u32[3] chrono_stat read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) u8:2 chrono_type read_write - tcp_chrono_start/stop(tcp_write_xmit,tcp_cwnd_validate,tcp_send_syn_data) diff --git a/Documentation/networking/netconsole.rst b/Documentation/networking/netconsole.rst index 390730a74332d7..b28c525e5d1e22 100644 --- a/Documentation/networking/netconsole.rst +++ b/Documentation/networking/netconsole.rst @@ -15,6 +15,8 @@ Extended console support by Tejun Heo , May 1 2015 Release prepend support by Breno Leitao , Jul 7 2023 +Userdata append support by Matthew Wood , Jan 22 2024 + Please send bug reports to Matt Mackall Satyam Sharma , and Cong Wang @@ -171,6 +173,70 @@ You can modify these targets in runtime by creating the following targets:: cat cmdline1/remote_ip 10.0.0.3 +Append User Data +---------------- + +Custom user data can be appended to the end of messages with netconsole +dynamic configuration enabled. User data entries can be modified without +changing the "enabled" attribute of a target. + +Directories (keys) under `userdata` are limited to 54 character length, and +data in `userdata//value` are limited to 200 bytes:: + + cd /sys/kernel/config/netconsole && mkdir cmdline0 + cd cmdline0 + mkdir userdata/foo + echo bar > userdata/foo/value + mkdir userdata/qux + echo baz > userdata/qux/value + +Messages will now include this additional user data:: + + echo "This is a message" > /dev/kmsg + +Sends:: + + 12,607,22085407756,-;This is a message + foo=bar + qux=baz + +Preview the userdata that will be appended with:: + + cd /sys/kernel/config/netconsole/cmdline0/userdata + for f in `ls userdata`; do echo $f=$(cat userdata/$f/value); done + +If a `userdata` entry is created but no data is written to the `value` file, +the entry will be omitted from netconsole messages:: + + cd /sys/kernel/config/netconsole && mkdir cmdline0 + cd cmdline0 + mkdir userdata/foo + echo bar > userdata/foo/value + mkdir userdata/qux + +The `qux` key is omitted since it has no value:: + + echo "This is a message" > /dev/kmsg + 12,607,22085407756,-;This is a message + foo=bar + +Delete `userdata` entries with `rmdir`:: + + rmdir /sys/kernel/config/netconsole/cmdline0/userdata/qux + +.. warning:: + When writing strings to user data values, input is broken up per line in + configfs store calls and this can cause confusing behavior:: + + mkdir userdata/testing + printf "val1\nval2" > userdata/testing/value + # userdata store value is called twice, first with "val1\n" then "val2" + # so "val2" is stored, being the last value stored + cat userdata/testing/value + val2 + + It is recommended to not write user data values with newlines. + Extended console: ================= diff --git a/Documentation/networking/netdevices.rst b/Documentation/networking/netdevices.rst index 9e4cccb90b8700..c2476917a6c37d 100644 --- a/Documentation/networking/netdevices.rst +++ b/Documentation/networking/netdevices.rst @@ -252,8 +252,8 @@ ndo_eth_ioctl: Context: process ndo_get_stats: - Synchronization: rtnl_lock() semaphore, dev_base_lock rwlock, or RCU. - Context: atomic (can't sleep under rwlock or RCU) + Synchronization: rtnl_lock() semaphore, or RCU. + Context: atomic (can't sleep under RCU) ndo_start_xmit: Synchronization: __netif_tx_lock spinlock. diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 535077cbeb07df..bfea9d8579ede0 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -71,9 +71,9 @@ Callbacks to implement bool (*xdo_dev_offload_ok) (struct sk_buff *skb, struct xfrm_state *x); void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); + void (*xdo_dev_state_update_stats) (struct xfrm_state *x); /* Solely packet offload callbacks */ - void (*xdo_dev_state_update_curlft) (struct xfrm_state *x); int (*xdo_dev_policy_add) (struct xfrm_policy *x, struct netlink_ext_ack *extack); void (*xdo_dev_policy_delete) (struct xfrm_policy *x); void (*xdo_dev_policy_free) (struct xfrm_policy *x); @@ -191,6 +191,6 @@ xdo_dev_policy_free() on any remaining offloaded states. Outcome of HW handling packets, the XFRM core can't count hard, soft limits. The HW/driver are responsible to perform it and provide accurate data when -xdo_dev_state_update_curlft() is called. In case of one of these limits +xdo_dev_state_update_stats() is called. In case of one of these limits occuried, the driver needs to call to xfrm_state_check_expire() to make sure that XFRM performs rekeying sequence. diff --git a/Documentation/power/energy-model.rst b/Documentation/power/energy-model.rst index 13225965c9a4c0..ada4938c37e56e 100644 --- a/Documentation/power/energy-model.rst +++ b/Documentation/power/energy-model.rst @@ -71,6 +71,31 @@ whose performance is scaled together. Performance domains generally have a required to have the same micro-architecture. CPUs in different performance domains can have different micro-architectures. +To better reflect power variation due to static power (leakage) the EM +supports runtime modifications of the power values. The mechanism relies on +RCU to free the modifiable EM perf_state table memory. Its user, the task +scheduler, also uses RCU to access this memory. The EM framework provides +API for allocating/freeing the new memory for the modifiable EM table. +The old memory is freed automatically using RCU callback mechanism when there +are no owners anymore for the given EM runtime table instance. This is tracked +using kref mechanism. The device driver which provided the new EM at runtime, +should call EM API to free it safely when it's no longer needed. The EM +framework will handle the clean-up when it's possible. + +The kernel code which want to modify the EM values is protected from concurrent +access using a mutex. Therefore, the device driver code must run in sleeping +context when it tries to modify the EM. + +With the runtime modifiable EM we switch from a 'single and during the entire +runtime static EM' (system property) design to a 'single EM which can be +changed during runtime according e.g. to the workload' (system and workload +property) design. + +It is possible also to modify the CPU performance values for each EM's +performance state. Thus, the full power and performance profile (which +is an exponential curve) can be changed according e.g. to the workload +or system property. + 2. Core APIs ------------ @@ -175,10 +200,82 @@ CPUfreq governor is in use in case of CPU device. Currently this calculation is not provided for other type of devices. More details about the above APIs can be found in ```` -or in Section 2.4 +or in Section 2.5 + + +2.4 Runtime modifications +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Drivers willing to update the EM at runtime should use the following dedicated +function to allocate a new instance of the modified EM. The API is listed +below:: + + struct em_perf_table __rcu *em_table_alloc(struct em_perf_domain *pd); + +This allows to allocate a structure which contains the new EM table with +also RCU and kref needed by the EM framework. The 'struct em_perf_table' +contains array 'struct em_perf_state state[]' which is a list of performance +states in ascending order. That list must be populated by the device driver +which wants to update the EM. The list of frequencies can be taken from +existing EM (created during boot). The content in the 'struct em_perf_state' +must be populated by the driver as well. + +This is the API which does the EM update, using RCU pointers swap:: + + int em_dev_update_perf_domain(struct device *dev, + struct em_perf_table __rcu *new_table); + +Drivers must provide a pointer to the allocated and initialized new EM +'struct em_perf_table'. That new EM will be safely used inside the EM framework +and will be visible to other sub-systems in the kernel (thermal, powercap). +The main design goal for this API is to be fast and avoid extra calculations +or memory allocations at runtime. When pre-computed EMs are available in the +device driver, than it should be possible to simply re-use them with low +performance overhead. + +In order to free the EM, provided earlier by the driver (e.g. when the module +is unloaded), there is a need to call the API:: + + void em_table_free(struct em_perf_table __rcu *table); + +It will allow the EM framework to safely remove the memory, when there is +no other sub-system using it, e.g. EAS. + +To use the power values in other sub-systems (like thermal, powercap) there is +a need to call API which protects the reader and provide consistency of the EM +table data:: + + struct em_perf_state *em_perf_state_from_pd(struct em_perf_domain *pd); + +It returns the 'struct em_perf_state' pointer which is an array of performance +states in ascending order. +This function must be called in the RCU read lock section (after the +rcu_read_lock()). When the EM table is not needed anymore there is a need to +call rcu_real_unlock(). In this way the EM safely uses the RCU read section +and protects the users. It also allows the EM framework to manage the memory +and free it. More details how to use it can be found in Section 3.2 in the +example driver. + +There is dedicated API for device drivers to calculate em_perf_state::cost +values:: + + int em_dev_compute_costs(struct device *dev, struct em_perf_state *table, + int nr_states); + +These 'cost' values from EM are used in EAS. The new EM table should be passed +together with the number of entries and device pointer. When the computation +of the cost values is done properly the return value from the function is 0. +The function takes care for right setting of inefficiency for each performance +state as well. It updates em_perf_state::flags accordingly. +Then such prepared new EM can be passed to the em_dev_update_perf_domain() +function, which will allow to use it. + +More details about the above APIs can be found in ```` +or in Section 3.2 with an example code showing simple implementation of the +updating mechanism in a device driver. -2.4 Description details of this API +2.5 Description details of this API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. kernel-doc:: include/linux/energy_model.h :internal: @@ -187,8 +284,11 @@ or in Section 2.4 :export: -3. Example driver ------------------ +3. Examples +----------- + +3.1 Example driver with EM registration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The CPUFreq framework supports dedicated callback for registering the EM for a given CPU(s) 'policy' object: cpufreq_driver::register_em(). @@ -242,3 +342,78 @@ EM framework:: 39 static struct cpufreq_driver foo_cpufreq_driver = { 40 .register_em = foo_cpufreq_register_em, 41 }; + + +3.2 Example driver with EM modification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This section provides a simple example of a thermal driver modifying the EM. +The driver implements a foo_thermal_em_update() function. The driver is woken +up periodically to check the temperature and modify the EM data:: + + -> drivers/soc/example/example_em_mod.c + + 01 static void foo_get_new_em(struct foo_context *ctx) + 02 { + 03 struct em_perf_table __rcu *em_table; + 04 struct em_perf_state *table, *new_table; + 05 struct device *dev = ctx->dev; + 06 struct em_perf_domain *pd; + 07 unsigned long freq; + 08 int i, ret; + 09 + 10 pd = em_pd_get(dev); + 11 if (!pd) + 12 return; + 13 + 14 em_table = em_table_alloc(pd); + 15 if (!em_table) + 16 return; + 17 + 18 new_table = em_table->state; + 19 + 20 rcu_read_lock(); + 21 table = em_perf_state_from_pd(pd); + 22 for (i = 0; i < pd->nr_perf_states; i++) { + 23 freq = table[i].frequency; + 24 foo_get_power_perf_values(dev, freq, &new_table[i]); + 25 } + 26 rcu_read_unlock(); + 27 + 28 /* Calculate 'cost' values for EAS */ + 29 ret = em_dev_compute_costs(dev, table, pd->nr_perf_states); + 30 if (ret) { + 31 dev_warn(dev, "EM: compute costs failed %d\n", ret); + 32 em_free_table(em_table); + 33 return; + 34 } + 35 + 36 ret = em_dev_update_perf_domain(dev, em_table); + 37 if (ret) { + 38 dev_warn(dev, "EM: update failed %d\n", ret); + 39 em_free_table(em_table); + 40 return; + 41 } + 42 + 43 /* + 44 * Since it's one-time-update drop the usage counter. + 45 * The EM framework will later free the table when needed. + 46 */ + 47 em_table_free(em_table); + 48 } + 49 + 50 /* + 51 * Function called periodically to check the temperature and + 52 * update the EM if needed + 53 */ + 54 static void foo_thermal_em_update(struct foo_context *ctx) + 55 { + 56 struct device *dev = ctx->dev; + 57 int cpu; + 58 + 59 ctx->temperature = foo_get_temp(dev, ctx); + 60 if (ctx->temperature < FOO_EM_UPDATE_TEMP_THRESHOLD) + 61 return; + 62 + 63 foo_get_new_em(ctx); + 64 } diff --git a/Documentation/power/opp.rst b/Documentation/power/opp.rst index a7c03c47098071..1b7f1d854f14a6 100644 --- a/Documentation/power/opp.rst +++ b/Documentation/power/opp.rst @@ -305,7 +305,7 @@ dev_pm_opp_get_opp_count { /* Do things */ num_available = dev_pm_opp_get_opp_count(dev); - speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); + speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL); /* populate the table in increasing order */ freq = 0; while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { diff --git a/Documentation/power/pci.rst b/Documentation/power/pci.rst index a125544b4cb68d..12070320307e5c 100644 --- a/Documentation/power/pci.rst +++ b/Documentation/power/pci.rst @@ -625,7 +625,7 @@ The PCI subsystem-level callbacks they correspond to:: pci_pm_poweroff() pci_pm_poweroff_noirq() -work in analogy with pci_pm_suspend() and pci_pm_poweroff_noirq(), respectively, +work in analogy with pci_pm_suspend() and pci_pm_suspend_noirq(), respectively, although they don't attempt to save the device's standard configuration registers. diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst index 65b86e487afe00..6fa50e4f87ceac 100644 --- a/Documentation/power/runtime_pm.rst +++ b/Documentation/power/runtime_pm.rst @@ -154,7 +154,7 @@ suspending the device are satisfied) and to queue up a suspend request for the device in that case. If there is no idle callback, or if the callback returns 0, then the PM core will attempt to carry out a runtime suspend of the device, also respecting devices configured for autosuspend. In essence this means a -call to pm_runtime_autosuspend() (do note that drivers needs to update the +call to __pm_runtime_autosuspend() (do note that drivers needs to update the device last busy mark, pm_runtime_mark_last_busy(), to control the delay under this circumstance). To prevent this (for example, if the callback routine has started a delayed suspend), the routine must return a non-zero value. Negative @@ -396,10 +396,9 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: nonzero, increment the counter and return 1; otherwise return 0 without changing the counter - `int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);` + `int pm_runtime_get_if_active(struct device *dev);` - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the - runtime PM status is RPM_ACTIVE, and either ign_usage_count is true - or the device's usage_count is non-zero, increment the counter and + runtime PM status is RPM_ACTIVE, increment the counter and return 1; otherwise return 0 without changing the counter `void pm_runtime_put_noidle(struct device *dev);` @@ -410,6 +409,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: pm_request_idle(dev) and return its result `int pm_runtime_put_autosuspend(struct device *dev);` + - does the same as __pm_runtime_put_autosuspend() for now, but in the + future, will also call pm_runtime_mark_last_busy() as well, DO NOT USE! + + `int __pm_runtime_put_autosuspend(struct device *dev);` - decrement the device's usage counter; if the result is 0 then run pm_request_autosuspend(dev) and return its result @@ -540,6 +543,7 @@ It is safe to execute the following helper functions from interrupt context: - pm_runtime_put_noidle() - pm_runtime_put() - pm_runtime_put_autosuspend() +- __pm_runtime_put_autosuspend() - pm_runtime_enable() - pm_suspend_ignore_children() - pm_runtime_set_active() @@ -865,9 +869,9 @@ automatically be delayed until the desired period of inactivity has elapsed. Inactivity is determined based on the power.last_busy field. Drivers should call pm_runtime_mark_last_busy() to update this field after carrying out I/O, -typically just before calling pm_runtime_put_autosuspend(). The desired length -of the inactivity period is a matter of policy. Subsystems can set this length -initially by calling pm_runtime_set_autosuspend_delay(), but after device +typically just before calling __pm_runtime_put_autosuspend(). The desired +length of the inactivity period is a matter of policy. Subsystems can set this +length initially by calling pm_runtime_set_autosuspend_delay(), but after device registration the length should be controlled by user space, using the /sys/devices/.../power/autosuspend_delay_ms attribute. @@ -878,7 +882,7 @@ instead of the non-autosuspend counterparts:: Instead of: pm_runtime_suspend use: pm_runtime_autosuspend; Instead of: pm_schedule_suspend use: pm_request_autosuspend; - Instead of: pm_runtime_put use: pm_runtime_put_autosuspend; + Instead of: pm_runtime_put use: __pm_runtime_put_autosuspend; Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend. Drivers may also continue to use the non-autosuspend helper functions; they @@ -917,7 +921,7 @@ Here is a schematic pseudo-code example:: lock(&foo->private_lock); if (--foo->num_pending_requests == 0) { pm_runtime_mark_last_busy(&foo->dev); - pm_runtime_put_autosuspend(&foo->dev); + __pm_runtime_put_autosuspend(&foo->dev); } else { foo_process_next_request(foo); } diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 50b3d1cb11159b..3a3810cd3c339f 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -30,8 +30,8 @@ you probably needn't concern yourself with pcmciautils. Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 5.1 gcc --version -Clang/LLVM (optional) 11.0.0 clang --version -Rust (optional) 1.74.1 rustc --version +Clang/LLVM (optional) 13.0.1 clang --version +Rust (optional) 1.75.0 rustc --version bindgen (optional) 0.65.1 bindgen --version GNU make 3.82 make --version bash 4.2 bash --version @@ -144,8 +144,8 @@ Bison Since Linux 4.16, the build system generates parsers during build. This requires bison 2.0 or later. -pahole: -------- +pahole +------ Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index c48382c6b47746..9c7cf734739437 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -203,7 +203,7 @@ Do not unnecessarily use braces where a single statement will do. and -.. code-block:: none +.. code-block:: c if (condition) do_this(); @@ -586,9 +586,9 @@ fix for this is to split it up into two error labels ``err_free_bar:`` and .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; @@ -660,7 +660,7 @@ make a good program). So, you can either get rid of GNU emacs, or change it to use saner values. To do the latter, you can stick the following in your .emacs file: -.. code-block:: none +.. code-block:: elisp (defun c-lineup-arglist-tabs-only (ignored) "Line up argument lists by tabs, not spaces" @@ -679,7 +679,7 @@ values. To do the latter, you can stick the following in your .emacs file: (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) @@ -899,7 +899,8 @@ which you should use to make sure messages are matched to the right device and driver, and are tagged with the right level: dev_err(), dev_warn(), dev_info(), and so forth. For messages that aren't associated with a particular device, defines pr_notice(), pr_info(), -pr_warn(), pr_err(), etc. +pr_warn(), pr_err(), etc. When drivers are working properly they are quiet, +so prefer to use dev_dbg/pr_debug unless something is wrong. Coming up with good debugging messages can be quite a challenge; and once you have them, they can be a huge help for remote troubleshooting. However diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst new file mode 100644 index 00000000000000..5e2753eff7294c --- /dev/null +++ b/Documentation/process/cve.rst @@ -0,0 +1,121 @@ +==== +CVEs +==== + +Common Vulnerabilities and Exposure (CVE®) numbers were developed as an +unambiguous way to identify, define, and catalog publicly disclosed +security vulnerabilities. Over time, their usefulness has declined with +regards to the kernel project, and CVE numbers were very often assigned +in inappropriate ways and for inappropriate reasons. Because of this, +the kernel development community has tended to avoid them. However, the +combination of continuing pressure to assign CVEs and other forms of +security identifiers, and ongoing abuses by individuals and companies +outside of the kernel community has made it clear that the kernel +community should have control over those assignments. + +The Linux kernel developer team does have the ability to assign CVEs for +potential Linux kernel security issues. This assignment is independent +of the :doc:`normal Linux kernel security bug reporting +process<../process/security-bugs>`. + +A list of all assigned CVEs for the Linux kernel can be found in the +archives of the linux-cve mailing list, as seen on +https://lore.kernel.org/linux-cve-announce/. To get notice of the +assigned CVEs, please `subscribe +`_ to that mailing list. + +Process +======= + +As part of the normal stable release process, kernel changes that are +potentially security issues are identified by the developers responsible +for CVE number assignments and have CVE numbers automatically assigned +to them. These assignments are published on the linux-cve-announce +mailing list as announcements on a frequent basis. + +Note, due to the layer at which the Linux kernel is in a system, almost +any bug might be exploitable to compromise the security of the kernel, +but the possibility of exploitation is often not evident when the bug is +fixed. Because of this, the CVE assignment team is overly cautious and +assign CVE numbers to any bugfix that they identify. This +explains the seemingly large number of CVEs that are issued by the Linux +kernel team. + +If the CVE assignment team misses a specific fix that any user feels +should have a CVE assigned to it, please email them at +and the team there will work with you on it. Note that no potential +security issues should be sent to this alias, it is ONLY for assignment +of CVEs for fixes that are already in released kernel trees. If you +feel you have found an unfixed security issue, please follow the +:doc:`normal Linux kernel security bug reporting +process<../process/security-bugs>`. + +No CVEs will be automatically assigned for unfixed security issues in +the Linux kernel; assignment will only automatically happen after a fix +is available and applied to a stable kernel tree, and it will be tracked +that way by the git commit id of the original fix. If anyone wishes to +have a CVE assigned before an issue is resolved with a commit, please +contact the kernel CVE assignment team at to get an +identifier assigned from their batch of reserved identifiers. + +No CVEs will be assigned for any issue found in a version of the kernel +that is not currently being actively supported by the Stable/LTS kernel +team. A list of the currently supported kernel branches can be found at +https://kernel.org/releases.html + +Disputes of assigned CVEs +========================= + +The authority to dispute or modify an assigned CVE for a specific kernel +change lies solely with the maintainers of the relevant subsystem +affected. This principle ensures a high degree of accuracy and +accountability in vulnerability reporting. Only those individuals with +deep expertise and intimate knowledge of the subsystem can effectively +assess the validity and scope of a reported vulnerability and determine +its appropriate CVE designation. Any attempt to modify or dispute a CVE +outside of this designated authority could lead to confusion, inaccurate +reporting, and ultimately, compromised systems. + +Invalid CVEs +============ + +If a security issue is found in a Linux kernel that is only supported by +a Linux distribution due to the changes that have been made by that +distribution, or due to the distribution supporting a kernel version +that is no longer one of the kernel.org supported releases, then a CVE +can not be assigned by the Linux kernel CVE team, and must be asked for +from that Linux distribution itself. + +Any CVE that is assigned against the Linux kernel for an actively +supported kernel version, by any group other than the kernel assignment +CVE team should not be treated as a valid CVE. Please notify the +kernel CVE assignment team at so that they can work to +invalidate such entries through the CNA remediation process. + +Applicability of specific CVEs +============================== + +As the Linux kernel can be used in many different ways, with many +different ways of accessing it by external users, or no access at all, +the applicability of any specific CVE is up to the user of Linux to +determine, it is not up to the CVE assignment team. Please do not +contact us to attempt to determine the applicability of any specific +CVE. + +Also, as the source tree is so large, and any one system only uses a +small subset of the source tree, any users of Linux should be aware that +large numbers of assigned CVEs are not relevant for their systems. + +In short, we do not know your use case, and we do not know what portions +of the kernel that you use, so there is no way for us to determine if a +specific CVE is relevant for your system. + +As always, it is best to take all released kernel changes, as they are +tested together in a unified whole by many community members, and not as +individual cherry-picked changes. Also note that for many bugs, the +solution to the overall problem is not found in a single change, but by +the sum of many fixes on top of each other. Ideally CVEs will be +assigned to all fixes for all issues, but sometimes we will fail to +notice fixes, therefore assume that some changes without a CVE assigned +might be relevant to take. + diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index 31000f07570730..bb2100228cc7b6 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -255,7 +255,7 @@ an involved disclosed party. The current ambassadors list: IBM Power Anton Blanchard IBM Z Christian Borntraeger Intel Tony Luck - Qualcomm Trilok Soni + Qualcomm Trilok Soni RISC-V Palmer Dabbelt Samsung Javier González diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6c73889c98fc3d..eebda4910a8887 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -351,8 +351,8 @@ Managing bug reports -------------------- One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, but you'll also learn to fix real world problems and you will +bugs reported by other people. Not only will you help to make the kernel +more stable, but you'll also learn to fix real-world problems and you will improve your skills, and other developers will be aware of your presence. Fixing bugs is one of the best ways to get merits among other developers, because not many people like wasting time fixing other people's bugs. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 6cb732dfcc7224..de9cbb7bd7eb2b 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -81,6 +81,7 @@ of special classes of bugs: regressions and security problems. handling-regressions security-bugs + cve embargoed-hardware-issues Maintainer information diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index 84ee60fceef24c..fd96e4a3cef9c0 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -431,7 +431,7 @@ patchwork checks Checks in patchwork are mostly simple wrappers around existing kernel scripts, the sources are available at: -https://github.com/kuba-moo/nipa/tree/master/tests +https://github.com/linux-netdev/nipa/tree/master/tests **Do not** post your patches just to run them through the checks. You must ensure that your patches are ready by testing them locally diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst index 08dd0f804410b6..497bb39727c8b0 100644 --- a/Documentation/process/maintainer-tip.rst +++ b/Documentation/process/maintainer-tip.rst @@ -304,13 +304,15 @@ following tag ordering scheme: - Reported-by: ``Reporter `` + - Closes: ``URL or Message-ID of the bug report this is fixing`` + - Originally-by: ``Original author `` - Suggested-by: ``Suggester `` - Co-developed-by: ``Co-author `` - Signed-off: ``Co-author `` + Signed-off-by: ``Co-author `` Note, that Co-developed-by and Signed-off-by of the co-author(s) must come in pairs. @@ -478,7 +480,7 @@ Multi-line comments:: * Larger multi-line comments should be split into paragraphs. */ -No tail comments: +No tail comments (see below): Please refrain from using tail comments. Tail comments disturb the reading flow in almost all contexts, but especially in code:: @@ -499,6 +501,34 @@ No tail comments: /* This magic initialization needs a comment. Maybe not? */ seed = MAGIC_CONSTANT; + Use C++ style, tail comments when documenting structs in headers to + achieve a more compact layout and better readability:: + + // eax + u32 x2apic_shift : 5, // Number of bits to shift APIC ID right + // for the topology ID at the next level + : 27; // Reserved + // ebx + u32 num_processors : 16, // Number of processors at current level + : 16; // Reserved + + versus:: + + /* eax */ + /* + * Number of bits to shift APIC ID right for the topology ID + * at the next level + */ + u32 x2apic_shift : 5, + /* Reserved */ + : 27; + + /* ebx */ + /* Number of processors at current level */ + u32 num_processors : 16, + /* Reserved */ + : 16; + Comment the important things: Comments should be added where the operation is not obvious. Documenting diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst index d159cd4f5e5b3b..beb484c5965dcf 100644 --- a/Documentation/process/researcher-guidelines.rst +++ b/Documentation/process/researcher-guidelines.rst @@ -167,4 +167,4 @@ If no one can be found to internally review patches and you need help finding such a person, or if you have any other questions related to this document and the developer community's expectations, please reach out to the private Technical Advisory Board mailing list: -. +. diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst index 692a3ba56cca83..56c560a00b37a6 100644 --- a/Documentation/process/security-bugs.rst +++ b/Documentation/process/security-bugs.rst @@ -99,9 +99,8 @@ CVE assignment The security team does not assign CVEs, nor do we require them for reports or fixes, as this can needlessly complicate the process and may delay the bug handling. If a reporter wishes to have a CVE identifier -assigned, they should find one by themselves, for example by contacting -MITRE directly. However under no circumstances will a patch inclusion -be delayed to wait for a CVE identifier to arrive. +assigned for a confirmed issue, they can contact the :doc:`kernel CVE +assignment team<../process/cve>` to obtain one. Non-disclosure agreements ------------------------- diff --git a/Documentation/rust/arch-support.rst b/Documentation/rust/arch-support.rst index 73203ba1e9011e..5c4fa9f5d1cdb7 100644 --- a/Documentation/rust/arch-support.rst +++ b/Documentation/rust/arch-support.rst @@ -15,6 +15,7 @@ support corresponds to ``S`` values in the ``MAINTAINERS`` file. ============= ================ ============================================== Architecture Level of support Constraints ============= ================ ============================================== +``arm64`` Maintained Little Endian only. ``loongarch`` Maintained - ``um`` Maintained ``x86_64`` only. ``x86`` Maintained ``x86_64`` only. diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst index 236c6dd3c647f8..081397827a7eab 100644 --- a/Documentation/rust/general-information.rst +++ b/Documentation/rust/general-information.rst @@ -77,27 +77,3 @@ configuration: #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`) #[cfg(CONFIG_X="m")] // Enabled as a module (`m`) #[cfg(not(CONFIG_X))] // Disabled - - -Testing -------- - -There are the tests that come from the examples in the Rust documentation -and get transformed into KUnit tests. These can be run via KUnit. For example -via ``kunit_tool`` (``kunit.py``) on the command line:: - - ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y - -Alternatively, KUnit can run them as kernel built-in at boot. Refer to -Documentation/dev-tools/kunit/index.rst for the general KUnit documentation -and Documentation/dev-tools/kunit/architecture.rst for the details of kernel -built-in vs. command line testing. - -Additionally, there are the ``#[test]`` tests. These can be run using -the ``rusttest`` Make target:: - - make LLVM=1 rusttest - -This requires the kernel ``.config`` and downloads external repositories. -It runs the ``#[test]`` tests on the host (currently) and thus is fairly -limited in what these tests can test. diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst index 965f2db529e0ff..46d35bd395cf5c 100644 --- a/Documentation/rust/index.rst +++ b/Documentation/rust/index.rst @@ -40,6 +40,7 @@ configurations. general-information coding-guidelines arch-support + testing .. only:: subproject and html diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst new file mode 100644 index 00000000000000..6658998d1b6c4b --- /dev/null +++ b/Documentation/rust/testing.rst @@ -0,0 +1,135 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Testing +======= + +This document contains useful information how to test the Rust code in the +kernel. + +There are two sorts of tests: + +- The KUnit tests. +- The ``#[test]`` tests. + +The KUnit tests +--------------- + +These are the tests that come from the examples in the Rust documentation. They +get transformed into KUnit tests. + +Usage +***** + +These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``) +on the command line:: + + ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y + +Alternatively, KUnit can run them as kernel built-in at boot. Refer to +Documentation/dev-tools/kunit/index.rst for the general KUnit documentation +and Documentation/dev-tools/kunit/architecture.rst for the details of kernel +built-in vs. command line testing. + +To use these KUnit doctests, the following must be enabled:: + + CONFIG_KUNIT + Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests + CONFIG_RUST_KERNEL_DOCTESTS + Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate + +in the kernel config system. + +KUnit tests are documentation tests +*********************************** + +These documentation tests are typically examples of usage of any item (e.g. +function, struct, module...). + +They are very convenient because they are just written alongside the +documentation. For instance: + +.. code-block:: rust + + /// Sums two numbers. + /// + /// ``` + /// assert_eq!(mymod::f(10, 20), 30); + /// ``` + pub fn f(a: i32, b: i32) -> i32 { + a + b + } + +In userspace, the tests are collected and run via ``rustdoc``. Using the tool +as-is would be useful already, since it allows verifying that examples compile +(thus enforcing they are kept in sync with the code they document) and as well +as running those that do not depend on in-kernel APIs. + +For the kernel, however, these tests get transformed into KUnit test suites. +This means that doctests get compiled as Rust kernel objects, allowing them to +run against a built kernel. + +A benefit of this KUnit integration is that Rust doctests get to reuse existing +testing facilities. For instance, the kernel log would look like:: + + KTAP version 1 + 1..1 + KTAP version 1 + # Subtest: rust_doctests_kernel + 1..59 + # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13 + ok 1 rust_doctest_kernel_build_assert_rs_0 + # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56 + ok 2 rust_doctest_kernel_build_assert_rs_1 + # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122 + ok 3 rust_doctest_kernel_init_rs_0 + ... + # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 + ok 59 rust_doctest_kernel_types_rs_2 + # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59 + # Totals: pass:59 fail:0 skip:0 total:59 + ok 1 rust_doctests_kernel + +Tests using the `? `_ +operator are also supported as usual, e.g.: + +.. code-block:: rust + + /// ``` + /// # use kernel::{spawn_work_item, workqueue}; + /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?; + /// # Ok::<(), Error>(()) + /// ``` + +The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal +code, thus also benefitting from extra linting. + +In order for developers to easily see which line of doctest code caused a +failure, a KTAP diagnostic line is printed to the log. This contains the +location (file and line) of the original test (i.e. instead of the location in +the generated Rust file):: + + # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 + +Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!`` +macros from the Rust standard library (``core``). We provide a custom version +that forwards the call to KUnit instead. Importantly, these macros do not +require passing context, unlike those for KUnit testing (i.e. +``struct kunit *``). This makes them easier to use, and readers of the +documentation do not need to care about which testing framework is used. In +addition, it may allow us to test third-party code more easily in the future. + +A current limitation is that KUnit does not support assertions in other tasks. +Thus, we presently simply print an error to the kernel log if an assertion +actually failed. Additionally, doctests are not run for nonpublic functions. + +The ``#[test]`` tests +--------------------- + +Additionally, there are the ``#[test]`` tests. These can be run using the +``rusttest`` Make target:: + + make LLVM=1 rusttest + +This requires the kernel ``.config`` and downloads external repositories. It +runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in +what these tests can test. diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst index cd421856409e65..2d2998faff62b9 100644 --- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -3864,14 +3864,16 @@ corresponding destructor. And next, set suspend/resume callbacks to the pci_driver:: - static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume); + static DEFINE_SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume); static struct pci_driver driver = { .name = KBUILD_MODNAME, .id_table = snd_my_ids, .probe = snd_my_probe, .remove = snd_my_remove, - .driver.pm = &snd_my_pm_ops, + .driver = { + .pm = &snd_my_pm_ops, + }, }; Module Parameters diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py index b9df61eb450138..03ace5f01b5c02 100644 --- a/Documentation/sphinx/kernel_feat.py +++ b/Documentation/sphinx/kernel_feat.py @@ -109,7 +109,7 @@ def run(self): else: out_lines += line + "\n" - nodeList = self.nestedParse(out_lines, fname) + nodeList = self.nestedParse(out_lines, self.arguments[0]) return nodeList def nestedParse(self, lines, fname): diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 7acf09963daa52..ec1ddfff1863f8 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -61,9 +61,9 @@ def run(self): env = self.state.document.settings.env cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] - # Pass the version string to kernel-doc, as it needs to use a different - # dialect, depending what the C domain supports for each specific - # Sphinx versions + # Pass the version string to kernel-doc, as it needs to use a different + # dialect, depending what the C domain supports for each specific + # Sphinx versions cmd += ['-sphinx-version', sphinx.__version__] filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] diff --git a/Documentation/sphinx/templates/kernel-toc.html b/Documentation/sphinx/templates/kernel-toc.html index b58efa99df527d..41f1efbe64bb28 100644 --- a/Documentation/sphinx/templates/kernel-toc.html +++ b/Documentation/sphinx/templates/kernel-toc.html @@ -12,5 +12,7 @@

Contents

diff --git a/Documentation/sphinx/translations.py b/Documentation/sphinx/translations.py index 47161e6eba9976..32c2b32b2b5ee9 100644 --- a/Documentation/sphinx/translations.py +++ b/Documentation/sphinx/translations.py @@ -29,10 +29,7 @@ } class LanguagesNode(nodes.Element): - def __init__(self, current_language, *args, **kwargs): - super().__init__(*args, **kwargs) - - self.current_language = current_language + pass class TranslationsTransform(Transform): default_priority = 900 @@ -49,7 +46,8 @@ def apply(self): # normalize docname to be the untranslated one docname = os.path.join(*components[2:]) - new_nodes = LanguagesNode(all_languages[this_lang_code]) + new_nodes = LanguagesNode() + new_nodes['current_language'] = all_languages[this_lang_code] for lang_code, lang_name in all_languages.items(): if lang_code == this_lang_code: @@ -84,7 +82,7 @@ def process_languages(app, doctree, docname): html_content = app.builder.templates.render('translations.html', context={ - 'current_language': node.current_language, + 'current_language': node['current_language'], 'languages': languages, }) diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst index 33f05901ccf37b..546de37d6caf10 100644 --- a/Documentation/spi/spi-summary.rst +++ b/Documentation/spi/spi-summary.rst @@ -9,7 +9,7 @@ What is SPI? The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial link used to connect microcontrollers to sensors, memory, and peripherals. It's a simple "de facto" standard, not complicated enough to acquire a -standardization body. SPI uses a master/slave configuration. +standardization body. SPI uses a host/target configuration. The three signal wires hold a clock (SCK, often on the order of 10 MHz), and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, @@ -19,14 +19,14 @@ commonly used. Each clock cycle shifts data out and data in; the clock doesn't cycle except when there is a data bit to shift. Not all data bits are used though; not every protocol uses those full duplex capabilities. -SPI masters use a fourth "chip select" line to activate a given SPI slave +SPI hosts use a fourth "chip select" line to activate a given SPI target device, so those three signal wires may be connected to several chips -in parallel. All SPI slaves support chipselects; they are usually active -low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have -other signals, often including an interrupt to the master. +in parallel. All SPI targets support chipselects; they are usually active +low signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have +other signals, often including an interrupt to the host. Unlike serial busses like USB or SMBus, even low level protocols for -SPI slave functions are usually not interoperable between vendors +SPI target functions are usually not interoperable between vendors (except for commodities like SPI memory chips). - SPI may be used for request/response style device protocols, as with @@ -43,10 +43,10 @@ SPI slave functions are usually not interoperable between vendors - Sometimes SPI is used to daisy-chain devices, like shift registers. -In the same way, SPI slaves will only rarely support any kind of automatic -discovery/enumeration protocol. The tree of slave devices accessible from -a given SPI master will normally be set up manually, with configuration -tables. +In the same way, SPI targets will only rarely support any kind of automatic +discovery/enumeration protocol. The tree of target devices accessible from +a given SPI host controller will normally be set up manually, with +configuration tables. SPI is only one of the names used by such four-wire protocols, and most controllers have no problem handling "MicroWire" (think of it as @@ -62,8 +62,8 @@ course they won't handle full duplex transfers. You may find such chips described as using "three wire" signaling: SCK, data, nCSx. (That data line is sometimes called MOMI or SISO.) -Microcontrollers often support both master and slave sides of the SPI -protocol. This document (and Linux) supports both the master and slave +Microcontrollers often support both host and target sides of the SPI +protocol. This document (and Linux) supports both the host and target sides of SPI interactions. @@ -75,7 +75,7 @@ protocol supported by every MMC or SD memory card. (The older "DataFlash" cards, predating MMC cards but using the same connectors and card shape, support only SPI.) Some PC hardware uses SPI flash for BIOS code. -SPI slave chips range from digital/analog converters used for analog +SPI target chips range from digital/analog converters used for analog sensors and codecs, to memory, to peripherals like USB controllers or Ethernet adapters; and more. @@ -118,8 +118,8 @@ starting low (CPOL=0) and data stabilized for sampling during the trailing clock edge (CPHA=1), that's SPI mode 1. Note that the clock mode is relevant as soon as the chipselect goes -active. So the master must set the clock to inactive before selecting -a slave, and the slave can tell the chosen polarity by sampling the +active. So the host must set the clock to inactive before selecting +a target, and the target can tell the chosen polarity by sampling the clock level when its select line goes active. That's why many devices support for example both modes 0 and 3: they don't care about polarity, and always clock data in/out on rising clock edges. @@ -142,13 +142,13 @@ There are two types of SPI driver, here called: Controller drivers ... controllers may be built into System-On-Chip - processors, and often support both Master and Slave roles. + processors, and often support both Controller and target roles. These drivers touch hardware registers and may use DMA. Or they can be PIO bitbangers, needing just GPIO pins. Protocol drivers ... these pass messages through the controller - driver to communicate with a Slave or Master device on the + driver to communicate with a target or Controller device on the other side of an SPI link. So for example one protocol driver might talk to the MTD layer to export @@ -179,22 +179,22 @@ shows up in sysfs in several locations:: /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices /sys/class/spi_master/spiB ... symlink to a logical node which could hold - class related state for the SPI master controller managing bus "B". + class related state for the SPI host controller managing bus "B". All spiB.* devices share one physical SPI bus segment, with SCLK, MOSI, and MISO. /sys/devices/.../CTLR/slave ... virtual file for (un)registering the - slave device for an SPI slave controller. - Writing the driver name of an SPI slave handler to this file - registers the slave device; writing "(null)" unregisters the slave + target device for an SPI target controller. + Writing the driver name of an SPI target handler to this file + registers the target device; writing "(null)" unregisters the target device. - Reading from this file shows the name of the slave device ("(null)" + Reading from this file shows the name of the target device ("(null)" if not registered). /sys/class/spi_slave/spiB ... symlink to a logical node which could hold - class related state for the SPI slave controller on bus "B". When + class related state for the SPI target controller on bus "B". When registered, a single spiB.* device is present here, possible sharing - the physical SPI bus segment with other SPI slave devices. + the physical SPI bus segment with other SPI target devices. At this time, the only class-specific state is the bus number ("B" in "spiB"), so those /sys/class entries are only useful to quickly identify busses. @@ -270,10 +270,10 @@ same SOC controller is used. For example, on one board SPI might use an external clock, where another derives the SPI clock from current settings of some master clock. -Declare Slave Devices -^^^^^^^^^^^^^^^^^^^^^ +Declare target Devices +^^^^^^^^^^^^^^^^^^^^^^ -The second kind of information is a list of what SPI slave devices exist +The second kind of information is a list of what SPI target devices exist on the target board, often with some board-specific data needed for the driver to work correctly. @@ -316,7 +316,7 @@ sharing a bus with a device that interprets chipselect "backwards" is not possible until the infrastructure knows how to deselect it. Then your board initialization code would register that table with the SPI -infrastructure, so that it's available later when the SPI master controller +infrastructure, so that it's available later when the SPI host controller driver is registered:: spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); @@ -469,39 +469,39 @@ routines are available to allocate and zero-initialize an spi_message with several transfers. -How do I write an "SPI Master Controller Driver"? +How do I write an "SPI Controller Driver"? ------------------------------------------------- An SPI controller will probably be registered on the platform_bus; write a driver to bind to the device, whichever bus is involved. -The main task of this type of driver is to provide an "spi_master". -Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() -to get the driver-private data allocated for that device. +The main task of this type of driver is to provide an "spi_controller". +Use spi_alloc_host() to allocate the host controller, and +spi_controller_get_devdata() to get the driver-private data allocated for that +device. :: - struct spi_master *master; + struct spi_controller *ctlr; struct CONTROLLER *c; - master = spi_alloc_master(dev, sizeof *c); - if (!master) + ctlr = spi_alloc_host(dev, sizeof *c); + if (!ctlr) return -ENODEV; - c = spi_master_get_devdata(master); + c = spi_controller_get_devdata(ctlr); -The driver will initialize the fields of that spi_master, including the -bus number (maybe the same as the platform device ID) and three methods -used to interact with the SPI core and SPI protocol drivers. It will -also initialize its own internal state. (See below about bus numbering -and those methods.) +The driver will initialize the fields of that spi_controller, including the bus +number (maybe the same as the platform device ID) and three methods used to +interact with the SPI core and SPI protocol drivers. It will also initialize +its own internal state. (See below about bus numbering and those methods.) -After you initialize the spi_master, then use spi_register_master() to +After you initialize the spi_controller, then use spi_register_controller() to publish it to the rest of the system. At that time, device nodes for the controller and any predeclared spi devices will be made available, and the driver model core will take care of binding them to drivers. -If you need to remove your SPI controller driver, spi_unregister_master() -will reverse the effect of spi_register_master(). +If you need to remove your SPI controller driver, spi_unregister_controller() +will reverse the effect of spi_register_controller(). Bus Numbering @@ -519,49 +519,49 @@ then be replaced by a dynamically assigned number. You'd then need to treat this as a non-static configuration (see above). -SPI Master Methods -^^^^^^^^^^^^^^^^^^ +SPI Host Controller Methods +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``master->setup(struct spi_device *spi)`` +``ctlr->setup(struct spi_device *spi)`` This sets up the device clock rate, SPI mode, and word sizes. Drivers may change the defaults provided by board_info, and then call spi_setup(spi) to invoke this routine. It may sleep. - Unless each SPI slave has its own configuration registers, don't + Unless each SPI target has its own configuration registers, don't change them right away ... otherwise drivers could corrupt I/O that's in progress for other SPI devices. .. note:: BUG ALERT: for some reason the first version of - many spi_master drivers seems to get this wrong. + many spi_controller drivers seems to get this wrong. When you code setup(), ASSUME that the controller is actively processing transfers for another device. -``master->cleanup(struct spi_device *spi)`` +``ctlr->cleanup(struct spi_device *spi)`` Your controller driver may use spi_device.controller_state to hold state it dynamically associates with that device. If you do that, be sure to provide the cleanup() method to free that state. -``master->prepare_transfer_hardware(struct spi_master *master)`` +``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)`` This will be called by the queue mechanism to signal to the driver that a message is coming in soon, so the subsystem requests the driver to prepare the transfer hardware by issuing this call. This may sleep. -``master->unprepare_transfer_hardware(struct spi_master *master)`` +``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)`` This will be called by the queue mechanism to signal to the driver that there are no more messages pending in the queue and it may relax the hardware (e.g. by power management calls). This may sleep. -``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)`` +``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)`` The subsystem calls the driver to transfer a single message while queuing transfers that arrive in the meantime. When the driver is finished with this message, it must call spi_finalize_current_message() so the subsystem can issue the next message. This may sleep. -``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)`` +``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)`` The subsystem calls the driver to transfer a single transfer while queuing transfers that arrive in the meantime. When the driver is finished with this transfer, it must call @@ -576,15 +576,15 @@ SPI Master Methods * 0: transfer is finished * 1: transfer is still in progress -``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` - This method allows SPI client drivers to request SPI master controller +``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` + This method allows SPI client drivers to request SPI host controller for configuring device specific CS setup, hold and inactive timing requirements. Deprecated Methods ^^^^^^^^^^^^^^^^^^ -``master->transfer(struct spi_device *spi, struct spi_message *message)`` +``ctrl->transfer(struct spi_device *spi, struct spi_message *message)`` This must not sleep. Its responsibility is to arrange that the transfer happens and its complete() callback is issued. The two will normally happen later, after other transfers complete, and diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst index dba3e5f6561295..3713adaa1608f6 100644 --- a/Documentation/staging/rpmsg.rst +++ b/Documentation/staging/rpmsg.rst @@ -157,7 +157,7 @@ Returns 0 on success and an appropriate error value on failure. int rpmsg_trysendto(struct rpmsg_endpoint *ept, void *data, int len, u32 dst) -sends a message across to the remote processor from a given endoint, +sends a message across to the remote processor from a given endpoint, to a destination address provided by the user. The user should specify the channel, the data it wants to send, diff --git a/Documentation/subsystem-apis.rst b/Documentation/subsystem-apis.rst index 2d353fb8ea26a4..74af50d2ef7ff3 100644 --- a/Documentation/subsystem-apis.rst +++ b/Documentation/subsystem-apis.rst @@ -61,6 +61,8 @@ Storage interfaces scsi/index target/index +Other subsystems +---------------- **Fixme**: much more organizational work is needed here. .. toctree:: diff --git a/Documentation/translations/it_IT/RCU/index.rst b/Documentation/translations/it_IT/RCU/index.rst new file mode 100644 index 00000000000000..22adf1d5875243 --- /dev/null +++ b/Documentation/translations/it_IT/RCU/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _it_rcu_concepts: + +=============== +Concetti su RCU +=============== + +.. toctree:: + :maxdepth: 3 + + torture + +.. only:: subproject and html + + Indici + ====== + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/RCU/torture.rst b/Documentation/translations/it_IT/RCU/torture.rst new file mode 100644 index 00000000000000..189f7c6caebc8e --- /dev/null +++ b/Documentation/translations/it_IT/RCU/torture.rst @@ -0,0 +1,369 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +============================================= +Le operazioni RCU per le verifiche *torture* +============================================= + +CONFIG_RCU_TORTURE_TEST +======================= + +L'opzione CONFIG_RCU_TORTURE_TEST è disponibile per tutte le implementazione di +RCU. L'opzione creerà un modulo rcutorture che potrete caricare per avviare le +verifiche. La verifica userà printk() per riportare lo stato, dunque potrete +visualizzarlo con dmesg (magari usate grep per filtrare "torture"). Le verifiche +inizieranno al caricamento, e si fermeranno alla sua rimozione. + +I parametri di modulo hanno tutti il prefisso "rcutortute.", vedere +Documentation/admin-guide/kernel-parameters.txt. + +Rapporto +======== + +Il rapporto sulle verifiche si presenta nel seguente modo:: + + rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4 + rcu-torture: rtc: (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767 + rcu-torture: Reader Pipe: 727860534 34213 0 0 0 0 0 0 0 0 0 + rcu-torture: Reader Batch: 727877838 17003 0 0 0 0 0 0 0 0 0 + rcu-torture: Free-Block Circulation: 155440 155440 155440 155440 155440 155440 155440 155440 155440 155440 0 + rcu-torture:--- End of test: SUCCESS: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4 + +Sulla maggior parte dei sistemi questo rapporto si produce col comando "dmesg | +grep torture:". Su configurazioni più esoteriche potrebbe essere necessario +usare altri comandi per visualizzare i messaggi di printk(). La funzione +printk() usa KERN_ALERT, dunque i messaggi dovrebbero essere ben visibili. ;-) + +La prima e l'ultima riga mostrano i parametri di module di rcutorture, e solo +sull'ultima riga abbiamo il risultato finale delle verifiche effettuate che può +essere "SUCCESS" (successo) or "FAILURE" (insuccesso). + +Le voci sono le seguenti: + +* "rtc": L'indirizzo in esadecimale della struttura attualmente visibile dai + lettori. + +* "ver": Il numero di volte dall'avvio che il processo scrittore di RCU ha + cambiato la struttura visible ai lettori. + +* "tfle": se non è zero, indica la lista di strutture "torture freelist" da + mettere in "rtc" è vuota. Questa condizione è importante perché potrebbe + illuderti che RCU stia funzionando mentre invece non è il caso. :-/ + +* "rta": numero di strutture allocate dalla lista "torture freelist". + +* "rtaf": il numero di allocazioni fallite dalla lista "torture freelist" a + causa del fatto che fosse vuota. Non è inusuale che sia diverso da zero, ma è + un brutto segno se questo numero rappresenta una frazione troppo alta di + "rta". + +* "rtf": il numero di rilasci nella lista "torture freelist" + +* "rtmbe": Un valore diverso da zero indica che rcutorture crede che + rcu_assign_pointer() e rcu_dereference() non funzionino correttamente. Il + valore dovrebbe essere zero. + +* "rtbe": un valore diverso da zero indica che le funzioni della famiglia + rcu_barrier() non funzionano correttamente. + +* "rtbke": rcutorture è stato capace di creare dei kthread real-time per forzare + l'inversione di priorità di RCU. Il valore dovrebbe essere zero. + +* "rtbre": sebbene rcutorture sia riuscito a creare dei kthread capaci di + forzare l'inversione di priorità, non è riuscito però ad impostarne la + priorità real-time al livello 1. Il valore dovrebbe essere zero. + +* "rtbf": Il numero di volte che è fallita la promozione della priorità per + risolvere un'inversione. + +* "rtb": Il numero di volte che rcutorture ha provato a forzare l'inversione di + priorità. Il valore dovrebbe essere diverso da zero Se state verificando la + promozione della priorità col parametro "test_bootst". + +* "nt": il numero di volte che rcutorture ha eseguito codice lato lettura + all'interno di un gestore di *timer*. Questo valore dovrebbe essere diverso da + zero se avete specificato il parametro "irqreader". + +* "Reader Pipe": un istogramma dell'età delle strutture viste dai lettori. RCU + non funziona correttamente se una qualunque voce, dalla terza in poi, ha un + valore diverso da zero. Se dovesse succedere, rcutorture stampa la stringa + "!!!" per renderlo ben visibile. L'età di una struttura appena creata è zero, + diventerà uno quando sparisce dalla visibilità di un lettore, e incrementata + successivamente per ogni periodo di grazia; infine rilasciata dopo essere + passata per (RCU_TORTURE_PIPE_LEN-2) periodi di grazia. + + L'istantanea qui sopra è stata presa da una corretta implementazione di RCU. + Se volete vedere come appare quando non funziona, sbizzarritevi nel romperla. + ;-) + +* "Reader Batch": un istogramma di età di strutture viste dai lettori, ma + conteggiata in termini di lotti piuttosto che periodi. Anche qui dalla terza + voce in poi devono essere zero. La ragione d'esistere di questo rapporto è che + a volte è più facile scatenare un terzo valore diverso da zero qui piuttosto + che nella lista "Reader Pipe". + +* "Free-Block Circulation": il numero di strutture *torture* che hanno raggiunto + un certo punto nella catena. Il primo numero dovrebbe corrispondere + strettamente al numero di strutture allocate; il secondo conta quelle rimosse + dalla vista dei lettori. Ad eccezione dell'ultimo valore, gli altri + corrispondono al numero di passaggi attraverso il periodo di grazia. L'ultimo + valore dovrebbe essere zero, perché viene incrementato solo se il contatore + della struttura torture viene in un qualche modo incrementato oltre il + normale. + +Una diversa implementazione di RCU potrebbe fornire informazioni aggiuntive. Per +esempio, *Tree SRCU* fornisce anche la seguente riga:: + + srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6) + +Questa riga mostra lo stato dei contatori per processore, in questo caso per +*Tree SRCU*, usando un'allocazione dinamica di srcu_struct (dunque "srcud-" +piuttosto che "srcu-"). I numeri fra parentesi sono i valori del "vecchio" +contatore e di quello "corrente" per ogni processore. Il valore "idx" mappa +questi due valori nell'array, ed è utile per il *debug*. La "T" finale contiene +il valore totale dei contatori. + +Uso su specifici kernel +======================= + +A volte può essere utile eseguire RCU torture su un kernel già compilato, ad +esempio quando lo si sta per mettere in proeduzione. In questo caso, il kernel +dev'essere compilato con CONFIG_RCU_TORTURE_TEST=m, cosicché le verifiche possano +essere avviate usano modprobe e terminate con rmmod. + +Per esempio, potreste usare questo script:: + + #!/bin/sh + + modprobe rcutorture + sleep 3600 + rmmod rcutorture + dmesg | grep torture: + +Potete controllare il rapporto verificando manualmente la presenza del marcatore +di errore "!!!". Ovviamente, siete liberi di scriverne uno più elaborato che +identifichi automaticamente gli errori. Il comando "rmmod" forza la stampa di +"SUCCESS" (successo), "FAILURE" (fallimento), o "RCU_HOTPLUG". I primi due sono +autoesplicativi; invece, l'ultimo indica che non son stati trovati problemi in +RCU, tuttavia ci sono stati problemi con CPU-hotplug. + + +Uso sul kernel di riferimento +============================= + +Quando si usa rcutorture per verificare modifiche ad RCU stesso, spesso è +necessario compilare un certo numero di kernel usando configurazioni diverse e +con parametri d'avvio diversi. In questi casi, usare modprobe ed rmmod potrebbe +richiedere molto tempo ed il processo essere suscettibile ad errori. + +Dunque, viene messo a disposizione il programma +tools/testing/selftests/rcutorture/bin/kvm.sh per le architetture x86, arm64 e +powerpc. Di base, eseguirà la serie di verifiche elencate in +tools/testing/selftests/rcutorture/configs/rcu/CFLIST. Ognuna di queste verrà +eseguita per 30 minuti in una macchina virtuale con uno spazio utente minimale +fornito da un initrd generato automaticamente. Al completamento, gli artefatti +prodotti e i messaggi vengono analizzati alla ricerca di errori, ed i risultati +delle esecuzioni riassunti in un rapporto. + +Su grandi sistemi, le verifiche di rcutorture posso essere velocizzare passano a +kvm.sh l'argomento --cpus. Per esempio, su un sistema a 64 processori, "--cpus +43" userà fino a 43 processori per eseguire contemporaneamente le verifiche. Su +un kernel v5.4 per eseguire tutti gli scenari in due serie, riduce il tempo +d'esecuzione da otto ore a un'ora (senza contare il tempo per compilare sedici +kernel). L'argomento "--dryrun sched" non eseguirà verifiche, piuttosto vi +informerà su come queste verranno organizzate in serie. Questo può essere utile +per capire quanti processori riservare per le verifiche in --cpus. + +Non serve eseguire tutti gli scenari di verifica per ogni modifica. Per esempio, +per una modifica a Tree SRCU potete eseguire gli scenari SRCU-N e SRCU-P. Per +farlo usate l'argomento --configs di kvm.sh in questo modo: "--configs 'SRCU-N +SRCU-P'". Su grandi sistemi si possono eseguire più copie degli stessi scenari, +per esempio, un hardware che permette di eseguire 448 thread, può eseguire 5 +istanze complete contemporaneamente. Per farlo:: + + kvm.sh --cpus 448 --configs '5*CFLIST' + +Oppure, lo stesso sistema, può eseguire contemporaneamente 56 istanze dello +scenario su otto processori:: + + kvm.sh --cpus 448 --configs '56*TREE04' + +O ancora 28 istanze per ogni scenario su otto processori:: + + kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04' + +Ovviamente, ogni esecuzione utilizzerà della memoria. Potete limitarne l'uso con +l'argomento --memory, che di base assume il valore 512M. Per poter usare valori +piccoli dovrete disabilitare le verifiche *callback-flooding* usando il +parametro --bootargs che vedremo in seguito. + +A volte è utile avere informazioni aggiuntive di debug, in questo caso potete +usare il parametro --kconfig, per esempio, ``--kconfig +'CONFIG_RCU_EQS_DEBUG=y'``. In aggiunta, ci sono i parametri --gdb, --kasan, and +kcsan. Da notare che --gdb vi limiterà all'uso di un solo scenario per +esecuzione di kvm.sh e richiede di avere anche un'altra finestra aperta dalla +quale eseguire ``gdb`` come viene spiegato dal programma. + +Potete passare anche i parametri d'avvio del kernel, per esempio, per +controllare i parametri del modulo rcutorture. Per esempio, per verificare +modifiche del codice RCU CPU stall-warning, usate ``bootargs +'rcutorture.stall_cpu=30``. Il programma riporterà un fallimento, ossia il +risultato della verifica. Come visto in precedenza, ridurre la memoria richiede +la disabilitazione delle verifiche *callback-flooding*:: + + kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \ + --bootargs 'rcutorture.fwd_progress=0' + +A volte tutto quello che serve è una serie completa di compilazioni del kernel. +Questo si ottiene col parametro --buildonly. + +Il parametro --duration sovrascrive quello di base di 30 minuti. Per esempio, +con ``--duration 2d`` l'esecuzione sarà di due giorni, ``--duraction 5min`` di +cinque minuti, e ``--duration 45s`` di 45 secondi. L'ultimo può essere utile per +scovare rari errori nella sequenza d'avvio. + +Infine, il parametro --trust-make permette ad ogni nuova compilazione del kernel +di riutilizzare tutto il possibile da quelle precedenti. Da notare che senza il +parametro --trust-make, i vostri file di *tag* potrebbero essere distrutti. + +Ci sono altri parametri più misteriosi che sono documentati nel codice sorgente +dello programma kvm.sh. + +Se un'esecuzione contiene degli errori, il loro numero durante la compilazione e +all'esecuzione verranno elencati alla fine fra i risultati di kvm.sh (che vi +consigliamo caldamente di reindirizzare verso un file). I file prodotti dalla +compilazione ed i risultati stampati vengono salvati, usando un riferimento +temporale, nelle cartella tools/testing/selftests/rcutorture/res. Una cartella +di queste cartelle può essere fornita a kvm-find-errors.sh per estrarne gli +errori. Per esempio:: + + tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \ + tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23 + +Tuttavia, molto spesso è più conveniente aprire i file direttamente. I file +riguardanti tutti gli scenari di un'esecuzione di trovano nella cartella +principale (2020.01.20-15.54.23 nell'esempio precedente), mentre quelli +specifici per scenario si trovano in sotto cartelle che prendono il nome dello +scenario stesso (per esempio, "TREE04"). Se un dato scenario viene eseguito più +di una volta (come abbiamo visto con "--configs '56*TREE04'"), allora dalla +seconda esecuzione in poi le sottocartelle includeranno un numero di +progressione, per esempio "TREE04.2", "TREE04.3", e via dicendo. + +Il file solitamente più usato nella cartella principale è testid.txt. Se la +verifica viene eseguita in un repositorio git, allora questo file conterrà il +*commit* sul quale si basano le verifiche, mentre tutte le modifiche non +registrare verranno mostrate in formato diff. + +I file solitamente più usati nelle cartelle di scenario sono: + +.config + Questo file contiene le opzioni di Kconfig + +Make.out + Questo file contiene il risultato di compilazione per uno specifico scenario + +console.log + Questo file contiene il risultato d'esecuzione per uno specifico scenario. + Questo file può essere esaminato una volta che il kernel è stato avviato, + ma potrebbe non esistere se l'avvia non è fallito. + +vmlinux + Questo file contiene il kernel, e potrebbe essere utile da esaminare con + programmi come pbjdump e gdb + +Ci sono altri file, ma vengono usati meno. Molti sono utili all'analisi di +rcutorture stesso o dei suoi programmi. + +Nel kernel v5.4, su un sistema a 12 processori, un'esecuzione senza errori +usando gli scenari di base produce il seguente risultato:: + + SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ] + SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ] + SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ] + SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ] + TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ] + TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ] + TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ] + TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198 + TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631 + TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ] + TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844 + TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497 + CPU count limited from 16 to 12 + TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961 + TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997 + TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732 + CPU count limited from 16 to 12 + TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011 + +Ripetizioni +=========== + +Immaginate di essere alla caccia di un raro problema che si verifica all'avvio. +Potreste usare kvm.sh, tuttavia questo ricompilerebbe il kernel ad ogni +esecuzione. Se avete bisogno di (diciamo) 1000 esecuzioni per essere sicuri di +aver risolto il problema, allora queste inutili ricompilazioni possono diventare +estremamente fastidiose. + +Per questo motivo esiste kvm-again.sh. + +Immaginate che un'esecuzione precedente di kvm.sh abbia lasciato i suoi +artefatti nella cartella:: + + tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 + +Questa esecuzione può essere rieseguita senza ricompilazioni:: + + kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 + +Alcuni dei parametri originali di kvm.sh possono essere sovrascritti, in +particolare --duration e --bootargs. Per esempio:: + + kvm-again.sh tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28 \ + --duration 45s + +rieseguirebbe il test precedente, ma solo per 45 secondi, e quindi aiutando a +trovare quel raro problema all'avvio sopracitato. + +Esecuzioni distribuite +====================== + +Sebbene kvm.sh sia utile, le sue verifiche sono limitate ad un singolo sistema. +Non è poi così difficile usare un qualsiasi ambiente di sviluppo per eseguire +(diciamo) 5 istanze di kvm.sh su altrettanti sistemi, ma questo avvierebbe +inutili ricompilazioni del kernel. In aggiunta, il processo di distribuzione +degli scenari di verifica per rcutorture sui sistemi disponibili richiede +scrupolo perché soggetto ad errori. + +Per questo esiste kvm-remote.sh. + +Se il seguente comando funziona:: + + ssh system0 date + +e funziona anche per system1, system2, system3, system4, e system5, e tutti +questi sistemi hanno 64 CPU, allora potere eseguire:: + + kvm-remote.sh "system0 system1 system2 system3 system4 system5" \ + --cpus 64 --duration 8h --configs "5*CFLIST" + +Questo compilerà lo scenario di base sul sistema locale, poi lo distribuirà agli +altri cinque sistemi elencati fra i parametri, ed eseguirà ogni scenario per +otto ore. Alla fine delle esecuzioni, i risultati verranno raccolti, registrati, +e stampati. La maggior parte dei parametri di kvm.sh possono essere usati con +kvm-remote.sh, tuttavia la lista dei sistemi deve venire sempre per prima. + +L'argomento di kvm.sh ``--dryrun scenarios`` può essere utile per scoprire +quanti scenari potrebbero essere eseguiti in gruppo di sistemi. + +Potete rieseguire anche una precedente esecuzione remota come abbiamo già fatto +per kvm.sh:: + + kvm-remote.sh "system0 system1 system2 system3 system4 system5" \ + tools/testing/selftests/rcutorture/res/2022.11.03-11.26.28-remote \ + --duration 24h + +In questo caso, la maggior parte dei parametri di kvm-again.sh possono essere +usati dopo il percorso alla cartella contenente gli artefatti dell'esecuzione da +ripetere. diff --git a/Documentation/translations/it_IT/core-api/index.rst b/Documentation/translations/it_IT/core-api/index.rst index cc4c4328ad037d..dad20402d11bce 100644 --- a/Documentation/translations/it_IT/core-api/index.rst +++ b/Documentation/translations/it_IT/core-api/index.rst @@ -10,6 +10,18 @@ Utilità di base symbol-namespaces +Primitive di sincronizzazione +============================= + +Come Linux impedisce che tutto si verifichi contemporaneamente. Consultate +Documentation/translations/it_IT/locking/index.rst per maggiorni informazioni +sul tema. + +.. toctree:: + :maxdepth: 1 + + ../RCU/index + .. only:: subproject and html Indices diff --git a/Documentation/translations/it_IT/i2c/i2c-protocol.rst b/Documentation/translations/it_IT/i2c/i2c-protocol.rst new file mode 100644 index 00000000000000..ba7c8cd8f560a4 --- /dev/null +++ b/Documentation/translations/it_IT/i2c/i2c-protocol.rst @@ -0,0 +1,99 @@ +================= +Il protocollo I2C +================= + +Questo documento è una panoramica delle transazioni di base I2C e delle API +del kernel per eseguirli. + +Spiegazione dei simboli +======================= + +=============== =========================================================== +S Condizione di avvio +P Condizione di stop +Rd/Wr (1 bit) Bit di lettura/scrittura. Rd vale 1, Wr vale 0. +A, NA (1 bit) Bit di riconoscimento (ACK) e di non riconoscimento (NACK). +Addr (7 bit) Indirizzo I2C a 7 bit. Nota che questo può essere espanso + per ottenere un indirizzo I2C a 10 bit. +Dati (8 bit) Un byte di dati. + +[..] Fra parentesi quadre i dati inviati da dispositivi I2C, + anziché dal master. +=============== =========================================================== + + +Transazione semplice di invio +============================= + +Implementato da i2c_master_send():: + + S Addr Wr [A] Dati [A] Dati [A] ... [A] Dati [A] P + + +Transazione semplice di ricezione +================================= + +Implementato da i2c_master_recv():: + + S Addr Rd [A] [Dati] A [Dati] A ... A [Dati] NA P + + +Transazioni combinate +===================== + +Implementato da i2c_transfer(). + +Sono come le transazioni di cui sopra, ma invece di uno condizione di stop P +viene inviata una condizione di inizio S e la transazione continua. +Un esempio di lettura di un byte, seguita da una scrittura di un byte:: + + S Addr Rd [A] [Dati] NA S Addr Wr [A] Dati [A] P + + +Transazioni modificate +====================== + +Le seguenti modifiche al protocollo I2C possono essere generate +impostando questi flag per i messaggi I2C. Ad eccezione di I2C_M_NOSTART, sono +di solito necessari solo per risolvere problemi di un dispositivo: + +I2C_M_IGNORE_NAK: + Normalmente il messaggio viene interrotto immediatamente se il dispositivo + risponde con [NA]. Impostando questo flag, si considera qualsiasi [NA] come + [A] e tutto il messaggio viene inviato. + Questi messaggi potrebbero comunque non riuscire a raggiungere il timeout + SCL basso->alto. + +I2C_M_NO_RD_ACK: + In un messaggio di lettura, il bit A/NA del master viene saltato. + +I2C_M_NOSTART: + In una transazione combinata, potrebbe non essere generato alcun + "S Addr Wr/Rd [A]". + Ad esempio, impostando I2C_M_NOSTART sul secondo messaggio parziale + genera qualcosa del tipo:: + + S Addr Rd [A] [Dati] NA Dati [A] P + + Se si imposta il flag I2C_M_NOSTART per il primo messaggio parziale, + non viene generato Addr, ma si genera la condizione di avvio S. + Questo probabilmente confonderà tutti gli altri dispositivi sul bus, quindi + meglio non usarlo. + + Questo viene spesso utilizzato per raccogliere le trasmissioni da più + buffer di dati presenti nella memoria di sistema in qualcosa che appare + come un singolo trasferimento verso il dispositivo I2C. Inoltre, alcuni + dispositivi particolari lo utilizzano anche tra i cambi di direzione. + +I2C_M_REV_DIR_ADDR: + Questo inverte il flag Rd/Wr. Cioè, se si vuole scrivere, ma si ha bisogno + di emettere una Rd invece di una Wr, o viceversa, si può impostare questo + flag. + Per esempio:: + + S Addr Rd [A] Dati [A] Dati [A] ... [A] Dati [A] P + +I2C_M_STOP: + Forza una condizione di stop (P) dopo il messaggio. Alcuni protocolli + simili a I2C come SCCB lo richiedono. Normalmente, non si vuole essere + interrotti tra i messaggi di un trasferimento. diff --git a/Documentation/translations/it_IT/i2c/index.rst b/Documentation/translations/it_IT/i2c/index.rst new file mode 100644 index 00000000000000..14fbe3d78299cd --- /dev/null +++ b/Documentation/translations/it_IT/i2c/index.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +Il sottosistema I2C/SMBus +========================= + +Introduzione +============ + +.. toctree:: + :maxdepth: 1 + + summary + i2c-protocol + +Scrivere un device driver +========================= + +.. toctree:: + :maxdepth: 1 + +Debugging +========= + +.. toctree:: + :maxdepth: 1 + +Slave I2C +========= + +.. toctree:: + :maxdepth: 1 + + +Argomenti avanzati +================== + +.. toctree:: + :maxdepth: 1 + +.. only:: subproject and html + + Indici + ====== + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/i2c/summary.rst b/Documentation/translations/it_IT/i2c/summary.rst new file mode 100644 index 00000000000000..1535e13a32e28b --- /dev/null +++ b/Documentation/translations/it_IT/i2c/summary.rst @@ -0,0 +1,64 @@ +========================== +Introduzione a I2C e SMBus +========================== + +I²C (letteralmente "I al quadrato C" e scritto I2C nella documentazione del +kernel) è un protocollo sviluppato da Philips. É un protocollo lento a 2 fili +(a velocità variabile, al massimo 400KHz), con un'estensione per le velocità +elevate (3.4 MHz). Questo protocollo offre un bus a basso costo per collegare +dispositivi di vario genere a cui si accede sporadicamente e utilizzando +poca banda. Alcuni sistemi usano varianti che non rispettano i requisiti +originali, per cui non sono indicati come I2C, ma hanno nomi diversi, per +esempio TWI (Interfaccia a due fili), IIC. + +L'ultima specifica ufficiale I2C è la `"Specifica I2C-bus e manuale utente" +(UM10204) `_ +pubblicata da NXP Semiconductors. Tuttavia, è necessario effettuare il login +al sito per accedere al PDF. Una versione precedente della specifica +(revisione 6) è archiviata +`qui `_. + +SMBus (Bus per la gestione del sistema) si basa sul protocollo I2C ed è +principalmente un sottoinsieme di protocolli e segnali I2C. Molti dispositivi +I2C funzioneranno su SMBus, ma alcuni protocolli SMBus aggiungono semantica +oltre quanto richiesto da I2C. Le moderne schede madri dei PC si affidano a +SMBus. I più comuni dispositivi collegati tramite SMBus sono moduli RAM +configurati utilizzando EEPROM I2C, e circuiti integrati di monitoraggio +hardware. + +Poiché SMBus è principalmente un sottoinsieme del bus I2C, +possiamo farne uso su molti sistemi I2C. Ci sono però sistemi che non +soddisfano i vincoli elettrici sia di SMBus che di I2C; e altri che non possono +implementare tutta la semantica o messaggi comuni del protocollo SMBus. + + +Terminologia +============ + +Utilizzando la terminologia della documentazione ufficiale, il bus I2C connette +uno o più circuiti integrati *master* e uno o più circuiti integrati *slave*. + +.. kernel-figure:: ../../../i2c/i2c_bus.svg + :alt: Un semplice bus I2C con un master e 3 slave + + Un semplice Bus I2C + +Un circuito integrato **master** è un nodo che inizia le comunicazioni con gli +slave. Nell'implementazione del kernel Linux è chiamato **adattatore** o bus. I +driver degli adattatori si trovano nella sottocartella ``drivers/i2c/busses/``. + +Un **algoritmo** contiene codice generico che può essere utilizzato per +implementare una intera classe di adattatori I2C. Ciascun driver dell' +adattatore specifico dipende da un driver dell'algoritmo nella sottocartella +``drivers/i2c/algos/`` o include la propria implementazione. + +Un circuito integrato **slave** è un nodo che risponde alle comunicazioni +quando indirizzato dal master. In Linux è chiamato **client** (dispositivo). I +driver dei dispositivi sono contenuti in una cartella specifica per la +funzionalità che forniscono, ad esempio ``drivers/media/gpio/`` per espansori +GPIO e ``drivers/media/i2c/`` per circuiti integrati relativi ai video. + +Per la configurazione di esempio in figura, avrai bisogno di un driver per il +tuo adattatore I2C e driver per i tuoi dispositivi I2C (solitamente un driver +per ciascuno dispositivo). diff --git a/Documentation/translations/it_IT/index.rst b/Documentation/translations/it_IT/index.rst index b95dfa1ded0484..70ccd23b2cdeba 100644 --- a/Documentation/translations/it_IT/index.rst +++ b/Documentation/translations/it_IT/index.rst @@ -91,6 +91,8 @@ interfacciarsi con il resto del kernel. :maxdepth: 1 core-api/index + Sincronizzazione nel kernel + subsystem-apis Strumenti e processi per lo sviluppo ==================================== diff --git a/Documentation/translations/it_IT/locking/index.rst b/Documentation/translations/it_IT/locking/index.rst new file mode 100644 index 00000000000000..19963d33e84d2e --- /dev/null +++ b/Documentation/translations/it_IT/locking/index.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================ +Sincronizzazione +================ + +.. toctree:: + :maxdepth: 1 + + locktypes + lockdep-design + lockstat + locktorture + +.. only:: subproject and html + + Indici + ====== + + * :ref:`genindex` diff --git a/Documentation/translations/it_IT/locking/lockdep-design.rst b/Documentation/translations/it_IT/locking/lockdep-design.rst new file mode 100644 index 00000000000000..9ed00d8cf28075 --- /dev/null +++ b/Documentation/translations/it_IT/locking/lockdep-design.rst @@ -0,0 +1,678 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +Validatore di sincronizzazione durante l'esecuzione +=================================================== + +Classi di blocchi +----------------- + +L'oggetto su cui il validatore lavora è una "classe" di blocchi. + +Una classe di blocchi è un gruppo di blocchi che seguono le stesse regole di +sincronizzazione, anche quando i blocchi potrebbero avere più istanze (anche +decine di migliaia). Per esempio un blocco nella struttura inode è una classe, +mentre ogni inode sarà un'istanza di questa classe di blocco. + +Il validatore traccia lo "stato d'uso" di una classe di blocchi e le sue +dipendenze con altre classi. L'uso di un blocco indica come quel blocco viene +usato rispetto al suo contesto d'interruzione, mentre le dipendenze di un blocco +possono essere interpretate come il loro ordine; per esempio L1 -> L2 suggerisce +che un processo cerca di acquisire L2 mentre già trattiene L1. Dal punto di +vista di lockdep, i due blocchi (L1 ed L2) non sono per forza correlati: quella +dipendenza indica solamente l'ordine in cui sono successe le cose. Il validatore +verifica permanentemente la correttezza dell'uso dei blocchi e delle loro +dipendenze, altrimenti ritornerà un errore. + +Il comportamento di una classe di blocchi viene costruito dall'insieme delle sue +istanze. Una classe di blocco viene registrata alla creazione della sua prima +istanza, mentre tutte le successive istanze verranno mappate; dunque, il loro +uso e le loro dipendenze contribuiranno a costruire quello della classe. Una +classe di blocco non sparisce quando sparisce una sua istanza, ma può essere +rimossa quando il suo spazio in memoria viene reclamato. Per esempio, questo +succede quando si rimuove un modulo, o quando una *workqueue* viene eliminata. + +Stato +----- + +Il validatore traccia l'uso cronologico delle classi di blocchi e ne divide +l'uso in categorie (4 USI * n STATI + 1). + +I quattro USI possono essere: + +- 'sempre trattenuto nel contesto ' +- 'sempre trattenuto come blocco di lettura nel contesto ' +- 'sempre trattenuto con abilitato' +- 'sempre trattenuto come blocco di lettura con abilitato' + +gli `n` STATI sono codificati in kernel/locking/lockdep_states.h, ad oggi +includono: + +- hardirq +- softirq + +infine l'ultima categoria è: + +- 'sempre trattenuto' [ == !unused ] + +Quando vengono violate le regole di sincronizzazione, questi bit di utilizzo +vengono presentati nei messaggi di errore di sincronizzazione, fra parentesi +graffe, per un totale di `2 * n` (`n`: bit STATO). Un esempio inventato:: + + modprobe/2287 is trying to acquire lock: + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + + but task is already holding lock: + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + +Per un dato blocco, da sinistra verso destra, la posizione del bit indica l'uso +del blocco e di un eventuale blocco di lettura, per ognuno degli `n` STATI elencati +precedentemente. Il carattere mostrato per ogni bit indica: + + === =========================================================================== + '.' acquisito con interruzioni disabilitate fuori da un contesto d'interruzione + '-' acquisito in contesto d'interruzione + '+' acquisito con interruzioni abilitate + '?' acquisito in contesto d'interruzione con interruzioni abilitate + === =========================================================================== + +Il seguente esempio mostra i bit:: + + (&sio_locks[i].lock){-.-.}, at: [] mutex_lock+0x21/0x24 + |||| + ||| \-> softirq disabilitati e fuori da un contesto di softirq + || \--> acquisito in un contesto di softirq + | \---> hardirq disabilitati e fuori da un contesto di hardirq + \----> acquisito in un contesto di hardirq + +Per un dato STATO, che il blocco sia mai stato acquisito in quel contesto di +STATO, o che lo STATO sia abilitato, ci lascia coi quattro possibili scenari +mostrati nella seguente tabella. Il carattere associato al bit indica con +esattezza in quale scenario ci si trova al momento del rapporto. + + +---------------+---------------+------------------+ + | | irq abilitati | irq disabilitati | + +---------------+---------------+------------------+ + | sempre in irq | '?' | '-' | + +---------------+---------------+------------------+ + | mai in irq | '+' | '.' | + +---------------+---------------+------------------+ + +Il carattere '-' suggerisce che le interruzioni sono disabilitate perché +altrimenti verrebbe mostrato il carattere '?'. Una deduzione simile può essere +fatta anche per '+' + +I blocchi inutilizzati (ad esempio i mutex) non possono essere fra le cause di +un errore. + +Regole dello stato per un blocco singolo +---------------------------------------- + +Avere un blocco sicuro in interruzioni (*irq-safe*) significa che è sempre stato +usato in un contesto d'interruzione, mentre un blocco insicuro in interruzioni +(*irq-unsafe*) significa che è sempre stato acquisito con le interruzioni +abilitate. + +Una classe softirq insicura è automaticamente insicura anche per hardirq. I +seguenti stati sono mutualmente esclusivi: solo una può essere vero quando viene +usata una classe di blocco:: + + o + o + +Questo perché se un blocco può essere usato in un contesto di interruzioni +(sicuro in interruzioni), allora non può mai essere acquisito con le +interruzioni abilitate (insicuro in interruzioni). Altrimenti potrebbe +verificarsi uno stallo. Per esempio, questo blocco viene acquisito, ma prima di +essere rilasciato il contesto d'esecuzione viene interrotto nuovamente, e quindi +si tenterà di acquisirlo nuovamente. Questo porterà ad uno stallo, in +particolare uno stallo ricorsivo. + +Il validatore rileva e riporta gli usi di blocchi che violano queste regole per +blocchi singoli. + +Regole per le dipendenze di blocchi multipli +-------------------------------------------- + +La stessa classe di blocco non deve essere acquisita due volte, questo perché +potrebbe portare ad uno blocco ricorsivo e dunque ad uno stallo. + +Inoltre, due blocchi non possono essere trattenuti in ordine inverso:: + + -> + -> + +perché porterebbe ad uno stallo - chiamato stallo da blocco inverso - in cui si +cerca di trattenere i due blocchi in un ciclo in cui entrambe i contesti +aspettano per sempre che l'altro termini. Il validatore è in grado di trovare +queste dipendenze cicliche di qualsiasi complessità, ovvero nel mezzo ci +potrebbero essere altre sequenze di blocchi. Il validatore troverà se questi +blocchi possono essere acquisiti circolarmente. + +In aggiunta, le seguenti sequenze di blocco nei contesti indicati non sono +permesse, indipendentemente da quale che sia la classe di blocco:: + + -> + -> + +La prima regola deriva dal fatto che un blocco sicuro in interruzioni può essere +trattenuto in un contesto d'interruzione che, per definizione, ha la possibilità +di interrompere un blocco insicuro in interruzioni; questo porterebbe ad uno +stallo da blocco inverso. La seconda, analogamente, ci dice che un blocco sicuro +in interruzioni software potrebbe essere trattenuto in un contesto di +interruzione software, dunque potrebbe interrompere un blocco insicuro in +interruzioni software. + +Le suddette regole vengono applicate per qualsiasi sequenza di blocchi: quando +si acquisiscono nuovi blocchi, il validatore verifica se vi è una violazione +delle regole fra il nuovo blocco e quelli già trattenuti. + +Quando una classe di blocco cambia stato, applicheremo le seguenti regole: + +- se viene trovato un nuovo blocco sicuro in interruzioni, verificheremo se + abbia mai trattenuto dei blocchi insicuri in interruzioni. + +- se viene trovato un nuovo blocco sicuro in interruzioni software, + verificheremo se abbia trattenuto dei blocchi insicuri in interruzioni + software. + +- se viene trovato un nuovo blocco insicuro in interruzioni, verificheremo se + abbia trattenuto dei blocchi sicuri in interruzioni. + +- se viene trovato un nuovo blocco insicuro in interruzioni software, + verificheremo se abbia trattenuto dei blocchi sicuri in interruzioni + software. + +(Di nuovo, questi controlli vengono fatti perché un contesto d'interruzione +potrebbe interrompere l'esecuzione di qualsiasi blocco insicuro portando ad uno +stallo; questo anche se lo stallo non si verifica in pratica) + +Eccezione: dipendenze annidate sui dati portano a blocchi annidati +------------------------------------------------------------------ + +Ci sono alcuni casi in cui il kernel Linux acquisisce più volte la stessa +istanza di una classe di blocco. Solitamente, questo succede quando esiste una +gerarchia fra oggetti dello stesso tipo. In questi casi viene ereditato +implicitamente l'ordine fra i due oggetti (definito dalle proprietà di questa +gerarchia), ed il kernel tratterrà i blocchi in questo ordine prefissato per +ognuno degli oggetti. + +Un esempio di questa gerarchia di oggetti che producono "blocchi annidati" sono +i *block-dev* che rappresentano l'intero disco e quelli che rappresentano una +sua partizione; la partizione è una parte del disco intero, e l'ordine dei +blocchi sarà corretto fintantoche uno acquisisce il blocco del disco intero e +poi quello della partizione. Il validatore non rileva automaticamente questo +ordine implicito, perché queste regole di sincronizzazione non sono statiche. + +Per istruire il validatore riguardo a questo uso corretto dei blocchi sono stati +introdotte nuove primitive per specificare i "livelli di annidamento". Per +esempio, per i blocchi a mutua esclusione dei *block-dev* si avrebbe una +chiamata simile a:: + + enum bdev_bd_mutex_lock_class + { + BD_MUTEX_NORMAL, + BD_MUTEX_WHOLE, + BD_MUTEX_PARTITION + }; + + mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION); + +In questo caso la sincronizzazione viene fatta su un *block-dev* sapendo che si +tratta di una partizione. + +Ai fini della validazione, il validatore lo considererà con una - sotto - classe +di blocco separata. + +Nota: Prestate estrema attenzione che la vostra gerarchia sia corretta quando si +vogliono usare le primitive _nested(); altrimenti potreste avere sia falsi +positivi che falsi negativi. + +Annotazioni +----------- + +Si possono utilizzare due costrutti per verificare ed annotare se certi blocchi +devono essere trattenuti: lockdep_assert_held*(&lock) e +lockdep_*pin_lock(&lock). + +Come suggerito dal nome, la famiglia di macro lockdep_assert_held* asseriscono +che un dato blocco in un dato momento deve essere trattenuto (altrimenti, verrà +generato un WARN()). Queste vengono usate abbondantemente nel kernel, per +esempio in kernel/sched/core.c:: + + void update_rq_clock(struct rq *rq) + { + s64 delta; + + lockdep_assert_held(&rq->lock); + [...] + } + +dove aver trattenuto rq->lock è necessario per aggiornare in sicurezza il clock +rq. + +L'altra famiglia di macro è lockdep_*pin_lock(), che a dire il vero viene usata +solo per rq->lock ATM. Se per caso un blocco non viene trattenuto, queste +genereranno un WARN(). Questo si rivela particolarmente utile quando si deve +verificare la correttezza di codice con *callback*, dove livelli superiori +potrebbero assumere che un blocco rimanga trattenuto, ma livelli inferiori +potrebbero invece pensare che il blocco possa essere rilasciato e poi +riacquisito (involontariamente si apre una sezione critica). lockdep_pin_lock() +restituisce 'struct pin_cookie' che viene usato da lockdep_unpin_lock() per +verificare che nessuno abbia manomesso il blocco. Per esempio in +kernel/sched/sched.h abbiamo:: + + static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf) + { + rf->cookie = lockdep_pin_lock(&rq->lock); + [...] + } + + static inline void rq_unpin_lock(struct rq *rq, struct rq_flags *rf) + { + [...] + lockdep_unpin_lock(&rq->lock, rf->cookie); + } + +I commenti riguardo alla sincronizzazione possano fornire informazioni utili, +tuttavia sono le verifiche in esecuzione effettuate da queste macro ad essere +vitali per scovare problemi di sincronizzazione, ed inoltre forniscono lo stesso +livello di informazioni quando si ispeziona il codice. Nel dubbio, preferite +queste annotazioni! + +Dimostrazione di correttezza al 100% +------------------------------------ + +Il validatore verifica la proprietà di chiusura in senso matematico. Ovvero, per +ogni sequenza di sincronizzazione di un singolo processo che si verifichi almeno +una volta nel kernel, il validatore dimostrerà con una certezza del 100% che +nessuna combinazione e tempistica di queste sequenze possa causare uno stallo in +una qualsiasi classe di blocco. [1]_ + +In pratica, per dimostrare l'esistenza di uno stallo non servono complessi +scenari di sincronizzazione multi-processore e multi-processo. Il validatore può +dimostrare la correttezza basandosi sulla sola sequenza di sincronizzazione +apparsa almeno una volta (in qualunque momento, in qualunque processo o +contesto). Uno scenario complesso che avrebbe bisogno di 3 processori e una +sfortunata presenza di processi, interruzioni, e pessimo tempismo, può essere +riprodotto su un sistema a singolo processore. + +Questo riduce drasticamente la complessità del controllo di qualità della +sincronizzazione nel kernel: quello che deve essere fatto è di innescare nel +kernel quante più possibili "semplici" sequenze di sincronizzazione, almeno una +volta, allo scopo di dimostrarne la correttezza. Questo al posto di innescare +una verifica per ogni possibile combinazione di sincronizzazione fra processori, +e differenti scenari con hardirq e softirq e annidamenti vari (nella pratica, +impossibile da fare) + +.. [1] + + assumendo che il validatore sia corretto al 100%, e che nessun altra parte + del sistema possa corromperne lo stato. Assumiamo anche che tutti i percorsi + MNI/SMM [potrebbero interrompere anche percorsi dove le interruzioni sono + disabilitate] sono corretti e non interferiscono con il validatore. Inoltre, + assumiamo che un hash a 64-bit sia unico per ogni sequenza di + sincronizzazione nel sistema. Infine, la ricorsione dei blocchi non deve + essere maggiore di 20. + +Prestazione +----------- + +Le regole sopracitate hanno bisogno di una quantità **enorme** di verifiche +durante l'esecuzione. Il sistema sarebbe diventato praticamente inutilizzabile +per la sua lentezza se le avessimo fatte davvero per ogni blocco trattenuto e +per ogni abilitazione delle interruzioni. La complessità della verifica è +O(N^2), quindi avremmo dovuto fare decine di migliaia di verifiche per ogni +evento, il tutto per poche centinaia di classi. + +Il problema è stato risolto facendo una singola verifica per ogni 'scenario di +sincronizzazione' (una sequenza unica di blocchi trattenuti uno dopo l'altro). +Per farlo, viene mantenuta una pila dei blocchi trattenuti, e viene calcolato un +hash a 64-bit unico per ogni sequenza. Quando la sequenza viene verificata per +la prima volta, l'hash viene inserito in una tabella hash. La tabella potrà +essere verificata senza bisogno di blocchi. Se la sequenza dovesse ripetersi, la +tabella ci dirà che non è necessario verificarla nuovamente. + +Risoluzione dei problemi +------------------------ + +Il massimo numero di classi di blocco che il validatore può tracciare è: +MAX_LOCKDEP_KEYS. Oltrepassare questo limite indurrà lokdep a generare il +seguente avviso:: + + (DEBUG_LOCKS_WARN_ON(id >= MAX_LOCKDEP_KEYS)) + +Di base questo valore è 8191, e un classico sistema da ufficio ha meno di 1000 +classi, dunque questo avviso è solitamente la conseguenza di un problema di +perdita delle classi di blocco o d'inizializzazione dei blocchi. Di seguito una +descrizione dei due problemi: + +1. caricare e rimuovere continuamente i moduli mentre il validatore è in + esecuzione porterà ad una perdita di classi di blocco. Il problema è che ogni + caricamento crea un nuovo insieme di classi di blocco per tutti i blocchi di + quel modulo. Tuttavia, la rimozione del modulo non rimuove le vecchie classi + (vedi dopo perché non le riusiamo). Dunque, il continuo caricamento e + rimozione di un modulo non fa altro che aumentare il contatore di classi fino + a raggiungere, eventualmente, il limite. + +2. Usare array con un gran numero di blocchi che non vengono esplicitamente + inizializzati. Per esempio, una tabella hash con 8192 *bucket* dove ognuno ha + il proprio spinlock_t consumerà 8192 classi di blocco a meno che non vengano + esplicitamente inizializzati in esecuzione usando spin_lock_init() invece + dell'inizializzazione durante la compilazione con __SPIN_LOCK_UNLOCKED(). + Sbagliare questa inizializzazione garantisce un esaurimento di classi di + blocco. Viceversa, un ciclo che invoca spin_lock_init() su tutti i blocchi li + mapperebbe tutti alla stessa classe di blocco. + + La morale della favola è che dovete sempre inizializzare esplicitamente i + vostri blocchi. + +Qualcuno potrebbe argomentare che il validatore debba permettere il riuso di +classi di blocco. Tuttavia, se siete tentati dall'argomento, prima revisionate +il codice e pensate alla modifiche necessarie, e tenendo a mente che le classi +di blocco da rimuovere probabilmente sono legate al grafo delle dipendenze. Più +facile a dirsi che a farsi. + +Ovviamente, se non esaurite le classi di blocco, la prossima cosa da fare è +quella di trovare le classi non funzionanti. Per prima cosa, il seguente comando +ritorna il numero di classi attualmente in uso assieme al valore massimo:: + + grep "lock-classes" /proc/lockdep_stats + +Questo comando produce il seguente messaggio:: + + lock-classes: 748 [max: 8191] + +Se il numero di assegnazioni (748 qui sopra) aumenta continuamente nel tempo, +allora c'è probabilmente un problema da qualche parte. Il seguente comando può +essere utilizzato per identificare le classi di blocchi problematiche:: + + grep "BD" /proc/lockdep + +Eseguite il comando e salvatene l'output, quindi confrontatelo con l'output di +un'esecuzione successiva per identificare eventuali problemi. Questo stesso +output può anche aiutarti a trovare situazioni in cui l'inizializzazione del +blocco è stata omessa. + +Lettura ricorsiva dei blocchi +----------------------------- + +Il resto di questo documento vuole dimostrare che certi cicli equivalgono ad una +possibilità di stallo. + +Ci sono tre tipi di bloccatori: gli scrittori (bloccatori esclusivi, come +spin_lock() o write_lock()), lettori non ricorsivi (bloccatori condivisi, come +down_read()), e lettori ricorsivi (bloccatori condivisi ricorsivi, come +rcu_read_lock()). D'ora in poi, per questi tipi di bloccatori, useremo la +seguente notazione: + + W o E: per gli scrittori (bloccatori esclusivi) (W dall'inglese per + *Writer*, ed E per *Exclusive*). + + r: per i lettori non ricorsivi (r dall'inglese per *reader*). + + R: per i lettori ricorsivi (R dall'inglese per *Reader*). + + S: per qualsiasi lettore (non ricorsivi + ricorsivi), dato che entrambe + sono bloccatori condivisi (S dall'inglese per *Shared*). + + N: per gli scrittori ed i lettori non ricorsivi, dato che entrambe sono + non ricorsivi. + +Ovviamente, N equivale a "r o W" ed S a "r o R". + +Come suggerisce il nome, i lettori ricorsivi sono dei bloccatori a cui è +permesso di acquisire la stessa istanza di blocco anche all'interno della +sezione critica di un altro lettore. In altre parole, permette di annidare la +stessa istanza di blocco nelle sezioni critiche dei lettori. + +Dall'altro canto, lo stesso comportamento indurrebbe un lettore non ricorsivo ad +auto infliggersi uno stallo. + +La differenza fra questi due tipi di lettori esiste perché: quelli ricorsivi +vengono bloccati solo dal trattenimento di un blocco di scrittura, mentre quelli +non ricorsivi possono essere bloccati dall'attesa di un blocco di scrittura. +Consideriamo il seguente esempio:: + + TASK A: TASK B: + + read_lock(X); + write_lock(X); + read_lock_2(X); + +L'attività A acquisisce il blocco di lettura X (non importa se di tipo ricorsivo +o meno) usando read_lock(). Quando l'attività B tenterà di acquisire il blocco +X, si fermerà e rimarrà in attesa che venga rilasciato. Ora se read_lock_2() è +un tipo lettore ricorsivo, l'attività A continuerà perché gli scrittori in +attesa non possono bloccare lettori ricorsivi, e non avremo alcuno stallo. +Tuttavia, se read_lock_2() è un lettore non ricorsivo, allora verrà bloccato +dall'attività B e si causerà uno stallo. + +Condizioni bloccanti per lettori/scrittori su uno stesso blocco +--------------------------------------------------------------- +Essenzialmente ci sono quattro condizioni bloccanti: + +1. Uno scrittore blocca un altro scrittore. +2. Un lettore blocca uno scrittore. +3. Uno scrittore blocca sia i lettori ricorsivi che non ricorsivi. +4. Un lettore (ricorsivo o meno) non blocca altri lettori ricorsivi ma potrebbe + bloccare quelli non ricorsivi (perché potrebbero esistere degli scrittori in + attesa). + +Di seguito le tabella delle condizioni bloccanti, Y (*Yes*) significa che il +tipo in riga blocca quello in colonna, mentre N l'opposto. + + +---+---+---+---+ + | | W | r | R | + +---+---+---+---+ + | W | Y | Y | Y | + +---+---+---+---+ + | r | Y | Y | N | + +---+---+---+---+ + | R | Y | Y | N | + +---+---+---+---+ + + (W: scrittori, r: lettori non ricorsivi, R: lettori ricorsivi) + +Al contrario dei blocchi per lettori non ricorsivi, quelli ricorsivi vengono +trattenuti da chi trattiene il blocco di scrittura piuttosto che da chi ne +attende il rilascio. Per esempio:: + + TASK A: TASK B: + + read_lock(X); + + write_lock(X); + + read_lock(X); + +non produce uno stallo per i lettori ricorsivi, in quanto il processo B rimane +in attesta del blocco X, mentre il secondo read_lock() non ha bisogno di +aspettare perché si tratta di un lettore ricorsivo. Tuttavia, se read_lock() +fosse un lettore non ricorsivo, questo codice produrrebbe uno stallo. + +Da notare che in funzione dell'operazione di blocco usate per l'acquisizione (in +particolare il valore del parametro 'read' in lock_acquire()), un blocco può +essere di scrittura (blocco esclusivo), di lettura non ricorsivo (blocco +condiviso e non ricorsivo), o di lettura ricorsivo (blocco condiviso e +ricorsivo). In altre parole, per un'istanza di blocco esistono tre tipi di +acquisizione che dipendono dalla funzione di acquisizione usata: esclusiva, di +lettura non ricorsiva, e di lettura ricorsiva. + +In breve, chiamiamo "non ricorsivi" blocchi di scrittura e quelli di lettura non +ricorsiva, mentre "ricorsivi" i blocchi di lettura ricorsivi. + +I blocchi ricorsivi non si bloccano a vicenda, mentre quelli non ricorsivi sì +(anche in lettura). Un blocco di lettura non ricorsivi può bloccare uno +ricorsivo, e viceversa. + +Il seguente esempio mostra uno stallo con blocchi ricorsivi:: + + TASK A: TASK B: + + read_lock(X); + read_lock(Y); + write_lock(Y); + write_lock(X); + +Il processo A attende che il processo B esegua read_unlock() so Y, mentre il +processo B attende che A esegua read_unlock() su X. + +Tipi di dipendenze e percorsi forti +----------------------------------- +Le dipendenze fra blocchi tracciano l'ordine con cui una coppia di blocchi viene +acquisita, e perché vi sono 3 tipi di bloccatori, allora avremo 9 tipi di +dipendenze. Tuttavia, vi mostreremo che 4 sono sufficienti per individuare gli +stalli. + +Per ogni dipendenza fra blocchi avremo:: + + L1 -> L2 + +Questo significa che lockdep ha visto acquisire L1 prima di L2 nello stesso +contesto di esecuzione. Per quanto riguarda l'individuazione degli stalli, ci +interessa sapere se possiamo rimanere bloccati da L2 mentre L1 viene trattenuto. +In altre parole, vogliamo sapere se esiste un bloccatore L3 che viene bloccato +da L1 e un L2 che viene bloccato da L3. Dunque, siamo interessati a (1) quello +che L1 blocca e (2) quello che blocca L2. Di conseguenza, possiamo combinare +lettori ricorsivi e non per L1 (perché bloccano gli stessi tipi) e possiamo +combinare scrittori e lettori non ricorsivi per L2 (perché vengono bloccati +dagli stessi tipi). + +Con questa semplificazione, possiamo dedurre che ci sono 4 tipi di rami nel +grafo delle dipendenze di lockdep: + +1) -(ER)->: + dipendenza da scrittore esclusivo a lettore ricorsivo. "X -(ER)-> Y" + significa X -> Y, dove X è uno scrittore e Y un lettore ricorsivo. + +2) -(EN)->: + dipendenza da scrittore esclusivo a bloccatore non ricorsivo. + "X -(EN)->" significa X-> Y, dove X è uno scrittore e Y può essere + o uno scrittore o un lettore non ricorsivo. + +3) -(SR)->: + dipendenza da lettore condiviso a lettore ricorsivo. "X -(SR)->" + significa X -> Y, dove X è un lettore (ricorsivo o meno) e Y è un + lettore ricorsivo. + +4) -(SN)->: + dipendenza da lettore condiviso a bloccatore non ricorsivo. + "X -(SN)-> Y" significa X -> Y , dove X è un lettore (ricorsivo + o meno) e Y può essere o uno scrittore o un lettore non ricorsivo. + +Da notare che presi due blocchi, questi potrebbero avere più dipendenza fra di +loro. Per esempio:: + + TASK A: + + read_lock(X); + write_lock(Y); + ... + + TASK B: + + write_lock(X); + write_lock(Y); + +Nel grafo delle dipendenze avremo sia X -(SN)-> Y che X -(EN)-> Y. + +Usiamo -(xN)-> per rappresentare i rami sia per -(EN)-> che -(SN)->, allo stesso +modo -(Ex)->, -(xR)-> e -(Sx)-> + +Un "percorso" in un grafo è una serie di nodi e degli archi che li congiungono. +Definiamo un percorso "forte", come il percorso che non ha archi (dipendenze) di +tipo -(xR)-> e -(Sx)->. In altre parole, un percorso "forte" è un percorso da un +blocco ad un altro attraverso le varie dipendenze, e se sul percorso abbiamo X +-> Y -> Z (dove X, Y, e Z sono blocchi), e da X a Y si ha una dipendenza -(SR)-> +o -(ER)->, allora fra Y e Z non deve esserci una dipendenza -(SN)-> o -(SR)->. + +Nella prossima sezione vedremo perché definiamo questo percorso "forte". + +Identificazione di stalli da lettura ricorsiva +---------------------------------------------- +Ora vogliamo dimostrare altre due cose: + +Lemma 1: + +Se esiste un percorso chiuso forte (ciclo forte), allora esiste anche una +combinazione di sequenze di blocchi che causa uno stallo. In altre parole, +l'esistenza di un ciclo forte è sufficiente alla scoperta di uno stallo. + +Lemma 2: + +Se non esiste un percorso chiuso forte (ciclo forte), allora non esiste una +combinazione di sequenze di blocchi che causino uno stallo. In altre parole, i +cicli forti sono necessari alla rilevazione degli stallo. + +Con questi due lemmi possiamo facilmente affermare che un percorso chiuso forte +è sia sufficiente che necessario per avere gli stalli, dunque averli equivale +alla possibilità di imbattersi concretamente in uno stallo. Un percorso chiuso +forte significa che può causare stalli, per questo lo definiamo "forte", ma ci +sono anche cicli di dipendenze che non causeranno stalli. + +Dimostrazione di sufficienza (lemma 1): + +Immaginiamo d'avere un ciclo forte:: + + L1 -> L2 ... -> Ln -> L1 + +Questo significa che abbiamo le seguenti dipendenze:: + + L1 -> L2 + L2 -> L3 + ... + Ln-1 -> Ln + Ln -> L1 + +Ora possiamo costruire una combinazione di sequenze di blocchi che causano lo +stallo. + +Per prima cosa facciamo sì che un processo/processore prenda L1 in L1 -> L2, poi +un altro prende L2 in L2 -> L3, e così via. Alla fine, tutti i Lx in Lx -> Lx+1 +saranno trattenuti da processi/processori diversi. + +Poi visto che abbiamo L1 -> L2, chi trattiene L1 vorrà acquisire L2 in L1 -> L2, +ma prima dovrà attendere che venga rilasciato da chi lo trattiene. Questo perché +L2 è già trattenuto da un altro processo/processore, ed in più L1 -> L2 e L2 -> +L3 non sono -(xR)-> né -(Sx)-> (la definizione di forte). Questo significa che L2 +in L1 -> L2 non è un bloccatore non ricorsivo (bloccabile da chiunque), e L2 in +L2 -> L3 non è uno scrittore (che blocca chiunque). + +In aggiunta, possiamo trarre una simile conclusione per chi sta trattenendo L2: +deve aspettare che L3 venga rilasciato, e così via. Ora possiamo dimostrare che +chi trattiene Lx deve aspettare che Lx+1 venga rilasciato. Notiamo che Ln+1 è +L1, dunque si è creato un ciclo dal quale non possiamo uscire, quindi si ha uno +stallo. + +Dimostrazione della necessità (lemma 2): + +Questo lemma equivale a dire che: se siamo in uno scenario di stallo, allora +deve esiste un ciclo forte nel grafo delle dipendenze. + +Secondo Wikipedia[1], se c'è uno stallo, allora deve esserci un ciclo di attese, +ovvero ci sono N processi/processori dove P1 aspetta un blocco trattenuto da P2, +e P2 ne aspetta uno trattenuto da P3, ... e Pn attende che il blocco P1 venga +rilasciato. Chiamiamo Lx il blocco che attende Px, quindi P1 aspetta L1 e +trattiene Ln. Quindi avremo Ln -> L1 nel grafo delle dipendenze. Similarmente, +nel grafo delle dipendenze avremo L1 -> L2, L2 -> L3, ..., Ln-1 -> Ln, il che +significa che abbiamo un ciclo:: + + Ln -> L1 -> L2 -> ... -> Ln + +, ed ora dimostriamo d'avere un ciclo forte. + +Per un blocco Lx, il processo Px contribuisce alla dipendenza Lx-1 -> Lx e Px+1 +contribuisce a quella Lx -> Lx+1. Visto che Px aspetta che Px+1 rilasci Lx, sarà +impossibile che Lx in Px+1 sia un lettore e che Lx in Px sia un lettore +ricorsivo. Questo perché i lettori (ricorsivi o meno) non bloccano lettori +ricorsivi. Dunque, Lx-1 -> Lx e Lx -> Lx+1 non possono essere una coppia di +-(xR)-> -(Sx)->. Questo è vero per ogni ciclo, dunque, questo è un ciclo forte. + +Riferimenti +----------- + +[1]: https://it.wikipedia.org/wiki/Stallo_(informatica) + +[2]: Shibu, K. (2009). Intro To Embedded Systems (1st ed.). Tata McGraw-Hill diff --git a/Documentation/translations/it_IT/locking/lockstat.rst b/Documentation/translations/it_IT/locking/lockstat.rst new file mode 100644 index 00000000000000..77972d971d7c5f --- /dev/null +++ b/Documentation/translations/it_IT/locking/lockstat.rst @@ -0,0 +1,230 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +======================= +Statistiche sui blocchi +======================= + +Cosa +==== + +Come suggerisce il nome, fornisce statistiche sui blocchi. + + +Perché +====== + +Perché, tanto per fare un esempio, le contese sui blocchi possono influenzare +significativamente le prestazioni. + +Come +==== + +*Lockdep* ha punti di collegamento nelle funzioni di blocco e inoltre +mappa le istanze di blocco con le relative classi. Partiamo da questo punto +(vedere Documentation/translations/it_IT/locking/lockdep-design.rst). +Il grafico sottostante mostra la relazione che intercorre fra le +funzioni di blocco e i vari punti di collegamenti che ci sono al loro +interno:: + + __acquire + | + lock _____ + | \ + | __contended + | | + | + | _______/ + |/ + | + __acquired + | + . + + . + | + __release + | + unlock + + lock, unlock - le classiche funzioni di blocco + __* - i punti di collegamento + <> - stati + +Grazie a questi punti di collegamento possiamo fornire le seguenti statistiche: + +con-bounces + - numero di contese su un blocco che riguarda dati di un processore + +contentions + - numero di acquisizioni di blocchi che hanno dovuto attendere + +wait time + min + - tempo minimo (diverso da zero) che sia mai stato speso in attesa di + un blocco + + max + - tempo massimo che sia mai stato speso in attesa di un blocco + + total + - tempo totale speso in attesa di un blocco + + avg + - tempo medio speso in attesa di un blocco + +acq-bounces + - numero di acquisizioni di blocco che riguardavano i dati su un processore + +acquisitions + - numero di volte che un blocco è stato ottenuto + +hold time + min + - tempo minimo (diverso da zero) che sia mai stato speso trattenendo un blocco + + max + - tempo massimo che sia mai stato speso trattenendo un blocco + + total + - tempo totale di trattenimento di un blocco + + avg + - tempo medio di trattenimento di un blocco + +Questi numeri vengono raccolti per classe di blocco, e per ogni stato di +lettura/scrittura (quando applicabile). + +Inoltre, questa raccolta di statistiche tiene traccia di 4 punti di contesa +per classe di blocco. Un punto di contesa è una chiamata che ha dovuto +aspettare l'acquisizione di un blocco. + +Configurazione +-------------- + +Le statistiche sui blocchi si abilitano usando l'opzione di configurazione +CONFIG_LOCK_STAT. + +Uso +--- + +Abilitare la raccolta di statistiche:: + + # echo 1 >/proc/sys/kernel/lock_stat + +Disabilitare la raccolta di statistiche:: + + # echo 0 >/proc/sys/kernel/lock_stat + +Per vedere le statistiche correnti sui blocchi:: + + ( i numeri di riga non fanno parte dell'output del comando, ma sono stati + aggiunti ai fini di questa spiegazione ) + + # less /proc/lock_stat + + 01 lock_stat version 0.4 + 02----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg + 04----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + 05 + 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99 + 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77 + 08 --------------- + 09 &mm->mmap_sem 1 [] khugepaged_scan_mm_slot+0x57/0x280 + 10 &mm->mmap_sem 96 [] __do_page_fault+0x1d4/0x510 + 11 &mm->mmap_sem 34 [] vm_mmap_pgoff+0x87/0xd0 + 12 &mm->mmap_sem 17 [] vm_munmap+0x41/0x80 + 13 --------------- + 14 &mm->mmap_sem 1 [] dup_mmap+0x2a/0x3f0 + 15 &mm->mmap_sem 60 [] SyS_mprotect+0xe9/0x250 + 16 &mm->mmap_sem 41 [] __do_page_fault+0x1d4/0x510 + 17 &mm->mmap_sem 68 [] vm_mmap_pgoff+0x87/0xd0 + 18 + 19............................................................................................................................................................................................................................. + 20 + 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48 + 22 --------------- + 23 unix_table_lock 45 [] unix_create1+0x16e/0x1b0 + 24 unix_table_lock 47 [] unix_release_sock+0x31/0x250 + 25 unix_table_lock 15 [] unix_find_other+0x117/0x230 + 26 unix_table_lock 5 [] unix_autobind+0x11f/0x1b0 + 27 --------------- + 28 unix_table_lock 39 [] unix_release_sock+0x31/0x250 + 29 unix_table_lock 49 [] unix_create1+0x16e/0x1b0 + 30 unix_table_lock 20 [] unix_find_other+0x117/0x230 + 31 unix_table_lock 4 [] unix_autobind+0x11f/0x1b0 + +Questo estratto mostra le statistiche delle prime due classi di +blocco. La riga 01 mostra la versione dell'output - la versione +cambierà ogni volta che cambia il formato. Le righe dalla 02 alla 04 +rappresentano l'intestazione con la descrizione delle colonne. Le +statistiche sono mostrate nelle righe dalla 05 alla 18 e dalla 20 +alla 31. Queste statistiche sono divise in due parti: le statistiche, +seguite dai punti di contesa (righe 08 e 13) separati da un divisore. + +Le righe dalla 09 alla 12 mostrano i primi quattro punti di contesa +registrati (il codice che tenta di acquisire un blocco) e le righe +dalla 14 alla 17 mostrano i primi quattro punti contesi registrati +(ovvero codice che ha acquisito un blocco). È possibile che nelle +statistiche manchi il valore *max con-bounces*. + +Il primo blocco (righe dalla 05 alla 18) è di tipo lettura/scrittura e quindi +mostra due righe prima del divisore. I punti di contesa non corrispondono alla +descrizione delle colonne nell'intestazione; essi hanno due colonne: *punti di +contesa* e *[] simboli*. Il secondo gruppo di punti di contesa sono i punti +con cui si contende il blocco. + +La parte interna del tempo è espressa in us (microsecondi). + +Quando si ha a che fare con blocchi annidati si potrebbero vedere le +sottoclassi di blocco:: + + 32........................................................................................................................................................................................................................... + 33 + 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82 + 35 --------- + 36 &rq->lock 645 [] task_rq_lock+0x43/0x75 + 37 &rq->lock 297 [] try_to_wake_up+0x127/0x25a + 38 &rq->lock 360 [] select_task_rq_fair+0x1f0/0x74a + 39 &rq->lock 428 [] scheduler_tick+0x46/0x1fb + 40 --------- + 41 &rq->lock 77 [] task_rq_lock+0x43/0x75 + 42 &rq->lock 174 [] try_to_wake_up+0x127/0x25a + 43 &rq->lock 4715 [] double_rq_lock+0x42/0x54 + 44 &rq->lock 893 [] schedule+0x157/0x7b8 + 45 + 46........................................................................................................................................................................................................................... + 47 + 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84 + 49 ----------- + 50 &rq->lock/1 11526 [] double_rq_lock+0x4f/0x54 + 51 ----------- + 52 &rq->lock/1 5645 [] double_rq_lock+0x42/0x54 + 53 &rq->lock/1 1224 [] schedule+0x157/0x7b8 + 54 &rq->lock/1 4336 [] double_rq_lock+0x4f/0x54 + 55 &rq->lock/1 181 [] try_to_wake_up+0x127/0x25a + +La riga 48 mostra le statistiche per la seconda sottoclasse (/1) della +classe *&irq->lock* (le sottoclassi partono da 0); in questo caso, +come suggerito dalla riga 50, ``double_rq_lock`` tenta di acquisire un blocco +annidato di due spinlock. + +Per vedere i blocco più contesi:: + + # grep : /proc/lock_stat | head + clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71 + tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59 + &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59 + &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69 + &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93 + tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72 + tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89 + rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89 + &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27 + rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76 + +Per cancellare le statistiche:: + + # echo 0 > /proc/lock_stat diff --git a/Documentation/translations/it_IT/locking/locktorture.rst b/Documentation/translations/it_IT/locking/locktorture.rst new file mode 100644 index 00000000000000..87a0dbeaca772a --- /dev/null +++ b/Documentation/translations/it_IT/locking/locktorture.rst @@ -0,0 +1,181 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +============================================ +Funzionamento del test *Kernel Lock Torture* +============================================ + +CONFIG_LOCK_TORTURE_TEST +======================== + +L'opzione di configurazione CONFIG_LOCK_TORTURE_TEST fornisce un +modulo kernel che esegue delle verifiche che *torturano* le primitive di +sincronizzazione del kernel. Se dovesse servire, il modulo kernel, +'locktorture', può essere generato successivamente su un kernel che +volete verificare. Periodicamente le verifiche stampano messaggi tramite +``printk()`` e che quindi possono essere letti tramite ``dmesg`` (magari +filtrate l'output con ``grep "torture"``). La verifica inizia quando +il modulo viene caricato e termina quando viene rimosso. Questo +programma si basa sulle modalità di verifica di RCU tramite rcutorture. + +Questa verifica consiste nella creazione di un certo numero di thread +del kernel che acquisiscono un blocco e lo trattengono per una certa +quantità di tempo così da simulare diversi comportamenti nelle sezioni +critiche. La quantità di contese su un blocco può essere simulata +allargando la sezione critica e/o creando più thread. + + +Parametri del modulo +==================== + +Questo modulo ha i seguenti parametri: + + +Specifici di locktorture +------------------------ + +nwriters_stress + Numero di thread del kernel che stresseranno l'acquisizione + esclusiva dei blocchi (scrittori). Il valore di base è il + doppio del numero di processori attivi presenti. + +nreaders_stress + Numero di thread del kernel che stresseranno l'acquisizione + condivisa dei blocchi (lettori). Il valore di base è lo stesso + di nwriters_stress. Se l'utente non ha specificato + nwriters_stress, allora entrambe i valori corrisponderanno + al numero di processori attivi presenti. + +torture_type + Tipo di blocco da verificare. Di base, solo gli spinlock + verranno verificati. Questo modulo può verificare anche + i seguenti tipi di blocchi: + + - "lock_busted": + Simula un'incorretta implementazione del + blocco. + + - "spin_lock": + coppie di spin_lock() e spin_unlock(). + + - "spin_lock_irq": + coppie di spin_lock_irq() e spin_unlock_irq(). + + - "rw_lock": + coppie di rwlock read/write lock() e unlock(). + + - "rw_lock_irq": + copie di rwlock read/write lock_irq() e + unlock_irq(). + + - "mutex_lock": + coppie di mutex_lock() e mutex_unlock(). + + - "rtmutex_lock": + coppie di rtmutex_lock() e rtmutex_unlock(). + Il kernel deve avere CONFIG_RT_MUTEXES=y. + + - "rwsem_lock": + coppie di semafori read/write down() e up(). + + +Generici dell'ambiente di sviluppo 'torture' (RCU + locking) +------------------------------------------------------------ + +shutdown_secs + Numero di secondi prima che la verifica termini e il sistema + venga spento. Il valore di base è zero, il che disabilita + la possibilità di terminare e spegnere. Questa funzionalità + può essere utile per verifiche automatizzate. + +onoff_interval + Numero di secondi fra ogni tentativo di esecuzione di + un'operazione casuale di CPU-hotplug. Di base è zero, il + che disabilita la funzionalità di CPU-hotplug. Nei kernel + con CONFIG_HOTPLUG_CPU=n, locktorture si rifiuterà, senza + dirlo, di effettuare una qualsiasi operazione di + CPU-hotplug indipendentemente dal valore specificato in + onoff_interval. + +onoff_holdoff + Numero di secondi da aspettare prima di iniziare le + operazioni di CPU-hotplug. Normalmente questo verrebbe + usato solamente quando locktorture è compilato come parte + integrante del kernel ed eseguito automaticamente all'avvio, + in questo caso è utile perché permette di non confondere + l'avvio con i processori che vanno e vengono. Questo + parametro è utile sono se CONFIG_HOTPLUG_CPU è abilitato. + +stat_interval + Numero di secondi fra una stampa (printk()) delle + statistiche e l'altra. Di base, locktorture riporta le + statistiche ogni 60 secondi. Impostando l'intervallo a 0 + ha l'effetto di stampare le statistiche -solo- quando il + modulo viene rimosso. + +stutter + Durata della verifica prima di effettuare una pausa di + eguale durata. Di base "stutter=5", quindi si eseguono + verifiche e pause di (circa) cinque secondi. + L'impostazione di "stutter=0" fa si che la verifica + venga eseguita continuamente senza fermarsi. + +shuffle_interval + Il numero di secondi per cui un thread debba mantenere + l'affinità con un sottoinsieme di processori, di base è + 3 secondi. Viene usato assieme a test_no_idle_hz. + +verbose + Abilita le stampe di debug, via printk(). Di base è + abilitato. Queste informazioni aggiuntive sono per la + maggior parte relative ad errori di alto livello e resoconti + da parte dell'struttura 'torture'. + + +Statistiche +=========== + +Le statistiche vengono stampate secondo il seguente formato:: + + spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0 + (A) (B) (C) (D) (E) + + (A): tipo di lock sotto verifica -- parametro torture_type. + + (B): Numero di acquisizione del blocco in scrittura. Se si ha a che fare + con una primitiva di lettura/scrittura apparirà di seguito anche una + seconda voce "Reads" + + (C): Numero di volte che il blocco è stato acquisito + + (D): Numero minimo e massimo di volte che un thread ha fallito + nell'acquisire il blocco + + (E): valori true/false nel caso di errori durante l'acquisizione del blocco. + Questo dovrebbe dare un riscontro positivo -solo- se c'è un baco + nell'implementazione delle primitive di sincronizzazione. Altrimenti un + blocco non dovrebbe mai fallire (per esempio, spin_lock()). + Ovviamente lo stesso si applica per (C). Un semplice esempio è il tipo + "lock_busted". + +Uso +=== + +Il seguente script può essere utilizzato per verificare i blocchi:: + + #!/bin/sh + + modprobe locktorture + sleep 3600 + rmmod locktorture + dmesg | grep torture: + +L'output può essere manualmente ispezionato cercando il marcatore d'errore +"!!!". Ovviamente potreste voler creare degli script più elaborati che +verificano automaticamente la presenza di errori. Il comando "rmmod" forza la +stampa (usando printk()) di "SUCCESS", "FAILURE", oppure "RCU_HOTPLUG". I primi +due si piegano da soli, mentre l'ultimo indica che non stati trovati problemi di +sincronizzazione, tuttavia ne sono stati trovati in CPU-hotplug. + +Consultate anche: Documentation/translations/it_IT/RCU/torture.rst diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst new file mode 100644 index 00000000000000..1c7056283b9de5 --- /dev/null +++ b/Documentation/translations/it_IT/locking/locktypes.rst @@ -0,0 +1,547 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: ../disclaimer-ita.rst + +.. _it_kernel_hacking_locktypes: + +======================================== +Tipologie di blocco e le loro istruzioni +======================================== + +Introduzione +============ + +Il kernel fornisce un certo numero di primitive di blocco che possiamo dividere +in tre categorie: + + - blocchi ad attesa con sospensione + - blocchi locali per CPU + - blocchi ad attesa attiva + +Questo documento descrive questi tre tipi e fornisce istruzioni su come +annidarli, ed usarli su kernel PREEMPT_RT. + +Categorie di blocchi +==================== + +Blocchi ad attesa con sospensione +--------------------------------- + +I blocchi ad attesa con sospensione possono essere acquisiti solo in un contesti +dov'è possibile la prelazione. + +Diverse implementazioni permettono di usare try_lock() anche in altri contesti, +nonostante ciò è bene considerare anche la sicurezza dei corrispondenti +unlock(). Inoltre, vanno prese in considerazione anche le varianti di *debug* +di queste primitive. Insomma, non usate i blocchi ad attesa con sospensioni in +altri contesti a meno che proprio non vi siano alternative. + +In questa categoria troviamo: + + - mutex + - rt_mutex + - semaphore + - rw_semaphore + - ww_mutex + - percpu_rw_semaphore + +Nei kernel con PREEMPT_RT, i seguenti blocchi sono convertiti in blocchi ad +attesa con sospensione: + + - local_lock + - spinlock_t + - rwlock_t + +Blocchi locali per CPU +---------------------- + + - local_lock + +Su kernel non-PREEMPT_RT, le funzioni local_lock gestiscono le primitive di +disabilitazione di prelazione ed interruzioni. Al contrario di altri meccanismi, +la disabilitazione della prelazione o delle interruzioni sono puri meccanismi +per il controllo della concorrenza su una CPU e quindi non sono adatti per la +gestione della concorrenza inter-CPU. + +Blocchi ad attesa attiva +------------------------ + + - raw_spinlcok_t + - bit spinlocks + + Nei kernel non-PREEMPT_RT, i seguenti blocchi sono ad attesa attiva: + + - spinlock_t + - rwlock_t + +Implicitamente, i blocchi ad attesa attiva disabilitano la prelazione e le +funzioni lock/unlock hanno anche dei suffissi per gestire il livello di +protezione: + + =================== ========================================================================= + _bh() disabilita / abilita *bottom halves* (interruzioni software) + _irq() disabilita / abilita le interruzioni + _irqsave/restore() salva e disabilita le interruzioni / ripristina ed attiva le interruzioni + =================== ========================================================================= + +Semantica del proprietario +========================== + +Eccetto i semafori, i sopracitati tipi di blocchi hanno tutti una semantica +molto stringente riguardo al proprietario di un blocco: + + Il contesto (attività) che ha acquisito il blocco deve rilasciarlo + +I semafori rw_semaphores hanno un'interfaccia speciale che permette anche ai non +proprietari del blocco di rilasciarlo per i lettori. + +rtmutex +======= + +I blocchi a mutua esclusione RT (*rtmutex*) sono un sistema a mutua esclusione +con supporto all'ereditarietà della priorità (PI). + +Questo meccanismo ha delle limitazioni sui kernel non-PREEMPT_RT dovuti alla +prelazione e alle sezioni con interruzioni disabilitate. + +Chiaramente, questo meccanismo non può avvalersi della prelazione su una sezione +dove la prelazione o le interruzioni sono disabilitate; anche sui kernel +PREEMPT_RT. Tuttavia, i kernel PREEMPT_RT eseguono la maggior parte delle +sezioni in contesti dov'è possibile la prelazione, specialmente in contesti +d'interruzione (anche software). Questa conversione permette a spinlock_t e +rwlock_t di essere implementati usando rtmutex. + +semaphore +========= + +La primitiva semaphore implementa un semaforo con contatore. + +I semafori vengono spesso utilizzati per la serializzazione e l'attesa, ma per +nuovi casi d'uso si dovrebbero usare meccanismi diversi, come mutex e +completion. + +semaphore e PREEMPT_RT +---------------------- + +I kernel PREEMPT_RT non cambiano l'implementazione di semaphore perché non hanno +un concetto di proprietario, dunque impediscono a PREEMPT_RT d'avere +l'ereditarietà della priorità sui semafori. Un proprietario sconosciuto non può +ottenere una priorità superiore. Di consequenza, bloccarsi sui semafori porta +all'inversione di priorità. + + +rw_semaphore +============ + +Il blocco rw_semaphore è un meccanismo che permette più lettori ma un solo scrittore. + +Sui kernel non-PREEMPT_RT l'implementazione è imparziale, quindi previene +l'inedia dei processi scrittori. + +Questi blocchi hanno una semantica molto stringente riguardo il proprietario, ma +offre anche interfacce speciali che permettono ai processi non proprietari di +rilasciare un processo lettore. Queste interfacce funzionano indipendentemente +dalla configurazione del kernel. + +rw_semaphore e PREEMPT_RT +------------------------- + +I kernel PREEMPT_RT sostituiscono i rw_semaphore con un'implementazione basata +su rt_mutex, e questo ne modifica l'imparzialità: + + Dato che uno scrittore rw_semaphore non può assicurare la propria priorità ai + suoi lettori, un lettore con priorità più bassa che ha subito la prelazione + continuerà a trattenere il blocco, quindi porta all'inedia anche gli scrittori + con priorità più alta. Per contro, dato che i lettori possono garantire la + propria priorità agli scrittori, uno scrittore a bassa priorità che subisce la + prelazione vedrà la propria priorità alzata finché non rilascerà il blocco, e + questo preverrà l'inedia dei processi lettori a causa di uno scrittore. + + +local_lock +========== + +I local_lock forniscono nomi agli ambiti di visibilità delle sezioni critiche +protette tramite la disattivazione della prelazione o delle interruzioni. + +Sui kernel non-PREEMPT_RT le operazioni local_lock si traducono +nell'abilitazione o disabilitazione della prelazione o le interruzioni. + + =============================== ====================== + local_lock(&llock) preempt_disable() + local_unlock(&llock) preempt_enable() + local_lock_irq(&llock) local_irq_disable() + local_unlock_irq(&llock) local_irq_enable() + local_lock_irqsave(&llock) local_irq_save() + local_unlock_irqrestore(&llock) local_irq_restore() + =============================== ====================== + +Gli ambiti di visibilità con nome hanno due vantaggi rispetto alle primitive di +base: + + - Il nome del blocco permette di fare un'analisi statica, ed è anche chiaro su + cosa si applichi la protezione cosa che invece non si può fare con le + classiche primitive in quanto sono opache e senza alcun ambito di + visibilità. + + - Se viene abilitato lockdep, allora local_lock ottiene un lockmap che + permette di verificare la bontà della protezione. Per esempio, questo può + identificare i casi dove una funzione usa preempt_disable() come meccanismo + di protezione in un contesto d'interruzione (anche software). A parte + questo, lockdep_assert_held(&llock) funziona come tutte le altre primitive + di sincronizzazione. + +local_lock e PREEMPT_RT +------------------------- + +I kernel PREEMPT_RT sostituiscono local_lock con uno spinlock_t per CPU, quindi +ne cambia la semantica: + + - Tutte le modifiche a spinlock_t si applicano anche a local_lock + +L'uso di local_lock +------------------- + +I local_lock dovrebbero essere usati su kernel non-PREEMPT_RT quando la +disabilitazione della prelazione o delle interruzioni è il modo più adeguato per +gestire l'accesso concorrente a strutture dati per CPU. + +Questo meccanismo non è adatto alla protezione da prelazione o interruzione su +kernel PREEMPT_RT dato che verrà convertito in spinlock_t. + + +raw_spinlock_t e spinlock_t +=========================== + +raw_spinlock_t +-------------- + +I blocco raw_spinlock_t è un blocco ad attesa attiva su tutti i tipi di kernel, +incluso quello PREEMPT_RT. Usate raw_spinlock_t solo in sezioni critiche nel +cuore del codice, nella gestione delle interruzioni di basso livello, e in posti +dove è necessario disabilitare la prelazione o le interruzioni. Per esempio, per +accedere in modo sicuro lo stato dell'hardware. A volte, i raw_spinlock_t +possono essere usati quando la sezione critica è minuscola, per evitare gli +eccessi di un rtmutex. + +spinlock_t +---------- + +Il significato di spinlock_t cambia in base allo stato di PREEMPT_RT. + +Sui kernel non-PREEMPT_RT, spinlock_t si traduce in un raw_spinlock_t ed ha +esattamente lo stesso significato. + +spinlock_t e PREEMPT_RT +----------------------- + +Sui kernel PREEMPT_RT, spinlock_t ha un'implementazione dedicata che si basa +sull'uso di rt_mutex. Questo ne modifica il significato: + + - La prelazione non viene disabilitata. + + - I suffissi relativi alla interruzioni (_irq, _irqsave / _irqrestore) per le + operazioni spin_lock / spin_unlock non hanno alcun effetto sullo stato delle + interruzioni della CPU. + + - I suffissi relativi alle interruzioni software (_bh()) disabilitano i + relativi gestori d'interruzione. + + I kernel non-PREEMPT_RT disabilitano la prelazione per ottenere lo stesso effetto. + + I kernel PREEMPT_RT usano un blocco per CPU per la serializzazione, il che + permette di tenere attiva la prelazione. Il blocco disabilita i gestori + d'interruzione software e previene la rientranza vista la prelazione attiva. + +A parte quanto appena discusso, i kernel PREEMPT_RT preservano il significato +di tutti gli altri aspetti di spinlock_t: + + - Le attività che trattengono un blocco spinlock_t non migrano su altri + processori. Disabilitando la prelazione, i kernel non-PREEMPT_RT evitano la + migrazione. Invece, i kernel PREEMPT_RT disabilitano la migrazione per + assicurarsi che i puntatori a variabili per CPU rimangano validi anche + quando un'attività subisce la prelazione. + + - Lo stato di un'attività si mantiene durante le acquisizioni del blocco al + fine di garantire che le regole basate sullo stato delle attività si possano + applicare a tutte le configurazioni del kernel. I kernel non-PREEMPT_RT + lasciano lo stato immutato. Tuttavia, la funzionalità PREEMPT_RT deve + cambiare lo stato se l'attività si blocca durante l'acquisizione. Dunque, + salva lo stato attuale prima di bloccarsi ed il rispettivo risveglio lo + ripristinerà come nell'esempio seguente:: + + task->state = TASK_INTERRUPTIBLE + lock() + block() + task->saved_state = task->state + task->state = TASK_UNINTERRUPTIBLE + schedule() + lock wakeup + task->state = task->saved_state + + Altri tipi di risvegli avrebbero impostato direttamente lo stato a RUNNING, + ma in questo caso non avrebbe funzionato perché l'attività deve rimanere + bloccata fintanto che il blocco viene trattenuto. Quindi, lo stato salvato + viene messo a RUNNING quando il risveglio di un non-blocco cerca di + risvegliare un'attività bloccata in attesa del rilascio di uno spinlock. Poi, + quando viene completata l'acquisizione del blocco, il suo risveglio + ripristinerà lo stato salvato, in questo caso a RUNNING:: + + task->state = TASK_INTERRUPTIBLE + lock() + block() + task->saved_state = task->state + task->state = TASK_UNINTERRUPTIBLE + schedule() + non lock wakeup + task->saved_state = TASK_RUNNING + + lock wakeup + task->state = task->saved_state + + Questo garantisce che il vero risveglio non venga perso. + +rwlock_t +======== + +Il blocco rwlock_t è un meccanismo che permette più lettori ma un solo scrittore. + +Sui kernel non-PREEMPT_RT questo è un blocco ad attesa e per i suoi suffissi si +applicano le stesse regole per spinlock_t. La sua implementazione è imparziale, +quindi previene l'inedia dei processi scrittori. + +rwlock_t e PREEMPT_RT +--------------------- + +Sui kernel PREEMPT_RT rwlock_t ha un'implementazione dedicata che si basa +sull'uso di rt_mutex. Questo ne modifica il significato: + + - Tutte le modifiche fatte a spinlock_t si applicano anche a rwlock_t. + + - Dato che uno scrittore rw_semaphore non può assicurare la propria priorità ai + suoi lettori, un lettore con priorità più bassa che ha subito la prelazione + continuerà a trattenere il blocco, quindi porta all'inedia anche gli + scrittori con priorità più alta. Per contro, dato che i lettori possono + garantire la propria priorità agli scrittori, uno scrittore a bassa priorità + che subisce la prelazione vedrà la propria priorità alzata finché non + rilascerà il blocco, e questo preverrà l'inedia dei processi lettori a causa + di uno scrittore. + + +Precisazioni su PREEMPT_RT +========================== + +local_lock su RT +---------------- + +Sui kernel PREEMPT_RT Ci sono alcune implicazioni dovute alla conversione di +local_lock in un spinlock_t. Per esempio, su un kernel non-PREEMPT_RT il +seguente codice funzionerà come ci si aspetta:: + + local_lock_irq(&local_lock); + raw_spin_lock(&lock); + +ed è equivalente a:: + + raw_spin_lock_irq(&lock); + +Ma su un kernel PREEMPT_RT questo codice non funzionerà perché local_lock_irq() +si traduce in uno spinlock_t per CPU che non disabilita né le interruzioni né la +prelazione. Il seguente codice funzionerà su entrambe i kernel con o senza +PREEMPT_RT:: + + local_lock_irq(&local_lock); + spin_lock(&lock); + +Un altro dettaglio da tenere a mente con local_lock è che ognuno di loro ha un +ambito di protezione ben preciso. Dunque, la seguente sostituzione è errate:: + + + func1() + { + local_irq_save(flags); -> local_lock_irqsave(&local_lock_1, flags); + func3(); + local_irq_restore(flags); -> local_unlock_irqrestore(&local_lock_1, flags); + } + + func2() + { + local_irq_save(flags); -> local_lock_irqsave(&local_lock_2, flags); + func3(); + local_irq_restore(flags); -> local_unlock_irqrestore(&local_lock_2, flags); + } + + func3() + { + lockdep_assert_irqs_disabled(); + access_protected_data(); + } + +Questo funziona correttamente su un kernel non-PREEMPT_RT, ma su un kernel +PREEMPT_RT local_lock_1 e local_lock_2 sono distinti e non possono serializzare +i chiamanti di func3(). L'*assert* di lockdep verrà attivato su un kernel +PREEMPT_RT perché local_lock_irqsave() non disabilita le interruzione a casa +della specifica semantica di spinlock_t in PREEMPT_RT. La corretta sostituzione +è:: + + func1() + { + local_irq_save(flags); -> local_lock_irqsave(&local_lock, flags); + func3(); + local_irq_restore(flags); -> local_unlock_irqrestore(&local_lock, flags); + } + + func2() + { + local_irq_save(flags); -> local_lock_irqsave(&local_lock, flags); + func3(); + local_irq_restore(flags); -> local_unlock_irqrestore(&local_lock, flags); + } + + func3() + { + lockdep_assert_held(&local_lock); + access_protected_data(); + } + +spinlock_t e rwlock_t +--------------------- + +Ci sono alcune conseguenze di cui tener conto dal cambiamento di semantica di +spinlock_t e rwlock_t sui kernel PREEMPT_RT. Per esempio, sui kernel non +PREEMPT_RT il seguente codice funziona come ci si aspetta:: + + local_irq_disable(); + spin_lock(&lock); + +ed è equivalente a:: + + spin_lock_irq(&lock); + +Lo stesso vale per rwlock_t e le varianti con _irqsave(). + +Sui kernel PREEMPT_RT questo codice non funzionerà perché gli rtmutex richiedono +un contesto con la possibilità di prelazione. Al suo posto, usate +spin_lock_irq() o spin_lock_irqsave() e le loro controparti per il rilascio. I +kernel PREEMPT_RT offrono un meccanismo local_lock per i casi in cui la +disabilitazione delle interruzioni ed acquisizione di un blocco devono rimanere +separati. Acquisire un local_lock àncora un processo ad una CPU permettendo cose +come un'acquisizione di un blocco con interruzioni disabilitate per singola CPU. + +Il tipico scenario è quando si vuole proteggere una variabile di processore nel +contesto di un thread:: + + + struct foo *p = get_cpu_ptr(&var1); + + spin_lock(&p->lock); + p->count += this_cpu_read(var2); + +Questo codice è corretto su un kernel non-PREEMPT_RT, ma non lo è su un +PREEMPT_RT. La modifica della semantica di spinlock_t su PREEMPT_RT non permette +di acquisire p->lock perché, implicitamente, get_cpu_ptr() disabilita la +prelazione. La seguente sostituzione funzionerà su entrambe i kernel:: + + struct foo *p; + + migrate_disable(); + p = this_cpu_ptr(&var1); + spin_lock(&p->lock); + p->count += this_cpu_read(var2); + +La funzione migrate_disable() assicura che il processo venga tenuto sulla CPU +corrente, e di conseguenza garantisce che gli accessi per-CPU alle variabili var1 e +var2 rimangano sulla stessa CPU fintanto che il processo rimane prelabile. + +La sostituzione con migrate_disable() non funzionerà nel seguente scenario:: + + func() + { + struct foo *p; + + migrate_disable(); + p = this_cpu_ptr(&var1); + p->val = func2(); + +Questo non funziona perché migrate_disable() non protegge dal ritorno da un +processo che aveva avuto il diritto di prelazione. Una sostituzione più adatta +per questo caso è:: + + func() + { + struct foo *p; + + local_lock(&foo_lock); + p = this_cpu_ptr(&var1); + p->val = func2(); + +Su un kernel non-PREEMPT_RT, questo codice protegge dal rientro disabilitando la +prelazione. Su un kernel PREEMPT_RT si ottiene lo stesso risultato acquisendo lo +spinlock di CPU. + +raw_spinlock_t su RT +-------------------- + +Acquisire un raw_spinlock_t disabilita la prelazione e possibilmente anche le +interruzioni, quindi la sezione critica deve evitare di acquisire uno spinlock_t +o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di +memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente:: + + raw_spin_lock(&lock); + p = kmalloc(sizeof(*p), GFP_ATOMIC); + +Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di +memoria può essere oggetto di prelazione e quindi non può essere chiamato in un +contesto atomico. Tuttavia, si può chiamare l'allocatore di memoria quando si +trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel +PREEMPT_RT:: + + spin_lock(&lock); + p = kmalloc(sizeof(*p), GFP_ATOMIC); + + +bit spinlocks +------------- + +I kernel PREEMPT_RT non possono sostituire i bit spinlock perché un singolo bit +è troppo piccolo per farci stare un rtmutex. Dunque, la semantica dei bit +spinlock è mantenuta anche sui kernel PREEMPT_RT. Quindi, le precisazioni fatte +per raw_spinlock_t valgono anche qui. + +In PREEMPT_RT, alcuni bit spinlock sono sostituiti con normali spinlock_t usando +condizioni di preprocessore in base a dove vengono usati. Per contro, questo non +serve quando si sostituiscono gli spinlock_t. Invece, le condizioni poste sui +file d'intestazione e sul cuore dell'implementazione della sincronizzazione +permettono al compilatore di effettuare la sostituzione in modo trasparente. + + +Regole d'annidamento dei tipi di blocchi +======================================== + +Le regole principali sono: + + - I tipi di blocco appartenenti alla stessa categoria possono essere annidati + liberamente a patto che si rispetti l'ordine di blocco al fine di evitare + stalli. + + - I blocchi con sospensione non possono essere annidati in blocchi del tipo + CPU locale o ad attesa attiva + + - I blocchi ad attesa attiva e su CPU locale possono essere annidati nei + blocchi ad attesa con sospensione. + + - I blocchi ad attesa attiva possono essere annidati in qualsiasi altro tipo. + +Queste limitazioni si applicano ad entrambe i kernel con o senza PREEMPT_RT. + +Il fatto che un kernel PREEMPT_RT cambi i blocchi spinlock_t e rwlock_t dal tipo +ad attesa attiva a quello con sospensione, e che sostituisca local_lock con uno +spinlock_t per CPU, significa che non possono essere acquisiti quando si è in un +blocco raw_spinlock. Ne consegue il seguente ordine d'annidamento: + + 1) blocchi ad attesa con sospensione + 2) spinlock_t, rwlock_t, local_lock + 3) raw_spinlock_t e bit spinlocks + +Se queste regole verranno violate, allora lockdep se ne accorgerà e questo sia +con o senza PREEMPT_RT. diff --git a/Documentation/translations/it_IT/networking/netdev-FAQ.rst b/Documentation/translations/it_IT/networking/netdev-FAQ.rst deleted file mode 100644 index 8a1e049585c036..00000000000000 --- a/Documentation/translations/it_IT/networking/netdev-FAQ.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. include:: ../disclaimer-ita.rst - -:Original: :ref:`Documentation/process/maintainer-netdev.rst ` - -.. _it_netdev-FAQ: - -========== -netdev FAQ -========== - -.. 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 index 5f244e16f51148..284a75ac19f8e1 100644 --- a/Documentation/translations/it_IT/process/coding-style.rst +++ b/Documentation/translations/it_IT/process/coding-style.rst @@ -575,9 +575,9 @@ due parti ``err_free_bar:`` e ``err_free_foo:``: .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; @@ -671,7 +671,7 @@ segue nel vostro file .emacs: (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) diff --git a/Documentation/translations/it_IT/subsystem-apis.rst b/Documentation/translations/it_IT/subsystem-apis.rst new file mode 100644 index 00000000000000..d179af60c26da4 --- /dev/null +++ b/Documentation/translations/it_IT/subsystem-apis.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================================== +Documentazione dei sottosistemi del kernel +========================================== + +In questa parte della documentazione si entra nel dettaglio di come funzionano +i sottosistemi specifici del kernel dal punto di vista di uno sviluppatore del +kernel. Molte delle informazioni qui contenute provengono direttamente dai +sorgenti del kernel, con aggiunte di materiale dove è necessario (anche se +talora *non* è stato aggiunto tutto ciò che era necessario). + +Sottosistemi principali +----------------------- + +.. toctree:: + :maxdepth: 1 + + core-api/index + +Interfacce uomo-macchina +------------------------ + +.. toctree:: + :maxdepth: 1 + + +Interfacce di rete +------------------ + +.. toctree:: + :maxdepth: 1 + +Interfacce per l'archiviazione +------------------------------ + +.. toctree:: + :maxdepth: 1 + + +Interfacce varie +---------------- + +.. toctree:: + :maxdepth: 1 + + i2c/index diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index a0261ba5b9026c..a3727476437119 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -604,9 +604,9 @@ Normalmente la solución para esto es dividirlo en dos etiquetas de error .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; @@ -698,7 +698,7 @@ sanos. Para hacer esto último, puede pegar lo siguiente en su archivo (c-offsets-alist . ( (arglist-close . c-lineup-arglist-tabs-only) (arglist-cont-nonempty . - (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) + (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only)) (arglist-intro . +) (brace-list-intro . +) (c . c-lineup-C-comments) diff --git a/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst index c261b428b3f0e7..7d4d694967c736 100644 --- a/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/sp_SP/process/embargoed-hardware-issues.rst @@ -273,7 +273,7 @@ revelada involucrada. La lista de embajadores actuales: IBM Power Anton Blanchard IBM Z Christian Borntraeger Intel Tony Luck - Qualcomm Trilok Soni + Qualcomm Trilok Soni Samsung Javier González Microsoft James Morris diff --git a/Documentation/translations/sp_SP/process/researcher-guidelines.rst b/Documentation/translations/sp_SP/process/researcher-guidelines.rst index 462b3290b7b835..deccc908a68de3 100644 --- a/Documentation/translations/sp_SP/process/researcher-guidelines.rst +++ b/Documentation/translations/sp_SP/process/researcher-guidelines.rst @@ -147,4 +147,4 @@ Si no se puede encontrar a nadie para revisar internamente los parches y necesit ayuda para encontrar a esa persona, o si tiene alguna otra pregunta relacionada con este documento y las expectativas de la comunidad de desarrolladores, por favor contacte con la lista de correo privada Technical Advisory Board: -. +. diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst index 17b9949d9b4357..da2745464ece45 100644 --- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst @@ -344,7 +344,7 @@ debugfs接口 :ref:`sysfs接口`。 DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, -``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 +``schemes``, ``monitor_on_DEPRECATED``, ``kdamond_pid``, ``mk_contexts`` 和 ``rm_contexts`` under its debugfs directory, ``/damon/``. @@ -521,15 +521,15 @@ DAMON导出了八个文件, ``attrs``, ``target_ids``, ``init_regions``, 开关 ---- -除非你明确地启动监测，否则如上所述的文件设置不会产生效果。你可以通过写入和读取 ``monitor_on`` +除非你明确地启动监测，否则如上所述的文件设置不会产生效果。你可以通过写入和读取 ``monitor_on_DEPRECATED`` 文件来启动、停止和检查监测的当前状态。写入 ``on`` 该文件可以启动对有属性的目标的监测。写入 ``off`` 该文件则停止这些目标。如果每个目标进程被终止，DAMON也会停止。下面的示例命令开启、关 闭和检查DAMON的状态:: # cd /damon - # echo on > monitor_on - # echo off > monitor_on - # cat monitor_on + # echo on > monitor_on_DEPRECATED + # echo off > monitor_on_DEPRECATED + # cat monitor_on_DEPRECATED off 请注意，当监测开启时，你不能写到上述的debugfs文件。如果你在DAMON运行时写到这些文件，将会返 @@ -543,11 +543,11 @@ DAMON通过一个叫做kdamond的内核线程来进行请求监测。你可以 得该线程的 ``pid`` 。当监测被 ``关闭`` 时，读取该文件不会返回任何信息:: # cd /damon - # cat monitor_on + # cat monitor_on_DEPRECATED off # cat kdamond_pid none - # echo on > monitor_on + # echo on > monitor_on_DEPRECATED # cat kdamond_pid 18594 @@ -574,7 +574,7 @@ DAMON通过一个叫做kdamond的内核线程来进行请求监测。你可以 # ls foo # ls: cannot access 'foo': No such file or directory -注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on`` 文件只在根目录下。 +注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on_DEPRECATED`` 文件只在根目录下。 监测结果的监测点 @@ -583,9 +583,9 @@ DAMON通过一个叫做kdamond的内核线程来进行请求监测。你可以 DAMON通过一个tracepoint ``damon:damon_aggregated`` 提供监测结果. 当监测开启时，你可 以记录追踪点事件，并使用追踪点支持工具如perf显示结果。比如说:: - # echo on > monitor_on + # echo on > monitor_on_DEPRECATED # perf record -e damon:damon_aggregated & # sleep 5 # kill 9 $(pidof perf) - # echo off > monitor_on + # echo off > monitor_on_DEPRECATED # perf script diff --git a/Documentation/translations/zh_CN/dev-tools/kasan.rst b/Documentation/translations/zh_CN/dev-tools/kasan.rst index 8fdb20c9665b4b..2b1e8f74904b01 100644 --- a/Documentation/translations/zh_CN/dev-tools/kasan.rst +++ b/Documentation/translations/zh_CN/dev-tools/kasan.rst @@ -137,7 +137,7 @@ KASAN受到通用 ``panic_on_warn`` 命令行参数的影响。当它被启用 典型的KASAN报告如下所示:: ================================================================== - BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [kasan_test] Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 @@ -147,8 +147,8 @@ KASAN受到通用 ``panic_on_warn`` 命令行参数的影响。当它被启用 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] + kmalloc_oob_right+0xa8/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -168,8 +168,8 @@ KASAN受到通用 ``panic_on_warn`` 命令行参数的影响。当它被启用 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] + kmalloc_oob_right+0x56/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -421,15 +421,15 @@ KASAN连接到vmap基础架构以懒清理未使用的影子内存。 当由于 ``kmalloc`` 失败而导致测试失败时:: - # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 + # kmalloc_large_oob_right: ASSERTION FAILED at mm/kasan/kasan_test.c:245 Expected ptr is not null, but is - not ok 4 - kmalloc_large_oob_right + not ok 5 - kmalloc_large_oob_right 当由于缺少KASAN报告而导致测试失败时:: - # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + # kmalloc_double_kzfree: EXPECTATION FAILED at mm/kasan/kasan_test.c:709 KASAN failure expected in "kfree_sensitive(ptr)", but none occurred - not ok 44 - kmalloc_double_kzfree + not ok 28 - kmalloc_double_kzfree 最后打印所有KASAN测试的累积状态。成功:: @@ -445,7 +445,7 @@ KASAN连接到vmap基础架构以懒清理未使用的影子内存。 1. 可加载模块 启用 ``CONFIG_KUNIT`` 后，KASAN-KUnit测试可以构建为可加载模块，并通过使用 - ``insmod`` 或 ``modprobe`` 加载 ``test_kasan.ko`` 来运行。 + ``insmod`` 或 ``modprobe`` 加载 ``kasan_test.ko`` 来运行。 2. 内置 diff --git a/Documentation/translations/zh_CN/power/opp.rst b/Documentation/translations/zh_CN/power/opp.rst index 8d6e3f6f62024e..7470fa2d4c43af 100644 --- a/Documentation/translations/zh_CN/power/opp.rst +++ b/Documentation/translations/zh_CN/power/opp.rst @@ -274,7 +274,7 @@ dev_pm_opp_get_opp_count { /* 做一些事情 */ num_available = dev_pm_opp_get_opp_count(dev); - speeds = kzalloc(sizeof(u32) * num_available, GFP_KERNEL); + speeds = kcalloc(num_available, sizeof(u32), GFP_KERNEL); /* 按升序填充表 */ freq = 0; while (!IS_ERR(opp = dev_pm_opp_find_freq_ceil(dev, &freq))) { diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index fa28ef0a7fee81..3bc2810b151d46 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -523,9 +523,9 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; diff --git a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst index cf5f1fca3d9247..c90ecb557811ac 100644 --- a/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_CN/process/embargoed-hardware-issues.rst @@ -177,7 +177,7 @@ CVE分配 AMD Tom Lendacky IBM Intel Tony Luck - Qualcomm Trilok Soni + Qualcomm Trilok Soni Microsoft Sasha Levin VMware diff --git a/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst index 6dee719a32ea61..7464279f9b7de0 100644 --- a/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst +++ b/Documentation/translations/zh_TW/admin-guide/mm/damon/usage.rst @@ -344,7 +344,7 @@ debugfs接口 :ref:`sysfs接口`。 DAMON導出了八個文件, ``attrs``, ``target_ids``, ``init_regions``, -``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` 和 +``schemes``, ``monitor_on_DEPRECATED``, ``kdamond_pid``, ``mk_contexts`` 和 ``rm_contexts`` under its debugfs directory, ``/damon/``. @@ -521,15 +521,15 @@ DAMON導出了八個文件, ``attrs``, ``target_ids``, ``init_regions``, 開關 ---- -除非你明確地啓動監測，否則如上所述的文件設置不會產生效果。你可以通過寫入和讀取 ``monitor_on`` +除非你明確地啓動監測，否則如上所述的文件設置不會產生效果。你可以通過寫入和讀取 ``monitor_on_DEPRECATED`` 文件來啓動、停止和檢查監測的當前狀態。寫入 ``on`` 該文件可以啓動對有屬性的目標的監測。寫入 ``off`` 該文件則停止這些目標。如果每個目標進程被終止，DAMON也會停止。下面的示例命令開啓、關 閉和檢查DAMON的狀態:: # cd /damon - # echo on > monitor_on - # echo off > monitor_on - # cat monitor_on + # echo on > monitor_on_DEPRECATED + # echo off > monitor_on_DEPRECATED + # cat monitor_on_DEPRECATED off 請注意，當監測開啓時，你不能寫到上述的debugfs文件。如果你在DAMON運行時寫到這些文件，將會返 @@ -543,11 +543,11 @@ DAMON通過一個叫做kdamond的內核線程來進行請求監測。你可以 得該線程的 ``pid`` 。當監測被 ``關閉`` 時，讀取該文件不會返回任何信息:: # cd /damon - # cat monitor_on + # cat monitor_on_DEPRECATED off # cat kdamond_pid none - # echo on > monitor_on + # echo on > monitor_on_DEPRECATED # cat kdamond_pid 18594 @@ -574,7 +574,7 @@ DAMON通過一個叫做kdamond的內核線程來進行請求監測。你可以 # ls foo # ls: cannot access 'foo': No such file or directory -注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on`` 文件只在根目錄下。 +注意， ``mk_contexts`` 、 ``rm_contexts`` 和 ``monitor_on_DEPRECATED`` 文件只在根目錄下。 監測結果的監測點 @@ -583,10 +583,10 @@ DAMON通過一個叫做kdamond的內核線程來進行請求監測。你可以 DAMON通過一個tracepoint ``damon:damon_aggregated`` 提供監測結果. 當監測開啓時，你可 以記錄追蹤點事件，並使用追蹤點支持工具如perf顯示結果。比如說:: - # echo on > monitor_on + # echo on > monitor_on_DEPRECATED # perf record -e damon:damon_aggregated & # sleep 5 # kill 9 $(pidof perf) - # echo off > monitor_on + # echo off > monitor_on_DEPRECATED # perf script diff --git a/Documentation/translations/zh_TW/dev-tools/kasan.rst b/Documentation/translations/zh_TW/dev-tools/kasan.rst index 979eb84bc58f1a..ed342e67d8ed02 100644 --- a/Documentation/translations/zh_TW/dev-tools/kasan.rst +++ b/Documentation/translations/zh_TW/dev-tools/kasan.rst @@ -137,7 +137,7 @@ KASAN受到通用 ``panic_on_warn`` 命令行參數的影響。當它被啓用 典型的KASAN報告如下所示:: ================================================================== - BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [test_kasan] + BUG: KASAN: slab-out-of-bounds in kmalloc_oob_right+0xa8/0xbc [kasan_test] Write of size 1 at addr ffff8801f44ec37b by task insmod/2760 CPU: 1 PID: 2760 Comm: insmod Not tainted 4.19.0-rc3+ #698 @@ -147,8 +147,8 @@ KASAN受到通用 ``panic_on_warn`` 命令行參數的影響。當它被啓用 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] + kmalloc_oob_right+0xa8/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -168,8 +168,8 @@ KASAN受到通用 ``panic_on_warn`` 命令行參數的影響。當它被啓用 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] + kmalloc_oob_right+0x56/0xbc [kasan_test] + kmalloc_tests_init+0x16/0x700 [kasan_test] do_one_initcall+0xa5/0x3ae do_init_module+0x1b6/0x547 load_module+0x75df/0x8070 @@ -421,15 +421,15 @@ KASAN連接到vmap基礎架構以懶清理未使用的影子內存。 當由於 ``kmalloc`` 失敗而導致測試失敗時:: - # kmalloc_large_oob_right: ASSERTION FAILED at lib/test_kasan.c:163 + # kmalloc_large_oob_right: ASSERTION FAILED at mm/kasan/kasan_test.c:245 Expected ptr is not null, but is - not ok 4 - kmalloc_large_oob_right + not ok 5 - kmalloc_large_oob_right 當由於缺少KASAN報告而導致測試失敗時:: - # kmalloc_double_kzfree: EXPECTATION FAILED at lib/test_kasan.c:974 + # kmalloc_double_kzfree: EXPECTATION FAILED at mm/kasan/kasan_test.c:709 KASAN failure expected in "kfree_sensitive(ptr)", but none occurred - not ok 44 - kmalloc_double_kzfree + not ok 28 - kmalloc_double_kzfree 最後打印所有KASAN測試的累積狀態。成功:: @@ -445,7 +445,7 @@ KASAN連接到vmap基礎架構以懶清理未使用的影子內存。 1. 可加載模塊 啓用 ``CONFIG_KUNIT`` 後，KASAN-KUnit測試可以構建爲可加載模塊，並通過使用 - ``insmod`` 或 ``modprobe`` 加載 ``test_kasan.ko`` 來運行。 + ``insmod`` 或 ``modprobe`` 加載 ``kasan_test.ko`` 來運行。 2. 內置 diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index f11dbb65ca2158..c7ac504f6f40ce 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -526,9 +526,9 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供 .. code-block:: c - err_free_bar: + err_free_bar: kfree(foo->bar); - err_free_foo: + err_free_foo: kfree(foo); return ret; diff --git a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst index 3cce7db2ab7ede..93d21fd8891003 100644 --- a/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst +++ b/Documentation/translations/zh_TW/process/embargoed-hardware-issues.rst @@ -180,7 +180,7 @@ CVE分配 AMD Tom Lendacky IBM Intel Tony Luck - Qualcomm Trilok Soni + Qualcomm Trilok Soni Microsoft Sasha Levin VMware diff --git a/Documentation/usb/functionfs.rst b/Documentation/usb/functionfs.rst index a3054bea38f3cd..d05a775bc45bc0 100644 --- a/Documentation/usb/functionfs.rst +++ b/Documentation/usb/functionfs.rst @@ -2,6 +2,9 @@ How FunctionFS works ==================== +Overview +======== + From kernel point of view it is just a composite function with some unique behaviour. It may be added to an USB configuration only after the user space driver has registered by writing descriptors and @@ -66,3 +69,36 @@ have been written to their ep0's. Conversely, the gadget is unregistered after the first USB function closes its endpoints. + +DMABUF interface +================ + +FunctionFS additionally supports a DMABUF based interface, where the +userspace can attach DMABUF objects (externally created) to an endpoint, +and subsequently use them for data transfers. + +A userspace application can then use this interface to share DMABUF +objects between several interfaces, allowing it to transfer data in a +zero-copy fashion, for instance between IIO and the USB stack. + +As part of this interface, three new IOCTLs have been added. These three +IOCTLs have to be performed on a data endpoint (ie. not ep0). They are: + + ``FUNCTIONFS_DMABUF_ATTACH(int)`` + Attach the DMABUF object, identified by its file descriptor, to the + data endpoint. Returns zero on success, and a negative errno value + on error. + + ``FUNCTIONFS_DMABUF_DETACH(int)`` + Detach the given DMABUF object, identified by its file descriptor, + from the data endpoint. Returns zero on success, and a negative + errno value on error. Note that closing the endpoint's file + descriptor will automatically detach all attached DMABUFs. + + ``FUNCTIONFS_DMABUF_TRANSFER(struct usb_ffs_dmabuf_transfer_req *)`` + Enqueue the previously attached DMABUF to the transfer queue. + The argument is a structure that packs the DMABUF's file descriptor, + the size in bytes to transfer (which should generally correspond to + the size of the DMABUF), and a 'flags' field which is unused + for now. Returns zero on success, and a negative errno value on + error. diff --git a/Documentation/usb/gadget-testing.rst b/Documentation/usb/gadget-testing.rst index 8cd62c466d20aa..b086c7ab72f065 100644 --- a/Documentation/usb/gadget-testing.rst +++ b/Documentation/usb/gadget-testing.rst @@ -206,6 +206,14 @@ the standard procedure for using FunctionFS (mount it, run the userspace process which implements the function proper). The gadget should be enabled by writing a suitable string to usb_gadget//UDC. +The FFS function provides just one attribute in its function directory: + + ready + +The attribute is read-only and signals if the function is ready (1) to be +used, E.G. if userspace has written descriptors and strings to ep0, so +the gadget can be enabled. + Testing the FFS function ------------------------ @@ -448,17 +456,17 @@ Function-specific configfs interface The function name to use when creating the function directory is "ncm". The NCM function provides these attributes in its function directory: - =============== ================================================== - ifname network device interface name associated with this - function instance - qmult queue length multiplier for high and super speed - host_addr MAC address of host's end of this - Ethernet over USB link - dev_addr MAC address of device's end of this - Ethernet over USB link - max_segment_size Segment size required for P2P connections. This - will set MTU to (max_segment_size - 14 bytes) - =============== ================================================== + ======================= ================================================== + ifname network device interface name associated with this + function instance + qmult queue length multiplier for high and super speed + host_addr MAC address of host's end of this + Ethernet over USB link + dev_addr MAC address of device's end of this + Ethernet over USB link + max_segment_size Segment size required for P2P connections. This + will set MTU to 14 bytes + ======================= ================================================== and after creating the functions/ncm. they contain default values: qmult is 5, dev_addr and host_addr are randomly selected. diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/userspace-api/gpio/chardev.rst new file mode 100644 index 00000000000000..c58dd9771ac9c0 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev.rst @@ -0,0 +1,116 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +GPIO Character Device Userspace API +=================================== + +This is latest version (v2) of the character device API, as defined in +``include/uapi/linux/gpio.h.`` + +First added in 5.10. + +.. note:: + Do NOT abuse userspace APIs to control hardware that has proper kernel + drivers. There may already be a driver for your use case, and an existing + kernel driver is sure to provide a superior solution to bitbashing + from userspace. + + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing + kernel wheels in userspace. + + Similarly, for multi-function lines there may be other subsystems, such as + Documentation/spi/index.rst, Documentation/i2c/index.rst, + Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that + provide suitable drivers and APIs for your hardware. + +Basic examples using the character device API can be found in ``tools/gpio/*``. + +The API is based around two major objects, the :ref:`gpio-v2-chip` and the +:ref:`gpio-v2-line-request`. + +.. _gpio-v2-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using gpio-v2-get-line-ioctl.rst +and the resulting line request is used to access the GPIO chip's lines or +monitor the lines for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line + Get Chip Info + Get Line Info + Watch Line Info + Unwatch Line Info + Read Line Info Changed Events + +.. _gpio-v2-line-request: + +Line Request +============ + +Line requests are created by gpio-v2-get-line-ioctl.rst and provide +access to a set of requested lines. The line request is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +Within this documentation, the line request file descriptor is referred to +as ``req_fd``. + +Operations +---------- + +The following operations may be performed on the line request: + +.. toctree:: + :titlesonly: + + Get Line Values + Set Line Values + Read Line Edge Events + Reconfigure Lines + +Types +===== + +This section contains the structs and enums that are referenced by the API v2, +as defined in ``include/uapi/linux/gpio.h``. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpio_v2_line_attr_id + gpio_v2_line_attribute + gpio_v2_line_changed_type + gpio_v2_line_config + gpio_v2_line_config_attribute + gpio_v2_line_event + gpio_v2_line_event_id + gpio_v2_line_flag + gpio_v2_line_info + gpio_v2_line_info_changed + gpio_v2_line_request + gpio_v2_line_values + gpiochip_info + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/chardev_v1.rst b/Documentation/userspace-api/gpio/chardev_v1.rst new file mode 100644 index 00000000000000..67124b1d048794 --- /dev/null +++ b/Documentation/userspace-api/gpio/chardev_v1.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================== +GPIO Character Device Userspace API (v1) +======================================== + +.. warning:: + This API is obsoleted by chardev.rst (v2). + + New developments should use the v2 API, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. The v2 API is a functional superset of the v1 API so any + v1 call can be directly translated to a v2 equivalent. + + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. + +First added in 4.8. + +The API is based around three major objects, the :ref:`gpio-v1-chip`, the +:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`. + +Where "line event" is used in this document it refers to the request that can +monitor a line for edge events, not the edge events themselves. + +.. _gpio-v1-chip: + +Chip +==== + +The Chip represents a single GPIO chip and is exposed to userspace using device +files of the form ``/dev/gpiochipX``. + +Each chip supports a number of GPIO lines, +:c:type:`chip.lines`. Lines on the chip are identified by an +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`. + +Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst +and the resulting line handle is used to access the GPIO chip's lines, or +gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor +a GPIO line for edge events. + +Within this documentation, the file descriptor returned by calling `open()` +on the GPIO device file is referred to as ``chip_fd``. + +Operations +---------- + +The following operations may be performed on the chip: + +.. toctree:: + :titlesonly: + + Get Line Handle + Get Line Event + Get Chip Info + Get Line Info + Watch Line Info + Unwatch Line Info + Read Line Info Changed Events + +.. _gpio-v1-line-handle: + +Line Handle +=========== + +Line handles are created by gpio-get-linehandle-ioctl.rst and provide +access to a set of requested lines. The line handle is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +Within this documentation, the line handle file descriptor is referred to +as ``handle_fd``. + +Operations +---------- + +The following operations may be performed on the line handle: + +.. toctree:: + :titlesonly: + + Get Line Values + Set Line Values + Reconfigure Lines + +.. _gpio-v1-line-event: + +Line Event +========== + +Line events are created by gpio-get-lineevent-ioctl.rst and provide +access to a requested line. The line event is exposed to userspace +via the anonymous file descriptor returned in +:c:type:`request.fd` by gpio-get-lineevent-ioctl.rst. + +Within this documentation, the line event file descriptor is referred to +as ``event_fd``. + +Operations +---------- + +The following operations may be performed on the line event: + +.. toctree:: + :titlesonly: + + Get Line Value + Read Line Edge Events + +Types +===== + +This section contains the structs that are referenced by the ABI v1. + +The :c:type:`struct gpiochip_info` is common to ABI v1 and v2. + +.. kernel-doc:: include/uapi/linux/gpio.h + :identifiers: + gpioevent_data + gpioevent_request + gpiohandle_config + gpiohandle_data + gpiohandle_request + gpioline_info + gpioline_info_changed + +.. toctree:: + :hidden: + + error-codes diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst new file mode 100644 index 00000000000000..6bf2948990cdcc --- /dev/null +++ b/Documentation/userspace-api/gpio/error-codes.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _gpio_errors: + +******************* +GPIO Error Codes +******************* + +.. _gpio-errors: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: Common GPIO error codes + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EAGAIN`` (aka ``EWOULDBLOCK``) + + - The device was opened in non-blocking mode and a read can't + be performed as there is no data available. + + - - ``EBADF`` + + - The file descriptor is not valid. + + - - ``EBUSY`` + + - The ioctl can't be handled because the device is busy. Typically + returned when an ioctl attempts something that would require the + usage of a resource that was already allocated. The ioctl must not + be retried without performing another action to fix the problem + first. + + - - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probably + caused by an invalid pointer reference. + + - - ``EINVAL`` + + - One or more of the ioctl parameters are invalid or out of the + allowed range. This is a widely used error code. + + - - ``ENODEV`` + + - Device not found or was removed. + + - - ``ENOMEM`` + + - There's not enough memory to handle the desired operation. + + - - ``EPERM`` + + - Permission denied. Typically returned in response to an attempt + to perform an action incompatible with the current line + configuration. + + - - ``EIO`` + + - I/O error. Typically returned when there are problems communicating + with a hardware device or requesting features that hardware does not + support. This could indicate broken or flaky hardware. + It's a 'Something is wrong, I give up!' type of error. + + - - ``ENXIO`` + + - Typically returned when a feature requiring interrupt support was + requested, but the line does not support interrupts. + +.. note:: + + #. This list is not exhaustive; ioctls may return other error codes. + Since errors may have side effects such as a driver reset, + applications should abort on unexpected errors, or otherwise + assume that the device is in a bad state. + + #. Request-specific error codes are listed in the individual + requests descriptions. diff --git a/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst new file mode 100644 index 00000000000000..05f07fdefe2f64 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_CHIPINFO_IOCTL: + +*********************** +GPIO_GET_CHIPINFO_IOCTL +*********************** + +Name +==== + +GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip. + +Synopsis +======== + +.. c:macro:: GPIO_GET_CHIPINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`chip_info` to be populated. + +Description +=========== + +Gets the publicly available information for a particular GPIO chip. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst new file mode 100644 index 00000000000000..09a9254f38cffd --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEEVENT_IOCTL: + +************************ +GPIO_GET_LINEEVENT_IOCTL +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEEVENT_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`event_request` specifying the line + to request and its configuration. + +Description +=========== + +Request a line with edge detection from the kernel. + +On success, the requesting process is granted exclusive access to the line +value and may receive events when edges are detected on the line, as +described in gpio-lineevent-data-read.rst. + +The state of a line is guaranteed to remain as requested until the returned +file descriptor is closed. Once the file descriptor is closed, the state of +the line becomes uncontrolled from the userspace perspective, and may revert +to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Requesting edge detection on a line that does not support interrupts is an +error (**ENXIO**). + +As with the :ref:`line handle`, the +bias configuration is best effort. + +Closing the ``chip_fd`` has no effect on existing line events. + +Configuration Rules +------------------- + +The following configuration rules apply: + +The line event is requested as an input, so no flags specific to output lines, +``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or +``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and +``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising +and falling edges. + +Requesting an invalid configuration is an error (**EINVAL**). + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the file +descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst new file mode 100644 index 00000000000000..9112a9d31174f7 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEHANDLE_IOCTL: + +************************* +GPIO_GET_LINEHANDLE_IOCTL +************************* + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-line-ioctl.rst. + +Name +==== + +GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`handle_request` specifying the lines to + request and their configuration. + +Description +=========== + +Request a line or lines from the kernel. + +While multiple lines may be requested, the same configuration applies to all +lines in the request. + +On success, the requesting process is granted exclusive access to the line +value and write access to the line configuration. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line handles. + +.. _gpio-get-linehandle-config-rules: + +Configuration Rules +------------------- + +The following configuration rules apply: + +The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and +``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the +only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the +line is requested "as-is" to allow reading of the line value without altering +the electrical configuration. + +The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the +``GPIOHANDLE_REQUEST_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and +it requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +Requesting an invalid configuration is an error (**EINVAL**). + + +.. _gpio-get-linehandle-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Direction reject +Drive emulate +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Drive is emulated by switching the line to an input when the line should not +be driven. + +In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst new file mode 100644 index 00000000000000..c895b8910b252a --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_IOCTL: + +*********************** +GPIO_GET_LINEINFO_IOCTL +*********************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst new file mode 100644 index 00000000000000..a82d0161daf871 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL: + +******************************* +GPIO_GET_LINEINFO_UNWATCH_IOCTL +******************************* + +Name +==== + +GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its +requested state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``offset`` + The offset of the line to no longer watch. + +Description +=========== + +Remove the line from the list of lines being watched on this ``chip_fd``. + +This is the reverse of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and +gpio-get-lineinfo-watch-ioctl.rst (v1). + +Unwatching a line that is not watched is an error (**EBUSY**). + +First added in 5.7. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst new file mode 100644 index 00000000000000..f5c92b69a4961b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_GET_LINEINFO_WATCH_IOCTL: + +***************************** +GPIO_GET_LINEINFO_WATCH_IOCTL +***************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-get-lineinfo-watch-ioctl.rst. + +Name +==== + +GPIO_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_WATCH_IOCTL, struct gpioline_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + + The line must be requested using gpio-get-linehandle-ioctl.rst or + gpio-get-lineevent-ioctl.rst to access its value, and the line event can + monitor a line for events using gpio-lineevent-data-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +First added in 5.7. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst new file mode 100644 index 00000000000000..25263b8f058885 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_GET_LINE_VALUES_IOCTL: + +******************************** +GPIOHANDLE_GET_LINE_VALUES_IOCTL +******************************** +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-get-values-ioctl.rst. + +Name +==== + +GPIOHANDLE_GET_LINE_VALUES_IOCTL - Get the values of all requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_GET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values` to be populated. + +Description +=========== + +Get the values of all requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +This ioctl can also be used to read the line value for line events, +substituting the ``event_fd`` for the ``handle_fd``. As there is only +one line requested in that case, only the one value is returned in ``values``. + +Return Value +============ + +On success 0 and ``values`` populated with the values read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst new file mode 100644 index 00000000000000..d002a84681acf9 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIOHANDLE_SET_CONFIG_IOCTL: + +*************************** +GPIOHANDLE_SET_CONFIG_IOCTL +*************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-config-ioctl.rst. + +Name +==== + +GPIOHANDLE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIOHANDLE_SET_CONFIG_IOCTL + +``int ioctl(int handle_fd, GPIOHANDLE_SET_CONFIG_IOCTL, struct gpiohandle_config *config)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``config`` + The new :c:type:`configuration` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The configuration applies to all requested lines. + +The same :ref:`gpio-get-linehandle-config-rules` and +:ref:`gpio-get-linehandle-config-support` that apply when requesting the +lines also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may be used more +generally to move lines seamlessly from one configuration state to another. + +To only change the value of output lines, use +gpio-handle-set-line-values-ioctl.rst. + +First added in 5.5. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst new file mode 100644 index 00000000000000..0aa05e623a6c80 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_HANDLE_SET_LINE_VALUES_IOCTL: + +********************************* +GPIO_HANDLE_SET_LINE_VALUES_IOCTL +********************************* +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-set-values-ioctl.rst. + +Name +==== + +GPIO_HANDLE_SET_LINE_VALUES_IOCTL - Set the values of all requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_HANDLE_SET_LINE_VALUES_IOCTL + +``int ioctl(int handle_fd, GPIO_HANDLE_SET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)`` + +Arguments +========= + +``handle_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-linehandle-ioctl.rst. + +``values`` + The :c:type:`line_values` to set. + +Description +=========== + +Set the values of all requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of input lines is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst new file mode 100644 index 00000000000000..68b8d4f9f604c4 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEEVENT_DATA_READ: + +************************ +GPIO_LINEEVENT_DATA_READ +************************ + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-line-event-read.rst. + +Name +==== + +GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. + +Synopsis +======== + +``int read(int event_fd, void *buf, size_t count)`` + +Arguments +========= + +``event_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-get-lineevent-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpioevent_data`. + +Description +=========== + +Read edge detection events for a line from a line event. + +Edge detection must be enabled for the input line using either +``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or +both. Edge events are then generated whenever edge interrupts are detected on +the input line. + +The kernel captures and timestamps edge events as close as possible to their +occurrence and stores them in a buffer from where they can be read by +userspace at its convenience using `read()`. + +The source of the clock for :c:type:`event.timestamp` is +``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was +``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data` +as to which clock source is used, it must be determined from either the kernel +version or sanity checks on the timestamp itself. + +Events read from the buffer are always in the same order that they were +detected by the kernel. + +The size of the kernel event buffer is fixed at 16 events. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +The `read()` will block if no event is available and the ``event_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``event_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpio_lineevent_data` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst new file mode 100644 index 00000000000000..c4f5e1787a9df5 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_LINEINFO_CHANGED_READ: + +************************** +GPIO_LINEINFO_CHANGED_READ +************************** + +.. warning:: + This ioctl is part of chardev_v1.rst and is obsoleted by + gpio-v2-lineinfo-changed-read.rst. + +Name +==== + +GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines +from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpioline_info_changed` event. + +Description +=========== + +Read line info change events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-lineevent-data-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +First added in 5.7. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of +a :c:type:`gpioline_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst new file mode 100644 index 00000000000000..56b975801b6af0 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst @@ -0,0 +1,152 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINE_IOCTL: + +********************** +GPIO_V2_GET_LINE_IOCTL +********************** + +Name +==== + +GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINE_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``request`` + The :c:type:`line_request` specifying the lines + to request and their configuration. + +Description +=========== + +On success, the requesting process is granted exclusive access to the line +value, write access to the line configuration, and may receive events when +edges are detected on the line, all of which are described in more detail in +:ref:`gpio-v2-line-request`. + +A number of lines may be requested in the one line request, and request +operations are performed on the requested lines by the kernel as atomically +as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the +requested lines at once. + +The state of a line, including the value of output lines, is guaranteed to +remain as requested until the returned file descriptor is closed. Once the +file descriptor is closed, the state of the line becomes uncontrolled from +the userspace perspective, and may revert to its default state. + +Requesting a line already in use is an error (**EBUSY**). + +Closing the ``chip_fd`` has no effect on existing line requests. + +.. _gpio-v2-get-line-config-rules: + +Configuration Rules +------------------- + +For any given requested line, the following configuration rules apply: + +The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and +``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then +the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` +and the line is requested "as-is" to allow reading of the line value +without altering the electrical configuration. + +The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the +``GPIO_V2_LINE_FLAG_OUTPUT`` to be set. +Only one drive flag may be set. +If none are set then the line is assumed push-pull. + +Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it +requires a direction flag to also be set. +If no bias flags are set then the bias configuration is not changed. + +The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require +``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising +and falling edges. Requesting edge detection from a line that does not support +it is an error (**ENXIO**). + +Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set. +If none are set then the event clock defaults to ``CLOCK_MONOTONIC``. +The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware +and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that +doesn't support it is an error (**EOPNOTSUP**). + +The :c:type:`debounce_period_us` attribute may only +be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce +applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and +the edges returned by gpio-v2-line-event-read.rst. If not +supported directly by hardware, debouncing is emulated in software by the +kernel. Requesting debounce on a line that supports neither debounce in +hardware nor interrupts, as required for software emulation, is an error +(**ENXIO**). + +Requesting an invalid configuration is an error (**EINVAL**). + +.. _gpio-v2-get-line-config-support: + +Configuration Support +--------------------- + +Where the requested configuration is not directly supported by the underlying +hardware and driver, the kernel applies one of these approaches: + + - reject the request + - emulate the feature in software + - treat the feature as best effort + +The approach applied depends on whether the feature can reasonably be emulated +in software, and the impact on the hardware and userspace if the feature is not +supported. +The approach applied for each feature is as follows: + +============== =========== +Feature Approach +============== =========== +Bias best effort +Debounce emulate +Direction reject +Drive emulate +Edge Detection reject +============== =========== + +Bias is treated as best effort to allow userspace to apply the same +configuration for platforms that support internal bias as those that require +external bias. +Worst case the line floats rather than being biased as expected. + +Debounce is emulated by applying a filter to hardware interrupts on the line. +An edge event is generated after an edge is detected and the line remains +stable for the debounce period. +The event timestamp corresponds to the end of the debounce period. + +Drive is emulated by switching the line to an input when the line should not +be actively driven. + +Edge detection requires interrupt support, and is rejected if that is not +supported. Emulation by polling can still be performed from userspace. + +In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst +is the requested configuration, not the resulting hardware configuration. +Userspace cannot determine if a feature is supported in hardware, is +emulated, or is best effort. + +Return Value +============ + +On success 0 and the :c:type:`request.fd` contains the +file descriptor for the request. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst new file mode 100644 index 00000000000000..bc4d8df887d40f --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_IOCTL: + +************************** +GPIO_V2_GET_LINEINFO_IOCTL +************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a line. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` to be populated, with the + ``offset`` field set to indicate the line to be collected. + +Description +=========== + +Get the publicly available information for a line. + +This information is available independent of whether the line is in use. + +.. note:: + The line info does not include the line value. + + The line must be requested using gpio-v2-get-line-ioctl.rst to access its + value. + +Return Value +============ + +On success 0 and ``info`` is populated with the chip info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst new file mode 100644 index 00000000000000..938ff85a93226f --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_GET_LINEINFO_WATCH_IOCTL: + +******************************** +GPIO_V2_GET_LINEINFO_WATCH_IOCTL +******************************** + +Name +==== + +GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its +request state and configuration information. + +Synopsis +======== + +.. c:macro:: GPIO_V2_GET_LINEINFO_WATCH_IOCTL + +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_WATCH_IOCTL, struct gpio_v2_line_info *info)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``info`` + The :c:type:`line_info` struct to be populated, with + the ``offset`` set to indicate the line to watch + +Description +=========== + +Enable watching a line for changes to its request state and configuration +information. Changes to line info include a line being requested, released +or reconfigured. + +.. note:: + Watching line info is not generally required, and would typically only be + used by a system monitoring component. + + The line info does NOT include the line value. + The line must be requested using gpio-v2-get-line-ioctl.rst to access + its value, and the line request can monitor a line for events using + gpio-v2-line-event-read.rst. + +By default all lines are unwatched when the GPIO chip is opened. + +Multiple lines may be watched simultaneously by adding a watch for each. + +Once a watch is set, any changes to line info will generate events which can be +read from the ``chip_fd`` as described in +gpio-v2-lineinfo-changed-read.rst. + +Adding a watch to a line that is already watched is an error (**EBUSY**). + +Watches are specific to the ``chip_fd`` and are independent of watches +on the same GPIO chip opened with a separate call to `open()`. + +Return Value +============ + +On success 0 and ``info`` is populated with the current line info. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst new file mode 100644 index 00000000000000..6513c23fb7cada --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst @@ -0,0 +1,83 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_EVENT_READ: + +*********************** +GPIO_V2_LINE_EVENT_READ +*********************** + +Name +==== + +GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request. + +Synopsis +======== + +``int read(int req_fd, void *buf, size_t count)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at + least the size of a :c:type:`gpio_v2_line_event`. + +Description +=========== + +Read edge detection events for lines from a request. + +Edge detection must be enabled for the input line using either +``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or +both. Edge events are then generated whenever edge interrupts are detected on +the input line. + +The kernel captures and timestamps edge events as close as possible to their +occurrence and stores them in a buffer from where they can be read by +userspace at its convenience using `read()`. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one request. + +The size of the kernel event buffer is fixed at the time of line request +creation, and can be influenced by the +:c:type:`request.event_buffer_size`. +The default size is 16 times the number of lines requested. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the oldest buffered event is +discarded. Overflow can be detected from userspace by monitoring the event +sequence numbers. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst +does not remove or modify the events already contained in the kernel event +buffer. + +The `read()` will block if no event is available and the ``req_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``req_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size of a +:c:type:`gpio_v2_line_event` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst new file mode 100644 index 00000000000000..e4e74a1926d823 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_GET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_GET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_GET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_GET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values` to get with the ``mask`` set + to indicate the subset of requested lines to get. + +Description +=========== + +Get the values of requested lines. + +The values of both input and output lines may be read. + +For output lines, the value returned is driver and configuration dependent and +may be either the output buffer (the last requested value set) or the input +buffer (the actual level of the line), and depending on the hardware and +configuration these may differ. + +Return Value +============ + +On success 0 and the corresponding :c:type:`values.bits` +contain the value read. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst new file mode 100644 index 00000000000000..9b942a8a53ca9a --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_CONFIG_IOCTL: + +***************************** +GPIO_V2_LINE_SET_CONFIG_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_CONFIG_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_CONFIG_IOCTL, struct gpio_v2_line_config *config)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``config`` + The new :c:type:`configuration` to apply to the + requested lines. + +Description +=========== + +Update the configuration of previously requested lines, without releasing the +line or introducing potential glitches. + +The new configuration must specify the configuration of all requested lines. + +The same :ref:`gpio-v2-get-line-config-rules` and +:ref:`gpio-v2-get-line-config-support` that apply when requesting the lines +also apply when updating the line configuration. + +The motivating use case for this command is changing direction of +bi-directional lines between input and output, but it may also be used to +dynamically control edge detection, or more generally move lines seamlessly +from one configuration state to another. + +To only change the value of output lines, use +gpio-v2-line-set-values-ioctl.rst. + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst new file mode 100644 index 00000000000000..6d2d1886950b6b --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINE_SET_VALUES_IOCTL: + +***************************** +GPIO_V2_LINE_SET_VALUES_IOCTL +***************************** + +Name +==== + +GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines. + +Synopsis +======== + +.. c:macro:: GPIO_V2_LINE_SET_VALUES_IOCTL + +``int ioctl(int req_fd, GPIO_V2_LINE_SET_VALUES_IOCTL, struct gpio_v2_line_values *values)`` + +Arguments +========= + +``req_fd`` + The file descriptor of the GPIO character device, as returned in the + :c:type:`request.fd` by gpio-v2-get-line-ioctl.rst. + +``values`` + The :c:type:`line_values` to set with the ``mask`` set + to indicate the subset of requested lines to set and ``bits`` set to + indicate the new value. + +Description +=========== + +Set the values of requested output lines. + +Only the values of output lines may be set. +Attempting to set the value of an input line is an error (**EPERM**). + +Return Value +============ + +On success 0. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst new file mode 100644 index 00000000000000..24ad325e725353 --- /dev/null +++ b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst @@ -0,0 +1,81 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. _GPIO_V2_LINEINFO_CHANGED_READ: + +***************************** +GPIO_V2_LINEINFO_CHANGED_READ +***************************** + +Name +==== + +GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched +lines from the chip. + +Synopsis +======== + +``int read(int chip_fd, void *buf, size_t count)`` + +Arguments +========= + +``chip_fd`` + The file descriptor of the GPIO character device returned by `open()`. + +``buf`` + The buffer to contain the :c:type:`events`. + +``count`` + The number of bytes available in ``buf``, which must be at least the size + of a :c:type:`gpio_v2_line_info_changed` event. + +Description +=========== + +Read line info changed events for watched lines from the chip. + +.. note:: + Monitoring line info changes is not generally required, and would typically + only be performed by a system monitoring component. + + These events relate to changes in a line's request state or configuration, + not its value. Use gpio-v2-line-event-read.rst to receive events when a + line changes value. + +A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate +info changed events. Subsequently, a request, release, or reconfiguration +of the line will generate an info changed event. + +The kernel timestamps events when they occur and stores them in a buffer +from where they can be read by userspace at its convenience using `read()`. + +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``. + +The buffer may overflow if bursts of events occur quicker than they are read +by userspace. If an overflow occurs then the most recent event is discarded. +Overflow cannot be detected from userspace. + +Events read from the buffer are always in the same order that they were +detected by the kernel, including when multiple lines are being monitored by +the one ``chip_fd``. + +To minimize the number of calls required to copy events from the kernel to +userspace, `read()` supports copying multiple events. The number of events +copied is the lower of the number available in the kernel buffer and the +number that will fit in the userspace buffer (``buf``). + +A `read()` will block if no event is available and the ``chip_fd`` has not +been set **O_NONBLOCK**. + +The presence of an event can be tested for by checking that the ``chip_fd`` is +readable using `poll()` or an equivalent. + +Return Value +============ + +On success the number of bytes read, which will be a multiple of the size +of a :c:type:`gpio_v2_line_info_changed` event. + +On error -1 and the ``errno`` variable is set appropriately. +Common error codes are described in error-codes.rst. diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst new file mode 100644 index 00000000000000..f258de4ef370f7 --- /dev/null +++ b/Documentation/userspace-api/gpio/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +GPIO +==== + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API + Obsolete Userspace APIs + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/userspace-api/gpio/obsolete.rst b/Documentation/userspace-api/gpio/obsolete.rst new file mode 100644 index 00000000000000..c42538b44ec8cc --- /dev/null +++ b/Documentation/userspace-api/gpio/obsolete.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================ +Obsolete GPIO Userspace APIs +============================ + +.. toctree:: + :maxdepth: 1 + + Character Device Userspace API (v1) + Sysfs Interface diff --git a/Documentation/admin-guide/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst similarity index 87% rename from Documentation/admin-guide/gpio/sysfs.rst rename to Documentation/userspace-api/gpio/sysfs.rst index 35171d15f78d46..116921048b18e9 100644 --- a/Documentation/admin-guide/gpio/sysfs.rst +++ b/Documentation/userspace-api/gpio/sysfs.rst @@ -2,18 +2,18 @@ GPIO Sysfs Interface for Userspace ================================== .. warning:: + This API is obsoleted by the chardev.rst and the ABI documentation has + been moved to Documentation/ABI/obsolete/sysfs-gpio. - THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO - Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS - ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL - NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED. + New developments should use the chardev.rst, and existing developments are + encouraged to migrate as soon as possible, as this API will be removed + in the future. -Refer to the examples in tools/gpio/* for an introduction to the new -character device ABI. Also see the userspace header in -include/uapi/linux/gpio.h + This interface will continue to be maintained for the migration period, + but new features will only be added to the new API. -The deprecated sysfs ABI ------------------------- +The obsolete sysfs ABI +---------------------- Platforms which use the "gpiolib" implementors framework may choose to configure a sysfs user interface to GPIOs. This is different from the debugfs interface, since it provides control over GPIO direction and @@ -33,9 +33,12 @@ userspace GPIO can be used to determine system configuration data that standard kernels won't know about. And for some tasks, simple userspace GPIO drivers could be all that the system really needs. -DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS. -PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst -TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY. +.. note:: + Do NOT abuse sysfs to control hardware that has proper kernel drivers. + Please read Documentation/driver-api/gpio/drivers-on-gpio.rst + to avoid reinventing kernel wheels in userspace. + + I MEAN IT. REALLY. Paths in Sysfs -------------- @@ -84,9 +87,9 @@ and have the following read/write attributes: allow userspace to reconfigure this GPIO's direction. "value" ... - reads as either 0 (low) or 1 (high). If the GPIO + reads as either 0 (inactive) or 1 (active). If the GPIO is configured as an output, this value may be written; - any nonzero value is treated as high. + any nonzero value is treated as active. If the pin can be configured as interrupt-generating interrupt and if it has been configured to generate interrupts (see the diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index 09f61bd2ac2ef5..afecfe3cc4a86b 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -9,31 +9,59 @@ While much of the kernel's user-space API is documented elsewhere also be found in the kernel tree itself. This manual is intended to be the place where this information is gathered. + +System calls +============ + +.. toctree:: + :maxdepth: 1 + + unshare + futex2 + ebpf/index + ioctl/index + +Security-related interfaces +=========================== + .. toctree:: - :caption: Table of contents - :maxdepth: 2 + :maxdepth: 1 no_new_privs seccomp_filter landlock - unshare + lsm spec_ctrl + tee + +Devices and I/O +=============== + +.. toctree:: + :maxdepth: 1 + accelerators/ocxl dma-buf-alloc-exchange - ebpf/index - ELF - ioctl/index + gpio/index iommu iommufd media/index + dcdbas + vduse + isapnp + +Everything else +=============== + +.. toctree:: + :maxdepth: 1 + + ELF netlink/index sysfs-platform_profile vduse futex2 - lsm - tee - isapnp - dcdbas + perf_ring_buffer .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst index 457e16f06e04de..c472423412bf27 100644 --- a/Documentation/userspace-api/ioctl/ioctl-number.rst +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -82,8 +82,9 @@ Code Seq# Include File Comments 0x10 00-0F drivers/char/s390/vmcp.h 0x10 10-1F arch/s390/include/uapi/sclp_ctl.h 0x10 20-2F arch/s390/include/uapi/asm/hypfs.h -0x12 all linux/fs.h +0x12 all linux/fs.h BLK* ioctls linux/blkpg.h +0x15 all linux/fs.h FS_IOC_* ioctls 0x1b all InfiniBand Subsystem 0x20 all drivers/cdrom/cm206.h @@ -309,6 +310,7 @@ Code Seq# Include File Comments 0x89 0B-DF linux/sockios.h 0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range 0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range +0x8A 00-1F linux/eventpoll.h 0x8B all linux/wireless.h 0x8C 00-3F WiNRADiO driver diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst index 2e38226770615d..a6e55912139b57 100644 --- a/Documentation/userspace-api/landlock.rst +++ b/Documentation/userspace-api/landlock.rst @@ -75,7 +75,8 @@ to be explicit about the denied-by-default access rights. LANDLOCK_ACCESS_FS_MAKE_BLOCK | LANDLOCK_ACCESS_FS_MAKE_SYM | LANDLOCK_ACCESS_FS_REFER | - LANDLOCK_ACCESS_FS_TRUNCATE, + LANDLOCK_ACCESS_FS_TRUNCATE | + LANDLOCK_ACCESS_FS_IOCTL, .handled_access_net = LANDLOCK_ACCESS_NET_BIND_TCP | LANDLOCK_ACCESS_NET_CONNECT_TCP, @@ -84,10 +85,10 @@ to be explicit about the denied-by-default access rights. Because we may not know on which kernel version an application will be executed, it is safer to follow a best-effort security approach. Indeed, we should try to protect users as much as possible whatever the kernel they are -using. To avoid binary enforcement (i.e. either all security features or -none), we can leverage a dedicated Landlock command to get the current version -of the Landlock ABI and adapt the handled accesses. Let's check if we should -remove access rights which are only supported in higher versions of the ABI. +using. + +To be compatible with older Linux versions, we detect the available Landlock ABI +version, and only use the available subset of access rights: .. code-block:: c @@ -113,6 +114,10 @@ remove access rights which are only supported in higher versions of the ABI. ruleset_attr.handled_access_net &= ~(LANDLOCK_ACCESS_NET_BIND_TCP | LANDLOCK_ACCESS_NET_CONNECT_TCP); + __attribute__((fallthrough)); + case 4: + /* Removes LANDLOCK_ACCESS_FS_IOCTL for ABI < 5 */ + ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_IOCTL; } This enables to create an inclusive ruleset that will contain our rules. @@ -224,6 +229,7 @@ access rights per directory enables to change the location of such directory without relying on the destination directory access rights (except those that are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` documentation). + Having self-sufficient hierarchies also helps to tighten the required access rights to the minimal set of data. This also helps avoid sinkhole directories, i.e. directories where data can be linked to but not linked from. However, @@ -317,18 +323,72 @@ It should also be noted that truncating files does not require the system call, this can also be done through :manpage:`open(2)` with the flags ``O_RDONLY | O_TRUNC``. -When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` -right is associated with the newly created file descriptor and will be used for -subsequent truncation attempts using :manpage:`ftruncate(2)`. The behavior is -similar to opening a file for reading or writing, where permissions are checked -during :manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and +The truncate right is associated with the opened file (see below). + +Rights associated with file descriptors +--------------------------------------- + +When opening a file, the availability of the ``LANDLOCK_ACCESS_FS_TRUNCATE`` and +``LANDLOCK_ACCESS_FS_IOCTL`` rights is associated with the newly created file +descriptor and will be used for subsequent truncation and ioctl attempts using +:manpage:`ftruncate(2)` and :manpage:`ioctl(2)`. The behavior is similar to +opening a file for reading or writing, where permissions are checked during +:manpage:`open(2)`, but not during the subsequent :manpage:`read(2)` and :manpage:`write(2)` calls. -As a consequence, it is possible to have multiple open file descriptors for the -same file, where one grants the right to truncate the file and the other does -not. It is also possible to pass such file descriptors between processes, -keeping their Landlock properties, even when these processes do not have an -enforced Landlock ruleset. +As a consequence, it is possible that a process has multiple open file +descriptors referring to the same file, but Landlock enforces different things +when operating with these file descriptors. This can happen when a Landlock +ruleset gets enforced and the process keeps file descriptors which were opened +both before and after the enforcement. It is also possible to pass such file +descriptors between processes, keeping their Landlock properties, even when some +of the involved processes do not have an enforced Landlock ruleset. + +Restricting IOCTL commands +-------------------------- + +When the ``LANDLOCK_ACCESS_FS_IOCTL`` right is handled, Landlock will restrict +the invocation of IOCTL commands. However, to *allow* these IOCTL commands +again, some of these IOCTL commands are then granted through other, preexisting +access rights. + +For example, consider a program which handles ``LANDLOCK_ACCESS_FS_IOCTL`` and +``LANDLOCK_ACCESS_FS_READ_FILE``. The program *allows* +``LANDLOCK_ACCESS_FS_READ_FILE`` on a file ``foo.log``. + +By virtue of granting this access on the ``foo.log`` file, it is now possible to +use common and harmless IOCTL commands which are useful when reading files, such +as ``FIONREAD``. + +When both ``LANDLOCK_ACCESS_FS_IOCTL`` and other access rights are +handled in the ruleset, these other access rights may start governing +the use of individual IOCTL commands instead of +``LANDLOCK_ACCESS_FS_IOCTL``. For instance, if both +``LANDLOCK_ACCESS_FS_IOCTL`` and ``LANDLOCK_ACCESS_FS_READ_FILE`` are +handled, allowing ``LANDLOCK_ACCESS_FS_READ_FILE`` will make it +possible to use ``FIONREAD`` and other IOCTL commands. + +The following table illustrates how IOCTL attempts for ``FIONREAD`` are +filtered, depending on how a Landlock ruleset handles and allows the +``LANDLOCK_ACCESS_FS_IOCTL`` and ``LANDLOCK_ACCESS_FS_READ_FILE`` rights: + ++-------------------------+--------------+--------------+--------------+ +| | ``FS_IOCTL`` | ``FS_IOCTL`` | ``FS_IOCTL`` | +| | not handled | handled and | handled and | +| | | allowed | not allowed | ++-------------------------+--------------+--------------+--------------+ +| ``FS_READ_FILE`` | allow | allow | deny | +| not handled | | | | ++-------------------------+ +--------------+--------------+ +| ``FS_READ_FILE`` | | allow | +| handled and allowed | | | ++-------------------------+ +-----------------------------+ +| ``FS_READ_FILE`` | | deny | +| handled and not allowed | | | ++-------------------------+--------------+-----------------------------+ + +The full list of IOCTL commands and the access rights which affect them is +documented below. Compatibility ============= @@ -457,6 +517,27 @@ Memory usage Kernel memory allocated to create rulesets is accounted and can be restricted by the Documentation/admin-guide/cgroup-v1/memory.rst. +IOCTL support +------------- + +The ``LANDLOCK_ACCESS_FS_IOCTL`` right restricts the use of :manpage:`ioctl(2)`, +but it only applies to newly opened files. This means specifically that +pre-existing file descriptors like stdin, stdout and stderr are unaffected. + +Users should be aware that TTY devices have traditionally permitted to control +other processes on the same TTY through the ``TIOCSTI`` and ``TIOCLINUX`` IOCTL +commands. It is therefore recommended to close inherited TTY file descriptors, +or to reopen them from ``/proc/self/fd/*`` without the +``LANDLOCK_ACCESS_FS_IOCTL`` right, if possible. The :manpage:`isatty(3)` +function checks whether a given file descriptor is a TTY. + +Landlock's IOCTL support is coarse-grained at the moment, but may become more +fine-grained in the future. Until then, users are advised to establish the +guarantees that they need through the file hierarchy, by only allowing the +``LANDLOCK_ACCESS_FS_IOCTL`` right on files where it is really harmless. In +cases where you can control the mounts, the ``nodev`` mount option can help to +rule out that device files can be accessed. + Previous limitations ==================== @@ -494,6 +575,16 @@ bind and connect actions to only a set of allowed ports thanks to the new ``LANDLOCK_ACCESS_NET_BIND_TCP`` and ``LANDLOCK_ACCESS_NET_CONNECT_TCP`` access rights. +IOCTL (ABI < 5) +--------------- + +IOCTL operations could not be denied before the fifth Landlock ABI, so +:manpage:`ioctl(2)` is always allowed when using a kernel that only supports an +earlier ABI. + +Starting with the Landlock ABI version 5, it is possible to restrict the use of +:manpage:`ioctl(2)` using the new ``LANDLOCK_ACCESS_FS_IOCTL`` access right. + .. _kernel_support: Kernel support diff --git a/Documentation/userspace-api/media/drivers/ccs.rst b/Documentation/userspace-api/media/drivers/ccs.rst index 161cb65f4d98a6..03015b33d5abbe 100644 --- a/Documentation/userspace-api/media/drivers/ccs.rst +++ b/Documentation/userspace-api/media/drivers/ccs.rst @@ -2,6 +2,8 @@ .. include:: +.. _media-ccs-uapi: + MIPI CCS camera sensor driver ============================= @@ -13,6 +15,8 @@ the binner and the scaler. As the capabilities of individual devices vary, the driver exposes interfaces based on the capabilities that exist in hardware. +Also see :ref:`the CCS driver kernel documentation `. + Pixel Array sub-device ---------------------- @@ -30,7 +34,7 @@ that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the sink pad (0). Additionally, if a device has no scaler or digital crop functionality, the -source pad (1) expses another digital crop selection rectangle that can only +source pad (1) exposes another digital crop selection rectangle that can only crop at the end of the lines and frames. Scaler diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst index b97d56ee543cf5..ffe8325749e5f4 100644 --- a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst @@ -23,3 +23,4 @@ DVB-S2, DVB-T2, ISDB, etc. :maxdepth: 1 frontend_legacy_dvbv3_api + legacy_dvb_decoder_api diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst new file mode 100644 index 00000000000000..b46fe2becd029f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_audio.rst @@ -0,0 +1,1642 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later OR GPL-2.0 + +.. c:namespace:: dtv.legacy.audio + +.. _dvb_audio: + +================ +DVB Audio Device +================ + +.. attention:: Do **not** use in new drivers! + See: :ref:`legacy_dvb_decoder_notes` + +The DVB audio device controls the MPEG2 audio decoder of the DVB +hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data +types and ioctl definitions can be accessed by including +``linux/dvb/audio.h`` in your application. + +Please note that most DVB cards don’t have their own MPEG decoder, which +results in the omission of the audio and video device. + +These ioctls were also used by V4L2 to control MPEG decoders implemented +in V4L2. The use of these ioctls for that purpose has been made obsolete +and proper V4L2 ioctls or controls have been created to replace that +functionality. Use :ref:`V4L2 ioctls